@x12i/youtube-video-uploader-cli 1.1.0 → 1.2.0

package/README.md

@@ -144,6 +144,32 @@ npx @x12i/youtube-video-uploader-cli ./my-videos --client-secrets-file ./client_
 
 ---
 
+## 🔁 Replacing a Video in a Playlist (`swap`)
+
+Re-uploads a song (e.g. a new version with lyrics subtitles) and swaps it into a playlist in place of the old video. The old video is **unlisted, never deleted**, so existing direct links keep working.
+
+```bash
+yt-uploader swap ./song-v2.mp4 --playlist PLxxxx --old-video VIDEOID
+yt-uploader swap ./song-v2.mp4 --playlist PLxxxx --old-video VIDEOID --dry-run
+```
+
+The swap runs as a resumable five-step state machine (state persisted to `.swap-history.json` after every step):
+
+1. **UPLOAD** — upload the new video *unlisted* (metadata carried over from the old video)
+2. **LOCATE** — find the old video's playlist item + position
+3. **INSERT** — insert the new video at the old position
+4. **REMOVE** — remove the old playlist item
+5. **FINALIZE** — old video → unlisted, new video → public
+
+If any step fails, re-run the same command — completed steps are skipped automatically (no duplicate uploads or playlist entries). A missing old video aborts with a "needs manual review" flag instead of guessing.
+
+**Quota cost:** ~150 shared-pool units + 1 upload-bucket unit per swap (well within the 10,000/day default pool).
+
+**Notes:**
+- OAuth scopes are now `youtube.upload` + `youtube.force-ssl` (narrower than before) — existing `token.json` files need a one-time re-consent.
+- The target playlist must use **Manual** ordering for position-preserving inserts (set in YouTube Studio).
+- Videos from an unverified Google Cloud project are forced private until the project passes YouTube's API audit.
+
 ## 🛠️ Programmatic Node.js API
 
 ```javascript

package/bin/cli.js

@@ -4,7 +4,9 @@ import { Command } from 'commander';
 import path from 'node:path';
 import fs from 'node:fs';
 import pc from 'picocolors';
-import { batchUpload, DAILY_DEFAULT_QUOTA } from '../src/index.js';
+import { google } from 'googleapis';
+import { batchUpload, DAILY_DEFAULT_QUOTA, swapSong, SwapStore, QUOTA_PER_SWAP } from '../src/index.js';
+import { authenticate } from '../src/auth.js';
 
 // Read package.json for version
 const pkgPath = new URL('../package.json', import.meta.url);
@@ -183,4 +185,117 @@ program
     }
   });
 
+program
+  .command('swap')
+  .description('Replace a song\'s video in a YouTube playlist: upload the new video, swap the playlist entry in place, unlist (never delete) the old video')
+  .argument('<videoFile>', 'Path to the new MP4 video file')
+  .requiredOption('--playlist <id>', 'Playlist ID containing the old video')
+  .requiredOption('--old-video <videoId>', 'Video ID of the old video to replace')
+  .option('-k, --key <songKey>', 'Stable song key for swap state tracking (default: video file basename)')
+  .option('--title <title>', 'Override the new video title (default: carried over from the old video)')
+  .option('--state-file <file>', 'Swap state filename (default: .swap-history.json in target dir)')
+  .option('--token-file <file>', 'Path to store or read OAuth token (default: token.json in cwd)')
+  .option('--client-secrets-file <file>', 'Path to client_secret.json downloaded from Google Cloud')
+  .option('--client-id <id>', 'Google OAuth Client ID')
+  .option('--client-secret <secret>', 'Google OAuth Client Secret')
+  .option('--fresh', 'Discard any previous swap state for this key and start over', false)
+  .option('-n, --dry-run', 'Print the swap plan without any API calls', false)
+  .option('-q, --quiet', 'Minimal output mode', false)
+  .action(async (videoFile, options) => {
+    const isQuiet = options.quiet;
+    const videoPath = path.resolve(videoFile);
+    const songKey = options.key || path.basename(videoPath);
+    const stateDir = process.cwd();
+
+    if (!isQuiet) {
+      console.log();
+      console.log(pc.bold(pc.red(`🔁 Playlist Video Swap`)) + ` ${pc.dim(`v${pkg.version}`)}`);
+      console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+      console.log(`${pc.bold('🎬 New Video      :')} ${pc.white(videoPath)}`);
+      console.log(`${pc.bold('🗑️  Old Video ID   :')} ${pc.white(options.oldVideo)}`);
+      console.log(`${pc.bold('📑 Playlist ID    :')} ${pc.white(options.playlist)}`);
+      console.log(`${pc.bold('🔑 Swap Key       :')} ${pc.white(songKey)}`);
+      console.log(pc.dim(`Estimated quota  : ~${QUOTA_PER_SWAP - 1} shared units + 1 upload`));
+      console.log();
+    }
+
+    if (!fs.existsSync(videoPath)) {
+      console.error(pc.red(`\n❌ Error: Video file not found: ${videoPath}\n`));
+      process.exit(1);
+    }
+
+    if (options.dryRun) {
+      if (!isQuiet) {
+        console.log(pc.yellow(`🔍 DRY RUN — the following steps would run:`));
+        console.log(`  1. UPLOAD    — videos.insert (unlisted), metadata carried over from old video`);
+        console.log(`  2. LOCATE    — playlistItems.list to find old item id + position`);
+        console.log(`  3. INSERT    — playlistItems.insert at the old position`);
+        console.log(`  4. REMOVE    — playlistItems.delete for the old item`);
+        console.log(`  5. FINALIZE  — old video → unlisted, new video → public`);
+        console.log();
+        console.log(pc.yellow(`✨ Dry run complete. No API calls were made.`));
+        console.log();
+      }
+      process.exit(0);
+    }
+
+    try {
+      const tokenFile = options.tokenFile
+        ? path.resolve(options.tokenFile)
+        : path.join(stateDir, 'token.json');
+
+      const auth = await authenticate({
+        tokenFile,
+        clientSecretsFile: options.clientSecretsFile,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+      });
+      const youtube = google.youtube({ version: 'v3', auth });
+
+      const store = new SwapStore(stateDir, options.stateFile);
+      const existing = store.getRecord(songKey);
+      if (existing && !options.fresh && !isQuiet) {
+        console.log(pc.cyan(`↩️  Resuming swap in progress (last status: ${existing.status}${existing.lastError ? ` — ${existing.lastError}` : ''})`));
+        console.log();
+      }
+
+      const { record } = await swapSong({
+        youtube,
+        songKey,
+        newVideoPath: videoPath,
+        playlistId: options.playlist,
+        oldVideoId: options.oldVideo,
+        meta: options.title ? { title: options.title } : undefined,
+        stateDir,
+        stateFile: options.stateFile,
+        fresh: options.fresh,
+        onEvent: (event) => {
+          if (isQuiet) return;
+          if (event.type === 'swap_step') {
+            console.log(pc.green(`  ✅ ${event.status.toUpperCase()}`));
+          } else if (event.type === 'swap_uploaded') {
+            console.log(pc.green(`  ⬆️  Uploaded new video: `) + pc.underline(pc.blue(event.url)));
+          } else if (event.type === 'swap_error') {
+            console.error(pc.red(`  ❌ Failed at swap step: ${event.error.message}`));
+            if (event.needsManualReview) {
+              console.error(pc.yellow(`     ⚠️  Needs manual review — the old video was not found in the playlist.`));
+            }
+          }
+        },
+      });
+
+      if (!isQuiet) {
+        console.log();
+        console.log(pc.green(pc.bold(`🎉 Swap complete!`)));
+        console.log(`  • Playlist entry replaced: ${pc.bold(options.playlist)} (position preserved)`);
+        console.log(`  • New video is public    : ${pc.underline(pc.blue(`https://youtu.be/${record.newVideoId}`))}`);
+        console.log(`  • Old video unlisted     : ${pc.dim(`https://youtu.be/${options.oldVideo} (direct links still work)`)}`);
+        console.log();
+      }
+    } catch (err) {
+      console.error(pc.red(`\n❌ Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/youtube-video-uploader-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "CLI tool to batch upload MP4 videos to YouTube via YouTube Data API v3 with OAuth2, metadata.json config, playlist assignment, and smart upload-state resume.",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/auth.js

