@myvillage/cli 1.91.0 → 2.1.0

package/README.md

@@ -4,7 +4,7 @@ The official command-line interface for the [MyVillage](https://www.myvillagepro
 
 ## Installation
 
-Requires Node.js 18 or higher.
+Requires Node.js 22 or higher.
 
 ```bash
 npm install -g @myvillage/cli

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.91.0",
+  "version": "2.1.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {
     "myvillage": "./bin/myvillage.js"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "files": [
     "bin/",
@@ -39,6 +39,7 @@
     "conf": "^12.0.0",
     "inquirer": "^9.2.12",
     "jpeg-js": "^0.4.4",
+    "music-metadata": "^11.14.0",
     "open": "^10.0.3",
     "ora": "^8.0.1",
     "p-limit": "^5.0.0",

package/src/commands/podcast.js

@@ -0,0 +1,406 @@
+import { existsSync, readFileSync, statSync } from 'fs';
+import { resolve, basename, extname } 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 {
+  confirmPodcastUpload,
+  createPodcast,
+  getMyPodcasts,
+  getPodcastDetail,
+  getPodcastUploadUrl,
+  submitPodcast,
+} from '../utils/api.js';
+
+/**
+ * podcast — show management. The setup half of the Listen pillar;
+ * publish-episode is the half people run every week.
+ *
+ * A show exists mostly to carry the metadata Apple validates before it will
+ * accept a feed: owner email, category, language, explicit flag, and square
+ * cover art. Getting any of those wrong is not a local error — the feed
+ * publishes, looks correct, and is refused during directory submission days
+ * later. So this command validates as much as it can on this machine, where the
+ * author is still looking at the thing they typed.
+ *
+ * See the platform's docs/features/podcasts.md.
+ */
+
+/** Apple's top-level categories. Mirrors APPLE_CATEGORIES server-side. */
+const CATEGORIES = [
+  'Arts', 'Business', 'Comedy', 'Education', 'Fiction', 'Government', 'History',
+  'Health & Fitness', 'Kids & Family', 'Leisure', 'Music', 'News',
+  'Religion & Spirituality', 'Science', 'Society & Culture', 'Sports',
+  'Technology', 'True Crime', 'TV & Film',
+];
+
+const COVER_MIN_PX = 1400;
+const COVER_MAX_PX = 3000;
+
+function fail(json, message) {
+  if (json) {
+    console.log(JSON.stringify({ success: false, error: message }));
+  } else {
+    console.log(chalk.red(`  ✗ ${message}`));
+  }
+  process.exitCode = 1;
+}
+
+function siteUrl() {
+  return getConfig().platformBaseUrl.replace(/\/api(\/v1)?$/, '');
+}
+
+// ============================================================
+// Cover art
+// ============================================================
+
+/**
+ * Read image dimensions from the file header.
+ *
+ * Header parsing rather than decoding: the only question is how many pixels
+ * wide and tall, and fully decoding a 3000x3000 JPEG to answer it wastes a
+ * second and a few hundred megabytes for nothing.
+ *
+ * Returns null when the format is not recognised, which is treated as "cannot
+ * check" rather than "invalid" — the server does not enforce dimensions, Apple
+ * does, and a warning is the honest thing to emit when we genuinely do not know.
+ */
+function readImageSize(filePath) {
+  const buf = readFileSync(filePath);
+
+  // PNG: fixed-position IHDR.
+  if (buf.length > 24 && buf.toString('hex', 0, 8) === '89504e470d0a1a0a') {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+  }
+
+  // JPEG: walk the segment chain to the first SOF marker.
+  if (buf.length > 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+    let offset = 2;
+    while (offset < buf.length - 9) {
+      if (buf[offset] !== 0xff) {
+        offset++;
+        continue;
+      }
+      const marker = buf[offset + 1];
+      // SOF0-SOF15, excluding DHT (c4), JPG (c8) and DAC (cc), which share the range.
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return { height: buf.readUInt16BE(offset + 5), width: buf.readUInt16BE(offset + 7) };
+      }
+      offset += 2 + buf.readUInt16BE(offset + 2);
+    }
+  }
+
+  return null;
+}
+
+/** Author-facing complaints about cover art. Empty means Apple should accept it. */
+function coverProblems(filePath) {
+  const size = readImageSize(filePath);
+  if (!size) return [];
+
+  const problems = [];
+  if (size.width !== size.height) {
+    problems.push(`It is ${size.width}x${size.height}. Podcast art has to be square.`);
+  }
+  if (size.width < COVER_MIN_PX || size.height < COVER_MIN_PX) {
+    problems.push(`It is ${size.width}x${size.height}. Apple needs at least ${COVER_MIN_PX}x${COVER_MIN_PX}.`);
+  }
+  if (size.width > COVER_MAX_PX || size.height > COVER_MAX_PX) {
+    problems.push(`It is ${size.width}x${size.height}. Apple's ceiling is ${COVER_MAX_PX}x${COVER_MAX_PX}.`);
+  }
+  return problems;
+}
+
+// ============================================================
+// podcast create
+// ============================================================
+
+export async function podcastCreateCommand(options = {}) {
+  const json = !!options.json;
+  const nonInteractive = json || !!options.yes;
+
+  if (!isAuthenticated()) {
+    return fail(json, "Authentication required. Run 'myvillage login' first.");
+  }
+
+  let title = options.title?.trim() || null;
+  let description = options.description?.trim() || null;
+  let category = options.category?.trim() || null;
+  let ownerEmail = options.email?.trim() || null;
+  let authorName = options.author?.trim() || null;
+
+  if (category && !CATEGORIES.includes(category)) {
+    return fail(
+      json,
+      `"${category}" is not one of Apple's categories. Pick one of: ${CATEGORIES.join(', ')}`,
+    );
+  }
+
+  if (nonInteractive) {
+    if (!title) return fail(json, 'A title is required. Pass --title.');
+    if (!category) category = 'Kids & Family';
+  } else {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'title',
+        message: 'Show title:',
+        when: !title,
+        validate: (v) => (v.trim() ? true : 'A title is required.'),
+      },
+      {
+        type: 'input',
+        name: 'description',
+        message: 'What is the show about?',
+        when: !description,
+      },
+      {
+        type: 'list',
+        name: 'category',
+        message: 'Category (Apple shows this on the listing page):',
+        choices: CATEGORIES,
+        default: 'Kids & Family',
+        when: !category,
+      },
+      {
+        type: 'input',
+        name: 'author',
+        message: 'Who is it by? (the byline listeners see)',
+        when: !authorName,
+      },
+      {
+        type: 'input',
+        name: 'email',
+        message: 'Owner email (Apple mails this to verify the feed):',
+        when: !ownerEmail,
+        validate: (v) =>
+          !v.trim() || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v.trim())
+            ? true
+            : 'That does not look like an email address.',
+      },
+    ]);
+    title = title || answers.title.trim();
+    if (!description && answers.description?.trim()) description = answers.description.trim();
+    category = category || answers.category;
+    if (!authorName && answers.author?.trim()) authorName = answers.author.trim();
+    if (!ownerEmail && answers.email?.trim()) ownerEmail = answers.email.trim();
+  }
+
+  const spinner = json ? null : villageSpinner('Creating the show...').start();
+  let podcast;
+  try {
+    const created = await createPodcast({
+      title,
+      description: description || undefined,
+      category,
+      authorName: authorName || undefined,
+      ownerEmail: ownerEmail || undefined,
+      explicit: options.explicit === true ? true : undefined,
+      language: options.language?.trim() || undefined,
+    });
+    podcast = created.podcast;
+    if (spinner) spinner.succeed(`Show created: ${chalk.bold(podcast.slug)}`);
+  } catch (err) {
+    if (spinner) spinner.stop();
+    return fail(json, err.response?.data?.error || err.message);
+  }
+
+  if (json) {
+    console.log(JSON.stringify({ success: true, podcast, feedUrl: `${siteUrl()}/podcasts/${podcast.slug}/feed.xml` }));
+    return;
+  }
+
+  console.log('');
+  console.log(`  ${chalk.dim('Next:')} add cover art, then submit the show for review.`);
+  console.log(`    ${chalk.cyan(`myvillage podcast cover ${podcast.slug} <image.jpg>`)}`);
+  console.log(`    ${chalk.cyan(`myvillage podcast submit ${podcast.slug}`)}`);
+  console.log('');
+}
+
+// ============================================================
+// podcast list
+// ============================================================
+
+export async function podcastListCommand(options = {}) {
+  const json = !!options.json;
+
+  if (!isAuthenticated()) {
+    return fail(json, "Authentication required. Run 'myvillage login' first.");
+  }
+
+  let podcasts;
+  try {
+    const result = await getMyPodcasts();
+    podcasts = result.podcasts || [];
+  } catch (err) {
+    return fail(json, err.response?.data?.error || err.message);
+  }
+
+  if (json) {
+    console.log(JSON.stringify({ success: true, podcasts }));
+    return;
+  }
+
+  if (podcasts.length === 0) {
+    console.log('');
+    console.log(`  You do not have a show yet. ${chalk.cyan('myvillage podcast create')} starts one.`);
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  for (const p of podcasts) {
+    const episodes = p._count?.episodes ?? 0;
+    console.log(`  ${chalk.bold(p.title)} ${chalk.dim(`(${p.slug})`)}`);
+    console.log(
+      `    ${chalk.dim('Status:')} ${p.status.toLowerCase()}   ${chalk.dim('Episodes:')} ${episodes}`,
+    );
+    if (p.status === 'PUBLISHED') {
+      console.log(`    ${chalk.dim('Feed:')}   ${chalk.cyan(`${siteUrl()}/podcasts/${p.slug}/feed.xml`)}`);
+    }
+    console.log('');
+  }
+}
+
+// ============================================================
+// podcast cover
+// ============================================================
+
+export async function podcastCoverCommand(slug, imagePath, options = {}) {
+  const json = !!options.json;
+
+  if (!isAuthenticated()) {
+    return fail(json, "Authentication required. Run 'myvillage login' first.");
+  }
+
+  const resolved = resolve(imagePath);
+  if (!existsSync(resolved)) {
+    return fail(json, `File not found: ${resolved}`);
+  }
+
+  const ext = extname(resolved).slice(1).toLowerCase();
+  if (!['jpg', 'jpeg', 'png'].includes(ext)) {
+    return fail(json, 'Cover art has to be a JPEG or PNG.');
+  }
+
+  const fileSize = statSync(resolved).size;
+  if (fileSize === 0) return fail(json, 'That image is empty.');
+
+  const problems = coverProblems(resolved);
+  if (problems.length > 0 && !options.force) {
+    return fail(
+      json,
+      `Apple will reject this cover. ${problems.join(' ')} Fix it, or pass --force to upload anyway.`,
+    );
+  }
+
+  const fileName = basename(resolved);
+  const spinner = json ? null : villageSpinner(`Uploading ${fileName}...`).start();
+  try {
+    const urlResult = await getPodcastUploadUrl(slug, { fileName, fileSize });
+
+    await axios.put(urlResult.uploadUrl, readFileSync(resolved), {
+      headers: { 'Content-Type': urlResult.contentType },
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    });
+
+    const confirmed = await confirmPodcastUpload(slug, { s3Key: urlResult.s3Key });
+    if (spinner) spinner.succeed('Cover art uploaded');
+
+    if (json) {
+      console.log(JSON.stringify({ success: true, podcast: confirmed.podcast, feedBlockers: confirmed.feedBlockers }));
+      return;
+    }
+
+    const blockers = confirmed.feedBlockers || [];
+    if (blockers.length > 0) {
+      console.log('');
+      console.log(chalk.yellow('  Still needed before this show can go out:'));
+      for (const b of blockers) console.log(`    • ${b}`);
+      console.log('');
+    }
+  } catch (err) {
+    if (spinner) spinner.stop();
+    return fail(json, err.response?.data?.error || err.message);
+  }
+}
+
+// ============================================================
+// podcast submit
+// ============================================================
+
+export async function podcastSubmitCommand(slug, options = {}) {
+  const json = !!options.json;
+
+  if (!isAuthenticated()) {
+    return fail(json, "Authentication required. Run 'myvillage login' first.");
+  }
+
+  const spinner = json ? null : villageSpinner('Submitting the show for review...').start();
+  try {
+    const result = await submitPodcast(slug);
+    if (spinner) spinner.succeed('Submitted for review');
+
+    if (json) {
+      console.log(JSON.stringify({ success: true, podcast: result.podcast }));
+      return;
+    }
+
+    console.log('');
+    console.log('  An admin reviews it, then publishes it. Once published, the feed');
+    console.log(`  lives at ${chalk.cyan(`${siteUrl()}/podcasts/${slug}/feed.xml`)}`);
+    console.log('  and that is the URL you give Apple Podcasts and Spotify.');
+    console.log('');
+  } catch (err) {
+    if (spinner) spinner.stop();
+    // The submit endpoint returns Apple's requirements as author-facing copy.
+    return fail(json, err.response?.data?.error || err.message);
+  }
+}
+
+// ============================================================
+// podcast info
+// ============================================================
+
+export async function podcastInfoCommand(slug, options = {}) {
+  const json = !!options.json;
+
+  if (!isAuthenticated()) {
+    return fail(json, "Authentication required. Run 'myvillage login' first.");
+  }
+
+  let result;
+  try {
+    result = await getPodcastDetail(slug);
+  } catch (err) {
+    return fail(json, err.response?.data?.error || err.message);
+  }
+
+  if (json) {
+    console.log(JSON.stringify({ success: true, ...result }));
+    return;
+  }
+
+  const p = result.podcast;
+  console.log('');
+  console.log(`  ${chalk.bold(p.title)} ${chalk.dim(`(${p.slug})`)}`);
+  console.log(`    ${chalk.dim('Status:')}   ${p.status.toLowerCase()}`);
+  console.log(`    ${chalk.dim('Category:')} ${p.category}${p.subcategory ? ` / ${p.subcategory}` : ''}`);
+  console.log(`    ${chalk.dim('Author:')}   ${p.authorName}`);
+  console.log(`    ${chalk.dim('Episodes:')} ${p.episodes?.length ?? 0}`);
+  if (p.status === 'PUBLISHED') {
+    console.log(`    ${chalk.dim('Feed:')}     ${chalk.cyan(result.feedUrl)}`);
+  }
+
+  const blockers = result.feedBlockers || [];
+  if (blockers.length > 0) {
+    console.log('');
+    console.log(chalk.yellow('  Before this show can go out:'));
+    for (const b of blockers) console.log(`    • ${b}`);
+  }
+  console.log('');
+}

package/src/commands/publish-episode.js

@@ -0,0 +1,347 @@
+import { existsSync, readFileSync, statSync } from 'fs';
+import { resolve, basename, extname } 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 {
+  createPodcastEpisode,
+  confirmEpisodeUpload,
+  getEpisodeUploadUrl,
+  getMyPodcasts,
+  submitEpisode,
+} from '../utils/api.js';
+
+/**
+ * publish-episode — upload an audio file as a podcast episode.
+ *
+ * The Listen pillar's counterpart to `publish-book`. Same shape: create the
+ * row, PUT the file straight to storage via a presigned URL, confirm, submit
+ * for review. The one addition is duration, which is read from the file's own
+ * headers here rather than server-side — the platform never decodes audio, so
+ * whoever holds the file is the only party that can cheaply know how long it is.
+ *
+ * See the platform's docs/features/podcasts.md.
+ */
+
+/** Mirrors ACCEPTED_AUDIO_EXTENSIONS server-side. Quoted so the failure is local. */
+const ACCEPTED_EXTENSIONS = ['mp3', 'm4a', 'mp4', 'aac', 'wav'];
+
+const EPISODE_TYPES = ['full', 'trailer', 'bonus'];
+
+// Server-enforced too. 90 minutes of 320kbps stereo is ~216MB.
+const MAX_AUDIO_MB = 500;
+
+function fail(json, message) {
+  if (json) {
+    console.log(JSON.stringify({ success: false, error: message }));
+  } else {
+    console.log(chalk.red(`  ✗ ${message}`));
+  }
+  process.exitCode = 1;
+}
+
+function titleFromFilename(audioPath) {
+  return basename(audioPath)
+    .replace(/\.[^.]+$/, '')
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function parsePositiveInt(value, label) {
+  if (value === undefined || value === null || value === '') return { value: undefined };
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) {
+    return { error: `${label} must be a whole number.` };
+  }
+  return { value: n };
+}
+
+/**
+ * Read the duration out of the file's own headers.
+ *
+ * Never fatal. <itunes:duration> is an optional tag, and an episode that
+ * publishes without a duration is a cosmetic loss; an episode that refuses to
+ * publish because a tag parser choked on an unusual encoder is a real one. The
+ * server independently sanity-checks whatever comes back against the byte count.
+ */
+async function readDuration(audioPath) {
+  try {
+    const { parseFile } = await import('music-metadata');
+    const metadata = await parseFile(audioPath, { duration: true });
+    const seconds = metadata?.format?.duration;
+    if (typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0) {
+      return Math.round(seconds);
+    }
+  } catch {
+    // Fall through — unknown duration is a supported state.
+  }
+  return null;
+}
+
+function formatDuration(seconds) {
+  if (!seconds) return 'unknown';
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = seconds % 60;
+  return h > 0
+    ? `${h}h ${String(m).padStart(2, '0')}m`
+    : `${m}m ${String(s).padStart(2, '0')}s`;
+}
+
+/**
+ * Pick which show the episode belongs to.
+ *
+ * Returns null when the author has no shows at all — publish-episode
+ * deliberately will not create one on the fly, because a show carries the
+ * owner email and cover art that Apple validates, and inventing those silently
+ * produces a feed that gets rejected weeks later.
+ */
+async function selectShow(json, nonInteractive) {
+  const spinner = json ? null : villageSpinner('Loading your shows...').start();
+  let podcasts;
+  try {
+    const result = await getMyPodcasts();
+    podcasts = result.podcasts || [];
+  } catch (err) {
+    if (spinner) spinner.fail(`Could not load your shows: ${err.message}`);
+    return { error: err.response?.data?.error || err.message };
+  }
+  if (spinner) spinner.stop();
+
+  if (podcasts.length === 0) {
+    return {
+      error:
+        "You do not have a show yet. Run 'myvillage podcast create' first — a show carries the cover art and owner email Apple checks before it will accept a feed.",
+    };
+  }
+  if (podcasts.length === 1) return { show: podcasts[0] };
+  if (nonInteractive) {
+    return {
+      error: `You have ${podcasts.length} shows. Pass --show <slug> to say which one this episode belongs to.`,
+    };
+  }
+
+  const { slug } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'slug',
+      message: 'Which show?',
+      choices: podcasts.map((p) => ({
+        name: `${p.title} ${chalk.dim(`(${p.slug}, ${p.status.toLowerCase()})`)}`,
+        value: p.slug,
+      })),
+    },
+  ]);
+
+  return { show: podcasts.find((p) => p.slug === slug) };
+}
+
+export async function publishEpisodeCommand(audioPath, options = {}) {
+  const json = !!options.json;
+  const nonInteractive = json || !!options.yes;
+
+  if (!isAuthenticated()) {
+    return fail(json, "Authentication required. Run 'myvillage login' first.");
+  }
+
+  // ── Validate the file locally, before any API call ──
+  const resolved = resolve(audioPath);
+  if (!existsSync(resolved)) {
+    return fail(json, `File not found: ${resolved}`);
+  }
+
+  const ext = extname(resolved).slice(1).toLowerCase();
+  if (!ACCEPTED_EXTENSIONS.includes(ext)) {
+    return fail(
+      json,
+      `"${ext || 'that file'}" is not a format podcast apps can play. Use one of: ${ACCEPTED_EXTENSIONS.join(', ')}.`,
+    );
+  }
+
+  const fileSize = statSync(resolved).size;
+  if (fileSize === 0) {
+    return fail(json, 'That audio file is empty.');
+  }
+  if (fileSize > MAX_AUDIO_MB * 1024 * 1024) {
+    return fail(
+      json,
+      `The file is ${Math.round(fileSize / 1024 / 1024)}MB — the limit is ${MAX_AUDIO_MB}MB. Export it at a lower bitrate.`,
+    );
+  }
+
+  // ── Flags ──
+  const episodeNumber = parsePositiveInt(options.episode, 'Episode number');
+  if (episodeNumber.error) return fail(json, episodeNumber.error);
+  const seasonNumber = parsePositiveInt(options.season, 'Season number');
+  if (seasonNumber.error) return fail(json, seasonNumber.error);
+
+  let episodeType = (options.type || 'full').toLowerCase();
+  if (!EPISODE_TYPES.includes(episodeType)) {
+    return fail(json, `Unknown episode type "${options.type}". Use one of: ${EPISODE_TYPES.join(', ')}`);
+  }
+
+  const durationOverride = parsePositiveInt(options.duration, 'Duration');
+  if (durationOverride.error) return fail(json, durationOverride.error);
+
+  // ── Which show ──
+  let show;
+  if (options.show) {
+    const result = await getMyPodcasts().catch((err) => ({ error: err }));
+    if (result.error) {
+      return fail(json, result.error.response?.data?.error || result.error.message);
+    }
+    show = (result.podcasts || []).find(
+      (p) => p.slug === options.show || p.id === options.show,
+    );
+    if (!show) {
+      return fail(json, `You do not have a show called "${options.show}".`);
+    }
+  } else {
+    const picked = await selectShow(json, nonInteractive);
+    if (picked.error) return fail(json, picked.error);
+    show = picked.show;
+  }
+
+  // ── Metadata: flags first, prompts for the gaps ──
+  let title = options.title?.trim() || null;
+  let description = options.description?.trim() || null;
+
+  if (nonInteractive) {
+    if (!title) title = titleFromFilename(resolved);
+  } else {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'title',
+        message: 'Episode title:',
+        default: title || titleFromFilename(resolved),
+        when: !title,
+        validate: (v) => (v.trim() ? true : 'A title is required.'),
+      },
+      {
+        type: 'input',
+        name: 'description',
+        message: 'Short description (shows in podcast apps):',
+        when: !description,
+      },
+    ]);
+    title = title || answers.title.trim();
+    if (!description && answers.description?.trim()) description = answers.description.trim();
+  }
+
+  // ── Duration, read locally ──
+  let spinner = json ? null : villageSpinner('Reading the audio...').start();
+  const durationSeconds = durationOverride.value ?? (await readDuration(resolved));
+  if (spinner) {
+    spinner.succeed(
+      durationSeconds
+        ? `${formatDuration(durationSeconds)} of audio`
+        : 'Audio read (could not determine length — the episode will publish without a duration)',
+    );
+  }
+
+  // ── Create → upload → confirm → submit ──
+  spinner = json ? null : villageSpinner('Creating the episode...').start();
+  let episode;
+  try {
+    const created = await createPodcastEpisode(show.id, {
+      title,
+      description: description || undefined,
+      episodeNumber: episodeNumber.value,
+      seasonNumber: seasonNumber.value,
+      episodeType: episodeType.toUpperCase(),
+      explicit: options.explicit === true ? true : undefined,
+    });
+    episode = created.episode;
+    if (spinner) spinner.succeed(`Episode created: ${chalk.bold(episode.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 getEpisodeUploadUrl(show.id, episode.id, {
+      fileName,
+      assetType: 'EPISODE_AUDIO',
+      fileSize,
+    });
+
+    await axios.put(urlResult.uploadUrl, readFileSync(resolved), {
+      headers: { 'Content-Type': urlResult.contentType },
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    });
+
+    await confirmEpisodeUpload(show.id, episode.id, {
+      s3Key: urlResult.s3Key,
+      assetType: 'EPISODE_AUDIO',
+      durationSeconds: durationSeconds ?? undefined,
+    });
+    if (spinner) spinner.succeed('Audio uploaded');
+  } catch (err) {
+    if (spinner) spinner.stop();
+    return fail(json, err.response?.data?.error || err.message);
+  }
+
+  spinner = json ? null : villageSpinner('Submitting for review...').start();
+  try {
+    await submitEpisode(show.id, episode.id);
+    if (spinner) spinner.succeed('Submitted');
+  } catch (err) {
+    if (spinner) spinner.stop();
+    return fail(json, err.response?.data?.error || err.message);
+  }
+
+  const config = getConfig();
+  const siteUrl = config.platformBaseUrl.replace(/\/api(\/v1)?$/, '');
+  const portalUrl = `${siteUrl}/podcasts`;
+  const feedUrl = `${siteUrl}/podcasts/${show.slug}/feed.xml`;
+
+  if (json) {
+    console.log(
+      JSON.stringify({
+        success: true,
+        showId: show.id,
+        showSlug: show.slug,
+        showStatus: show.status,
+        episodeId: episode.id,
+        episodeSlug: episode.slug,
+        title,
+        durationSeconds,
+        fileSize,
+        status: 'SUBMITTED',
+        feedUrl,
+        portalUrl,
+      }),
+    );
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.green('  ✓ Your episode is in the review queue.'));
+  console.log(`    ${chalk.dim('Show:')}      ${show.title}`);
+  console.log(`    ${chalk.dim('Episode:')}   ${title}`);
+  console.log(`    ${chalk.dim('Length:')}    ${formatDuration(durationSeconds)}`);
+  console.log('');
+
+  // The show's own state decides whether "published" will mean anything, so say
+  // so now rather than letting the author discover it after approval.
+  if (show.status === 'PUBLISHED') {
+    console.log(`  Once an admin approves it, it appears in the feed at`);
+    console.log(`  ${chalk.cyan(feedUrl)}`);
+  } else {
+    console.log(
+      `  ${chalk.yellow('Note:')} the show itself is ${chalk.bold(show.status.toLowerCase())}, so its feed is not live yet.`,
+    );
+    console.log(`  Episodes cannot go out until the show is published at ${chalk.cyan(portalUrl)}.`);
+  }
+  console.log('');
+}

package/src/index.js

@@ -19,6 +19,14 @@ 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 { publishEpisodeCommand } from './commands/publish-episode.js';
+import {
+  podcastCreateCommand,
+  podcastListCommand,
+  podcastCoverCommand,
+  podcastSubmitCommand,
+  podcastInfoCommand,
+} from './commands/podcast.js';
 import { statusCommand } from './commands/status.js';
 import { feedCommand } from './commands/feed.js';
 import {
@@ -243,6 +251,66 @@ export function run() {
     .option('--json', 'Output the result as JSON (implies non-interactive)')
     .action((pdf, options) => publishBookCommand(pdf, options));
 
+  program
+    .command('publish-episode <audio>')
+    .description('Publish an audio file as a podcast episode')
+    .option('-s, --show <slug>', 'Which show it belongs to (skips the prompt)')
+    .option('-t, --title <title>', 'Episode title (defaults to the file name)')
+    .option('-d, --description <text>', 'Short description, shown in podcast apps')
+    .option('-e, --episode <n>', 'Episode number')
+    .option('--season <n>', 'Season number')
+    .option('--type <type>', 'full | trailer | bonus', 'full')
+    .option('--duration <seconds>', 'Override the length read from the file')
+    .option('--explicit', 'Mark this episode explicit')
+    .option('-y, --yes', 'Non-interactive: defaults instead of prompts')
+    .option('--json', 'Output the result as JSON (implies non-interactive)')
+    .action((audio, options) => publishEpisodeCommand(audio, options));
+
+  // ── Podcast show management ────────────────────────
+
+  const podcastCmd = program
+    .command('podcast')
+    .description('Manage podcast shows (the feeds episodes go into)');
+
+  podcastCmd
+    .command('create')
+    .description('Create a show')
+    .option('-t, --title <title>', 'Show title')
+    .option('-d, --description <text>', 'What the show is about')
+    .option('-c, --category <category>', "One of Apple's categories, e.g. 'Kids & Family'")
+    .option('-a, --author <name>', 'The byline listeners see')
+    .option('-e, --email <email>', 'Owner email — Apple mails this to verify the feed')
+    .option('--language <lang>', 'BCP-47 language tag (default: en-us)')
+    .option('--explicit', 'Mark the show explicit')
+    .option('-y, --yes', 'Non-interactive: defaults instead of prompts')
+    .option('--json', 'Output the result as JSON (implies non-interactive)')
+    .action((options) => podcastCreateCommand(options));
+
+  podcastCmd
+    .command('list')
+    .description('List your shows')
+    .option('--json', 'Output the result as JSON')
+    .action((options) => podcastListCommand(options));
+
+  podcastCmd
+    .command('info <slug>')
+    .description('Show detail, including what still blocks its feed')
+    .option('--json', 'Output the result as JSON')
+    .action((slug, options) => podcastInfoCommand(slug, options));
+
+  podcastCmd
+    .command('cover <slug> <image>')
+    .description('Upload square cover art (1400-3000px)')
+    .option('--force', 'Upload even if the dimensions look wrong')
+    .option('--json', 'Output the result as JSON')
+    .action((slug, image, options) => podcastCoverCommand(slug, image, options));
+
+  podcastCmd
+    .command('submit <slug>')
+    .description('Submit a show for review')
+    .option('--json', 'Output the result as JSON')
+    .action((slug, options) => podcastSubmitCommand(slug, options));
+
   program
     .command('status')
     .description('Check deployment status of your games')

package/src/utils/api.js

@@ -632,6 +632,94 @@ export async function getMyStoryBooks() {
   return response.data;
 }
 
+// ── Podcasts API (/api/v1/podcasts) ────────────────────
+//
+// Shows and episodes are separate resources on purpose: a show is created once
+// and lives for years, episodes flow through it. Episode endpoints nest under
+// their show rather than sitting at /podcasts/episodes/... — a show whose title
+// slugged to "episodes" would otherwise shadow the whole route.
+
+export async function createPodcast(data) {
+  const client = getApiClient();
+  const response = await client.post('/podcasts', data);
+  return response.data;
+}
+
+export async function getMyPodcasts() {
+  const client = getApiClient();
+  const response = await client.get('/podcasts');
+  return response.data;
+}
+
+export async function getPodcastDetail(idOrSlug) {
+  const client = getApiClient();
+  const response = await client.get(`/podcasts/${encodeURIComponent(idOrSlug)}`);
+  return response.data;
+}
+
+export async function updatePodcast(idOrSlug, data) {
+  const client = getApiClient();
+  const response = await client.patch(`/podcasts/${encodeURIComponent(idOrSlug)}`, data);
+  return response.data;
+}
+
+export async function getPodcastUploadUrl(idOrSlug, data) {
+  const client = getApiClient();
+  const response = await client.post(`/podcasts/${encodeURIComponent(idOrSlug)}/upload-url`, data);
+  return response.data;
+}
+
+export async function confirmPodcastUpload(idOrSlug, data) {
+  const client = getApiClient();
+  const response = await client.post(`/podcasts/${encodeURIComponent(idOrSlug)}/confirm-upload`, data);
+  return response.data;
+}
+
+export async function submitPodcast(idOrSlug) {
+  const client = getApiClient();
+  const response = await client.post(`/podcasts/${encodeURIComponent(idOrSlug)}/submit`, {});
+  return response.data;
+}
+
+export async function createPodcastEpisode(showId, data) {
+  const client = getApiClient();
+  const response = await client.post(`/podcasts/${encodeURIComponent(showId)}/episodes`, data);
+  return response.data;
+}
+
+export async function getPodcastEpisodes(showId) {
+  const client = getApiClient();
+  const response = await client.get(`/podcasts/${encodeURIComponent(showId)}/episodes`);
+  return response.data;
+}
+
+export async function getEpisodeUploadUrl(showId, episodeId, data) {
+  const client = getApiClient();
+  const response = await client.post(
+    `/podcasts/${encodeURIComponent(showId)}/episodes/${encodeURIComponent(episodeId)}/upload-url`,
+    data,
+  );
+  return response.data;
+}
+
+export async function confirmEpisodeUpload(showId, episodeId, data) {
+  const client = getApiClient();
+  const response = await client.post(
+    `/podcasts/${encodeURIComponent(showId)}/episodes/${encodeURIComponent(episodeId)}/confirm-upload`,
+    data,
+  );
+  return response.data;
+}
+
+export async function submitEpisode(showId, episodeId) {
+  const client = getApiClient();
+  const response = await client.post(
+    `/podcasts/${encodeURIComponent(showId)}/episodes/${encodeURIComponent(episodeId)}/submit`,
+    {},
+  );
+  return response.data;
+}
+
 // ── GameKit SDK preflight ──────────────────────────────
 
 // Fetch the GUID allowlist for a specific SDK version. Public endpoint —