Commit Graph
97 Commits
Author SHA1 Message Date
Andrew Beveridge ☄️andClaude Opus 5.5 e9465c73d4 chore: gemini-3.8-flash everywhere + auto-correct on Opus 5.5 (cost) (#1054)
## Why
GCP credits expired 2026-09-19; Vertex Gemini 3.1 Pro spend had grown $9
→ $37 → $105/30d. `gemini-3.8-flash` is $0.75/$3.75 per 1M (vs $2/$12
for 3.1 Pro; rises to $1.50/$7.50 on 2027-01-01). Opus 5.5 is $4/$20 (vs
$5/$25 for 4.8).

## Changes
- All Gemini defaults → `gemini-3.8-flash`: credit eval, custom lyrics,
auto-correct (default + compare leg), match judge, parse titles, tenant
bulk analyze, agentic AI router, error-monitor LLM analysis (also
`us-central1` → `global`, required for Gemini 3.x), frontend
`translate.py`.
- Auto-correct Claude leg `claude-opus-4-8` → `claude-opus-5-5` (ci.yml
env), with `effort: "high"` pinned (5.5 defaults to medium). Pricing
table gains both new models.
- Docs updated; version 0.241.1.

## Evidence (12 recent prod jobs, pre-review lyrics scored against the
human-reviewed final)
| Model | Precision | Word-level recall | $/job |
|---|---|---|---|
| gemini-3.1-pro-preview | 91% | 74% | $0.067 |
| gemini-3.8-flash | 98% | 38–41% | $0.020 |
| gemini-3.8-flash @ high thinking | 97% | 60% (4/12 timed out, 504) |
$0.041 |
| claude-opus-4-8 | 94% | 33% | $0.080 |
| claude-opus-5-5 (effort high) | 93% | 58% | $0.048 |

Flash for the Gemini leg is a deliberate cost/recall trade-off (Andrew
chose it); Opus 5.5 more than compensates. Also verified:
`gemini-3.8-flash` works on Vertex `global` (rejects
`thinking_level=minimal`; nothing here uses it), match-judge latency
median 3.3s / max 6.2s (< 12s timeout), Japanese translation smoke test
preserves ICU placeholders. Translation cache is keyed on English text +
locale, so no re-translation churn.

Tests: auto_correct, credit eval, custom lyrics, parse_titles,
error_monitor, agentic router suites pass locally.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* AI-powered correction, translation, matching, title parsing, and
evaluation now use updated models, including Gemini 3.8 Flash and Claude
Opus 5.5.
* **Updates**
* AI service pricing reflects scheduled rate changes, including a Gemini
3.8 Flash rate change beginning January 1, 2027.
  * Application version updated to 0.241.1.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-26 14:53:04 -04:00
