@mangomagic/cli 0.1.3 → 0.1.4

package/README.md

@@ -18,6 +18,9 @@ at `~/.mangomagic/credentials.json` (mode 0600) so the next runs skip auth.
 | `mangomagic logout` | Forget the cached token. |
 | `mangomagic whoami` | Show the cached identity. |
 | `mangomagic home` | Show fast wins after sign-in. |
+| `mangomagic chat` | Start an interactive natural-language session. |
+| `mangomagic ask "..."` | Run one natural-language request. |
+| `mangomagic key set` | Store a Moonshot/Kimi API key in macOS Keychain, or a mode-0600 fallback file on other platforms. |
 | `mangomagic tools` | Show available MCP tools and near-next workflows. Add `--json` for machine-readable output. |
 | `mangomagic cards` | Open the Talking Cards workspace. Add `--no-open` to print the URL only. |
 | `mangomagic splash` | Show the splash once. `--anim`, `--loop` supported. |
@@ -42,6 +45,20 @@ Add to Claude Desktop's `claude_desktop_config.json` (or Cursor's MCP settings):
 The MCP server uses the same token cached by `mangomagic login`, so make sure
 you sign in first.
 
+## Natural language
+
+```bash
+npx -y @mangomagic/cli chat
+npx -y @mangomagic/cli create talking cards about AI adoption
+```
+
+Obvious requests are handled locally. Fuzzy routing uses Kimi K2.6 through the
+Moonshot API. Store the key securely:
+
+```bash
+npx -y @mangomagic/cli key set
+```
+
 ## 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.3",
