@lovinka/vitrinka 1.7.0 → 1.8.0

package/skills/screenshot/SKILL.md

@@ -1,70 +0,0 @@
----
-name: screenshot
-description: Use when the user invokes "screenshot", or asks to visually capture / document / screenshot UI work as it's built (screens, components, design changes) on iOS simulators, Android emulators, web browsers, or any local UI.
----
-
-# screenshot
-
-Sticky capture mode: once ON, snap after **every meaningful UI change**. Everything publishes live to a **vitrinka board** — the interactive surface where the user reviews the flow, annotates regions, and queues fixes back to THIS session in real time. The board is the deliverable; the set/journey page is its archive.
-
-All mechanics: `vitrinka <cmd>` (zero-dep TypeScript).
-
-## ON
-
-1. Git-ignore `.screenshots/` (`.gitignore` or `.git/info/exclude`), then `mkdir -p .screenshots && touch .screenshots/.active`.
-2. `vitrinka remote-init --root .screenshots` — mints the session's set (auto project+branch from git, sticky).
-3. Set the journey header (re-run when your understanding sharpens):
-   ```bash
-   vitrinka meta --root .screenshots \
-     --kicker "<MODE · FLOW>" --title "<display title>" --accent "<vivid tail>" \
-     --intro "<1–2 sentences>" --chip "Persona=<who>" --chip "Motiv=<light|dark>"
-   ```
-4. Tell the user it's ON; the board link follows after the first shot.
-
-Stay ON all session — `.screenshots/.active` is the marker (survives compaction; re-check it if unsure). OFF on "stop screenshots": `rm .screenshots/.active`.
-
-## Each capture
-
-One `snap` + one `Read`:
-
-```bash
-vitrinka snap <ios|android|macos|web> \
-  [--file <path>] [--open <deeplink>] [--settle <s>] \
-  --route "<url or nav path>" --label "<STAGE, 1-2 uppercase words>" \
-  --title "<short state title>" --note "<1-2 lines: what & why>" \
-  --action "<what you do on this screen to reach the NEXT shot>" \
-  --src <implementing file> [--src <key component>] \
-  --state "<seed user · role · notable app state>"
-```
-
-- Capture **after render** (post hot-reload), one shot per coherent change; when unsure, capture.
-- **`--src` is the highest-value field** — you just navigated the code, so you KNOW the screen's implementing file + 1-2 key visible components (repo-relative paths, repeatable). An annotation on this shot then dispatches with exact file targets. `--state` records what a reproducer needs (who's logged in, fixtures, locale). Optional: `--device <name>` (auto-filled from the iOS simulator) and `--viewport WxH[@scale]`.
-- ios = `simctl` (UDID auto-resolved) · android = `adb` · macos = `screencapture` · **web** = capture via Playwright/chrome-devtools MCP (or `bunx playwright screenshot`, use `127.0.0.1`), then adopt with `--file`.
-- `--open <deeplink>` navigates + waits + captures in ONE command — never chain shell sleeps.
-- **`--hq`** — full-fidelity flow screenshots for **marketing materials**: skips the lossy q85 WebP re-encode and never resizes (keeps the original PNG; uses lossless WebP only when it comes out smaller). The shot is tagged `hq: true` in the manifest. Use it for hero/press assets, not routine review shots (those stay small q85).
-- `--action` becomes the arrow label between this shot and the next on the board; last shot of a flow needs none.
-- snap prints saved path + `(shot N)` (manifest position — what `--select` addresses on multi-day sets) and pushes detached — never wait or poll.
-- Then **Read the saved image to verify** — right screen, right state. Non-delegable.
-
-## The board — default surface
-
-After the **first** shot lands, and again whenever new shots have landed since:
-
-```bash
-vitrinka board-from-set --root .screenshots
-```
-
-Idempotent: creates/reuses the board (slug = set key), imports only new shots, lays the journey out serpentine with `--action`-labeled arrows. **Give the user the board URL as soon as it exists** — it fills live.
-
-## Wrap-up → listen
-
-1. Re-run `board-from-set` (final append).
-2. The summary leads with the board — hand the exact URLs `board-from-set` and `remote-init` printed (server-authoritative; they carry the `/w/<workspace>` segment in multitenant, none in single-tenant): `🧷 board → …` + `📸 N shots → …`. Never hand-compose `{base}/boards/<key>` — it omits the workspace.
-3. **Then attach the listener AUTOMATICALLY — the board is interactive.** Annotations and plain thread replies route to claude (this session) by default; `@eve` only on explicit mention. Don't offer or ask — read `~/.claude/skills/vitrinka/listen/SKILL.md` and follow it: arm the native background monitor (`vitrinka watch`, zero-token idle), announce `⏳ listening — annotate away`, END the turn; the monitor re-invokes this session on each new annotation. Skip only if this session isn't in the app repo (then point the user at `/vitrinka:listen` from the right one).
-
-## Gotchas
-
-- Vitrinka is **WireGuard-mesh-only**; a failed push writes `.screenshots/.vitrinka-offline` — warn once, keep capturing; syncs are idempotent full-set uploads, later pushes backfill (`push --root .screenshots` to force).
-- Shots transcode to WebP q85 (`brew install webp` if `cwebp` missing — falls back to PNG).
-- Never commit shots. Write auth: `VITRINKA_TOKEN` env or `~/.config/vitrinka/token` — never echo it.
-- Local gallery: `.screenshots/index.html`, kept current by snap; rebuild after manual deletions with `build --root .screenshots`.

