sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-02-28 06:22:45 -08:00
Code Issues Packages Projects Releases Wiki Activity

update docs and deps

Browse Source
This commit is contained in:
Kyle Yasuda
2026-02-21 23:31:09 -08:00
parent 7a561fca45
commit 44c7b05f96
10 changed files with 487 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
backlog/tasks/task-102 - Restore-Jellyfin-session-migration-contract-and-build-green.md Normal file
View File

@@ -0,0 +1,55 @@
---
id: TASK-102
title: Restore Jellyfin session migration contract and build green
status: To Do
assignee: []
created_date: '2026-02-22 07:12'
updated_date: '2026-02-22 07:12'
labels:
- bug
- jellyfin
- maintainability
dependencies:
- TASK-93
priority: high
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
`bun run build` is currently failing after refactor/rebase drift in Jellyfin auth/session wiring.
Observed drift:
- `src/config/definitions/defaults-integrations.ts` still includes `jellyfin.accessToken` and `jellyfin.userId`.
- `src/config/resolve/integrations.ts` still parses those removed config keys.
- `src/main.ts` still calls removed token-store methods (`loadToken/saveToken/clearToken`) instead of session-store methods.
- setup/config patch flows still attempt to write removed Jellyfin auth fields to config.
This task restores the TASK-93 contract end-to-end: auth in env/stored session, no token/userId in editable config.
<!-- SECTION:DESCRIPTION:END -->
## Action Steps
<!-- SECTION:PLAN:BEGIN -->
1. Remove stale `jellyfin.accessToken`/`jellyfin.userId` keys from defaults and config resolve parsing.
2. Update `src/main.ts` Jellyfin deps wiring to use `loadStoredSession/saveStoredSession/clearStoredSession` with `createJellyfinTokenStore`.
3. Update Jellyfin setup/auth flows so config patch writes only supported Jellyfin config keys.
4. Update launcher-side Jellyfin config loader to stop reading removed auth keys from config file.
5. Add/adjust regression tests around Jellyfin resolver precedence and setup/auth save+clear paths.
6. Verify with `bun run build`, `bun run test:config:src`, and targeted Jellyfin runtime tests.
<!-- SECTION:PLAN:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 `bun run build` passes on `main` after Jellyfin session contract fix.
- [ ] #2 No production config defaults/resolvers parse `jellyfin.accessToken` or `jellyfin.userId`.
- [ ] #3 Main/runtime Jellyfin auth wiring compiles against session-store API only.
- [ ] #4 Jellyfin setup/login/logout paths are covered by source tests and pass.
<!-- AC:END -->
## Definition of Done
<!-- DOD:BEGIN -->
- [ ] #1 Compile + config test lanes pass without local patches.
- [ ] #2 Runtime Jellyfin tests include session-store save/load/clear expectations.
- [ ] #3 Docs/examples reflect session-store contract and no longer mention removed config auth keys.
<!-- DOD:END -->

51
backlog/tasks/task-103 - Extract-Jellyfin-runtime-wiring-from-main.ts-composition-root.md Normal file
View File

@@ -0,0 +1,51 @@
---
id: TASK-103
title: Extract Jellyfin runtime wiring from main.ts composition root
status: To Do
assignee: []
created_date: '2026-02-22 07:13'
updated_date: '2026-02-22 07:13'
labels:
- refactor
- maintainability
- jellyfin
dependencies:
- TASK-102
- TASK-94
- TASK-97
priority: medium
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
`src/main.ts` remains oversized (3014 LOC) and still carries a dense Jellyfin wiring block (roughly `main.ts:1145-1565`) despite composition-root refactors.
Goal: finish extraction of Jellyfin-specific dependency construction and command/setup orchestration into dedicated runtime composer modules so `main.ts` remains thin and legible.
<!-- SECTION:DESCRIPTION:END -->
## Action Steps
<!-- SECTION:PLAN:BEGIN -->
1. Extract Jellyfin config/client-info/auth/list/play/setup dependency builders from `src/main.ts` into focused files under `src/main/runtime/composers/`.
2. Create one Jellyfin composition entrypoint that returns fully wired handlers used by `main.ts`.
3. Remove duplicated inline adapter lambdas from `main.ts`; keep only high-level invocation points.
4. Add/expand composer seam tests for extracted Jellyfin module boundaries.
5. Re-run fan-in and compile checks to ensure extraction does not regress runtime wiring.
<!-- SECTION:PLAN:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 `src/main.ts` no longer contains the full Jellyfin deps-building block.
- [ ] #2 New Jellyfin composer modules have focused tests covering handler wiring.
- [ ] #3 `bun run check:main-fanin` stays green after extraction.
- [ ] #4 `bun run build` and `bun run test:core:src` pass.
<!-- AC:END -->
## Definition of Done
<!-- DOD:BEGIN -->
- [ ] #1 `src/main.ts` LOC reduced materially from current baseline.
- [ ] #2 Jellyfin runtime wiring is centralized in named composer module(s) with clear ownership docs.
- [ ] #3 No behavior regressions in Jellyfin command/setup flows.
<!-- DOD:END -->

