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

refactor(main): modularize runtime and harden anilist setup flow

Browse Source
This commit is contained in:
Kyle Yasuda
2026-02-19 16:04:59 -08:00
parent 58f28b7b55
commit 162be118e1
73 changed files with 4413 additions and 1251 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/subagents/INDEX.md
View File

@@ -4,4 +4,7 @@ Read first. Keep concise.
| agent_id | alias | mission | status | file | last_update_utc |
| ------------ | -------------- | ---------------------------------------------------- | --------- | ------------------------------------- | ---------------------- |
| `codex-main` | `planner-exec` | `Unify config path resolution across app + launcher` | `handoff` | `docs/subagents/agents/codex-main.md` | `2026-02-19T09:05:26Z` |
| `codex-main` | `planner-exec` | `Fix frequency/N+1 regression in plugin --start flow` | `in_progress` | `docs/subagents/agents/codex-main.md` | `2026-02-19T19:36:46Z` |
| `codex-config-validation-20260219T172015Z-iiyf` | `codex-config-validation` | `Find root cause of config validation error for ~/.config/SubMiner/config.jsonc` | `completed` | `docs/subagents/agents/codex-config-validation-20260219T172015Z-iiyf.md` | `2026-02-19T17:26:17Z` |
| `codex-task85-20260219T233711Z-46hc` | `codex-task85` | `Resume TASK-85 maintainability refactor from latest handoff point` | `in_progress` | `docs/subagents/agents/codex-task85-20260219T233711Z-46hc.md` | `2026-02-20T00:00:55Z` |
| `codex-anilist-deeplink-20260219T233926Z` | `anilist-deeplink` | `Fix external subminer:// AniList callback handling from browser` | `done` | `docs/subagents/agents/codex-anilist-deeplink-20260219T233926Z.md` | `2026-02-19T23:59:21Z` |

14
docs/subagents/agents/TEMPLATE.md
View File

@@ -1,11 +1,11 @@
# Agent: <agent_id>
# Agent: `<agent_id>`
- alias: <short label>
- mission: <one-line focus>
- status: <planning|editing|testing|blocked|handoff|done>
- branch: <name>
- started_at: <UTC ISO>
- heartbeat_minutes: <n>
- alias: `<short label>`
- mission: `<one-line focus>`
- status: `<planning|editing|testing|blocked|handoff|done>`
- branch: `<name>`
- started_at: `<UTC ISO>`
- heartbeat_minutes: `<n>`
## Current Work (newest first)
- [YYYY-MM-DDTHH:MM:SSZ] intent: ...

38
docs/subagents/agents/codex-anilist-deeplink-20260219T233926Z.md Normal file
View File

@@ -0,0 +1,38 @@
# Agent: codex-anilist-deeplink-20260219T233926Z
- alias: anilist-deeplink
- mission: Fix external subminer:// AniList callback handling from browser
- status: done
- branch: main
- started_at: 2026-02-19T23:39:26Z
- heartbeat_minutes: 5
## Current Work (newest first)
- [2026-02-19T23:59:21Z] handoff: updated backlog/docs/config artifacts for AniList flow completion; TASK-29.3 marked Done with AC/DoD checked and implementation notes.
- [2026-02-19T23:59:21Z] test: `bun run generate:config-example` pass (includes build), `bun test src/main/runtime/anilist-setup.test.ts` pass (11/11).
- [2026-02-19T23:42:42Z] progress: added app-level protocol registration (`setAsDefaultProtocolClient`) plus `open-url` and `second-instance` deep-link listeners; AniList token consumption moved to shared handler so browser callback `subminer://anilist-setup?access_token=...` saves token even when setup window is not navigating.
- [2026-02-19T23:42:42Z] test: `bun test src/main/runtime/anilist-setup.test.ts` pass (11/11); `bun run build` pass.
- [2026-02-19T23:39:26Z] intent: fix AniList callback deep-link handoff from external browser to app protocol handler; verify token is consumed and setup resolves without requiring in-window nav interception.
- [2026-02-19T23:39:26Z] planned files: `src/main.ts`, `src/main/runtime/anilist-setup.ts`, `src/main/runtime/anilist-setup.test.ts`, `backlog/tasks/task-29.3 - Fix-AniList-OAuth-callback-token-handling-in-setup-window.md`.
- [2026-02-19T23:39:26Z] assumptions: worker emits valid `subminer://anilist-setup?access_token=...` URL; failure is missing app-level protocol registration/open-url handling.
## Files Touched
- `docs/subagents/INDEX.md`
- `docs/subagents/agents/codex-anilist-deeplink-20260219T233926Z.md`
- `src/main.ts`
- `src/main/runtime/anilist-setup.ts`
- `src/main/runtime/anilist-setup.test.ts`
- `backlog/tasks/task-29.3 - Fix-AniList-OAuth-callback-token-handling-in-setup-window.md`
- `docs/configuration.md`
- `src/config/definitions.ts`
- `config.example.jsonc`
- `docs/public/config.example.jsonc`
## Assumptions
- Existing TASK-29.3 covers this bugfix; no new backlog ticket needed.
## Open Questions / Blockers
- none
## Next Step
- Wait for next user direction.

