@lovinka/vitrinka 1.10.2 → 1.12.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 `vitrinka update` prints the sections newer than your previous version after
 updating — keep entries short and user-facing.
 
+## 1.11.0 — 2026-07-15
+
+### Added
+- `vitrinka upload <files…> --board <slug>` — put PDFs, documents, and images
+  on a board as cards straight from disk (the bytes never pass through an AI
+  context). PDFs land as live embedded document cards, other files as download
+  chips. Placement is intent-based: `--section "Name"` lands inside a journey
+  frame (grows to fit), `--anchor <cardId> [--side right|below]` docks beside a
+  card, and no flag = server free placement (never a 0,0 pile).
+
 ## 1.10.1 — 2026-07-13
 
 ### Changed

package/dist/cli.js

@@ -10,7 +10,7 @@
 // skills/screenshot/gallery.mjs (offline marker, COPYFILE_DISABLE, control-file excludes,
 // `--key`, repeatable `--chip`). gallery.mjs is now a passthrough shim to this file.
 // Design: vitrinka/docs/plans/2026-07-03-hand-in-hand-tooling-design.md
-import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync, copyFileSync, mkdtempSync, chmodSync, appendFileSync, statSync, openSync, readSync, closeSync, realpathSync, } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync, copyFileSync, mkdtempSync, chmodSync, appendFileSync, statSync, openSync, readSync, closeSync, realpathSync, openAsBlob, } from 'node:fs';
 import { join, resolve, basename, dirname, extname, relative, sep } from 'node:path';
 import { tmpdir, hostname } from 'node:os';
 import { spawnSync, spawn } from 'node:child_process';
@@ -82,6 +82,55 @@ export function positionals(argv) {
     }
     return out;
 }