@@ -8,7 +8,7 @@ import pc from 'picocolors';
 
 export const YOUTUBE_SCOPES = [
   'https://www.googleapis.com/auth/youtube.upload',
-  'https://www.googleapis.com/auth/youtube',
+  'https://www.googleapis.com/auth/youtube.force-ssl',
 ];
 
 export const DEFAULT_REDIRECT_URI = 'http://localhost:3000/oauth2callback';

package/src/index.d.ts

@@ -81,3 +81,76 @@ export const DAILY_DEFAULT_QUOTA: number;
 export const DEFAULT_CATEGORY_ID: string;
 export const DEFAULT_PRIVACY_STATUS: string;
 export const VALID_PRIVACY_STATUSES: Set<string>;
+
+// ─── Playlist video swap ───────────────────────────────────────────────────
+
+export type SwapStatus =
+  | 'pending'
+  | 'uploaded'
+  | 'located'
+  | 'inserted'
+  | 'removed'
+  | 'finalized'
+  | 'failed';
+
+export interface SwapRecord {
+  songKey: string;
+  oldVideoId: string;
+  playlistId: string;
+  newVideoPath?: string;
+  newVideoId?: string;
+  oldPlaylistItemId?: string;
+  oldPosition?: number;
+  newPlaylistItemId?: string;
+  status: SwapStatus;
+  lastError?: string;
+  updatedAt?: string;
+}
+
+export class SwapStore {
+  constructor(targetFolder?: string, stateFilename?: string);
+  getRecord(songKey: string): SwapRecord | null;
+  initRecord(record: { songKey: string; playlistId: string; oldVideoId: string; newVideoPath?: string }): SwapRecord;
+  updateRecord(songKey: string, fields: Partial<SwapRecord>): SwapRecord;
+  listRecords(status?: SwapStatus): SwapRecord[];
+}
+
+export function uploadNewVideo(
+  youtube: youtube_v3.Youtube,
+  newVideoPath: string,
+  opts?: { oldVideoId?: string; meta?: VideoMetadata; retries?: number }
+): Promise<{ videoId: string; url: string }>;
+
+export function findPlaylistItem(
+  youtube: youtube_v3.Youtube,
+  playlistId: string,
+  oldVideoId: string
+): Promise<{ playlistItemId: string; position: number } | null>;
+
+export function insertAtPosition(
+  youtube: youtube_v3.Youtube,
+  playlistId: string,
+  newVideoId: string,
+  position: number
+): Promise<{ newPlaylistItemId: string }>;
+
+export function removeOldItem(youtube: youtube_v3.Youtube, oldPlaylistItemId: string): Promise<void>;
+
+export function finalizeSwap(youtube: youtube_v3.Youtube, oldVideoId: string, newVideoId: string): Promise<void>;
+
+export function swapSong(params: {
+  youtube: youtube_v3.Youtube;
+  songKey: string;
+  newVideoPath: string;
+  playlistId: string;
+  oldVideoId: string;
+  meta?: VideoMetadata;
+  stateDir?: string;
+  stateFile?: string;
+  fresh?: boolean;
+  onEvent?: (event: { type: string; [key: string]: any }) => void;
+}): Promise<{ record: SwapRecord }>;
+
+export const QUOTA_PER_SWAP: number;
+export const DEFAULT_SWAP_STATE_FILENAME: string;
+export const SWAP_STATUSES: string[];

