@lovinka/vitrinka 1.11.0 → 1.14.0

package/dist/cli.js

@@ -10,8 +10,8 @@
 // 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, openAsBlob, } from 'node:fs';
-import { join, resolve, basename, dirname, extname, relative, sep } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync, copyFileSync, mkdtempSync, chmodSync, appendFileSync, statSync, openSync, readSync, closeSync, realpathSync, openAsBlob, lstatSync, constants as fsConstants, } from 'node:fs';
+import { join, resolve, basename, dirname, extname, relative, sep, isAbsolute } from 'node:path';
 import { tmpdir, hostname } from 'node:os';
 import { spawnSync, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -21,6 +21,9 @@ import { readToken, tokenSource, tokenPath, tokenHelp } from "./lib/token.js";
 import { operatorPath, readOperator, actorHeaderValue } from "./lib/operator.js";
 import { resolveBaseUrl } from "./lib/base-url.js";
 const CLI_PATH = fileURLToPath(import.meta.url);
+// Cap on the gzipped tarball push streams to the server. spawnSync kills tar (SIGTERM,
+// empty stderr) if its stdout exceeds this, so pushCmd surfaces the size in its error.
+const TAR_MAX_BUFFER = 512 * 1024 * 1024;
 export function parseArgs(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -82,6 +85,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,21 +241,79 @@ 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);
     }
+    // --file is a manifest reference relative to root: it is stored verbatim, served as a
+    // relative img.src in index.html, and becomes the tar member name under `-C root` at push.
+    // An absolute or ../-escaping path therefore can't be referenced in place — push (which
+    // tars root only) would silently drop it → broken image on the board with no error.
+    // But /tmp captures and vault exports are a real workflow, so an out-of-root path that
+    // EXISTS is copied into root and the manifest stores the in-root copy. Only an
+    // out-of-root path with no bytes behind it is an error (nothing to copy, nothing to
+    // serve). In-root rel-paths keep the old contract: existence NOT required, shots are
+    // often added before the bytes land.
+    let fileStr = String(file);
+    const rootAbs = resolve(root);
+    const source = resolve(rootAbs, fileStr);
+    const relToRoot = relative(rootAbs, source);
+    const lexicallyOut = relToRoot === '' || relToRoot === '..' || relToRoot.startsWith(`..${sep}`) || isAbsolute(relToRoot);
+    // A symlink source must ALSO be materialized even when lexically in-root: push tars
+    // symlinks as symlink entries and the server ingest rejects those, so storing the link
+    // verbatim would defer the failure to push — exactly what this guard exists to prevent.
+    const sourceLst = lstatSync(source, { throwIfNoEntry: false });
+    if (lexicallyOut || sourceLst?.isSymbolicLink()) {
+        if (!sourceLst) {
+            console.error(`cli.ts add: --file ${fileStr} is outside root (${rootAbs}) and does not exist — an outside file must exist so it can be copied into root`);
+            process.exit(2);
+        }
+        // stat follows symlinks: directories, FIFOs, devices, and dangling symlinks all get
+        // the same actionable exit instead of a raw copyFileSync throw (EISDIR, hang on FIFO).
+        if (!statSync(source, { throwIfNoEntry: false })?.isFile()) {
+            console.error(`cli.ts add: --file ${fileStr} does not resolve to a regular file — only regular files can be stored in root`);
+            process.exit(2);
+        }
+        mkdirSync(rootAbs, { recursive: true });
+        if (!lexicallyOut) {
+            // In-root symlink: replace it in place with the target's bytes so the manifest
+            // name the caller chose stays valid and push ships a regular file.
+            const real = realpathSync(source);
+            rmSync(source);
+            copyFileSync(real, source, fsConstants.COPYFILE_EXCL);
+            console.log(`copied ${real} → ${source} (replaced symlink)`);
+        }
+        else {
+            // Basename collisions get a numeric suffix instead of clobbering an earlier shot.
+            // lstat, not existsSync: a dangling symlink at the destination must count as a
+            // collision, or copyFileSync would follow it and write outside root.
+            let name = basename(source);
+            for (let i = 2; lstatSync(join(rootAbs, name), { throwIfNoEntry: false }); i++) {
+                const ext = extname(basename(source));
+                name = `${basename(source, ext)}-${i}${ext}`;
+            }
+            // COPYFILE_EXCL: if a dirent races in between the lstat loop and the copy,
+            // fail loudly rather than follow it.
+            copyFileSync(source, join(rootAbs, name), fsConstants.COPYFILE_EXCL);
+            console.log(`copied ${source} → ${join(rootAbs, name)}`);
+            fileStr = name;
+        }
+    }
+    // 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),
+        file: fileStr,
         surface: args.surface && args.surface !== true ? String(args.surface) : 'other',
         route: args.route && args.route !== true ? String(args.route) : '',
         note: args.note && args.note !== true ? String(args.note) : '',
         // 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),
     };