55
backlog/tasks/task-104 - Split-launcher-config.ts-into-domain-parsers-and-cli-builder.md Normal file
View File

@@ -0,0 +1,55 @@
---
id: TASK-104
title: Split launcher config.ts into domain parsers and CLI builder
status: To Do
assignee: []
created_date: '2026-02-22 07:13'
updated_date: '2026-02-22 07:13'
labels:
- refactor
- launcher
- maintainability
dependencies:
- TASK-81
- TASK-102
priority: medium
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
`launcher/config.ts` is still a large multi-responsibility file (~700 LOC) combining:
- config file reading/parsing for multiple domains,
- plugin runtime config parsing,
- CLI command tree construction,
- root/subcommand arg normalization.
This file remains a cleanup hotspot and makes contract changes (like Jellyfin session migration) expensive to land safely.
<!-- SECTION:DESCRIPTION:END -->
## Action Steps
<!-- SECTION:PLAN:BEGIN -->
1. Extract launcher config-file readers into domain loaders (YouTube/Jimaku, Jellyfin, plugin runtime).
2. Extract Commander command-tree setup into a dedicated CLI builder module.
3. Extract post-parse normalization into focused argument-normalization helpers.
4. Remove stale Jellyfin config auth field assumptions from launcher config readers.
5. Add focused tests per extracted module while preserving existing `launcher/config.test.ts` behavior expectations.
6. Keep `parseArgs` API stable for launcher call sites.
<!-- SECTION:PLAN:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 `launcher/config.ts` is reduced to thin orchestration over extracted modules.
- [ ] #2 Each extracted module has focused tests that assert current behavior.
- [ ] #3 Launcher still passes `bun run test:launcher` without CLI behavior regressions.
- [ ] #4 Launcher config readers align with current Jellyfin session contract (no config token/userId dependency).
<!-- AC:END -->
## Definition of Done
<!-- DOD:BEGIN -->
- [ ] #1 Public launcher parsing API unchanged for downstream callers.
- [ ] #2 Help text and subcommand option behavior remains unchanged.
- [ ] #3 `bun run test:launcher` and `bun run test:fast` pass.
<!-- DOD:END -->

50
backlog/tasks/task-105 - Eliminate-unsafe-non-test-runtime-casts-in-main-boundaries.md Normal file
View File

@@ -0,0 +1,50 @@
---
id: TASK-105
title: Eliminate unsafe non-test runtime casts in main boundaries
status: To Do
assignee: []
created_date: '2026-02-22 07:13'
updated_date: '2026-02-22 07:13'
labels:
- refactor
- type-safety
- maintainability
dependencies:
- TASK-97
- TASK-80
priority: medium
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Production runtime wiring still relies on many unsafe type escapes (`as never`, `as unknown as`) across `src/main.ts` and `src/main/runtime/*` non-test files.
Current scan shows repeated casts in dependency builders and runtime adapters, which hides contract drift and allowed current Jellyfin compile break to persist until full build.
<!-- SECTION:DESCRIPTION:END -->
## Action Steps
<!-- SECTION:PLAN:BEGIN -->
1. Build a baseline list of non-test unsafe casts in `src/main.ts` and `src/main/runtime`.
2. Group casts by ownership domain (Jellyfin, overlay, startup, IPC, tokenization, tray).
3. For each domain, introduce explicit interface types/adapters so casts are removed at boundary creation.
4. Keep test-only casts allowed where practical, but remove production-path `as never` usage.
5. Add compile-time contract assertions for critical dependency builders to catch drift early.
6. Validate with `bun run build` and affected source test suites.
<!-- SECTION:PLAN:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 Non-test `as never` occurrences in `src/main.ts` and `src/main/runtime` are reduced to zero or documented narrow exceptions.
- [ ] #2 Runtime dependency builders compile without unsafe production-path cast escapes.
- [ ] #3 Contract regressions are caught by compile/test checks rather than runtime behavior.
<!-- AC:END -->
## Definition of Done
<!-- DOD:BEGIN -->
- [ ] #1 Cast reduction report attached in task notes (before/after counts).
- [ ] #2 `bun run build` and `bun run test:core:src` pass.
- [ ] #3 Any remaining exceptions have explicit rationale in code comments or task notes.
<!-- DOD:END -->

54
backlog/tasks/task-106 - Decompose-immersion-tracker-service-into-storage-session-and-metadata-modules.md Normal file
View File

