76 lines
3.6 KiB
Markdown
76 lines
3.6 KiB
Markdown
# Alignment Fallback Safety Implementation Plan
|
|
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Stop subtitle generation from silently falling back into the Studio project workflow unless an explicit environment flag enables it.
|
|
|
|
**Architecture:** Keep the existing alignment adapter and Studio fallback code path, but gate that fallback behind a parsed boolean config from `.env`. When the alignment endpoint returns `404` or `405` and the flag is not enabled, fail fast with a clear error instead of returning unrelated subtitles.
|
|
|
|
**Tech Stack:** TypeScript, Vitest, Express, Node fetch/FormData APIs
|
|
|
|
---
|
|
|
|
### Task 1: Add failing tests for safe-by-default fallback behavior
|
|
|
|
**Files:**
|
|
- Modify: `E:/Downloads/ai-video-dubbing-&-translation/src/server/alignmentAdapter.test.ts`
|
|
- Modify: `E:/Downloads/ai-video-dubbing-&-translation/src/server/audioPipelineConfig.test.ts`
|
|
- Modify: `E:/Downloads/ai-video-dubbing-&-translation/src/server/subtitleGeneration.test.ts`
|
|
|
|
**Step 1: Write the failing tests**
|
|
|
|
- Add a test asserting `requestAlignedTranscript()` throws a clear error on `404` when Studio fallback is not explicitly enabled.
|
|
- Update the existing fallback test to pass only when `allowStudioProjectFallback` is set to `true`.
|
|
- Add config tests for parsing `ALLOW_STUDIO_PROJECT_FALLBACK` with a default of `false`.
|
|
- Add a pipeline test asserting `generateSubtitlePipeline()` forwards the parsed fallback flag into `requestAlignedTranscript()`.
|
|
|
|
**Step 2: Run targeted tests to verify they fail**
|
|
|
|
Run: `node ./node_modules/vitest/vitest.mjs run src/server/alignmentAdapter.test.ts src/server/audioPipelineConfig.test.ts src/server/subtitleGeneration.test.ts`
|
|
|
|
Expected: FAIL because the fallback flag does not exist yet and `requestAlignedTranscript()` still auto-falls back.
|
|
|
|
### Task 2: Implement the minimal fallback gate
|
|
|
|
**Files:**
|
|
- Modify: `E:/Downloads/ai-video-dubbing-&-translation/src/server/audioPipelineConfig.ts`
|
|
- Modify: `E:/Downloads/ai-video-dubbing-&-translation/src/server/alignmentAdapter.ts`
|
|
- Modify: `E:/Downloads/ai-video-dubbing-&-translation/src/server/subtitleGeneration.ts`
|
|
|
|
**Step 1: Add config parsing**
|
|
|
|
- Extend `AudioPipelineConfig` with `allowStudioProjectFallback: boolean`.
|
|
- Parse `ALLOW_STUDIO_PROJECT_FALLBACK` from `.env`, defaulting to `false`.
|
|
|
|
**Step 2: Gate fallback execution**
|
|
|
|
- Extend `RequestAlignedTranscriptOptions` with `allowStudioProjectFallback`.
|
|
- When the alignment root returns `404` or `405` and the flag is `false`, throw a clear error that points to `ALLOW_STUDIO_PROJECT_FALLBACK=true` or a proper alignment backend.
|
|
- When the flag is `true`, keep the current Studio project workflow unchanged.
|
|
|
|
**Step 3: Thread config through the pipeline**
|
|
|
|
- Pass `allowStudioProjectFallback` from `resolveAudioPipelineConfig()` into `requestAlignedTranscript()` inside `generateSubtitlePipeline()`.
|
|
|
|
### Task 3: Update docs and verify
|
|
|
|
**Files:**
|
|
- Modify: `E:/Downloads/ai-video-dubbing-&-translation/.env.example`
|
|
- Modify: `E:/Downloads/ai-video-dubbing-&-translation/README.md`
|
|
|
|
**Step 1: Document the new flag**
|
|
|
|
- Add `ALLOW_STUDIO_PROJECT_FALLBACK="false"` to `.env.example`.
|
|
- Clarify in `README.md` that subtitle generation now uses the local Studio workflow by default, and that fail-fast mode is opt-in.
|
|
|
|
**Step 2: Run verification**
|
|
|
|
Run: `node ./node_modules/vitest/vitest.mjs run src/server/alignmentAdapter.test.ts src/server/audioPipelineConfig.test.ts src/server/subtitleGeneration.test.ts`
|
|
Expected: PASS
|
|
|
|
Run: `node ./node_modules/vitest/vitest.mjs run`
|
|
Expected: PASS
|
|
|
|
Run: `cmd /c npm run lint`
|
|
Expected: PASS
|