@@ -861,11 +971,50 @@ function markOffline(root, error) {
     }
     writeFileSync(p, JSON.stringify({ ts: new Date().toISOString(), error, ...(warned ? { warned } : {}) }) + '\n');
 }
+// pushExcluded mirrors the tar --exclude basename patterns below, so the pre-tar
+// file-count guard sees exactly what would be packaged.
+function pushExcluded(name) {
+    return name.startsWith('.vitrinka') || name === '.active' || name.startsWith('._') || name === '.DS_Store';
+}
+// countPushFiles counts the files tar would include under root (excludes pruned,
+// dirs not counted). Used to catch a --root pointed at something far bigger than a
+// screenshot set before the expensive tar spawn.
+function countPushFiles(root) {
+    let count = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir: tar would report it; the guard just skips it
+        }
+        for (const e of entries) {
+            if (pushExcluded(e.name))
+                continue;
+            if (e.isDirectory())
+                walk(join(dir, e.name));
+            else
+                count++;
+        }
+    };
+    walk(root);
+    return count;
+}
+const PUSH_FILE_GUARD = 100;
 async function pushCmd(root, args) {
     if (!existsSync(vitrinkaCfgPath(root))) {
         console.error(`push: no ${vitrinkaCfgPath(root)} — run \`node ${CLI_PATH} remote-init --root ${root}\` first`);
         process.exit(2);
     }
+    // Guard BEFORE the expensive tar spawn: a --root accidentally pointed at a whole
+    // repo (node_modules and all) blows past tar's maxBuffer. --confirm overrides; it is
+    // intentionally undocumented (not in the push flags/help) — an escape hatch, not a workflow.
+    const fileCount = countPushFiles(root);
+    if (fileCount > PUSH_FILE_GUARD && args.confirm !== true) {
+        console.error(`push: ${fileCount} files under ${root} exceeds the ${PUSH_FILE_GUARD}-file guard — that is far more than a screenshot set. If --root really is your capture dir, re-run with --confirm; otherwise point --root at the right directory.`);
+        process.exit(2);
+    }
     const cfg = loadVitrinkaCfg(root);
     const projectDir = dirname(root);
     // Control files are excluded here AND skipped server-side (belt and suspenders).
@@ -876,9 +1025,24 @@ async function pushCmd(root, args) {
         '--exclude', '.active', '--exclude', './.active',
         '--exclude', '._*', '--exclude', './._*', '--exclude', '.DS_Store',
         '-C', root, '.',
-    ], { maxBuffer: 512 * 1024 * 1024, env: { ...process.env, COPYFILE_DISABLE: '1' } });
+    ], { maxBuffer: TAR_MAX_BUFFER, env: { ...process.env, COPYFILE_DISABLE: '1' } });
     if (tar.status !== 0) {
-        console.error(`push: tar failed: ${String(tar.stderr)}`);
+        // When spawnSync kills tar for exceeding maxBuffer, the reason is on tar.error/tar.signal
+        // and tar.stderr is an empty Buffer — so the old `String(tar.stderr)` printed a blank line.
+        // Surface every diagnostic field so a maxBuffer kill (or any other failure) is legible.
+        const stderr = tar.stderr ? String(tar.stderr).trim() : '';
+        const stdoutBytes = tar.stdout ? tar.stdout.length : 0;
+        const parts = [
+            stderr && `stderr: ${stderr}`,
+            tar.error && `error: ${tar.error.message}`,
+            `status: ${tar.status}`,
+            tar.signal && `signal: ${tar.signal}`,
+            `stdout: ${stdoutBytes} bytes (maxBuffer ${TAR_MAX_BUFFER})`,
+        ].filter(Boolean);
+        console.error(`push: tar failed — ${parts.join(', ')}`);
+        if (stdoutBytes >= TAR_MAX_BUFFER || tar.error?.code === 'ENOBUFS') {
+            console.error(`push: the tarball exceeded the ${Math.round(TAR_MAX_BUFFER / (1024 * 1024))} MB buffer — check that --root (${root}) points at your capture dir, not a whole repo`);
+        }
         process.exit(1);
     }
     const commit = git(['rev-parse', '--short', 'HEAD'], projectDir);
