@hypersocial/decks-cli 0.9.1 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",

package/skills/hyperdecks/SKILL.md

@@ -143,6 +143,7 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | Watch a draft with its real face | `hyperdecks play decks/<slug>` | the `previewUrl` from `get_deck_source` |
 | Ship | `hyperdecks release decks/<slug> --to "<name>" --email <e>` | `release_deck` |
 | Share-link poster | `hyperdecks poster <slug>` | `generate_deck_poster` |
+| PDF for a data room or attachment | `hyperdecks export <slug> --pdf [--notes] --out deck.pdf`, `hyperdecks export list` | `export_deck`, `list_exports` |
 | Import only | `hyperdecks import <file> --slug <slug>` | `import_deck_from_url` |
 | One more link | `hyperdecks share new <slug> "<name>" [--no-forward]` | `create_share` (`allowForward`) |
 | Forwarding, one link | `hyperdecks share forward on\|off\|default <token>` | `set_share_forwarding` |
@@ -611,8 +612,13 @@ still.
   `voice clone` (it asks them for consent; never clone anyone else's voice).
 - Names speech-to-text spells another way fail narrate's transcript check
   (step 4). Map what it heard to what you wrote with a `normalize:` entry in
-  the front matter, `heard=written`, comma-separated: a clip that says
-  "Minimoji" but is transcribed as "Moji" needs `normalize: moji=minimoji`.
+  the front matter, `heard=written`, several on one line, comma-separated: a
+  clip that says "Minimoji" but is transcribed as "Moji" needs
+  `normalize: moji=minimoji`, and with a second entry
+  `normalize: moji=minimoji, dash=D.A.S.H.` (one line, not a YAML list).
+- Write a narrator's name as it is spoken when the two differ, or leave it to
+  the narrator's spoken name: `narrator list` shows it, and narrate reads
+  "D.A.S.H." as "Dash" (captions keep what you wrote).
 
 ### 4. Narrate and read the guard
 

package/skills/hyperdecks/chat.md

@@ -96,6 +96,13 @@ makes the hello deck; continue from step 5 below.
    `set_recipient_archived` to tidy the activity feed; `credits` for the
    balance. `remove_deck` deletes a deck and breaks every link to it: confirm
    with the user first.
+11. When someone asks for "the PDF" (a data room, an attachment):
+   `export_deck { slug, kind: "pdf", notes? }` renders the released deck, one
+   1600×900 page per slide with a footer carrying its tracked link (pass
+   `shareToken` to choose which), and returns a download `url` that lasts 30
+   days; `notes: true` adds the slide's script after each slide.
+   `list_exports` shows what was exported. Release first: it prints the live
+   deck, not the draft.
 
 ## Rules that matter
 

package/src/commands.mjs

@@ -1,4 +1,5 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
 import {
   installHyperdecksSkill,
   login,
@@ -409,6 +410,11 @@ commands:
   review <slug> [--script <script.md>] [--json]
                    GPT-6 Luna reviews every slide (desktop + phone screenshots) and lists what to fix
   review-job <jobId> [--json]
+  export <slug|deck-dir> --pdf [--notes] [--out <file.pdf>] [--share <token>] [--json]
+                   a PDF of the released deck: one 1600x900 page per slide (a script page after each
+                   with --notes), a footer with the deck's tracked link; kept 30 days
+  export list [<slug>] [--json]    your exports and their download links
+  export rm <exportId>             delete an export now
   poster <slug> [--force] [--json]
                    regenerate the share-link poster (release makes one) and print its URL
   credits [--limit <n>] [--json]   show your credit balance and recent history
@@ -440,7 +446,7 @@ commands:
   narrator default <name|id|dash>   make it the default
   narrator remove <name|id>         remove it; decks already shared keep working
   narrator voice <name|id> <voice>  change its voice (one of yours, or dash)
-  narrator rename <name|id> <new name>   rename it
+  narrator rename <name|id> [<new name>] [--say <spoken name>]   rename it, or say how it is spoken ("" clears)
   narrator face <name|id> <avatar>  change its face (one of your avatars)
   deck narrator <slug> <name|id|none|default>   the deck's own narrator (none: captions only)
 
@@ -663,6 +669,47 @@ async function reviewJob(pos, opts) {
   printReview(job);
 }
 
+// hyperdecks export <slug|deck-dir> --pdf: a local deck folder exports its
+// released copy (the slug is --slug or the folder's name) with its own script.md
+// (for its [reveal] cues and --notes); nothing renders locally.
+export function exportTarget(arg, opts = {}, cwd = process.cwd()) {
+  const dir = [resolve(cwd, arg), join(cwd, "decks", arg)].find((d) => existsSync(join(d, "index.html")));
+  if (!dir) return { slug: arg, script: undefined };
+  const scriptPath = join(dir, "script.md");
+  return { slug: opts.slug || basename(dir), script: existsSync(scriptPath) ? readFileSync(scriptPath, "utf8") : undefined };
+}
+
+async function exportCmd(pos, opts) {
+  const [arg] = pos;
+  const usage = "usage: export <slug|deck-dir> --pdf [--notes] [--out <file.pdf>] [--share <token>]";
+  if (!arg) throw new Error(usage);
+  if (opts.mp4 || opts.gif) throw new Error("only --pdf exports are available so far (video comes later; the email GIF is `hyperdecks preview create`)");
+  if (!opts.pdf) throw new Error(`${usage}\n(--pdf is the only format so far)`);
+  const { slug, script } = exportTarget(arg, opts);
+  if (slug !== arg) process.stderr.write(`deck folder ${arg} → slug ${slug} (pass --slug to change it)\n`);
+  process.stderr.write(`rendering ${slug} as a PDF${opts.notes ? " with notes" : ""}…\n`);
+  const out = await ops.exportDeck(opts, { slug, kind: "pdf", notes: !!opts.notes, script, shareToken: opts.share });
+  const file = opts.out === true ? out.filename : opts.out || out.filename;
+  await saveTo(file, out.url);
+  if (opts.json) return void console.log(JSON.stringify({ ...out, file }, null, 2));
+  console.log(`✓ ${out.pages} page(s), ${(out.bytes / 1e6).toFixed(1)} MB → ${file}`);
+  console.log(`  footer link: ${out.link}`);
+  for (const w of out.warnings ?? []) console.log(`  ⚠ ${w}`);
+  console.log(`  download (30 days): ${out.url}`);
+}
+
+async function exportList(pos, opts) {
+  const rows = await ops.listExports(opts, { slug: pos[0] });
+  if (opts.json) return void console.log(JSON.stringify(rows, null, 2));
+  if (!rows.length) return void console.log("no exports in the last 30 days");
+  for (const r of rows) {
+    const when = new Date(r.createdAt).toISOString().slice(0, 16).replace("T", " ");
+    const what = r.status === "ready" ? `${r.pages} pages, ${((r.bytes ?? 0) / 1e6).toFixed(1)} MB` : r.status === "failed" ? `failed: ${r.error}` : r.status;
+    console.log(`${r.exportId}  ${when}  ${r.slug}  ${r.kind}${r.notes ? "+notes" : ""}  ${what}`);
+    if (r.url) console.log(`  ${r.url}`);
+  }
+}
+
 async function poster(pos, opts) {
   const [slug] = pos;
   if (!slug) throw new Error("usage: poster <slug> [--force] [--json]");
@@ -851,9 +898,11 @@ function commandTable(pos, rest, opts) {
       console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.name} speaks in ${out.voice} now`);
     },
     "narrator rename": async () => {
-      if (rest.length < 2) throw new Error("usage: narrator rename <name|id> <new name>");
-      const out = await ops.renameNarrator(opts, rest[0], rest.slice(1).join(" "));
-      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.was} is ${out.name} now`);
+      if (Object.hasOwn(opts, "say") && (opts.say === undefined || String(opts.say).startsWith("--"))) throw new Error('--say needs a value (--say "" clears it)');
+      const say = Object.hasOwn(opts, "say") ? String(opts.say) : undefined;
+      if (rest.length < 1 || (rest.length < 2 && say === undefined)) throw new Error("usage: narrator rename <name|id> [<new name>] [--say <spoken name>]");
+      const out = await ops.renameNarrator(opts, rest[0], rest.slice(1).join(" "), say);
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.was} is ${out.name} now${out.spokenName ? `, said "${out.spokenName}"` : ""}`);
     },
     "narrator face": async () => {
       if (rest.length < 2) throw new Error("usage: narrator face <name|id> <avatar>");
@@ -928,6 +977,13 @@ function commandTable(pos, rest, opts) {
     review: () => review(pos.slice(1), opts),
     "review-job": () => reviewJob(pos.slice(1), opts),
     poster: () => poster(pos.slice(1), opts),
+    export: () => exportCmd(pos.slice(1), opts),
+    "export list": () => exportList(pos.slice(2), opts),
+    "export rm": async () => {
+      if (!pos[2]) throw new Error("usage: export rm <exportId>");
+      const out = await ops.removeExport(opts, { exportId: pos[2] });
+      console.log(opts.json ? JSON.stringify(out) : `✓ removed ${pos[2]}`);
+    },
     credits: () => credits(pos.slice(1), opts),
   };
 }

package/src/firstDeck.mjs

@@ -6,7 +6,8 @@ import { packageText } from "./files.mjs";
 import { slugify } from "./importer.mjs";
 
 export const FIRST_DECK_LAYOUTS = "hero,features,closer";
-export const DASH_AVATAR = "https://decks.hypersocial.ai/player/v1/dash-avatar.json";
+export { DASH_AVATAR } from "./presenter.mjs";
+import { DASH_AVATAR } from "./presenter.mjs";
 export const ANSWER_MAX = { name: 40, about: 80, ask: 80 };
 
 // One answer as it goes on a slide and into the script: one line, no stage-tag

package/src/narrator.mjs

@@ -11,7 +11,7 @@ const interactiveOf = (opts) => !opts.json && !!process.stdin.isTTY && !!process
 export async function narratorList(opts, { log = console.log } = {}) {
   const out = await ops.listNarrators(opts);
   if (opts.json) return out;
-  for (const n of out.narrators) log(`${n.isDefault ? "*" : " "} ${n.name}\t${n.face ?? "(no face)"} · ${n.voice ? `${n.voice}${n.voiceReady ? "" : " (not ready)"}` : "(voice removed)"}\t${n.id}`);
+  for (const n of out.narrators) log(`${n.isDefault ? "*" : " "} ${n.name}${n.spokenName && n.spokenName !== n.name ? ` (said "${n.spokenName}")` : ""}\t${n.face ?? "(no face)"} · ${n.voice ? `${n.voice}${n.voiceReady ? "" : " (not ready)"}` : "(voice removed)"}\t${n.id}`);
   if (out.note) log(`\n${out.note}`);
   log("\n* the default; decks use it unless they set their own (deck narrator <slug> <id>)");
   return out;

package/src/ops.mjs

@@ -200,6 +200,33 @@ export async function generatePoster(opts, fields = {}) {
   return (await client(opts)).action(api.posters.generatePoster, args);
 }
 
+// ---- deck exports (convex/exports.ts) -------------------------------------
+
+// Render a PDF of a released deck you own (one 1600x900 page per slide, a notes
+// page after each with notes=true, a footer with the deck's tracked link) and
+// keep it 30 days. Returns { exportId, url, filename, bytes, pages, slides,
+// notes, link, expiresAt }. Waits for the file (about a second per slide).
+export async function exportDeck(opts, fields = {}) {
+  if (!fields.slug) throw new Error("slug is required");
+  const kind = fields.kind ?? "pdf";
+  if (kind !== "pdf") throw new Error(`kind "${kind}" is not supported yet: only "pdf" (video export comes from \`hyperdecks export --mp4\` later)`);
+  const args = { slug: String(fields.slug), kind: "pdf" };
+  if (fields.notes) args.notes = true;
+  if (fields.script) args.script = String(fields.script);
+  if (fields.shareToken) args.shareToken = String(fields.shareToken);
+  return (await client(opts)).action(api.exports.create, args);
+}
+
+// Your exports (newest first, 30 days), optionally for one deck.
+export async function listExports(opts, fields = {}) {
+  return (await client(opts)).query(api.exports.list, fields.slug ? { slug: String(fields.slug) } : {});
+}
+
+export async function removeExport(opts, fields = {}) {
+  if (!fields.exportId) throw new Error("exportId is required");
+  return (await client(opts)).mutation(api.exports.remove, { exportId: String(fields.exportId) });
+}
+
 // ---- deck review (convex/review.ts) --------------------------------------
 
 // Queue a GPT-6 Luna review of every slide (desktop + phone screenshots of the
