storymode-cli 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# storymode-cli
+
+Play AI-animated pixel art characters in your terminal.
+
+```
+npx storymode-cli play 1
+```
+
+## Commands
+
+### `play <id>`
+Play a gallery animation with interactive controls.
+
+```
+npx storymode-cli play 1
+```
+
+**Controls:**
+- `space` — pause / resume
+- `←` `→` — step frames (when paused)
+- `+` `-` — adjust speed
+- `q` — quit
+
+### `show <id>`
+Print the first frame as a static portrait.
+
+```
+npx storymode-cli show 1
+```
+
+### `browse`
+Browse the gallery and pick an animation to play.
+
+```
+npx storymode-cli browse
+```
+
+### `mcp`
+Start a Model Context Protocol server for Claude Code integration.
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "storymode": {
+      "command": "npx",
+      "args": ["storymode-cli", "mcp"]
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- A terminal with truecolor support (iTerm2, Terminal.app, Windows Terminal, Claude Code)
+
+## Zero Dependencies
+
+Built entirely on Node.js built-ins — no `node_modules` needed.
+
+## Gallery
+
+Browse characters at [storymode.fixmy.codes](https://storymode.fixmy.codes)

package/bin/storymode.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "storymode-cli",
+  "version": "1.0.0",
+  "description": "Play AI-animated pixel art characters in your terminal",
+  "type": "module",
+  "bin": {
+    "storymode": "bin/storymode.mjs",
+    "storymode-cli": "bin/storymode.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "pixel-art",
+    "animation",
+    "terminal",
+    "ansi",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Yuncun/storymode-cli"
+  },
+  "homepage": "https://storymode.fixmy.codes"
+}

package/src/api.mjs

@@ -0,0 +1,45 @@
+import https from 'node:https';
+import http from 'node:http';
+import { gunzipSync } from 'node:zlib';
+
+const BASE = 'https://storymode.fixmy.codes';
+
+function request(url) {
+  return new Promise((resolve, reject) => {
+    const mod = url.startsWith('https') ? https : http;
+    mod.get(url, { headers: { 'Accept-Encoding': 'identity' } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return resolve(request(res.headers.location));
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode}`));
+      }
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => resolve({ buffer: Buffer.concat(chunks), contentType: res.headers['content-type'] || '' }));
+      res.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+export async function fetchGallery() {
+  const { buffer } = await request(`${BASE}/gallery`);
+  return JSON.parse(buffer.toString('utf-8'));
+}
+
+export async function fetchFrames(galleryId) {
+  const { buffer, contentType } = await request(`${BASE}/gallery/${galleryId}/frames`);
+  let json;
+  if (contentType.includes('gzip') || buffer[0] === 0x1f) {
+    json = gunzipSync(buffer).toString('utf-8');
+  } else {
+    json = buffer.toString('utf-8');
+  }
+  return JSON.parse(json);
+}
+
+export async function fetchCharacter(galleryId) {
+  const { buffer } = await request(`${BASE}/gallery/${galleryId}/character`);
+  return JSON.parse(buffer.toString('utf-8'));
+}

package/src/browse.mjs

@@ -0,0 +1,70 @@
+import { createInterface } from 'node:readline/promises';
+import { fetchGallery, fetchFrames } from './api.mjs';
+import { playAnimation } from './player.mjs';
+
+export async function browse() {
+  const spinner = startSpinner('Fetching gallery...');
+  let items;
+  try {
+    items = await fetchGallery();
+  } finally {
+    stopSpinner(spinner);
+  }
+
+  if (!items || items.length === 0) {
+    console.log('Gallery is empty.');
+    return;
+  }
+
+  console.log('');
+  console.log('  storymode gallery');
+  console.log('');
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    const name = item.name || 'untitled';
+    const prompt = item.prompt ? ` — ${item.prompt}` : '';
+    const author = item.author_name ? ` (by ${item.author_name})` : '';
+    console.log(`  ${String(i + 1).padStart(3)}.  ${name}${prompt}${author}`);
+  }
+  console.log('');
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    while (true) {
+      const answer = await rl.question('  Enter number to play (q to quit): ');
+      const trimmed = answer.trim().toLowerCase();
+      if (trimmed === 'q' || trimmed === 'quit' || trimmed === '') break;
+
+      const num = parseInt(trimmed, 10);
+      if (isNaN(num) || num < 1 || num > items.length) {
+        console.log(`  Pick 1-${items.length}`);
+        continue;
+      }
+
+      const item = items[num - 1];
+      rl.close();
+
+      console.log(`\n  Loading ${item.name || 'animation'}...`);
+      const framesData = await fetchFrames(item.id);
+      await playAnimation(framesData);
+      return;
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function startSpinner(msg) {
+  const chars = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  process.stdout.write(`  ${chars[0]} ${msg}`);
+  return setInterval(() => {
+    i = (i + 1) % chars.length;
+    process.stdout.write(`\r  ${chars[i]} ${msg}`);
+  }, 80);
+}
+
+function stopSpinner(id) {
+  clearInterval(id);
+  process.stdout.write('\r\x1b[K');
+}

package/src/cli.mjs

@@ -0,0 +1,92 @@
+import { fetchFrames, fetchCharacter } from './api.mjs';
+import { playAnimation, showFrame } from './player.mjs';
+import { browse } from './browse.mjs';
+import { startMcpServer } from './mcp.mjs';
+
+const HELP = `
+  storymode-cli — play AI-animated pixel art in your terminal
+
+  Usage:
+    storymode play <gallery_id>    Play an animation
+    storymode show <gallery_id>    Show first frame as static portrait
+    storymode browse               Browse the gallery interactively
+    storymode mcp                  Start MCP server (for Claude Code)
+
+  Controls (during playback):
+    space     pause / resume
+    < / >     step frames (when paused)
+    + / -     increase / decrease speed
+    q         quit
+
+  https://storymode.fixmy.codes
+`;
+
+export async function run(args) {
+  const cmd = args[0];
+  const id = args[1];
+
+  switch (cmd) {
+    case 'play': {
+      if (!id) {
+        console.error('Usage: storymode play <gallery_id>');
+        process.exit(1);
+      }
+      try {
+        process.stderr.write('  Loading animation...\n');
+        const framesData = await fetchFrames(id);
+        await playAnimation(framesData);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'show': {
+      if (!id) {
+        console.error('Usage: storymode show <gallery_id>');
+        process.exit(1);
+      }
+      try {
+        process.stderr.write('  Loading...\n');
+        const [framesData, character] = await Promise.all([
+          fetchFrames(id),
+          fetchCharacter(id).catch(() => null),
+        ]);
+        const info = character
+          ? { ...character, galleryId: id }
+          : { galleryId: id };
+        showFrame(framesData, info);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'browse':
+      try {
+        await browse();
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+
+    case 'mcp':
+      startMcpServer();
+      break;
+
+    case '--help':
+    case '-h':
+    case 'help':
+    case undefined:
+      console.log(HELP);
+      break;
+
+    default:
+      console.error(`Unknown command: ${cmd}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/src/mcp.mjs

@@ -0,0 +1,150 @@
+import { createInterface } from 'node:readline';
+import { fetchGallery, fetchFrames, fetchCharacter } from './api.mjs';
+
+const TOOLS = [
+  {
+    name: 'list_characters',
+    description: 'List all characters in the Storymode gallery',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'show_character',
+    description: 'Show character info and portrait (first frame as ANSI art)',
+    inputSchema: {
+      type: 'object',
+      properties: { gallery_id: { type: 'string', description: 'Gallery item ID' } },
+      required: ['gallery_id'],
+    },
+  },
+  {
+    name: 'play_animation',
+    description: 'Get animation data for a gallery character (returns first frame as ANSI art + metadata)',
+    inputSchema: {
+      type: 'object',
+      properties: { gallery_id: { type: 'string', description: 'Gallery item ID' } },
+      required: ['gallery_id'],
+    },
+  },
+];
+
+async function handleToolCall(name, args) {
+  switch (name) {
+    case 'list_characters': {
+      const items = await fetchGallery();
+      const lines = items.map((item, i) =>
+        `${i + 1}. ${item.name || 'untitled'}${item.prompt ? ' — ' + item.prompt : ''} (id: ${item.id})`
+      );
+      return lines.join('\n') || 'Gallery is empty.';
+    }
+    case 'show_character': {
+      const id = args.gallery_id;
+      const [character, framesData] = await Promise.all([
+        fetchCharacter(id).catch(() => null),
+        fetchFrames(id),
+      ]);
+      let text = '';
+      if (character) {
+        text += `Name: ${character.name || 'untitled'}\n`;
+        if (character.backstory) text += `Backstory: ${character.backstory}\n`;
+        if (character.animations?.length) {
+          text += `Animations: ${character.animations.map(a => a.name || a.prompt).join(', ')}\n`;
+        }
+        text += '\n';
+      }
+      // First frame as ANSI
+      if (framesData.frames?.length > 0) {
+        text += 'Portrait (ANSI):\n';
+        text += framesData.frames[0].join('\n');
+      }
+      return text;
+    }
+    case 'play_animation': {
+      const id = args.gallery_id;
+      const framesData = await fetchFrames(id);
+      let text = '';
+      if (framesData.frames?.length > 0) {
+        text += framesData.frames[0].join('\n');
+        text += `\n\n${framesData.frames.length} frames @ ${framesData.fps || 16} fps`;
+        text += `\n\nTo see the full animation, run:\n  npx storymode-cli play ${id}`;
+      } else {
+        text = 'No frames available.';
+      }
+      return text;
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+function handleMessage(msg) {
+  const { id, method, params } = msg;
+
+  switch (method) {
+    case 'initialize':
+      send({
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'storymode', version: '1.0.0' },
+        },
+      });
+      break;
+
+    case 'notifications/initialized':
+      // No response needed
+      break;
+
+    case 'tools/list':
+      send({ jsonrpc: '2.0', id, result: { tools: TOOLS } });
+      break;
+
+    case 'tools/call':
+      handleToolCall(params.name, params.arguments || {})
+        .then((text) => {
+          send({
+            jsonrpc: '2.0',
+            id,
+            result: { content: [{ type: 'text', text }] },
+          });
+        })
+        .catch((err) => {
+          send({
+            jsonrpc: '2.0',
+            id,
+            result: {
+              content: [{ type: 'text', text: `Error: ${err.message}` }],
+              isError: true,
+            },
+          });
+        });
+      break;
+
+    default:
+      if (id) {
+        send({
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32601, message: `Method not found: ${method}` },
+        });
+      }
+  }
+}
+
+export function startMcpServer() {
+  const rl = createInterface({ input: process.stdin });
+  rl.on('line', (line) => {
+    try {
+      const msg = JSON.parse(line);
+      handleMessage(msg);
+    } catch {
+      // Ignore malformed input
+    }
+  });
+  rl.on('close', () => process.exit(0));
+}

package/src/player.mjs

@@ -0,0 +1,146 @@
+const { stdout, stdin } = process;
+
+export function playAnimation(framesData) {
+  const frames = framesData.frames;
+  const baseFps = framesData.fps || 16;
+  const nFrames = frames.length;
+
+  if (nFrames === 0) {
+    console.log('No frames to play.');
+    return;
+  }
+
+  const maxLines = Math.max(...frames.map(f => f.length));
+  let frameIdx = 0;
+  let frameCount = 0;
+  let loopCount = 0;
+  let paused = false;
+  let currentFps = baseFps;
+  let interval = 1000 / currentFps;
+  let quit = false;
+
+  // Enter alt screen, hide cursor, clear
+  stdout.write('\x1b[?1049h\x1b[?25l\x1b[2J\x1b[H');
+
+  function drawFrame(idx) {
+    let out = '\x1b[H';
+    const frameLines = frames[idx];
+    for (let i = 0; i < maxLines; i++) {
+      if (i < frameLines.length) {
+        out += frameLines[i];
+      }
+      out += '\x1b[K\n';
+    }
+    const status = paused ? 'PAUSED' : 'playing';
+    out += `\x1b[0m\x1b[K  [${status}] frame ${idx + 1}/${nFrames}  `;
+    out += `${currentFps} fps  loop ${loopCount + 1}  `;
+    out += '[space]=pause [</>]=step [+/-]=speed [q]=quit\n';
+    stdout.write(out);
+  }
+
+  function cleanup() {
+    if (stdin.isTTY) stdin.setRawMode(false);
+    stdin.removeAllListeners('data');
+    stdin.pause();
+    // Exit alt screen, show cursor
+    stdout.write('\x1b[?1049l\x1b[?25h');
+    stdout.write(
+      `\x1b[0m${frameCount} frames displayed (${nFrames} unique, ${loopCount} loops)\n`
+    );
+  }
+
+  function handleKey(data) {
+    const key = data.toString();
+    if (key === 'q' || key === '\x03') {
+      quit = true;
+      return;
+    }
+    if (key === ' ') {
+      paused = !paused;
+      drawFrame(frameIdx);
+      return;
+    }
+    if (key === '+' || key === '=') {
+      currentFps = Math.min(currentFps + 2, 60);
+      interval = 1000 / currentFps;
+      drawFrame(frameIdx);
+      return;
+    }
+    if (key === '-' || key === '_') {
+      currentFps = Math.max(currentFps - 2, 1);
+      interval = 1000 / currentFps;
+      drawFrame(frameIdx);
+      return;
+    }
+    // Arrow keys: ESC [ A/B/C/D
+    if (key === '\x1b[C' && paused) {
+      // right arrow - next frame
+      frameIdx = (frameIdx + 1) % nFrames;
+      frameCount++;
+      drawFrame(frameIdx);
+    } else if (key === '\x1b[D' && paused) {
+      // left arrow - prev frame
+      frameIdx = (frameIdx - 1 + nFrames) % nFrames;
+      frameCount++;
+      drawFrame(frameIdx);
+    }
+  }
+
+  // Set raw mode for key input
+  if (stdin.isTTY) {
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on('data', handleKey);
+  }
+
+  return new Promise((resolve) => {
+    function tick() {
+      if (quit) {
+        cleanup();
+        resolve();
+        return;
+      }
+      if (!paused) {
+        drawFrame(frameIdx);
+        frameCount++;
+        frameIdx++;
+        if (frameIdx >= nFrames) {
+          loopCount++;
+          frameIdx = 0;
+        }
+      }
+      setTimeout(tick, paused ? 50 : interval);
+    }
+    tick();
+
+    // Handle SIGINT gracefully
+    process.on('SIGINT', () => {
+      quit = true;
+    });
+  });
+}
+
+export function showFrame(framesData, info) {
+  const frames = framesData.frames;
+  if (!frames || frames.length === 0) {
+    console.log('No frames available.');
+    return;
+  }
+  // Print first frame
+  const frame = frames[0];
+  for (const line of frame) {
+    stdout.write(line + '\x1b[K\n');
+  }
+  stdout.write('\x1b[0m');
+  // Print character info below if provided
+  if (info) {
+    console.log('');
+    if (info.name) console.log(`  ${info.name}`);
+    if (info.author_name) console.log(`  by ${info.author_name}`);
+    if (info.backstory) console.log(`  ${info.backstory}`);
+    console.log('');
+    console.log(`  ${frames.length} frames @ ${framesData.fps || 16} fps`);
+    console.log(`  npx storymode-cli play ${info.galleryId || '?'}`);
+  }
+  console.log('');
+}