@@ -1300,10 +1464,12 @@ function pluginRuntimes() {
         }
     }
     out.push({ name: 'claude', present: claudePresent, installed: claudeInstalled });
-    const codexPresent = !spawnSync('codex', ['--version'], { stdio: 'ignore' }).error;
+    const codexPresent = !spawnSync('codex', ['--version'], { stdio: 'ignore', timeout: 3_000 }).error;
     let codexInstalled = false;
     if (codexPresent) {
-        const r = spawnSync('codex', ['plugin', 'list'], { encoding: 'utf8' });
+        // Already fast in practice (~200ms); timeout is belt-and-suspenders so a
+        // hung codex child cannot freeze doctor the way `claude mcp list` did.
+        const r = spawnSync('codex', ['plugin', 'list'], { encoding: 'utf8', timeout: 5_000 });
         codexInstalled = r.status === 0 && /\bvitrinka\b/.test(r.stdout || '');
     }
     out.push({ name: 'codex', present: codexPresent, installed: codexInstalled });
@@ -1346,12 +1512,55 @@ function rcPathOf(home) {
 // every /mcp request, so registration without a token is refused with the
 // token help. X-Board-Actor rides along when an operator persona exists
 // (UTF-8 bytes latin-1-encoded — header values are ByteStrings).
+//
+// mcpRegistered MUST stay O(1)/fast: doctor and install status call it on every
+// run. Never shell out to `claude mcp list` — that health-checks EVERY approved
+// MCP server (measured ~60s with ~13 servers; one flaky server can hang longer).
+// Prefer reading Claude Code's config file; fall back to `claude mcp get
+// vitrinka` (health-checks only that one server, ~1s) with a hard timeout.
 function claudeCliPresent() {
-    return !spawnSync('claude', ['--version'], { stdio: 'ignore' }).error;
+    return !spawnSync('claude', ['--version'], { stdio: 'ignore', timeout: 3_000 }).error;
+}
+function mcpRegisteredFromClaudeConfig() {
+    const home = process.env.HOME || '';
+    if (!home)
+        return null;
+    const cfgPath = join(home, '.claude.json');
+    if (!existsSync(cfgPath))
+        return null;
+    try {
+        const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
+        if (cfg.mcpServers && Object.prototype.hasOwnProperty.call(cfg.mcpServers, 'vitrinka')) {
+            return true;
+        }
+        // Project-scoped registrations (less common for our remote HTTP install,
+        // which uses --scope user) — accept any project that names vitrinka.
+        for (const proj of Object.values(cfg.projects || {})) {
+            if (proj?.mcpServers && Object.prototype.hasOwnProperty.call(proj.mcpServers, 'vitrinka')) {
+                return true;
+            }
+        }
+        // Config readable and no vitrinka entry anywhere → definitive no (skip the
+        // slower get-fallback). A missing file / parse error returns null instead.
+        return false;
+    }
+    catch {
+        return null;
+    }
 }
 function mcpRegistered() {
-    const r = spawnSync('claude', ['mcp', 'list'], { encoding: 'utf8' });
-    return r.status === 0 && /\bvitrinka\b/.test(r.stdout);
+    const fromCfg = mcpRegisteredFromClaudeConfig();
+    if (fromCfg !== null)
+        return fromCfg;
+    // Schema unknown / unreadable config — single-server probe (not fleet list).
+    const r = spawnSync('claude', ['mcp', 'get', 'vitrinka'], {
+        encoding: 'utf8',
+        timeout: 5_000,
+    });
+    if (r.error || r.status !== 0)
+        return false;
+    // "get" prints the server block when registered; otherwise errors / no match.
+    return /\bvitrinka\b/i.test((r.stdout || '') + (r.stderr || ''));
 }
 function mcpTarget() {
     const args = ['--transport', 'http', 'vitrinka', `${resolveBaseUrl()}/mcp`];
@@ -2452,7 +2661,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 +2816,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 +2826,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 +3139,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' },
@@ -3063,6 +3278,32 @@ export const COMMANDS = [
         examples: ['vitrinka upload report.pdf --board pr-105-vitrinka --section "Evidence"',
             'vitrinka upload spec.docx shots/*.png --board payout-flow'],
     },
+    {
+        name: 'import', summary: 'Parse a source file (OpenAPI / SQL DDL / docker-compose) into a refreshable diagram card',
+        usage: '<file> --board <slug> [--kind auto|openapi|sqlddl|compose] [--title "…"] [--section "Name"] [--rev <sha>] [--actor <name>] [--base <url>]',
+        positional: '<file>',
+        flags: [{ f: '--board', arg: '<slug>', d: 'target board (required)' },
+            { f: '--kind', arg: '<auto|openapi|sqlddl|compose>', d: 'source kind (default: auto-detect from name/content)' },
+            { f: '--title', arg: '<t>', d: 'diagram title (default: derived from the source)' },
+            { f: '--section', arg: '<name>', d: 'land inside the named section frame (docs boards: Architecture/Database/API/Pages)' },
+            { f: '--rev', arg: '<sha>', d: 'source revision (git SHA) stamped on the ↻ label' },
+            { f: '--actor', arg: '<name>', d: 'override the operator attribution' }, BASE_FLAG],
+        dynamic: 'boards',
+        examples: ['vitrinka import openapi.yaml --board arch-docs',
+            'vitrinka import schema.sql --board myapp-docs --section Database --rev $(git rev-parse --short HEAD)',
+            'vitrinka import docker-compose.yml --board infra'],
+    },
+    {
+        name: 'schema', summary: 'Introspect a live Postgres LOCALLY (psql) and push its schema as a refreshable diagram — the connection string never leaves the machine',
+        usage: 'push --db <postgres-url> --board <slug> [--title "…"] [--actor <name>] [--base <url>]',
+        positional: 'push',
+        flags: [{ f: '--db', arg: '<postgres-url>', d: 'connection string, passed to local psql (required)' },
+            { f: '--board', arg: '<slug>', d: 'target board (required)' },
+            { f: '--title', arg: '<t>', d: 'diagram title (default: derived from the database name)' },
+            { f: '--actor', arg: '<name>', d: 'override the operator attribution' }, BASE_FLAG],
+        dynamic: 'boards',
+        examples: ['vitrinka schema push --db postgres://localhost/shop --board db-docs'],
+    },
     {
         name: 'board-from-set', summary: 'Turn the set into an annotation flow board',
         usage: '[--root <dir>] [--slug <board>] [--btitle <t>] [--actor <name>]',
@@ -3071,6 +3312,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>]',
@@ -3595,7 +3844,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);
@@ -3623,7 +3875,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) {
@@ -3631,6 +3886,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}` : '';
@@ -3710,6 +3970,192 @@ async function uploadCmd(rest, args) {
     }
     console.log(text);
 }
+// ---------- import / schema push: refreshable diagram sources ----------
+//
+// `vitrinka import <file>` parses a real source (OpenAPI / SQL DDL /
+// docker-compose) SERVER-SIDE into a living diagram card; `vitrinka schema
+// push` introspects a live Postgres LOCALLY (the connection string never
+// leaves the machine) and posts only the parsed schema JSON. Both land on
+// POST /api/v1/boards/{slug}/import, which stamps payload.source so the card
+// refreshes in place as the source evolves.
+// detectImportKind picks the importer kind from an explicit flag, the file
+// name, then a content sniff. Returns "" when it can't decide.
+export function detectImportKind(explicit, file, content) {
+    if (explicit && explicit !== 'auto')
+        return explicit;
+    const base = basename(file).toLowerCase();
+    const ext = extname(base);
+    if (/(^|[.-])(docker-)?compose\.ya?ml$/.test(base))
+        return 'compose';
+    if (ext === '.sql')
+        return 'sqlddl';
+    const head = content.slice(0, 4000);
+    if (/^\s*services\s*:/m.test(head))
+        return 'compose';
+    if (/["']?(openapi|swagger)["']?\s*:/.test(head) || /^\s*(openapi|swagger)\s*:/m.test(head))
+        return 'openapi';
+    if (/create\s+table/i.test(head))
+        return 'sqlddl';
+    if (/["']?paths["']?\s*:/.test(head))
+        return 'openapi';
+    if (ext === '.json' || ext === '.yaml' || ext === '.yml')
+        return 'openapi';
+    return '';
+}
+// postImport sends a raw source to the board import endpoint and prints the card.
+async function postImport(board, body, args) {
+    const base = resolveBaseUrl(strArg(args.base));
+    const headers = { 'Content-Type': 'application/json' };
+    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)}/import`, {
+        method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(120_000),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        console.error(`import: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    console.log(text);
+}
+async function importCmd(rest, args) {
+    const file = rest.find((a) => !a.startsWith('--'));
+    const board = strArg(args.board);
+    if (!file || !board) {
+        console.error('usage: vitrinka import <file> --board <slug> [--kind auto|openapi|sqlddl|compose] [--title "…"]');
+        process.exit(2);
+    }
+    if (!existsSync(file)) {
+        console.error(`import: no such file: ${file}`);
+        process.exit(2);
+    }
+    const source = readFileSync(file, 'utf8');
+    const kind = detectImportKind(strArg(args.kind), file, source);
+    if (!kind) {
+        console.error(`import: could not detect the source kind of ${basename(file)} — pass --kind openapi|sqlddl|compose`);
+        process.exit(2);
+    }
+    const body = { kind, source, ref: basename(file) };
+    const title = strArg(args.title);
+    if (title)
+        body.title = title;
+    // Placement + provenance passthrough (docs-boards decisions #2/#6): --section
+    // lands inside a scaffold frame (Architecture/Database/API/Pages on docs
+    // boards); --rev stamps the source revision (git SHA) for the ↻ micro-label.
+    const section = strArg(args.section);
+    if (section)
+        body.section = section;
+    const rev = strArg(args.rev);
+    if (rev)
+        body.rev = rev;
+    await postImport(board, body, args);
+}
+// PG_INTROSPECT_SQL emits the pgschema JSON document (one row) from
+// information_schema — tables, columns (type/nullable/pk/unique) and single-
+// column foreign keys. Shelled to `psql`; the connection string stays local.
+const PG_INTROSPECT_SQL = `
+WITH cols AS (
+  SELECT table_schema, table_name, column_name, data_type, ordinal_position,
+         (is_nullable = 'YES') AS nullable
+  FROM information_schema.columns
+  WHERE table_schema NOT IN ('pg_catalog','information_schema')
+),
+pk AS (
+  SELECT tc.table_schema, tc.table_name, kcu.column_name
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+  WHERE tc.constraint_type = 'PRIMARY KEY'
+),
+uq AS (
+  SELECT tc.table_schema, tc.table_name, kcu.column_name
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+  WHERE tc.constraint_type = 'UNIQUE'
+),
+fk AS (
+  SELECT tc.table_schema, tc.table_name, kcu.column_name,
+         ccu.table_schema AS ref_schema, ccu.table_name AS ref_table, ccu.column_name AS ref_column
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+  JOIN information_schema.constraint_column_usage ccu
+    ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
+  WHERE tc.constraint_type = 'FOREIGN KEY'
+),
+tabs AS (
+  SELECT table_schema, table_name FROM information_schema.tables
+  WHERE table_type = 'BASE TABLE' AND table_schema NOT IN ('pg_catalog','information_schema')
+)
+SELECT json_build_object(
+  'database', current_database(),
+  'tables', COALESCE(json_agg(json_build_object(
+    'schema', t.table_schema, 'name', t.table_name,
+    'columns', (SELECT COALESCE(json_agg(json_build_object(
+        'name', c.column_name, 'type', c.data_type, 'nullable', c.nullable,
+        'pk', EXISTS(SELECT 1 FROM pk WHERE pk.table_schema=c.table_schema AND pk.table_name=c.table_name AND pk.column_name=c.column_name),
+        'unique', EXISTS(SELECT 1 FROM uq WHERE uq.table_schema=c.table_schema AND uq.table_name=c.table_name AND uq.column_name=c.column_name)
+      ) ORDER BY c.ordinal_position), '[]'::json)
+      FROM cols c WHERE c.table_schema=t.table_schema AND c.table_name=t.table_name),
+    'foreignKeys', (SELECT COALESCE(json_agg(json_build_object(
+        'column', f.column_name, 'refSchema', f.ref_schema, 'refTable', f.ref_table, 'refColumn', f.ref_column
+      )), '[]'::json)
+      FROM fk f WHERE f.table_schema=t.table_schema AND f.table_name=t.table_name)
+  ) ORDER BY t.table_schema, t.table_name), '[]'::json)
+) FROM tabs t;
+`;
+async function schemaCmd(rest, args) {
+    const sub = rest.find((a) => !a.startsWith('--'));
+    if (sub !== 'push') {
+        console.error('usage: vitrinka schema push --db <postgres-url> --board <slug> [--title "…"]');
+        process.exit(2);
+    }
+    const db = strArg(args.db);
+    const board = strArg(args.board);
+    if (!db || !board) {
+        console.error('usage: vitrinka schema push --db <postgres-url> --board <slug> [--title "…"]');
+        process.exit(2);
+    }
+    // Introspect LOCALLY via psql; the connection string never leaves the machine.
+    const run = spawnSync('psql', [db, '-X', '-A', '-t', '-c', PG_INTROSPECT_SQL], {
+        encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+    });
+    if (run.error && run.error.code === 'ENOENT') {
+        console.error('schema push: `psql` not found on PATH — install the PostgreSQL client (the introspection runs locally; only the parsed schema is uploaded)');
+        process.exit(1);
+    }
+    if (run.status !== 0) {
+        console.error(`schema push: psql failed:\n${(run.stderr || '').trim()}`);
+        process.exit(1);
+    }
+    const schemaJSON = (run.stdout || '').trim();
+    if (!schemaJSON) {
+        console.error('schema push: psql returned no schema (empty database, or the connection string is wrong)');
+        process.exit(1);
+    }
+    const body = { kind: 'pgschema', source: schemaJSON, ref: pgRefLabel(db) };
+    const title = strArg(args.title);
+    if (title)
+        body.title = title;
+    await postImport(board, body, args);
+}
+// pgRefLabel derives a non-secret "host/db" label from a connection string for
+// payload.source.ref — never the credentials.
+export function pgRefLabel(db) {
+    try {
+        const u = new URL(db);
+        const name = u.pathname.replace(/^\//, '') || 'postgres';
+        return `${u.hostname || 'localhost'}/${name}`;
+    }
+    catch {
+        return 'postgres';
+    }
+}
 // announceLine renders the single stdout line for one work item:
 //   №<id> [<intent>] <board>: <prompt, single line, ≤100 chars>
 export function announceLine(it) {
@@ -3962,7 +4408,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)`);
@@ -3994,11 +4440,17 @@ 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 === 'import')
+        await importCmd(rest, args);
+    else if (cmd === 'schema')
+        await schemaCmd(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')