@@ -1017,7 +1044,7 @@ export async function listNarrators(opts = {}) {
   return {
     default: out.defaultId,
     ...(out.unpickedVoice ? { note: `no default narrator yet: decks narrate in your voice "${out.unpickedVoice}"` } : {}),
-    narrators: out.narrators.map((n) => ({ id: n.id, name: n.name, isDefault: n.isDefault, builtin: n.builtin, face: n.face?.name ?? null, voice: n.voice?.name ?? null, voiceReady: !!n.voice?.ready })),
+    narrators: out.narrators.map((n) => ({ id: n.id, name: n.name, spokenName: n.spokenName ?? null, isDefault: n.isDefault, builtin: n.builtin, face: n.face?.name ?? null, voice: n.voice?.name ?? null, voiceReady: !!n.voice?.ready })),
     voices: out.voices.map((x) => ({ id: x.ref, name: x.name, status: x.status, character: x.character, narrators: x.narrators })),
   };
 }
@@ -1068,12 +1095,20 @@ export async function setNarratorVoice(opts, ref, voice) {
   return { narrator: n.id, name: n.name, voice: String(voice) };
 }
 
-export async function renameNarrator(opts, ref, name) {
-  if (!String(name ?? "").trim()) throw new Error("usage: narrator rename <name|id> <new name>");
+// A new name, and/or how it is said (`spokenName`, "" clears it): narrate gives
+// the voice the spoken form, so "J.P." is not read letter by letter.
+export async function renameNarrator(opts, ref, name, spokenName) {
+  const next = String(name ?? "").trim();
+  if (!next && spokenName === undefined) throw new Error("usage: narrator rename <name|id> [<new name>] [--say <spoken name>]");
   const n = await findNarrator(opts, ref);
   if (n.builtin) throw new Error("D.A.S.H. is built in; its name stays");
-  await (await client(opts)).mutation(api.narrators.rename, { narrator: n.id, name: String(name).trim() });
-  return { narrator: n.id, was: n.name, name: String(name).trim() };
+  await (await client(opts)).mutation(api.narrators.rename, {
+    narrator: n.id, ...(next ? { name: next } : {}), ...(spokenName !== undefined ? { spokenName: String(spokenName) } : {}),
+  });
+  return {
+    narrator: n.id, was: n.name, name: next || n.name,
+    spokenName: spokenName === undefined ? n.spokenName : String(spokenName).trim() || null,
+  };
 }
 
 // face: one of your avatars (name or id from `avatar`); D.A.S.H. keeps its own.

package/src/play.mjs

@@ -55,7 +55,8 @@ async function lookUpPresenter(opts, { slug, path, html, log }) {
 
 // Says what the served page does, not what the lookup answered.
 function sayWhoPresents({ html, page, presenter, who, log }) {
-  if (presenter && page === html) log("⚠ the player tag already names a presenter, so it plays as written");
+  // A tag that already has this face (an init deck's D.A.S.H.) is not a conflict.
+  if (presenter && page === html && !html.includes(`data-avatar="${presenter.avatarUrl}"`)) log("⚠ the player tag already names a presenter, so it plays as written");
   else if (who?.face && !presenter && playsCaptionsOnly(html)) log(`⚠ captions only: the page names no presenter, and a face for voice "${who.voice}" is not added here`);
   else if (who) log(presenterLine(who));
 }

package/src/presenter.mjs

@@ -6,6 +6,12 @@
 // preview, so all rewrite the tag the same way; only a release stores it. A tag that already names a presenter (D.A.S.H.
 // on a character-voice deck, or one set by hand) is left alone.
 
+// D.A.S.H.'s face: the head doc and still that ship with the player. A deck
+// narrated in its character voice gets this face at release, even when the
+// tag was scaffolded captions-only (data-presenter="none").
+export const DASH_AVATAR = "https://decks.hypersocial.ai/player/v1/dash-avatar.json";
+export const DASH_PRESENTER = Object.freeze({ avatarUrl: DASH_AVATAR, imageUrl: "https://decks.hypersocial.ai/avatars/dash.png" });
+
 const PLAYER_TAG = /<script\b[^>]*\bsrc="[^"]*\/player\/v1\/player\.js"[^>]*>/i;
 
 const attr = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;");

package/src/release.mjs

@@ -110,7 +110,7 @@ export async function release(pos, opts = {}, io = {}) {
     throw new Error(`narration changed the deck (${after.split("\n").length} file(s)):\n${after}\n` +
       `run \`hyperdecks check ${pos[0]}\`, look at it, commit (index.html and narration/), then run release again`);
   }
-  // Narrated in your own voice: the released page gets your avatar's face.
+  // The released page gets the narrator's face: your avatar, or D.A.S.H.'s for its voice.
   let presenter = null;
   try {
     presenter = await ops.presenterFor(opts, slug, opts.voice);
@@ -118,7 +118,7 @@ export async function release(pos, opts = {}, io = {}) {
     log(`⚠ could not look up your avatar (${ops.errorText(e)}); releasing captions only`);
   }
   const released = presenter ? releaseBundle(deckDir, presenter) : bundle;
-  if (presenter) log("✓ presented by your avatar");
+  if (presenter) log(`✓ presented by ${job.presenter?.face ?? "your avatar"}`);
   // A terminal user sees this before it ships, so the CLI warns rather than refuses.
   else if (job.presenter && !job.presenter.face) log(`⚠ releasing captions only: ${job.presenter.reason ?? "no face"}`);
   return publish({ opts, io: { log, commit }, deckDir, slug, to, checked, bundle, released, summary: job.presenter ?? null });

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.9.1";
+export const VERSION = "0.9.2";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -128,6 +128,11 @@ export const api = {
   posters: {
     generatePoster: makeFunctionReference("posters:generatePoster"),
   },
+  exports: {
+    create: makeFunctionReference("exports:create"),
+    list: makeFunctionReference("exports:list"),
+    remove: makeFunctionReference("exports:remove"),
+  },
   review: {
     reviewDeck: makeFunctionReference("review:reviewDeck"),
     checkReviewJob: makeFunctionReference("review:checkReviewJob"),
@@ -156,7 +161,7 @@ export const api = {
   },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "loop", "upload", "dry-run", "narrated", "layout", "strict", "fix", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji", "captions-only", "no-brand", "no-logo"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "loop", "upload", "dry-run", "narrated", "layout", "strict", "fix", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji", "captions-only", "no-brand", "no-logo", "pdf", "notes", "mp4", "gif"]);
 // release's recipients, in order: each --to starts one, and an --email right
 // after it belongs to it (`--to A --email a --to B`). Collected as opts.recipients;
 // opts.email stays the last --email for the other commands (share new).