@lovinka/vitrinka 1.1.0 → 1.4.0

package/skills/vitrinka/tests/install-name.test.ts

@@ -0,0 +1,111 @@
+// install-name.test.ts — the `install` PATH shim (temp $HOME, idempotence) and the
+// `name` command's arg validation + PATCH request shape against a loopback fixture.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { makeTmp, runCli, CLI } from './_helpers.ts';
+
+test('install writes an executable shim + zshrc PATH block, idempotently', () => {
+  const home = makeTmp();
+  const env = { HOME: home, PATH: '/usr/bin:/bin' };
+
+  const first = runCli(['install'], { env });
+  assert.equal(first.status, 0, first.stderr);
+  const shimPath = join(home, '.local', 'bin', 'vitrinka');
+  const shim = readFileSync(shimPath, 'utf8');
+  assert.match(shim, /^#!\/bin\/sh\n/);
+  assert.ok(shim.includes(`exec node "${CLI}" "$@"`), shim);
+  assert.ok(statSync(shimPath).mode & 0o100, 'shim must be executable');
+  const zshrc = readFileSync(join(home, '.zshrc'), 'utf8');
+  assert.ok(zshrc.includes('# vitrinka-cli'), zshrc);
+  assert.ok(zshrc.includes('export PATH="$HOME/.local/bin:$PATH"'), zshrc);
+
+  // Re-run: no duplicate PATH block, reports already-installed.
+  const second = runCli(['install'], { env });
+  assert.equal(second.status, 0, second.stderr);
+  assert.match(second.stdout, /already/);
+  const again = readFileSync(join(home, '.zshrc'), 'utf8');
+  assert.equal(again, zshrc, 'zshrc must not grow on re-install');
+});
+
+test('install skips zshrc when bin dir is already on PATH', () => {
+  const home = makeTmp();
+  const env = { HOME: home, PATH: `/usr/bin:${join(home, '.local', 'bin')}` };
+  // --no-completion isolates the PATH-block behavior: with completion appended
+  // by default (its own suite covers that), install would otherwise create
+  // .zshrc for the completion line even when the PATH block is skipped.
+  const r = runCli(['install', '--no-completion'], { env });
+  assert.equal(r.status, 0, r.stderr);
+  assert.ok(!existsSync(join(home, '.zshrc')), 'zshrc must not be created');
+});
+
+test('name validates its arguments', () => {
+  for (const args of [
+    ['name'],                              // no ref
+    ['name', 'fixit/main'],                // 2 segments
+    ['name', 'fixit/main/2'],              // no new name
+    ['name', 'fixit/main/2', 'x', '--clear'], // both
+  ]) {
+    const r = runCli(args, { env: { HOME: makeTmp() } });
+    assert.equal(r.status, 2, `${args.join(' ')}: ${r.stdout}${r.stderr}`);
+  }
+});
+
+// PATCH fixture: records method+url+auth+body, replies 200 JSON.
+const SERVER_JS = `
+const http = require('node:http');
+const fs = require('node:fs');
+const srv = http.createServer((req, res) => {
+  let body = '';
+  req.setEncoding('utf8');
+  req.on('data', (c) => body += c);
+  req.on('end', () => {
+    fs.appendFileSync(process.argv[1],
+      JSON.stringify({ method: req.method, url: req.url, auth: req.headers.authorization || '', body }) + '\\n');
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ url: 'http://vitrinka.test/fixit/main/2', version: 2, name: 'payouts' }));
+  });
+});
+srv.listen(0, '127.0.0.1', () => console.log(srv.address().port));
+`;
+
+function startServer(logPath: string): Promise<{ port: number; stop: () => void }> {
+  return new Promise((resolvePort, reject) => {
+    const child = spawn(process.execPath, ['-e', SERVER_JS, logPath], { stdio: ['ignore', 'pipe', 'inherit'] });
+    child.stdout.setEncoding('utf8');
+    child.stdout.once('data', (d) => resolvePort({ port: Number(String(d).trim()), stop: () => child.kill() }));
+    child.once('error', reject);
+  });
+}
+
+test('name PATCHes the API with token + lowercased slug; --clear sends empty', async () => {
+  const log = join(makeTmp(), 'reqs.log');
+  writeFileSync(log, '');
+  const srv = await startServer(log);
+  try {
+    const env = {
+      HOME: makeTmp(),
+      VITRINKA_URL: `http://127.0.0.1:${srv.port}`,
+      VITRINKA_TOKEN: 'tok-123',
+    };
+    const r = runCli(['name', 'fixit/main/2', 'PayOuts'], { env });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /named fixit\/main\/2 → .*\/fixit\/main\/payouts/);
+
+    const rc = runCli(['name', 'fixit/main/payouts', '--clear'], { env });
+    assert.equal(rc.status, 0, rc.stderr);
+
+    const reqs = readFileSync(log, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+    assert.equal(reqs.length, 2);
+    assert.deepEqual(
+      { method: reqs[0].method, url: reqs[0].url, auth: reqs[0].auth, body: JSON.parse(reqs[0].body) },
+      { method: 'PATCH', url: '/api/v1/sets/fixit/main/2', auth: 'Bearer tok-123', body: { name: 'payouts' } },
+    );
+    assert.equal(reqs[1].url, '/api/v1/sets/fixit/main/payouts');
+    assert.deepEqual(JSON.parse(reqs[1].body), { name: '' });
+  } finally {
+    srv.stop();
+  }
+});

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

@@ -0,0 +1,98 @@
+// manifest.test.ts — manifest ops through the real CLI (add / meta incl. chips / build).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { makeTmp, runCli } from './_helpers.ts';
+
+test('add appends a shot, writes manifest.json + index.html', () => {
+  const root = join(makeTmp(), '.screenshots');
+  const r = runCli(['add', '--root', root,
+    '--file', '2026-07-03/01-ios-login.png', '--surface', 'ios',
+    '--route', 'Login', '--note', 'first shot',
+    '--label', 'VSTUP', '--title', 'Přihlášení']);
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /\+ 2026-07-03\/01-ios-login\.png {2}\(1 shots\)/);
+
+  const m = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'));
+  assert.equal(m.shots.length, 1);
+  const s = m.shots[0];
+  assert.equal(s.file, '2026-07-03/01-ios-login.png');
+  assert.equal(s.surface, 'ios');
+  assert.equal(s.route, 'Login');
+  assert.equal(s.note, 'first shot');
+  assert.equal(s.label, 'VSTUP');
+  assert.equal(s.title, 'Přihlášení');
+  assert.equal(Number.isNaN(Date.parse(s.ts)), false);
+
+  const html = readFileSync(join(root, 'index.html'), 'utf8');
+  assert.match(html, /01-ios-login\.png/);
+
+  // second add accumulates
+  const r2 = runCli(['add', '--root', root, '--file', '2026-07-03/02-web-home.png', '--surface', 'web',
+    '--route', '/home', '--note', 'second']);
+  assert.equal(r2.status, 0);
+  assert.match(r2.stdout, /\(2 shots\)/);
+  const m2 = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'));
+  assert.equal(m2.shots.length, 2);
+  assert.equal(m2.shots[1].label, undefined); // optional journey fields stay absent
+});
+
+test('add without --file exits 2', () => {
+  const root = join(makeTmp(), '.screenshots');
+  const r = runCli(['add', '--root', root]);
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /--file <rel-path> is required/);
+});
+
+test('meta sets journey header + chips, bumps version to 2, rebuilds index.html', () => {
+  const root = join(makeTmp(), '.screenshots');
+  runCli(['add', '--root', root, '--file', '2026-07-03/01-web-a.png', '--surface', 'web', '--route', '/a', '--note', 'n']);
+  const r = runCli(['meta', '--root', root,
+    '--kicker', 'MODE · FLOW', '--title', 'Display title', '--accent', 'title',
+    '--intro', 'One sentence.', '--chip', 'Persona=Dev', '--chip', 'Jazyk=CZ']);
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /journey meta set \(kicker, title, accent, intro, chips\)/);
+
+  const m = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'));
+  assert.equal(m.version, 2);
+  assert.equal(m.journey.kicker, 'MODE · FLOW');
+  assert.equal(m.journey.title, 'Display title');
+  assert.equal(m.journey.accent, 'title');
+  assert.equal(m.journey.intro, 'One sentence.');
+  assert.deepEqual(m.journey.chips, [{ k: 'Persona', v: 'Dev' }, { k: 'Jazyk', v: 'CZ' }]);
+  assert.equal(existsSync(join(root, 'index.html')), true);
+
+  // re-running meta updates fields but keeps the rest (sticky journey)
+  const r2 = runCli(['meta', '--root', root, '--title', 'Better title']);
+  assert.equal(r2.status, 0);
+  const m2 = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'));
+  assert.equal(m2.journey.title, 'Better title');
+  assert.equal(m2.journey.kicker, 'MODE · FLOW');
+  assert.deepEqual(m2.journey.chips, [{ k: 'Persona', v: 'Dev' }, { k: 'Jazyk', v: 'CZ' }]);
+});
+
+test('meta rejects a chip without "=" (exit 2)', () => {
+  const root = join(makeTmp(), '.screenshots');
+  const r = runCli(['meta', '--root', root, '--chip', 'NoEquals']);
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /--chip expects "Key=Value"/);
+});
+
+test('build rebuilds index.html from the manifest alone', () => {
+  const root = join(makeTmp(), '.screenshots');
+  runCli(['add', '--root', root, '--file', '2026-07-03/01-web-a.png', '--surface', 'web', '--route', '/a', '--note', 'n']);
+  const r = runCli(['build', '--root', root]);
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /built .*index\.html \(1 shots\)/);
+});
+
+test('corrupt manifest is refused loudly, never overwritten', () => {
+  const root = join(makeTmp(), '.screenshots');
+  mkdirSync(root, { recursive: true });
+  writeFileSync(join(root, 'manifest.json'), 'not json{');
+  const r = runCli(['add', '--root', root, '--file', 'x.png']);
+  assert.notEqual(r.status, 0);
+  assert.match(r.stderr, /Corrupt manifest/);
+  assert.equal(readFileSync(join(root, 'manifest.json'), 'utf8'), 'not json{'); // untouched
+});

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