package/skills/screenshot/gallery.mjs

@@ -1,6 +0,0 @@
-#!/usr/bin/env node
-// gallery.mjs — superseded by the unified vitrinka CLI; passthrough shim so old invocations keep working.
-import { spawnSync } from 'node:child_process';
-console.error('[gallery.mjs] moved — use the "vitrinka" bin (or: node <repo>/pkg/src/cli.ts <cmd>) …');
-const r = spawnSync(process.execPath, [new URL('../vitrinka/cli.ts', import.meta.url).pathname, ...process.argv.slice(2)], { stdio: 'inherit' });
-process.exit(r.status ?? 1);

package/skills/vitrinka/cli.ts

@@ -1,39 +0,0 @@
-#!/usr/bin/env node
-// skills/vitrinka/cli.ts — BACKWARD-COMPAT DELEGATOR.
-//
-// The vitrinka CLI implementation moved into the unified @lovinka/vitrinka
-// package (pkg/src/cli.ts, shipped as the `vitrinka` bin). This thin entry is
-// kept so anything still calling this path keeps working — in particular
-// already-armed `Monitor(node <repo>/skills/vitrinka/cli.ts watch)` commands in
-// live sessions, and repo-dev invocations.
-//
-// New code should call the `vitrinka` bin on PATH (see the skill SKILL.md docs).
-//
-// Resolution: prefer the sibling package source (repo checkout); if this file
-// was copied somewhere without the package alongside it, fall back to the
-// `vitrinka` bin on PATH.
-import { existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-const sibling = fileURLToPath(new URL('../../pkg/src/cli.ts', import.meta.url));
-
-if (existsSync(sibling)) {
-  const mod = await import(sibling);
-  await mod.main(process.argv.slice(2));
-} else if (process.env.VITRINKA_DELEGATED === '1') {
-  // The `vitrinka` we spawned resolved back to THIS delegator (a stale shim
-  // pointing here without the package alongside) — refuse to recurse.
-  console.error('vitrinka: shim loop detected — repoint the shim (npm i -g @lovinka/vitrinka, or `vitrinka install` from a repo checkout)');
-  process.exit(127);
-} else {
-  const { spawnSync } = await import('node:child_process');
-  const r = spawnSync('vitrinka', process.argv.slice(2), {
-    stdio: 'inherit',
-    env: { ...process.env, VITRINKA_DELEGATED: '1' },
-  });
-  if (r.error) {
-    console.error('vitrinka: no sibling package and no `vitrinka` on PATH — install @lovinka/vitrinka');
-    process.exit(127);
-  }
-  process.exit(r.status ?? 1);
-}

package/skills/vitrinka/commands/listen.md

@@ -1,10 +0,0 @@
----
-description: Tune this session into a vitrinka annotation board and work its queue continuously — arms a native background monitor (`vitrinka watch`), zero-token idle. Run FROM THE APP'S REPO. Defaults to auto-scoping to this repo+branch.
-argument-hint: "[board-slug]"
----
-
-Read `~/.claude/skills/vitrinka/listen/SKILL.md` and follow it exactly. Do not
-improvise the loop from memory — the file is the contract (native Monitor,
-scoping, lease rules, per-item workflow).
-
-Arguments: $ARGUMENTS (optional board slug; empty = auto-scope to this repo+branch).

package/skills/vitrinka/listen/SKILL.md

@@ -1,197 +0,0 @@
----
-name: listen
-description: "Tune this Claude Code session into a vitrinka annotation board and work its queue continuously — armed by a NATIVE background monitor (`vitrinka watch`) whose every line re-invokes the session, so idle costs zero tokens and a finished turn still wakes on new work. Fix each annotation in the current repo, push proof shots, honor cancels. Invoke as /vitrinka:listen [board-slug] FROM THE APP'S REPO."
----
-
-# /vitrinka:listen — the listening session (native Monitor)
-
-You are the **worker half of an audit loop**: the user looks at their app's
-screens on a vitrinka board and annotates what's wrong; you fix each annotation
-in THIS repository, attach visual proof, and go back to listening.
-
-**How the listening works (read this — it changed).** You do NOT loop on
-`wait_for_work` in-model. Instead you arm Claude Code's **native background
-Monitor** on `vitrinka watch`: a persistent script that long-polls the work
-queue and prints ONE line per NEW annotation. Each line re-invokes this session;
-while the queue is idle it prints nothing and costs nothing. This fixes the two
-fatal flaws of the old in-model loop: (1) a finished turn can't re-invoke itself
-via MCP, so the session that published the board never heard new work; (2) even
-a looping session burned one context entry per idle heartbeat and eventually
-died by compaction. Silence now means "healthy and idle", forever.
-
-Argument: an optional board slug (`/vitrinka:listen fixit-audit`). **Without a
-board it now AUTO-SCOPES to this repo + branch** — it infers the project from the
-repo (the main worktree's name, the same derivation `vitrinka push` uses) and the
-current git branch, and listens for exactly that project+branch's work. This is
-what lets several Claude sessions listen at once without stepping on each other:
-each session's listener scopes to its own work.
-
-## One listener per scope (the multi-session model)
-
-Multiple Claude sessions can work concurrently on different things, and each arms
-its own scoped listener. The server enforces **at most one live listener per
-scope** — the same board (or the same project+branch) cannot be listened to twice:
-
-- The listener *leases* its scope through the `vitrinka watch` long-poll — that
-  long-poll IS the heartbeat, so if this session (or its process) dies the lease
-  lapses within ~90s and any work it had claimed reverts to the queue for another
-  session. A clean stop (the Monitor being torn down) releases the lease
-  immediately.
-- If another live session already holds this scope, `vitrinka watch` prints
-  `⚠ listener already active (live): <actor>@<host:pid> on <scope>` and exits
-  (code 2). **Tell the user which session holds it** and stop — do not re-arm in a
-  loop. They can listen from that session, pick a different board, or (if the
-  named holder is actually dead) pass `--takeover`.
-- `--takeover` steals only an **expired** lease (a crashed/hard-killed session
-  whose lease hasn't been released). It can never steal a live one.
-
-Scope flags (all optional): `--board <slug>` (one board), `--project <p>
---branch <b>` (override the inferred repo scope), `--all` (the firehose — observe
-every board; `--all` conflicts with nothing and claims no scope, so use it only
-for a read-only overview session, never to work items another session owns).
-
-All scope resolves *within the token's workspace* — the server infers the
-workspace from your Bearer token, so `wait_for_work`/`list_work` scoping by
-`{board}` or `{project, branch}` only ever sees that workspace's work.
-
-## Preconditions — check once, then arm
-
-1. You are in the app repository the board's screenshots come from
-   (`git rev-parse --show-toplevel` works and the project matches what capsules
-   will reference). If the cwd is clearly not an app repo, say so and stop.
-2. The `vitrinka` MCP tools are available (`wait_for_work`, `set_status`,
-   `reply`, `attach_after`, `get_capsule`). If not, tell the user to run
-   `claude mcp add --scope user vitrinka -- npx -y --package=@lovinka/vitrinka vitrinka-mcp`
-   (or, on a repo checkout, `-- node <vitrinka-repo>/mcp/server.ts`).
-3. The **Monitor tool** is available in this harness. If it is NOT, use the
-   FALLBACK loop at the bottom of this file instead.
-
-## Arm the monitor, then END THE TURN
-
-Use the `vitrinka` binary on PATH (installed by `vitrinka install` / `npm i -g
-@lovinka/vitrinka`). If it is not on PATH (a repo-dev machine without the shim),
-fall back to `node <vitrinka-repo>/pkg/src/cli.ts watch`.
-
-Arm the monitor (the schema requires `timeout_ms` and `persistent` even though
-`timeout_ms` is ignored when `persistent` is true — pass both):
-
-```
-Monitor({
-  command: "vitrinka watch",   // auto-scopes to this repo+branch; add --board <slug> for one board, --all for the firehose
-  persistent: true,
-  timeout_ms: 300000,
-  description: "vitrinka work queue (<repo/branch|board|all>)"
-})
-```
-
-**Default is auto-scope** — no `--board` needed. `vitrinka watch` with no scope
-flag infers project+branch from the repo you are in and leases that scope. If the
-monitor's FIRST output line is a `⚠ listener already active …` (exit 2), another
-session already owns this scope: surface which one and stop (see the multi-session
-section above); do not silently re-arm.
-
-Then, in the SAME turn:
-
-1. Announce exactly one line: `⏳ listening on <board|all boards> — annotate away`.
-2. **END THE TURN.** Do not loop, do not poll, do not sleep. Idle costs nothing;
-   the monitor's next line re-invokes you. This is the whole point — a finished
-   turn is fine, the monitor is what wakes you.
-
-## On a monitor notification — drain the queue
-
-A monitor line looks like `№<id> [<intent>] <board>: <prompt…>` — one per new
-annotation. When you're re-invoked by one (or a batch):
-
-1. **Drain via MCP, SCOPED THE SAME WAY.** Call `wait_for_work({ …scope,
-   timeoutSec: 1 })` and loop it until it returns `{"idle":true}`, working each
-   returned capsule serially, oldest first, under the per-item rules below. Pass
-   the SAME scope the monitor uses so you only drain your own work: `{ board }`
-   for a board listener, or `{ project, branch }` for the auto-scoped repo
-   listener. Use `timeoutSec: 1` (NOT 50) — the monitor is what waits; here you're
-   just draining what's ready right now, not blocking.
-2. When `wait_for_work` returns idle, the ready queue is empty. **End the turn
-   again.** The monitor stays armed (it's `persistent`) and will re-invoke you on
-   the next annotation. Never disarm it yourself.
-
-Do NOT re-arm the monitor on each notification — it is already running for the
-session's lifetime.
-
-## Working one item
-
-1. **Claim it**: `set_status {id, status: "working"}` — the user's board pin
-   flips amber live. If this returns a 409 (cancelled / already claimed), skip
-   the item silently.
-2. **Announce the plan**: `reply` with ONE terse line ("tightening hero contrast
-   on the dark theme").
-3. **Understand**: the capsule has the ask, the region, and a crop URL — fetch
-   the crop image if seeing the region matters (it usually does). `get_capsule
-   {id}` re-fetches the latest brief after user edits.
-4. **Fix it in this repo.** Scope discipline: the annotated ask only — no
-   drive-by refactors. Commit with a conventional message referencing №id.
-5. **Prove it**: regenerate the screen(s) and push a new set the way this repo
-   does it (its CLAUDE.md / `vitrinka snap` / journey script). Then `attach_after
-   {id, project, branch, selector, file, commit}` pointing at the fixed screen
-   inside the set you just pushed.
-6. **Report**: `reply` with 1-3 lines (what changed, commit, anything the user
-   should eyeball), then `set_status {id, status: "in_review"}`.
-
-Progress notes: at most one `reply` per meaningful moment (plan, pushed vN).
-Never spam the thread; never post "still working".
-
-## Cancels (the user changed their mind)
-
-Any vitrinka tool returning **409 "cancelled"** for an item means the user
-withdrew it mid-flight:
-
-1. Revert the working-tree changes you made FOR THAT ITEM (`git checkout` / drop
-   the WIP commit — surgical, don't touch unrelated state).
-2. Do not reply to the cancelled annotation (writes bounce); mention the
-   cancellation in your session output only.
-3. Move on to the next ready item as if it never existed.
-
-## Degraded / down
-
-If a monitor line reads `⚠ vitrinka unreachable for <n>s — listener degraded`,
-tell the user vitrinka looks down and that the listener is retrying — **keep the
-monitor armed** (it self-recovers and will print `✓ vitrinka reachable again`).
-Do not disarm or re-arm it.
-
-## Rules
-
-- **Never `set_status resolved`** — only the user accepts, on the board.
-- Statuses are the UI: claim before touching code, in_review only after the
-  after-shot is attached.
-- One item at a time; the queue is FIFO — take the oldest first.
-- If a fix genuinely needs the user's input, `reply` with the question,
-  `set_status {status: "open"}` to put it back, and end the turn — any plain
-  reply in the thread re-queues the item and the monitor wakes you again
-  (annotation threads route to claude by default; only explicit @eve turns go to
-  eve).
-- If your context grows unwieldy after many fixes, finish the current item, tell
-  the user to restart the listener, and stop.
-
----
-
-## FALLBACK — in-model loop (only if the Monitor tool is unavailable)
-
-If this harness has **no Monitor tool**, you cannot arm a background watcher —
-fall back to the old in-model loop. It works but is inferior: it burns context
-while idle and the *publishing* session can't self-wake once its turn ends, so
-prefer the Monitor path whenever it exists.
-
-1. Announce `⏳ listening on <board|all boards> — annotate away`.
-2. Loop, never exiting on your own:
-
-```
-forever:
-  r = wait_for_work({ board?, timeoutSec: 50 })
-  if r.idle → call wait_for_work again (free; do NOT sleep, do NOT stop)
-  for each capsule in r.work (serially, oldest first):
-    work the item (per "Working one item" above)
-  → wait_for_work again
-```
-
-`{"idle":true}` is the normal heartbeat of an empty queue — loop silently. Never
-conclude "no work, I'm done". The loop only ends when the user interrupts you, or
-when your context grows unwieldy (finish the current item, tell the user to
-restart the listener, and stop — the ONLY self-initiated exit).

package/skills/vitrinka/tests/_helpers.ts

@@ -1,108 +0,0 @@
-// _helpers.ts — shared fixtures for the vitrinka CLI test suites. Not a test file itself.
-import { mkdtempSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-// The CLI moved into the unified @lovinka/vitrinka package; tests run its source
-// directly. The gallery.mjs shim (and skills/vitrinka/cli.ts delegator) still
-// forward here — covered by shim.test.ts.
-export const CLI = fileURLToPath(new URL('../../../pkg/src/cli.ts', import.meta.url));
-export const SHIM = fileURLToPath(new URL('../../screenshot/gallery.mjs', import.meta.url));
-
-// 1x1 transparent PNG.
-export const PNG = Buffer.from(
-  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==',
-  'base64',
-);
-
-export function makeTmp(): string {
-  return mkdtempSync(join(tmpdir(), 'vitrinka-test-'));
-}
-
-export type RunResult = { status: number | null; stdout: string; stderr: string };
-
-export function runCli(cliArgs: string[], opts: { cwd?: string; env?: Record<string, string> } = {}): RunResult {
-  const r = spawnSync(process.execPath, [CLI, ...cliArgs], {
-    encoding: 'utf8',
-    cwd: opts.cwd,
-    env: { ...process.env, ...opts.env },
-  });
-  if (r.error) throw r.error;
-  return { status: r.status, stdout: r.stdout, stderr: r.stderr };
-}
-
-export function runShim(shimArgs: string[], opts: { cwd?: string } = {}): RunResult {
-  const r = spawnSync(process.execPath, [SHIM, ...shimArgs], { encoding: 'utf8', cwd: opts.cwd });
-  if (r.error) throw r.error;
-  return { status: r.status, stdout: r.stdout, stderr: r.stderr };
-}
-
-// writeFakeBin drops an arbitrary Node-script executable into binDir (for
-// faking capture tools like xcrun/cwebp on PATH).
-export function writeFakeBin(binDir: string, name: string, script: string): string {
-  mkdirSync(binDir, { recursive: true });
-  const p = join(binDir, name);
-  writeFileSync(p, `#!/usr/bin/env node\n${script}`);
-  chmodSync(p, 0o755);
-  return p;
-}
-
-// noWebpPath returns a PATH prefixed with a failing `cwebp`, pinning snap's
-// keep-the-original fallback — otherwise assertions on .png filenames break on
-// machines where `brew install webp` happened.
-export function noWebpPath(): string {
-  const bin = join(makeTmp(), 'bin');
-  writeFakeBin(bin, 'cwebp', 'process.exit(1);');
-  return `${bin}:${process.env.PATH}`;
-}
-
-// A fake `sips` on PATH: copies <src> to the --out path (stands in for resize+jpeg).
-export function writeFakeSips(binDir: string): string {
-  mkdirSync(binDir, { recursive: true });
-  const p = join(binDir, 'sips');
-  writeFileSync(p, `#!/usr/bin/env node
-const fs = require('node:fs');
-const a = process.argv.slice(2);
-const dst = a[a.indexOf('--out') + 1];
-const src = a.find((x) => x !== dst && fs.existsSync(x) && fs.statSync(x).isFile());
-if (!src || !dst) { console.error('fake sips: bad args ' + a.join(' ')); process.exit(1); }
-fs.copyFileSync(src, dst);
-`);
-  chmodSync(p, 0o755);
-  return binDir;
-}
-
-// A screenshots root with a journey header + n sequenced shots (real PNG bytes).
-export function writeShotsFixture(root: string, n = 3): void {
-  const day = '2026-07-03';
-  mkdirSync(join(root, day), { recursive: true });
-  const routes = ['/home', '/detail', '/end', '/extra'];
-  const shots = [];
-  for (let i = 1; i <= n; i++) {
-    const file = `${day}/${String(i).padStart(2, '0')}-web-step${i}.png`;
-    writeFileSync(join(root, file), PNG);
-    shots.push({
-      file,
-      surface: 'web',
-      route: routes[i - 1] || `/r${i}`,
-      note: `note ${i}`,
-      label: `STEP ${i}`,
-      title: `Step ${i}`,
-      ts: `2026-07-03T10:0${i}:00Z`,
-    });
-  }
-  const manifest = {
-    version: 2,
-    journey: {
-      kicker: 'TEST · FLOW',
-      title: 'Test journey',
-      accent: 'journey',
-      intro: 'Intro sentence.',
-      chips: [{ k: 'Persona', v: 'Dev' }],
-    },
-    shots,
-  };
-  writeFileSync(join(root, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
-}

package/skills/vitrinka/tests/derive.test.ts

@@ -1,118 +0,0 @@
-// derive.test.ts — pure helpers: slugs, sequence/filename derivation, --select parsing, udid lookup.
-import { test } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-import { basename } from 'node:path';
-import { kebab, sanitizeSeg, validKey, nextSeq, deriveShotName, parseSelect, findUdid, parseArgs, mainWorktreeTop } from '../../../pkg/src/cli.ts';
-import { makeTmp } from './_helpers.ts';
-
-test('kebab: human titles → filename slugs', () => {
-  assert.equal(kebab('Payout Gate — Sheet!'), 'payout-gate-sheet');
-  assert.equal(kebab('Login Error'), 'login-error');
-  assert.equal(kebab('Přihlášení'), 'prihlaseni'); // diacritics folded
-  assert.equal(kebab('Domov — dlaždice „Hned teď“'), 'domov-dlazdice-hned-ted');
-  assert.equal(kebab('!!!'), 'shot'); // never empty
-  assert.equal(kebab('x'.repeat(100)).length <= 60, true);
-});
-
-test('sanitizeSeg mirrors vitrinka slug rules', () => {
-  assert.equal(sanitizeSeg('Feature/Payouts', 64), 'feature-payouts');
-  assert.equal(sanitizeSeg('..hidden..', 64), 'hidden');
-  assert.equal(sanitizeSeg('a--b___c', 64), 'a-b___c'); // underscores allowed, dashes collapse
-  assert.equal(sanitizeSeg('', 5), 'x');
-});
-
-test('nextSeq: max sequenced prefix + 1, ignoring non-shot files', () => {
-  const tmp = makeTmp();
-  const dir = join(tmp, '2026-07-03');
-  assert.equal(nextSeq(dir), '01'); // dir does not exist yet
-  mkdirSync(dir, { recursive: true });
-  assert.equal(nextSeq(dir), '01');
-  writeFileSync(join(dir, '01-web-a.png'), 'x');
-  writeFileSync(join(dir, '02-ios-b.png'), 'x');
-  writeFileSync(join(dir, 'index.html'), 'x'); // non-shot files don't count
-  writeFileSync(join(dir, '.DS_Store'), 'x');
-  assert.equal(nextSeq(dir), '03');
-});
-
-test('nextSeq never reuses a surviving sequence after a manual shot deletion', () => {
-  const tmp = makeTmp();
-  const dir = join(tmp, '2026-07-03');
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, '01-web-a.png'), 'x');
-  writeFileSync(join(dir, '02-web-b.png'), 'x');
-  writeFileSync(join(dir, '03-web-c.png'), 'x');
-  rmSync(join(dir, '02-web-b.png')); // SKILL-documented curation: delete a bad shot
-  // count-based derivation would say '03' and overwrite 03-web-c.png on re-capture
-  assert.equal(nextSeq(dir), '04');
-});
-
-test('mainWorktreeTop: a linked worktree resolves to the MAIN checkout (project grouping)', () => {
-  const tmp = makeTmp();
-  const main = join(tmp, 'FixIt');
-  const wt = join(tmp, 'cpi-admin-ui-overhaul');
-  const sh = (cmd: string, cwd: string) => execSync(cmd, { cwd, stdio: 'pipe' });
-  mkdirSync(main, { recursive: true });
-  sh('git init -q -b main', main);
-  sh('git -c user.email=t@t -c user.name=t commit -q --allow-empty -m init', main);
-  sh(`git worktree add -q -b cpi-admin-ui-overhaul ${JSON.stringify(wt)}`, main);
-  // From the worktree the project must be the main repo dir, not the branch dir.
-  assert.equal(basename(mainWorktreeTop(wt)), 'FixIt');
-  assert.equal(basename(mainWorktreeTop(main)), 'FixIt'); // main checkout unchanged
-  assert.equal(mainWorktreeTop(join(tmp)), ''); // outside a repo → '' (caller falls back)
-});
-
-test('validKey mirrors the server rules (purely numeric / "latest" / *.zip rejected)', () => {
-  assert.equal(validKey('payout-analysis'), true);
-  assert.equal(validKey('s-20260703-0930'), true);
-  assert.equal(validKey('v2.1'), true); // has non-digits → fine
-  assert.equal(validKey('42'), false); // resolves as a version selector
-  assert.equal(validKey('latest'), false);
-  assert.equal(validKey('my.zip'), false);
-  assert.equal(validKey('MY.ZIP'), true); // server suffix check is case-sensitive — mirror exactly
-});
-
-test('deriveShotName: NN-surface-slug.ext', () => {
-  assert.equal(deriveShotName('03', 'ios', 'Login Error'), '03-ios-login-error.png');
-  assert.equal(deriveShotName('01', 'web', '/settings/alerts', '.jpeg'), '01-web-settings-alerts.jpeg');
-});
-
-test('parseSelect: singles, ranges, dedupe, ordering', () => {
-  assert.deepEqual(parseSelect('1,3-5', 6), [1, 3, 4, 5]);
-  assert.deepEqual(parseSelect('2-2', 3), [2]);
-  assert.deepEqual(parseSelect('3,1-2,2', 3), [1, 2, 3]); // dedupe + ascending
-  assert.deepEqual(parseSelect(' 1 , 2 ', 2), [1, 2]); // whitespace tolerated
-});
-
-test('parseSelect: rejects junk, reversed ranges, out-of-range, empty', () => {
-  assert.throws(() => parseSelect('x', 3), /bad token/);
-  assert.throws(() => parseSelect('1;2', 3), /bad token/);
-  assert.throws(() => parseSelect('5-3', 9), /bad range/);
-  assert.throws(() => parseSelect('0', 3), /bad range/);
-  assert.throws(() => parseSelect('9', 3), /out of range/);
-  assert.throws(() => parseSelect('', 3), /empty selection/);
-  assert.throws(() => parseSelect(',', 3), /empty selection/);
-});
-
-test('findUdid: prefers udid-ish keys, falls back to any UUID-shaped value', () => {
-  const u1 = '11111111-2222-3333-4444-555555555555';
-  const u2 = 'AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE';
-  assert.equal(findUdid({ udid: u1 }), u1);
-  assert.equal(findUdid({ worktree: { simulatorUdid: u1 } }), u1); // nested + udid-ish key
-  assert.equal(findUdid({ device: u2, iosUdid: u1 }), u1); // udid-ish key wins
-  assert.equal(findUdid({ something: u2 }), u2); // fallback: any UUID-shaped string
-  assert.equal(findUdid({ udid: 'not-a-udid', other: 42 }), '');
-  assert.equal(findUdid(null), '');
-  assert.equal(findUdid('string'), '');
-});
-
-test('parseArgs: gallery.mjs semantics (accumulating flags, bare flags → true)', () => {
-  const a = parseArgs(['--chip', 'A=1', '--chip', 'B=2', '--flag', '--key', 'v']);
-  assert.deepEqual(a.chip, ['A=1', 'B=2']);
-  assert.equal(a.flag, true);
-  assert.equal(a.key, 'v');
-  const b = parseArgs(['positional', '--x', 'y']);
-  assert.equal(b.x, 'y'); // non-flag tokens skipped
-});