package/src/index.js

@@ -9,3 +9,12 @@ export {
   QUOTA_PER_PLAYLIST_ITEM,
   DAILY_DEFAULT_QUOTA,
 } from './uploader.js';
+export { SwapStore, DEFAULT_SWAP_STATE_FILENAME, SWAP_STATUSES } from './swap/store.js';
+export {
+  uploadNewVideo,
+  findPlaylistItem,
+  insertAtPosition,
+  removeOldItem,
+  finalizeSwap,
+} from './swap/steps.js';
+export { swapSong, QUOTA_PER_SWAP } from './swap/swapSong.js';

package/src/swap/steps.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import { uploadVideo } from '../uploader.js';
+
+/**
+ * The five individual steps of a playlist video swap. Each is a plain
+ * function over the googleapis youtube client so they can be composed and
+ * tested independently.
+ */
+
+/**
+ * Step 1 — Upload the new video as unlisted (never straight to public).
+ *
+ * Metadata (title/description/tags/category) is carried over from the old
+ * video's snippet when available so the replacement stays continuous.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} newVideoPath
+ * @param {object} [opts]
+ * @param {string} [opts.oldVideoId] - Fetch old video's snippet to carry over
+ * @param {object} [opts.meta] - Explicit metadata overrides
+ * @param {number} [opts.retries=3]
+ * @returns {Promise<{ videoId: string, url: string }>}
+ */
+export async function uploadNewVideo(youtube, newVideoPath, opts = {}) {
+  if (!fs.existsSync(newVideoPath)) {
+    throw new Error(`New video file not found: ${newVideoPath}`);
+  }
+
+  let meta = {
+    title: opts.meta?.title,
+    description: opts.meta?.description,
+    tags: opts.meta?.tags,
+    categoryId: opts.meta?.categoryId,
+    privacyStatus: 'unlisted',
+    selfDeclaredMadeForKids: opts.meta?.selfDeclaredMadeForKids ?? false,
+  };
+
+  // Carry over metadata from the old video where not explicitly overridden
+  if (opts.oldVideoId) {
+    try {
+      const res = await youtube.videos.list({
+        part: ['snippet', 'status'],
+        id: [opts.oldVideoId],
+      });
+      const old = res.data.items?.[0];
+      if (old) {
+        meta = {
+          title: meta.title || old.snippet?.title,
+          description: meta.description ?? old.snippet?.description,
+          tags: meta.tags || old.snippet?.tags || [],
+          categoryId: meta.categoryId || old.snippet?.categoryId,
+          privacyStatus: 'unlisted',
+          selfDeclaredMadeForKids: meta.selfDeclaredMadeForKids
+            ?? (old.status?.madeForKids !== undefined ? old.status.madeForKids : false),
+        };
+      }
+    } catch {
+      // Metadata carry-over is best-effort; explicit meta or defaults still apply
+    }
+  }
+
+  if (!meta.title) {
+    throw new Error('Cannot upload swap video without a title: provide meta.title or a reachable oldVideoId');
+  }
+
+  // Uploads are the most failure-prone step — retry with backoff
+  const retries = opts.retries ?? 3;
+  let lastErr;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      return await uploadVideo(youtube, newVideoPath, meta, 'unlisted');
+    } catch (err) {
+      lastErr = err;
+      if (attempt < retries) {
+        await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt - 1)));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * Step 2 — Locate the old video's playlistItem id and position.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} playlistId
+ * @param {string} oldVideoId
+ * @returns {Promise<{ playlistItemId: string, position: number } | null>} Null when the video is not in the playlist
+ */
+export async function findPlaylistItem(youtube, playlistId, oldVideoId) {
+  let pageToken;
+  do {
+    const { data } = await youtube.playlistItems.list({
+      part: ['snippet'],
+      playlistId,
+      maxResults: 50,
+      pageToken,
+    });
+    const match = (data.items || []).find(
+      item => item.snippet?.resourceId?.videoId === oldVideoId
+    );
+    if (match) {
+      return { playlistItemId: match.id, position: match.snippet.position };
+    }
+    pageToken = data.nextPageToken;
+  } while (pageToken);
+  return null;
+}
+
+/**
+ * Step 3 — Insert the new video into the playlist at the old item's position.
+ * The old item shifts down one slot temporarily; it is removed in step 4.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} playlistId
+ * @param {string} newVideoId
+ * @param {number} position
+ * @returns {Promise<{ newPlaylistItemId: string }>}
+ */
+export async function insertAtPosition(youtube, playlistId, newVideoId, position) {
+  const res = await youtube.playlistItems.insert({
+    part: ['snippet'],
+    requestBody: {
+      snippet: {
+        playlistId,
+        position,
+        resourceId: { kind: 'youtube#video', videoId: newVideoId },
+      },
+    },
+  });
+  return { newPlaylistItemId: res.data.id };
+}
+
+/**
+ * Step 4 — Remove the old video's playlist item.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} oldPlaylistItemId
+ */
+export async function removeOldItem(youtube, oldPlaylistItemId) {
+  await youtube.playlistItems.delete({ id: oldPlaylistItemId });
+}
+
+/**
+ * Step 5 — Finalize: unlist the old video (never delete), then publish the
+ * new one. Ordered so any earlier failure leaves the old video untouched.
+ *
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {string} oldVideoId
+ * @param {string} newVideoId
+ */
+export async function finalizeSwap(youtube, oldVideoId, newVideoId) {
+  await youtube.videos.update({
+    part: ['status'],
+    requestBody: { id: oldVideoId, status: { privacyStatus: 'unlisted' } },
+  });
+  await youtube.videos.update({
+    part: ['status'],
+    requestBody: { id: newVideoId, status: { privacyStatus: 'public' } },
+  });
+}