Andrew Beveridge ☄️andClaude Opus 5.5 b177c36641 feat(kjbox): free-text song resolve for singer search auto-correct (v0.241.0) (#1053)
## Summary
Andrew wants the kjbox singer song search to auto-correct like gen's job
creation does, e.g. "the strokes max picu" → The Strokes — Machu Picchu,
with Undo. gen's match-judge only takes a separate artist and title, and
its catalog stage only fixes formatting, not typos. So this adds:

- **`POST /api/kjbox/catalog/resolve`** (`X-Kjbox-Secret`) `{query}` →
match-judge verdict shape (`kind` cosmetic/content/ambiguous/none,
`confident`, `canonical_*`, `alternatives`) plus
`typed_artist`/`typed_title`.
- **`backend/services/match_judge/free_text.py`**: one small Gemini call
(the match judge's model and settings) that splits and corrects
together. Bad or incomplete model output, or any model failure, degrades
to `kind: "none"`, never a 5xx.
- **Cost and abuse controls:**
- Results are cached per case-folded query (in-process, 2000 entries);
transient failures are not cached.
- A partner-wide cap of 120 AI calls/min per instance (429
`rate_limited`); cache hits are free.
- kjbox only calls this after its own catalogue search came back empty.
- Docs: `docs/API.md` § kjbox Partner API.

## Testing
- `test_match_judge_free_text.py` (8)
- `TestCatalogResolve` (4)
- Full backend suite passes (emulator tests excluded)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added free-text song search resolution that identifies artist and
title, corrects typos, and can suggest alternatives when a match is
ambiguous.
* Repeated searches can use cached results. If resolution is
unavailable, the request returns without an error; uncached requests may
be rate-limited.
* **Documentation**
* Documented the song-resolution API, including its response behavior
and request limits.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-26 13:09:27 -04:00
Andrew Beveridge ☄️andClaude Opus 5.5 36e95c7fe9 feat(kjbox): on-demand review sign-in link + record who started the review (v0.240.0) (#1052)
## Summary
Backs Andrew's feedback on the kjbox singer make-it flow (kjbox
companion PR to follow):

- **`POST /api/kjbox/jobs/{job_id}/review-link`** (partner secret +
singer Bearer session): mints the same one-click `job_review:<id>`
sign-in link the kjbox review email carries, on demand. This powers
"**Tap here** to review it yourself" on the singer's My songs. It is
owner-only (404 otherwise, including unknown ids) and only while
`awaiting_review`/`in_review` (409 `not_in_review`). It also returns
`review_started_by`.
- **`state_data.review_started_by` / `review_started_at`** are recorded
on the first `AWAITING_REVIEW → IN_REVIEW` transition. The value is
`"admin"` when an admin other than the owner (the KJ) opened it, and
`"owner"` otherwise (review-token links count as owner). It is wired
into `GET /api/review/{id}/correction-data` (`require_review_auth` now
stashes the reviewer on `request.state`) and into the legacy
`start-review` / `corrections` routes. kjbox reads it through its admin
job poll to show "Andrew has already started reviewing".
- Docs: `docs/API.md` § kjbox Partner API.

## Testing
- New `TestReviewLink` (6 tests) in `test_kjbox_partner_api.py`
- New `test_review_started_by.py` (7 tests)
- New route-level `TestCorrectionDataRecordsReviewStarter` (2 tests)
- Full backend suite: 4671 passed (excluding emulator tests)

CodeRabbit CLI has no seat on this org, so this PR is opened without the
ignore line and the GitHub bot will review it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a partner API endpoint for job owners to request a localized
sign-in link for jobs awaiting or undergoing review.
* Review details now indicate whether the owner or an administrator
started the review.
* **Documentation**
* Updated the API documentation with the required partner secret header
for review-link requests.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-26 03:28:22 -04:00
Andrew Beveridge ☄️andClaude Opus 5.5 d570b1f139 feat(kjbox): partner API for singer email-code sign-in + show credits (v0.239.0) (#1051)
## Summary
Partner API so the kjbox singer UI (live karaoke nights) can turn
patrons into real karaoke-gen customers: the singer verifies their email
with a 6-digit code typed into the kjbox page, and kjbox then searches
audio / creates the job **as that user** (normal gen delivery emails).

All under `/api/kjbox`, gated by `X-Kjbox-Secret` (Secret Manager
`kjbox-partner-secret`, wired in ci.yml; 503 when unset):
- `POST /auth/send-code` — emails a 6-digit code (hashed at rest, 10-min
expiry, new code supersedes old). Exempt from the 2-signups-per-IP cap
(a venue shares one IP) — replaced by a partner-wide 100 new accounts /
24h cap + 5 codes / email / hour. New users tagged `signup_source=kjbox`
(+ venue).
- `POST /auth/verify-code` — 5 attempts then burned, single-use; shares
the post-login path with magic-link verify (refactored into
`complete_verified_login`: welcome credit w/ AI eval, locale, referral,
session, welcome email).
- `POST /credits/show-credit` (+ user Bearer) — +1 credit, no email
("free at Andrew's shows"), idempotent per key, 5 / user / 24h.
- Review-needed + 24h reminder emails for `X-Client-Id: kjbox*` jobs
carry a one-click sign-in link to the review page (singers never signed
in on gen's site).

Paired kjbox PR: nomadkaraoke/kjbox (singer make-it flow, v0.116.0).
Plan: kjbox `docs/archive/2026-09-24-singer-make-it-auto-flow-plan.md`.

## Testing
- New: `backend/tests/test_kjbox_partner_api.py`,
`backend/tests/emulator/test_kjbox_partner_service.py` (+ additions to
existing tests for the verify refactor, review-email links, X-Client-Id
on create-from-search)
- Backend unit suite: 4644 passed; emulator suite passed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added partner sign-in with one-time email codes and show-credit
claiming, with limits on code requests and credit grants to prevent
repeated or duplicate claims.
* Added localized sign-in emails and single-use review links for
eligible reminders.
  * Sign-in supports welcome-credit evaluation and referral attribution.
* **Improvements**
* Review reminders can use custom links, and new accounts can record
signup source and venue.
  * Credential-like request headers are redacted from stored metadata.
* **Documentation**
  * Added partner API usage and behavior details.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-26 00:03:10 -04:00
Andrew Beveridge ☄️andClaude Fable 5 a9c6de0617 feat: KaraokeHunt interceptor — one freebie per email + community-version short-circuit (v0.236.0) (#1039)
## Summary

Follow-ups from Andrew's live test of the v0.235.0 interceptor (#1037):

1. **Community short-circuit** — his "abba - Waterloo" test generated a
real job despite a community karaoke version existing. Now
`check_community_versions` gates the whole routing: existing version →
no job, no board; the email's main button is the YouTube link (outcome
`community_existing`), and new users keep their conversion credit for a
custom song.
2. **One freebie EVER per email** (Andrew's spec): the goal is
converting installs into direct gen.nomadkaraoke.com users, not keeping
the dead app alive. First-time emails (all variants) now state the app
is retired and they must uninstall it and use Gen directly. A second
request from a converted address gets no job/board/credit — just the
"please uninstall" email (`repeat_request`), throttled to one per
address per 7 days. Accidental same-song double-taps stay silent
(`duplicate` dedup runs first).

## Implementation

- `karaokehunt_conversion.py`: `CONVERTED_OUTCOMES` +
`_freebie_already_used` (fails open) + `_uninstall_email_recently_sent`
(fails closed — anti-spam) + community short-circuit before routing;
queried fields re-verified in Python (defense in depth).
- `send_karaokehunt_conversion`: new `community` and `uninstall`
variants; rewritten intro (retired app, one-time freebie); bold
uninstall note on every first-time variant; new keys translated to all
32 locales.
- Docs: API.md + interceptor README routing updated.

## Testing

42 karaokehunt tests (6 new: community short-circuit ×2,
repeat/uninstall ×2, email variants ×2 more); full `make test` green.
Post-merge: live POSTs through create.karaokehunt.com for (a) a song
with a community version and (b) a repeat request from a converted
address.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* KaraokeHunt requests now receive a one-time conversion per email
address. Repeat requests receive an uninstall reminder instead of a new
conversion, with reminders limited to once every seven days.
* When a community version is available, the email links directly to it;
new users keep their free credit.
* Conversion emails explain credit status and include a Nomad Karaoke
sign-in link.

* **Documentation**
* Updated guidance on request outcomes and the one-time conversion
process.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-09-22 23:38:43 -04:00
Andrew Beveridge ☄️andClaude Fable 5 3d1ee6a621 feat: KaraokeHunt retired-app request interceptor — auto-convert to Gen users (v0.235.0) (#1037)
## Summary

The retired KaraokeHunt mobile app still has installs submitting ~5-10
song requests/month. Each request POSTs to the dead
`create.karaokehunt.com`, fires a client-side Pushbullet push to Andrew,
and shows the user a hardcoded *"you should receive an email in 5-10
minutes with a link to your new karaoke video"* — a promise broken for
years. This PR makes it true and converts those users into Gen users
(Andrew's spec, BACKLOG Frog #2 extension).

## How

- **Cloudflare Worker**
(`infrastructure/cloudflare/karaokehunt-interceptor/`, deployed via
`deploy.sh` — the karaokehunt.com zone is not IaC-managed): answers the
app instantly, `waitUntil`-forwards the payload to the new backend
intake with a shared secret.
- **`POST /api/karaokehunt/request`**: unauthenticated intake, gated by
`X-KH-Forwarder-Secret` (Secret Manager `karaokehunt-forwarder-secret`,
already created; wired in ci.yml `--set-secrets`), 10/min/IP rate limit,
lenient payload parsing, Firestore `karaokehunt_requests` audit trail.
- **Conversion** (`backend/workers/karaokehunt_conversion.py`, mirrors
`community_daily_pick`):
- new email → account + 1 credit (`karaokehunt_app_conversion`) → job
created **as them** (consumes it); first sign-in still grants the
welcome credit (deliberate — next song covered)
- existing user with credits → job on their credit (email offers to
restore it on reply)
- no credits, or over `KARAOKEHUNT_DAILY_JOB_CAP` (default 3/day, bounds
unattended spend) → free community requests board (dedup → upvote)
- conservative `pick_auto_selection` (not `select_best`): unconfident
matches park in `AWAITING_AUDIO_SELECTION` and the email asks them to
pick — garbage app inputs must never auto-publish to YouTube
- 14-day per-email+song dedup; failures retryable via admin `POST
/api/karaokehunt/internal/reprocess/{doc_id}`
- **Email** `send_karaokehunt_conversion`: 3 variants (job started /
pick the recording / on the board), 7-day one-click sign-in link,
KaraokeNerds community-version bonus link when one exists. EN + all 32
locales via translate.py.

## Safety

Deploys **dark**: endpoint 503s until the secret env lands, and receives
no traffic until the Worker + DNS flip (done post-merge via
`deploy.sh`). Kill switch = delete the Worker route; backend-side =
remove the secret mapping or `KARAOKEHUNT_DAILY_JOB_CAP=0`.

## Testing

- 36 new tests (`test_karaokehunt_intake.py`,
`test_karaokehunt_conversion.py`): secret/rate-limit/JSON gates, all
conversion routings, credit-grant guards, park-on-unconfident-search,
email variants + HTML escaping, reprocess auth.
- Full `make test` green (backend + frontend).
- Post-deploy: live end-to-end POST through `create.karaokehunt.com`
mimicking the app payload, verifying account/job/email/Firestore.

Plan doc: `docs/archive/2026-09-22-karaokehunt-app-interceptor-plan.md`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **New Features**
- Requests submitted through the retired KaraokeHunt app are now
received and converted into Nomad Karaoke jobs, accounts, or
community-board requests.
- Users receive localized email updates with job status, credit usage,
audio-selection prompts, and tracking links.
  - Requests can be retried by administrators when processing fails.
- Duplicate protection, request limits, and daily processing caps help
prevent repeated or excessive submissions.
- **Documentation**
- Added API and deployment documentation for the request-forwarding
workflow.
- **Chores**
  - Released version 0.235.0.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-09-22 21:26:18 -04:00
Andrew Beveridge ☄️andClaude Fable 5 d85b6e271c feat: precomputed vocals peaks — Waveforms strips paint sub-second (#1031)
## Summary

Final piece of the review-page speed work (#1024 → #1028 → #1029): the
Waveforms-mode strips no longer require downloading + WebAudio-decoding
the entire vocals stem (~7.5MB, ~4–6s) — the backend now serves a
**precomputed 400-peaks/s envelope as ~150KB of uint8/base64 JSON**,
cached in GCS and pre-warmed at prep time, so strips paint sub-second.

## How

- **`WaveformGenerator.generate_peaks()`** — numpy max-abs envelope,
bucket-for-bucket identical to the frontend's `computePeaks` (same
drift-free fractional-stride bucketing; exact match vs a naive reference
in tests).
- **`AudioAnalysisService.get_vocals_peaks()`** — GCS cache at
`review-audio/vocals_peaks_400.json`, validated against the stem path;
miss decodes the small transcoded OGG; upload best-effort.
- **`GET /api/review/{job_id}/vocals-peaks`** — off the event loop under
the shared waveform semaphore; `202 Retry-After: 15` while separation
runs (mirrors `/audio/vocals`); `Cache-Control: private, max-age=600`;
`peaks_per_second` clamped 50–1000.
- **`screens_worker`** pre-computes the envelope next to the existing
OGG + waveform pre-warm, so it's a pure cache read by the time a job
reaches review.
- **Frontend** — `VocalsAudioDataLoader` prefers the peaks endpoint (one
quick retry on transient errors) and **falls back to the original full
download+decode** on any terminal peaks failure, so a peaks-side problem
can never cost a user their waveforms. Local mode (no peaks URL) uses
the old path unchanged. Vocal stem selection factored into
`backend/utils/stems.py` (shared by routes + worker).

## Testing

- Package: 4 tests incl. exact naive-reference parity (**106 passed**)
- Backend: 4 service + 4 endpoint tests (**4518 passed**)
- Frontend: `fetchVocalsPeaks` units + 5 loader-behavior tests (prefers
peaks / falls back / one-retry-then-fallback / 202 polling / audio-only
mode) (**1307 passed**)
- `review-fast-load.spec.ts` prod E2E extended with a cached
vocals-peaks latency/shape check
- Post-deploy: will verify the endpoint on a real in-review job and
confirm payload size + latency

## Notes

- Existing in-review jobs have no cache yet — their first Waveforms open
computes + caches lazily (bounded); every open after that is sub-second.
New jobs are pre-warmed.
- 8-bit amplitude quantization is visually lossless at strip heights
(14px).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-09-20 13:08:19 -04:00
Andrew Beveridge ☄️andClaude Fable 5 30cf41e7d6 feat: concurrent-reliability phases 2-5 — Cloud Run shape, degradation telemetry, banner tuning, load-test guard (#1028)
## Summary

Phases 2–5 of the concurrent-load reliability initiative (Phase 1 =
#1024, verified live: the 10-tab meltdown went from 9/30 failed requests
to 30/30 OK). Verbatim spec:
`docs/archive/2026-09-17-concurrent-review-reliability-verbatim-record.md`;
plan:
`docs/archive/2026-09-18-concurrent-review-reliability-investigation-and-plan.md`.

## P2 — Cloud Run shape
- **`--concurrency 80 → 16`** for karaoke-backend: the service is one
uvicorn process per 2-vCPU instance, and review loads are heavy; at 80 a
burst never triggers scale-out and all lands on the single min-instance.
16 makes bursts fan out while staying well above normal per-instance
load. (Deploy flags live in ci.yml — the service is not Pulumi-managed.)
- **Local preview ffmpeg fallback bounded**
(`LOCAL_PREVIEW_MAX_CONCURRENCY=1`, 900s queue timeout, fast
RuntimeError after that): the GCE-outage fallback runs ffmpeg ON the API
instance; unbounded, a few concurrent Preview clicks during an encoder
outage pegged both vCPUs, stalled the health probe, and showed everyone
the orange banner (Andrew's banner-during-preview screenshot).

## P3 — degradation telemetry (the explicit ask)
- New **`POST /api/client-events`** (unauthenticated so review-token
users report too; 30/min/IP rate limit; bot-filtered; detail capped;
URLs query-stripped). Each event → Firestore `client_events` collection
**and** a structured `client_event type=…` log line, so "how often are
users seeing this?" is reviewable via Firestore aggregation or Cloud
Logging correlation.
- Frontend reporter `lib/degradation-events.ts` (60s per-type throttle,
localhost no-op, never throws), wired into:
- `BackendStatusBanner` → `banner_reconnecting` / `banner_unavailable`
with stall age, in-flight count, probe state
- review lyrics-load failure → `lyrics_load_failed` with message/status
- `VocalsAudioDataLoader` → `waveform_slow` (>20s to first strips) and
`waveform_failed` (gave up) with poll/retry counts

## P4 — banner tuning
- Escalating to the full "We're having trouble reaching our servers"
card now requires **two consecutive failed health probes**
(`UNAVAILABLE_PROBE_FAILURES=2`). One failed 4s probe against a
briefly-pegged instance shows only the calm "Reconnecting…" pill.
Single-failure behavior for the pill is unchanged, as is instant
clearing on recovery.

## P5 — regression guard
- **`scripts/load-test-review.py`** checked in: replays the 10-tab
incident (Firestore-ADC review tokens, curl request trios, pass/fail
thresholds, exit code). Documented in `docs/TESTING.md`. Validated
against prod post-Phase-1: 9/9 requests OK, tabs < 3s.

## Testing
- Backend: 6 new tests for client-events
(persist/validate/rate-limit/bot/fail-soft/detail-cap) + local-preview
bound test — full suite **4517 passed**.
- Frontend: new degradation-events suite, two-probe escalation +
debug-snapshot tests; one existing api-fetch test updated to the new
escalation contract — full suite **1298 passed**.
- Live validation of the load-test tool against prod (small 3-tab run):
PASS.

## Notes for review
- Cloud Run concurrency change means bursts now spin up extra instances
(billable during requests only; max-instances unchanged at 20).
- Firestore `client_events` has no TTL policy yet (needs a
gcloud/console action our read-only ADC can't do); volume is tiny
(throttled per client) — can add later if it ever matters.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Added automatic reporting for degraded experiences, including
reconnecting or unavailable backend status, failed lyrics loads, and
slow or failed waveform loads.
- Added concurrent review-page load testing to help verify performance
under multiple open tabs.

- **Improvements**
- Backend status now remains in “reconnecting” until multiple health
checks fail, reducing premature unavailable messages.
- Local preview processing is limited during heavy demand to improve
stability.

- **Documentation**
- Added API documentation for client telemetry and guidance for running
concurrent-load regression tests.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-09-19 12:48:21 -04:00
Andrew Beveridge ☄️andClaude Fable 5 b336f36f4e perf: survive concurrent review-page loads (10-tab meltdown fix, Phase 1) (#1024)
## Summary

Andrew can reliably take the backend down by opening ~10 lyrics-review
tabs at once: 1–2 load, the rest show "We're having trouble reaching our
servers" / "The server is temporarily unavailable". This PR is Phase 1
of the systematic fix (investigation + full phased plan in
`docs/archive/2026-09-18-concurrent-review-reliability-investigation-and-plan.md`;
Andrew's verbatim spec in
`docs/archive/2026-09-17-concurrent-review-reliability-verbatim-record.md`).

**Reproduced before the fix (prod, 2026-09-18 03:35Z):** 10 simulated
tabs → 8/30 requests HTTP 500, survivors took 44–72s (vs 0.8–1.3s solo),
Cloud Run logged 9× "request aborted — no available instance". Root
cause: `/waveform-data` decodes a whole stem (pydub→ffmpeg + Python RMS
loop) **synchronously on the single uvicorn event loop, uncached**,
while every other review endpoint also does blocking Firestore/GCS on
that loop — one wedged instance takes all traffic (concurrency=80 → no
scale-out at 10 tabs).

## Changes

**Backend**
- `/waveform-data`: persistent GCS cache
(`jobs/{id}/review-audio/waveform_review_{n}.json`, validated against
source path + num_points), computed via `asyncio.to_thread` under a
bounded semaphore (`REVIEW_WAVEFORM_MAX_CONCURRENCY`, default 4). Cache
miss decodes the ~3MB transcoded OGG instead of the ~35MB raw FLAC.
Pre-computed in `screens_worker` (next to the existing OGG pre-warm) so
review opens are pure cache reads.
- Blocking Firestore/GCS calls (`get_job`, `file_exists`,
`download_json`, `transition_to_state`) moved off the event loop via
`asyncio.to_thread` in the review hot-path endpoints (correction-data,
waveform-data, audio proxies, instrumental-urls/-analysis).
- `/audio/vocals`: now served from the bounded LRU byte cache
(previously a fresh multi-MB GCS download per request), honors HTTP
Range (206), and ranged review-audio responses carry `Cache-Control:
private, max-age=600`.

**Frontend**
- `VocalsAudioDataLoader`: transient failures (5xx/429/network) retry
with backoff `[5s, 15s, 30s, 60s]` instead of silently giving up — the
"Waveforms mode shows no waveforms until manual reload" symptom. 404
stays terminal via new typed `AudioFetchError`; 202 polling unchanged.

## Testing

- 12 new backend tests (waveform cache
hit/miss/stale-source/num_points/OGG-preference/upload-failure; vocals
LRU + Range 206 + Cache-Control; waveform-data endpoint routing) — full
backend suite **4500 passed**.
- 3 new frontend tests (transient retry → load, retry exhaustion, 404
terminal) — full Jest suite **1289 passed** across 105 suites.
- Post-deploy: will re-run the 10-tab burst repro against prod and
record before/after numbers in the plan doc.

## Follow-ups (later phases, tracked in the plan doc + BACKLOG)

Cloud Run shape (lower concurrency so bursts scale out),
`/api/client-events` degradation telemetry (Andrew's explicit ask),
banner threshold tuning, `instrumental-analysis` still signs 4 URLs
(13.7s baseline), load-test regression guard.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Review waveforms load faster with cached waveform data and improved
concurrent-load handling.
* Audio playback supports partial-range requests and short-term caching
for smoother streaming.
  * Transient audio failures are automatically retried up to four times.

* **Bug Fixes**
  * Reduced review-page failures and delays during simultaneous loads.
* Waveform generation falls back to available audio when backing vocals
are unavailable.

* **Documentation**
* Added API documentation for waveform data and updated audio streaming
behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-09-18 00:25:41 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 bb743b49e4 Review fast full load: remove IAM signBlob from the review hot path (v0.229.0) (#1018)
## Why

Root-cause fix for the **2026-09-17 signing-hang incident**. `GET
/api/review/{id}/correction-data` signed 2-3 GCS URLs per load via the
IAM **signBlob** API — a network round-trip that made review loads slow
and, when it stalled (~120s), exhausted the request thread pool and took
gen down (`Service Unavailable`, "Loading lyrics data…" hang).

`v0.228.1` bounded/timed signing and made audio + waveform
**best-effort** (the degraded fail-soft path). Andrew's ask was to fix
the root cause so the review page **always loads fast with all features
— audio + waveform — present on first paint**, not the degraded path.

## What (Option B — same-origin byte proxy)

Removes IAM signBlob from the review hot path **entirely** —
`correction-data` now performs **zero** signing calls.

**Backend** (`backend/api/routes/review.py`)
- New `GET /{job_id}/instrumental-audio/{option_id}`: streams the
transcoded OGG bytes with HTTP **Range (206)** support (so `<audio>` can
seek), authenticated by `require_review_auth` (token in the query string
for raw-media-src use, exactly like `/audio/vocals`). The stem GCS path
is resolved **server-side** from the option id — clients can't request
arbitrary blobs. Bounded **LRU byte cache** (prod-safe, unlike the
unbounded dev cache).
- `_build_instrumental_options`: returns **relative same-origin proxy
paths** as `audio_url`, no signing. Local-dev byte proxy path unchanged.
- Dropped the `backing_vocals_waveform_url` signing — it was a **dead
field** (0 consumers repo-wide; the waveform is drawn from the
Bearer-auth JSON `/waveform-data` endpoint).
- Also removed a now-unused `storage` param + refreshed stale
docstrings.

**Frontend** (`frontend/lib/api.ts`)
- Resolves each option's relative proxy path into an absolute,
`?token=`-authenticated `<audio>` src in the API layer
(`getCorrectionData` + `refreshInstrumentalUrls`) — **zero component
changes**, mirrors the proven `getVocalsAudioUrl` pattern. Also fixes
the CORS `Origin: null` issue for good, and the proxy URLs never expire
(the whole signed-URL expiry/refresh dance is now moot).

The `v0.228.1` signing timeout + bounded admission stays as
**defense-in-depth** for the remaining, non-review-hot-path signing
(e.g. preview-video).

## Tests
- Backend: new endpoint (bytes / Range 206 / auth / 404s), plus
**positive assertions that the hot path signs nothing**
(`generate_signed_url` / `get_review_audio_url_async` not called).
- Frontend: URL-resolution unit tests (relative→absolute+token; dev
absolute + null left untouched; refresh path).
- Prod E2E: `frontend/e2e/production/review-fast-load.spec.ts` —
env-gated contract (proxy `audio_url`s present, endpoint serves
`audio/ogg` + Range, loads fast).
- Full suites green: **backend 4469 passed**, **frontend jest 1286
passed**.

## Deploy note
Minor, self-healing skew: during the backend↔frontend deploy gap, only
the **instrumental preview player** for a job opened in that window may
not play (lyrics + everything else fine); a reload after both deploy
fixes it. Far less severe than the signBlob-stall outage this removes.

Plan + rationale:
`docs/archive/2026-09-17-review-fast-full-load-plan.md`. Runbook updated
in `docs/TROUBLESHOOTING.md`.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **New Features**
- Review pages now load instrumental audio through same-origin,
authenticated audio URLs.
- Audio playback supports streaming and range requests for faster, more
reliable access.
- Instrumental audio options automatically include usable
token-authenticated URLs.

- **Bug Fixes**
- Review data no longer depends on URL-signing round trips, preventing
loading delays caused by signing timeouts.
- Removed the unused backing-vocals waveform URL from review responses.

- **Documentation**
- Updated API and troubleshooting documentation for the new audio
streaming behavior.

- **Chores**
  - Version updated to 0.229.0.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-09-17 18:11:56 +00:00
Andrew Beveridge ☄️andClaude Opus 4.8 36b331f3d7 feat(requests-board): admin history view + fix community publish transition (#1008)
## Why

Andrew asked whether we can see past community-requests-board
submissions and whether our first real user got a video. Investigation
surfaced:

- **First real user was fully served.** `tas041964@gmail.com` requested
*Sam Cooke and the Soul Stirrers – Wonderful* (Sep 15); it was
auto-picked, generated, published to YouTube (NOMAD-1650), and he got
the completion email + emailed thanks. ✅
- **No admin view existed** to see this — you had to query Firestore
directly.
- **A real bug:** the community publish fan-out (`mark_published` +
voter emails) fired **only** on the `youtube_upload_queue` path. Jobs
published via the direct video-worker distribution path (like Sam
Cooke's) bypassed it, so the request stayed `in_progress`, never lit up
the board's public "Recently made" list, and other up-voters would
silently miss their "track is live" email.

## What

1. **Fix the publish transition** — extract the fan-out into
`backend/services/community_publish.py` and call it from **both**
publish paths (`youtube_queue_processor` + `video_worker`). Also fixes a
latent `len(int)` crash in the log line.
2. **Backfill / safety net** — `POST
/api/internal/community-requests/reconcile`: idempotent, publishes any
`in_progress` pick whose job is already live on YouTube. (Will be run in
prod post-deploy to fix the Sam Cooke request.)
3. **Admin history view** — `GET /api/admin/community-requests` + a
`/admin/community-requests` page: every request, all statuses, with
requester, votes, and job + YouTube links.

The public board's "Recently made" section already existed in the UI —
it was empty only because of bug #1; fixing the transition (+ reconcile
backfill) lights it up.

## Testing

- `backend/tests/test_community_voter_notify.py` — fan-out from the
shared module, both-path idempotency, voter dedupe/retry, YouTube-url
resolution, and the reconcile scan.
- `backend/tests/test_community_review_admin.py` — the new admin history
endpoint maps all statuses.
- All 31 requests-board + 158 worker tests pass. The one unrelated
failure in `test_audio_processor_local_gpu.py` is pre-existing
(confirmed with changes stashed).

## Notes

- Admin surface is English-only (no i18n changes); no `en.json` strings
added.
- Local CodeRabbit review couldn't run (CLI requires life360-org SSO; no
seat on this repo) — leaving to the GitHub bot.

Plan:
`docs/archive/2026-09-17-requests-board-history-and-publish-transition-plan.md`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Added an admin Community Requests history page covering all statuses,
votes, submitters, review details, linked jobs, and YouTube videos.
  - Added admin reconciliation for eligible requests with live videos.
- Added automatic voter email notifications after community-request
publication.

- **Bug Fixes**
- Improved publication handling across direct and queued video
workflows.
- Added recovery for incomplete voter notifications and missed
publication transitions.

- **Documentation**
- Documented the community-request history and reconciliation API
endpoints.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-09-17 01:07:40 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 bedbcdc3bd Requests board: skip songs with existing community karaoke versions (submit + pick time) (#979)
## Summary

Stops the requests board from spending a free track — or wasting voters'
time — on a song that **already has a good community karaoke version
online**, reusing the same KaraokeNerds check the normal job-submission
flow uses, at two points.

Follow-up to the requests-board Phase 2 automation (#977). Addresses
Andrew's two asks:

**A) Submission time (soft, non-blocking).** As a signed-in user types
an artist/title on the board, we debounce-check KaraokeNerds and surface
any existing community versions in a dismissible banner with YouTube
links. They can still request it — but many will just watch the existing
one. Reuses the existing `POST /api/catalog/community-check` endpoint +
`CommunityVersionBanner` component (added an optional board-appropriate
subtitle).

**B) Pick time (review).** A song may have had no version when requested
but gained one by the time it's upvoted to the top. So the daily picker
now KaraokeNerds-checks each candidate **in rank order**:
- A candidate that already has a community version is **flagged for
review** (`review_state=pending`) instead of auto-made, and the picker
**skips to the next clean request** — so a fresh, non-duplicate free
track still ships that day.
- Andrew is emailed a summary and resolves held picks at
**`/admin/community-reviews`**: **Make ours anyway** (creates the job
like a normal pick), **Reject** (declines and emails every up-voter a
link to the existing version), or **Keep on board** (leaves it votable,
snoozing re-review for 30 days).
- Held requests stay visible/votable on the board; they just aren't
auto-made. Flag/email is idempotent (no daily re-nag).

## Andrew's decisions (via AskUserQuestion)
Held pick → **skip to next clean request**. Review surface → **admin
queue page + email**. "Keep" → **return to board, snooze re-review (30
days)**.

## Changes
- **Model:** `SongRequest.review_state` (pending|snoozed),
`community_versions`, `community_checked_at`, `review_snoozed_until`.
- **Service:** `list_pick_candidates` (skips review-blocked),
`set_review_pending` (transactional/idempotent), `snooze_review`,
`clear_review`, `reject_request`, `list_pending_reviews`.
- **Picker:** candidate loop + community check; extracted
`_provision_and_start` shared by the picker and the admin "make" action.
- **Admin:** `GET/POST /api/admin/community-reviews`,
`/admin/community-reviews` page + sidebar item. New existing-version
email to up-voters (33 locales).
- **Frontend:** board submit form debounced check + banner.

## Testing
- Picker candidate loop (flag dup → make next clean; all-dup → empty +
flagged; resume skips re-check), admin actions (make/reject/keep, 404,
500), emulator coverage for the new service methods. 86 passing across
touched suites; frontend typechecks clean; 32/32 locale parity.

## Deploy
No `infrastructure/` changes — merge deploys it. The daily picker is
already enabled in prod, so the pick-time check goes live with the
backend deploy; the submission banner ships with the frontend.

## Review
CodeRabbit reviewed locally (one minor grammar nit, fixed).

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-09-03 16:59:16 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 05f024bdd4 Requests voting board Phase 2: daily free-community-track automation (#977)
## Summary

Phase 2 of the requests voting board (`requests.nomadkaraoke.com`) — the
daily automation that turns the top-voted request into a free,
auto-generated, published karaoke video. **Deploys dark** behind a
kill-switch (`COMMUNITY_DAILY_PICK_ENABLED`, default off); the daily
Scheduler only shadow-logs until it's flipped on.

Picks up
`docs/archive/2026-09-03-requests-voting-board-phase2-handoff.md`.
Design + Andrew's decisions:
`docs/archive/2026-09-03-requests-board-phase2-plan.md`.

## What's included
- **Daily picker** (`community_daily_pick.py`, Scheduler noon US
Eastern, DST-aware): claims the UTC day with a create-only lock
(`daily_community_pick/{YYYY-MM-DD}` → **one free track/day, total**),
picks the top open request with net votes ≥ 0 (source-agnostic; skips
community-rejected), grants the requester a free credit, and submits the
job **as that user** (owned by them, credit consumed) via the same
search → auto-select → download path the web flow uses. Fully idempotent
(resumable per-day lock phase + per-request guard flags).
Shadow/`?dry_run=true` mode.
- **24h ownership handoff** (`community_handoff.py`, hourly): reassigns
a stale review to the next up-voter (compare-and-set guarded), up to **5
voters**, then parks the track (`stalled`). Community jobs excluded from
the normal stale-review auto-cancel.
- **Voter publish fan-out**: YouTube upload-queue hook marks the request
`published` and emails every up-voter (except the owner) a new "track
you voted for is live" email (33 locales). Retry-safe (per-voter success
tracking).
- **Two internal endpoints** + two Cloud Scheduler jobs (Pulumi).

## Andrew's decisions (via AskUserQuestion)
- Trigger: **noon US Eastern**. Trending-agent fallback source:
**deferred** to a follow-up. Net-negative requests: **skipped**. Handoff
cap: **5 voters then park**.

## Deferred / follow-ups (not in this PR)
- **Trending-agent fallback source** (auto-submit a candidate when the
board is empty) — deliberately deferred; must generate candidates the
careful way (karaoke-decide `candidates` + KaraokeNerds).
- **YouTube description board link** — left untouched to avoid
clobbering Andrew's parallel descriptions work; add
`requests.nomadkaraoke.com` to `default_youtube_description` once that
lands.

## Testing
- Worker unit tests (kill-switch shadow, empty board, day-lock
idempotency, credit-grant/job-create guards, handoff cap/stale/CAS,
voter fan-out retry-safety) + emulator tests for the new service methods
against real Firestore transactions.
- All touched existing suites (youtube queue, stale-review,
requests-board routes/logic) pass. 79 passed locally.

## Review
CodeRabbit reviewed locally (2 cycles completed; 2 major + 1 minor
findings all addressed — retry-safe fan-out, CAS owner assignment,
up-voter ordering). 3rd cycle hit the free-OSS rate limit; it would only
re-verify the applied fixes.

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-09-03 01:34:31 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 d41854f787 feat(requests-board): public song-request voting board (Phase 1) (#975)
## What & why

Phase 1 of the **daily-free-community-track** initiative (BACKLOG:
*"Daily free community track via public voting board"*). A public,
Hacker-News-style voting board at **requests.nomadkaraoke.com** where
anyone signs in with an email magic link, submits a song request
(artist/title auto-corrected + deduped), and casts **one vote per
calendar day**. Publicly viewable so it can be linked from YouTube
descriptions to drive top-of-funnel awareness.

Ships the board first (this PR) so the linkable URL exists; the
automation (daily auto-picker, free-credit grant on pick, 24h ownership
handoff, voter publish-emails, and the trending-karaoke agent as a
fallback request source — one free track/day total) is **Phase 2**.
Design doc: `docs/archive/2026-09-02-requests-voting-board-plan.md`.

## Backend
- New `song_request` models + service (Firestore `song_requests` /
`song_request_votes`) with transactional vote arithmetic (create / move
/ flip / toggle-off), dedupe, and ranking. One-vote-per-day is enforced
structurally via the vote doc id (`{email}__{YYYY-MM-DD}`).
- New `/api/requests-board` router: `GET /requests` (public, annotates
the caller's vote), `POST /requests` (submit — auto-corrects via the
existing `match_judge`), `POST /requests/{id}/vote`, `GET /me`.
- Board sign-in (`purpose="requests_board"`): passwordless identity only
— **no welcome credit**, a **higher per-IP signup cap**
(`BOARD_MAX_SIGNUPS_PER_IP`, default 30) so a shared venue WiFi can
register many voters while the per-fingerprint cap stays strict, and
`redirect_path="/requests"`.
- New `POST /users/claim-welcome-credit` powers the "Make it yourself
now" conversion (grants the standard credit the normal way, idempotent).

## Frontend
- `app/[locale]/requests` board: submit form with "we tidied that to…"
feedback, ranked vote list with daily-vote UX, convert-to-gen CTA,
recently-made list with YouTube links.
- API client methods + types; verify page honors `redirect_path`; new
`requests` i18n namespace translated to **all 33 locales**.
- `requests` added to `nonTenantSubdomains`.

## Testing
- 20 backend unit tests (routes + pure logic + sign-in + board signup
limit) and 8 emulator tests exercising **real Firestore transactions**
(vote arithmetic, dedupe, idempotent resubmit, one-vote-per-day). Full
backend unit suite green (4247 passed); frontend typecheck clean.
- Reviewed locally with CodeRabbit CLI (3 cycles); all findings
addressed (auth headers, idempotent resubmit, signup-limit hardening,
blank-input validation, i18n particle, refresh race).

## Deploy note
The board is reachable at `gen.nomadkaraoke.com/en/requests` on deploy.
Wiring the vanity `requests.nomadkaraoke.com` is a **post-deploy
Cloudflare step** — see
`docs/runbooks/requests-subdomain-cloudflare.md`.

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-09-02 22:02:35 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 af36975db7 Admin create/manage tenants: album batch via tenant bulk flow + full theme customisation (#971)
## Why

Enables the "album for one client" use case: a batch of tracks with
audio provided up front, a client-supplied instrumental per track, and
one shared theme. That pipeline already exists as the **tenant bulk
flow** (folder pick → LLM pairs mixed↔instrumental → resumable uploads →
skip separation → locked theme on every job) — the only missing piece
was an easy way to **mint a tenant** (previously a hand-run
`scripts/setup-*-tenant.py`). This adds admin create **and** manage, so
a client's feedback can be iterated on (edit theme, re-render).

## What

**Backend** (`backend/services/tenant_admin_service.py` +
`backend/api/routes/tenant_admin.py`):
- `POST /api/admin/tenants` (multipart) — mint a tenant: derives a
**self-contained theme** from the default Nomad theme (copies its assets
so every `background_image` basename resolves), applies colour
overrides, overlays uploaded backgrounds, registers the theme, writes
`tenants/{id}/config.json` with B2B defaults (private, no
YouTube/GDrive, locked theme). Reserves the config **create-only before
any theme write**, with rollback on failure.
- `GET /api/admin/tenants` / `GET /api/admin/tenants/{id}` / `GET
/api/admin/tenants/_template` — list, full detail (config + theme
`style_params` + assets), and the default theme JSON as a template.
- `PUT /api/admin/tenants/{id}` (multipart) — **full theme
customisation**: merge config (one level, `id` immutable), replace the
entire `style_params.json`, upload/replace assets (images **or fonts**),
update logo.
- Full `style_params` override accepted on create too. Theme docs
validated to `intro/karaoke/end/cdg`. Guards against a tenant id
colliding with an existing theme.

**Frontend** (`/admin/tenants`):
- Tenants list + **Create** dialog (name→auto-slug, colours,
backgrounds, Dropbox/delivery, logo, + an "Advanced: full theme JSON"
editor seeded from the Nomad template).
- **Manage** dialog: editable config fields + a validated full **theme
JSON editor** + asset list & upload.
- New tenants are driveable immediately via **`?preview_tenant=<id>`** —
no DNS needed.
- Sidebar "Tenants" entry;
`adminApi.listTenants/createTenant/getTenant/updateTenant/getThemeTemplate`.

## Testing
- 36 backend tests (`test_tenant_admin_service.py`,
`test_tenant_admin_route.py`) + 4 frontend tests
(`admin-tenants-page.test.tsx`), incl. atomic-reservation /
conflict-no-clobber / rollback / theme-collision / full-theme-edit.
- Full `make test` green locally (backend + 1245 frontend); typecheck
clean.
- Reviewed locally with CodeRabbit (2 cycles, all findings addressed).

## Notes
- Admin is English-only → no i18n locale files touched.
- Follow-up (out of scope): saved **user** themes in the Custom Video
Style dialog (reuses this theme-derivation core); and an optional
"re-apply theme + re-render existing job" action.

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-31 18:31:16 -04:00
Andrew Beveridge ☄️andClaude Fable 5 5d6a6d4f1b fix(review): async preview video generation — survive encoder cold-starts (v0.207.0) (#954)
## Summary

Preview videos in the lyrics review UI got stuck on "Generating preview
video..." whenever the GCE encoding worker needed a cold start (job
`326e1aef`, 2026-08-29): the synchronous `POST /preview-video` held the
connection for 2m36s while three zones were stocked out and a fallback
VM booted — Cloudflare cuts browser connections at ~100s, so the UI
never saw the (successful!) response.

### Backend
- `POST /api/review/{job_id}/preview-video` now returns `{"status":
"generating", "preview_hash"}` immediately after the ASS subtitles are
uploaded; encoding runs in a background asyncio task (established
pattern in this file): GCE encode → local render fallback → GCS error
marker (`previews/{hash}.error.json`) if both fail
- Cache short-circuit: the preview hash is deterministic over the
correction data, so an identical retry returns the existing mp4
instantly as `{"status": "success"}`
- New `GET /api/review/{job_id}/preview-video/{hash}/status` poll
endpoint — GCS-backed (mp4/error-marker existence), so polls work across
Cloud Run instances
- Blocking prep work (GCS downloads, ASS generation) moved to
`asyncio.to_thread` so it no longer stalls the event loop

### Frontend
- `PreviewVideoSection` polls the status endpoint (3s interval, 5-min
cap), escalating to a "starting up an encoding server — this can take a
couple of minutes" message after 30s
- Fixed the Retry button: it previously reset state without
re-triggering generation (spun forever) and was hardcoded English; now
works via a retry nonce and is translated
- Removed the dead `worker_starting` branch (a status the backend never
returned)
- New i18n keys (`encoding`, `timedOut`, `retry`) + updated
`startingEncoder` translated for all 33 locales

## Testing

- 9 new backend tests: cache-hit, generating + background spawn +
stale-marker cleanup, status endpoint (ready/error/generating),
background task (GCE success / local fallback / error marker)
- 7 new Jest tests for `PreviewVideoSection`: cache hit,
poll-until-ready, transient poll failure, terminal error stops polling,
timeout, Retry re-runs, missing hash
- Full suites green: backend 4093 ✓, karaoke_gen unit 1779 ✓, frontend
Jest 1203 ✓, `tsc --noEmit` no new errors vs main, translation
`--keys-only` validation ✓

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-29 02:14:23 -04:00
Andrew Beveridge ☄️andClaude Fable 5 f01213f5cb Fully-auto review for confident jobs: review_mode framework + auto-approval scorer/executor + replay tool (v0.202.0) (#947)
## Summary

Ships the **fully-automated review framework**: jobs now default to
`review_mode="auto"` — when the auto-approval scorer is fully confident
on BOTH axes, the combined review screens are skipped entirely and the
job renders straight through. Everything else falls back to human review
exactly as before.

**The confident class (deliberately narrow to start, ~5% of jobs
expected):**
- **Lyrics**: synced reference present, ≥90-99% anchor coverage, and
every gap word covered by the pre-generated AI auto-correct suggestions
(which the executor applies server-side — a faithful port of the review
UI's on-load auto-apply, including conflict-group resolution) — OR zero
gaps outright.
- **Backing vocals**: non-subjective only — no audible backing content →
clean instrumental.
- **Never-auto gates**: vocalization sections (da-da-dun/woo-woo — P3),
phantom/absurd-duration lines (P8), too-few-words, no/unsynced
reference, errored backing analysis.

**Calibrated against a 20-job human-review corpus** (all recent admin
reviews replayed + annotated): safety 100% (every job that truly needed
a human stays in review), lyrics-auto 3/20, overall-auto 1/20.

## How it works

- `screens_worker` (pre-AWAITING_REVIEW) and `audio_worker` (post-stems,
for the audio-lags-lyrics ordering) both call
`maybe_auto_complete_review()`. Every job gets a verdict recorded in
`processing_metadata.auto_approval` (shadow data keeps accumulating for
calibration); enforcement additionally requires: flag on +
`review_mode="auto"` + not made-for-you + no existing/custom
instrumental + audio complete.
- Enforce path mirrors a human "Complete Review": apply cached AI
suggestions → sanity checks → `corrections_updated.json` →
`instrumental_selection="clean"` → clear progress keys →
`GENERATING_SCREENS→REVIEW_COMPLETE` (new legal edge; no review token or
"ready for review" notification is ever issued) → trigger render worker.
- **Fail-safe everywhere**: stale suggestions, duplicate-word artifacts
(P1 self-conflict signature), state changed mid-enforce (human opened
editor), any exception → normal human review. Auto-approval can never
fail a job.
- Kill switch: `AUTO_APPROVAL_ENFORCE_ENABLED=false` (scoring
continues). Per-job: `review_mode="always_review"` (admin PATCH,
validated).
- Excluded from enforcement (still shadow-scored): made-for-you orders
(human QC is part of that product), custom-instrumental jobs.

## Also in this PR (sessions 1-3 of the initiative)

- **Review replay tool** (admin-only, prod-inert): `?replay=1` reopens
the real lyrics/instrumental review UIs read-only for completed jobs —
queue nav, Post-AI/Final toggle, edit-log action panel, dev-only audio
byte-proxy (env-gated `REVIEW_AUDIO_PROXY`, path-anchored). This is what
produced the calibration corpus.
- `auto_approval` service package: scorer (anchor/gap/AI-coverage
signals + P3/P8 gate detectors), apply engine, executor, lyrics-diff,
offline capture script.

## Testing

- 100+ new unit tests across scorer/apply/executor/replay routes; full
backend suite 4000+ green locally (8 pre-existing emulator failures
reproduce identically on pristine `main` — local-env only, green in CI).
Frontend: 1196 Jest tests green.
- Scorer validated read-only against the 20 real prod jobs in the
private calibration corpus.

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-27 03:07:33 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 156d4369f9 Tenant bulk upload: folder pick + LLM pairing + review table + resumable uploads (v0.200.0) (#943)
## Summary

Adds a **Bulk** mode to tenant portals (frog #3, Vocal Star ask): drop a
folder of tracks, automation pairs Mixed vs Instrumental audio and
extracts Artist/Title from filenames, the operator reviews/fixes an
editable table, then submits all as jobs — with uploads that survive
slow/flaky connections.

### Bulk mode
- `POST /api/tenant/bulk/analyze` — authed, gated on new
`TenantFeatures.bulk_upload` (default on), cap 100 audio files. Regex
fast path for the `S####-1/-2 … Guide/BV/Instru` convention +
Vertex-Gemini pass for leftovers
(`backend/services/tenant_bulk/analyze.py`), regex-only fallback if the
model errors. Pure analysis — filenames only, no state written.
- Label parsing: STRONG labels (guide/instru/bv/backing vocals) override
the `-1`/`-2` slot (surfaces the real-world `S1102-2 … Guide` anomaly as
mixed-only unpaired); WEAK words (Off/Lead/Vocals/Karaoke) stay in the
title unless bracketed.
- `TenantBulkFlow.tsx`: folder/file pick → editable review table
(reassignable Mixed/Instrumental dropdowns, warnings strip,
low-confidence cautions) → bounded-concurrency submit reusing the tenant
single-submit sequence. Mixed-only rows blocked + flagged. Jobs stamped
`state_data.batch_id` + `created_from='tenant-bulk'`.

### Resilient uploads (opt-in `upload_mode: "resumable"`)
- Backend returns **GCS resumable session URIs** (created server-side
with the caller's Origin → GCS answers session CORS itself; **no bucket
CORS changes**). Signed PUT stays the default for all existing clients.
- `frontend/lib/resumable-upload.ts` (dependency-free): 256KiB-aligned
adaptive chunks, always-query-offset resume (no persisted byte ever
re-sent), stall detection instead of hard timeouts, backoff+jitter cut
short by online/visibility events, waiting-offline pause, EWMA
throughput + per-row ETA, non-advancing-308 loop guard.
- `frontend/lib/upload-recovery.ts`: IndexedDB persistence → after a
reload/crash a "Resume unfinished batch?" banner lets the operator
re-pick the folder and every upload resumes from its server-side offset
against the same jobs (never duplicates).

### Tests
- Backend: 26 new (real Bulk-Batch-1 fixture incl. S1102 anomaly,
label-in-title regressions, endpoint auth/feature/cap gates, upload_mode
contract)
- Frontend: 22 new (engine chunk choreography/offset recovery/permanent
errors/retry caps; component resumable routing, re-pick recovery,
retry-no-duplicate)
- Full suite green: backend (incl. emulator) + 1194 frontend
- Prod E2E extension of `tenant-happy-path` is a documented follow-up
(needs this deployed first)

### Docs
- `docs/API.md`: new endpoint + `upload_mode`/`batch_id` fields
- Design + decision record: workspace
`docs/archive/2026-08-25-tenant-bulk-upload-plan.md`

Local CodeRabbit review: 3 completed rounds on this branch, all 9
findings fixed.

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-25 17:10:07 -04:00
Andrew Beveridge ☄️andClaude Fable 5 e0e5959edc fix(review): surface relevance-filter rejection when pasting lyrics + Add Anyway force option (#937)
## Summary

Pasting reference lyrics in the review UI could silently do nothing: if
the relevance filter (30% anchor-match threshold) rejected the pasted
source during the correction rerun, the `add-lyrics` endpoint still
returned a generic success, so the paste tab cleared the box, closed the
modal, and no reference lyrics appeared — with zero feedback.

Observed in prod on job `0eebb248` ("Jonny Hill & Linda Feller –
Darling"): two "successful" add-lyrics calls, both sources rejected at
1.3% relevance (3/230 words), `reference_lyrics` left empty.

## Changes

- **Backend (`/api/review/{job_id}/add-lyrics`)**: when the source is
dropped by the relevance filter, return `{status: "rejected", rejection:
{relevance, matched_words, total_words}}` and skip persisting the no-op
rerun to GCS. Same change in the local `ReviewServer` (wheel/CLI review
mode), including `force` support it previously lacked.
- **Frontend**: `addLyrics` API client sends the `force` flag (as a
string — the endpoint body is `Dict[str, str]`, which also makes it
deploy-skew-safe). `PasteLyricsTab` keeps the pasted text on rejection,
shows a warning with the match %, and offers an **Add Anyway** button
that retries with `force=true`. Covers both the Add Lyrics modal and the
inline empty-state, which share the tab.
- **i18n**: new `pasteLyrics.rejectedWarning` / `addAnyway` strings
translated to all 33 locales.
- **Docs**: `docs/API.md` add-lyrics section documents the rejected
response.
- **Tests**: backend endpoint tests (success/rejected/force passthrough,
no-upload-on-reject), API client tests (force string, rejected
envelope), and `PasteLyricsTab` component tests (rejection UI, Add
Anyway flow, warning cleared on edit, legacy void result).

## Testing

- `make test`: full backend + frontend suite green (92 suites / 1158
frontend tests; backend 56 review-route tests incl. 3 new).
- Local CodeRabbit review completed; single finding was a pre-existing
translation nitpick (skipped).

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 17:06:41 -04:00
Andrew Beveridge ☄️andClaude Fable 5 b5461132d0 feat(admin): create users from admin UI + auto-create account on job user_email reassignment (#936)
## Summary

Lets admins provision user accounts before the user has ever logged in —
so we can grant free credits, submit jobs on their behalf, and
impersonate them — and fixes the gap where reassigning a job's
`user_email` to an unknown email left the job orphaned (no account, no
credits, impersonation 404s).

### Changes

- **`POST /api/users/admin/users`** — create a user account directly:
`email` (required), `display_name`, `initial_credits` (0-1000),
`credit_reason`. Returns 409 on duplicate. Initial credits set
`welcome_credits_granted` so the user doesn't also get the automatic
welcome credit on first login.
- **`PATCH /api/admin/jobs/{id}`** — `user_email` is now trimmed +
lowercased (account doc IDs are lowercased emails; mixed case would
silently orphan the job), blank/invalid values are rejected with 400,
and a `gen_users` account is auto-created when none exists. Response
message notes the creation.
- **Admin users page** — "Create User" button + dialog; on success the
list filters to the new user so Impersonate / Add Credits work
immediately.
- **Admin jobs page** — field-save toast surfaces the account-created
message; local state mirrors the backend's email normalization.

### Testing

- New `backend/tests/test_admin_create_user.py` (9 tests) +
`TestUpdateJobUserEmailAutoCreate` (5 tests) in
`test_admin_job_update.py`
- Full backend suite: 3917 passed. Frontend: 1151 Jest tests passed;
eslint/tsc clean on touched files
- CodeRabbit local review: 2 cycles, all findings addressed (PII
redaction, blank-email 400, masked audit log, normalized local state)

Version bump: 0.198.3 → 0.199.0

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 16:03:15 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 1e99f9e0d5 feat(admin): per-job/user locale badge + "emails sent to user" history (#930)
## Summary

Two admin-only features so support/intervention work can (a) know what
language/country a user is using the product in, and (b) see the exact
emails ever sent to a user, rendered as they appeared in the inbox with
full delivery metadata.

### A — Language / country visibility (admin-only)
- New `get_full_locale_from_request()` captures the real UI language
(any of 33, not the narrowed en/es/de email locale) on **every**
job-creation path (URL, upload, audio-search, bulk, made-for-you via
Stripe metadata). Stored as `Job.locale` (+ added to the dashboard
summary projection) and `User.ui_locale` (kept separate from
`User.locale`).
- `LocaleBadge` (flag + language) shown in the admin jobs table, admin
job detail (+ country via the existing `IpInfo` on the creation IP), the
user-detail header, and the customer `JobCard` **gated to admins only**
— regular users never see it.
- Country is derived from IP (existing `ip_geolocation_service`); no new
capture.

### B — "Emails sent to this user"
- Every send routes through one `EmailService._log_and_send` chokepoint
that persists each email to a new Firestore `email_log` collection
(rendered HTML + Postmark MessageID), best-effort so it can never break
or delay a send. Single-use auth/capability tokens (magic-link, review,
referral) are **redacted** before persistence.
- `PostmarkAdminService` merges the Postmark Messages API (last ~45
days: exact HTML + opens/clicks/bounce/delivery status, paginated) with
the Firestore log (permanent), de-duplicated by message id.
- Endpoints `GET /api/admin/users/{email}/emails` and `GET
/api/admin/emails/{id}`; the user-detail "Emails Sent" card opens a
modal rendering the email in a sandboxed `<iframe srcDoc>` with a
metadata side panel.
- New Firestore composite index (`email_log` recipient + created_at)
added to Pulumi.

## Testing
- **41 new backend tests** (locale capture incl. q=0, email logging +
token redaction, PostmarkAdminService incl. pagination + 45-day
fallback, job-locale persistence, admin endpoints) — all pass.
- **10 new frontend tests** (LocaleBadge, UserEmailsCard list +
sandboxed-iframe modal) — all pass.
- Regression sweep on related existing suites: green. Preview-email flow
smoke-tested through the new chokepoint.

## Notes
- `pulumi up` for the new `email_log` index should be applied before
merge (done locally).
- `Job.locale` populates for new jobs going forward; historical jobs
fall back to the submitting user's locale where shown.

Local CodeRabbit review completed and addressed (token redaction,
pagination, row a11y, locale-overwrite guard, q=0 handling).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-23 01:51:42 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 84b0683cba fix(audio-search): recover parked jobs — edit + re-search + own-audio fallback (#906)
## Problem

In Bulk Mode (and single jobs), the "Choose audio" dialog was a **hard
dead-end**. When a search returned nothing usable — 0 results, a
transient flacfetch failure, or an auto-picked source that's unusable —
the bulk worker parks the job in `AWAITING_AUDIO_SELECTION` with
**empty** cached results. The dialog then showed "No audio sources
found" with **no retry, no way to edit the title, and no manual
source**, so the user was trapped.

Real-world trigger (batch `4af58968a64a`): two Arctic Monkeys tracks
parked with 0 results (one a transient miss on a common track, one an
over-long title), and three more stuck downloading the **same dead RED
torrent** — all with no path forward.

## What this does

Adds a full recovery path to the shared `AudioSearchDialog` (used by
bulk **and** single jobs):

- **Edit + Search again** — always-available editable artist/title with
a re-search button. Edits apply to the job's search terms *and* display
metadata.
- **Provide your own audio** — paste a YouTube/yt-dlp URL, or upload a
file.
- **Graceful empty state** — a 400 (no cached results) renders as the
empty state with the refine bar, not a red error; real network/5xx
errors still surface.

### Backend (`audio_search.py`) — all guarded to
`AWAITING_AUDIO_SELECTION`, tenant-gated, no new job, no double-charge
(final duration billing reconciles post-download)
- `POST /{job_id}/research` — retry / edit-and-re-search. Empty results
are a normal `200`.
- `POST /{job_id}/provide-url` — YouTube URLs go through the **async**
audio-download worker; generic yt-dlp URLs download inline, bounded by a
timeout (never strands a job).
- `POST /{job_id}/attach-upload-url` + `/attach-upload-complete` —
signed-URL upload of the user's own file (extension allow-list +
traversal-safe; the complete step pins the exact uploaded object).
- Factored the triplicated result serialization into
`_build_result_response`.

## Testing
- 20 backend endpoint tests + 5 frontend dialog tests (all green);
broader audio/jobs sweeps pass.
- i18n: 15 new `audioSearch` keys across all 33 locales.

## Review
Local CodeRabbit review completed (2 cycles, all 6 findings addressed,
final pass 0 findings).

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-14 02:50:53 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 c94abbf7f4 docs: Cloudflare edge security (WAF + origin lock) — persistent-doc coverage (#889)
Documents the 2026-07-20 edge cutover (shipped in #886 + #888) in the
persistent docs.

## Changes
- **ARCHITECTURE.md**: Cloudflare edge added to the System Overview
request path + new **§ Edge Security (Cloudflare)** (WAF, rate limit,
origin lock, SSL "full" rationale).
- **LESSONS-LEARNED.md**: the SSL "dragon" resolution (managed cert
can't provision behind CF, but "full" mode makes it work + renewal-safe
→ never use "full (strict)") + Free-plan WAF/rate-limit constraints +
origin-lock-without-breaking-internal-callers.
- **README.md**: Recent Changes entry + Current State row.
- **API.md**: origin-lock note (direct-to-`*.run.app` → 403 without
`X-Edge-Auth`).

Docs-only; no version bump.

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-21 02:37:11 +00:00
Andrew Beveridge ☄️andClaude Opus 4.8 ad3c0bffc0 fix: harden 4 prod error paths (seek non-finite, auto-correct 429, download race + timeout) (#877)
## Summary
Investigated and fixed four production error patterns flagged by the
error monitor, each with tests.

## Changes
**Frontend — `TypeError: currentTime non-finite`** (`/en/app/jobs`
review UI)
- Guard lyrics-review/audio-editor seek sinks
(`AudioPlayer.seekAndPlay`/`handleSeek`, `AudioEditor.seekTo`) and the
`handlePlaySegment` dispatcher with `Number.isFinite`; harden
`TimelineEditor.handleTimelineClick` against a zero-width container.
Restores parity with instrumental-review, which already had these
guards.

**Backend — auto-correct Vertex `429 RESOURCE_EXHAUSTED` surfaced as
generic 502**
- Retry model calls with exponential backoff on transient
(rate-limit/overload) errors via `_is_transient_model_error`; surface a
distinct **retryable 429** instead of 502. Retry env knobs parsed
defensively (clamp + warn, never crash at import).

**Backend — `audio-download-job` `InvalidStateTransitionError:
downloading -> downloading`**
- Root cause: a manual `/retry` raced the Cloud Run auto-retry; the
losing run's post-download transition raised and the generic `except`
`fail_job`'d a job the winner had already advanced. Fix: idempotent
transition — re-read status first, treat an already-advanced job as
success, and use `raise_on_invalid=False` so a race never fails a live
job.

**Backend/infra — `audio-download-job` 600s task-timeout SIGKILL**
- Internal `wait_for_download` timeout equalled the Cloud Run task
timeout, so slow torrents were SIGKILLed before failing gracefully
(leaving the orphaned retry that fed the race above). New
`DOWNLOAD_WAIT_TIMEOUT_SECONDS=1080` kept strictly below the task
timeout, raised `600s → 1200s`. **Infra already applied to prod via
`pulumi up` (targeted); stack is clean.**

## Testing
- [x] Backend: 122 tests across touched suites pass (auto_correct incl.
10 retry/env, audio_download_worker incl. 3 race/timeout, review API,
proactive)
- [x] Frontend: full jest suite 1073/1073 pass (incl. new AudioPlayer
non-finite guard test); `tsc` clean for changed files
- [x] Infra: `pulumi preview` clean (273 unchanged) after applying
timeout + reconciling pre-existing divebar drift

## Review
- [x] Local CodeRabbit review completed (1 major finding — retry env
validation — fixed + tested)
- [x] Version bumped 0.190.5 → 0.191.0

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-15 17:40:04 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 2ff5e4b49f feat(bulk): collapse editions to tracklist variants + clickable community versions (#852)
## Summary
Improves Bulk Mode's "By album" UX in two ways (live-MusicBrainz, no
mirror dependency):

**1. Edition selection → tracklist variants (A+C).** The release
dropdown was ~17 rows of the same album pressed in different countries.
Since the selection only feeds a list of track *names*, we now collapse
a release-group's editions into a few distinct **tracklist variants**
(Option 1: grouped by track count — zero extra MB calls, dodges the
egress rate-limiter) and show a single confident default — *"Using
Original · 1976 · 10 tracks"* — with a **Change** disclosure (hidden
entirely when there's one variant). **Track numbers** are now rendered.
Representative pressing is locale-biased (`next-intl` locale → country
preference), wiring the hook the future mirror upgrade will lean on.

**2. Community versions → vertical, clickable.** The wide inline
`Community version: A, B, C` is replaced by a vertical list, each row a
**clickable YouTube link** so the user can preview a version and decide
whether to remake it. We simply stopped discarding the `youtube_url` the
scraper already captured. Shared by album and text modes.

## Changes
- **Backend** — `musicbrainz_service.build_variants()` +
`country_prefs_for_locale()`; `karaokenerds_service` batch returns
`versions:[{brand,url}]` (back-compat `brands` kept); `bulk.py`
models/routes gain `variants`, `selected_variant_mbid`, per-track
`versions`, and a `locale` param.
- **Frontend** — new `CommunityVersions` component (replaces
`AvailabilityBadge`); `BulkAlbumMode` C-pattern picker + track numbers;
types updated.
- **i18n** — 6 new `bulk` keys translated to all 32 locales.
- **Docs** — `API.md` bulk endpoints updated.

## Testing
- Backend: new unit tests for variant grouping, locale prefs, versions
dedup, and route plumbing; full bulk/MB/KN/catalog suites green (62
passing across touched + regression files).
- Frontend: `community-versions.test.tsx` (link href/target/rel,
fallback, hidden states); `tsc` clean on all touched files.
- Post-deploy: API-level prod verification of
`/api/bulk/album/tracklist` (variants + versions present).

## Notes
- The larger mirror-backed upgrade (exact tracklist-signature grouping +
popularity ranking) is captured in
`docs/archive/2026-06-18-musicbrainz-mirror-and-album-ux-handoff.md`;
this PR is the cheap live-MB version.
- Design:
`docs/archive/2026-06-22-bulk-edition-collapse-and-community-versions-design.md`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-22 18:44:02 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 feca70674b feat: Bulk Mode — submit up to 100 karaoke jobs at once (album or text) (#845)
## Bulk Mode — submit up to 100 karaoke jobs at once

Adds a **Bulk Mode** tab to the job-submission flow so users can make
karaoke versions of a whole album (or a typed list) in one go.

### Two ways in
- **By album** — MusicBrainz artist → album → tracklist.
Live/remix/bonus tracks and songs that already have a community version
on KaraokeNerds start **unticked** (re-tick anything). Auto-picks the
canonical edition, with an edition switcher.
- **By text** — up to 100 artist/title rows, each with a
community-version availability badge.

### Auto + review-queue model
Batch settings (auto-pick lossless / public-private / skip audio edit /
skip customization) drive auto-completion. The server runs each audio
search and **auto-selects only a confident lossless ("tier 1") match**;
everything else is parked in the existing `AWAITING_AUDIO_SELECTION`
state and surfaced as a review queue (reusing the existing
`AudioSearchDialog`). A popular full-FLAC album with all toggles on =
zero further prompts; the tab can be closed (searches run as a Cloud Run
Job).

### Credits
Gated upfront: requires `credits >= number_of_songs` (1/song minimum)
before any job is created; admins bypass. Duration deltas for long
tracks are charged per-song during processing as today.

### Backend
- `POST /api/bulk/submit`, `GET /api/bulk/{batch_id}`, `GET
/api/bulk/album/{artists,albums,tracklist}`, `POST
/api/bulk/availability`
- `bulk_search_worker` Cloud Run Job (`infrastructure/`:
`bulk-search-job`) — search → tier-1 auto-select (with duration-delta
charge) or park; per-job crash isolation; idempotent on retry
(charge_pending guard prevents double-charge)
- New `musicbrainz_service` (release lookup + extras detection); reuses
existing `karaokenerds_service` scraper (batch helper) for availability
— **no karaoke-decide change** (it has the `is_community` flag matching
"community-created"; see design doc)
- `pick_auto_selection` ports the frontend tier-1 confidence rule to the
backend (parity test)

### Frontend
- `components/job/bulk/*` (album/text modes, batch settings, submit bar,
batch progress + review queue); api client + types; 33-locale i18n

### Testing
- 40 new backend tests (foundations, MusicBrainz, lookup routes, submit
credit gate, search worker auto/park + credit math, progress) + frontend
Jest for the default-selection and credit-gate helpers
- Safe production E2E smoke
(`frontend/e2e/production/bulk-mode.spec.ts`) — read-only lookups + gate
rejection, does not spawn real jobs
- Full backend suite green (3588 passed); frontend typechecks clean (no
new errors)

### Deploy notes
- **Requires `pulumi up`** to create the `bulk-search-job` Cloud Run Job
before submit works in prod.
- Design + plan: `docs/archive/2026-06-18-bulk-mode-design.md`,
`-plan.md`

Docs: `docs/API.md` § Bulk Mode, `docs/LESSONS-LEARNED.md`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-18 16:18:02 +00:00
Andrew Beveridge ☄️andClaude Opus 4.8 b6dcf6602d feat: match-judge improvements — parallel tidy + hard gate, two-way toggle, weak-tier AI verify, preview perf (#841)
## Summary

Four follow-ups to the artist/title **match judge** (shipped in
v0.184.1), per
`docs/archive/2026-06-16-match-judge-improvements-prompt.md`:

### 1. Race fix — parallel tidy + hard gate
The judge previously ran only *after* the audio search resolved, leaving
a window where a user could select audio with un-tidied metadata (or
have a late verdict clobber their pick).
- Split into a **`fast`** catalog-only pass (fired on mount, parallel
with the audio search) and a **`full`** pass (with the tier, may use
AI). New `stage` field + `needs_ai` marker on
`/api/catalog/match-judge`.
- **Hard-gate** all audio-selection buttons until the judge settles,
with a subtle "Checking song details…" indicator. A 12s safety timeout
guarantees release. Impossible to reach Step 3 with un-tidied metadata
in the normal flow.

### 2. Two-way tidy/correction toggle
The notice now switches **both directions** — canonical ⇄ what-you-typed
— instead of a one-way undo. The current value is always clear.

### 3. Title-screen preview performance
`TitleCardPreview` + `KaraokeBackgroundPreview` rendered a 3840×2160
(4K) canvas and loaded a 2.7 MB 4K PNG for a small thumbnail.
- Render at preview resolution (960×540, dpr-aware) via a scale
transform.
- Low-res background assets (~540 KB) for the preview; 4K stays for the
real render path.
- Preload backgrounds at Step 2; show a loading spinner.

### 4. Catalog-match trust — verify weak matches with AI
A confident catalog match could land on a junk/misspelled Spotify entry
(prod: `Queen / Bohemian Rapsody` → wrongly "already canonical"). Now,
when audio results are weak (tier 3), the AI judge verifies the catalog
match and can override. Extra cost (~$0.0003/call) only on weak-result
cases.

## Testing
- **Backend:** new unit tests for `fast`/`full` staging, `needs_ai`,
weak-tier AI override + keep-catalog-on-unconfident/failure/disabled;
route tests for `stage` forwarding. Full suite green (3510 passed).
- **Frontend:** Jest coverage for fast-on-mount, gate disable→enable,
12s timeout release, full-pass-only-when-needed, two-way toggle;
`TitleCardPreview` preview-resolution canvas + low-res bg + spinner.
Full unit suite green (1024 passed).
- `make test` green; `tsc` introduces zero net-new errors; ESLint clean.

## i18n
6 new keys (`matchUsingTyped`, `matchUseTidied`, `matchUseCorrection`,
`matchChecking`, `titleCardPreview.loading`,
`karaokeBackgroundPreview.loading`) translated to all 32 locales.

## Notes
Preserves all "constraints from history": no Step-1 autocomplete,
cosmetic never restarts the audio search, deferred job creation, public
brand rule, audio-before-customize ordering.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 02:15:43 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 ffa9558db5 feat: artist/title match-judge — auto-tidy formatting, replace 'database' panel (#836)
## Summary

Reworks the **artist/title matching, suggestions & auto-correction** on
Step 2 of the Create Karaoke Video flow. The confusing green **"Song
found in our database"** panel is gone; formatting is now tidied
intelligently and (mostly) invisibly.

Driven by a new backend **match judge**: a deterministic normalizer +
the karaoke-decide catalog run first, and a light Vertex Gemini model
(`gemini-3.5-flash`) is consulted **only** when those aren't confident.

### Behaviour (Step 2)
- **Cosmetic** fix (casing/punctuation/diacritics, same song) → applied
**silently**, with a quiet *"Tidied to X · keep what I typed"* line.
**Never** re-runs the audio search.
- **Confident content** fix (e.g. `Yesteray → Yesterday`) → applied with
a *"Corrected to X · Undo"* line, and re-runs the audio search **only
when the original results were weak** (tier 3).
- **Ambiguous** → ask-first *"Did you mean…?"* prompt before changing
anything.
- **None** → no change.

Resilient by design: the judge never blocks job creation — on
timeout/error it returns `none`. Kill switch:
`MATCH_JUDGE_ENABLED=false` (deterministic + catalog still run).

## Why
The catalog panel existed only to nudge official formatting (quality bar
for published tracks), but read like "we already have this karaoke
video." User feedback flagged it as confusing. This preserves the
formatting-hygiene benefit while removing the friction/confusion. Design
+ history review in
`docs/archive/2026-06-15-artist-title-matching-rework-plan.md`.

## Preserved (hard-won lessons honoured)
- No Step-1 autocomplete; suggestions stay on Step 2.
- Cosmetic correction never restarts the audio search (existing
`onArtistTitleCorrection` no-restart path reused).
- Deferred job-creation / search-session pattern untouched.
- `stringSimilarity`/`findFuzzyMatches` kept as pure utils (existing
tests green).
- No changes to step structure, visibility/customize ordering, or the
public-style brand rule.

## Changes
- **Backend**: `backend/services/match_judge/` (classifier → AI judge →
orchestration), `POST /api/catalog/match-judge`, config
(`MATCH_JUDGE_ENABLED`/`MATCH_JUDGE_MODEL`/`MATCH_JUDGE_TIMEOUT_MS`).
- **Frontend**: `api.matchJudge`, Step 2 rewired, green panel removed,
new `MatchNotice` component; 5 `jobFlow` i18n keys across all 33
locales.
- **Docs**: API.md endpoint section + design/plan doc. Version →
0.183.0.

## Testing
- Full suite green: backend (unit + integration + emulator, coverage
gate passed) + **1008 frontend tests** + e2e.
- New: 20 backend tests (classifier, AI mapping, orchestration,
endpoint) + updated `AudioSourceStep` tests (cosmetic tidy, ambiguous
ask, none, failure-silent) + preserved fuzzy-matching tests.
- CodeRabbit: 1 finding fixed (Literal types), 1 false positive.

## Follow-ups (separate PRs)
- Title-screen preview perf (4K canvas/bg → low-res + preload +
spinner).

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-15 18:02:23 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 39fb93653f fix(auto-correct): switch active model from Fable 5 to Opus 4.8 (#822)
## Summary

Claude **Fable 5** (`claude-fable-5`) is no longer available on the
Anthropic API. Verified live against `api.anthropic.com`:

```
404 not_found_error: "Claude Fable 5 is not available. Please use Opus 4.8.
Learn more: https://www.anthropic.com/news/fable-mythos-access"
```

`claude-opus-4-8` responds normally and is the API's own prescribed
replacement. Opus 4.8 was also ≈ Gemini 3.1 Pro in our 30-job offline
eval, so switching to it preserves the two-model compare quality.

## Changes

- **`.github/workflows/ci.yml`** (load-bearing):
`AUTO_CORRECT_MODEL=claude-opus-4-8` and
`AUTO_CORRECT_COMPARE_MODELS=claude-opus-4-8;gemini-3.1-pro-preview`.
Compare mode now runs **Opus 4.8 + Gemini 3.1 Pro** instead of Fable +
Gemini.
- **`scripts/measure_autocorrect_cost.py`**: default models + docstring
example → Opus, so the cost tool measures what prod runs.
- **`docs/API.md`**: example auto-correct response reflects Opus.
- **`pyproject.toml`**: `0.182.1` → `0.182.2`.

## Re-enable path

Fable is **disabled, not deleted** — its pricing entry in `pricing.py`
and all Fable unit tests are intentionally left intact. If access
returns, flip it back by reverting the two env-var values in `ci.yml`.

## Testing

- Auto-correct suite: 73 passed (`backend/tests/services/auto_correct/`
+ `test_proactive_auto_correct.py`).
- Live API probe confirmed Fable 404s and Opus 4.8 works.
- CodeRabbit (uncommitted): 0 findings.

@coderabbitai ignore

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-13 10:27:58 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 a7bb338703 feat(auto-correct): enable proactive pre-generation (runs on API service) (#818)
## Summary

Enables the proactive pre-generation that PR #816 intended but couldn't
deploy (the lyrics-job `--update-secrets` crashed on Cloud Run secret
aliases). Per the chosen approach, the work now runs **on the API
service** — which already has a working `ANTHROPIC_API_KEY` +
`AUTO_CORRECT_COMPARE_MODELS` — instead of the lyrics job, sidestepping
the secret-alias problem entirely.

## How it works

1. Lyrics worker finishes transcription → after `mark_lyrics_complete`,
fires `WorkerService.trigger_auto_correct(job_id)` — a direct, awaited
HTTP call (no Cloud Tasks / new queue). Best-effort: never blocks or
fails the job.
2. New internal endpoint `POST /api/internal/workers/auto-correct`
(admin auth) runs `process_proactive_auto_correct(job_id)` synchronously
on the service: loads `corrections.json`, runs the multi-model
`suggest()` with default settings (cache-aligned with the UI), caches
it. Gated by `AUTO_CORRECT_PROACTIVE_ENABLED`, 180s timeout, swallows
all errors.
3. `ci.yml`: `AUTO_CORRECT_PROACTIVE_ENABLED=true` added to the
**service** env (deploys cleanly — the broken lyrics-job secret path is
gone).

Result: when a reviewer opens the lyrics UI, the auto-run-on-load
request is an instant cache hit.

## Testing
- Backend: **3462 passing** (emulator excluded), incl. rewritten
`test_proactive_auto_correct.py` covering the service worker (flag
gating, no-references skip, happy path multi-model, error-swallow) and
the lyrics-worker trigger (fires / swallows errors).
- CodeRabbit: trace-context propagation + defensive endpoint guard
applied.

## Notes
- Failure modes unchanged & graceful: flaky AI / out of credits /
timeout → endpoint returns a status, job proceeds; UI falls back to
on-demand generation.
- Version bumped 0.180.0 → 0.181.0.

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-11 19:42:08 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 364e4ebd5f feat(auto-correct): proactive multi-model suggestions + cost logging + de-AI-ified review UI (#816)
## Summary

Makes AI lyrics auto-correction run **automatically on every job**
(multi-model), so suggestions are cached and ready the moment the
reviewer opens the lyrics UI — plus token/cost instrumentation and a UI
cleanup that removes all "AI"/"model" wording.

Measured cost first (`scripts/measure_autocorrect_cost.py`):
**~$0.13/track** multi-model on normal songs — cheap enough to run
proactively.

## Changes

**Cost instrumentation**
- Capture per-model `usage` from Anthropic + Gemini; log greppable
`auto-correct usage` / `auto-correct cost … total_est_cost_usd=…` lines
from `suggest()`.
- `backend/services/auto_correct/pricing.py` (Anthropic rates
authoritative; Gemini estimated) + `scripts/measure_autocorrect_cost.py`
offline harness.

**Proactive generation (every job)**
- `lyrics_worker._run_proactive_auto_correct()` runs the multi-model
path after `mark_lyrics_complete` (downstream already triggered →
non-blocking), gated by `AUTO_CORRECT_PROACTIVE_ENABLED`, bounded by a
180s timeout, and **swallows every error** — it never blocks or fails
the karaoke job (flaky AI / out of credits / timeout all degrade
gracefully).
- Cache-key aligned with the UI request, so the review page's on-load
call is an instant cache hit (no double spend).
- `ci.yml`: wires `AUTO_CORRECT_*` env + the `anthropic-api-key` secret
onto `lyrics-transcription-job` (same SA as the API service — no IAM
change).

**Review UI**
- Always multi-model (removed the model-selection toggle); button
renamed **"Auto-correct"**; stripped model/consensus/cached attribution
badges; reworded strings to drop "AI"/"model" (translated to all 32
locales).
- Auto-runs once on review load so suggestions are ready without a
click; the button stays for the paste-references-later flow.

## Testing
- Backend: **3460 passed** (`backend/tests/`, emulator excluded) — incl.
new `test_pricing.py` + `test_proactive_auto_correct.py` (gating,
graceful failure, cache alignment).
- Frontend: **1006 jest tests pass**; type-clean; 33-locale key parity
verified.

## Notes / follow-ups
- Proactive activates on the **next deploy** (the lyrics-job env/secret
apply via this PR's ci.yml on merge).
- Left "AI" wording in two *separate* features untouched (different
subsystems): `lyricsReview.agenticMetrics` and
`lyricsReview.modals.correctionAnnotation` — flagged for a separate
decision.
- The production E2E spec's click-to-open flow may want a tweak now that
suggestions auto-run on load.

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-11 18:22:51 -04:00
Andrew Beveridge ☄️andClaude Fable 5 0dd5d404e5 feat: cache AI auto-correct suggestions per job (free re-runs on unmodified lyrics) (#815)
@coderabbitai ignore

Per Andrew: clicking AI Suggest twice on the same unmodified lyrics
shouldn't spend AI tokens twice.

Suggestions are now cached per job in GCS
(`jobs/{job_id}/lyrics/auto_correct_cache/{hash}.json`), keyed on the
exact input — word ids + texts, reference lyrics texts, settings knobs,
and the resolved model list. A repeat run on byte-identical input
returns the previous suggestions instantly with `cached: true` (teal
"cached" badge in the panel) and incurs no LLM cost. Any edit to the
lyrics, references, or settings produces a new key and a fresh run; word
ids in the key guarantee cached suggestions always reference words that
still exist.

Cache reads/writes are strictly best-effort — any storage failure
degrades to a normal uncached run (tested). 7 new backend tests (hit
skips model call, miss writes cache, key stability/sensitivity, payload
round-trip, corrupt entry = miss, storage failure never breaks the
request).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 18:03:44 +00:00
Andrew Beveridge ☄️andClaude Fable 5 e4aad66a06 feat: Fable 5 default + multi-model compare for AI auto-correct (v0.178.0) (#811)
@coderabbitai ignore

## Summary

Follow-up to #809, per Andrew's direction: switch the auto-correct
default to the eval's best model, and add an opt-in **multi-model
compare mode** that queries several models in parallel, dedupes
identical suggestions with consensus counts, and lets the reviewer pick
between conflicting variants.

## Changes

**Fable 5 as production default**
- New Anthropic provider path in `AutoCorrectService` (structured
outputs + adaptive thinking — the exact configuration the 30-job eval
used). Eval rationale: strict precision 0.62 vs 0.56, strict recall 0.51
vs 0.46, 27s vs 35s median latency vs Gemini 3.1 Pro.
- `anthropic-api-key` secret: container added to Pulumi
(`infrastructure/modules/secrets.py`, **already applied** — preview was
exactly +1 create after pinning pulumi-gcp to 9.22.0 to avoid
provider-upgrade VM replaces), value added and verified against the live
API.
- Cloud Run deploy: `AUTO_CORRECT_MODEL=claude-fable-5`,
`AUTO_CORRECT_COMPARE_MODELS=claude-fable-5;gemini-3.1-pro-preview`,
`ANTHROPIC_API_KEY` secret mapping.
- No silent provider fallback: missing key → clear 502.
- `anthropic >=0.109` added as a direct dependency (lock updated).

**Multi-model compare mode**
- `compare_models` setting → all configured models queried in parallel;
identical suggestions deduped with `consensus`/`total_models` + `models`
attribution; overlapping disagreements share a `conflict_group`.
- UI: "Compare multiple AI models" toggle in the run modal; consensus
badges ("2/2 models") and variant badges in the panel; accepting one
variant of a conflict group auto-rejects its siblings; accept-all picks
the highest-consensus winner per group.
- Partial model failure (call error or malformed output) degrades to a
response warning; only all-fail returns 502.
- EditLog decisions now record models/consensus/conflict_group —
per-model accept-rate data accrues in prod.

**Cross-provider bug fixed**: google-genai mutates `response_schema`
dicts in place (injects `property_ordering`), which the Anthropic API
rejects — found via real-call smoke test of compare mode; schemas now
deep-copied per call, with a regression test.

## Testing

- 55 backend auto-correct tests (incl. 10 new multi-model
merge/conflict/degradation tests + schema-pollution regression) and
frontend conflict-util tests; full suite green (3,426 backend unit + 103
emulator + 1,004 frontend)
- Real-call smoke tests: single-model Fable (glory→chlorine, 0.98, 5.6s)
and compare mode (Fable + Gemini parallel, merged to one 2/2-consensus
suggestion, 5.8s)
- Secret value verified end-to-end against the Anthropic API
- CodeRabbit CLI: 12 findings — 5 fixed, 5 skipped with reasons, 2 in
files from another merged PR

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 06:52:14 +00:00
Andrew Beveridge ☄️andClaude Fable 5 6f8503a113 feat: opt-in AI auto-correct suggestions in lyrics review UI (v0.177.0) (#809)
@coderabbitai ignore

## Summary

Third take on lyrics auto-correction, redesigned around the failures
that led to disabling it in #321 (Jan 2026): **one whole-song LLM call**
instead of per-gap calls, **user-triggered from the review UI** instead
of blocking the pipeline, and a **pending-suggestion layer with
per-change accept/reject/undo** instead of silent application. Fully
opt-in — zero change to the default review journey.

## Changes

**Backend**
- `POST /api/review/{job_id}/auto-correct` — stateless; client posts its
current working segments + reference lyrics, gets back word-id-keyed
suggestions (`replace` / `delete` / `insert_after`) with reason,
category, confidence
- `backend/services/auto_correct/` — prompts (kept in sync with the
offline eval harness), settings knobs (adlib removal, insertions,
min-confidence), Vertex Gemini call with 120s timeout, strict
server-side validation of model output
- `AUTO_CORRECT_MODEL` env (default `gemini-3.1-pro-preview`); 422 when
no reference sources exist

**Frontend**
- "AI Suggest" button in the review header → settings modal →
suggestions panel: per-row accept/reject/undo, accept-all/reject-all,
click-to-scroll-and-flash, stale detection when targeted words were
edited since generation
- `useAutoCorrect` hook + pure `autoCorrectApply` utils (id-based
apply/revert, safe against concurrent edits)
- EditLog ops `ai_suggestion_run/accept/reject/undo` — real accept-rate
data accrues from day one
- i18n strings translated to all 33 locales

**Model choice** backed by an offline eval over 30 real production jobs
scored against actual human review edits (design doc:
`docs/archive/2026-06-10-lyrics-auto-correction-reeval-plan.md`): Fable
5 ≈ Gemini 3.1 Pro at the top; GPT-5.2 actively worsened lyrics (would
have repeated the 2025 failure). Gemini chosen for v1 (already on
Vertex, no new secret); switching models is one env var.

## Testing

- 42 backend unit/route tests (`backend/tests/services/auto_correct/`,
`backend/tests/api/test_review_auto_correct.py`)
- 15 frontend unit tests (`autoCorrectApply.test.ts`)
- Production E2E spec
(`frontend/e2e/production/auto-correct-suggestions.spec.ts`) — runs one
real suggestion cycle and dismisses without mutating review state
- Full `make test` green (unit + backend + emulator + frontend)
- CodeRabbit CLI review: 7 findings, 6 fixed, 1 skipped with reason

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 05:44:51 +00:00
Andrew Beveridge ☄️andClaude Opus 4.8 7cf42c8983 feat(pricing): duration-based credit pricing + long-duration input handling (#799)
@coderabbitai ignore

## Summary

Implements **duration-based credit pricing** for karaoke jobs, replacing
the flat 1-credit/job model. Credits now scale with input audio length
(`ceil(min/10)`, hard-block >60 min), with cost confirmed before heavy
processing and reconciled against the actual measured audio. Closes out
the planned fix from the 2026-06-04 long-duration mashup incident.

- Design:
`docs/archive/2026-06-04-long-duration-input-handling-design.md`
- Plan: `docs/archive/2026-06-04-long-duration-input-handling-plan.md`

## Pricing model

`credits = max(1, ceil(minutes / 10))` — 1 credit ≤10 min, 2 ≤20 min … 6
≤60 min. Inputs over 60 min are blocked. Single source of truth in
`backend/services/pricing.py`, mirrored in `frontend/lib/pricing.ts`.

## How it works

- **`state_data.credits_charged`** is the authoritative running total.
`create_job` charges the base (URL = full N via `acknowledged_credits`;
search/upload = 1); top-ups deduct only the **delta**
(`count_as_job_creation=False`).
- **Reconciliation engine** (`duration_reconciliation.py`) runs at the
single convergence point before separation+transcription in all three
processing paths (download / post-edit / `start_job_processing`),
exactly once each. It measures the audio actually sent to AudioShake
(post-edit if trimmed):
  - actual < estimate → auto-refund the difference
- actual > estimate → pause at new **`AWAITING_DURATION_CONFIRM`**
state, user re-confirms (inline Buy Credits)
  - actual > 60 min → refund everything + cancel
- **`POST /api/jobs/{id}/confirm-duration`** (+ `POST
/api/jobs/estimate`) reuse the review-stage pause/resume.
- **Notifications**: in-browser + push, 15-min idle email, 24h reminder,
**48h auto-cancel + full refund** — via the existing idle-reminder /
stale-job machinery.
- **Admin / made-for-you jobs bypass charging entirely**
(`payment_bypassed` → reconcile short-circuits).

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/api/jobs/estimate` | URL duration probe →
`{duration_seconds, credits, blocked, source}` |
| `POST` | `/api/jobs/{id}/confirm-duration` | confirm cost / resume
(402 insufficient, 409 mismatch) |
| `POST` | `/api/jobs` | URL create gains optional `duration_seconds`,
`acknowledged_credits` |
| `POST` | `/api/audio-search/{id}/select` | gains optional
`acknowledged_credits` |

## Frontend

`DurationCostConfirm` modal (Radix Dialog) surfaced via a "Confirm Cost"
action on `awaiting_duration_confirm` jobs (`useDurationConfirm` hook),
per-result cost chips on audio search, `pricing` i18n namespace in all
33 locales.

## Testing

- Backend: **3358 passing** (incl. boundary tables, money-math
conservation, reconcile up/down/over-limit, confirm 402/409, idempotency
guards, stale-expiry refund, an end-to-end integration test). Frontend:
**960 passing**. i18n completeness clean.
- Reviewed locally: per-task spec + quality review, a holistic
cross-cutting review, `/test-review`, and two CodeRabbit fix cycles.

## Notable bugs caught & fixed during review

- **Multi-credit under-refund**: `_refund_credit_for_job` refunded a
flat 1 — now refunds `credits_charged` (user-cancel of a long job).
- **Admin-bypass trap**: admin jobs would pause at the confirm gate and
be charged real credits — now short-circuited.
- Over-limit double-refund (suppress `cancel_job`'s built-in 1-credit
refund); over-limit email used the wrong "48h" message;
double-confirm/double-select idempotency guards.
- Hit the summary-projection gotcha (added fields to both projection
lists + regression test).

## Known residuals / follow-ups (non-blocking)

- **URL pre-flight cost-confirm is inert** until flacfetch's
`/check-youtube` returns a `duration` key — currently falls back to a
1-credit hold + post-download reconcile (functionally correct). Separate
flacfetch change.
- Duration-confirm email **bodies** are English (URLs are
locale-prefixed; backend i18n covers en/es/de) — `# TODO(i18n)` left.
- Concurrent confirm/select **double-charge TOCTOU** is an accepted
low-probability residual (atomic claim would need a Firestore
transaction); the status-transition guard handles the realistic
double-click case.

## Deploy note

Reuses the existing Cloud Tasks idle-reminder queue and the hourly
stale-review Cloud Scheduler (status-list / action-type expansions only)
— no new infra expected, but worth confirming `pulumi up` is a no-op on
deploy.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-07 18:39:06 -04:00
Andrew Beveridge ☄️andClaude Opus 4.8 fe8430d990 fix(admin): allow regen-screens from in_review state + surface errors via toast (#793)
## Summary
- Fixes a 400 when regenerating title/end screens for a job the user has
opened in the review UI (`in_review` state).
- Fixes the root cause behind "click Regenerate Screens → modal just
closes, no error": `<Toaster />` was never mounted, so **all** `toast()`
calls (success and error) silently no-op'd.

## Changes
- **Backend:** add `in_review` to `REGENERATE_SCREENS_ALLOWED_STATES` in
`backend/api/routes/admin.py`. The sibling `/restart` endpoint already
allows `in_review`; this restores parity. Updated `docs/API.md`.
- **Frontend:** mount the shadcn `<Toaster />` (same `@/hooks/use-toast`
store) in the root `app/layout.tsx` so admin toasts render app-wide.
- **Frontend:** give the regen-screens handlers specific, human-readable
failure titles/messages (admin dashboard + compact `AdminJobActions`
toolbar).
- Version bump `0.174.12` → `0.174.13`.

## Testing
- [x] Backend: `tests/unit/test_regenerate_screens.py` — allow-list
membership, `in_review` → 200, invalid state → 400, missing job → 404 (4
pass).
- [x] Frontend: `AdminJobActions.test.tsx` — error-toast path now
covered (5 pass).
- [x] CodeRabbit CLI review: 0 findings.
- [x] Typecheck: no new errors from these changes (pre-existing errors
unrelated).

## Review
- [x] CodeRabbit CLI review completed locally
- [x] Issues addressed

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-03 12:31:19 -04:00
Andrew Beveridge ☄️andClaude Opus 4.7 6d52503126 fix(auth): one-click magic-link resend on verify failure (#739)
## Summary

When a magic-link verify fails (expired or already used), the verify
page now shows a one-click button that emails a fresh sign-in link to
the address the original token was issued to. Complements the 24h TTL
bump from #734 and gives Yahoo recipients (and anyone with deferred
mail) a recovery path that doesn't require re-entering their email.

## Why

Customer `hojob2002@yahoo.com` is back today reporting "Sign-in failed"
despite #734 having extended TTL to 24h two days ago. Investigation
showed her job had auto-cancelled at the 48h review timeout while she
was burning through expired magic links during Yahoo's deferral window —
and the verify failure UX gave her nothing actionable beyond "Go to
App". With Postmark approval still pending, this is the cheapest
recovery improvement we can ship to help users in the same situation.

## Changes

- **Backend** — `POST /api/users/auth/resend-from-token`
- Looks up the original token in Firestore, mints a fresh magic link for
the same email, and sends it
- Carries forward `tenant_id`, `referral_code`, and `device_fingerprint`
from the original token
- 60-second per-token cooldown stamps `last_resend_at` on the doc;
repeat clicks (and email-scanner pre-fetches) within the window report
`sent` to the UI without re-emailing
- Returns `{status: "sent" | "no_token", masked_email, message}` —
`no_token` lets the UI degrade gracefully
- **Frontend** — verify page error UI
  - "Email me a new link" button (with sending spinner)
  - Success state shows masked destination email
  - Distinct fallback when backend reports `no_token`
  - Inline error message on network failure
- **Translations** — 33 frontend locales, 33 backend locales
(auto-translated, French verb form fixed manually)
- **Docs** — `docs/API.md` documents the new endpoint with concrete
request/response examples
- **Version** — 0.172.5 → 0.172.6

## Security note

The token in the URL is a 32-byte cryptographic secret — only the
original email recipient could possess it. Resending to the email
already recorded in the magic-link doc (rather than accepting an email
from the request body) avoids enumeration and adds no new attack
surface; the worst case if a token leaked is inbox spam to the verified
address, which is bounded by the 60s cooldown.

## Testing

- [x] 9 backend tests in `test_resend_magic_link.py` (token exists /
missing / empty / used / no-email / no-email-svc / tenant-context /
cooldown-suppresses / cooldown-expires)
- [x] 4 frontend Jest tests in `verify-page-resend.test.tsx` (button
visible on failure, happy path, no_token fallback, network error)
- [x] All 173 existing auth/anti-abuse tests still pass
- [x] Type-check clean for the modified frontend files

## Review

- [x] Local CodeRabbit review completed; relevant findings (cooldown,
French grammar, JSON example validity) addressed in fixup commit
- [x] Final CodeRabbit pass returns no findings on this branch's code

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-29 11:13:35 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 1c1c17f9ab fix: Stripe Connect redirect and referral payout management (#702)
## Summary

- **Fix broken Stripe Connect return URL** — was redirecting to
`/app?tab=referrals` (the dashboard, which ignores that param) instead
of `/app/referrals`. Users were ending up logged out at `/en/` after
completing Stripe onboarding.
- **Add locale redirect fallback** for `/app/referrals` route so Stripe
can redirect without locale prefix
- **Add Connect account status and management** — new backend endpoints
for account status, Express dashboard login, and re-onboarding. Frontend
shows payouts enabled/pending status, "Manage Payouts" and "Update Bank
Account" buttons.
- **Improve Connect button UX** — loading spinner + note that user will
be redirected to Stripe, error feedback for all actions

## Test plan

- [x] Backend: 48 referral tests + 7 Stripe tests pass
- [x] Frontend: 721 tests pass
- [x] CodeRabbit review: 3 issues found and fixed
- [ ] Manual: verify Connect flow with test account after deploy
- [ ] Manual: verify return redirect lands on referrals page with
success banner

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 18:29:29 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 80cb53f3a2 feat: referral link system with discounts and Stripe Connect payouts (#669)
## Summary

- Add a referral system where any user gets a shareable link (`/r/CODE`)
with a personalized interstitial page
- Referred users get a configurable discount (default 10%) on credit
purchases for 30 days
- Referrers earn a cash kickback (default 20% of revenue) paid out via
Stripe Connect at $20 threshold
- Admin can create vanity links with custom rates and manage all
referral links

## Changes

### Backend
- **New models** (`backend/models/referral.py`): ReferralLink,
ReferralEarning, ReferralPayout + API request/response models
- **New service** (`backend/services/referral_service.py`): Link CRUD,
attribution, discount detection, earnings recording, Stripe Connect
onboarding, auto-payout
- **New routes** (`backend/api/routes/referrals.py`): 7 endpoints —
public interstitial, user dashboard, link updates, Connect onboarding,
admin vanity/list/update
- **Stripe integration**: Coupon creation/lookup, Connect Express
accounts, transfers
- **Webhook hook**: Referral earnings recorded on credit purchases
- **Auth hook**: Referral attribution on first magic link verification
via `x-referral-code` header
- **User model**: Added referral fields (referral_code,
referred_by_code, referred_at, discount_expires_at,
stripe_connect_account_id)

### Frontend
- **Interstitial page** (`/r/CODE`): Shows referrer's name, custom
message, discount details
- **Referral dashboard** (`/app/referrals`): Link sharing, stats,
earnings, payout history, Stripe Connect CTA
- **Discount badge**: Shown in Buy Credits dialog during active referral
window
- **Referral capture**: Cookie + localStorage via `/r/CODE` route and
`?ref=CODE` query param
- **Auth integration**: Passes referral code on magic link verification,
clears after use
- **i18n**: 33 new translation keys in `referrals` namespace

### Documentation
- Design spec: `docs/archive/2026-04-04-referral-system-design.md`
- Implementation plan: `docs/archive/2026-04-04-referral-system-plan.md`
- Updated `docs/README.md` status table and `docs/API.md` with referral
endpoints

## Testing
- 68 referral-specific tests (models, service, routes) — all passing
- 2935 total backend tests — zero regressions
- 710 frontend tests — all passing
- Covers: link management, attribution, self-referral blocking, discount
detection, earnings calculation, payout threshold, edge cases (rounding,
zero amounts), all API endpoints

## Review
- [x] CodeRabbit CLI review completed locally (11 findings, 7 fixed)
- [x] Test review completed (P0/P1 gaps identified and filled)
- [x] Docs reviewed and updated

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-04 17:39:18 -04:00
Andrew Beveridge ☄️ c98da49da9 feat: add jobs search, status filter, and fix loading states (#637)
## Summary
- Add server-side text search to jobs list API (case-insensitive
substring match across artist, title, job_id)
- Replace eye icon toggle with status filter dropdown (All statuses,
Active, Failed, Completed, Cancelled, Awaiting review, Processing)
- Add debounced search input to Recent Jobs header
- Expand limit dropdown options (5, 10, 20, 50, 100, 1000)
- Fix loading state showing "No jobs yet" during cold starts (now shows
spinner)
- Fix API always fetching limit=100 regardless of dropdown selection

## Test plan
- [x] 8 unit tests for `_search_filter_jobs` (artist, title, job_id,
audio search fields, case insensitivity, None handling, empty string,
limit interaction)
- [x] Full backend test suite passes (2870 passed)
- [x] Frontend builds cleanly
- [ ] Manual: verify search filters jobs in real-time on dashboard
- [ ] Manual: verify status dropdown filters correctly
- [ ] Manual: verify loading spinner shows during cold starts instead of
"No jobs yet"

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-03-30 05:03:05 +00:00
Andrew Beveridge ☄️andClaude Opus 4.6 591c050545 feat: Reference lyrics search with relevance filtering (#632)
## Summary

- Add relevance filtering to the correction pipeline — automatically
rejects wrong-song reference lyrics (below 30% word match threshold,
validated against 168 prod source pairs)
- New `POST /api/review/{job_id}/search-lyrics` endpoint lets users
search with alternate artist/title from the review UI, with force-add
override for edge cases
- Redesigned Add Reference Lyrics modal with Search (default) and Paste
tabs, plus inline empty state when no valid sources exist

## Changes

### Backend
- **Relevance filtering** (`correction/relevance.py`): Per-source
scoring based on anchor sequence word coverage. Integrated into
`LyricsCorrector.run()` after anchor finding — sources below threshold
removed before corrections computed
- **Search endpoint** (`routes/review.py`): Queries all providers
(Genius, Spotify, Musixmatch, LRCLIB) with user-supplied artist/title,
auto-filters results, returns added/rejected/not-found breakdown
- **Provider factory** (`operations.py`): `create_lyrics_providers()`
reads env vars, `search_lyrics_sources()` orchestrates
fetch+filter+correct
- **Force override**: `add-lyrics` and `search-lyrics` support `force`
flag to bypass threshold

### Frontend
- **Tabbed modal**: `AddLyricsModal` rewritten with Search (default) and
Paste tabs
- **SearchLyricsTab**: Artist/title inputs, provider search, rejected
source cards with force-add checkboxes
- **ReferenceEmptyState**: Inline search/paste UI when no valid
reference sources exist
- **API client**: New `searchLyrics()` method with
`SearchLyricsResponse` types

### Analysis
- Empirical threshold analysis script
(`scripts/analyze_reference_relevance.py`) + visual review tool
- 168 source pairs from 81 prod jobs: wrong-song max 3.5%, correct-song
min 26.8% → 30% threshold

## Testing
- 35 new backend tests (relevance scoring, filtering, corrector
integration, search operation, API endpoint)
- 717 existing frontend tests passing (no regressions)
- Edge case: all sources filtered out handled gracefully

## Review
- [x] Local CodeRabbit review completed (3 issues fixed: response
contract, force param coercion, null checks)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-30 00:25:47 +00:00
Andrew Beveridge ☄️andClaude Opus 4.6 6577babfea Reduce free credits from 2 to 1 per grant (#592)
## Summary

- Welcome credits: 2 → 1 (granted on first email verification)
- Feedback credits: 2 → 1 (granted for submitting product feedback)
- Total possible free credits per account: 4 → 2

## Changes

**Backend:** `NEW_USER_FREE_CREDITS` constant, feedback credit grant, AI
evaluation prompt, model defaults
**Frontend:** Landing page, dashboard banner, feedback dialog, auth
dropdown menu text
**Tests:** Updated all assertions and mock values (115 backend + 712
frontend tests pass)
**Docs:** AI-CREDIT-GATING.md, API.md, README.md,
PRODUCT-COMMUNICATION-GUIDE.md

## Test plan

- [x] Backend tests pass (115 passed)
- [x] Frontend Jest tests pass (712 passed)
- [ ] CI pipeline passes
- [ ] Verify landing page shows "1 Free Credit" after deploy
- [ ] Verify new user signup grants 1 credit (not 2)

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-24 21:30:38 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 c9e434037b feat: admin feedback visibility — page + email notification (#581)
<!-- @coderabbitai ignore -->

## Summary

- **Admin feedback page** at `/admin/feedback` — browse all user
feedback submissions with star ratings, text fields, search, pagination,
and aggregate stats
- **Email notification** to admin@nomadkaraoke.com whenever a user
submits new feedback (configurable via `ADMIN_NOTIFICATION_EMAIL` env
var)
- **Admin API endpoint** `GET /api/admin/feedback` with pagination,
search, test-data filtering, and average ratings

## Context

User feedback was stored in Firestore (`user_feedback` collection) but
completely invisible to the admin — the admin panel only showed a
boolean "Feedback Submitted: Yes/No" badge per user. This PR closes that
gap.

## Changes

**Backend:**
- `GET /api/admin/feedback` endpoint with pagination, search,
`exclude_test` filter, aggregate rating averages
- `send_feedback_notification()` method on `EmailService` — sends HTML
email with star ratings, all text fields, link to admin page
- Wired into `submit_user_feedback` as fire-and-forget (won't block user
response)

**Frontend:**
- New admin page with aggregate stat cards, searchable/paginated table,
visual star ratings, expandable rows for text detail
- "Feedback" sidebar nav item with MessageSquare icon
- `adminApi.listFeedback()` client method + TypeScript types

**Tests:** 14 tests covering endpoint (pagination, search, filtering,
aggregates, empty state, datetime edge cases), email (content, subject,
custom admin, failure), and caller-callee contract integration

## Test plan

- [x] `make test` — 712 tests pass (39 suites)
- [x] 14 new tests in `test_admin_feedback.py`
- [ ] Manual: verify admin page renders at `/admin/feedback` after
deploy
- [ ] Manual: submit feedback → verify email arrives at
admin@nomadkaraoke.com

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23 16:18:32 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 376008fc8f Anti-abuse: credits on verification, IP + fingerprint rate limiting (#552)
## Summary

Three-layer defense against free credit abuse (disposable email bypass):

- **Credits on verification**: Welcome credits granted on first magic
link verification, not account creation. Unverified accounts get 0
credits.
- **Per-IP rate limiting**: Max 2 new accounts per IP per 24 hours.
Silent reject (anti-enumeration).
- **Device fingerprinting**: FingerprintJS (open source) sends browser
fingerprint with magic link request. Combined with IP — either signal
hitting 2/day triggers block. Graceful degradation if fingerprinting
fails.

## Changes

### Backend
- `get_or_create_user()` creates users with 0 credits, stores
`signup_ip` and `device_fingerprint`
- New `grant_welcome_credits_if_eligible()` with
`welcome_credits_granted` flag for idempotency
- Verify endpoint grants credits and returns `credits_granted` in
response
- `count_recent_signups_from_ip()` and
`count_recent_signups_from_fingerprint()` query Firestore
- `is_signup_rate_limited()` combines IP + fingerprint signals
- `send_magic_link` endpoint checks rate limit before creating magic
link (new users only)
- New fields: `User.signup_ip`, `User.device_fingerprint`,
`User.welcome_credits_granted`, `MagicLinkToken.device_fingerprint`,
`SendMagicLinkRequest.device_fingerprint`,
`VerifyMagicLinkResponse.credits_granted`

### Frontend
- New `fingerprint.ts` lib (lazy-loaded FingerprintJS)
- `sendMagicLink` sends `device_fingerprint` with request
- Verify page shows "You received N free credits to get started!" on
first login
- `VerifyMagicLinkResponse` type updated with `credits_granted`

### Tests
- 33 unit + integration tests in `test_anti_abuse.py`
- Covers: credit granting, idempotency, rate limiting (IP +
fingerprint), error paths, caller-callee contracts, model fields,
endpoint integration

## Testing
- [x] All backend tests pass (33 new + existing)
- [x] All frontend tests pass (707 tests)
- [x] `make test` passes

## Review
- [x] CodeRabbit CLI review completed locally
- [x] Review feedback addressed (added `welcome_credits_granted` flag
for idempotency)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-21 01:51:44 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 05cb7a9bec feat: auto-sync disposable email blocklist from community repo (#546)
## Summary

- Add daily auto-sync of disposable email domains from the
[disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains)
community repo (~4,800 domains vs previous 160 hardcoded)
- Restructure Firestore blocklist into three layers: external
(auto-synced), manual (admin-added), allowlisted (admin overrides)
- Admin UI updated with separate sections for each domain source + "Sync
Now" button

## Changes

### Backend
- New `disposable_domain_sync_service.py` — fetch, parse, and sync
external blocklist with migration support
- Updated `email_validation_service.py` — effective set = (external +
manual) - allowlisted, new allowlist CRUD, backward-compatible
`get_blocklist_config()`
- New API endpoints: `POST /blocklists/sync`, `POST/DELETE
/blocklists/allowlisted-domains`, `POST
/internal/sync-disposable-domains`
- Updated `GET /blocklists` response with `external_domains`,
`manual_domains`, `allowlisted_domains`, `last_sync_at`,
`last_sync_count`

### Frontend
- Admin rate-limits page: three sub-sections (external/manual/allowlist)
with sync status bar
- Updated API client types and methods

### Infrastructure
- Cloud Scheduler job for daily sync at 3:00 AM UTC (Pulumi)

### Migration
- First sync automatically migrates from old `disposable_domains` field
- Hardcoded `DEFAULT_DISPOSABLE_DOMAINS` replaced with empty set
(external sync takes over)

## Testing
- 47 new/updated tests across 3 test files (54 total for email
validation + sync)
- 2584 tests pass in full suite
- CodeRabbit CLI: no findings

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 18:45:51 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 6b17a1c748 feat: review reminder emails and auto-expiry for stale jobs (#544)
## Summary

- Hourly cron detects jobs stuck in review (`awaiting_review` /
`in_review`) and takes action
- **24h**: sends gentle reminder email with review link, help offer, and
expiry warning
- **48h**: auto-cancels job, refunds credit, sends expiry notification
with balance

## Changes

- **New:** `backend/workers/stale_review_processor.py` — core processor
logic
- **New:** `EmailService.send_review_reminder()` and
`send_review_expired()` email methods
- **New:** `POST /api/internal/process-stale-reviews` endpoint (Cloud
Scheduler target)
- **New:** Cloud Scheduler job `stale-review-hourly` (hourly, Pulumi)
- **New:** 24 unit tests (14 processor + 10 email)
- **Fix:** `make test` no longer hangs on frontend Playwright E2E tests
- Excludes made-for-you and tenant jobs
- Uses separate `expiry_reminder_sent` flag (independent of existing
idle reminder)
- Version bump: 0.142.4 → 0.143.0

## Testing

- [x] 24 new unit tests, all passing
- [x] Full backend test suite: 2578 passed
- [x] Full frontend unit tests: 704 passed
- [x] `make test` completes without hanging

## Review

- [x] Local CodeRabbit review completed (5 findings, 4 fixed, 1
correctly skipped)
- [x] Spec review completed (critical `reminder_sent` flag collision
caught and fixed)

## Design

See `docs/archive/2026-03-19-review-reminder-autoexpiry.plan.md` for
full spec.

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 16:15:01 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 51cd0eadc5 Extend search session TTL to 7 days and handle expiry gracefully (#510)
## Summary
- Extended search session TTL from 30 minutes to 7 days so users who
leave a tab open mid-flow don't hit "Search expired"
- Added graceful frontend handling when sessions do expire — redirects
to re-search with a friendly message instead of raw error
- Updated API docs and tests to match

## Changes
- `backend/api/routes/audio_search.py`: TTL `timedelta(minutes=30)` →
`timedelta(days=7)`
- `frontend/components/job/GuidedJobFlow.tsx`: Catch 404/"Search
expired" errors, clear stale session, redirect to Step 2 with friendly
message preserving song info
- `backend/tests/test_standalone_search.py`: Updated test helper TTL to
match
- `docs/API.md`: Updated TTL reference from "30-min" to "7-day"

## Testing
- [x] All 31 search-specific tests pass
- [x] Full backend suite passes (2212 passed)

## Review
- [x] Local CodeRabbit review completed (no issues with these changes)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 03:23:46 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 f1ec70924e Add lyrics review session backup/restore system (#509)
## Summary

- Server-side auto-save of lyrics review sessions (every 60s if dirty,
on preview, on page hide) with SHA-256 deduplication
- Split-pane restore UI with session browser, edit diff preview, and
cross-job search
- Auto-prompts on load if saved sessions exist; falls back to
localStorage for local mode

## Changes

### Backend
- **New model**: `ReviewSession` + `ReviewSessionSummary` dataclasses
with Firestore serialization
- **5 new API endpoints** under `/api/review/`: save, list, get, delete
sessions + cross-job search
- **Firestore**: 8 new methods for review session CRUD using
subcollection pattern (`jobs/{jobId}/review_sessions/{sessionId}`)
- **GCS storage**: Correction data stored in GCS (can exceed Firestore's
1MB doc limit); metadata in Firestore
- **Deduplication**: SHA-256 hash comparison skips saving identical data

### Frontend
- **`useReviewSessionAutoSave` hook**: 60s interval auto-save,
visibilitychange save, exposed `saveSession()` for manual/preview
triggers
- **`SessionRestoreDialog`**: Split-pane modal with session list + edit
diff preview, "This Job"/"All Jobs" tabs, cross-job search, duration
mismatch warning
- **`LyricsAnalyzer` integration**: Auto-checks for saved sessions on
load, "Save Progress" and "Session History" toolbar buttons, triggers
save on preview

### Docs
- API.md: 5 new review session endpoints documented
- README.md: Feature added to Current State table + Recent Changes
- LESSONS-LEARNED.md: GCS + Firestore metadata pattern

### Also included (from #508)
- Job observability improvements: timeline metadata, `log_to_job()`
helper

## Testing
- [x] 18 backend unit tests (model serialization, all API endpoints,
deduplication, auth, 404s)
- [x] 10 auto-save hook tests (triggers, deduplication tracking,
interval, read-only, error handling, summary computation)
- [x] 16 SessionRestoreDialog tests (rendering, restore flow, tab
switching, cross-job search, empty states)
- [x] All 607 frontend tests pass
- [x] All 2409 backend tests pass

## Review
- [x] CodeRabbit CLI review completed locally (1 fix applied:
beforeunload → visibilitychange)
- [x] Test review completed (26 new frontend tests added)
- [x] Docs review completed

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 00:23:42 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 e04337fa5d Fix broken notification and CLI review URLs (#507)
## Summary
- Push notifications were sending users to `/review/{id}` and
`/instrumental/{id}` which 404 on Cloudflare Pages static hosting
- Remote CLI was opening browser to path-based URLs missing the `#/`
hash fragment
- Documentation referenced incorrect URL formats

All URLs now correctly use hash-based routing: `/app/jobs#/{id}/review`
and `/app/jobs#/{id}/instrumental`

## Changes
- **backend/services/push_notification_service.py** — Fixed notification
click URLs
- **backend/api/routes/jobs.py** — Fixed edit track response
`review_url`
- **karaoke_gen/utils/remote_cli.py** — Fixed CLI browser open URLs
- **karaoke_gen/utils/cli_args.py** — Fixed help text
- **Tests** — Updated assertions in push notification and remote CLI
tests
- **Docs** — Fixed URL examples in API.md, README.md, TESTING.md
- **pyproject.toml** — Bump version 0.137.0 → 0.137.1

## Test plan
- [x] Backend push notification tests pass (35 tests)
- [x] Remote CLI tests pass (174 tests)
- [x] Full backend test suite passes (103 tests)
- [x] Frontend unit tests pass (581 tests)

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-07 21:22:28 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 3f568373fd Add edit completed tracks feature (#506)
## Summary

- Add ability to edit completed karaoke tracks: cleans up existing
outputs (YouTube, Dropbox, GDrive, GCS), recycles brand code, resets
state to AWAITING_REVIEW
- Support optional artist/title metadata updates during edit (triggers
screens regeneration)
- New `POST /api/jobs/{job_id}/edit` endpoint with cleanup tracking and
review URL response
- Edit button in OutputLinks for completed jobs with confirmation modal
explaining implications

## Changes

### Backend
- `backend/api/routes/jobs.py` - New edit endpoint with full output
cleanup (YouTube, Dropbox, GDrive, GCS finals), brand code recycling,
state transition, and optional metadata update
- `backend/models/job.py` - Added COMPLETE → AWAITING_REVIEW state
transition and `edit_count` field
- `backend/tests/test_edit_completed_track.py` - 14 unit tests covering
success, metadata updates, validation, and cleanup

### Frontend
- `frontend/components/job/EditTrackModal.tsx` - Confirmation modal with
optional artist/title editing
- `frontend/components/job/OutputLinks.tsx` - Edit button (amber) for
completed jobs with outputs
- `frontend/lib/api.ts` - `editCompletedTrack()` API method and
`EditTrackResponse` type
- `frontend/components/__tests__/OutputLinks.test.tsx` - 3 new tests for
Edit button visibility

### Docs
- `docs/API.md` - Documented new endpoint
- `docs/README.md` - Added recent changes entry
- `docs/archive/2026-03-06-edit-completed-tracks-plan.md` -
Implementation plan

## Test plan

- [x] 14 backend unit tests for edit endpoint (success, metadata,
validation, cleanup)
- [x] 3 frontend tests for Edit button visibility (complete job, deleted
outputs, non-complete)
- [x] All 576 frontend unit tests passing
- [ ] Manual: Edit a completed track, verify outputs are cleaned up and
review reopens
- [ ] Manual: Edit with metadata change, verify screens regenerate

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-07 02:23:38 -05:00