@hypersocial/decks-cli 0.4.0 → 0.6.0

package/src/ops.mjs

@@ -1,4 +1,5 @@
 import { zipSync } from "fflate";
+import { COLOR_KEYS, FONT_PAIRINGS, FONT_ROLES, findPairing, googleFontsUrl } from "./brand.mjs";
 import { api, client, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
 import {
   bytesFromText,
@@ -1019,6 +1020,68 @@ 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>");
+  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() };
+}
+
+// face: one of your avatars (name or id from `avatar`); D.A.S.H. keeps its own.
+export async function setNarratorFace(opts, ref, avatarRef) {
+  if (!avatarRef) throw new Error("usage: narrator face <name|id> <avatar>");
+  const n = await findNarrator(opts, ref);
+  if (n.builtin) throw new Error("D.A.S.H. is built in and keeps its face");
+  const a = await findAvatar(opts, avatarRef);
+  if (a.source === "dash") throw new Error("D.A.S.H.'s face is D.A.S.H.'s; pick one of your avatars");
+  await (await client(opts)).mutation(api.narrators.setFace, { narrator: n.id, avatarId: a.id });
+  return { narrator: n.id, name: n.name, face: a.name };
+}
+
+// A short sample of a voice, or of a narrator's voice: { url, caption } (what
+// the dashboard's play buttons play). A narrator also brings its face still.
+export async function hearVoice(opts, { voice, narrator } = {}) {
+  const c = await client(opts);
+  if (!voice && !narrator) throw new Error("name a voice or a narrator (list_voices / list_narrators)");
+  let ref = voice ? String(voice) : null;
+  let who = null;
+  if (narrator) {
+    const n = await findNarrator(opts, narrator);
+    const raw = (await c.query(api.narrators.list, {})).narrators.find((x) => x.id === n.id);
+    if (!raw?.voice) throw new Error(`${n.name} has no voice yet; give it one (narrator voice)`);
+    if (!raw.voice.ready) throw new Error(`${n.name}'s voice ${raw.voice.name} is not ready yet`);
+    ref = raw.voice.ref;
+    who = { narrator: n.id, name: n.name, faceUrl: raw.face?.thumbUrl ?? null, faceName: raw.face?.name ?? null };
+  }
+  const out = await c.action(api.narratorsNode.hear, { voice: ref });
+  return { ...out, voice: ref, ...(who ?? {}) };
+}
+
+// A photo drawing started from chat (avatar_from_photo with a photo): still
+// drawing, failed, or drawn, when it hands back the link where the person
+// approves it. Nothing is used before they do.
+export async function startAvatarDrawing(opts, { bytes, contentType }) {
+  if (!/^image\/(jpeg|png)$/.test(contentType ?? "")) throw new Error("the photo must be a .jpg or .png");
+  const c = await client(opts);
+  const storageId = await runtimeUploadBytes(c, bytes, contentType);
+  const { draftId } = await c.mutation(api.avatars.drawSelfie, { storageId });
+  return { status: "drawing", draftId };
+}
+
+export async function avatarDraftStatus(opts, draftId) {
+  if (!draftId) throw new Error("draftId is required");
+  const c = await client(opts);
+  const draft = await c.query(api.avatars.getDraft, { draftId: String(draftId) });
+  if (!draft) throw new Error("the drawing is gone; start again with avatar_from_photo");
+  if (draft.status === "drawing") return { status: "drawing", draftId };
+  if (draft.status === "failed") throw new Error(draft.error || "the drawing failed; try another photo");
+  if (draft.status === "added") return { status: "added", draftId, avatarId: draft.avatarId ?? null };
+  if (draft.status !== "drawn") throw new Error(`the drawing is in an unexpected state (${draft.status}); start again with avatar_from_photo`);
+  const link = await c.mutation(api.avatars.createLink, { kind: "review", draftId });
+  return { status: "waiting", reviewUrl: link.url, token: link.token, draftId, expiresAt: link.expiresAt };
+}
+
 // A deck's own narrator: a narrator, `none` (captions only) or `default`.
 export async function setDeckNarrator(opts, slug, ref) {
   if (!slug || !ref) throw new Error("usage: deck narrator <slug> <narrator|none|default>");
@@ -1026,6 +1089,58 @@ export async function setDeckNarrator(opts, slug, ref) {
   return (await client(opts)).mutation(api.narrators.setDeckNarrator, { slug, narrator: value });
 }
 
+// The account's brand (convex/brand.ts): what new_deck / deck new start from.
+export async function getBrand(opts = {}) {
+  return (await client(opts)).query(api.brand.get, {});
+}
+
+// Merge into the saved brand: a field left out keeps its value, "" clears it.
+// fontPairing names one of FONT_PAIRINGS and fills the three fonts (an explicit
+// font still wins). logoUrl is fetched into our storage; logoBytes (with
+// logoType) is a file the CLI read. clearLogo removes the logo.
+export async function setBrand(opts, { name, designMd, colors, fonts, fontPairing, presenterStyle, logoUrl, logoBytes, logoType, clearLogo } = {}) {
+  const c = await client(opts);
+  let fontSet = fonts;
+  if (fontPairing) {
+    const p = findPairing(fontPairing);
+    if (!p) throw new Error(`no font pairing "${fontPairing}": pick one of ${FONT_PAIRINGS.map((x) => x.id).join(", ")}`);
+    fontSet = { display: p.display, body: p.body, mono: p.mono, ...(fonts ?? {}) };
+  }
+  if (logoUrl && logoBytes) throw new Error("pass logoUrl or a logo file, not both");
+  if (clearLogo && (logoUrl || logoBytes)) throw new Error("clearLogo removes the logo; do not also pass one");
+  const known = (map, keys, what) => {
+    const extra = Object.keys(map ?? {}).filter((k) => !keys.includes(k));
+    if (extra.length) throw new Error(`unknown ${what} ${extra.join(", ")}: use ${keys.join(", ")}`);
+    return map;
+  };
+  known(colors, COLOR_KEYS, "colour");
+  known(fontSet, FONT_ROLES, "font role");
+  const fields = { name, designMd, colors, fonts: fontSet, presenterStyle };
+  const defined = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined && v !== null));
+  if (!Object.keys(defined).length && !logoUrl && !logoBytes && !clearLogo) throw new Error("nothing to set: pass colors, fonts, fontPairing, logoUrl, designMd, name or presenterStyle");
+  let out = Object.keys(defined).length ? await c.mutation(api.brand.set, defined) : null;
+  try {
+    if (clearLogo) out = await c.mutation(api.brand.clear, { logoOnly: true });
+    if (logoUrl) out = await c.action(api.brandNode.importLogo, { url: String(logoUrl) });
+    if (logoBytes) {
+      const bytes = logoBytes instanceof ArrayBuffer ? logoBytes : new Uint8Array(logoBytes).slice().buffer;
+      out = await c.action(api.brandNode.uploadLogo, { bytes, contentType: String(logoType ?? "") });
+    }
+  } catch (e) {
+    // The fields above are already saved: say so, so nobody redoes or reports them as lost.
+    const kept = Object.keys(defined);
+    throw new Error(`${kept.length ? `brand saved (${kept.join(", ")}) but the logo was not` : "the logo was not saved"}: ${errorText(e)}`);
+  }
+  return out ?? getBrand(opts);
+}
+
+export async function clearBrand(opts = {}) {
+  await (await client(opts)).mutation(api.brand.clear, {});
+  return { cleared: true };
+}
+
+export const listFontPairings = () => ({ pairings: FONT_PAIRINGS.map((p) => ({ ...p, urls: [googleFontsUrl(p.display, "display"), googleFontsUrl(p.body, "body"), googleFontsUrl(p.mono, "mono")] })) });
+
 // Polls `read` until `done`; a few failed reads in a row (a network blip) are
 // retried, since the person may still be finishing in the browser.
 async function pollUntil(read, done, { intervalMs = 2000, timeoutMs }) {

package/src/presenter.mjs

@@ -26,3 +26,12 @@ export function withAvatar(html, { avatarUrl, imageUrl }) {
   const next = none ? tag.replace(/\sdata-presenter="none"/, face) : tag.replace(/>$/, `${face}>`);
   return html.replace(tag, () => next);
 }
+
+// One line for who presents a deck, from narrate's or release's `presenter`
+// ({ narrator, voice, face, reason }); a warning when it plays captions only.
+// Empty for an older backend that sends none.
+export function presenterLine(p) {
+  if (!p) return "";
+  if (!p.face) return `⚠ captions only: ${p.reason ?? `no face for voice "${p.voice}"`}`;
+  return `presented by ${p.face}${p.narrator && p.narrator !== p.face ? ` (narrator ${p.narrator})` : ""}, voice "${p.voice}"`;
+}

package/src/release.mjs

@@ -108,6 +108,8 @@ export async function release(pos, opts = {}, io = {}) {
   }
   const released = presenter ? releaseBundle(deckDir, presenter) : bundle;
   if (presenter) log("✓ presented by 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"}`);
   const imported = await ops.importDeckFromBytes(opts, {
     slug,
     title: opts.title,
@@ -142,5 +144,5 @@ export async function release(pos, opts = {}, io = {}) {
     log(`✓ share for "${r.recipient}"${share.qa ? " (QA, untracked)" : ""} → ${share.url}`);
   }
   if (!shares.length) log(`  no --to given: \`hyperdecks share new ${imported.slug} "Me" --qa\` makes a link for your own viewing`);