+  "version": "0.1.4",
   "description": "MangoMagic CLI — sign in, manage episodes, and expose MangoMagic to MCP clients (Claude Desktop, Cursor).",
   "type": "module",
   "bin": {

package/src/ai/kimi.mjs

@@ -0,0 +1,66 @@
+import { loadMoonshotKey } from "../secrets/moonshot-key-store.mjs";
+
+export class MissingMoonshotKeyError extends Error {
+  constructor() {
+    super("Missing Moonshot API key.");
+    this.name = "MissingMoonshotKeyError";
+  }
+}
+
+export async function planWithKimi(userText, context = {}) {
+  const secret = loadMoonshotKey();
+  if (!secret?.key) throw new MissingMoonshotKeyError();
+
+  const response = await fetch("https://api.moonshot.ai/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${secret.key}`,
+    },
+    body: JSON.stringify({
+      model: "kimi-k2.6",
+      messages: [
+        {
+          role: "system",
+          content: `You route natural-language terminal requests for MangoMagic.
+
+Return only compact JSON. No markdown.
+
+Allowed actions:
+- open_cards: open the Talking Cards generator. Args: {"focus": optional string}
+- open_brand_doc: open Brand Doc setup/review.
+- show_tools: show available MCP tools.
+- mcp_config: print MCP config.
+- list_episodes: list recent episodes. Args: {"limit": integer 1-10}
+- search_episodes: search episodes. Args: {"query": string}
+- get_episode: get one episode. Args: {"episode": id or slug}
+- home: show fast wins.
+- answer: answer briefly without external action. Args: {"text": string}
+
+Prefer a direct tool action over a chatty answer. If the user asks to create talking cards, choose open_cards and preserve their idea as focus.`,
+        },
+        {
+          role: "user",
+          content: JSON.stringify({ userText, context }),
+        },
+      ],
+      thinking: { type: "disabled" },
+      max_tokens: 700,
+    }),
+  });
+
+  const bodyText = await response.text();
+  let body;
+  try { body = JSON.parse(bodyText); } catch { body = null; }
+
+  if (!response.ok) {
+    const message = body?.error?.message || body?.error || bodyText || `HTTP ${response.status}`;
+    throw new Error(`Kimi request failed: ${message}`);
+  }
+
+  const content = body?.choices?.[0]?.message?.content;
+  if (!content) throw new Error("Kimi returned no routing decision.");
+
+  const jsonText = String(content).trim().replace(/^```json\s*/i, "").replace(/^```\s*/i, "").replace(/```$/i, "").trim();
+  return JSON.parse(jsonText);
+}

package/src/chat/natural-language.mjs

@@ -0,0 +1,173 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { apiCall } from "../api.mjs";
+import { MissingMoonshotKeyError, planWithKimi } from "../ai/kimi.mjs";
+import { moonshotKeyStorageHint } from "../secrets/moonshot-key-store.mjs";
+
+const GOLD = "\x1b[38;2;241;171;28m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+
+function compact(s) {
+  return String(s || "").trim().replace(/\s+/g, " ");
+}
+
+function localPlan(text) {
+  const raw = compact(text);
+  const t = raw.toLowerCase();
+  if (!t) return { action: "answer", args: { text: "" } };
+
+  if (/^(exit|quit|bye)$/i.test(t)) return { action: "exit", args: {} };
+  if (t.includes("brand doc") || t.includes("brand colour") || t.includes("brand color")) {
+    return { action: "open_brand_doc", args: {} };
+  }
+  if (t.includes("talking card") || t.includes("carousel") || /\bcards?\b/.test(t)) {
+    return { action: "open_cards", args: { focus: raw } };
+  }
+  if (t.includes("mcp") && (t.includes("config") || t.includes("connect") || t.includes("claude") || t.includes("cursor") || t.includes("codex"))) {
+    return { action: "mcp_config", args: {} };
+  }
+  if (t.includes("tool") || t.includes("what can")) return { action: "show_tools", args: {} };
+  if (t.includes("latest episode") || t.includes("recent episode") || t === "episodes" || t.includes("list episodes")) {
+    return { action: "list_episodes", args: { limit: 5 } };
+  }
+  const searchMatch = raw.match(/search(?: my)? episodes? (?:for|about)\s+(.+)/i);
+  if (searchMatch?.[1]) return { action: "search_episodes", args: { query: searchMatch[1] } };
+  const getMatch = raw.match(/(?:get|show|open)(?: episode)?\s+([a-z0-9][a-z0-9_-]{5,})/i);
+  if (getMatch?.[1]) return { action: "get_episode", args: { episode: getMatch[1] } };
+  if (t.includes("home") || t.includes("help")) return { action: "home", args: {} };
+
+  return null;
+}
+
+function asArray(data) {
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.episodes)) return data.episodes;
+  if (Array.isArray(data?.results)) return data.results;
+  if (Array.isArray(data?.data)) return data.data;
+  return [];
+}
+
+function printEpisodeList(data) {
+  const rows = asArray(data);
+  if (!rows.length) {
+    process.stdout.write("No episodes found.\n");
+    return;
+  }
+  for (const ep of rows.slice(0, 10)) {
+    const title = ep.title || ep.name || ep.slug || ep.id || "Untitled episode";
+    const id = ep.id || ep.slug || "";
+    process.stdout.write(`  ${GOLD}${title}${RESET}${id ? ` ${DIM}${id}${RESET}` : ""}\n`);
+  }
+}
+
+function printEpisode(data) {
+  const ep = data?.episode || data?.data || data;
+  if (!ep || typeof ep !== "object") {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(`${BOLD}${ep.title || ep.name || ep.id || "Episode"}${RESET}\n`);
+  if (ep.summary) process.stdout.write(`\n${ep.summary}\n`);
+  if (Array.isArray(ep.takeaways) && ep.takeaways.length) {
+    process.stdout.write("\nTakeaways:\n");
+    for (const item of ep.takeaways.slice(0, 8)) process.stdout.write(`  - ${item}\n`);
+  }
+  if (ep.id) process.stdout.write(`\n${DIM}${ep.id}${RESET}\n`);
+}
+
+export async function handleNaturalLanguage(text, actions, { allowModel = true } = {}) {
+  let plan = localPlan(text);
+  if (!plan && allowModel) {
+    try {
+      plan = await planWithKimi(text, {
+        availableTools: ["open_cards", "open_brand_doc", "show_tools", "mcp_config", "list_episodes", "search_episodes", "get_episode", "home"],
+      });
+    } catch (err) {
+      if (err instanceof MissingMoonshotKeyError) {
+        process.stdout.write(`
+${BOLD}Natural-language routing needs a Kimi API key for fuzzy requests.${RESET}
+
+Obvious commands still work, for example:
+  ${GOLD}npx -y @mangomagic/cli create talking cards${RESET}
+  ${GOLD}npx -y @mangomagic/cli search episodes for AI adoption${RESET}
+
+Set Kimi up securely:
+  ${GOLD}npx -y @mangomagic/cli key set${RESET}
+
+Storage: ${moonshotKeyStorageHint()}
+`);
+        return;
+      }
+      throw err;
+    }
+  }
+
+  if (!plan) {
+    process.stdout.write("I could not map that to a MangoMagic action yet. Try `tools` or `chat`.\n");
+    return;
+  }
+
+  const action = plan.action;
+  const args = plan.args || {};
+  switch (action) {
+    case "exit":
+      return "exit";
+    case "open_cards":
+      return actions.cards({ path: "/carousels/generate", focus: args.focus });
+    case "open_brand_doc":
+      return actions.openPath("/carousels/doc");
+    case "show_tools":
+      return actions.tools();
+    case "mcp_config":
+      return actions.mcpConfig();
+    case "home":
+      return actions.home();
+    case "list_episodes": {
+      const data = await apiCall("cli-list-episodes", { body: { limit: Math.max(1, Math.min(Number(args.limit || 5), 10)) } });
+      return printEpisodeList(data);
+    }
+    case "search_episodes": {
+      if (!args.query) {
+        process.stdout.write("What should I search for?\n");
+        return;
+      }
+      const data = await apiCall("cli-search-episodes", { body: { query: args.query } });
+      return printEpisodeList(data);
+    }
+    case "get_episode": {
+      if (!args.episode) {
+        process.stdout.write("Which episode id or slug?\n");
+        return;
+      }
+      const data = await apiCall("cli-get-episode", { body: { episode: args.episode } });
+      return printEpisode(data);
+    }
+    case "answer":
+      process.stdout.write(`${args.text || "I can help with MangoMagic episodes, talking cards, and MCP setup."}\n`);
+      return;
+    default:
+      process.stdout.write(`I do not know how to run action "${action}" yet.\n`);
+  }
+}
+
+export async function chat(actions) {
+  const rl = readline.createInterface({ input, output });
+  process.stdout.write(`
+${BOLD}MangoMagic Chat${RESET}
+Type what you want. Try: ${GOLD}create talking cards about AI adoption${RESET}
+Type ${DIM}exit${RESET} to leave.
+
+`);
+  try {
+    while (true) {
+      const text = await rl.question(`${GOLD}mango>${RESET} `);
+      const result = await handleNaturalLanguage(text, actions);
+      if (result === "exit") break;
+      process.stdout.write("\n");
+    }
+  } finally {
+    rl.close();
+  }
+}

package/src/index.mjs

@@ -1,8 +1,11 @@
 import { deviceLogin } from "./auth/device-flow.mjs";
+import { chat, handleNaturalLanguage } from "./chat/natural-language.mjs";
 import { loadToken, saveToken, clearToken, credentialsPath } from "./auth/token-store.mjs";
 import { APP_ORIGIN } from "./config.mjs";
+import { clearMoonshotKey, loadMoonshotKey, moonshotKeyStorageHint, saveMoonshotKey } from "./secrets/moonshot-key-store.mjs";
 import { openUrl } from "./system/open-url.mjs";
-import { MCP_TOOL_CATALOG, NEXT_WORKFLOWS, QUICK_WINS } from "./tools/catalog.mjs";
+import { COMMAND_PREFIX, MCP_TOOL_CATALOG, NEXT_WORKFLOWS, QUICK_WINS } from "./tools/catalog.mjs";
+import { promptHidden } from "./ui/prompt-hidden.mjs";
 import { playSplash } from "./ui/splash.mjs";
 
 const GOLD = "\x1b[38;2;241;171;28m";
@@ -18,6 +21,8 @@ ${BOLD}mangomagic${RESET}  ${DIM}— sign into MangoMagic and bring your account
   ${GOLD}mangomagic logout${RESET}      Forget the token cached on this machine.
   ${GOLD}mangomagic whoami${RESET}      Show the cached identity.
   ${GOLD}mangomagic home${RESET}        Show fast wins for creating value right now.
+  ${GOLD}mangomagic chat${RESET}        Talk to MangoMagic in natural language.
+  ${GOLD}mangomagic key set${RESET}     Store a Moonshot/Kimi API key securely.
   ${GOLD}mangomagic tools${RESET}       Show available MCP tools and next workflows.
   ${GOLD}mangomagic cards${RESET}       Open the Talking Cards workspace.
   ${GOLD}mangomagic splash${RESET}      Show the MangoMagic splash once. Add --anim or --loop for motion.
@@ -26,6 +31,9 @@ ${BOLD}mangomagic${RESET}  ${DIM}— sign into MangoMagic and bring your account
   ${GOLD}mangomagic help${RESET}        This message.
 
 Token cache: ${credentialsPath()}
+
+If \`mangomagic\` is not installed globally, use:
+  ${GOLD}${COMMAND_PREFIX} chat${RESET}
 `);
 }
 
