spotifify 0.1.1

package/src/sync/apply.ts

@@ -0,0 +1,142 @@
+/**
+ * Execute a Plan against Spotify + the export folder, writing state back after every successful
+ * remote operation so a crash mid-way leaves a consistent (re-plannable) state. See DESIGN.md §6.
+ */
+import type { Config } from "../config.ts";
+import type { SpotifyApi } from "../spotify/api.ts";
+import { MANAGED_DESCRIPTION } from "../spotify/types.ts";
+import type { Repo } from "../state/repo.ts";
+import { chunk } from "../util/retry.ts";
+import { log } from "../util/log.ts";
+import { exportTrack } from "./export.ts";
+import type { ExportPlan, Plan, PlaylistPlan } from "./plan.ts";
+
+export interface ApplyDeps {
+  api: SpotifyApi;
+  repo: Repo;
+  cfg: Config;
+  prune: boolean;
+  now: number;
+}
+
+export interface ApplySummary {
+  created: number;
+  renamed: number;
+  added: number;
+  pruned: number;
+  moved: number;
+  replaced: number;
+  liked: number;
+  unliked: number;
+  exported: number;
+  exportErrors: number;
+}
+
+/** Replace the whole playlist only when it saves real calls: more than this many moves AND more than a third of the list. */
+const REPLACE_MIN_MOVES = 5;
+const REPLACE_MOVE_RATIO = 1 / 3;
+
+/** Applies playlist and library changes. Exports run separately (`applyExports`) before planning. */
+export async function applyPlan(plan: Plan, deps: ApplyDeps): Promise<ApplySummary> {
+  const s: ApplySummary = { created: 0, renamed: 0, added: 0, pruned: 0, moved: 0, replaced: 0, liked: 0, unliked: 0, exported: 0, exportErrors: 0 };
+
+  for (const p of plan.playlists) await applyPlaylist(p, deps, s);
+
+  if (plan.likes.add.length > 0) {
+    await deps.api.saveTracks(plan.likes.add);
+    deps.repo.addLiked(plan.likes.add, deps.now);
+    s.liked = plan.likes.add.length;
+  }
+  if (deps.prune && plan.likes.prune.length > 0) {
+    await deps.api.removeSavedTracks(plan.likes.prune);
+    deps.repo.removeLiked(plan.likes.prune);
+    s.unliked = plan.likes.prune.length;
+  }
+  return s;
+}
+
+/** Run the ffmpeg export step alone; also used by `spotifify export`. `uriChanged` counts re-exports whose `spotify:local:` identity differs from the previous export (the pasted entries for those are now stale). */
+export async function applyExports(plans: ExportPlan[], deps: { repo: Repo; cfg: Config; now: number }): Promise<{ exported: number; uriChanged: number; errors: number }> {
+  const out = { exported: 0, uriChanged: 0, errors: 0 };
+  for (const e of plans) {
+    const track = deps.repo.representativeTracks([e.canonicalKey]).get(e.canonicalKey);
+    if (!track?.file) continue;
+    try {
+      const previous = deps.repo.getExport(e.canonicalKey);
+      const r = await exportTrack(e, track, deps.cfg.export);
+      deps.repo.setExport({ canonicalKey: e.canonicalKey, exportPath: r.exportPath, localUri: r.localUri, contentHash: track.file.contentHash, exportedAt: deps.now });
+      out.exported++;
+      if (previous && previous.localUri !== r.localUri) out.uriChanged++;
+      log.info("exported", { path: r.exportPath, uri: r.localUri });
+    } catch (err) {
+      out.errors++;
+      log.error("export failed", { path: e.sourcePath, error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  return out;
+}
+
+async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary): Promise<void> {
+  const { api, repo, now } = deps;
+  let spotifyId = p.spotifyId;
+  let name = p.rename?.from ?? p.sourceName;
+
+  if (p.create) {
+    const created = await api.createPlaylist(p.create.name, MANAGED_DESCRIPTION);
+    spotifyId = created.id;
+    name = created.name;
+    repo.setSpotifyPlaylist({ sourcePlaylistId: p.sourcePlaylistId, spotifyId, name, snapshotId: created.snapshot_id, lastSyncedAt: null });
+    s.created++;
+    log.info("created playlist", { name, id: spotifyId });
+  }
+  if (spotifyId === null) throw new Error(`playlist plan for ${p.sourceName} has neither spotifyId nor create`);
+
+  if (p.rename) {
+    await api.renamePlaylist(spotifyId, p.rename.to);
+    name = p.rename.to;
+    s.renamed++;
+    log.info("renamed playlist", p.rename);
+  }
+
+  // Replace-all fast path: only when no local items exist and moving would cost noticeably more calls.
+  const useReplace = p.replaceAllowed && p.moves.length > REPLACE_MIN_MOVES && p.moves.length > p.targetOrder.length * REPLACE_MOVE_RATIO;
+  let snapshot: string | null = null;
+
+  if (useReplace) {
+    // Prune not requested → pruned items were kept in targetOrder by the planner, so nothing is lost here.
+    snapshot = await api.replacePlaylistItems(spotifyId, p.targetOrder);
+    repo.addManaged(spotifyId, p.adds, now);
+    if (deps.prune) repo.removeManaged(spotifyId, p.prune.map((x) => x.uri));
+    s.added += p.adds.length;
+    s.pruned += deps.prune ? p.prune.length : 0;
+    s.replaced++;
+    log.info("replaced playlist contents", { name, items: p.targetOrder.length });
+  } else {
+    for (const uris of chunk(p.adds, 100)) {
+      snapshot = await api.addPlaylistItems(spotifyId, uris);
+      repo.addManaged(spotifyId, uris, now);
+      s.added += uris.length;
+    }
+    if (deps.prune && p.prune.length > 0) {
+      snapshot ??= (await api.getPlaylist(spotifyId))?.snapshot_id ?? null;
+      if (snapshot === null) throw new Error(`playlist ${spotifyId} vanished during apply`);
+      const items = p.prune.map((x) => (x.uri.startsWith("spotify:local:") ? { uri: x.uri, positions: x.positions } : { uri: x.uri }));
+      snapshot = await api.removePlaylistItems(spotifyId, items, snapshot);
+      repo.removeManaged(spotifyId, p.prune.map((x) => x.uri));
+      s.pruned += p.prune.length;
+    }
+    if (p.moves.length > 0) {
+      snapshot ??= (await api.getPlaylist(spotifyId))?.snapshot_id ?? null;
+      if (snapshot === null) throw new Error(`playlist ${spotifyId} vanished during apply`);
+      for (const m of p.moves) {
+        snapshot = await api.reorderPlaylistItems(spotifyId, m.rangeStart, m.insertBefore, snapshot);
+        s.moved++;
+      }
+    }
+  }
+
+  if (p.adds.length > 0 || p.moves.length > 0 || p.prune.length > 0) {
+    log.info("synced playlist", { name, added: p.adds.length, pruned: deps.prune ? p.prune.length : 0, moves: p.moves.length, awaiting: p.awaiting.length });
+  }
+  repo.setSpotifyPlaylist({ sourcePlaylistId: p.sourcePlaylistId, spotifyId, name, snapshotId: snapshot, lastSyncedAt: now });
+}

package/src/sync/duration.ts

@@ -0,0 +1,115 @@
+/**
+ * Whole-second duration exactly as the Spotify desktop client computes it for its local-file index —
+ * the value it writes into the last `spotify:local:` segment. Verified against the client's index for
+ * 81 CBR mp3 files (ffmpeg-written Info frame): floor((xingFrames + 1) * samplesPerFrame / sampleRate),
+ * which for CBR equals floor(audioBytes * 8 / bitrate). ffprobe's duration (gapless-trimmed, Info frame
+ * excluded) is up to ~0.05 s shorter and floors differently for 4 of those 81 files, so it cannot be used.
+ * VBR mp3 ("Xing" rather than "Info") is not verified; `exportTrack` re-encodes such files to CBR.
+ * m4a: floor(mvhd duration / timescale) [unverified against the client; no m4a in the sample].
+ */
+
+export interface Mp3Probe {
+  durationSec: number;
+  /** "Xing" frame present: variable bitrate, duration formula unverified */
+  vbr: boolean;
+}
+
+// index: [MPEG1, MPEG2, MPEG2.5] × sample-rate index
+const SAMPLE_RATES: Record<number, readonly number[]> = { 3: [44100, 48000, 32000], 2: [22050, 24000, 16000], 0: [11025, 12000, 8000] };
+// kbit/s by layer for MPEG1 and MPEG2/2.5
+const BITRATES_V1: Record<number, readonly number[]> = {
+  3: [0, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448],
+  2: [0, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384],
+  1: [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320],
+};
+const BITRATES_V2: Record<number, readonly number[]> = {
+  3: [0, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256],
+  2: [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
+  1: [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
+};
+
+interface FrameHeader {
+  sampleRate: number;
+  samplesPerFrame: number;
+  bitrateKbps: number;
+  /** offset of the Xing/Info tag inside the frame (after side info) */
+  xingOffset: number;
+}
+
+function parseFrameHeader(b: Uint8Array, at: number): FrameHeader | null {
+  if (at + 4 > b.length) return null;
+  const b1 = b[at + 1]!;
+  const b2 = b[at + 2]!;
+  const b3 = b[at + 3]!;
+  if (b[at] !== 0xff || (b1 & 0xe0) !== 0xe0) return null;
+  const version = (b1 >> 3) & 3; // 3 MPEG1, 2 MPEG2, 0 MPEG2.5, 1 reserved
+  const layer = (b1 >> 1) & 3; // 3 Layer I, 2 Layer II, 1 Layer III, 0 reserved
+  const bitrateIdx = b2 >> 4;
+  const srIdx = (b2 >> 2) & 3;
+  if (version === 1 || layer === 0 || bitrateIdx === 0 || bitrateIdx === 15 || srIdx === 3) return null;
+  const sampleRate = SAMPLE_RATES[version]![srIdx]!;
+  const bitrateKbps = (version === 3 ? BITRATES_V1 : BITRATES_V2)[layer]![bitrateIdx]!;
+  const samplesPerFrame = layer === 3 ? 384 : layer === 2 || version === 3 ? 1152 : 576;
+  const mono = (b3 >> 6) === 3;
+  const xingOffset = 4 + (version === 3 ? (mono ? 17 : 32) : mono ? 9 : 17);
+  return { sampleRate, samplesPerFrame, bitrateKbps, xingOffset };
+}
+
+function id3v2End(b: Uint8Array): number {
+  if (b.length < 10 || b[0] !== 0x49 || b[1] !== 0x44 || b[2] !== 0x33) return 0;
+  const size = ((b[6]! & 0x7f) << 21) | ((b[7]! & 0x7f) << 14) | ((b[8]! & 0x7f) << 7) | (b[9]! & 0x7f);
+  return 10 + size + (b[5]! & 0x10 ? 10 : 0);
+}
+
+const ascii = (b: Uint8Array, at: number, n: number) => String.fromCharCode(...b.subarray(at, at + n));
+
+export function probeMp3(b: Uint8Array): Mp3Probe | null {
+  let at = id3v2End(b);
+  let hdr: FrameHeader | null = null;
+  for (; at + 4 <= b.length; at++) {
+    hdr = parseFrameHeader(b, at);
+    if (hdr) break;
+  }
+  if (!hdr) return null;
+  const tag = ascii(b, at + hdr.xingOffset, 4);
+  const vbr = tag === "Xing";
+  if (vbr || tag === "Info") {
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    const flags = view.getUint32(at + hdr.xingOffset + 4);
+    if (flags & 1) {
+      const frames = view.getUint32(at + hdr.xingOffset + 8);
+      return { durationSec: Math.floor(((frames + 1) * hdr.samplesPerFrame) / hdr.sampleRate), vbr };
+    }
+  }
+  const tail = b.length >= 128 && ascii(b, b.length - 128, 3) === "TAG" ? 128 : 0;
+  const audioBytes = b.length - at - tail;
+  return { durationSec: Math.floor((audioBytes * 8) / (hdr.bitrateKbps * 1000)), vbr };
+}
+
+/** floor(mvhd.duration / mvhd.timescale); null when no movie header is found. */
+export function probeMp4DurationSec(b: Uint8Array): number | null {
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  const walk = (start: number, end: number): number | null => {
+    let at = start;
+    while (at + 8 <= end) {
+      let size = view.getUint32(at);
+      const type = ascii(b, at + 4, 4);
+      let header = 8;
+      if (size === 1) {
+        size = Number(view.getBigUint64(at + 8));
+        header = 16;
+      } else if (size === 0) size = end - at;
+      if (size < header) return null;
+      if (type === "moov") return walk(at + header, at + size);
+      if (type === "mvhd") {
+        const version = b[at + header]!;
+        const timescale = view.getUint32(at + header + (version === 1 ? 20 : 12));
+        const duration = version === 1 ? Number(view.getBigUint64(at + header + 24)) : view.getUint32(at + header + 16);
+        return timescale > 0 ? Math.floor(duration / timescale) : null;
+      }
+      at += size;
+    }
+    return null;
+  };
+  return walk(0, b.length);
+}

package/src/sync/export.ts

@@ -0,0 +1,159 @@
+/**
+ * Export one unmatched local track into the Spotify desktop "Local Files" folder.
+ * Every file goes through ffmpeg so tags are canonical and the resulting `spotify:local:` URI is
+ * predictable. mp3/m4a keep their codec; everything else is transcoded to mp3. See DESIGN.md §6.5.
+ */
+import { link, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+import type { Config } from "../config.ts";
+import { decryptNcm } from "../sources/local/ncm.ts";
+import type { SourceTrackRow } from "../state/repo.ts";
+import { buildLocalUri } from "../spotify/localUri.ts";
+import { probeMp3, probeMp4DurationSec } from "./duration.ts";
+import { log } from "../util/log.ts";
+import type { ExportPlan } from "./plan.ts";
+import { RetryableError, withRetry } from "../util/retry.ts";
+
+export interface ExportResult {
+  exportPath: string;
+  localUri: string;
+  /** tag values actually written */
+  tags: { artist: string; album: string; title: string };
+  /** whole seconds as the desktop client will index them (last uri segment) */
+  durationSec: number;
+}
+
+const COPY_EXT: Record<string, "mp3" | "m4a"> = { mp3: "mp3", m4a: "m4a", mp4: "m4a", aac: "m4a" };
+
+export class ExportError extends Error {}
+
+export async function exportTrack(plan: ExportPlan, track: SourceTrackRow, cfg: Config["export"]): Promise<ExportResult> {
+  const tmpBase = join(tmpdir(), `spotifify-${track.file?.contentHash.slice(0, 16) ?? Date.now()}`);
+  const cleanup: string[] = [];
+  try {
+    let input = plan.sourcePath;
+    let inputExt = extname(plan.sourcePath).slice(1).toLowerCase();
+    let coverPath: string | null = null;
+    let tags = { artist: track.artists.join(", "), album: track.album ?? "", title: track.title };
+
+    if (plan.decryptNcm) {
+      const { meta, cover } = await decryptNcm(plan.sourcePath, `${tmpBase}.${"audio"}`);
+      input = `${tmpBase}.audio`;
+      cleanup.push(input);
+      inputExt = meta.format.toLowerCase();
+      tags = { artist: meta.artist.map(([name]) => name).join(", "), album: meta.album, title: meta.musicName };
+      if (cover && cover.length > 0) {
+        coverPath = `${tmpBase}.cover`;
+        await writeFile(coverPath, cover);
+        cleanup.push(coverPath);
+      }
+    }
+    const outExt = COPY_EXT[inputExt] ?? "mp3";
+    const mode: "copy" | "mp3" = COPY_EXT[inputExt] ? "copy" : "mp3";
+    const exportPath = join(cfg.dir, `${plan.baseName}.${outExt}`);
+    // The desktop client watches export.dir: it parses a path once when the entry is created and drops it
+    // when the entry disappears, never re-reading in between. So ffmpeg must not write the final name
+    // (a half-written file is indexed with an unknown duration and never plays); the finished file is
+    // produced under a non-audio extension and then placed as a new, complete entry (see placeExport).
+    const partPath = `${exportPath}.part`;
+    cleanup.push(partPath);
+    await mkdir(cfg.dir, { recursive: true });
+
+    const encode = ["-c:a", "libmp3lame", "-b:a", cfg.bitrate];
+    const codec = mode === "copy" ? ["-c:a", "copy"] : encode;
+    let withCover = await runFfmpeg(cfg.ffmpeg, input, inputExt, coverPath, tags, codec, outExt, partPath);
+    if (!withCover.ok) {
+      // Cover muxing is the fragile part (odd picture streams, mp4 attached_pic quirks): retry audio-only.
+      const audioOnly = await runFfmpeg(cfg.ffmpeg, input, inputExt, null, tags, codec, outExt, partPath, false);
+      if (!audioOnly.ok) throw new ExportError(`ffmpeg failed for ${plan.sourcePath}: ${audioOnly.stderr}`);
+      log.warn("exported without cover art", { path: exportPath });
+    }
+    let durationSec = await probeDuration(partPath, outExt);
+    if (durationSec === null && outExt === "mp3" && mode === "copy") {
+      // A copied VBR stream: the client's duration for "Xing" files is unverified, so re-encode to CBR.
+      withCover = await runFfmpeg(cfg.ffmpeg, input, inputExt, coverPath, tags, encode, outExt, partPath);
+      if (!withCover.ok) throw new ExportError(`ffmpeg re-encode failed for ${plan.sourcePath}: ${withCover.stderr}`);
+      durationSec = await probeDuration(partPath, outExt);
+    }
+    if (durationSec === null) throw new ExportError(`cannot determine the client duration of ${exportPath}`);
+    await placeExport(partPath, exportPath);
+
+    return { exportPath, localUri: buildLocalUri({ ...tags, durationSec }), tags, durationSec };
+  } finally {
+    await Promise.all(cleanup.map((p) => rm(p, { force: true })));
+  }
+}
+
+/**
+ * Make the finished file appear at `exportPath` as a freshly created, complete entry. A hard link to the
+ * `.part` file is atomic and raises the watcher's "added" event with the whole content already there;
+ * a rename is only the fallback for filesystems without hard links (the client then sees the file at its
+ * next restart or folder toggle). An existing file is removed first so the client drops its old entry;
+ * that fails with EPERM/EBUSY while the client has it open (playing), which clears within seconds.
+ */
+async function placeExport(partPath: string, exportPath: string): Promise<void> {
+  await withRetry(
+    async () => {
+      try {
+        await rm(exportPath, { force: true });
+      } catch (e) {
+        const code = (e as NodeJS.ErrnoException).code;
+        if (code === "EPERM" || code === "EBUSY") throw new RetryableError(`${code} replacing ${exportPath}`);
+        throw e;
+      }
+    },
+    { attempts: 6, baseMs: 500 },
+  );
+  try {
+    await link(partPath, exportPath);
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code !== "EXDEV" && code !== "EPERM" && code !== "ENOSYS" && code !== "ENOTSUP") throw e;
+    log.warn("hard link unavailable, renaming instead; the desktop client will only index the file after a restart", { path: exportPath });
+    await rename(partPath, exportPath);
+  }
+}
+
+/** null: unparsable, or a VBR mp3 whose client duration is not predictable. */
+async function probeDuration(path: string, ext: "mp3" | "m4a"): Promise<number | null> {
+  const buf = await readFile(path);
+  if (ext === "m4a") return probeMp4DurationSec(buf);
+  const p = probeMp3(buf);
+  return p === null || p.vbr ? null : p.durationSec;
+}
+
+async function runFfmpeg(
+  ffmpeg: string,
+  input: string,
+  inputExt: string,
+  coverPath: string | null,
+  tags: ExportResult["tags"],
+  codec: string[],
+  outExt: string,
+  outPath: string,
+  includeCover = true,
+): Promise<{ ok: boolean; stderr: string }> {
+  const args = ["-y", "-hide_banner", "-loglevel", "error"];
+  // Raw decrypted ncm audio has no extension; tell ffmpeg the container explicitly.
+  if (input.endsWith(".audio")) args.push("-f", inputExt === "mp3" ? "mp3" : inputExt);
+  args.push("-i", input);
+  if (coverPath) args.push("-i", coverPath);
+  args.push("-map", "0:a:0");
+  if (includeCover) {
+    if (coverPath) args.push("-map", "1:v:0");
+    else args.push("-map", "0:v:0?");
+    args.push("-c:v", "copy", "-disposition:v:0", "attached_pic");
+  }
+  args.push("-map_metadata", "-1", "-map_chapters", "-1");
+  args.push("-metadata", `title=${tags.title}`, "-metadata", `artist=${tags.artist}`, "-metadata", `album=${tags.album}`);
+  args.push(...codec);
+  if (outExt === "mp3") args.push("-id3v2_version", "3", "-write_id3v1", "1");
+  if (outExt === "m4a") args.push("-movflags", "+faststart");
+  args.push("-f", outExt === "m4a" ? "mp4" : "mp3", outPath);
+
+  const proc = Bun.spawn([ffmpeg, ...args], { stdout: "ignore", stderr: "pipe", stdin: "ignore" });
+  const stderr = await new Response(proc.stderr).text();
+  const code = await proc.exited;
+  return { ok: code === 0, stderr: stderr.trim() };
+}

package/src/sync/plan.ts

@@ -0,0 +1,205 @@
+/**
+ * Plan = pure data describing the difference between desired state (sources + match decisions)
+ * and the remote Spotify state. Computed by `computePlaylistPlan` (pure) / `buildPlan` (run.ts),
+ * printed by `--dry-run`, executed by `apply`. See DESIGN.md §6.
+ */
+import type { LocalExportRow } from "../state/repo.ts";
+import { buildLocalUri, parseLocalUri } from "../spotify/localUri.ts";
+import { planMoves } from "./reorder.ts";
+
+export interface DesiredItem {
+  uri: string;
+  kind: "spotify" | "local";
+  canonicalKey: string;
+}
+
+export interface Move {
+  /** index of the item to move in the *current* order at the time this move is applied */
+  rangeStart: number;
+  /** target index (Spotify `insert_before` semantics) */
+  insertBefore: number;
+}
+
+export interface PlaylistPlan {
+  sourcePlaylistId: number;
+  sourceName: string;
+  /** null when the playlist must be created first */
+  spotifyId: string | null;
+  create: { name: string } | null;
+  rename: { from: string; to: string } | null;
+  /** spotify:track URIs to POST, in desired order */
+  adds: string[];
+  /** local items that must be pasted into the desktop client by the user */
+  awaiting: DesiredItem[];
+  /** tool-managed remote items no longer in the source; removed only with --prune */
+  prune: Array<{ uri: string; positions: number[] }>;
+  /** remote items not managed by this tool; never removed, kept at the tail */
+  foreign: string[];
+  /** minimal move sequence to reach desired order (after adds, and prune when enabled) */
+  moves: Move[];
+  /** full target order (after adds/prune) — used by the replace-all fast path */
+  targetOrder: string[];
+  /** when true, apply may replace the whole playlist instead of moving (no local items involved) */
+  replaceAllowed: boolean;
+}
+
+export interface LikePlan {
+  /** spotify track ids to PUT /me/tracks */
+  add: string[];
+  /** tool-liked ids no longer desired; removed only with --prune */
+  prune: string[];
+}
+
+export interface ExportPlan {
+  canonicalKey: string;
+  sourcePath: string;
+  /** sanitized file name without extension, unique within export.dir */
+  baseName: string;
+  decryptNcm: boolean;
+}
+
+export interface Plan {
+  playlists: PlaylistPlan[];
+  likes: LikePlan;
+  exports: ExportPlan[];
+  /** canonical keys needing human review */
+  reviewPending: number;
+}
+
+export interface RemoteItem {
+  uri: string;
+  isLocal: boolean;
+  /**
+   * A local entry that names one of our exports but with an identity the client will never resolve
+   * (different duration segment, tags from an earlier export). Removed with --prune so a correct paste can replace it.
+   */
+  stale: boolean;
+}
+
+export interface PlaylistPlanInput {
+  sourcePlaylistId: number;
+  sourceName: string;
+  targetName: string;
+  /** existing remote playlist (already verified to exist), or null */
+  spotify: { id: string; name: string } | null;
+  /** ordered, deduped by uri */
+  desired: DesiredItem[];
+  /** current remote order; local uris already canonicalized via `resolveRemoteLocalUri` */
+  remote: RemoteItem[];
+  /** uris this tool added to the remote playlist */
+  managed: Set<string>;
+  pruneEnabled: boolean;
+}
+
+/** Exported titles once carried this marker; remote entries created from them are stale. */
+const LEGACY_TITLE_SUFFIX = / \(local\)$/;
+
+export interface ResolvedRemoteLocal {
+  uri: string;
+  stale: boolean;
+}
+
+/**
+ * Map a remote local-file uri onto our export identities. Same artist/album/title/duration as an export
+ * → the export's `local_uri`. Same artist/album/title but a different identity (wrong or missing
+ * duration segment, legacy title suffix) → stale. Anything else is left untouched (a foreign local file).
+ */
+export function resolveRemoteLocalUri(remoteUri: string, exports: readonly LocalExportRow[]): ResolvedRemoteLocal {
+  const parts = parseLocalUri(remoteUri);
+  if (!parts) return { uri: remoteUri, stale: false };
+  const fold = (s: string) => s.replace(LEGACY_TITLE_SUFFIX, "").trim().toLowerCase();
+  for (const e of exports) {
+    const p = parseLocalUri(e.localUri);
+    if (!p) continue;
+    if (fold(p.artist) !== fold(parts.artist) || fold(p.album) !== fold(parts.album) || fold(p.title) !== fold(parts.title)) continue;
+    const exact = parts.durationSec === p.durationSec && parts.title === p.title;
+    // stale entries keep the API's exact uri: removal of local items needs it verbatim alongside positions
+    return exact ? { uri: e.localUri, stale: false } : { uri: remoteUri, stale: true };
+  }
+  return { uri: buildLocalUri(parts), stale: false };
+}
+
+export function computePlaylistPlan(input: PlaylistPlanInput): PlaylistPlan {
+  const { desired, remote, managed, pruneEnabled } = input;
+  const desiredSet = new Set(desired.map((d) => d.uri));
+
+  if (input.spotify === null) {
+    return {
+      sourcePlaylistId: input.sourcePlaylistId,
+      sourceName: input.sourceName,
+      spotifyId: null,
+      create: { name: input.targetName },
+      rename: null,
+      adds: desired.filter((d) => d.kind === "spotify").map((d) => d.uri),
+      awaiting: desired.filter((d) => d.kind === "local"),
+      prune: [],
+      foreign: [],
+      moves: [],
+      targetOrder: desired.filter((d) => d.kind === "spotify").map((d) => d.uri),
+      replaceAllowed: false,
+    };
+  }
+
+  const remoteSet = new Set(remote.map((r) => r.uri));
+  const adds = desired.filter((d) => d.kind === "spotify" && !remoteSet.has(d.uri)).map((d) => d.uri);
+  const awaiting = desired.filter((d) => d.kind === "local" && !remoteSet.has(d.uri));
+
+  const prune: PlaylistPlan["prune"] = [];
+  const pruneByUri = new Map<string, number[]>();
+  const foreign: string[] = [];
+  remote.forEach((r, i) => {
+    if (desiredSet.has(r.uri)) return;
+    if (managed.has(r.uri) || r.stale) {
+      let positions = pruneByUri.get(r.uri);
+      if (!positions) {
+        positions = [];
+        pruneByUri.set(r.uri, positions);
+        prune.push({ uri: r.uri, positions });
+      }
+      positions.push(i);
+    } else if (!foreign.includes(r.uri)) {
+      foreign.push(r.uri);
+    }
+  });
+
+  // Predict the order after adds (appended) and prune (when enabled), tokenizing duplicates so
+  // the reorder planner sees a permutation.
+  const pruneSet = pruneEnabled ? new Set(pruneByUri.keys()) : new Set<string>();
+  const occurrence = new Map<string, number>();
+  const token = (uri: string) => {
+    const n = occurrence.get(uri) ?? 0;
+    occurrence.set(uri, n + 1);
+    return `${uri}#${n}`;
+  };
+  const current: string[] = [];
+  for (const r of remote) if (!pruneSet.has(r.uri)) current.push(token(r.uri));
+  for (const uri of adds) current.push(token(uri));
+
+  const currentSet = new Set(current);
+  const target: string[] = [];
+  for (const d of desired) {
+    const t = `${d.uri}#0`;
+    if (currentSet.has(t)) target.push(t);
+  }
+  const targetSet = new Set(target);
+  for (const t of current) if (!targetSet.has(t)) target.push(t);
+
+  const moves = planMoves(current, target);
+  const targetOrder = target.map((t) => t.slice(0, t.lastIndexOf("#")));
+  const anyLocal = remote.some((r) => r.isLocal) || targetOrder.some((u) => u.startsWith("spotify:local:"));
+
+  return {
+    sourcePlaylistId: input.sourcePlaylistId,
+    sourceName: input.sourceName,
+    spotifyId: input.spotify.id,
+    create: null,
+    rename: input.spotify.name === input.targetName ? null : { from: input.spotify.name, to: input.targetName },
+    adds,
+    awaiting,
+    prune,
+    foreign,
+    moves,
+    targetOrder,
+    replaceAllowed: !anyLocal,
+  };
+}