-  return { slug: imported.slug, deckDir, commit: sha, deckUrl: imported.deckUrl, totalDuration: checked.totalDuration, files: bundle.files, shares };
+  return { slug: imported.slug, deckDir, commit: sha, deckUrl: imported.deckUrl, totalDuration: checked.totalDuration, presenter: job.presenter ?? null, files: bundle.files, shares };
 }

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.4.0";
+export const VERSION = "0.6.0";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -40,6 +40,20 @@ export const api = {
     setVoice: makeFunctionReference("narrators:setVoice"),
     setDeckNarrator: makeFunctionReference("narrators:setDeckNarrator"),
     newLink: makeFunctionReference("narrators:newLink"),
+    rename: makeFunctionReference("narrators:rename"),
+    setFace: makeFunctionReference("narrators:setFace"),
+  },
+  brand: {
+    get: makeFunctionReference("brand:get"),
+    set: makeFunctionReference("brand:set"),
+    clear: makeFunctionReference("brand:clear"),
+  },
+  brandNode: {
+    importLogo: makeFunctionReference("brandNode:importLogo"),
+    uploadLogo: makeFunctionReference("brandNode:uploadLogo"),
+  },
+  narratorsNode: {
+    hear: makeFunctionReference("narratorsNode:hear"),
   },
   avatarsNode: {
     options: makeFunctionReference("avatarsNode:options"),
@@ -49,6 +63,7 @@ export const api = {
   assets: {
     generateUploadUrl: makeFunctionReference("assets:generateUploadUrl"),
     saveAsset: makeFunctionReference("assets:saveAsset"),
+    list: makeFunctionReference("assets:list"),
   },
   assetsNode: {
     importAssetFromUrl: makeFunctionReference("assetsNode:importAssetFromUrl"),
@@ -130,7 +145,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", "upload", "dry-run", "narrated", "layout", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "upload", "dry-run", "narrated", "layout", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji", "captions-only", "no-brand", "no-logo"]);
 // 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).

package/src/scaffold.mjs

@@ -9,12 +9,13 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
 import { PRESENTER_STYLES } from "./checkRules.mjs";
-import { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate } from "./layouts.mjs";
+import { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts } from "./layouts.mjs";
+import { applyBrand, brandForNewDeck, brandSummary } from "./brand.mjs";
 
 export { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts, readLayout } from "./layouts.mjs";
 
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
-const USAGE = 'usage: deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style <stage|bubble|glass|corner>] [--dir <path>]';
+const USAGE = 'usage: deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style <stage|bubble|glass|corner>] [--no-brand] [--dir <path>]';
 
 export async function deckNew(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
   const [slug, title] = pos;
@@ -28,9 +29,15 @@ export async function deckNew(pos, opts = {}, { log = (line) => console.log(line
   const dir = resolve(/*turbopackIgnore: true*/ cwd, typeof opts.dir === "string" ? opts.dir : join("decks", slug));
   if (existsSync(dir)) throw new Error(`${dir} already exists; pick another slug or --dir`);
   if (opts.layouts === true) throw new Error(`--layouts needs a list, e.g. --layouts ${LAYOUTS.slice(0, 3).join(",")},closer`);
-  const files = opts.layouts !== undefined
-    ? Object.entries(assembleLayoutDeck({ slug, title, presenterStyle, layouts: opts.layouts }))
-    : Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle })]);
+  if (opts.layouts !== undefined) parseLayouts(opts.layouts);
+  // The account's brand goes on the template (--no-brand: the template's look);
+  // an explicit --presenter-style wins over the brand's.
+  const { brand, readError } = await brandForNewDeck(() => ops.getBrand(opts), !(opts["no-brand"] || opts.brand === false));
+  const style = presenterStyle ?? (PRESENTER_STYLES.includes(brand?.presenterStyle) ? brand.presenterStyle : undefined);
+  const files = (opts.layouts !== undefined
+    ? Object.entries(assembleLayoutDeck({ slug, title, presenterStyle: style, layouts: opts.layouts }))
+    : Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle: style })]))
+    .map(([out, text]) => [out, out === "index.html" ? applyBrand(text, brand) : text]);
   await ops.createDeck(opts, { slug, title });
   try {
     mkdirSync(dir, { recursive: true });
@@ -39,6 +46,7 @@ export async function deckNew(pos, opts = {}, { log = (line) => console.log(line
     rmSync(dir, { recursive: true, force: true });
     throw new Error(`deck ${slug} is registered but its files could not be written (${e.message}); remove the draft with \`hyperdecks deck rm ${slug}\` and run deck new again`);
   }
-  log(`✓ created deck "${slug}" → ${dir}\n  files: ${Object.keys(NARRATED_FILES).join(", ")}\n  next:  hyperdecks narrate ${dir} --dry-run`);
-  return { slug, title, dir, files: Object.keys(NARRATED_FILES) };
+  const summary = brandSummary(brand, readError);
+  log(`✓ created deck "${slug}" → ${dir}\n  files: ${Object.keys(NARRATED_FILES).join(", ")}\n  brand: ${summary.error ? `could not read it (${summary.error}); template look` : summary.applied.length ? summary.applied.join(", ") : "none applied (hyperdecks brand set)"}\n  next:  hyperdecks narrate ${dir} --dry-run`);
+  return { slug, title, dir, files: Object.keys(NARRATED_FILES), brand: summary };
 }

package/templates/icons/LICENSE

@@ -0,0 +1,43 @@
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.