@@ -44,6 +52,10 @@ ${DIM}Try this in Claude, Cursor, or Codex after MCP is connected:${RESET}
   "Use MangoMagic to search my episodes for AI adoption."
   "Use MangoMagic to get my latest episode and draft five LinkedIn post ideas."
 
+${DIM}Talk in the terminal:${RESET}
+  ${GOLD}${COMMAND_PREFIX} chat${RESET}
+  ${GOLD}${COMMAND_PREFIX} create talking cards about my LinkedIn idea${RESET}
+
 ${DIM}Open app:${RESET} ${APP_ORIGIN}
 ${DIM}Token cache:${RESET} ${credentialsPath()}
 `);
@@ -121,13 +133,22 @@ function whoami() {
   process.stdout.write(`Signed in (user ${t.userId ?? "?"}), approved ${t.approvedAt}\n`);
 }
 
-function cards({ openInBrowser = true } = {}) {
-  const url = `${APP_ORIGIN}/carousels`;
+function openPath(path) {
+  const url = `${APP_ORIGIN}${path}`;
+  const shouldOpen = process.env.MANGOMAGIC_CLI_NO_OPEN !== "1";
+  const opened = shouldOpen ? openUrl(url) : false;
+  if (shouldOpen) process.stdout.write(opened ? `Opening ${url}\n` : "Could not open a browser automatically.\n");
+  process.stdout.write(`${GOLD}${url}${RESET}\n`);
+}
+
+function cards({ openInBrowser = process.env.MANGOMAGIC_CLI_NO_OPEN !== "1", path = "/carousels/generate", focus = null } = {}) {
+  const url = `${APP_ORIGIN}${path}`;
   if (openInBrowser) {
     const opened = openUrl(url);
     process.stdout.write(opened ? "Opening Talking Cards...\n" : "Could not open a browser automatically.\n");
   }
   process.stdout.write(`${GOLD}${url}${RESET}\n`);
+  if (focus) process.stdout.write(`${DIM}Idea: ${focus}${RESET}\n`);
 }
 
 async function mcpServer() {
@@ -148,6 +169,33 @@ function mcpConfig() {
   process.stdout.write(JSON.stringify(cfg, null, 2) + "\n");
 }
 
+async function keyCommand(argv) {
+  const sub = argv[0] || "status";
+  if (sub === "set") {
+    const key = await promptHidden("Moonshot API key: ");
+    const where = saveMoonshotKey(key);
+    process.stdout.write(`Saved Moonshot API key in ${where}.\n`);
+    return;
+  }
+  if (sub === "clear" || sub === "delete" || sub === "remove") {
+    const cleared = clearMoonshotKey();
+    process.stdout.write(cleared ? "Moonshot API key removed.\n" : "No stored Moonshot API key found.\n");
+    return;
+  }
+  if (sub === "status") {
+    const key = loadMoonshotKey();
+    if (key) process.stdout.write(`Moonshot API key found via ${key.source}.\n`);
+    else process.stdout.write(`No Moonshot API key found. Store one with \`${COMMAND_PREFIX} key set\`.\nStorage: ${moonshotKeyStorageHint()}\n`);
+    return;
+  }
+  process.stderr.write(`Unknown key command: ${sub}\n`);
+  process.exit(2);
+}
+
+function actions() {
+  return { cards, openPath, tools, mcpConfig, home };
+}
+
 export async function run(argv) {
   const cmd = argv[0] ?? (loadToken() ? "home" : "login");
   switch (cmd) {
@@ -155,6 +203,10 @@ export async function run(argv) {
     case "logout":     return logout();
     case "whoami":     return whoami();
     case "home":       return home();
+    case "chat":       return chat(actions());
+    case "ask":        return handleNaturalLanguage(argv.slice(1).join(" "), actions());
+    case "key":
+    case "kimi-key":   return keyCommand(argv.slice(1));
     case "tools":      return tools({ json: argv.includes("--json") });
     case "cards":      return cards({ openInBrowser: !argv.includes("--no-open") && process.env.MANGOMAGIC_CLI_NO_OPEN !== "1" });
     case "splash":     return playSplash({ mode: argv.includes("--loop") ? "loop" : argv.includes("--anim") ? "anim" : "static" });
@@ -164,8 +216,6 @@ export async function run(argv) {
     case "--help":
     case "-h":         return help();
     default:
-      process.stderr.write(`Unknown command: ${cmd}\n`);
-      help();
-      process.exit(2);
+      return handleNaturalLanguage(argv.join(" "), actions());
   }
 }

package/src/secrets/moonshot-key-store.mjs

@@ -0,0 +1,110 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+
+const SERVICE = "mangomagic.moonshot.api-key";
+const dir = join(homedir(), ".mangomagic");
+const fallbackFile = join(dir, "moonshot.json");
+
+function account() {
+  return process.env.USER || userInfo().username || "default";
+}
+
+function canUseKeychain() {
+  return process.platform === "darwin" && existsSync("/usr/bin/security");
+}
+
+function readKeychain() {
+  if (!canUseKeychain()) return null;
+  try {
+    const key = execFileSync("/usr/bin/security", [
+      "find-generic-password",
+      "-a", account(),
+      "-s", SERVICE,
+      "-w",
+    ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    return key || null;
+  } catch {
+    return null;
+  }
+}
+
+function writeKeychain(key) {
+  execFileSync("/usr/bin/security", [
+    "add-generic-password",
+    "-a", account(),
+    "-s", SERVICE,
+    "-w", key,
+    "-U",
+  ], { stdio: "ignore" });
+}
+
+function clearKeychain() {
+  if (!canUseKeychain()) return false;
+  try {
+    execFileSync("/usr/bin/security", [
+      "delete-generic-password",
+      "-a", account(),
+      "-s", SERVICE,
+    ], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readFallback() {
+  if (!existsSync(fallbackFile)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(fallbackFile, "utf8"));
+    return typeof raw?.apiKey === "string" ? raw.apiKey : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeFallback(key) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(fallbackFile, JSON.stringify({ apiKey: key }, null, 2));
+  try { chmodSync(fallbackFile, 0o600); } catch { /* windows */ }
+}
+
+export function loadMoonshotKey() {
+  if (process.env.MOONSHOT_API_KEY) return { key: process.env.MOONSHOT_API_KEY, source: "MOONSHOT_API_KEY" };
+  const keychainKey = readKeychain();
+  if (keychainKey) return { key: keychainKey, source: "macOS Keychain" };
+  const fileKey = readFallback();
+  if (fileKey) return { key: fileKey, source: fallbackFile };
+  return null;
+}
+
+export function saveMoonshotKey(key) {
+  if (!key || typeof key !== "string") throw new Error("Missing API key.");
+  const trimmed = key.trim();
+  if (!trimmed) throw new Error("Missing API key.");
+
+  if (canUseKeychain()) {
+    writeKeychain(trimmed);
+    return "macOS Keychain";
+  }
+
+  writeFallback(trimmed);
+  return fallbackFile;
+}
+
+export function clearMoonshotKey() {
+  const keychainCleared = clearKeychain();
+  let fileCleared = false;
+  if (existsSync(fallbackFile)) {
+    unlinkSync(fallbackFile);
+    fileCleared = true;
+  }
+  return keychainCleared || fileCleared;
+}
+
+export function moonshotKeyStorageHint() {
+  return canUseKeychain()
+    ? "macOS Keychain service mangomagic.moonshot.api-key"
+    : `${fallbackFile} (mode 0600) or MOONSHOT_API_KEY`;
+}

package/src/tools/catalog.mjs

@@ -1,5 +1,7 @@
 import { APP_ORIGIN } from "../config.mjs";
 
+export const COMMAND_PREFIX = "npx -y @mangomagic/cli";
+
 export const MCP_TOOL_CATALOG = [
   {
     name: "list_episodes",
@@ -40,20 +42,26 @@ export const MCP_TOOL_CATALOG = [
 
 export const QUICK_WINS = [
   {
-    command: "mangomagic cards",
+    command: `${COMMAND_PREFIX} cards`,
     title: "Create Talking Cards",
     description: "Open the card workspace, build a Brand Doc, choose colours, and generate LinkedIn-ready cards.",
     url: `${APP_ORIGIN}/carousels`,
     status: "ready",
   },
   {
-    command: "mangomagic mcp-config",
+    command: `${COMMAND_PREFIX} chat`,
+    title: "Talk To MangoMagic",
+    description: "Type natural language and let the CLI choose the right MangoMagic action.",
+    status: "ready",
+  },
+  {
+    command: `${COMMAND_PREFIX} mcp-config`,
     title: "Connect Claude, Cursor, or Codex",
     description: "Print the MCP config that lets your AI client use MangoMagic tools.",
     status: "ready",
   },
   {
-    command: "mangomagic tools",
+    command: `${COMMAND_PREFIX} tools`,
     title: "See Every Tool",
     description: "Show the full MCP tool list plus the next high-value workflows to wire in.",
     status: "ready",

package/src/ui/prompt-hidden.mjs

@@ -0,0 +1,45 @@
+export function promptHidden(prompt) {
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    let value = "";
+    let rawWasEnabled = false;
+
+    function cleanup() {
+      stdin.off("data", onData);
+      if (rawWasEnabled && stdin.isTTY) stdin.setRawMode(false);
+      stdin.pause();
+      stdout.write("\n");
+    }
+
+    function onData(chunk) {
+      const s = String(chunk);
+      for (const ch of s) {
+        if (ch === "\u0003") {
+          cleanup();
+          reject(new Error("Cancelled."));
+          return;
+        }
+        if (ch === "\r" || ch === "\n") {
+          cleanup();
+          resolve(value);
+          return;
+        }
+        if (ch === "\u007f" || ch === "\b") {
+          value = value.slice(0, -1);
+          continue;
+        }
+        value += ch;
+      }
+    }
+
+    stdout.write(prompt);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    if (stdin.isTTY) {
+      stdin.setRawMode(true);
+      rawWasEnabled = true;
+    }
+    stdin.on("data", onData);
+  });
+}