39
docs/subagents/agents/codex-config-validation-20260219T172015Z-iiyf.md Normal file
View File

@@ -0,0 +1,39 @@
# Agent Log
- agent_id: `codex-config-validation-20260219T172015Z-iiyf`
- alias: `codex-config-validation`
- mission: `Find root cause of config validation error for ~/.config/SubMiner/config.jsonc`
- status: `completed`
- last_update_utc: `2026-02-19T17:26:17Z`
## Intent
- inspect validation code path + expected schema
- inspect user config values
- map failing field/type; report exact issue
## Planned Files
- `~/.config/SubMiner/config.jsonc`
- `src/**` (validation/schema)
## Assumptions
- config error produced by current repo binary/schema
- user wants diagnosis only; no edits unless asked
## Run Notes
- phase: `inspect -> reproduce -> handoff`
- strict parse: ok (`reloadConfigStrict` succeeded)
- warnings:
- `ankiConnect.openRouter` deprecated; use `ankiConnect.ai`
- `ankiConnect.isLapis.sentenceCardSentenceField` deprecated; fixed internal value
- `ankiConnect.isLapis.sentenceCardAudioField` deprecated; fixed internal value
## Handoff
- touched files: `docs/subagents/INDEX.md`, `docs/subagents/agents/codex-config-validation-20260219T172015Z-iiyf.md`, `src/main/config-validation.ts`, `src/main/runtime/startup-config.ts`, `src/core/services/config-hot-reload.ts`, `src/main.ts`, `src/main/config-validation.test.ts`, `src/main/runtime/startup-config.test.ts`, `src/core/services/config-hot-reload.test.ts`
- key decision: report warnings as likely user-visible "config validation issue(s)" root cause; then implement detailed warning bodies for startup + hot-reload notifications
- blocker: none
- next step: optional tune max-lines/format for notification bodies

52
docs/subagents/agents/codex-main.md
View File