package/src/swap/store.js

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_SWAP_STATE_FILENAME = '.swap-history.json';
+
+export const SWAP_STATUSES = [
+  'pending',
+  'uploaded',
+  'located',
+  'inserted',
+  'removed',
+  'finalized',
+  'failed',
+];
+
+/**
+ * State manager for playlist video swaps. Persists a SwapRecord per song key
+ * so an interrupted swap can be safely resumed without re-uploading or
+ * double-inserting playlist items.
+ *
+ * @typedef {Object} SwapRecord
+ * @property {string} songKey - Stable key identifying this swap (song/file identifier)
+ * @property {string} oldVideoId
+ * @property {string} playlistId
+ * @property {string} [newVideoPath]
+ * @property {string} [newVideoId]
+ * @property {string} [oldPlaylistItemId]
+ * @property {number} [oldPosition]
+ * @property {string} [newPlaylistItemId]
+ * @property {string} status
+ * @property {string} [lastError]
+ * @property {string} [updatedAt]
+ */
+export class SwapStore {
+  /**
+   * @param {string} targetFolder
+   * @param {string} [stateFilename]
+   */
+  constructor(targetFolder, stateFilename = DEFAULT_SWAP_STATE_FILENAME) {
+    this.targetFolder = path.resolve(targetFolder || process.cwd());
+    this.statePath = path.join(this.targetFolder, stateFilename);
+    this.data = this._load();
+  }
+
+  _load() {
+    if (fs.existsSync(this.statePath)) {
+      try {
+        const content = fs.readFileSync(this.statePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        return { ...parsed, swaps: parsed.swaps || {} };
+      } catch {
+        return { swaps: {} };
+      }
+    }
+    return { swaps: {} };
+  }
+
+  save() {
+    try {
+      fs.writeFileSync(this.statePath, JSON.stringify(this.data, null, 2), 'utf-8');
+    } catch (err) {
+      console.warn(`Warning: Could not save swap state to ${this.statePath}: ${err.message}`);
+    }
+  }
+
+  /**
+   * @param {string} songKey
+   * @returns {SwapRecord | null}
+   */
+  getRecord(songKey) {
+    return this.data.swaps[songKey] || null;
+  }
+
+  /**
+   * Create or reset a pending swap record.
+   * @param {object} record
+   * @returns {SwapRecord}
+   */
+  initRecord(record) {
+    /** @type {SwapRecord} */
+    const full = {
+      status: 'pending',
+      updatedAt: new Date().toISOString(),
+      ...record,
+    };
+    this.data.swaps[full.songKey] = full;
+    this.save();
+    return full;
+  }
+
+  /**
+   * Merge fields into an existing record and persist immediately.
+   * @param {string} songKey
+   * @param {Partial<SwapRecord>} fields
+   * @returns {SwapRecord}
+   */
+  updateRecord(songKey, fields) {
+    if (!this.data.swaps[songKey]) {
+      throw new Error(`No swap record exists for key: ${songKey}`);
+    }
+    this.data.swaps[songKey] = {
+      ...this.data.swaps[songKey],
+      ...fields,
+      songKey,
+      updatedAt: new Date().toISOString(),
+    };
+    this.save();
+    return this.data.swaps[songKey];
+  }
+
+  /**
+   * List all records with the given status (or all records).
+   * @param {string} [status]
+   * @returns {SwapRecord[]}
+   */
+  listRecords(status) {
+    const all = Object.values(this.data.swaps);
+    return status ? all.filter(r => r.status === status) : all;
+  }
+}

package/src/swap/swapSong.js

@@ -0,0 +1,154 @@
+import { SwapStore } from './store.js';
+import {
+  uploadNewVideo,
+  findPlaylistItem,
+  insertAtPosition,
+  removeOldItem,
+  finalizeSwap,
+} from './steps.js';
+
+/** Shared-pool quota cost of one full swap (list + insert + delete + 2 updates). */
+export const QUOTA_PER_SWAP = 150 + 1; // ~150 shared units + 1 upload-bucket unit
+
+/**
+ * Swap state machine:
+ *
+ *   1. UPLOAD    — upload the new video (videos.insert), unlisted for now
+ *   2. LOCATE    — find the old video's playlistItem id + position
+ *   3. INSERT    — add the new video at the old item's position
+ *   4. REMOVE    — delete the old playlistItem
+ *   5. FINALIZE  — old video → unlisted, new video → public
+ *
+ * Every step persists state before moving on, so a crash or API error at any
+ * point can be safely resumed by re-running swapSong — completed steps are
+ * skipped, the old video is never deleted, and the upload is never repeated.
+ *
+ * @param {object} params
+ * @param {import('googleapis').youtube_v3.Youtube} params.youtube - Authorized youtube client
+ * @param {string} params.songKey - Stable key for this swap (song/file identifier)
+ * @param {string} params.newVideoPath - Path to the replacement video file
+ * @param {string} params.playlistId
+ * @param {string} params.oldVideoId
+ * @param {object} [params.meta] - Explicit new-video metadata overrides
+ * @param {string} [params.stateDir] - Where the swap state file lives (default: cwd)
+ * @param {string} [params.stateFile] - Custom state filename
+ * @param {boolean} [params.fresh=false] - Reset any existing record for songKey
+ * @param {(event: { type: string, [key: string]: any }) => void} [params.onEvent]
+ * @returns {Promise<{ record: any, dryRunPlan?: string[] }>}
+ */
+export async function swapSong(params) {
+  const {
+    youtube,
+    songKey,
+    newVideoPath,
+    playlistId,
+    oldVideoId,
+    meta,
+    stateDir,
+    stateFile,
+    fresh = false,
+    onEvent = () => {},
+  } = params;
+
+  if (!songKey || !newVideoPath || !playlistId || !oldVideoId) {
+    throw new Error('swapSong requires songKey, newVideoPath, playlistId and oldVideoId');
+  }
+
+  const store = new SwapStore(stateDir || process.cwd(), stateFile);
+  const existing = store.getRecord(songKey);
+
+  if (existing && !fresh && ['pending', 'uploaded', 'located', 'inserted', 'removed'].includes(existing.status)) {
+    onEvent({ type: 'swap_resume', songKey, status: existing.status });
+  }
+
+  const record = (existing && !fresh)
+    ? { ...existing, playlistId, oldVideoId, newVideoPath }
+    : store.initRecord({ songKey, playlistId, oldVideoId, newVideoPath, status: 'pending' });
+  if (existing && !fresh) {
+    // persist any refreshed params above
+    store.updateRecord(songKey, { playlistId, oldVideoId, newVideoPath });
+  }
+
+  /**
+   * Run one step, guarding against re-doing completed work.
+   * @template T
+   * @param {string} doneStatus - Status that marks this step complete
+   * @param {() => Promise<T>} fn
+   * @param {(result: T) => Partial<Record<string, any>>} [fieldsFromResult]
+   */
+  async function step(doneStatus, fn, fieldsFromResult) {
+    if (stepIndex(record.status) >= stepIndex(doneStatus)) return;
+    const result = await fn();
+    store.updateRecord(songKey, { status: doneStatus, lastError: undefined, ...(fieldsFromResult ? fieldsFromResult(result) : {}) });
+    onEvent({ type: 'swap_step', songKey, status: doneStatus });
+  }
+
+  try {
+    // 1. UPLOAD
+    await step('uploaded', async () => {
+      const alreadyUploaded = store.getRecord(songKey).newVideoId;
+      if (alreadyUploaded) {
+        return { videoId: alreadyUploaded };
+      }
+      const up = await uploadNewVideo(youtube, newVideoPath, { oldVideoId, meta });
+      onEvent({ type: 'swap_uploaded', songKey, newVideoId: up.videoId, url: up.url });
+      return up;
+    }, r => ({ newVideoId: r.videoId }));
+    const newVideoId = store.getRecord(songKey).newVideoId;
+
+    // 2. LOCATE
+    await step('located', async () => {
+      const found = await findPlaylistItem(youtube, playlistId, oldVideoId);
+      if (!found) {
+        const err = new Error(
+          `Old video ${oldVideoId} not found in playlist ${playlistId} — ` +
+          `it may have already been removed, or the video ID is wrong.`
+        );
+        err.needsManualReview = true;
+        throw err;
+      }
+      return found;
+    }, r => ({ oldPlaylistItemId: r.playlistItemId, oldPosition: r.position }));
+    const current = store.getRecord(songKey);
+
+    // 3. INSERT (guard: if a previous attempt already inserted the new video
+    // but crashed before persisting, reuse that item instead of duplicating it)
+    await step('inserted', async () => {
+      const alreadyInserted = await findPlaylistItem(youtube, playlistId, newVideoId);
+      if (alreadyInserted) {
+        return { newPlaylistItemId: alreadyInserted.playlistItemId };
+      }
+      return await insertAtPosition(youtube, playlistId, newVideoId, current.oldPosition);
+    }, r => ({ newPlaylistItemId: r.newPlaylistItemId }));
+
+    // 4. REMOVE
+    await step('removed', async () => {
+      await removeOldItem(youtube, current.oldPlaylistItemId);
+    });
+
+    // 5. FINALIZE
+    await step('finalized', async () => {
+      await finalizeSwap(youtube, oldVideoId, newVideoId);
+    });
+
+    onEvent({ type: 'swap_complete', songKey, oldVideoId, newVideoId, playlistId });
+    return { record: store.getRecord(songKey) };
+  } catch (err) {
+    const updated = store.updateRecord(songKey, { status: 'failed', lastError: err.message });
+    onEvent({ type: 'swap_error', songKey, error: err, needsManualReview: Boolean(err.needsManualReview) });
+    const wrapped = new Error(`Swap failed for ${songKey} (status persisted, safe to re-run): ${err.message}`);
+    wrapped.cause = err;
+    wrapped.record = updated;
+    throw wrapped;
+  }
+}
+
+/**
+ * Rank a status by how far through the state machine it is.
+ * @param {string} status
+ * @returns {number}
+ */
+function stepIndex(status) {
+  const order = ['pending', 'failed', 'uploaded', 'located', 'inserted', 'removed', 'finalized'];
+  return order.indexOf(status);
+}