@@ -0,0 +1,54 @@
---
id: TASK-106
title: Decompose immersion tracker service into storage session and metadata modules
status: To Do
assignee: []
created_date: '2026-02-22 07:14'
updated_date: '2026-02-22 07:14'
labels:
- refactor
- maintainability
- immersion-tracking
dependencies:
- TASK-95
priority: medium
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
`src/core/services/immersion-tracker-service.ts` remains large (~1100 LOC) and still mixes multiple concerns in one class:
- queue/flush orchestration,
- DB schema and SQL lifecycle,
- session state transitions,
- local media metadata probing (`ffprobe`/hashing).
Further decomposition is needed to keep ownership boundaries clear and reduce refactor risk.
<!-- SECTION:DESCRIPTION:END -->
## Action Steps
<!-- SECTION:PLAN:BEGIN -->
1. Extract SQLite schema+statement setup into a storage module dedicated to DB lifecycle.
2. Extract session-state transition/event-recording logic into a session runtime module.
3. Extract local metadata probing (hash + ffprobe parsing) into a metadata adapter module.
4. Keep `ImmersionTrackerService` as orchestration facade over extracted collaborators.
5. Expand seam tests for extracted modules and reduce skipped tracker coverage where feasible.
6. Verify with source tracker tests and full build.
<!-- SECTION:PLAN:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 `immersion-tracker-service.ts` no longer embeds full schema SQL and metadata probing logic directly.
- [ ] #2 Extracted modules have focused tests for session transitions, DB writes, and metadata parsing.
- [ ] #3 Tracker behavior remains unchanged (session lifecycle, rollups, retention, queue semantics).
- [ ] #4 Build and tracker-related source tests pass.
<!-- AC:END -->
## Definition of Done
<!-- DOD:BEGIN -->
- [ ] #1 Service file size reduced materially from current baseline.
- [ ] #2 Ownership boundaries documented in `docs/architecture.md` or relevant service docs.
- [ ] #3 No regression in `bun run test:core:src` immersion tracker coverage.
<!-- DOD:END -->

57
backlog/tasks/task-57 - Evaluate-anki-integration.ts-for-further-decomposition.md
View File

@@ -4,52 +4,57 @@ title: Evaluate anki-integration.ts for further decomposition
status: To Do
assignee: []
created_date: '2026-02-16 04:47'
labels: []
updated_date: '2026-02-22 07:14'
labels:
- maintainability
- anki
dependencies: []
references:
- /home/sudacode/projects/japanese/SubMiner/src/anki-integration.ts
- /home/sudacode/projects/japanese/SubMiner/src/anki-integration/
priority: low
priority: medium
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
anki-integration.ts remains the largest file at 1930 lines despite having domain modules extracted to `src/anki-integration/` directory.
`src/anki-integration.ts` remains a major hotspot after refactors and still centralizes too many adapter and helper responsibilities.
Current state:
- Main file: `src/anki-integration.ts` (1930 lines)
- Main file: `src/anki-integration.ts` (~1120 lines on 2026-02-22)
- Extracted modules:
- card-creation.ts (727 lines)
- known-word-cache.ts (398 lines)
- field-grouping.ts (79 lines)
- polling.ts (36 lines)
- duplicate.ts (30 lines)
- ui-feedback.ts (29 lines)
- ai.ts (4.2k)
- workflow and service collaborators already exist under `src/anki-integration/*`
- main class still owns media generation wrappers, field parsing helpers, config normalization, and notification plumbing
This task is to evaluate whether the main anki-integration.ts file can be further decomposed or if 1930 lines is acceptable for a main integration class.
Evaluation criteria:
1. Are there remaining cohesive units that could be extracted?
2. Is the remaining code primarily orchestration logic (which is acceptable to be longer)?
3. Would further splitting improve or hurt readability?
4. Are there internal classes or helpers that could be standalone?
Deliverable: A decision document with recommendations - either proceed with further decomposition or document why the current state is acceptable.
This task decides and documents the next decomposition move, then prepares an implementation-ready extraction plan.
<!-- SECTION:DESCRIPTION:END -->
## Action Steps
<!-- SECTION:PLAN:BEGIN -->
1. Re-map `src/anki-integration.ts` by concern: orchestration, media generation wrappers, field parsing helpers, notification/UI feedback, runtime config patching.
2. Identify cohesive extraction candidates that reduce class surface without adding indirection noise.
3. Define target module boundaries and public interfaces for each candidate extraction.
4. Produce a concrete follow-up implementation plan (candidate files, migration order, regression tests).
5. If no extraction is justified, record explicit rationale and closure criteria.
<!-- SECTION:PLAN:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 Review anki-integration.ts structure and identify remaining cohesive units
- [ ] #2 Evaluate if extraction would improve or hurt maintainability
- [ ] #3 Document decision with rationale
- [ ] #4 If proceeding: create extraction plan with specific modules to create
- [ ] #5 If not proceeding: document architectural justification for keeping as-is
- [ ] #1 Current anki-integration responsibilities are documented with concrete line/section mapping.
- [ ] #2 At least one recommended path is chosen: extraction plan or explicit keep-as-is rationale.
- [ ] #3 Decision includes maintainability tradeoffs and expected impact on testability/readability.
- [ ] #4 Follow-up implementation scope (files/tests/sequence) is explicit enough to execute directly.
<!-- AC:END -->
## Definition of Done
<!-- DOD:BEGIN -->
- [ ] #1 Decision + plan/rationale is captured in task notes.
- [ ] #2 Any proposed extraction references existing collaborators under `src/anki-integration/*`.
- [ ] #3 Follow-up implementation task(s) are created if extraction is recommended.
<!-- DOD:END -->