@@ -1,14 +1,40 @@
# Agent: codex-main
- alias: planner-exec
- mission: Unify config path resolution across app + launcher
- status: handoff
- mission: Fix frequency/N+1 regression in plugin --start flow
- status: in_progress
- branch: main
- started_at: 2026-02-19T08:06:28Z
- heartbeat_minutes: 20
## Current Work (newest first)
- [2026-02-19T19:36:46Z] progress: config confirmed frequency enabled (`~/.config/SubMiner/config.jsonc`); likely mode-latch issue after initial `--texthooker`.
- [2026-02-19T19:36:46Z] change: in `src/main.ts`, `handleCliCommand` now disables `texthookerOnlyMode` on follow-up `--start`/overlay commands and triggers background warmups.
- [2026-02-19T19:36:46Z] test: `bun run build` pass; `bun test src/core/services/cli-command.test.ts src/cli/args.test.ts src/core/services/startup-bootstrap.test.ts` pass (28/28).
- [2026-02-19T19:29:00Z] progress: found second-instance toggle gap: MPV connect was gated to initial-source toggles only; plugin toggle handoff could show overlay without subtitle stream/tokenization.
- [2026-02-19T19:29:00Z] change: updated `src/core/services/cli-command.ts` so toggle/toggle-visible/toggle-invisible trigger MPV connect regardless of source when app is already running.
- [2026-02-19T19:29:00Z] test: added `handleCliCommand connects MPV for toggle on second-instance`; `bun test src/core/services/cli-command.test.ts` pass (19/19).
- [2026-02-19T19:24:18Z] progress: root cause confirmed: subtitle tokenization is skipped when no overlay windows (`src/main.ts`), and `--start` command path did not initialize overlay runtime.
- [2026-02-19T19:24:18Z] change: `src/core/services/cli-command.ts` now initializes overlay runtime for `--start`; second-instance `--start` is ignored only when overlay runtime is already initialized.
- [2026-02-19T19:24:18Z] test: `src/core/services/cli-command.test.ts` covers start-driven init + second-instance behaviors; `bun test src/core/services/cli-command.test.ts` pass (18/18).
- [2026-02-19T19:04:58Z] intent: investigate report that frequency tracking resolves from app config location instead of active app binary root during just-built binary tests; add regression test first, then patch runtime path resolution.
- [2026-02-19T19:04:58Z] planned files: `src/main/frequency-dictionary-runtime.ts`, `src/core/services/frequency-dictionary.ts`, `src/core/services/frequency-dictionary.test.ts`, `backlog/tasks/*` (ticket link).
- [2026-02-19T19:04:58Z] assumptions: runtime should prefer binary-adjacent frequency assets when `SUBMINER_BINARY_PATH` points to a built app binary; config-path-based defaults should remain fallback.
- [2026-02-19T19:05:00Z] backlog: linked work to `TASK-87` (`backlog/tasks/task-87 - Resolve-frequency-storage-path-relative-to-active-app-binary.md`).
- [2026-02-19T16:58:00Z] intent: investigate AniList login regression (`unsupported_grant_type`), add callback token-consumption tests first, then wire `openAnilistSetupWindow` navigation handlers to persist OAuth token from callback URL/hash.
- [2026-02-19T16:54:18Z] handoff: implemented inline same-line option comments in config template output, including enum/boolean value lists where known; regenerated `config.example.jsonc` and `docs/public/config.example.jsonc`.
- [2026-02-19T16:54:18Z] test: `bun run build && node --test dist/config/config.test.js` -> pass (33/33); macOS helper compile sandbox-denied cache path fallback unchanged.
- [2026-02-19T16:51:29Z] intent: user requested inline same-line comments for each example config option with short purpose + allowed values where enum-like; target `config.example.jsonc` (+ `docs/public/config.example.jsonc` parity if needed).
- [2026-02-19T10:24:42Z] progress: continued TASK-85 decomposition slices in `src/main.ts`; extracted config-derived runtime wrappers, AniList setup helpers, clipboard queue runtime, AniList state runtime, immersion media runtime, startup config runtime, and main subsync runtime under `src/main/runtime/`; updated call sites.
- [2026-02-19T10:24:42Z] test: `bun run build` pass (sandbox Swift cache fallback unchanged), `node --test dist/main/runtime/anilist-setup.test.js dist/main/runtime/clipboard-queue.test.js dist/main/runtime/anilist-state.test.js dist/main/runtime/immersion-media.test.js dist/main/runtime/immersion-startup.test.js dist/main/runtime/startup-config.test.js dist/main/config-validation.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js` -> pass (35/35).
- [2026-02-19T10:05:25Z] progress: continued TASK-85 refactor execution; extracted app-ready config runtime handlers to `src/main/runtime/startup-config.ts` + tests and immersion tracker startup handler to `src/main/runtime/immersion-startup.ts` + tests; wired `src/main.ts` call sites to factories; `src/main.ts` now 3250 LOC.
- [2026-02-19T10:05:25Z] test: `bun run build` pass (same macOS helper sandbox fallback), `node --test dist/main/runtime/immersion-startup.test.js dist/main/runtime/startup-config.test.js dist/main/config-validation.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js` -> pass (24/24).
- [2026-02-19T09:55:47Z] handoff: initialized Backlog non-interactive (`backlog init --defaults --integration-mode mcp --auto-open-browser false`), moved TASK-85 to In Progress, completed Task 2 guardrail slice (`scripts/check-file-budgets.ts`, docs, package scripts), and started Task 3 with first `src/main.ts` extraction (`src/main/config-validation.ts` + tests); build/tests pass.
- [2026-02-19T09:55:47Z] test: `bun run check:file-budgets` (warn list), `bun run check:file-budgets:strict` (expected fail), `bun run build` (pass; macOS helper falls back to source due sandbox cache permission), `node --test dist/main/config-validation.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js` (15/15 pass).
- [2026-02-19T09:47:52Z] handoff: delivered concrete maintainability plan at `docs/plans/2026-02-19-repo-maintainability-refactor-plan.md` plus umbrella ticket `TASK-85`; ready for execution-mode choice.
- [2026-02-19T09:45:26Z] intent: user requested concrete maintainability/readability plan via writing-plans + refactor skills; focus hotspots `src/main.ts`, `src/anki-integration.ts`, `plugin/subminer.lua`, generated `subminer` launcher artifact strategy.
- [2026-02-19T09:45:26Z] progress: scanned LOC hotspots and module graph; confirmed `subminer` is generated/ignored build artifact (`make build-launcher`) and major live hotspots are `src/main.ts` (3316 LOC), `src/anki-integration.ts` (1703 LOC), `src/config/service.ts` (1565 LOC), `src/core/services/immersion-tracker-service.ts` (1470 LOC).
- [2026-02-19T09:05:26Z] handoff: completed TASK-70 (Done); unified config path resolution into shared `src/config/path-resolution.ts`, wired app+launcher call sites, added precedence tests, verified build/tests/launcher bundle, and checked AC/DoD in Backlog.
- [2026-02-19T09:05:26Z] test: `bun run build && node --test dist/config/path-resolution.test.js dist/config/config.test.js && bun build ./launcher/main.ts --target=bun --packages=bundle --outfile=/tmp/subminer-task70` -> pass.
- [2026-02-19T08:57:36Z] progress: plan saved to `docs/plans/2026-02-19-task-70-unify-config-path-resolution.md`, mirrored to backlog TASK-70 `planSet`; moving to edit/test execution.
@@ -62,6 +88,13 @@
- `docs/mining-workflow.md`
- `backlog/tasks/task-83 - Simplify-isLapis-sentence-card-field-config-to-fixed-field-names.md`
- `backlog/tasks/task-38 - Add-user-friendly-config-validation-errors-on-startup.md`
- `docs/plans/2026-02-19-repo-maintainability-refactor-plan.md`
- `backlog/tasks/task-85 - Refactor-large-files-for-maintainability-and-readability.md`
- `backlog/config.yml`
- `scripts/check-file-budgets.ts`
- `docs/file-size-budgets.md`
- `src/main/config-validation.ts`
- `src/main/config-validation.test.ts`
## Assumptions
@@ -73,4 +106,17 @@
## Next Step
- Await user review; optional next step is commit for TASK-70 changes.
- Continue Task 3: extract next `src/main.ts` runtime slice (startup reload/logging branch) into `src/main/runtime/*` with seam tests, then re-run build + targeted core tests.
- [2026-02-19T17:20:00Z] intent: improve launcher help output so top-level help auto-lists available subcommands from command registry; add/adjust tests if present.
- [2026-02-19T16:56:43Z] intent: improve launcher help output so top-level help auto-lists available subcommands from command registry; add/adjust tests if present.
- [2026-02-19T16:59:23Z] progress: added auto-generated root help subcommand section by rendering Commander subcommand registry (`launcher/config.ts`) and covered with launcher help regression test (`launcher/config.test.ts`).
- [2026-02-19T16:59:23Z] test: `bun test launcher/config.test.ts` pass; `make build-launcher && ./subminer -h` shows Commands list with jellyfin/yt/doctor/config/mpv/texthooker.
- [2026-02-19T16:59:23Z] handoff: completed requested launcher help improvement; top-level `-h` now includes available subcommands without hard-coded help string updates.
- [2026-02-19T17:07:25Z] progress: added launcher passthrough subcommand `app|bin` that forwards raw args directly to SubMiner binary (`launcher/config.ts`, `launcher/main.ts`, `launcher/types.ts`).
- [2026-02-19T17:07:25Z] test: `bun test launcher/config.test.ts launcher/parse-args.test.ts` pass; passthrough smoke via stub binary env (`SUBMINER_APPIMAGE_PATH=/tmp/subminer-app-stub.sh bun run launcher/main.ts app --anilist --anilist-status`) forwards raw args; `make build-launcher && ./subminer -h` shows `app|bin`.
- [2026-02-19T17:07:25Z] handoff: user-requested direct app/binary passthrough implemented; supports AniList trigger via `subminer app --anilist`.
- [2026-02-19T17:34:30Z] progress: hardened `app|bin` passthrough to bypass Commander parsing and forward raw argv suffix verbatim after subcommand token (`launcher/config.ts`).
- [2026-02-19T17:34:30Z] test: `bun test launcher/config.test.ts launcher/parse-args.test.ts` pass; stub verification confirms exact forwarding for `app --start --anilist-setup -h`; rebuilt wrapper via `make build-launcher`.

