T-LJLH-app-harness-simplicity-dx-review
State: planning/proposed · Impact: high · Complexity: medium
Make @sksizer/app-harness simple before anyone outside this repo uses it. After every internal app
has adopted it, review the API against real use, cut what nobody needs, and write the guide a new
adopter follows.
| Location | Role today |
|---|---|
packages/ts/app-harness/ | withScratchApp, serveScratchApp, scratchWebServer, scratchFixture; options grew per adopter |
| Family adapters | scratchPlatform (Determined), the Tauri-app adapter from T-UU4J, any adapter added for agentpants or ontological desktop |
packages/ts/app-harness/README.md | Describes options; no step-by-step adopter guide |
| S-0020 “How to apply” | Names the harness; no pointer to a guide |
Proposed
Section titled “Proposed”Every option on withScratchApp and each adapter is used by at least one adopter. A new app adopts
the harness with one adapter call in its launcher, one scratchWebServer line in its Playwright
config and one fixture import in its specs. The README opens with that path. Boot time and flake
rate for every suite are measured and recorded.
Approach
Section titled “Approach”- List every option and export, and every adopter’s use of it, in a table in the PR body.
- Remove options and exports with no adopter. Fold adapters that differ only in argv into one.
- Make the one-call path the README’s first section: launcher, config, spec, in that order.
- Add an “Adopting the harness” section to the README: headless server contract
(
FLEET_ROOT, port arg, resolved-paths endpoint), adapter choice, seeding fixtures, warm caches. - Point S-0020 “How to apply” at that section.
- Run each suite 10 times in a row; record median boot time and pass rate per suite in the PR body.
- Fix every suite below 10/10 and any boot above 15 s, or file a task naming the cause.
| Area | Note |
|---|---|
packages/ts/app-harness/ | API cuts, README |
solutions/determined/tests/ui/harness/ | Adapter simplification |
| Every adopting suite | Follow API changes |
docs/planning/standards/S-0020-desktop-apps-tested-web-first-in-scratch-root.md | Guide pointer |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: The PR body has an option-by-adopter table, and every remaining option has at least one adopter.
- AC-2: The README’s first code block is a complete launcher, config line and spec for a new app, under 30 lines total.
- AC-3: Every migrated suite passes 10 consecutive local runs; the PR body lists median boot time and pass count per suite.
- AC-4: S-0020 “How to apply” links the README’s adopter section.
- AC-5: Every internal suite still passes after the API cuts.
Out of scope
Section titled “Out of scope”- Publishing (
T-97OP) and the template (T-GQ9Y). - CI wiring (
T-CAWD).
Dependencies
Section titled “Dependencies”- Every internal migration:
T-VEK2,T-GXNH,T-UU4J,T-AAR2,T-KOTJ,T-JPFC,T-TLET.
Discovery context
Section titled “Discovery context”- Options were added one adopter at a time. A review across all adopters is the cheapest point to remove the ones that did not pay off, before the API is public.
Depends on
Section titled “Depends on”T-VEK2, T-GXNH, T-UU4J, T-AAR2, T-KOTJ, T-JPFC, T-TLET