@lovinka/vitrinka 1.1.1 → 1.5.0

package/skills/vitrinka/listen/SKILL.md

@@ -0,0 +1,193 @@
+---
+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).
+
+## 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 `install.sh` / `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

@@ -0,0 +1,108 @@
+// _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

@@ -0,0 +1,118 @@
+// 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
+});