49
docs/subagents/agents/codex-task85-20260219T233711Z-46hc.md Normal file
View File

@@ -0,0 +1,49 @@
# Agent: codex-task85-20260219T233711Z-46hc
- alias: codex-task85
- mission: Resume TASK-85 maintainability refactor from latest handoff point
- status: in_progress
- branch: main
- started_at: 2026-02-19T23:37:11Z
- heartbeat_minutes: 5
## Current Work (newest first)
- [2026-02-20T00:00:55Z] progress: extracted AniList setup/protocol handlers (`notifyAnilistSetup`, `consumeAnilistSetupTokenFromUrl`, `handleAnilistSetupProtocolUrl`, `registerSubminerProtocolClient`) from `src/main.ts` into `src/main/runtime/anilist-setup-protocol.ts`; rewired protocol registration and callback wiring; `src/main.ts` now 2988 LOC.
- [2026-02-20T00:00:55Z] test: `bun run build` pass (expected macOS helper Swift cache fallback) + `node --test dist/main/runtime/anilist-setup-protocol.test.js dist/main/runtime/jellyfin-remote-connection.test.js dist/main/runtime/jellyfin-remote-playback.test.js dist/main/runtime/jellyfin-remote-commands.test.js dist/main/runtime/config-hot-reload-handlers.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js` pass (35/35).
- [2026-02-19T23:58:32Z] progress: extracted Jellyfin MPV connection/bootstrap handlers (`waitForMpvConnected`, `launchMpvIdleForJellyfinPlayback`, `ensureMpvConnectedForJellyfinPlayback`) from `src/main.ts` into `src/main/runtime/jellyfin-remote-connection.ts`; rewired call sites; `src/main.ts` now 2996 LOC.
- [2026-02-19T23:58:32Z] test: `bun run build` pass (expected macOS helper Swift cache fallback) + `node --test dist/main/runtime/jellyfin-remote-connection.test.js dist/main/runtime/jellyfin-remote-playback.test.js dist/main/runtime/jellyfin-remote-commands.test.js dist/main/runtime/config-hot-reload-handlers.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js` pass (31/31).
- [2026-02-19T23:50:09Z] progress: extracted Jellyfin remote playback reporting logic (`secondsToJellyfinTicks`, `reportJellyfinRemoteProgress`, `reportJellyfinRemoteStopped`) from `src/main.ts` into `src/main/runtime/jellyfin-remote-playback.ts`; rewired main runtime handlers.
- [2026-02-19T23:50:09Z] test: `bun run build` pass (expected macOS helper Swift cache fallback) + `node --test dist/main/runtime/jellyfin-remote-playback.test.js dist/main/runtime/jellyfin-remote-commands.test.js dist/main/runtime/config-hot-reload-handlers.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js` pass (28/28).
- [2026-02-19T23:48:01Z] progress: extracted Jellyfin remote command/session parsing handlers from `src/main.ts` into `src/main/runtime/jellyfin-remote-commands.ts` (`getConfiguredJellyfinSession`, `handleJellyfinRemotePlay`, `handleJellyfinRemotePlaystate`, `handleJellyfinRemoteGeneralCommand` factories); rewired `src/main.ts` to use handler factories.
- [2026-02-19T23:48:01Z] test: `bun run build` pass (expected macOS helper Swift cache fallback) + `node --test dist/main/runtime/jellyfin-remote-commands.test.js dist/main/runtime/config-hot-reload-handlers.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js` pass (24/24).
- [2026-02-19T23:40:59Z] progress: extracted config hot-reload apply/message callbacks from `src/main.ts` into `src/main/runtime/config-hot-reload-handlers.ts`; `src/main.ts` now 3096 LOC (down from 3116 at session start).
- [2026-02-19T23:40:59Z] test: `bun run build` pass (expected macOS helper Swift cache fallback in sandbox) + `node --test dist/main/runtime/config-hot-reload-handlers.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js` pass (19/19).
- [2026-02-19T23:37:11Z] intent: review TASK-85 state + subagent handoff, then continue next refactor slice from prior checkpoint.
- [2026-02-19T23:37:11Z] planned files: `src/main.ts`, `src/main/runtime/*`, `src/main/runtime/*.test.ts`, `docs/subagents/INDEX.md`, `docs/subagents/agents/codex-task85-20260219T233711Z-46hc.md`.
- [2026-02-19T23:37:11Z] assumptions: backlog MCP not initialized in this workspace; continue using existing `backlog/tasks/task-85 - Refactor-large-files-for-maintainability-and-readability.md` as source of truth.
## Files Touched
- `docs/subagents/INDEX.md`
- `docs/subagents/agents/codex-task85-20260219T233711Z-46hc.md`
- `src/main.ts`
- `src/main/runtime/config-hot-reload-handlers.ts`
- `src/main/runtime/config-hot-reload-handlers.test.ts`
- `src/main/runtime/jellyfin-remote-commands.ts`
- `src/main/runtime/jellyfin-remote-commands.test.ts`
- `src/main/runtime/jellyfin-remote-playback.ts`
- `src/main/runtime/jellyfin-remote-playback.test.ts`
- `src/main/runtime/jellyfin-remote-connection.ts`
- `src/main/runtime/jellyfin-remote-connection.test.ts`
- `src/main/runtime/anilist-setup-protocol.ts`
- `src/main/runtime/anilist-setup-protocol.test.ts`
## Open Questions / Blockers
- none
## Next Step
- identify next extractable `src/main.ts` domain slice, add seam test, extract to `src/main/runtime/*`, run build + targeted tests.
- extract next `src/main.ts` slice likely Jellyfin setup UI branch (`openJellyfinSetupWindow` form handling + config patch helpers) into `src/main/runtime/jellyfin-setup-window.ts` with seam tests.

1
docs/subagents/collaboration.md
View File

@@ -4,3 +4,4 @@ Shared notes. Append-only.
- [YYYY-MM-DDTHH:MM:SSZ] [agent_id|alias] note, question, dependency, conflict, decision.
- [2026-02-19T08:21:11Z] [codex-main|planner-exec] conflict note: `docs/subagents/INDEX.md` and `docs/subagents/agents/codex-main.md` were externally updated to TASK-69 while TASK-38 work was in-flight; reconciled own row/file back to TASK-38 handoff state.
- [2026-02-20T00:01:40Z] [codex-anilist-deeplink|anilist-deeplink] preparing commit; scoping staged set to repo changes, excluding external reference dirs (vendor/yomitan-jlpt-vocab, mpv-anilist-updater).