lablup / lablup/backend.ai-webui
[pr-devserver-review] Walkthrough 3/4 — the walkthrough skill: mint stops headless, verify, post the PR comment
- Dominant language
- TypeScript
- Stars
- 133
- Forks
- 81
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 355
Description
## Parent
FR-3313. Design: wayfinder map FR-3941, decisions FR-3943 (headless minting), FR-3945 (the skill), FR-3946 (the PR comment). Prototype to start from: branch `proto/FR-3943-headless-minting`, `react/vite-plugins/review-overlay/proto-FR-3943/mint.mjs`. Builds on FR-A (fields) — the verify pass needs FR-B only for the guided-mode look, not for resolution.
## What to build
A webui-owned skill `.claude/skills/walkthrough/` the implementing session runs as the last step of the workflow, after `dev-server` has advertised the PR's server.
- **`SKILL.md`**: when to run (after advertise; on demand for any PR with a live server), the stop manifest the session writes (`{route, via[], find: {testid|text}, type, kind, ch, ck, old, new, code[]`}), selection rules (one stop per on-screen-recognizable change; representative call site only; no code-only stops — those go to the PR description's "Not shown in the walkthrough" list; ≤ 20; order = the requester's flow, dialog stops after their opener), wording rules (`ch` past tense with the previous state; `ck` one verifiable expected outcome; `old`/`new` ≤ 40; requester's language, UI labels verbatim), failure reporting, re-run rule (UI-changing re-runs re-mint; doc/test-only do not), the final-message line `Walkthrough: · N stops (k could not be pinned)`.
- **`scripts/mint.mjs`** (Playwright from `node_modules/@playwright/test`): reads the manifest + the boot record (`~/.local/state/fw/dev-servers/.json`) for URL/endpoint/PR/branch, logs in with the box's `e2e/envs/.env.playwright` admin account, **preflights** that the app shell survives login (today's default backend fails with `Cannot query field "scopes" on type "Role"` → exit with a one-line reason, no walkthrough), replays each stop's `via`, mints the anchor in-page through `/__review/{anchor,codec,id}.js` with the FR-A fields (`sha` = `git rev-parse HEAD`, `pr` from the boot record), builds the set link (`deeplink.ts` grammar, first stop's page), **verifies** in a fresh page (on-landing stops resolve within 12 s, path stops after replaying `via`, landmark must match), drops failures into a `couldNotPin[]`, and prints a report JSON `{setLink, stops[], couldNotPin[], sha, pr`}.
- **`scripts/comment.sh`** (or part of mint): upsert the PR comment under `` — header `📍 **Walkthrough · N stops · ** — [Open the walkthrough]()`, `Served by \`\``, a numbered list (bold label, kind, `ch`, `old → new`, `check:`, `code:` file-line links), `Could not pin (check by hand):` list; **no** per-stop dev links, **no** `` markers, **no** `> 📍` blocks; one per PR, edited in place; plus the PR description's `## Walkthrough` section (comment URL + "Not shown" list).
- **CLAUDE.md**: the implementation workflow gains the last step "after advertising the dev server for a PR you implemented, run the `walkthrough` skill"; `dev-server`'s SKILL.md is untouched.
- Shell/unit tests where the repo has them (`test-advertise.sh` style for the comment upsert; a vitest for the manifest validation).
## Acceptance criteria
- [ ] On this box, against a booted server for a UI PR, the skill produces a set link that opens all on-landing stops and a PR comment matching the shape above (screenshot or `gh api` output in the PR).
- [ ] A stop whose element cannot be found ends in "Could not pin" with its `ck`; a preflight failure produces no comment and one explanatory line.
- [ ] Running the skill twice edits the same comment (one marker per PR); the comment carries no `bai-review` marker and `review-pins parse` finds zero pins in it.
- [ ] `bash scripts/verify.sh` passes.
JIRA Issue: FR-3951
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the prototype at react/vite-plugins/review-overlay/proto-FR-3943/mint.mjs and read the requested .claude/skills/walkthrough/SKILL.md, scripts/mint.mjs, and scripts/comment.sh responsibilities. Check existing test-advertise.sh-style tests and the manifest-validation vitest, then run the workflow against a booted server. Done means the skill verifies stops, reports failures, upserts one PR comment, updates CLAUDE.md, and passes scripts/verify.sh.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, github, playwright, shell, typescript
- Domain
- developer-experience, testing, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100