@mangomagic/cli 0.1.15 → 0.1.16

package/README.md

@@ -24,7 +24,7 @@ runs skip auth.
 | `mangomagic ask "..."` | Run one natural-language request. |
 | `mangomagic tools` | Show the CLI/MCP catalog. Add `--all` for the full list or `--json` for machine-readable output. |
 | `mangomagic tool <name> '{"json":"args"}'` | Run the same tool exposed to MCP clients. |
-| `mangomagic cards "idea"` | Create talking cards in the terminal and save them to your library. Add `--count 3`. |
+| `mangomagic cards "idea"` | Create talking cards, save cloud drafts, and export local files under `~/MangoMagic/exports/talking-cards`. Add `--count 3`. |
 | `mangomagic open cards` | Open the Talking Cards workspace in a browser. |
 | `mangomagic splash` | Show the splash once. `--anim`, `--loop` supported. |
 | `mangomagic mcp` | Run as a stdio MCP server. Wire into Claude Desktop / Cursor. |
@@ -65,6 +65,15 @@ npx -y @mangomagic/cli cards "why founder-led sales stalls" --count 3
 Obvious requests are handled locally. Fuzzy routing uses MangoMagic's backend AI
 router, so end users never need to provide a Moonshot/Kimi key.
 
+Talking card creation writes a local bundle by default:
+
+- `index.html` for a browser preview
+- `README.md` for the slide copy and edit links
+- `captions.txt` for captions
+- `cards.json` for structured data
+
+Set `MANGOMAGIC_EXPORT_DIR` to change the export root.
+
 ## Requirements
 
 Node 18 or later. The splash uses true-color ANSI; on terminals without it,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mangomagic/cli",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "MangoMagic CLI — sign in, manage episodes, and expose MangoMagic to MCP clients (Claude Desktop, Cursor).",
   "type": "module",
   "bin": {

package/src/chat/natural-language.mjs

@@ -2,6 +2,8 @@ import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { apiCall } from "../api.mjs";
 import { planWithKimi } from "../ai/kimi.mjs";
+import { exportTalkingCards } from "../export/cards.mjs";
+import { openUrl } from "../system/open-url.mjs";
 import { runCatalogTool } from "../tools/run.mjs";
 
 const GOLD = "\x1b[38;2;241;171;28m";
@@ -51,6 +53,13 @@ function localPlan(text) {
   if (t.includes("brand doc") || t.includes("brand colour") || t.includes("brand color")) {
     return { action: "open_brand_doc", args: {} };
   }
+  if (
+    /\b(save|export|download|where|file|files|computer|local|view|open)\b/.test(t) &&
+    /\b(them|these|those|cards?|carousels?|files?)\b/.test(t) &&
+    !/\b(create|generate|make)\b/.test(t)
+  ) {
+    return { action: "export_latest_cards", args: { open: /\b(open|view|show)\b/.test(t) } };
+  }
   if (t.includes("talking card") || t.includes("carousel") || /\bcards?\b/.test(t)) {
     return { action: "create_talking_cards", args: { focus: raw, count: inferCount(raw) } };
   }
@@ -338,6 +347,29 @@ function cardUrl(card) {
   return card?.id ? `https://mangomagic.live/carousels/${card.id}` : null;
 }
 
+function printExportInfo(info, { opened = false } = {}) {
+  process.stdout.write(`${BOLD}Saved locally.${RESET}\n`);
+  process.stdout.write(`  Folder: ${GOLD}${info.dir}${RESET}\n`);
+  process.stdout.write(`  View:   ${GOLD}${info.indexPath}${RESET}${opened ? ` ${DIM}(opened)${RESET}` : ""}\n`);
+  process.stdout.write(`  Copy:   ${GOLD}${info.markdownPath}${RESET}\n`);
+  process.stdout.write(`  Data:   ${GOLD}${info.jsonPath}${RESET}\n`);
+}
+
+function exportLatestCards(state = {}, { open = false } = {}) {
+  let info = state.latestCardExport;
+  if (!info && state.latestCards) {
+    info = exportTalkingCards(state.latestCards, { focus: state.latestCardFocus || "talking-cards" });
+    state.latestCardExport = info;
+  }
+  if (!info) {
+    process.stdout.write(`No recent talking cards in this session yet. Try ${GOLD}create 3 talking cards about founder-led sales${RESET} first.\n`);
+    return null;
+  }
+  const opened = open ? openUrl(info.indexPath) : false;
+  printExportInfo(info, { opened });
+  return info;
+}
+
 export function printCards(result) {
   const cards = Array.isArray(result?.carousels) ? result.carousels : [];
   if (!cards.length) {
@@ -348,6 +380,7 @@ export function printCards(result) {
   process.stdout.write(`${BOLD}Created ${cards.length} talking card${cards.length === 1 ? "" : "s"}.${RESET}\n\n`);
   for (const [idx, card] of cards.entries()) {
     process.stdout.write(`${GOLD}${idx + 1}. ${card.title || "Untitled card"}${RESET}\n`);
+    if (card.hook) process.stdout.write(`   Hook: ${card.hook}\n`);
     if (card.seam) process.stdout.write(`   ${DIM}${card.seam}${RESET}\n`);
     const slides = Array.isArray(card?.spec?.slides) ? card.spec.slides : [];
     for (const slide of slides.slice(0, 8)) {
@@ -361,7 +394,7 @@ export function printCards(result) {
   }
 }
 
-export async function createTalkingCards({ focus, count = 3 } = {}) {
+export async function createTalkingCards({ focus, count = 3, state = null, saveLocal = true, openLocal = false } = {}) {
   const cleanFocus = compact(focus);
   if (!cleanFocus) {
     process.stdout.write(`Give me an idea, for example:\n  ${GOLD}mangomagic cards "why founder-led sales stalls" --count 3${RESET}\n`);
@@ -374,6 +407,25 @@ export async function createTalkingCards({ focus, count = 3 } = {}) {
       body: { focus: cleanFocus, count: Math.max(1, Math.min(Number(count || 3), 10)) },
     });
     printCards(result);
+    if (state) {
+      state.latestCards = result;
+      state.latestCardFocus = cleanFocus;
+    }
+    if (saveLocal) {
+      try {
+        const info = exportTalkingCards(result, { focus: cleanFocus });
+        result.localExport = info;
+        if (state) state.latestCardExport = info;
+        if (info) {
+          const opened = openLocal ? openUrl(info.indexPath) : false;
+          printExportInfo(info, { opened });
+        }
+      } catch (err) {
+        result.localExportError = err?.message ?? String(err);
+        process.stdout.write(`${DIM}Created in MangoMagic Cloud, but I could not write the local export: ${result.localExportError}${RESET}\n`);
+      }
+    }
+    return result;
   } catch (err) {
     const message = err?.message ?? String(err);
     if (message.includes("HTTP 404")) {
@@ -385,13 +437,14 @@ export async function createTalkingCards({ focus, count = 3 } = {}) {
   }
 }
 
-export async function handleNaturalLanguage(text, actions, { allowModel = true } = {}) {
+export async function handleNaturalLanguage(text, actions, { allowModel = true, state = null } = {}) {
   let plan = localPlan(text);
   if (!plan && allowModel) {
     try {
       plan = await planWithKimi(text, {
         availableTools: [
           "create_talking_cards",
+          "export_latest_cards",
           "list_inbox",
           "list_leads",
           "analyze_guests",
@@ -430,7 +483,9 @@ ${DIM}${err?.message ?? err}${RESET}
     case "exit":
       return "exit";
     case "create_talking_cards":
-      return createTalkingCards({ focus: args.focus || text, count: args.count || 3 });
+      return createTalkingCards({ focus: args.focus || text, count: args.count || 3, state });
+    case "export_latest_cards":
+      return exportLatestCards(state, { open: Boolean(args.open) });
     case "open_cards":
       return actions.cards({ path: "/carousels/generate", focus: args.focus });
     case "open_brand_doc":
@@ -527,6 +582,7 @@ ${DIM}${err?.message ?? err}${RESET}
 
 export async function chat(actions, { showHeader = true } = {}) {
   const rl = readline.createInterface({ input, output });
+  const state = {};
   if (showHeader) {
     process.stdout.write(`
 ${BOLD}MangoMagic Chat${RESET}
@@ -544,7 +600,7 @@ Type ${DIM}exit${RESET} to leave.
         if (err?.message === "readline was closed") break;
         throw err;
       }
-      const result = await handleNaturalLanguage(text, actions);
+      const result = await handleNaturalLanguage(text, actions, { state });
       if (result === "exit") break;
       process.stdout.write("\n");
     }

package/src/export/cards.mjs

@@ -0,0 +1,278 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+function compact(s) {
+  return String(s || "").trim().replace(/\s+/g, " ");
+}
+
+function slugify(s) {
+  return compact(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60) || "talking-cards";
+}
+
+function stamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+}
+
+function escapeHtml(s) {
+  return String(s ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function cardsFrom(result) {
+  return Array.isArray(result?.carousels) ? result.carousels : [];
+}
+
+function titleFromSlug(s) {
+  return compact(s)
+    .replace(/[-_]+/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function cardTitle(card) {
+  return titleFromSlug(card?.title) || "Untitled card";
+}
+
+function lineText(line) {
+  if (typeof line === "string") return line;
+  return line?.text || "";
+}
+
+function slideLines(slide) {
+  return Array.isArray(slide?.lines) ? slide.lines.map(lineText).filter(Boolean) : [];
+}
+
+function cardUrl(card) {
+  return card?.id ? `https://mangomagic.live/carousels/${card.id}` : "";
+}
+
+function hasFullSlideSpec(card) {
+  return Array.isArray(card?.spec?.slides) && card.spec.slides.length > 0;
+}
+
+function line(text, size = "body", gold = false) {
+  return { text, size, gold };
+}
+
+function fallbackSlides(card) {
+  const hook = compact(card?.hook) || cardTitle(card);
+  const seam = compact(card?.seam) || "A useful idea worth turning into a post.";
+  const engine = compact(card?.engine);
+  return [
+    {
+      type: "hook",
+      lines: [line(hook, "hook", true)],
+      swipe: true,
+      swipe_label: "Swipe",
+    },
+    {
+      type: "build",
+      lines: [line(seam, "body")],
+      swipe: true,
+      swipe_label: "Then",
+    },
+    {
+      type: "turn",
+      lines: [
+        line("Name the tension.", "punch", true),
+        line("Make it obvious enough that the right reader feels seen.", "body"),
+      ],
+      swipe: true,
+      swipe_label: "Use it",
+    },
+    {
+      type: "cta",
+      lines: [
+        line("Draft saved in MangoMagic.", "punch", true),
+        line("Use this local preview as the working copy, then polish the cloud draft.", "small"),
+      ],
+      swipe: false,
+      swipe_label: "",
+    },
+  ].map((slide) => engine && slide.type === "cta"
+    ? { ...slide, lines: [...slide.lines, line(`Engine: ${engine}`, "small")] }
+    : slide);
+}
+
+function slidesFor(card) {
+  return hasFullSlideSpec(card) ? card.spec.slides : fallbackSlides(card);
+}
+
+function captionFor(card) {
+  if (card?.caption) return card.caption;
+  const parts = [
+    compact(card?.hook),
+    compact(card?.seam),
+    "Turn this into a post that makes the right people feel caught in the act.",
+    cardUrl(card) ? `Edit the cloud draft: ${cardUrl(card)}` : "",
+  ].filter(Boolean);
+  return parts.join("\n\n");
+}
+
+function cardForExport(card) {
+  return {
+    ...card,
+    localPreview: {
+      derived: !hasFullSlideSpec(card),
+      slides: slidesFor(card),
+      caption: captionFor(card),
+    },
+  };
+}
+
+function exportRoot() {
+  return process.env.MANGOMAGIC_EXPORT_DIR || join(homedir(), "MangoMagic", "exports", "talking-cards");
+}
+
+function markdownFor(cards, meta) {
+  const out = [
+    `# MangoMagic Talking Cards`,
+    "",
+    `Exported: ${new Date().toLocaleString()}`,
+    `Directory: ${meta.dir}`,
+    "",
+  ];
+
+  cards.forEach((card, cardIdx) => {
+    out.push(`## ${cardIdx + 1}. ${cardTitle(card)}`, "");
+    if (card.seam) out.push(`Scenario: ${card.seam}`, "");
+    if (card.hook) out.push(`Hook: ${card.hook}`, "");
+    if (card.engine) out.push(`Engine: ${card.engine}`, "");
+    if (cardUrl(card)) out.push(`Cloud edit link: ${cardUrl(card)}`, "");
+
+    if (!hasFullSlideSpec(card)) {
+      out.push("Note: the cloud response did not include the full slide spec, so this local preview was derived from the returned hook and scenario.", "");
+    }
+
+    const slides = slidesFor(card);
+    if (slides.length) {
+      out.push("### Slides", "");
+      slides.forEach((slide, idx) => {
+        out.push(`Slide ${idx + 1}${slide.type ? ` (${slide.type})` : ""}`);
+        for (const line of slideLines(slide)) out.push(`- ${line}`);
+        if (slide.swipe_label) out.push(`- Swipe label: ${slide.swipe_label}`);
+        out.push("");
+      });
+    }
+
+    out.push("### Caption", "", captionFor(card), "");
+  });
+
+  return out.join("\n");
+}
+
+function captionsFor(cards) {
+  return cards.map((card, idx) => [
+    `# ${idx + 1}. ${cardTitle(card)}`,
+    captionFor(card),
+    cardUrl(card) ? `Edit: ${cardUrl(card)}` : "",
+  ].filter(Boolean).join("\n")).join("\n\n---\n\n");
+}
+
+function slideHtml(card, slide, idx, total) {
+  const bg = card?.spec?.bg || "#111111";
+  const ink = card?.spec?.ink || "#f8f4ec";
+  const accent = card?.spec?.accent || "#f1ab1c";
+  const lines = slideLines(slide);
+  return `
+    <section class="slide" style="--bg:${escapeHtml(bg)};--ink:${escapeHtml(ink)};--accent:${escapeHtml(accent)}">
+      <div class="slide-kicker">${idx + 1}/${total}${slide.type ? ` · ${escapeHtml(slide.type)}` : ""}</div>
+      <div class="slide-lines">
+        ${lines.map((line, lineIdx) => `<p class="${lineIdx === 0 ? "primary" : ""}">${escapeHtml(line)}</p>`).join("")}
+      </div>
+      ${slide.swipe_label ? `<div class="swipe">${escapeHtml(slide.swipe_label)}</div>` : ""}
+      ${card?.spec?.footer ? `<div class="footer">${escapeHtml(card.spec.footer)}</div>` : ""}
+    </section>`;
+}
+
+function htmlFor(cards) {
+  const decks = cards.map((card, idx) => {
+    const slides = slidesFor(card);
+    return `
+      <article class="deck">
+        <header>
+          <p class="eyebrow">Talking Card ${idx + 1}</p>
+          <h2>${escapeHtml(cardTitle(card))}</h2>
+          ${card.seam ? `<p>${escapeHtml(card.seam)}</p>` : ""}
+          ${cardUrl(card) ? `<a href="${escapeHtml(cardUrl(card))}">Open cloud draft</a>` : ""}
+          ${!hasFullSlideSpec(card) ? `<p class="note">Local preview derived from returned hook and scenario.</p>` : ""}
+        </header>
+        <div class="slides">
+          ${slides.map((slide, slideIdx) => slideHtml(card, slide, slideIdx, slides.length)).join("")}
+        </div>
+        <section class="caption"><h3>Caption</h3><pre>${escapeHtml(captionFor(card))}</pre></section>
+      </article>`;
+  }).join("\n");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>MangoMagic Talking Cards</title>
+  <style>
+    :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #f7f4ef; color: #1d1c19; }
+    * { box-sizing: border-box; }
+    body { margin: 0; padding: 32px; }
+    main { max-width: 1180px; margin: 0 auto; }
+    h1 { margin: 0 0 8px; font-size: 32px; }
+    .meta { color: #6f6a61; margin-bottom: 32px; }
+    .deck { border-top: 1px solid #d8d0c2; padding: 28px 0 36px; }
+    header { max-width: 760px; margin-bottom: 20px; }
+    .eyebrow { color: #9b6b0f; text-transform: uppercase; font-size: 12px; font-weight: 800; letter-spacing: .08em; }
+    h2 { margin: 0 0 8px; font-size: 26px; }
+    a { color: #9b6b0f; font-weight: 700; }
+    .note { color: #7b725f; font-size: 14px; }
+    .slides { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 18px; }
+    .slide { aspect-ratio: 1 / 1; display: flex; flex-direction: column; justify-content: center; padding: 24px; position: relative; background: var(--bg); color: var(--ink); border-radius: 10px; overflow: hidden; box-shadow: 0 16px 36px rgba(20, 16, 8, .16); }
+    .slide-kicker { position: absolute; top: 14px; left: 16px; color: var(--accent); font-size: 12px; font-weight: 800; text-transform: uppercase; }
+    .slide-lines p { margin: 10px 0; font-size: 24px; line-height: 1.02; font-weight: 800; }
+    .slide-lines .primary { color: var(--accent); font-size: 30px; }
+    .swipe { position: absolute; right: 16px; bottom: 40px; color: var(--accent); font-weight: 800; }
+    .footer { position: absolute; left: 16px; right: 16px; bottom: 14px; font-size: 11px; color: color-mix(in srgb, var(--ink), transparent 36%); }
+    .caption { margin-top: 20px; max-width: 760px; background: #fff; border: 1px solid #e3dccf; border-radius: 10px; padding: 18px; }
+    .caption h3 { margin-top: 0; }
+    pre { white-space: pre-wrap; font: inherit; margin: 0; }
+    .empty { background: #24211c; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>MangoMagic Talking Cards</h1>
+    <p class="meta">Exported ${escapeHtml(new Date().toLocaleString())}</p>
+    ${decks}
+  </main>
+</body>
+</html>`;
+}
+
+export function exportTalkingCards(result, { focus = "talking-cards" } = {}) {
+  const cards = cardsFrom(result);
+  if (!cards.length) return null;
+
+  const dir = join(exportRoot(), `${stamp()}_${slugify(focus || cards[0]?.title)}`);
+  mkdirSync(dir, { recursive: true });
+
+  const meta = {
+    dir,
+    count: cards.length,
+    indexPath: join(dir, "index.html"),
+    markdownPath: join(dir, "README.md"),
+    jsonPath: join(dir, "cards.json"),
+    captionsPath: join(dir, "captions.txt"),
+  };
+
+  writeFileSync(meta.jsonPath, JSON.stringify({ ...result, carousels: cards.map(cardForExport), exportedAt: new Date().toISOString() }, null, 2));
+  writeFileSync(meta.markdownPath, markdownFor(cards, meta));
+  writeFileSync(meta.captionsPath, captionsFor(cards));
+  writeFileSync(meta.indexPath, htmlFor(cards));
+
+  return meta;
+}

package/src/index.mjs

@@ -45,6 +45,7 @@ ${BOLD}You can type naturally now.${RESET}
 
 Try:
   ${GOLD}create 3 talking cards about founder-led sales${RESET}
+  ${GOLD}where are those files?${RESET}
   ${GOLD}analyse my guests${RESET}
   ${GOLD}show me my clips${RESET}
   ${GOLD}what episodes do I have?${RESET}
@@ -72,6 +73,7 @@ ${DIM}Try this in Claude, Cursor, or Codex after MCP is connected:${RESET}
 ${DIM}Talk in the terminal:${RESET}
   ${GOLD}${COMMAND_PREFIX} login${RESET}
   ${GOLD}${COMMAND_PREFIX} create talking cards about my LinkedIn idea${RESET}
+  ${GOLD}${COMMAND_PREFIX} cards "why founder-led sales stalls" --count 3${RESET}
 
 ${DIM}Open app:${RESET} ${APP_ORIGIN}
 ${DIM}Token cache:${RESET} ${credentialsPath()}

package/src/tools/catalog.mjs

@@ -42,12 +42,13 @@ export const MCP_TOOL_CATALOG = [
   },
   {
     name: "create_talking_cards",
-    description: "Generate branded LinkedIn-ready talking cards from a short idea and save them as draft carousels.",
+    description: "Generate branded LinkedIn-ready talking cards from a short idea, save cloud drafts, and export a local preview bundle.",
     inputSchema: {
       type: "object",
       properties: {
         focus: { type: "string", description: "The idea, theme, or LinkedIn angle to turn into cards" },
         count: { type: "integer", minimum: 1, maximum: 10, default: 3 },
+        saveLocal: { type: "boolean", default: true, description: "Write index.html, README.md, captions.txt, and cards.json to ~/MangoMagic/exports/talking-cards" },
       },
       required: ["focus"],
     },
@@ -65,7 +66,7 @@ export const QUICK_WINS = [
   {
     command: `${COMMAND_PREFIX} cards "why founder-led sales stalls" --count 3`,
     title: "Create Talking Cards",
-    description: "Generate LinkedIn-ready talking cards from the terminal and save them to your library.",
+    description: "Generate LinkedIn-ready talking cards, save cloud drafts, and export local files you can open immediately.",
     status: "ready",
   },
   {
@@ -91,7 +92,7 @@ export const QUICK_WINS = [
 export const NEXT_WORKFLOWS = [
   {
     name: "create_talking_cards",
-    description: "Generate a batch of branded talking cards from a short idea and save them to the user's carousel library.",
+    description: "Generate a batch of branded talking cards, save cloud drafts, and write local preview/copy/data files.",
   },
   {
     name: "sync_linkedin_brand_context",

package/src/tools/run.mjs

@@ -1,4 +1,5 @@
 import { apiCall } from "../api.mjs";
+import { exportTalkingCards } from "../export/cards.mjs";
 import { ALL_MCP_TOOL_CATALOG } from "./catalog.mjs";
 import { functionNameFromEdgeTool } from "./edge-functions.mjs";
 
@@ -56,12 +57,22 @@ const BUILTIN_TOOL_HANDLERS = {
   list_episodes: async ({ limit = 10 }) => apiCall("cli-list-episodes", { body: { limit } }),
   get_episode: async ({ episode }) => apiCall("cli-get-episode", { body: { episode } }),
   search_episodes: async ({ query }) => apiCall("cli-search-episodes", { body: { query } }),
-  create_talking_cards: async ({ focus, count = 3 }) => apiCall("cli-create-talking-cards", {
-    body: {
-      focus,
-      count: Math.max(1, Math.min(Number(count || 3), 10)),
-    },
-  }),
+  create_talking_cards: async ({ focus, count = 3, saveLocal = true } = {}) => {
+    const result = await apiCall("cli-create-talking-cards", {
+      body: {
+        focus,
+        count: Math.max(1, Math.min(Number(count || 3), 10)),
+      },
+    });
+    if (saveLocal !== false) {
+      try {
+        result.localExport = exportTalkingCards(result, { focus });
+      } catch (err) {
+        result.localExportError = err?.message ?? String(err);
+      }
+    }
+    return result;
+  },
   qualify_leads: async ({ stage = "all", limit = 10 } = {}) => {
     const leads = await apiCall("magic-assistant", {
       body: {