@hypersocial/decks-cli 0.2.2 → 0.3.1

package/src/commands.mjs

@@ -12,7 +12,7 @@ import * as ops from "./ops.mjs";
 
 export const playbackLabel = (p) => p.narrationFinished ? "narration finished"
   : p.narrationStarted ? "narration started"
-    : p.telemetryVersion === 2 ? "narration not started" : "playback unknown (legacy)";
+    : (p.telemetryVersion ?? 0) >= 2 ? "narration not started" : "playback unknown (legacy)";
 
 const fmtMs = (ms) => (ms >= 60000 ? `${(ms / 60000).toFixed(1)}m` : `${Math.round(ms / 1000)}s`);
 
@@ -167,6 +167,41 @@ async function activity(pos, opts) {
   }
 }
 
+const pct = (n) => (n === null || n === undefined ? "n/a" : `${n}%`);
+const slideName = (s) => (s.title ? `${s.index} ${s.title}` : `slide ${s.index}`);
+
+async function engagement(pos, opts) {
+  const who = pos.join(" ");
+  if (!who) throw new Error("usage: engagement <recipient|token> [--deck <slug>] [--json]");
+  const entries = await ops.recipientEngagement(opts, who, opts.deck);
+  if (opts.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+  if (!entries.length) {
+    console.log(`(no links for "${who}"${opts.deck ? ` on ${opts.deck}` : ""})`);
+    return;
+  }
+  for (const e of entries) {
+    const s = e.summary;
+    console.log(`${e.recipient} — ${e.deck.title} (${e.deck.slug}, link ${e.link.token}${e.link.enabled ? "" : ", off"})`);
+    if (!s.visits) {
+      console.log("  never opened");
+      continue;
+    }
+    const titles = new Map(e.slides.map((r) => [r.index, r]));
+    const list = (xs) => (xs === null ? "n/a" : xs.length ? xs.map((i) => slideName(titles.get(i) ?? { index: i })).join(", ") : "none");
+    console.log(`  visits:      ${s.visits} (last ${new Date(s.lastSeenAt).toISOString().slice(0, 16).replace("T", " ")}) · ${fmtMs(s.totalMs)} engaged`);
+    console.log(`  narration:   ${s.narration.finished ? "finished" : s.narration.started ? "started" : "not started"} · heard ${pct(s.narration.heardPct)}${s.narration.telemetry === "v3" ? "" : " (playback detail unavailable)"}`);
+    console.log(`  reached:     slide ${s.furthestSlide}${e.deck.slides ? ` of ${e.deck.slides}` : ""}${s.droppedOffOn ? ` · dropped off on ${slideName(s.droppedOffOn)}` : ""}`);
+    console.log(`  replayed:    ${list(s.replayedSlides)}`);
+    console.log(`  skipped:     ${list(s.skippedSlides)}`);
+    console.log(`  most time:   ${s.mostTime.map((m) => `${slideName(m)} (${fmtMs(m.ms)})`).join(", ") || "none"}`);
+    if (!s.slideData) console.log("  slide data unavailable (this deck reports time only)");
+    if (s.deckChangedSinceView) console.log("  the deck changed since their last visit");
+  }
+}
+
 async function credits(pos, opts) {
   const bal = await ops.creditsBalance(opts);
   const ledger = await ops.creditsLedger(opts, opts.limit || 10);
@@ -237,6 +272,12 @@ export function help() {
   console.log(`decks ${VERSION}
 
 commands:
+  init [--yes] [--json] [--agent <id>]... [--all-agents] [--voice dash] [--name <n> --about <a> --ask <k>] [--dir <path>]
+       [--no-voice] [--no-skill] [--no-release] [--no-open]
+                   the first run: sign in, install the skill, pick a voice (clone yours, or D.A.S.H.),
+                   scaffold a 3-slide hello deck from your answers, narrate it and release a QA link.
+                   Re-running resumes where it stopped. --json prints one object; it never clones
+                   (consent is typed by a person) and reports that step as needs-human.
   login [--token <pat>] [--broker <url>] [--dev]
   logout [--dev]
   whoami [--json] [--dev]
@@ -247,6 +288,14 @@ commands:
   check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--layout] [--json]
                    the narrated-deck gate: slides vs manifest, timing, captions, clip URLs,
                    local refs, pinned player, a data-note per slide, mobile titles
+  deck new|check|release … --hosted
+                   the same on a hosted draft (no folder, no git: what chat agents use over the remote MCP)
+  source pull <slug> [dir] | source push <slug> [dir] [--base-rev N]
+                   move a hosted draft (index.html, script.md, evidence.md) to a folder and back
+  asset add <slug> <file|url> [--name n]
+                   file an image, video or font under the deck; prints its hosted URL
+  guide [workflow|format|script|design|layouts|presenter|transitions|check]
+                   the skill, one topic at a time (what deck_guide serves)
   release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v]
                    on a committed deck: check → narrate → import → share new per --to
   share new|list|on|off|mute|unmute|rm|url
@@ -256,7 +305,10 @@ commands:
   import-design <project-id> --serve-token <token> --entry <file.html> --slug <slug>
   skill install [--agent codex,claude-code] [--all-agents]
   skills install [--agent codex,claude-code] [--all-agents]
+                   default: every agent found in your home directory (else codex, claude-code)
   activity [--deck <slug>] [--limit <n>] [--json]
+  engagement <recipient|token> [--deck <slug>] [--json]
+                   what one recipient watched per deck: narration heard, replays, drop-off, visits
   gen-image "<prompt>" [--model gpt-image-2.5|nano-banana-2.1|gpt-image-2] [--transparent] [--image <url>] [--size <s>]
             [--quality <q>] [--count <n>] [--seed <n>] [--slug <deck>] [--download <file>]
                    default model gpt-image-2.5; --seed applies to nano-banana-2.1
@@ -523,18 +575,44 @@ function commandTable(pos, rest, opts) {
       const result = await createPreview(rest, opts);
       console.log(opts.json ? JSON.stringify(result) : `Preview saved: ${result.manifestPath}\n${result.email.sendable ? result.email.path : "Insert the GIF or PNG manually; upload with an existing share for linked email HTML."}`);
     },
+    init: async () => {
+      const { init } = await import("./init.mjs");
+      const out = await init(pos.slice(1), opts, opts.json ? { log: (line) => console.error(line) } : {});
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
     "deck new": async () => {
+      if (opts.hosted) {
+        const { hostedNewDeck } = await import("./source.mjs");
+        if (!opts.narrated) throw new Error("the published CLI scaffolds narrated decks only: add --narrated");
+        const out = await hostedNewDeck(opts, { slug: rest[0], title: rest[1], layouts: opts.layouts, presenterStyle: opts["presenter-style"] });
+        return void console.log(opts.json ? JSON.stringify(out, null, 2) : `✓ created hosted deck "${out.slug}" (rev ${out.rev})\n  preview: ${out.previewUrl}\n  edit locally: hyperdecks source pull ${out.slug}`);
+      }
       const { deckNew } = await import("./scaffold.mjs");
       const out = await deckNew(rest, opts, opts.json ? { log: (line) => console.error(line) } : {});
       if (opts.json) console.log(JSON.stringify(out, null, 2));
     },
     check: async () => {
       const { check } = await import("./check.mjs");
-      const result = await check(pos.slice(1), opts);
+      const { hostedCheck } = await import("./source.mjs");
+      const result = opts.hosted ? await hostedCheck(opts, { slug: pos[1], forbid: opts.forbid, maxDuration: opts["max-duration"] }) : await check(pos.slice(1), opts);
+      if (opts.hosted && !opts.json) {
+        console.log(`deck "${pos[1]}" rev ${result.rev}: ${result.slides} slides${result.totalDuration != null ? `, ${result.totalDuration}s narrated` : ""}`);
+        for (const e of result.errors) console.log(`  - ${e}`);
+        if (!result.errors.length) console.log("✓ check passed");
+        for (const w of result.warnings) console.log(`  ⚠ ${w}`);
+      }
       if (opts.json) console.log(JSON.stringify(result, null, 2));
       if (result.errors.length) throw new Error(`check found ${result.errors.length} issue(s)`);
     },
     release: async () => {
+      if (opts.hosted) {
+        const { hostedRelease } = await import("./source.mjs");
+        const out = await hostedRelease(opts, { slug: pos[1], recipients: opts.recipients, qa: opts.qa, title: opts.title, forbid: opts.forbid });
+        if (opts.json) return void console.log(JSON.stringify(out, null, 2));
+        console.log(`✓ released ${out.slug} rev ${out.rev}\n  deck: ${out.deckUrl}`);
+        for (const s of out.shares) console.log(`✓ share for "${s.recipient}"${s.qa ? " (QA, untracked)" : ""} → ${s.url}`);
+        return;
+      }
       const { release } = await import("./release.mjs");
       const out = await release(pos.slice(1), opts, opts.json ? { log: (line) => console.error(line) } : {});
       if (opts.json) console.log(JSON.stringify(out, null, 2));
@@ -544,6 +622,26 @@ function commandTable(pos, rest, opts) {
       const result = await narrate(pos.slice(1), opts, opts.json ? { log: (line) => console.error(line) } : {});
       if (opts.json) console.log(JSON.stringify(result, null, 2));
     },
+    "source pull": async () => {
+      const { sourcePull } = await import("./source.mjs");
+      const out = await sourcePull(rest, opts, opts.json ? { log: (line) => console.error(line) } : {});
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    "source push": async () => {
+      const { sourcePush } = await import("./source.mjs");
+      const out = await sourcePush(rest, opts, opts.json ? { log: (line) => console.error(line) } : {});
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    "asset add": async () => {
+      const { assetAdd } = await import("./source.mjs");
+      const out = await assetAdd(rest, opts, opts.json ? { log: () => {} } : {});
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    guide: async () => {
+      const { guide } = await import("./guide.mjs");
+      const out = await guide(pos.slice(1), opts);
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
     "voice list": async () => {
       const voices = await ops.listVoices(opts);
       if (opts.json) return void console.log(JSON.stringify(voices, null, 2));
@@ -592,6 +690,7 @@ function commandTable(pos, rest, opts) {
     "skill install": () => installHyperdecksSkill(opts, rest),
     "skills install": () => installHyperdecksSkill(opts, rest),
     activity: () => activity(pos.slice(1), opts),
+    engagement: () => engagement(pos.slice(1), opts),
     "gen-image": () => genImage(pos.slice(1), opts),
     "image-job": () => imageJob(pos.slice(1), opts),
     "gen-video": () => genVideo(pos.slice(1), opts),

package/src/files.mjs

@@ -0,0 +1,35 @@
+// The packaged text files the hosted MCP route reads at runtime: templates and
+// the skill. Each is a literal new URL(…, import.meta.url), which the Next.js
+// bundler copies next to the route and the CLI resolves next to this file. A
+// path that is not here cannot be read, so nothing outside the package is.
+import { readFileSync } from "node:fs";
+
+const FILES = {
+  "templates/narrated-deck.html": () => new URL("../templates/narrated-deck.html", import.meta.url),
+  "templates/script.md": () => new URL("../templates/script.md", import.meta.url),
+  "templates/evidence.md": () => new URL("../templates/evidence.md", import.meta.url),
+  "templates/layouts/_deck.html": () => new URL("../templates/layouts/_deck.html", import.meta.url),
+  "templates/layouts/chart.html": () => new URL("../templates/layouts/chart.html", import.meta.url),
+  "templates/layouts/closer.html": () => new URL("../templates/layouts/closer.html", import.meta.url),
+  "templates/layouts/compare.html": () => new URL("../templates/layouts/compare.html", import.meta.url),
+  "templates/layouts/features.html": () => new URL("../templates/layouts/features.html", import.meta.url),
+  "templates/layouts/hero.html": () => new URL("../templates/layouts/hero.html", import.meta.url),
+  "templates/layouts/number.html": () => new URL("../templates/layouts/number.html", import.meta.url),
+  "templates/layouts/product.html": () => new URL("../templates/layouts/product.html", import.meta.url),
+  "templates/layouts/quote.html": () => new URL("../templates/layouts/quote.html", import.meta.url),
+  "templates/layouts/team.html": () => new URL("../templates/layouts/team.html", import.meta.url),
+  "templates/layouts/timeline.html": () => new URL("../templates/layouts/timeline.html", import.meta.url),
+  "skills/hyperdecks/SKILL.md": () => new URL("../skills/hyperdecks/SKILL.md", import.meta.url),
+  "skills/hyperdecks/chat.md": () => new URL("../skills/hyperdecks/chat.md", import.meta.url),
+};
+
+const cache = new Map();
+
+export function packageText(path) {
+  const url = FILES[path];
+  if (!url) throw new Error(`no packaged file ${path}`);
+  if (!cache.has(path)) cache.set(path, readFileSync(url(), "utf8"));
+  return cache.get(path);
+}
+
+export const PACKAGE_FILES = Object.keys(FILES);

package/src/guide.mjs

@@ -0,0 +1,55 @@
+// hyperdecks guide [topic]
+//
+// The skill, served in sections, for agents that cannot install it (chat apps on
+// the hosted MCP call deck_guide). `workflow` is chat.md; the other topics are
+// the SKILL.md sections marked <!-- topic: … -->, and `layouts` is built from
+// each layout file's leading comment.
+import { packageText } from "./files.mjs";
+import { LAYOUTS, readLayout } from "./layouts.mjs";
+
+export const GUIDE_TOPICS = ["workflow", "format", "script", "design", "layouts", "presenter", "transitions", "check"];
+const CLI_NOTE = "_Written for the CLI. On the hosted MCP there is no folder: use the tool names in `deck_guide` (workflow), hosted URLs for every file, and write_deck_source for edits._\n\n";
+
+// One <!-- topic: name --> section of SKILL.md: its heading and body, up to the
+// next topic marker or the next heading of the same or a higher level.
+export function skillSection(skill, topic) {
+  const lines = skill.split("\n");
+  const start = lines.findIndex((l) => l.trim() === `<!-- topic: ${topic} -->`);
+  if (start === -1) return null;
+  const level = /^(#+)\s/.exec(lines[start + 1] ?? "")?.[1].length ?? 6;
+  const out = [];
+  for (const line of lines.slice(start + 1)) {
+    if (out.length && (/^<!-- topic: /.test(line.trim()) || ((/^(#+)\s/.exec(line)?.[1].length ?? 99) <= level))) break;
+    out.push(line);
+  }
+  return out.join("\n").trim();
+}
+
+function layoutsTopic() {
+  const rows = LAYOUTS.map((name) => {
+    const { meta } = readLayout(name);
+    return [`### ${name}`, meta.summary, meta.use && `Use: ${meta.use}`, meta.slot && `Slots: ${meta.slot}`, meta.cues && `Cues: ${meta.cues}`].filter(Boolean).join("\n");
+  });
+  return `# Layouts\n\nPass any of these, in order, as new_deck's \`layouts\` (repeat one for more of the same: number, number gives slides number and number-2).\n\n${rows.join("\n\n")}`;
+}
+
+// { topic, topics, text } for one topic; no topic gives the workflow.
+export function deckGuide(topic = "workflow") {
+  const t = String(topic || "workflow").toLowerCase();
+  if (!GUIDE_TOPICS.includes(t)) throw new Error(`unknown topic "${topic}": pick one of ${GUIDE_TOPICS.join(", ")}`);
+  let text;
+  if (t === "workflow") text = packageText("skills/hyperdecks/chat.md");
+  else if (t === "layouts") text = layoutsTopic();
+  else {
+    const section = skillSection(packageText("skills/hyperdecks/SKILL.md"), t);
+    if (!section) throw new Error(`SKILL.md has no <!-- topic: ${t} --> section`);
+    text = CLI_NOTE + section;
+  }
+  return { topic: t, topics: GUIDE_TOPICS, text };
+}
+
+export async function guide(pos, opts = {}, { log = (line) => console.log(line) } = {}) {
+  const out = deckGuide(pos[0]);
+  if (!opts.json) log(out.text);
+  return out;
+}

package/src/hosted.mjs

@@ -0,0 +1,74 @@
+// The hosted deck source (convex/deckSources.ts) as ops: a deck's files kept on
+// Hyperdecks as a draft. The hosted MCP route, the stdio MCP and the CLI
+// (source.mjs) share these; no local file I/O, so the route can bundle them.
+import { api, client, target } from "./runtime.mjs";
+import { PRESENTER_STYLES } from "./checkRules.mjs";
+import { NARRATED_FILES, assembleLayoutDeck, fillTemplate } from "./layouts.mjs";
+
+export const SOURCE_FILES = Object.keys(NARRATED_FILES);
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const urls = (opts, slug, previewToken) => {
+  const base = target(opts).shareBase;
+  return { previewUrl: previewToken ? `${base}/p/${previewToken}` : null, dashboardUrl: `${base}/dashboard/d/${slug}` };
+};
+
+// Scaffold the files (the same templates as deck new) and register the draft.
+export async function hostedNewDeck(opts, { slug, title, layouts, presenterStyle } = {}) {
+  if (!slug || !title) throw new Error("slug and title are required");
+  if (!SLUG.test(slug)) throw new Error("slug must be lowercase letters, digits and dashes (max 64)");
+  if (presenterStyle !== undefined && !PRESENTER_STYLES.includes(presenterStyle)) throw new Error(`presenterStyle must be one of ${PRESENTER_STYLES.join(", ")}`);
+  const list = Array.isArray(layouts) ? layouts.join(",") : layouts;
+  const files = list
+    ? assembleLayoutDeck({ slug, title, presenterStyle, layouts: list })
+    : Object.fromEntries(Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle })]));
+  const made = await (await client(opts)).mutation(api.deckSources.create, { slug, title, files });
+  return { slug, rev: made.rev, files, ...urls(opts, slug, made.previewToken) };
+}
+
+export async function getDeckSource(opts, { slug, file } = {}) {
+  if (!slug) throw new Error("slug is required");
+  const got = await (await client(opts)).query(api.deckSources.get, { slug, ...(file ? { file } : {}) });
+  return { ...got, ...urls(opts, slug, got.previewToken) };
+}
+
+export async function writeDeckSource(opts, { slug, file, content, edits, baseRev } = {}) {
+  if (!slug || !file) throw new Error("slug and file are required");
+  if ((content === undefined) === (edits === undefined)) throw new Error("pass exactly one of content or edits");
+  const args = { slug, file, ...(content !== undefined ? { content: String(content) } : { edits }) };
+  if (baseRev !== undefined && baseRev !== null) args.baseRev = Number(baseRev);
+  return (await client(opts)).mutation(api.deckSources.write, args);
+}
+
+// A public URL (or a ChatGPT upload's download_url) filed under the deck.
+export async function uploadDeckAsset(opts, { slug, name, url, file } = {}) {
+  if (!slug) throw new Error("slug is required");
+  const from = url ?? file?.download_url;
+  if (!from) throw new Error("pass url, or file (a chat upload with a download_url)");
+  // A same-name upload replaces the earlier asset (and its URL stops working), so
+  // a name taken from the file or URL gets a unique suffix; only an explicit name replaces.
+  const fallback = file?.file_name ?? (() => { try { return new URL(from).pathname.split("/").pop(); } catch { return ""; } })();
+  const clean = (s) => String(s).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[^A-Za-z0-9]+/, "");
+  const unique = (s) => { const m = /^(.*?)(\.[A-Za-z0-9]{1,8})?$/.exec(clean(s) || "asset"); return `${(m[1] || "asset").slice(0, 100)}-${Date.now().toString(36)}${m[2] ?? ""}`; };
+  const assetName = name ? clean(name).slice(0, 120) || "asset" : unique(fallback || "asset");
+  return (await client(opts)).action(api.assetsNode.importAssetFromUrl, { slug, name: assetName, url: String(from), ...(file?.mime_type ? { mimeType: String(file.mime_type) } : {}) });
+}
+
+export async function hostedCheck(opts, { slug, forbid, maxDuration } = {}) {
+  if (!slug) throw new Error("slug is required");
+  const list = typeof forbid === "string" ? forbid.split(",").map((s) => s.trim()).filter(Boolean) : forbid;
+  return (await client(opts)).action(api.deckSources.check, { slug, ...(list?.length ? { forbid: list } : {}), ...(maxDuration ? { maxDuration: Number(maxDuration) } : {}) });
+}
+
+export async function hostedRelease(opts, { slug, recipients, qa, title, forbid, rev, voice } = {}) {
+  if (!slug) throw new Error("slug is required");
+  const list = typeof forbid === "string" ? forbid.split(",").map((s) => s.trim()).filter(Boolean) : forbid;
+  const args = { slug };
+  if (recipients?.length) args.recipients = recipients.map((r) => ({ recipient: String(r.recipient), ...(r.email ? { email: String(r.email) } : {}) }));
+  if (qa) args.qa = true;
+  if (title) args.title = String(title);
+  if (list?.length) args.forbid = list;
+  if (rev !== undefined && rev !== null) args.rev = Number(rev);
+  if (voice) args.voice = String(voice);
+  return (await client(opts)).action(api.deckSources.release, args);
+}
+