+// parseBranches extracts journey branch groups from the RAW argv (the generic
+// parser accumulates repeated flags but loses which --target/--action belongs
+// to which --next). Grammar: each `--next <label>` opens a group; a following
+// `--target <json>` / `--action <text>` belongs to it until the next `--next`.
+// An `--action` BEFORE the first `--next` stays the shot's own linear action.
+export function parseBranches(argv) {
+    let branches;
+    let linearAction;
+    let cur;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--'))
+            continue;
+        const next = argv[i + 1];
+        const val = next === undefined || next.startsWith('--') ? undefined : argv[++i];
+        if (a === '--next') {
+            if (!val)
+                fail('--next needs the target shot\'s label', 2);
+            cur = { to: val };
+            (branches ??= []).push(cur);
+        }
+        else if (a === '--target') {
+            if (!cur)
+                fail('--target must follow a --next (it belongs to that branch)', 2);
+            if (!val)
+                fail('--target needs a {x,y,w,h} JSON bbox', 2);
+            let t;
+            try {
+                t = JSON.parse(val);
+            }
+            catch {
+                fail(`--target: malformed JSON ${JSON.stringify(val)}`, 2);
+            }
+            const r = t;
+            const nums = [r.x, r.y, r.w, r.h].map(Number);
+            if (nums.some((n) => !Number.isFinite(n)) || nums[2] <= 0 || nums[3] <= 0) {
+                fail('--target: need {x,y,w,h} numbers with positive w/h (image px)', 2);
+            }
+            cur.target = { x: nums[0], y: nums[1], w: nums[2], h: nums[3] };
+        }
+        else if (a === '--action' && val !== undefined) {
+            if (cur)
+                cur.action = val;
+            else
+                linearAction = val;
+        }
+    }
+    return { branches, linearAction };
+}
 function manifestPathOf(root) { return join(root, 'manifest.json'); }
 function htmlPathOf(root) { return join(root, 'index.html'); }
 function loadManifest(root) {
@@ -189,12 +238,15 @@ function appendShot(root, shot) {
     writeFileSync(htmlPath, renderHtml(m.shots, project));
     return { count: m.shots.length, htmlPath };
 }
-function addCmd(root, args) {
+function addCmd(root, args, rawArgv = []) {
     const file = args.file;
     if (!file || file === true) {
         console.error('cli.ts add: --file <rel-path> is required');
         process.exit(2);
     }
+    // Branch groups need the raw argv (which --target belongs to which --next);
+    // with branches present the grouped parse also owns the action flags.
+    const { branches, linearAction } = parseBranches(rawArgv);
     const shot = {
         file: String(file),
         surface: args.surface && args.surface !== true ? String(args.surface) : 'other',
@@ -203,7 +255,8 @@ function addCmd(root, args) {
         // journey fields (vitrinka editorial viewer): stage label + short human title
         label: args.label && args.label !== true ? String(args.label) : undefined,
         title: args.title && args.title !== true ? String(args.title) : undefined,
-        action: args.action && args.action !== true ? String(args.action) : undefined,
+        action: branches ? linearAction : (args.action && args.action !== true ? String(args.action) : undefined),
+        branches,
         ts: new Date().toISOString(),
         ...shotContext(args),
     };
@@ -2452,7 +2505,7 @@ export function chooseEncoding(i) {
     }
     return 'original';
 }
-async function snapCmd(surface, args) {
+async function snapCmd(surface, args, rawArgv = []) {
     if (!['ios', 'android', 'macos', 'web'].includes(surface)) {
         console.error(`snap: surface must be ios|android|macos|web, got ${JSON.stringify(surface)}`);
         process.exit(2);
@@ -2607,6 +2660,9 @@ async function snapCmd(surface, args) {
             : surface === 'android' ? 'adb-screencap'
                 : 'screencapture';
     const url = strArg(args.url) || openUrl;
+    // Branch groups (journey signposts) parse from the raw argv — with --next
+    // present, the grouped parse owns the --action flags too.
+    const { branches, linearAction } = parseBranches(rawArgv);
     const { count } = appendShot(root, {
         file: `${day}/${name}`,
         surface,
@@ -2614,7 +2670,8 @@ async function snapCmd(surface, args) {
         note,
         label: strArg(args.label) || undefined,
         title: strArg(args.title) || undefined,
-        action: strArg(args.action) || undefined,
+        action: branches ? linearAction : (strArg(args.action) || undefined),
+        branches,
         hq: hq || undefined,
         ts: new Date().toISOString(),
         tool,
@@ -2926,7 +2983,9 @@ const BASE_FLAG = { f: '--base', arg: '<url>', d: 'vitrinka base URL (default $V
 const CTX_FLAGS = [
     { f: '--label', arg: '<STAGE>', d: 'journey stage label' },
     { f: '--title', arg: '<t>', d: 'short human title' },
-    { f: '--action', arg: '<a>', d: 'edge label — the action leading to the NEXT shot' },
+    { f: '--action', arg: '<a>', d: 'edge label — the action leading to the NEXT shot (after a --next: that branch\'s wire label)' },
+    { f: '--next', arg: '<LABEL>', d: 'journey branch: this screen leads to the shot labeled <LABEL> (repeatable — 2+ make the screen a signpost; each opens a group for --target/--action)' },
+    { f: '--target', arg: '<json>', d: 'the clicked element\'s {x,y,w,h} bbox in IMAGE px (getBoundingClientRect × devicePixelRatio) — belongs to the preceding --next; the wire leaves from it' },
     { f: '--src', arg: '<file>', d: "implementing source file(s) (repeatable or comma-list)" },
     { f: '--state', arg: '<s>', d: 'app/auth state note' },
     { f: '--device', arg: '<name>', d: 'device name' },
@@ -3051,6 +3110,18 @@ export const COMMANDS = [
             { f: '--hq', d: 'full-fidelity marketing asset: no lossy re-encode, no resize (lossless WebP only if smaller)' }],
         examples: ['vitrinka snap ios --route /home --note "landing"', 'vitrinka snap web --route / --note "hero" --hq'],
     },
+    {
+        name: 'upload', summary: 'Upload files (PDF/docs/images) onto a board as cards — bytes stream from disk, never through an AI context',
+        usage: '<files…> --board <slug> [--section "Name"] [--anchor <cardId> --side right|below] [--actor <name>] [--base <url>]',
+        flags: [{ f: '--board', arg: '<slug>', d: 'target board (required)' },
+            { f: '--section', arg: '<name>', d: 'land inside the named journey/take frame (grows to fit)' },
+            { f: '--anchor', arg: '<cardId>', d: 'dock beside an existing card' },
+            { f: '--side', arg: '<right|below>', d: 'which side of the anchor (default right)' },
+            { f: '--actor', arg: '<name>', d: 'override the operator attribution' }, BASE_FLAG],
+        dynamic: 'boards',
+        examples: ['vitrinka upload report.pdf --board pr-105-vitrinka --section "Evidence"',
+            'vitrinka upload spec.docx shots/*.png --board payout-flow'],
+    },
     {
         name: 'board-from-set', summary: 'Turn the set into an annotation flow board',
         usage: '[--root <dir>] [--slug <board>] [--btitle <t>] [--actor <name>]',
@@ -3059,6 +3130,14 @@ export const COMMANDS = [
         dynamic: 'boards',
         examples: ['vitrinka board-from-set --root .screenshots'],
     },
+    {
+        name: 'journey-from-set', summary: 'Turn the set into a journey TREE board — signpost screens fan their branches, wires leave from the clicked element (snap --next/--target)',
+        usage: '[--root <dir>] [--slug <board>] [--btitle <t>] [--actor <name>]',
+        flags: [ROOT_FLAG, { f: '--slug', arg: '<board>', d: 'board slug (default: set key)' },
+            { f: '--btitle', arg: '<t>', d: 'board title' }, { f: '--actor', arg: '<name>', d: 'override the operator attribution' }],
+        dynamic: 'boards',
+        examples: ['vitrinka journey-from-set --root .screenshots'],
+    },
     {
         name: 'watch', summary: 'Monitor the work queue (listen v2); auto-scopes to repo+branch, leases the scope (one listener each), one line per new item',
         usage: '[--board <slug>|--project <p> --branch <b>|--all] [--takeover] [--quiet-grace <sec>] [--once] [--base <url>]',
@@ -3583,7 +3662,10 @@ async function emitHint(cmdline, errorText, helpSection) {
 // board where shots are laid out as the user flow (serpentine, action-labeled
 // arrows). Board slug defaults to the set key; re-running appends the newest
 // import below the existing content (server behavior).
-async function boardFromSetCmd(root, args) {
+// journey=true (the `journey-from-set` verb, or shots carrying --next
+// branches — the server auto-detects those) lays the flow out as a TREE:
+// signpost screens fan their branches, wires leave from the clicked element.
+async function boardFromSetCmd(root, args, journey = false) {
     if (!existsSync(vitrinkaCfgPath(root))) {
         console.error(`board-from-set: no ${vitrinkaCfgPath(root)} — run remote-init first`);
         process.exit(2);
@@ -3611,7 +3693,10 @@ async function boardFromSetCmd(root, args) {
     }
     const imp = await fetch(`${cfg.base}/api/v1/boards/${encodeURIComponent(slug)}/import-set`, {
         method: 'POST', headers,
-        body: JSON.stringify({ project: cfg.project, branch: cfg.slug, selector: cfg.key }),
+        body: JSON.stringify({
+            project: cfg.project, branch: cfg.slug, selector: cfg.key,
+            ...(journey ? { mode: 'journey' } : {}),
+        }),
         signal: AbortSignal.timeout(60_000),
     });
     if (!imp.ok) {
@@ -3619,6 +3704,11 @@ async function boardFromSetCmd(root, args) {
         process.exit(1);
     }
     const out = await imp.json();
+    // A declared path whose target label matched no shot — surface it loudly so
+    // the walker fixes the label (or captures the missing screen) and re-imports.
+    for (const u of out.unresolvedBranches || []) {
+        console.error(`⚠ branch dropped: ${u.from} → ${u.to} (no shot labeled ${JSON.stringify(u.to)} in this set)`);
+    }
     // Prefer the server-authoritative board url (carries /w/<workspace>); compose
     // the workspace-prefixed path only as a fallback for older servers.
     const ws = cfg.workspace ? `/w/${cfg.workspace}` : '';
@@ -3627,6 +3717,77 @@ async function boardFromSetCmd(root, args) {
     // The board is about to be annotated — make sure its autocomplete index is fresh.
     await pushProjectIndex(dirname(root), cfg.base, cfg.project);
 }
+// ---------- upload: files → board cards (mcp-file-upload 2026-07-15) ----------
+//
+// `vitrinka upload <files…> --board <slug>` streams local files to the board's
+// multipart /upload endpoint — PDFs land as live embedded document cards,
+// other files as download chips, images as media cards. Built for agents: the
+// bytes never pass through the model's context (the CLI reads disk), and
+// placement is INTENT — --section lands inside a journey frame, --anchor
+// [--side] docks beside a card, neither = server free placement (never 0,0).
+async function uploadCmd(rest, args) {
+    // Positionals = tokens that are neither flags nor a flag's consumed value.
+    const valueFlags = new Set(['--board', '--section', '--anchor', '--side', '--base', '--actor', '--root']);
+    const files = [];
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a.startsWith('--')) {
+            if (valueFlags.has(a))
+                i++; // skip its value
+            continue;
+        }
+        files.push(a);
+    }
+    const board = strArg(args.board);
+    if (!board || !files.length) {
+        console.error('usage: vitrinka upload <files…> --board <slug> [--section "Name"] [--anchor <cardId> --side right|below]');
+        process.exit(2);
+    }
+    const missing = files.filter((f) => !existsSync(f));
+    if (missing.length) {
+        console.error(`upload: no such file: ${missing.join(', ')}`);
+        process.exit(2);
+    }
+    const section = strArg(args.section);
+    const anchor = strArg(args.anchor);
+    const side = strArg(args.side);
+    if (section && anchor) {
+        console.error('upload: --section and --anchor are mutually exclusive');
+        process.exit(2);
+    }
+    const base = resolveBaseUrl(strArg(args.base));
+    const fd = new FormData();
+    for (const f of files) {
+        // openAsBlob is file-backed — fetch streams it, so a batch of 50 MiB
+        // PDFs never materializes in this process's memory.
+        fd.append('files', await openAsBlob(f), basename(f));
+        // The file's mtime is the chronological sort key layouts trust
+        // (sort-cols decisions #4) — same field the browser drop path sends.
+        fd.append('modified', String(Math.round(statSync(f).mtimeMs)));
+    }
+    if (section)
+        fd.append('section', section);
+    if (anchor)
+        fd.append('anchor', anchor);
+    if (side)
+        fd.append('side', side);
+    const headers = {};
+    const token = readToken();
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    const actor = actorFor(args);
+    if (actor)
+        headers['X-Board-Actor'] = actor;
+    const res = await fetch(`${base}/api/v1/boards/${encodeURIComponent(board)}/upload`, {
+        method: 'POST', headers, body: fd, signal: AbortSignal.timeout(300_000),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        console.error(`upload: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    console.log(text);
+}
 // announceLine renders the single stdout line for one work item:
 //   №<id> [<intent>] <board>: <prompt, single line, ≤100 chars>
 export function announceLine(it) {
@@ -3879,7 +4040,7 @@ async function runSub(argv) {
     const args = parseArgs(rest);
     const root = resolve(strArg(args.root) || '.screenshots');
     if (cmd === 'add')
-        addCmd(root, args);
+        addCmd(root, args, rest);
     else if (cmd === 'build') {
         const { count, htmlPath } = buildIndex(root);
         console.log(`built ${htmlPath} (${count} shots)`);
@@ -3911,9 +4072,13 @@ async function runSub(argv) {
     else if (cmd === 'status')
         await statusCmd(root, args);
     else if (cmd === 'snap')
-        await snapCmd(rest[0] && !rest[0].startsWith('--') ? rest[0] : '', args);
+        await snapCmd(rest[0] && !rest[0].startsWith('--') ? rest[0] : '', args, rest);
+    else if (cmd === 'upload')
+        await uploadCmd(rest, args);
     else if (cmd === 'board-from-set')
         await boardFromSetCmd(root, args);
+    else if (cmd === 'journey-from-set')
+        await boardFromSetCmd(root, args, true);
     else if (cmd === 'watch')
         await watchCmd(args);
     else if (cmd === 'index')