Refactor/s2 project params - #70
Merged
Merged
Conversation
Replace the open-ended index signature with specific optional fields: timestamp_offset, diarization_seed, num_speakers, sync_window_seconds. These are the three params the refactor plan calls out as needing to live in project.json rather than transient CLI flags. Downstream pipeline scripts can now read readProject().params and get a typed, predictable shape. AC: PipelineParams shape matches docs/PRODUCTION_REFACTOR_PLAN.md spec.
Update SAMPLE fixture to use the new typed fields (timestamp_offset, diarization_seed, num_speakers, sync_window_seconds) replacing the old open-ended seed key that no longer satisfies the typed interface. Add two new integration tests: - roundtrip preserves all deterministic pipeline params: verifies each field survives a write/read cycle with correct value and type - roundtrip with partial params: verifies optional fields are preserved as undefined when omitted (partial project files must stay valid) AC: read/write params roundtrip verified for all typed fields.
Add readProjectParams() helper that reads .ragtech/project.json and
returns the params object, returning {} on any error (file absent or
malformed). This keeps the script self-contained without importing TS.
Resolution order: --num-speakers CLI flag > project.params.num_speakers.
If neither is present, the script exits with a clear error message pointing
the user to the wizard or the flag.
This makes num_speakers reproducible: once the wizard writes it to the
project file, reruns don't need the flag explicitly.
AC: rerunning diarize uses persisted num_speakers from project file.
…llback
Add readProjectParams() helper (same pattern as diarize-audio.js) that
reads .ragtech/project.json, returning {} when the file is absent.
Resolution order: --timestamp-offset CLI flag > project.params.timestamp_offset > 0.
This removes CLI ownership of the value: once the wizard stores it in the
project file, reruns pick it up automatically without needing the flag.
AC: rerunning transcribe uses persisted timestamp_offset from project file.
…nscript
Add readProjectParams() helper that reads .ragtech/project.json, returning
{} when the file is absent or malformed. Resolve timestampOffset using the
same precedence as other entrypoints: CLI flag > project.params.timestamp_offset > 0.
The resolved value is stored in a local variable so all downstream checks
and log statements use the project-sourced value rather than the raw CLI object.
Also remove two dead variable assignments (actualEnd, baseStart) and an
unused constant (OUTRO_DURATION_SECS) that were pre-existing ESLint warnings
blocking the pre-commit hook.
AC: rerunning edit-transcript uses persisted timestamp_offset from project file.
…arams Inventory: annotate Sprint 1 issue #3 as done on refactor/s2-project-params. CLAUDE.md: update scripts/config/project.ts row to reflect the typed PipelineParams interface added in this sprint (timestamp_offset, diarization_seed, num_speakers, sync_window_seconds).
…rypoints Pre-push audit identified that readProjectParams() in diarize-audio.js and transcribe-audio.js was untested. These helpers are private to their entrypoints so they're verified via observable stdout behavior: the scripts log speaker count and timestamp offset before attempting diarization/transcription. Tests cover three cases each: - param read from project file (no CLI flag present) - default behavior when project file is absent - CLI flag takes precedence over project file value
W1: add Phase 3 migration comment to readProjectParams in all three .js scripts pointing to scripts/config/project.ts as the canonical source. W2: add 3 integration tests for edit-transcript.js covering project-file timestamp_offset, absent-file fallback, and CLI override resolution paths. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PipelineParams— replaced the open-ended[key: string]: unknownindex signature inscripts/config/project.tswith specific optional fields (timestamp_offset,diarization_seed,num_speakers,sync_window_seconds), matching the schema indocs/PRODUCTION_REFACTOR_PLAN.md. Downstream phases can now rely on typed, named fields fromreadProject().params.diarize-audio.jsreadsnum_speakers, andtranscribe-audio.js/edit-transcript.jsreadtimestamp_offsetfrom.ragtech/project.jsonbefore falling back to CLI flags. Rerunning any of these scripts no longer requires repeating the flags.--num-speakersor--timestamp-offsetis unchanged; the flag takes precedence over the project file.How to review
scripts/config/project.ts—PipelineParamsfields should match the spec indocs/PRODUCTION_REFACTOR_PLAN.md§Layer 1 exactly (field names, types, all optional).scripts/diarize/diarize-audio.js—readProjectParams()helper and updatedresolveArgs(). Verify resolution order:cli.numSpeakers ?? projectParams.num_speakers ?? null.scripts/transcribe/transcribe-audio.js— same pattern fortimestamp_offset. Verifycli.timestampOffset ?? projectParams.timestamp_offset ?? 0.scripts/edit-transcript.js— same pattern; also check three pre-existing dead-code removals (OUTRO_DURATION_SECS,actualEnd,baseStart) that were blocking the linter.tests/integration/project-params-entrypoints.test.ts— 6 tests that spawn the real entrypoints in a temp dir. Confirm they exercise all three resolution paths.tests/integration/project.test.ts— 3 new tests for the typed params roundtrip. Confirmroundtrip with partial paramscovers the optional-field case.Test plan
npm testpasses (15 suites, 272 tests)tsc --noEmitcleanManual verification completed:
npm run transcribe -- --audio <file>withparams.timestamp_offset: 0.5in project.json printsOffset: -0.5swithout--timestamp-offsetflagnpm run diarize -- --audio <file>withparams.num_speakers: 3printsSpeakers: 3 (locked)without--num-speakersflag🤖 Generated with Claude Code
Issues
Closes #16