mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-10-21 05:01:26 -07:00
sudacode
78eca52b7e
* test: add headless end-to-end harness and CI job Boot the built app against a real mpv, a synthetic clip, a fixture Yomitan dictionary, and a fake AnkiConnect inside a private Xvfb display, then assert on the overlay DOM and the AnkiConnect requests. Adds the test:e2e lane, an e2e session CLI for exploratory checks, and a three-platform CI job. * ci: set e2e temp dir from a step * test: make e2e session startup robust on slow machines Bun caps node:test hooks at 5s, so boot the session inside the first test. Keep pausing until the app's resume retries stop, read cue tokens in one round trip, and resolve Electron through its package entry so CI downloads the binary. * test: harden e2e harness for CI runners Fail fast when mpv cannot be spawned, read every Yomitan popup frame instead of trusting target order, and put the chocolatey mpv directory on PATH. * test: add e2e failure diagnostics and mark Windows job experimental Report what the overlay showed when a cue never renders, dispose the session when the overlay cannot be opened, skip popup frames that vanish mid-poll, and turn off AniSkip lookups in the harness config. * test: read the lookup popup entry from textContent * test: capture renderer console and main-side subtitle state in e2e failures * test: expose the Electron main-process inspector to the e2e harness Adds session.mainProcess() and 'e2e eval main', and reports main's window list alongside the overlay state when a cue never renders. * test: tap subtitle sends and receipts in e2e failure diagnostics * test: probe alternate main-to-renderer paths in e2e failure diagnostics * test: select the visible overlay layer, not the primed modal window Windows and macOS pre-create a hidden modal window that loads the same renderer document, and the harness could attach to it instead of the visible overlay. Drops the delivery taps that found this. * ci: run the Windows e2e job as a normal matrix entry * test: address review on e2e harness Slice the app log at a byte offset before decoding, create the session state file owner-only since it carries the inspector URL, and keep the cue failure when inspector diagnostics are unavailable. * test: create the e2e session state file exclusively
86 lines
5.2 KiB
Markdown
86 lines
5.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## Internal Docs
|
|
|
|
Start here, then leave this file.
|
|
|
|
- Internal system of record: [`docs/README.md`](./docs/README.md)
|
|
- Architecture map: [`docs/architecture/README.md`](./docs/architecture/README.md)
|
|
- Workflow map: [`docs/workflow/README.md`](./docs/workflow/README.md)
|
|
- Verification lanes: [`docs/workflow/verification.md`](./docs/workflow/verification.md)
|
|
- Testing guidelines: [`docs/workflow/testing.md`](./docs/workflow/testing.md)
|
|
- Knowledge-base rules: [`docs/knowledge-base/README.md`](./docs/knowledge-base/README.md)
|
|
- Release guide: [`docs/RELEASING.md`](./docs/RELEASING.md)
|
|
|
|
`docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.
|
|
|
|
`CLAUDE.md` is a symlink to this file; there is one project instruction file, not two.
|
|
|
|
## Quick Start
|
|
|
|
- Init workspace: `git submodule update --init --recursive`
|
|
- Install deps: `make deps` or `bun install` plus `(cd vendor/texthooker-ui && bun install --frozen-lockfile)`
|
|
- Fast dev loop: `make dev-watch`
|
|
- Full local run: `bun run dev`
|
|
- Verbose Electron debug: `electron . --start --dev --log-level debug`
|
|
|
|
## Build / Test
|
|
|
|
- Runtime/package manager: Bun; use the version pinned by `package.json`.
|
|
- Follow [`docs/workflow/verification.md`](./docs/workflow/verification.md) and start with the cheapest sufficient lane.
|
|
- Full handoff gate for substantial changes:
|
|
`bun run typecheck`
|
|
`bun run test:fast`
|
|
`bun run test:env`
|
|
`bun run build`
|
|
`bun run test:smoke:dist`
|
|
- If `docs-site/` changed, also run:
|
|
`bun run docs:test`
|
|
`bun run docs:build`
|
|
- Prefer `make pretty` and `bun run format:check:src`
|
|
|
|
## Change-Specific Checks
|
|
|
|
- Config/schema/defaults: `bun run test:config`; if template/defaults changed, `bun run generate:config-example`
|
|
- Launcher/plugin: `bun run test:launcher` or `bun run test:env`
|
|
- Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
|
|
- Stats dashboard UI (`stats/`): `bun run test:stats`
|
|
- Overlay / renderer / mpv / mining behavior in the running app: `bun run build`, then `bun run test:e2e` (headless, sandboxed; `bun run e2e start` for exploratory checks)
|
|
- Build/release scripts (`scripts/**`): `bun run test:scripts`
|
|
- Internal docs, `AGENTS.md`, or repo skills: `bun run test:docs:kb`
|
|
- User-facing `docs-site/`: `bun run docs:test`, then `bun run docs:build`
|
|
- macOS mpv window helper (`scripts/get-mpv-window-macos.swift`): compile it on macOS with `bun run build`
|
|
- Test lanes are directory-discovered via `scripts/test-lanes.ts`; never hand-list test files in `package.json`
|
|
|
|
## Docs Upkeep
|
|
|
|
- Docs ship with the change, not after. If a change alters behavior, defaults, flags, shortcuts, ports, or APIs, update the matching docs in the same PR. Touching code without reconciling its docs is an incomplete change.
|
|
- Source of truth for config defaults is the generated `config.example.jsonc`. Never write a default value into prose you didn't read from it, and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
|
|
- Trigger map (touch left → update right):
|
|
- `src/config/definitions/**` (schema/defaults/template) → `bun run generate:config-example`, then reconcile `docs-site/configuration.md` + any feature doc that cites that default
|
|
- shortcuts/keybindings (`shortcuts.*`, `keybindings`, `stats.*Key`, `subtitleSidebar.toggleKey`, controller bindings) → `docs-site/shortcuts.md`
|
|
- CLI flags/subcommands (`src/cli/args.ts`, `launcher/**`) → `docs-site/usage.md` + relevant integration doc
|
|
- feature behavior (anki / jellyfin / jimaku / anilist / youtube / immersion / stats / websocket / sidebar / character-dictionary / annotations) → matching `docs-site/<feature>.md`
|
|
- architecture / IPC / workflow / internal process → internal `docs/` (system of record)
|
|
- feature set / requirements / install flow → `README.md`
|
|
- Removing or renaming a config key: grep `docs-site/` and `docs/` for the old key and any value it documented; legacy/hidden keys (`LEGACY_HIDDEN_CONFIG_PATHS`) should not appear in user docs as current settings.
|
|
- Verify after doc edits: `bun run verify:config-example` (if config touched), `bun run docs:test`, `bun run docs:build`.
|
|
|
|
## Sensitive Files
|
|
|
|
- Launcher source of truth: `launcher/*.ts`
|
|
- Generated launcher artifact: `dist/launcher/subminer`; never hand-edit it
|
|
- Repo-root `./subminer` is stale; do not revive it
|
|
- `bun run build` rebuilds bundled Yomitan from `vendor/subminer-yomitan`
|
|
- Do not change signing/packaging identifiers unless the task explicitly requires it
|
|
|
|
## Release / PR Notes
|
|
|
|
- User-visible PRs need reconciled current-outcome fragment(s) in `changes/*.md`. Format and rules live in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; inspect existing same-PR fragments, then update/remove stale bullets or add only genuinely separate outcomes; apply the `skip-changelog` label to opt out).
|
|
- User-visible docs changes get a `type: docs` fragment
|
|
- CI enforces `bun run changelog:lint` and `bun run changelog:pr-check`
|
|
- PR review helpers:
|
|
- `gh pr view --json number,title --jq '"PR #\\(.number): \\(.title)"'`
|
|
- `gh api repos/:owner/:repo/pulls/<num>/comments --paginate`
|
|
- For CI debugging, inspect runs with `gh run list/view`; rerun or fix only within the requested scope.
|