@@ -0,0 +1,119 @@
+// operator.test.ts — the `operator` persona command: local file write, server
+// PUT with the token, and the read path (local + server), against a loopback
+// fixture. Also pins that board-from-set stamps X-Board-Actor from the
+// configured operator (UTF-8-as-latin1 so Czech names don't crash the write).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { makeTmp, runCli } from './_helpers.ts';
+
+// Records method+url+auth+actor+body per request, replies with a small JSON
+// body shaped for each route the operator/board commands hit.
+const SERVER_JS = `
+const http = require('node:http');
+const fs = require('node:fs');
+const srv = http.createServer((req, res) => {
+  let body = '';
+  req.setEncoding('utf8');
+  req.on('data', (c) => body += c);
+  req.on('end', () => {
+    fs.appendFileSync(process.argv[1], JSON.stringify({
+      method: req.method, url: req.url,
+      auth: req.headers.authorization || '',
+      actor: req.headers['x-board-actor'] || '',
+      body,
+    }) + '\\n');
+    res.writeHead(200, { 'content-type': 'application/json' });
+    if (req.method === 'GET' && req.url === '/api/v1/operator') res.end(JSON.stringify({ operator: 'ServerBob' }));
+    else if (req.url === '/api/v1/boards') res.end(JSON.stringify({ slug: 'b1' }));
+    else if (req.url.includes('/import-set')) res.end(JSON.stringify({ cards: [], edges: [] }));
+    else if (req.url.includes('/index')) res.end(JSON.stringify({ hash: 'h' }));
+    else res.end(JSON.stringify({ operator: JSON.parse(body || '{}').operator ?? null }));
+  });
+});
+srv.listen(0, '127.0.0.1', () => console.log(srv.address().port));
+`;
+
+function startServer(logPath: string): Promise<{ port: number; stop: () => void }> {
+  return new Promise((resolvePort, reject) => {
+    const child = spawn(process.execPath, ['-e', SERVER_JS, logPath], { stdio: ['ignore', 'pipe', 'inherit'] });
+    child.stdout.setEncoding('utf8');
+    child.stdout.once('data', (d) => resolvePort({ port: Number(String(d).trim()), stop: () => child.kill() }));
+    child.once('error', reject);
+  });
+}
+
+test('operator <name> writes the local file AND PUTs the server default', async () => {
+  const log = join(makeTmp(), 'reqs.log');
+  writeFileSync(log, '');
+  const srv = await startServer(log);
+  try {
+    const home = makeTmp();
+    const env = { HOME: home, VITRINKA_URL: `http://127.0.0.1:${srv.port}`, VITRINKA_TOKEN: 'tok-1' };
+    const r = runCli(['operator', 'Lukáš'], { env });
+    assert.equal(r.status, 0, r.stderr);
+
+    // Local file written verbatim.
+    assert.equal(readFileSync(join(home, '.config', 'vitrinka', 'operator'), 'utf8').trim(), 'Lukáš');
+
+    const reqs = readFileSync(log, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+    const put = reqs.find((q) => q.method === 'PUT' && q.url === '/api/v1/operator');
+    assert.ok(put, 'expected a PUT /api/v1/operator');
+    assert.equal(put.auth, 'Bearer tok-1');
+    assert.deepEqual(JSON.parse(put.body), { operator: 'Lukáš' });
+  } finally {
+    srv.stop();
+  }
+});
+
+test('operator with no arg prints the local + server values', async () => {
+  const log = join(makeTmp(), 'reqs.log');
+  writeFileSync(log, '');
+  const srv = await startServer(log);
+  try {
+    const home = makeTmp();
+    const env = { HOME: home, VITRINKA_URL: `http://127.0.0.1:${srv.port}`, VITRINKA_OPERATOR: 'LocalAmy' };
+    const r = runCli(['operator'], { env });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /operator \(local\): LocalAmy/);
+    assert.match(r.stdout, /operator \(server\): ServerBob/);
+  } finally {
+    srv.stop();
+  }
+});
+
+test('operator <name> without a token still writes locally, warns about the server', () => {
+  const home = makeTmp();
+  const r = runCli(['operator', 'Solo'], { env: { HOME: home, VITRINKA_URL: 'http://127.0.0.1:0' } });
+  assert.equal(r.status, 0, r.stderr);
+  assert.ok(existsSync(join(home, '.config', 'vitrinka', 'operator')));
+  assert.match(r.stderr, /no write token/);
+});
+
+test('board-from-set stamps X-Board-Actor from the operator (Czech name, latin1-encoded)', async () => {
+  const log = join(makeTmp(), 'reqs.log');
+  writeFileSync(log, '');
+  const srv = await startServer(log);
+  try {
+    const home = makeTmp();
+    const root = join(makeTmp(), '.screenshots');
+    // Seed a .vitrinka config so board-from-set has a set to import.
+    const base = `http://127.0.0.1:${srv.port}`;
+    runCli(['remote-init', '--root', root, '--base', base, '--project', 'fixit', '--branch', 'main', '--key', 's-x'],
+      { env: { HOME: home } });
+    const env = { HOME: home, VITRINKA_OPERATOR: 'Lukáš' };
+    const r = runCli(['board-from-set', '--root', root], { env });
+    assert.equal(r.status, 0, r.stderr);
+
+    const reqs = readFileSync(log, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+    const create = reqs.find((q) => q.url === '/api/v1/boards');
+    assert.ok(create, 'expected a create-board POST');
+    // The server read the header as latin1 → decoding those bytes back as UTF-8
+    // yields the original Czech name.
+    assert.equal(Buffer.from(create.actor, 'latin1').toString('utf8'), 'Lukáš');
+  } finally {
+    srv.stop();
+  }
+});

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

@@ -0,0 +1,115 @@
+// push.test.ts — push query params + .vitrinka persistence (--source/--title) and the
+// offline-marker warn-once lifecycle across repeated failed pushes. Loopback-only: the
+// "server" is a child-process HTTP fixture on 127.0.0.1 (runCli is spawnSync, which would
+// starve an in-process server's event loop); the offline tests use a port that was bound
+// and released, so connections are refused instantly. No external network.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createServer } from 'node:net';
+import { spawn } from 'node:child_process';
+import { makeTmp, runCli, PNG } from './_helpers.ts';
+
+function writeCfg(root: string, base: string): void {
+  mkdirSync(root, { recursive: true });
+  writeFileSync(join(root, '.vitrinka'), JSON.stringify({
+    base, project: 'proj', branch: 'main', slug: 'main', key: 's-test', kind: 'screenshots', issue: '',
+  }, null, 2) + '\n');
+}
+
+// Appends each request URL to the log file (argv[1]), always answers 200 JSON.
+const SERVER_JS = `
+const http = require('node:http');
+const fs = require('node:fs');
+const srv = http.createServer((req, res) => {
+  fs.appendFileSync(process.argv[1], req.url + '\\n');
+  req.resume();
+  req.on('end', () => {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ files: 1, url: 'http://vitrinka.test/canonical' }));
+  });
+});
+srv.listen(0, '127.0.0.1', () => console.log(srv.address().port));
+`;
+
+function startServer(logPath: string): Promise<{ port: number; stop: () => void }> {
+  return new Promise((resolvePort, reject) => {
+    const child = spawn(process.execPath, ['-e', SERVER_JS, logPath], { stdio: ['ignore', 'pipe', 'inherit'] });
+    child.stdout.setEncoding('utf8');
+    child.stdout.once('data', (d) => resolvePort({ port: Number(String(d).trim()), stop: () => child.kill() }));
+    child.once('error', reject);
+    child.once('exit', (code) => reject(new Error(`server fixture exited early (code ${code})`)));
+  });
+}
+
+// A port that is guaranteed connection-refused: bind, read, release.
+function freePort(): Promise<number> {
+  return new Promise((res, rej) => {
+    const s = createServer();
+    s.once('error', rej);
+    s.listen(0, '127.0.0.1', () => {
+      const port = (s.address() as { port: number }).port;
+      s.close((e) => (e ? rej(e) : res(port)));
+    });
+  });
+}
+
+test('push persists explicit --source/--title on success; a plain re-push re-sends both', async () => {
+  const tmp = makeTmp();
+  const log = join(tmp, 'requests.log');
+  writeFileSync(log, '');
+  const { port, stop } = await startServer(log);
+  try {
+    const root = join(tmp, '.screenshots');
+    writeCfg(root, `http://127.0.0.1:${port}`);
+
+    const r1 = runCli(['push', '--root', root, '--source', 'fixit/main/s-xyz', '--title', 'Human Title']);
+    assert.equal(r1.status, 0);
+    assert.match(r1.stdout, /synced 1 files → http:\/\/vitrinka\.test\/canonical/);
+    const cfg = JSON.parse(readFileSync(join(root, '.vitrinka'), 'utf8'));
+    assert.equal(cfg.source, 'fixit/main/s-xyz');
+    assert.equal(cfg.title, 'Human Title');
+
+    // The SKILL's "iterate = edit + push again" plain push: the server clears omitted
+    // ?source=/?title= on re-sync, so the CLI must re-send the persisted values.
+    const r2 = runCli(['push', '--root', root]);
+    assert.equal(r2.status, 0);
+
+    const urls = readFileSync(log, 'utf8').trim().split('\n');
+    assert.equal(urls.length, 2);
+    for (const u of urls) {
+      const q = new URL(u, 'http://x').searchParams;
+      assert.equal(q.get('source'), 'fixit/main/s-xyz');
+      assert.equal(q.get('title'), 'Human Title');
+    }
+  } finally {
+    stop();
+  }
+});
+
+test('a failed push mid-episode keeps the marker warned flag — snap warns once per offline episode', async () => {
+  const proj = makeTmp();
+  writeFileSync(join(proj, 'src.png'), PNG);
+  const root = join(proj, '.screenshots');
+  writeCfg(root, `http://127.0.0.1:${await freePort()}`); // nothing listens → every push fails
+
+  const p1 = runCli(['push', '--root', root]);
+  assert.equal(p1.status, 1);
+  assert.match(p1.stderr, /vitrinka unreachable/);
+
+  const s1 = runCli(['snap', 'web', '--file', 'src.png', '--route', '/a', '--note', 'n1'], { cwd: proj });
+  assert.equal(s1.status, 0);
+  assert.match(s1.stderr, /vitrinka unreachable on a previous push/);
+
+  // The episode continues: another failed push (explicit here; snap's detached push does
+  // the same) must carry the warned flag forward instead of re-arming the warning.
+  const p2 = runCli(['push', '--root', root]);
+  assert.equal(p2.status, 1);
+  const marker = JSON.parse(readFileSync(join(root, '.vitrinka-offline'), 'utf8'));
+  assert.equal(marker.warned, true);
+
+  const s2 = runCli(['snap', 'web', '--file', 'src.png', '--route', '/b', '--note', 'n2'], { cwd: proj });
+  assert.equal(s2.status, 0);
+  assert.doesNotMatch(s2.stderr, /vitrinka unreachable/); // warned exactly once for the whole episode
+});

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

@@ -0,0 +1,173 @@
+// scaffold.test.ts — artifact-init / artifact-from-set: import map + kit usage, data embedding,
+// .vitrinka key/kind/source recording, .gitignore. All offline (remote-init never touches network).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { sanitizeSeg } from '../../../pkg/src/cli.ts';
+import { makeTmp, runCli, writeFakeSips, writeShotsFixture } from './_helpers.ts';
+
+test('artifact-init scaffolds index.html with the pinned import map + kit, mints the set, git-ignores', () => {
+  const proj = makeTmp();
+  const r = runCli(['artifact-init', '--slug', 'test-report', '--title', 'My Report'], { cwd: proj });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /vitrinka set → /);
+  assert.match(r.stdout, /scaffolded .*\.artifacts\/test-report\/index\.html/);
+
+  const html = readFileSync(join(proj, '.artifacts', 'test-report', 'index.html'), 'utf8');
+  // import map: the exact vendored, versioned modules
+  assert.match(html, /"react": "\/vendor\/react\.mjs"/);
+  assert.match(html, /"react-dom\/client": "\/vendor\/react-dom-client\.mjs"/);
+  assert.match(html, /"htm": "\/vendor\/htm\.mjs"/);
+  assert.match(html, /"kit-1": "\/vendor\/kit-1\.mjs"/);
+  assert.match(html, /"zipstore-1": "\/vendor\/zipstore-1\.mjs"/);
+  // xyflow stays commented out
+  assert.match(html, /<!-- Flow diagram\?[\s\S]*"@xyflow\/react": "\/vendor\/xyflow-react\.mjs"[\s\S]*-->/);
+  assert.doesNotMatch(html, /"@xyflow\/react":\s*"\/vendor\/xyflow-react\.mjs"\s*[,}]/); // not a live import-map entry
+  // runtime shell
+  assert.match(html, /<script src="\/vendor\/tailwind\.js"><\/script>/);
+  assert.match(html, /const html = htm\.bind\(React\.createElement\);/);
+  assert.match(html, /import { Hero, Chips, Section, ShotCard, StatRow, DownloadAllButton } from 'kit-1';/);
+  assert.match(html, /<title>My Report<\/title>/);
+  assert.match(html, /TODO/);
+  assert.doesNotMatch(html, /fetch\('\.\/data\.json'\)/); // no data.json present at scaffold time
+
+  // vitrinka set config: key = slug, kind = report (default)
+  const cfg = JSON.parse(readFileSync(join(proj, '.artifacts', 'test-report', '.vitrinka'), 'utf8'));
+  assert.equal(cfg.key, 'test-report');
+  assert.equal(cfg.kind, 'report');
+
+  // .artifacts/ git-ignored
+  assert.match(readFileSync(join(proj, '.gitignore'), 'utf8'), /^\.artifacts\/$/m);
+});
+
+test('artifact-init picks up a pre-existing data.json (fetch wired in)', () => {
+  const proj = makeTmp();
+  mkdirSync(join(proj, '.artifacts', 'with-data'), { recursive: true });
+  writeFileSync(join(proj, '.artifacts', 'with-data', 'data.json'), '{}\n');
+  const r = runCli(['artifact-init', '--slug', 'with-data'], { cwd: proj });
+  assert.equal(r.status, 0);
+  const html = readFileSync(join(proj, '.artifacts', 'with-data', 'index.html'), 'utf8');
+  assert.match(html, /fetch\('\.\/data\.json'\)/);
+});
+
+test('artifact-init refuses to clobber an existing index.html (exit 2)', () => {
+  const proj = makeTmp();
+  assert.equal(runCli(['artifact-init', '--slug', 'once'], { cwd: proj }).status, 0);
+  const r = runCli(['artifact-init', '--slug', 'once'], { cwd: proj });
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /already exists/);
+});
+
+test('artifact-init requires --slug', () => {
+  const r = runCli(['artifact-init'], { cwd: makeTmp() });
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /--slug <slug> is required/);
+});
+
+test('a title with double quotes lands as an htm interpolation, not a broken quoted attribute', () => {
+  const proj = makeTmp();
+  const title = 'Report "Q3" summary';
+  const r = runCli(['artifact-init', '--slug', 'q3', '--title', title], { cwd: proj });
+  assert.equal(r.status, 0);
+  const html = readFileSync(join(proj, '.artifacts', 'q3', 'index.html'), 'utf8');
+  // htm passes the interpolated JS string through verbatim — inner quotes survive
+  assert.equal(html.includes('title=${' + JSON.stringify(title) + '}'), true);
+  assert.doesNotMatch(html, /<\$\{Hero\}[^\n]*title="Report/); // the attribute form truncates at the inner '"'
+  assert.equal(html.includes('<title>Report "Q3" summary</title>'), true); // element text: quotes are fine
+});
+
+test('server-invalid set keys (purely numeric / "latest" / *.zip) fail fast, before any writes', () => {
+  const proj = makeTmp();
+  for (const slug of ['42', 'latest', 'my.zip']) {
+    const r = runCli(['artifact-init', '--slug', slug], { cwd: proj });
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /invalid set key/);
+    assert.equal(existsSync(join(proj, '.artifacts', slug)), false); // nothing scaffolded
+  }
+  const r2 = runCli(['remote-init', '--root', join(proj, '.screenshots'), '--key', 'latest']);
+  assert.equal(r2.status, 2);
+  assert.match(r2.stderr, /invalid set key/);
+  assert.equal(existsSync(join(proj, '.screenshots', '.vitrinka')), false);
+
+  const shots = join(proj, '.screenshots');
+  writeShotsFixture(shots, 1);
+  const env = { PATH: `${writeFakeSips(join(proj, 'fakebin'))}:${process.env.PATH!}` };
+  const r3 = runCli(['artifact-from-set', '--slug', '2026', '--from', '.screenshots'], { cwd: proj, env });
+  assert.equal(r3.status, 2);
+  assert.match(r3.stderr, /invalid set key/);
+  assert.equal(existsSync(join(proj, '.artifacts', '2026')), false); // fails before embedding
+});
+
+test('artifact-init outside a git repo files the set under the project dir, not "artifacts"', () => {
+  const proj = makeTmp(); // temp dir — not a git repo
+  const r = runCli(['artifact-init', '--slug', 'data-analysis'], { cwd: proj });
+  assert.equal(r.status, 0);
+  const cfg = JSON.parse(readFileSync(join(proj, '.artifacts', 'data-analysis', '.vitrinka'), 'utf8'));
+  assert.equal(cfg.project, sanitizeSeg(basename(proj), 64)); // the real project dir…
+  assert.notEqual(cfg.project, 'artifacts'); // …not the .artifacts container
+});
+
+test('artifact-from-set: embeds shots, composes Hero/Section/ShotCard/DownloadAllButton, records source', () => {
+  const proj = makeTmp();
+  const shots = join(proj, '.screenshots');
+  writeShotsFixture(shots, 2);
+  writeFileSync(join(shots, '.vitrinka'), JSON.stringify({
+    base: 'https://vitrinka.example', project: 'proj', branch: 'main',
+    slug: 'main', key: 's-test', kind: 'screenshots', issue: '',
+  }, null, 2) + '\n');
+  const env = { PATH: `${writeFakeSips(join(proj, 'fakebin'))}:${process.env.PATH!}` };
+
+  const r = runCli(['artifact-from-set', '--slug', 'demo', '--from', '.screenshots'], { cwd: proj, env });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /scaffolded .*\.artifacts\/demo\/index\.html \(2 shots embedded, source proj\/main\/s-test\)/);
+  assert.match(r.stdout, /write the narrative sections, then `push`/);
+
+  // data.json: journey + embedded shots
+  const data = JSON.parse(readFileSync(join(proj, '.artifacts', 'demo', 'data.json'), 'utf8'));
+  assert.equal(data.shots.length, 2);
+  assert.equal(data.journey.title, 'Test journey');
+  assert.match(data.shots[0].src, /^data:image\/jpeg;base64,/);
+
+  // scaffold: pre-composed kit usage
+  const html = readFileSync(join(proj, '.artifacts', 'demo', 'index.html'), 'utf8');
+  assert.match(html, /fetch\('\.\/data\.json'\)/);
+  assert.match(html, /<\$\{Hero\} kicker=\$\{j\.kicker\} title=\$\{j\.title\} accent=\$\{j\.accent\} intro=\$\{j\.intro\} chips=\$\{j\.chips\} \/>/);
+  assert.match(html, /<\$\{Section\} key=\$\{i\} label=\$\{s\.label\} title=\$\{s\.title\} note=\$\{s\.note\}>/);
+  assert.match(html, /<\$\{ShotCard\} src=\$\{s\.src\} alt=\$\{s\.title \|\| s\.route \|\| 'screenshot'\} caption=\$\{s\.note\} \/>/);
+  assert.match(html, /<\$\{DownloadAllButton\} files=\$\{files\} zipName="demo\.zip" \/>/);
+  assert.match(html, /"kit-1": "\/vendor\/kit-1\.mjs"/);
+  assert.match(html, /"zipstore-1": "\/vendor\/zipstore-1\.mjs"/);
+  assert.match(html, /<title>Test journey<\/title>/); // title from the journey header
+  assert.match(html, /TODO/); // narrative slots left for the author
+
+  // source ref recorded in the artifact's .vitrinka; key = slug, kind = report
+  const cfg = JSON.parse(readFileSync(join(proj, '.artifacts', 'demo', '.vitrinka'), 'utf8'));
+  assert.equal(cfg.key, 'demo');
+  assert.equal(cfg.kind, 'report');
+  assert.equal(cfg.source, 'proj/main/s-test');
+
+  assert.match(readFileSync(join(proj, '.gitignore'), 'utf8'), /^\.artifacts\/$/m);
+});
+
+test('artifact-from-set: --select subsets, --source overrides, missing set config only warns', () => {
+  const proj = makeTmp();
+  const shots = join(proj, '.screenshots');
+  writeShotsFixture(shots, 3); // no .vitrinka in the screenshots root
+  const env = { PATH: `${writeFakeSips(join(proj, 'fakebin'))}:${process.env.PATH!}` };
+
+  const r = runCli(['artifact-from-set', '--slug', 'partial', '--from', '.screenshots',
+    '--select', '1,3', '--source', 'other/branch/key-1'], { cwd: proj, env });
+  assert.equal(r.status, 0);
+  const data = JSON.parse(readFileSync(join(proj, '.artifacts', 'partial', 'data.json'), 'utf8'));
+  assert.deepEqual(data.shots.map((s: { route: string }) => s.route), ['/home', '/end']);
+  const cfg = JSON.parse(readFileSync(join(proj, '.artifacts', 'partial', '.vitrinka'), 'utf8'));
+  assert.equal(cfg.source, 'other/branch/key-1');
+
+  // and without --source: warn, still scaffold, no source recorded
+  const r2 = runCli(['artifact-from-set', '--slug', 'nosource', '--from', '.screenshots'], { cwd: proj, env });
+  assert.equal(r2.status, 0);
+  assert.match(r2.stderr, /source set not recorded/);
+  const cfg2 = JSON.parse(readFileSync(join(proj, '.artifacts', 'nosource', '.vitrinka'), 'utf8'));
+  assert.equal(cfg2.source, undefined);
+});

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

