beehaven 0.8.16

package/dist/commands/slides.js

@@ -0,0 +1,418 @@
+/**
+ * `beehaven slides` — presentations.
+ *
+ * ⚠⚠ SEVENTEEN `deck-*` ACTIONS AND NO CLI DOOR. Same shape as `sheet`: a first-class artifact
+ * — a deck is a document row, with a key, project filing, trash and search like anything else —
+ * reachable only as `beehaven call deck-add-slide '{…}'`. Thirteen of the seventeen also had no
+ * input schema until 2026-09-05, so the arguments could only be learned by reading the handler.
+ *
+ * ⚠ THE TRAPS THIS MAKES UNTYPEABLE:
+ *
+ *   · `deck-move-slide` REQUIRES `to` and refuses without it (`code: "no-target"`) — not something
+ *     the verb name suggests. This verb takes it positionally, so it cannot be forgotten.
+ *   · `deck-render` vs `deck-export` are near-synonyms that do different jobs: render is to LOOK
+ *     at a deck, export is to take the FILE out. Two subcommands, `show` and `export`, named for
+ *     the job rather than the mechanism.
+ *   · A layout typed from memory does not error — an unrecognised one silently falls back to
+ *     `titleBody`. `slides layouts` is one call and is named in the refusal.
+ *
+ * ⚠ `agentRpc`, NEVER bare `rpcOnce` — see the note in `ticket.ts`.
+ */
+import { agentRpc as rpcOnce } from './workspace.js';
+/** Only `pptx` returns a `filename`; the text formats return bare `content`. Falling back to
+ *  `${id}.${format}` wrote `PLA-3518.markdown` — an id nobody recognises and an extension no
+ *  editor associates. Fall back to the deck's TITLE and a real extension. */
+export const DECK_EXPORT_EXT = {
+    markdown: 'md', notes: 'txt', html: 'html', svg: 'svg', pptx: 'pptx',
+    // `slides show`'s formats. `png` is the only one that arrives as a data: URI.
+    png: 'png', tsv: 'tsv',
+};
+/** Extension for a `data:` URI's mime type. `image/svg+xml` → `svg`, not `svg+xml`. */
+export const DATA_URI_EXT = {
+    'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/svg+xml': 'svg',
+    'application/pdf': 'pdf',
+};
+/**
+ * ⚠⚠ THE EXPORT DECISION, EXTRACTED SO A GUARD CAN EXECUTE IT (CBH2-42).
+ *
+ * This logic used to live inline in the `export` branch, which made it unreachable from a test —
+ * so its guard (`slides-export-writes.test.ts`) could only read the file as TEXT and assert that
+ * identifiers like `writeFileSync` appeared somewhere in it. That guard called itself behavioural
+ * and was not: every string it matched also survives in a COMMENT, so the fix could be deleted and
+ * the suite stayed green. Extraction IS the fix to that criticism, not a tidy-up — the same move
+ * that rescued `clipToRange` in `sheet-rpcs.ts`.
+ *
+ * Everything here is a DECISION; the caller does the IO (two `writeFileSync`, one `console.log`).
+ * `exists` and `resolvePath` are INJECTED rather than imported, so the clobber refusal and the
+ * filename derivation can both be exercised without touching a real filesystem or a real cwd.
+ *
+ * ⚠ BASE64 vs TEXT IS DECIDED BY WHICH FIELD CAME BACK, never by the format name. Keying on
+ * `format === 'pptx'` breaks the day another binary format is added, and writing a base64 STRING
+ * into a .pptx produces a file that opens as garbage rather than failing loudly.
+ *
+ * Sabotage-tested (2026-09-05): removing the clobber refusal fails 1, keying on the format name
+ * fails 3, and falling back to `id.format` fails 2.
+ *
+ * ⚠⚠ THREE VERBS SHARE IT NOW (CBH2-85): `slides export`, `slides show` and `sheet get`. `--out`
+ * and `-o` are registered GLOBALLY in `parseArgs`, so EVERY verb accepts them — acceptance has
+ * never been evidence of support, and those two rendered/printed and wrote no file. The clobber
+ * refusal and the extension fallback are both non-obvious and already tested; a second and third
+ * copy of them is how one caller keeps refusing to overwrite while another silently does.
+ *
+ * ⚠ IT IS SHAPED BY THE PAYLOAD, NOT BY THE VERB, which is what lets a sheet reuse it: hand it
+ * `{ content, filename }` and it plans one text file, the same way `deck-export`'s markdown does.
+ * The name stays `planDeckExport` — renaming it would churn every guard that names it for no gain.
+ *
+ * ⚠⚠ A `data:` URI IS BINARY AND MUST BE DECODED. `deck-render { format: 'png' }` answers with
+ * `slides: ['data:image/png;base64,…']`, and writing those STRINGS to `.png` files produces images
+ * that open as garbage — exactly the failure the base64-vs-text rule above exists to prevent, one
+ * payload shape further out. The extension follows the URI's own mime type rather than the
+ * requested format, so a fallback to SVG (which `deck-render` does silently when rasterising
+ * fails) lands in a file named `.svg`, not a `.png` containing SVG.
+ */
+export function planDeckExport(res, opts, exists, resolvePath) {
+    const fmt = String(opts.format ?? 'pptx');
+    const ext = DECK_EXPORT_EXT[fmt] ?? fmt;
+    const name = String(res?.filename || `${res?.title || opts.id}.${ext}`);
+    /**
+     * ⚠⚠ `svg` IS A THIRD PAYLOAD SHAPE — `slides: [...]`, one entry per slide, with NO `base64`
+     * and NO `content`. Measured on a 12-slide deck. The first cut of this verb knew only the two
+     * shapes, so `--format svg` refused with "neither base64 nor content" on a format the help
+     * offers. **A deck of N slides is N SVGs** — there is no single-file form to fall back to, so
+     * `--out` names the BASE and the slides land beside it as `<base>-1.svg` … `<base>-N.svg`.
+     */
+    const slides = Array.isArray(res?.slides) ? res.slides : [];
+    if (slides.length) {
+        /**
+         * ⚠ ANY KNOWN EXTENSION IS STRIPPED, NOT ONLY THE ONE THIS RUN EMITS. `slides show --out
+         * shot.png` whose render DEGRADES to SVG would otherwise write `shot.png-1.svg` — a name
+         * carrying two extensions, the first of which is wrong. Only extensions this CLI itself emits
+         * are stripped, so `My.Deck.Name` keeps its dots.
+         */
+        const known = new Set([...Object.values(DECK_EXPORT_EXT), ...Object.values(DATA_URI_EXT)]);
+        const base = String(opts.out ?? name).replace(/\.([A-Za-z0-9]+)$/, (m, e) => (known.has(String(e).toLowerCase()) ? '' : m));
+        const files = slides.map((s, i) => {
+            const body = typeof s === 'string' ? s : String(s?.svg ?? s?.content ?? '');
+            // ⚠ See the header: a `data:` URI carries BINARY, and its own mime names the extension.
+            const uri = /^data:([\w.+-]+\/[\w.+-]+);base64,(.*)$/s.exec(body);
+            if (uri) {
+                const mimeExt = DATA_URI_EXT[uri[1]] ?? uri[1].split('/')[1] ?? ext;
+                return {
+                    dest: resolvePath(`${base}-${i + 1}.${mimeExt}`),
+                    body: { kind: 'binary', base64: uri[2] },
+                };
+            }
+            return { dest: resolvePath(`${base}-${i + 1}.${ext}`), body: { kind: 'text', content: body } };
+        });
+        const clash = opts.force ? null : files.find((f) => exists(f.dest));
+        if (clash) {
+            return { ok: false, code: 'exists', error: `${clash.dest} already exists`,
+                hint: `This export writes ${files.length} files. Pass --force to overwrite, or --out <base> to write elsewhere.` };
+        }
+        return { ok: true, files };
+    }
+    const dest = resolvePath(String(opts.out ?? name));
+    // ⚠ An export is a READ. Silently overwriting a neighbouring file is not something a read
+    //   should be able to do; `--force` is the opt-in.
+    if (exists(dest) && !opts.force) {
+        return { ok: false, code: 'exists', error: `${dest} already exists`,
+            hint: 'Pass --force to overwrite, or --out <path> to write elsewhere.' };
+    }
+    if (typeof res?.base64 === 'string' && res.base64) {
+        return { ok: true, files: [{ dest, body: { kind: 'binary', base64: res.base64 } }] };
+    }
+    if (typeof res?.content === 'string') {
+        return { ok: true, files: [{ dest, body: { kind: 'text', content: res.content } }] };
+    }
+    // ⚠ Say what came back rather than writing an empty file that looks like a successful export.
+    return { ok: false, code: 'no-payload',
+        error: 'the export returned neither `base64`, `content` nor `slides` — nothing to write',
+        hint: `Keys returned: ${Object.keys(res ?? {}).join(', ')}` };
+}
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+function getTimeout(values) {
+    const t = Number(values?.timeout);
+    return Number.isFinite(t) && t > 0 ? t : 30_000;
+}
+function failure(res) {
+    if (!res || typeof res !== 'object')
+        return null;
+    if (typeof res.error === 'string' && res.error)
+        return res.error;
+    if (res.ok === false)
+        return String(res.message ?? res.code ?? 'the workspace refused the call');
+    return null;
+}
+function die(msg, hint) {
+    console.error(`  ${msg}`);
+    if (hint)
+        console.error(c.dim(`  ${hint}`));
+    process.exit(1);
+}
+export async function cmdSlides(sub, rest, values) {
+    const t = getTimeout(values);
+    if (!sub || sub === 'help') {
+        console.log(`
+  ${c.cyan('beehaven slides')} — presentations
+
+    slides list                 Every deck, newest first
+    slides new "<title>"        Create one  (--project <id>, --aspect 16:9|4:3)
+    slides get <id>             The outline  (--slide N for one slide in full)
+    slides add <id> "<title>"   Append a slide  (--layout, --bullets "a|b|c", --notes, --at N)
+    slides move <id> <n> <to>   Reorder — <to> is the 1-based destination
+    slides rm <id> <n>          Delete a slide
+    slides layouts              The layout ids you may pass to --layout
+    slides show <id>            Render it to look at  (--slide N)
+    slides export <id>          Take the file out  (--format pptx|html|markdown|notes|svg)
+
+  ${c.dim('<id> is a deck id or its key. <n> is a 1-based slide number or a slide id.')}
+  ${c.dim('show renders a picture; export produces a file. They are not the same verb.')}
+`);
+        return;
+    }
+    if (sub === 'list') {
+        const res = await rpcOnce('deck-list', {}, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const rows = res?.decks ?? [];
+        if (!rows.length) {
+            console.log('  No decks.');
+            return;
+        }
+        console.log('');
+        for (const d of rows) {
+            const n = d.slideCount ?? d.slides?.length;
+            console.log(`  ${c.cyan(String(d.key ?? d.id ?? ''))}  ${String(d.title ?? 'Untitled')}${n != null ? c.dim(`  · ${n} slides`) : ''}`);
+        }
+        console.log('');
+        return;
+    }
+    if (sub === 'new' || sub === 'create') {
+        const title = rest.join(' ').trim();
+        if (!title)
+            die('a title is required', 'beehaven slides new "Q1 review"');
+        const res = await rpcOnce('deck-create', {
+            title,
+            ...(values.aspect ? { aspect: String(values.aspect) } : {}),
+            ...(values.project ? { projectId: String(values.project) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Created ${c.cyan(String(res?.key ?? res?.id ?? ''))}`);
+        console.log(c.dim('  Add slides:  beehaven slides add <id> "<title>" --bullets "a|b|c"'));
+        return;
+    }
+    if (sub === 'get') {
+        const id = rest[0];
+        if (!id)
+            die('a deck id or key is required', 'beehaven slides get CLR-42');
+        const res = await rpcOnce('deck-get', {
+            id,
+            ...(values.slide ? { slide: Number(values.slide) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const outline = res?.outline ?? [];
+        if (!outline.length) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log('');
+        outline.forEach((s, i) => console.log(`  ${String(i + 1).padStart(2)}. ${String(s.title ?? s.layout ?? '')}`));
+        console.log('');
+        return;
+    }
+    if (sub === 'add') {
+        const [id, ...titleParts] = rest;
+        if (!id)
+            die('a deck id or key is required', 'beehaven slides add CLR-42 "Results"');
+        const res = await rpcOnce('deck-add-slide', {
+            id,
+            ...(titleParts.length ? { title: titleParts.join(' ') } : {}),
+            ...(values.layout ? { layout: String(values.layout) } : {}),
+            // ⚠ PIPE-SEPARATED, not comma — a bullet routinely contains a comma and almost never a pipe.
+            ...(values.bullets ? { bullets: String(values.bullets).split('|').map((b) => b.trim()).filter(Boolean) } : {}),
+            ...(values.notes ? { notes: String(values.notes) } : {}),
+            ...(values.at ? { at: Number(values.at) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Added slide to ${c.cyan(id)}`);
+        return;
+    }
+    if (sub === 'move') {
+        const [id, slide, to] = rest;
+        // ⚠ `to` POSITIONALLY, because the action refuses without it and the verb name gives no hint.
+        if (!id || !slide || !to) {
+            die('usage: beehaven slides move <id> <n> <to>', 'e.g. beehaven slides move CLR-42 5 2   — <to> is the 1-based destination and is required.');
+        }
+        const res = await rpcOnce('deck-move-slide', { id, slide, to: Number(to) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Moved slide ${slide} → ${to} in ${c.cyan(id)}`);
+        return;
+    }
+    if (sub === 'rm' || sub === 'delete') {
+        const [id, slide] = rest;
+        if (!id || !slide)
+            die('usage: beehaven slides rm <id> <n>');
+        const res = await rpcOnce('deck-delete-slide', { id, slide }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        // ⚠ The action returns the slide it removed precisely so this can say WHAT went.
+        const gone = res?.removed?.title;
+        console.log(`  Removed slide ${slide}${gone ? ` — ${c.dim(String(gone))}` : ''} from ${c.cyan(id)}`);
+        return;
+    }
+    if (sub === 'layouts') {
+        const res = await rpcOnce('deck-layouts', {}, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log('');
+        for (const l of (res?.layouts ?? []))
+            console.log(`  ${c.cyan(String(l.id))}  ${c.dim(String(l.label ?? ''))}`);
+        console.log('');
+        return;
+    }
+    if (sub === 'show' || sub === 'render') {
+        const id = rest[0];
+        if (!id)
+            die('a deck id or key is required');
+        const res = await rpcOnce('deck-render', {
+            id,
+            ...(values.slide ? { slide: Number(values.slide) } : {}),
+            ...(values.format ? { format: String(values.format) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        /**
+         * ⚠⚠ IT ACCEPTED `--out` AND WROTE NOTHING (CBH2-85) — `--out`/`-o` are registered globally in
+         * `parseArgs`, so this verb took the flag, ignored it, and printed a JSON envelope holding
+         * megabytes of base64 PNG to the terminal. Same accept-and-ignore class as `slides export`
+         * before CBH2-2, and the same fix: `planDeckExport` owns the decision, this branch does IO.
+         *
+         * ⚠ THE FLAG IS THE OPT-IN. Without it the behaviour is byte-identical to before — a render is
+         * usually looked at, not saved, and writing files from a read verb by default is a surprise.
+         */
+        const outPath = (values.out ?? values.output);
+        if (!outPath) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const { writeFileSync, existsSync } = await import('fs');
+        const { resolve } = await import('path');
+        const plan = planDeckExport(res, 
+        // ⚠ THE SERVER'S OWN `format`, NOT THE REQUESTED ONE. `deck-render` falls back to SVG when
+        //   rasterising fails (`degraded`), so trusting `--format png` would name a `.png` holding SVG.
+        { format: String(res?.format ?? values.format ?? 'svg'), out: outPath, id, force: !!values.force }, existsSync, resolve);
+        if (!plan.ok)
+            die(plan.error, plan.hint);
+        if (res?.degraded)
+            console.log(`  ${c.dim(`⚠ ${String(res.degraded)}`)}`);
+        for (const file of plan.files) {
+            const buf = file.body.kind === 'binary'
+                ? Buffer.from(file.body.base64, 'base64')
+                : Buffer.from(file.body.content, 'utf8');
+            writeFileSync(file.dest, buf);
+            console.log(`  Wrote ${c.cyan(file.dest)}${c.dim(`  · ${buf.length} bytes`)}`);
+        }
+        return;
+    }
+    if (sub === 'export') {
+        const id = rest[0];
+        if (!id)
+            die('a deck id or key is required');
+        const res = await rpcOnce('deck-export', {
+            id,
+            format: String(values.format ?? 'pptx'),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        /**
+         * ⚠⚠ WRITE THE FILE. THIS PRINTED THE PAYLOAD TO STDOUT (fixed 2026-09-05, CBH2-2).
+         *
+         * The help I wrote for this verb says export "produces a FILE to take away", and it produced
+         * no file anywhere — it dumped the envelope to stdout, which for the DEFAULT format (pptx)
+         * is 16.5 KB of base64 into the terminal. `--out` and `-o` are registered globally in
+         * `parseArgs`, so they were accepted and silently ignored: the exact accept-and-ignore class
+         * this sprint keeps finding, in a verb written during the sprint.
+         *
+         * ⚠ THE ACTION ALREADY HAD EVERYTHING NEEDED — it returns `filename` and either `base64`
+         * (pptx) or `content` (text formats). Nothing had to be added server-side; the verb simply
+         * never used them.
+         *
+         * ⚠ BASE64 vs TEXT IS DECIDED BY WHICH FIELD CAME BACK, not by the format name. Keying on
+         * `format === 'pptx'` would break the day another binary format is added, and writing a
+         * base64 STRING to a .pptx produces a file that opens as garbage rather than failing.
+         *
+         * ⚠ REFUSES TO CLOBBER. An export is a read; silently overwriting a neighbouring file is not
+         * something a read should be able to do. `--force` is the opt-in.
+         */
+        const { writeFileSync, existsSync } = await import('fs');
+        const { resolve } = await import('path');
+        // ⚠ The DECISION is `planDeckExport` (pure, executed by the guard); this branch does only IO.
+        const plan = planDeckExport(res, { format: String(values.format ?? 'pptx'), out: (values.out ?? values.output), id, force: !!values.force }, existsSync, resolve);
+        if (!plan.ok)
+            die(plan.error, plan.hint);
+        /**
+         * ⚠ THE SIZE IS MEASURED HERE, NOT TAKEN FROM THE SERVER. `deck-export` reports `bytes` as a
+         * CHARACTER count: a 3,993-character markdown deck is 4,046 bytes on disk once the em-dashes
+         * and ⚠ glyphs are UTF-8 encoded, and the CLI printed the server's 3,993 beside a file that
+         * `ls` calls 4,046. Small, and exactly the class this sprint is about — a number that looks
+         * like an answer to a question nobody asked it.
+         */
+        for (const f of plan.files) {
+            const buf = f.body.kind === 'binary'
+                ? Buffer.from(f.body.base64, 'base64')
+                : Buffer.from(f.body.content, 'utf8');
+            writeFileSync(f.dest, buf);
+            console.log(`  Wrote ${c.cyan(f.dest)}${c.dim(`  · ${buf.length} bytes`)}`);
+        }
+        return;
+    }
+    die(`unknown subcommand "${sub}"`, 'beehaven slides help');
+}