@myvillage/cli 1.90.0 → 1.91.0

package/README.md

@@ -21,10 +21,14 @@ myvillage create-game
 
 # Deploy to the platform
 myvillage deploy
+
+# Publish a PDF story book to the Read tab
+myvillage publish-book ./my-story.pdf
 ```
 
 ## What You Can Do
 
+- **Publish Story Books** — Upload a comic-style PDF; the platform turns it into pages for the muni Read tab, with MVT rewards for readers who finish.
 - **Build & Deploy Games** — Scaffold projects from built-in templates (quiz, exploration, narrative, or custom Three.js) and deploy to the M-UNI game platform.
 - **Community Network** — Browse feeds, create posts, join communities, comment, vote, and search — right from the CLI.
 - **AI Agents** — Create and manage local or external AI agents that participate in the MyVillage Agent Network.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.90.0",
+  "version": "1.91.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/commands/publish-book.js

@@ -0,0 +1,308 @@
+import { existsSync, readFileSync, statSync } from 'fs';
+import { resolve, basename } from 'path';
+import chalk from 'chalk';
+import axios from 'axios';
+import inquirer from 'inquirer';
+import { villageSpinner } from '../utils/brand.js';
+import { isAuthenticated } from '../utils/auth.js';
+import { getConfig } from '../utils/config.js';
+import {
+  createStoryBook,
+  getStoryBookUploadUrl,
+  confirmStoryBookUpload,
+  getStoryBookStatus,
+} from '../utils/api.js';
+import { getMyVillages } from '../utils/village-resolver.js';
+
+/**
+ * publish-book — upload a PDF story book to the Read pillar.
+ *
+ * The book counterpart to `deploy`: create the book, PUT the PDF straight to
+ * storage via a presigned URL, confirm, then watch the platform rasterize it
+ * into pages. On success the book sits in the review queue; an admin publishes
+ * it from the portal, after which it appears in the muni Read tab.
+ *
+ * See the platform's docs/features/story-books.md.
+ */
+
+const GENRES = [
+  'adventure', 'folktale', 'history', 'biography',
+  'science', 'faith', 'humor', 'education', 'other',
+];
+
+const AGE_GROUPS = ['under-5', '6-12', '13-and-over'];
+
+// Server-enforced too — quoted here so the failure is local and instant.
+const MAX_PDF_MB = 200;
+
+// Rasterization is ~0.5s/page server-side; a 300-page book plus queueing
+// comfortably fits inside this. Past it, assume something is wrong.
+const POLL_INTERVAL_MS = 2500;
+const POLL_TIMEOUT_MS = 12 * 60 * 1000;
+
+function fail(json, message) {
+  if (json) {
+    console.log(JSON.stringify({ success: false, error: message }));
+  } else {
+    console.log(chalk.red(`  ✗ ${message}`));
+  }
+  process.exitCode = 1;
+}
+
+function normGenre(v) {
+  if (!v) return null;
+  const g = String(v).toLowerCase();
+  return GENRES.includes(g) ? g.toUpperCase() : null;
+}
+
+function normAge(v) {
+  if (!v) return null;
+  const a = String(v).toLowerCase();
+  return AGE_GROUPS.includes(a) ? a : null;
+}
+
+function titleFromFilename(pdfPath) {
+  return basename(pdfPath)
+    .replace(/\.pdf$/i, '')
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Village visibility, same flow as `deploy`: pick which villages can see the
+ * book. Wording is book-specific, behavior identical — when the author isn't
+ * in any villages the book ships unscoped.
+ */
+async function selectBookVillages() {
+  const spinner = villageSpinner('Loading your villages...').start();
+  let villages;
+  try {
+    villages = await getMyVillages();
+  } catch (err) {
+    spinner.fail(`Could not load your villages: ${err.message}`);
+    return null;
+  }
+  spinner.stop();
+
+  if (!villages.length) {
+    console.log(chalk.yellow('  You are not a member of any villages — the book will be submitted without village scoping.'));
+    return [];
+  }
+
+  const { selected } = await inquirer.prompt([{
+    type: 'checkbox',
+    name: 'selected',
+    message: 'Which villages can see & read this book? (space to toggle, enter to confirm)',
+    choices: villages.map((v) => ({
+      name: `${v.name}${v.city ? ` (${v.city}${v.state ? ', ' + v.state : ''})` : ''}`,
+      value: v.id,
+      checked: false,
+    })),
+    validate: (ans) => (ans.length > 0 ? true : 'Select at least one village (space to toggle).'),
+  }]);
+
+  return selected;
+}
+
+async function pollUntilProcessed(bookId, spinner) {
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+
+  for (;;) {
+    if (Date.now() > deadline) {
+      return { ok: false, error: 'Timed out waiting for processing. Check the book in the portal — it may still finish.' };
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+
+    let status;
+    try {
+      status = await getStoryBookStatus(bookId);
+    } catch {
+      continue; // transient poll failure — the render is server-side, keep waiting
+    }
+
+    if (status.processing) {
+      if (spinner && status.pagesRendered > 0) {
+        spinner.text = `Rendering pages... ${status.pagesRendered} done`;
+      }
+      continue;
+    }
+    if (status.error) {
+      return { ok: false, error: status.error, status };
+    }
+    return { ok: true, status };
+  }
+}
+
+export async function publishBookCommand(pdfPath, options = {}) {
+  const json = !!options.json;
+  const nonInteractive = json || !!options.yes;
+
+  if (!isAuthenticated()) {
+    return fail(json, "Authentication required. Run 'myvillage login' first.");
+  }
+
+  // ── Validate the PDF locally, before any API call ──
+  const resolved = resolve(pdfPath);
+  if (!existsSync(resolved)) {
+    return fail(json, `File not found: ${resolved}`);
+  }
+  if (!/\.pdf$/i.test(resolved)) {
+    return fail(json, 'Story books are published from PDF files (.pdf).');
+  }
+  const fileSize = statSync(resolved).size;
+  if (fileSize === 0) {
+    return fail(json, 'That PDF is empty.');
+  }
+  if (fileSize > MAX_PDF_MB * 1024 * 1024) {
+    return fail(json, `PDF is ${Math.round(fileSize / 1024 / 1024)}MB — the limit is ${MAX_PDF_MB}MB. Export it smaller or split it into volumes.`);
+  }
+
+  // ── Metadata: flags first, prompts for the gaps ──
+  let title = options.title?.trim() || null;
+  let genre = normGenre(options.genre);
+  let targetAge = normAge(options.age);
+  let description = options.description?.trim() || null;
+
+  if (options.genre && !genre) {
+    return fail(json, `Unknown genre "${options.genre}". Use one of: ${GENRES.join(', ')}`);
+  }
+  if (options.age && !targetAge) {
+    return fail(json, `Unknown age group "${options.age}". Use one of: ${AGE_GROUPS.join(', ')}`);
+  }
+
+  if (nonInteractive) {
+    if (!title) title = titleFromFilename(resolved);
+    if (!genre) genre = 'OTHER';
+  } else {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'title',
+        message: 'Book title:',
+        default: title || titleFromFilename(resolved),
+        when: !title,
+        validate: (v) => (v.trim() ? true : 'A title is required.'),
+      },
+      {
+        type: 'list',
+        name: 'genre',
+        message: 'Genre:',
+        choices: GENRES,
+        default: 'other',
+        when: !genre,
+      },
+      {
+        type: 'list',
+        name: 'age',
+        message: 'Target age:',
+        choices: [...AGE_GROUPS, new inquirer.Separator(), 'skip'],
+        when: !targetAge,
+      },
+      {
+        type: 'input',
+        name: 'description',
+        message: 'Short description (optional):',
+        when: !description,
+      },
+    ]);
+    title = title || answers.title.trim();
+    genre = genre || answers.genre.toUpperCase();
+    if (!targetAge && answers.age && answers.age !== 'skip') targetAge = answers.age;
+    if (!description && answers.description?.trim()) description = answers.description.trim();
+  }
+
+  // ── Village visibility (same flow as deploy) ──
+  let villageIds;
+  if (typeof options.villages === 'string') {
+    villageIds = options.villages.split(',').map((v) => v.trim()).filter(Boolean);
+  } else if (nonInteractive) {
+    villageIds = []; // unscoped; admins can narrow it in the portal
+  } else {
+    villageIds = await selectBookVillages();
+    if (villageIds === null) return fail(json, 'Could not load villages. Try again, or pass --villages <ids>.');
+  }
+
+  // ── Create → upload → confirm ──
+  let spinner = json ? null : villageSpinner('Creating the book...').start();
+  let book;
+  try {
+    const created = await createStoryBook({
+      title,
+      description: description || undefined,
+      genre,
+      targetAge: targetAge || undefined,
+      villageIds,
+    });
+    book = created.storyBook;
+    if (spinner) spinner.succeed(`Book created: ${chalk.bold(book.slug)}`);
+  } catch (err) {
+    if (spinner) spinner.stop();
+    return fail(json, err.response?.data?.error || err.message);
+  }
+
+  const fileName = basename(resolved);
+  spinner = json ? null : villageSpinner(`Uploading ${fileName} (${(fileSize / 1024 / 1024).toFixed(1)}MB)...`).start();
+  try {
+    const urlResult = await getStoryBookUploadUrl(book.id, {
+      fileName,
+      assetType: 'SOURCE_PDF',
+      fileSize,
+    });
+
+    await axios.put(urlResult.uploadUrl, readFileSync(resolved), {
+      headers: { 'Content-Type': urlResult.contentType },
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    });
+
+    await confirmStoryBookUpload(book.id, {
+      s3Key: urlResult.s3Key,
+      fileName,
+      assetType: 'SOURCE_PDF',
+    });
+    if (spinner) spinner.succeed('PDF uploaded');
+  } catch (err) {
+    if (spinner) spinner.stop();
+    return fail(json, err.response?.data?.error || err.message);
+  }
+
+  // ── Watch the rasterizer ──
+  spinner = json ? null : villageSpinner('Rendering pages...').start();
+  const result = await pollUntilProcessed(book.id, spinner);
+
+  if (!result.ok) {
+    if (spinner) spinner.fail(result.error);
+    if (json) console.log(JSON.stringify({ success: false, error: result.error, bookId: book.id, slug: book.slug }));
+    process.exitCode = 1;
+    return;
+  }
+
+  const pageCount = result.status.pageCount ?? 0;
+  if (spinner) spinner.succeed(`${pageCount} pages rendered`);
+
+  const config = getConfig();
+  const portalUrl = `${config.platformBaseUrl.replace(/\/api$/, '')}/story-books`;
+
+  if (json) {
+    console.log(JSON.stringify({
+      success: true,
+      bookId: book.id,
+      slug: book.slug,
+      title,
+      pageCount,
+      status: result.status.status,
+      portalUrl,
+    }));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.green('  ✓ Your book is in the review queue.'));
+  console.log(`    ${chalk.dim('Title:')}  ${title}`);
+  console.log(`    ${chalk.dim('Pages:')}  ${pageCount} (page one is the cover)`);
+  console.log(`    ${chalk.dim('Genre:')}  ${genre.toLowerCase()}`);
+  console.log('');
+  console.log(`  An admin reviews it at ${chalk.cyan(portalUrl)} — once published,`);
+  console.log('  it appears in the muni Read tab and readers earn MVT for finishing it.');
+}

package/src/index.js

@@ -18,6 +18,7 @@ import {
 import { createGameCommand } from './commands/create-game.js';
 import { createCommand } from './commands/create-app.js';
 import { deployCommand } from './commands/deploy.js';
+import { publishBookCommand } from './commands/publish-book.js';
 import { statusCommand } from './commands/status.js';
 import { feedCommand } from './commands/feed.js';
 import {
@@ -230,6 +231,18 @@ export function run() {
     .option('--json', 'Output the result as JSON (implies non-interactive)')
     .action((options) => deployCommand(options));
 
+  program
+    .command('publish-book <pdf>')
+    .description('Publish a PDF story book to the muni Read tab')
+    .option('-t, --title <title>', 'Book title (defaults to the PDF filename)')
+    .option('-g, --genre <genre>', 'adventure | folktale | history | biography | science | faith | humor | education | other')
+    .option('-a, --age <age>', 'Target age: under-5 | 6-12 | 13-and-over')
+    .option('-d, --description <text>', 'Short description')
+    .option('--villages <ids>', 'Comma-separated village ids for visibility (skips the prompt)')
+    .option('-y, --yes', 'Non-interactive: defaults instead of prompts')
+    .option('--json', 'Output the result as JSON (implies non-interactive)')
+    .action((pdf, options) => publishBookCommand(pdf, options));
+
   program
     .command('status')
     .description('Check deployment status of your games')

package/src/utils/api.js

@@ -594,6 +594,44 @@ export async function submitGameForReview(gameId) {
   return response.data;
 }
 
+// ── Story Books API (/api/v1/storybooks) ───────────────
+
+export async function createStoryBook(data) {
+  const client = getApiClient();
+  const response = await client.post('/storybooks/submit', data);
+  return response.data;
+}
+
+export async function getStoryBookUploadUrl(bookId, data) {
+  const client = getApiClient();
+  const response = await client.post(`/storybooks/${encodeURIComponent(bookId)}/upload-url`, data);
+  return response.data;
+}
+
+export async function confirmStoryBookUpload(bookId, data) {
+  const client = getApiClient();
+  const response = await client.post(`/storybooks/${encodeURIComponent(bookId)}/confirm-upload`, data);
+  return response.data;
+}
+
+export async function getStoryBookStatus(bookId) {
+  const client = getApiClient();
+  const response = await client.get(`/storybooks/${encodeURIComponent(bookId)}/status`);
+  return response.data;
+}
+
+export async function getStoryBookDetail(bookId) {
+  const client = getApiClient();
+  const response = await client.get(`/storybooks/${encodeURIComponent(bookId)}`);
+  return response.data;
+}
+
+export async function getMyStoryBooks() {
+  const client = getApiClient();
+  const response = await client.get('/storybooks/my-books');
+  return response.data;
+}
+
 // ── GameKit SDK preflight ──────────────────────────────
 
 // Fetch the GUID allowlist for a specific SDK version. Public endpoint —