@@ -0,0 +1,28 @@
+// shim.test.ts — gallery.mjs is now a passthrough shim: same args reach the CLI, exit codes
+// and output pass through, and a one-line migration hint lands on stderr.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { makeTmp, runShim } from './_helpers.ts';
+
+test('shim with no args passes through to the CLI usage screen (exit 2) + migration hint', () => {
+  const r = runShim([]);
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /\[gallery\.mjs\] moved — use the "vitrinka" bin/);
+  assert.match(r.stderr, /Usage:/);
+  assert.match(r.stderr, /artifact-from-set/); // the unified CLI's usage, not the old gallery one
+});
+
+test('shim passes real commands through with identical behavior', () => {
+  const root = join(makeTmp(), '.screenshots');
+  const add = runShim(['add', '--root', root, '--file', '2026-07-03/01-web-a.png',
+    '--surface', 'web', '--route', '/a', '--note', 'via shim']);
+  assert.equal(add.status, 0);
+  assert.match(add.stdout, /\+ 2026-07-03\/01-web-a\.png {2}\(1 shots\)/);
+
+  const build = runShim(['build', '--root', root]);
+  assert.equal(build.status, 0);
+  assert.match(build.stdout, /built .*index\.html \(1 shots\)/);
+  assert.equal(existsSync(join(root, 'index.html')), true);
+});