spotifify 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.1.3](https://github.com/FYWinds/Spotifify/compare/v0.1.2...v0.1.3) (2026-09-05)
+
+
+### Bug Fixes
+
+* **match:** let a fingerprint hit decide for a pooled track ([75c2717](https://github.com/FYWinds/Spotifify/commit/75c27178f16b277a5062ff3aff5c396bbc36ec4b))
+* **sources:** unreadable files and partial pulls are not deletions ([0fb80a7](https://github.com/FYWinds/Spotifify/commit/0fb80a7a3af3a03d06543e118be1cb7171fd5880))
+* **spotify:** make playlist writes safe to interrupt and retry ([5882336](https://github.com/FYWinds/Spotifify/commit/5882336ec47f4c8ededef8712312864f7d1d7f16))
+* **sync:** never prune beyond what the run reconciles ([fd1d732](https://github.com/FYWinds/Spotifify/commit/fd1d732fa06cfcff5b855f60ff90c68414d41bb9))
+
 ## [0.1.2](https://github.com/FYWinds/Spotifify/compare/v0.1.1...v0.1.2) (2026-09-05)
 
 

package/README.md

@@ -67,7 +67,7 @@ State lives in `~/.spotifify` (`config.toml`, `state.db`, logs); override with `
 | `init [--force\|--upgrade]` | Write the config template; `--upgrade` merges options added in newer versions into your file (values kept, `.bak` written). |
 | `doctor` | Check config, state db, `ffmpeg`/`fpcalc`, token scopes, search-quota deadline, and the desktop client's local-files index (exports it never indexed or indexed with another duration — the two causes of grey rows). |
 | `auth spotify` / `auth netease [--cookie …]` | Log in. |
-| `sync [--dry-run] [--prune] [--source netease\|local] [--playlist NAME] [--skip-match]` | Pull → match → export → plan → apply → report. `--prune` also removes superseded local entries and exported files no longer needed. Exit code `3` = re-authenticate. |
+| `sync [--dry-run] [--prune] [--source netease\|local] [--playlist NAME] [--skip-match]` | Pull → match → export → plan → apply → report. `--prune` also removes superseded local entries and exported files no longer needed — never beyond what the run can account for: with `--playlist`/`--source` nothing is unliked that another mirrored playlist wants, exports still referenced from a playlist outside the run are kept, and a run that mirrors no playlist at all prunes nothing. Exit code `3` = re-authenticate. |
 | `review` | Ink TUI: `j/k` move, `1-9`/`Enter` pick a candidate, `/` custom search, `p` paste a Spotify URL/URI, `o`/`O` open candidate/source in the browser, `l` keep as local file, `s` skip, `u` undo, `?` help. |
 | `status` | Match counts, playlist mappings, last run. |
 | `unmatched [--status local\|review\|all] [--tsv]` | Tracks without a Spotify match and the local file that backs them. |

package/README.zh-CN.md

@@ -67,7 +67,7 @@ spotifify review               # 处理低置信度匹配
 | `init [--force\|--upgrade]` | 写配置模板；`--upgrade` 把新版本新增的选项合并进现有文件（保留原值，写 `.bak`）。 |
 | `doctor` | 检查配置、状态库、`ffmpeg`/`fpcalc`、token scope、搜索配额截止时间，以及桌面端的本地文件索引（哪些导出没被索引、哪些时长和我们算的不一致——歌单里灰掉的两种原因）。 |
 | `auth spotify` / `auth netease [--cookie …]` | 登录。 |
-| `sync [--dry-run] [--prune] [--source netease\|local] [--playlist 名称] [--skip-match]` | 拉取 → 匹配 → 导出 → 计划 → 执行 → 报告。`--prune` 还会删掉被取代的本地条目和不再需要的导出文件。退出码 `3` = 需要重新登录。 |
+| `sync [--dry-run] [--prune] [--source netease\|local] [--playlist 名称] [--skip-match]` | 拉取 → 匹配 → 导出 → 计划 → 执行 → 报告。`--prune` 还会删掉被取代的本地条目和不再需要的导出文件——但只在本次能对账的范围内：带 `--playlist`/`--source` 时不会取消其他镜像歌单想要的喜欢，本次计划外的歌单仍引用的导出文件保留，没有任何镜像歌单的运行什么都不删。退出码 `3` = 需要重新登录。 |
 | `review` | Ink TUI：`j/k` 移动，`1-9`/`Enter` 选候选，`/` 自定义搜索，`p` 粘贴 Spotify 链接/URI，`o`/`O` 在浏览器打开候选/来源，`l` 保持为本地文件，`s` 跳过，`u` 撤销，`?` 帮助。 |
 | `status` | 匹配统计、歌单映射、上次运行。 |
 | `unmatched [--status local\|review\|all] [--tsv]` | 没有 Spotify 匹配的歌以及对应的本地文件。 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spotifify",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "Idempotently sync Netease Cloud Music playlists and a local music library (incl. .ncm) to Spotify",
   "keywords": [

package/src/cli.ts

@@ -44,7 +44,7 @@ interface Ctx {
 const program = new Command()
   .name("spotifify")
   .description("Sync Netease Cloud Music playlists and a local library to Spotify")
-  .version("0.1.2") // x-release-please-version
+  .version("0.1.3") // x-release-please-version
   .option("--config <path>", "config file (default: <state-dir>/config.toml)")
   .option("--state-dir <dir>", "state directory (default: ~/.spotifify or $SPOTIFIFY_STATE_DIR)")
   .option("--log-file <path>", "append log lines to this file")

package/src/match/matcher.ts

@@ -17,6 +17,7 @@ const TRACK_REF = /^(?:spotify:track:|https?:\/\/open\.spotify\.com\/(?:intl-[a-
 /** Dedupes search results by id (and relinked origin id) and scores each one once. */
 class CandidatePool {
   private readonly seen = new Set<string>();
+  private readonly byId = new Map<string, Candidate>();
   private readonly candidates: Candidate[] = [];
 
   constructor(
@@ -37,11 +38,23 @@ class CandidatePool {
       if (scored.parts.artist < minArtist) continue;
       const c = toCandidate(t.id, t, scored);
       this.candidates.push(c);
+      this.byId.set(t.id, c);
+      if (t.linked_from) this.byId.set(t.linked_from.id, c);
       added.push(c);
     }
     return added;
   }
 
+  /** Pooled candidates for these tracks, whichever query admitted them (an identity hit must count even for a track a text query saw first). */
+  known(tracks: SpotifyTrack[]): Candidate[] {
+    const out = new Set<Candidate>();
+    for (const t of tracks) {
+      const c = (t.id !== null ? this.byId.get(t.id) : undefined) ?? (t.linked_from !== undefined ? this.byId.get(t.linked_from.id) : undefined);
+      if (c) out.add(c);
+    }
+    return [...out];
+  }
+
   sorted(): Candidate[] {
     return [...this.candidates].sort((a, b) => b.score - a.score);
   }
@@ -63,19 +76,24 @@ function toCandidate(id: string, t: SpotifyTrack, scored: { score: number; parts
 
 type Hit = { by: "isrc" | "fingerprint"; candidate: Candidate } | { by: "auto" };
 
+/** ISRCs for a local file (Chromaprint → AcoustID → MusicBrainz); replaceable so the decision path can be exercised without `fpcalc`. */
+export type IsrcLookup = (path: string, contentHash: string, cfg: Config["matching"], repo: Repo, now: number) => Promise<string[]>;
+
 export class Matcher {
   private readonly api: SpotifyApi;
   private readonly repo: Repo;
   private readonly cfg: Config;
   private readonly market: string;
   private readonly search: TrackSearch;
+  private readonly isrcLookup: IsrcLookup;
 
-  constructor(deps: { api: SpotifyApi; repo: Repo; cfg: Config; market: string }) {
+  constructor(deps: { api: SpotifyApi; repo: Repo; cfg: Config; market: string; isrcLookup?: IsrcLookup }) {
     this.api = deps.api;
     this.repo = deps.repo;
     this.cfg = deps.cfg;
     this.market = deps.market;
     this.search = new TrackSearch(deps.api, deps.repo, deps.cfg.matching, deps.market);
+    this.isrcLookup = deps.isrcLookup ?? isrcsByFingerprint;
   }
 
   /** Network searches spent by this matcher (cache hits excluded). */
@@ -92,10 +110,11 @@ export class Matcher {
     for (const q of queries) {
       const tracks = await this.search.search(q, now);
       const added = pool.add(tracks, true, q === bareTitle ? BARE_TITLE_MIN_ARTIST : 0);
-      if (added.length === 0) continue;
       if (q.startsWith("isrc:")) {
-        let best = added[0]!;
-        for (const c of added) if (c.score > best.score) best = c;
+        const hits = pool.known(tracks);
+        if (hits.length === 0) continue;
+        let best = hits[0]!;
+        for (const c of hits) if (c.score > best.score) best = c;
         return { by: isrcBy, candidate: best };
       }
       if (added.some((c) => passesAutoGate(c.score, c.parts, m))) return { by: "auto" };
@@ -114,7 +133,7 @@ export class Matcher {
     const bareTitle = track.artists.length > 0 ? queryTitle(track.title) : null;
     let hit = await this.runQueries(pool, this.search.queriesFor(track), bareTitle, "isrc", now);
     if (hit === null && track.file && m.fingerprint) {
-      const isrcs = await isrcsByFingerprint(track.file.path, track.file.contentHash, m, this.repo, now);
+      const isrcs = await this.isrcLookup(track.file.path, track.file.contentHash, m, this.repo, now);
       for (const isrc of isrcs) {
         hit = await this.runQueries(pool, [`isrc:${isrc}`], null, "fingerprint", now);
         if (hit !== null) break;

package/src/sources/local/source.ts

@@ -89,17 +89,26 @@ export class LocalSource implements Source {
 
   private async track(file: ScannedFile): Promise<SourceTrack | null> {
     const cached = this.cache.get(file.path);
-    if (cached?.file !== undefined && cached.file.size === file.size && cached.file.mtimeMs === file.mtimeMs) {
-      const { id: _id, canonicalKey: _key, lastSeenAt: _seen, ...track } = cached;
-      return track;
-    }
+    if (cached?.file !== undefined && cached.file.size === file.size && cached.file.mtimeMs === file.mtimeMs) return stripRow(cached);
     try {
       const contentHash = await hashFile(file.path);
       const meta = await describe(file.path, this.cfg.filename_pattern);
       return { kind: "local", externalId: file.path, ...meta, file: { path: file.path, contentHash, size: file.size, mtimeMs: file.mtimeMs } };
     } catch (e) {
-      log.warn(`skipping unreadable file ${file.path}: ${e instanceof Error ? e.message : String(e)}`);
+      // A file that cannot be read right now (half-downloaded, locked, damaged) is not a file that left the
+      // library: the previous row stands until it can be read again, so the track is never treated as removed.
+      const error = e instanceof Error ? e.message : String(e);
+      if (cached?.file !== undefined) {
+        log.warn(`cannot read ${file.path}; keeping its previous metadata: ${error}`);
+        return stripRow(cached);
+      }
+      log.warn(`skipping unreadable file ${file.path}: ${error}`);
       return null;
     }
   }
 }
+
+function stripRow(row: SourceTrackRow): SourceTrack {
+  const { id: _id, canonicalKey: _key, lastSeenAt: _seen, ...track } = row;
+  return track;
+}

package/src/sources/netease/client.ts

@@ -35,26 +35,26 @@ export class NeteaseAuthError extends Error {
 const LoginStatusBody = z.object({
   data: z.object({ profile: z.object({ userId: z.number(), nickname: z.string().default("") }).nullish() }).optional(),
 });
+// Fields a pull cannot do without (`playlist`, `trackIds`) are required: a shape change must fail the run, not
+// read as "the user has no playlists / the playlist is empty" and delete everything downstream.
 const UserPlaylistBody = z.object({
   more: z.boolean().default(false),
-  playlist: z
-    .array(
-      z.object({
-        id: z.number(),
-        name: z.string(),
-        creator: z.object({ userId: z.number() }).nullish(),
-        userId: z.number().optional(),
-        specialType: z.number().default(0),
-        trackCount: z.number().default(0),
-        updateTime: z.number().default(0),
-        trackUpdateTime: z.number().optional(),
-      }),
-    )
-    .default([]),
+  playlist: z.array(
+    z.object({
+      id: z.number(),
+      name: z.string(),
+      creator: z.object({ userId: z.number() }).nullish(),
+      userId: z.number().optional(),
+      specialType: z.number().default(0),
+      trackCount: z.number().default(0),
+      updateTime: z.number().default(0),
+      trackUpdateTime: z.number().optional(),
+    }),
+  ),
 });
 const PlaylistDetailBody = z.object({
   playlist: z.object({
-    trackIds: z.array(z.object({ id: z.number() })).default([]),
+    trackIds: z.array(z.object({ id: z.number() })),
     updateTime: z.number().default(0),
     trackUpdateTime: z.number().optional(),
   }),

package/src/sources/netease/source.ts

@@ -78,10 +78,17 @@ export class NeteaseSource implements Source {
       }
 
       const tracks: SourceTrack[] = [];
+      const omitted: string[] = [];
       for (const id of ids) {
         const t = known.get(id) ?? fetched.get(id);
         if (t) tracks.push(t);
-        else log.warn("netease song_detail omitted a track", { playlist: summary.name, id });
+        else omitted.push(id);
+      }
+      if (omitted.length > 0) {
+        // Songs the detail endpoint left out were never known, so nothing is lost yet; but the playlist must not be
+        // recorded as pulled at this version, or the cache would serve the short list until the playlist changes.
+        log.warn("netease song_detail omitted tracks; the playlist will be pulled again next run", { playlist: summary.name, omitted: omitted.length, ids: omitted.slice(0, 5) });
+        playlist.sourceUpdatedAt = undefined;
       }
       log.info("netease playlist pulled", { name: summary.name, tracks: tracks.length, fetched: fetched.size, cached: known.size });
       playlists.push({ playlist, tracks });

package/src/spotify/api.ts

@@ -6,8 +6,8 @@ import type { SpotifyPlaylist, SpotifyPlaylistItem, SpotifyTrack } from "./types
 // `/me/library?uris=`; the legacy `/tracks` and `/me/tracks/contains` paths answer 403 for newer apps.
 const ITEM_FIELDS = "next,total,items(added_at,is_local,item(id,uri,name,is_local,duration_ms,artists(id,name),album(id,name)))";
 
-/** Playlist item batch limit for add/remove/replace. */
-const ITEMS_BATCH = 100;
+/** Playlist item batch limit for add/remove; also the most a single replace can hold. */
+export const ITEMS_BATCH = 100;
 /** `/me/library` batch limit (probed: 41+ uris → 400 "Too many uris requested"). */
 const LIBRARY_BATCH = 40;
 
@@ -92,8 +92,9 @@ export class SpotifyApi {
 
   /**
    * ≤100 per request. Catalog tracks are removed by URI; local files must be removed by position only
-   * (`/items` answers 400 "Invalid base62 id" for a `spotify:local:` URI). Positions are removed highest
-   * first with chained snapshot ids, so earlier indexes never shift underneath later batches.
+   * (`/items` answers 400 "Invalid base62 id" for a `spotify:local:` URI). Every position batch names the
+   * snapshot the positions were read from: Spotify resolves them against that snapshot, so batches never
+   * see each other's shifts (or a concurrent edit). Positions are still sent highest first.
    */
   async removePlaylistItems(id: string, items: Array<{ uri: string; positions?: number[] }>, snapshotId: string): Promise<string> {
     let snapshot = snapshotId;
@@ -101,7 +102,7 @@ export class SpotifyApi {
     const uris = items.filter((x) => x.positions === undefined).map((x) => ({ uri: x.uri }));
     for (const batch of chunk(positions, ITEMS_BATCH)) {
       const res = await this.client.request<{ snapshot_id: string }>("DELETE", `/v1/playlists/${id}/items`, {
-        body: { positions: batch, snapshot_id: snapshot },
+        body: { positions: batch, snapshot_id: snapshotId },
       });
       snapshot = res.snapshot_id;
     }
@@ -121,13 +122,11 @@ export class SpotifyApi {
     return res.snapshot_id;
   }
 
-  /** PUT the first ≤100 (which also clears the playlist), then append the rest. */
+  /** One atomic PUT (≤100 items: a longer list would need a follow-up POST that can fail half-way and lose the tail). */
   async replacePlaylistItems(id: string, uris: string[]): Promise<string> {
-    const res = await this.client.request<{ snapshot_id: string }>("PUT", `/v1/playlists/${id}/items`, {
-      body: { uris: uris.slice(0, ITEMS_BATCH) },
-    });
-    const rest = uris.slice(ITEMS_BATCH);
-    return rest.length === 0 ? res.snapshot_id : this.addPlaylistItems(id, rest);
+    if (uris.length > ITEMS_BATCH) throw new Error(`replacePlaylistItems: ${uris.length} items exceed the single-request limit of ${ITEMS_BATCH}`);
+    const res = await this.client.request<{ snapshot_id: string }>("PUT", `/v1/playlists/${id}/items`, { body: { uris } });
+    return res.snapshot_id;
   }
 
   /** ≤50 per request; result aligns with `ids` order. */

package/src/spotify/auth.ts

@@ -48,7 +48,8 @@ async function postToken(form: Record<string, string>, previous?: SpotifyTokens)
     access_token: body.access_token,
     refresh_token: refresh,
     expires_at: Date.now() + body.expires_in * 1000 - EXPIRY_MARGIN_MS,
-    scope: body.scope ?? previous?.scope ?? SCOPES.join(" "),
+    // A refresh response may omit `scope` (or an older store may hold ""): the grant did not shrink, so keep what was known.
+    scope: body.scope || previous?.scope || SCOPES.join(" "),
   };
 }
 
@@ -110,12 +111,7 @@ export async function loginPkce(opts: { clientId: string; port: number; store: T
   }
 }
 
-/** PKCE refresh responses may omit `refresh_token`; the previous one is kept in that case. */
-export async function refreshTokens(clientId: string, refreshToken: string): Promise<SpotifyTokens> {
-  return postToken({ client_id: clientId, grant_type: "refresh_token", refresh_token: refreshToken }, {
-    access_token: "",
-    refresh_token: refreshToken,
-    expires_at: 0,
-    scope: "",
-  });
+/** PKCE refresh responses may omit `refresh_token` and `scope`; the previous values are kept in that case. */
+export async function refreshTokens(clientId: string, previous: SpotifyTokens): Promise<SpotifyTokens> {
+  return postToken({ client_id: clientId, grant_type: "refresh_token", refresh_token: previous.refresh_token }, previous);
 }

package/src/spotify/client.ts

@@ -77,7 +77,9 @@ export class SpotifyClient {
           log.warn(`Spotify rate limited; waiting ${secs}s`, { method, path: url.pathname });
           throw new RetryableError(`429 on ${method} ${url.pathname}`, waitMs);
         }
-        if (res.status >= 500) throw new RetryableError(`${res.status} on ${method} ${url.pathname}`);
+        // A 5xx on a write may arrive after Spotify applied it (a re-sent POST would add twice, a re-sent
+        // reorder move twice), so only reads are retried; a failed write ends the run and the next one re-plans.
+        if (res.status >= 500 && method === "GET") throw new RetryableError(`${res.status} on ${method} ${url.pathname}`);
         throw new SpotifyHttpError(res.status, text, method, url.pathname);
       },
       { attempts: ATTEMPTS },
@@ -107,7 +109,7 @@ export class SpotifyClient {
     if (this.refreshing) return this.refreshing;
     const tokens = this.store.load();
     if (tokens === null) throw new AuthExpiredError();
-    this.refreshing = refreshTokens(this.clientId, tokens.refresh_token)
+    this.refreshing = refreshTokens(this.clientId, tokens)
       .then((fresh) => {
         this.store.save(fresh);
         return fresh;

package/src/state/repo.ts

@@ -386,6 +386,29 @@ export class Repo {
     })();
   }
 
+  /** `spotify:local:` uris recorded as present in a managed playlist → ids of the playlists referencing each. */
+  localUriReferences(): Map<string, string[]> {
+    const out = new Map<string, string[]>();
+    for (const r of this.db.query<{ uri: string; spotify_playlist_id: string }, []>("SELECT uri, spotify_playlist_id FROM managed_item WHERE uri LIKE 'spotify:local:%'").all()) {
+      let ids = out.get(r.uri);
+      if (!ids) {
+        ids = [];
+        out.set(r.uri, ids);
+      }
+      ids.push(r.spotify_playlist_id);
+    }
+    return out;
+  }
+
+  /** Record exactly which of our local entries a playlist holds after a sync (rows for entries the user removed by hand go away). */
+  replaceManagedLocal(spotifyPlaylistId: string, uris: string[], now: number): void {
+    const q = this.db.query("INSERT OR IGNORE INTO managed_item (spotify_playlist_id, uri, added_at) VALUES (?, ?, ?)");
+    this.db.transaction(() => {
+      this.db.run("DELETE FROM managed_item WHERE spotify_playlist_id = ? AND uri LIKE 'spotify:local:%'", [spotifyPlaylistId]);
+      for (const u of uris) q.run(spotifyPlaylistId, u, now);
+    })();
+  }
+
   likedIds(): Set<string> {
     return new Set(this.db.query<{ spotify_id: string }, []>("SELECT spotify_id FROM liked").all().map((r) => r.spotify_id));
   }

package/src/sync/apply.ts

@@ -3,7 +3,7 @@
  * 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 { ITEMS_BATCH, 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";
@@ -38,6 +38,13 @@ export interface ApplySummary {
 const REPLACE_MIN_MOVES = 5;
 const REPLACE_MOVE_RATIO = 1 / 3;
 
+export class PlaylistDriftError extends Error {
+  constructor(name: string) {
+    super(`playlist "${name}" changed since it was read; nothing was applied to it — rerun \`spotifify sync\``);
+    this.name = "PlaylistDriftError";
+  }
+}
+
 /** 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, exportsRemoved: 0 };
@@ -93,6 +100,14 @@ async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary):
   }
   if (spotifyId === null) throw new Error(`playlist plan for ${p.sourceName} has neither spotifyId nor create`);
 
+  // Moves and the replace order describe the playlist as it was listed and carry no snapshot Spotify could
+  // validate them against (unlike position removals), so an edit since the listing would reorder the wrong
+  // rows: such a playlist is checked before anything is written to it.
+  const willPrune = deps.prune && p.prune.length > 0;
+  if (p.snapshotId !== null && p.moves.length > 0 && (await api.getPlaylistSnapshot(spotifyId)) !== p.snapshotId) {
+    throw new PlaylistDriftError(name);
+  }
+
   if (p.rename) {
     await api.renamePlaylist(spotifyId, p.rename.to);
     name = p.rename.to;
@@ -100,8 +115,10 @@ async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary):
     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;
+  // Replace-all fast path: one atomic PUT, only for lists it can hold whole, with no local items, and when
+  // moving would cost noticeably more calls.
+  const useReplace =
+    p.replaceAllowed && p.targetOrder.length <= ITEMS_BATCH && p.moves.length > REPLACE_MIN_MOVES && p.moves.length > p.targetOrder.length * REPLACE_MOVE_RATIO;
   let snapshot: string | null = null;
 
   if (useReplace) {
@@ -114,12 +131,12 @@ async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary):
     s.replaced++;
     log.info("replaced playlist contents", { name, items: p.targetOrder.length });
   } else {
-    for (const uris of chunk(p.adds, 100)) {
+    for (const uris of chunk(p.adds, ITEMS_BATCH)) {
       snapshot = await api.addPlaylistItems(spotifyId, uris);
       repo.addManaged(spotifyId, uris, now);
       s.added += uris.length;
     }
-    if (deps.prune && p.prune.length > 0) {
+    if (willPrune) {
       // Positions come from the planning-time listing, so they are validated against that snapshot
       // (Spotify checks them against the snapshot given, not the current one). Adds only append.
       const base = p.snapshotId ?? snapshot ?? (await api.getPlaylist(spotifyId))?.snapshot_id ?? null;
@@ -139,6 +156,11 @@ async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary):
       }
     }
   }
+  // Local entries present after this run reference their export from this playlist; an export is only
+  // garbage-collected once no playlist references it any more (see planExportGc). Without --prune the
+  // stale ones are still there.
+  const localPresent = deps.prune ? p.linked : [...p.linked, ...p.prune.map((x) => x.uri).filter((u) => u.startsWith("spotify:local:"))];
+  repo.replaceManagedLocal(spotifyId, localPresent, now);
 
   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 });

package/src/sync/plan.ts

@@ -37,11 +37,13 @@ export interface PlaylistPlan {
   prune: Array<{ uri: string; positions: number[] }>;
   /** remote items not managed by this tool; never removed, kept at the tail */
   foreign: string[];
+  /** owned local entries that resolve to a desired export: the user's paste landed, so the export is referenced from this playlist */
+  linked: 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) */
+  /** when true, apply may replace the whole playlist instead of moving (no local or unresolved items involved) */
   replaceAllowed: boolean;
 }
 
@@ -71,6 +73,7 @@ export interface Plan {
 }
 
 export interface RemoteItem {
+  /** empty when Spotify returned the entry without an item (unresolvable): it keeps its position but is never touched */
   uri: string;
   isLocal: boolean;
   /**
@@ -142,6 +145,7 @@ export function computePlaylistPlan(input: PlaylistPlanInput): PlaylistPlan {
       awaiting: desired.filter((d) => d.kind === "local"),
       prune: [],
       foreign: [],
+      linked: [],
       moves: [],
       targetOrder: desired.filter((d) => d.kind === "spotify").map((d) => d.uri),
       replaceAllowed: false,
@@ -151,11 +155,17 @@ export function computePlaylistPlan(input: PlaylistPlanInput): PlaylistPlan {
   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 linked = desired.filter((d) => d.kind === "local" && remoteSet.has(d.uri)).map((d) => d.uri);
 
   const prune: PlaylistPlan["prune"] = [];
   const pruneByUri = new Map<string, number[]>();
   const foreign: string[] = [];
+  let unresolved = false;
   remote.forEach((r, i) => {
+    if (r.uri === "") {
+      unresolved = true;
+      return;
+    }
     if (desiredSet.has(r.uri)) return;
     if (managed.has(r.uri) || r.owned) {
       let positions = pruneByUri.get(r.uri);
@@ -207,8 +217,9 @@ export function computePlaylistPlan(input: PlaylistPlanInput): PlaylistPlan {
     awaiting,
     prune,
     foreign,
+    linked,
     moves,
     targetOrder,
-    replaceAllowed: !anyLocal,
+    replaceAllowed: !anyLocal && !unresolved,
   };
 }

package/src/sync/run.ts

@@ -15,7 +15,7 @@ import { SpotifyHttpError, SpotifyRateLimitedError } from "../spotify/client.ts"
 import { MANAGED_DESCRIPTION, type SpotifyPlaylistItem } from "../spotify/types.ts";
 import { parseLocalUri } from "../spotify/localUri.ts";
 import type { LocalExportRow, Repo, SourcePlaylistRow } from "../state/repo.ts";
-import { sanitizeFilename } from "../util/fs.ts";
+import { MAX_FILENAME, sanitizeFilename } from "../util/fs.ts";
 import { log } from "../util/log.ts";
 import { mapLimit } from "../util/retry.ts";
 import { applyExports, applyPlan, type ApplySummary } from "./apply.ts";
@@ -93,8 +93,12 @@ export async function runSync(deps: SyncDeps, opts: SyncOptions): Promise<SyncRe
       apply.exported = exported.exported;
       apply.exportErrors = exported.errors;
     }
-    // After apply: the playlist entries pointing at these files were pruned above, so the files can go.
-    if (apply && opts.prune) apply.exportsRemoved = await removeExports(plan.exportGc, repo);
+    // After apply: the playlist entries pointing at these files were pruned above, so the files can go —
+    // unless some playlist outside this plan still holds an entry for them.
+    if (apply && opts.prune) {
+      const referenced = repo.localUriReferences();
+      apply.exportsRemoved = await removeExports(plan.exportGc.filter((e) => !referenced.has(e.localUri)), repo);
+    }
     const summary: SyncSummary = {
       pulled,
       matched,
@@ -137,14 +141,22 @@ export function planExportsOnly(repo: Repo, cfg: Config, opts: Pick<SyncOptions,
 /**
  * Exported files no longer needed: the track left every mirrored playlist, or it has a Spotify match
  * now. Only meaningful for a full run — with `--playlist`/`--source` the other playlists' exports
- * would look unneeded — and the remote entries pointing at these files are pruned in the same run
- * (they are `owned`), so nothing in a playlist is left pointing at a deleted file.
+ * would look unneeded — and never when nothing is mirrored (a config slip must not delete everything).
+ * An export whose entry sits in a playlist outside `planned` (retired from mirroring, or filtered out)
+ * is kept: only the playlists in this plan prune their entries in the same run.
  */
-export function planExportGc(repo: Repo, cfg: Config, opts: Pick<SyncOptions, "source" | "playlist">): LocalExportRow[] {
+export function planExportGc(repo: Repo, cfg: Config, opts: Pick<SyncOptions, "source" | "playlist">, planned: ReadonlySet<string>): LocalExportRow[] {
   if (opts.source || opts.playlist) return [];
-  const needed = selectedKeys(repo, cfg, opts);
-  const local = new Set(repo.listMatches("local").map((m) => m.canonicalKey));
-  return repo.listExports().filter((e) => !needed.has(e.canonicalKey) || !local.has(e.canonicalKey));
+  if (selectedSourcePlaylists(repo, cfg, {}).length === 0) return [];
+  const needed = selectedKeys(repo, cfg, {});
+  // `review` keeps its export: a candidate that still needs a human must not undo a paste (see desiredItems)
+  const keep = new Set([...repo.listMatches("local"), ...repo.listMatches("review")].map((m) => m.canonicalKey));
+  const referenced = repo.localUriReferences();
+  return repo.listExports().filter((e) => {
+    if (needed.has(e.canonicalKey) && keep.has(e.canonicalKey)) return false;
+    const refs = referenced.get(e.localUri);
+    return refs === undefined || refs.every((id) => planned.has(id));
+  });
 }
 
 // ---- pull -------------------------------------------------------------------
@@ -261,38 +273,24 @@ export async function buildPlan(deps: SyncDeps, opts: Pick<SyncOptions, "prune"
   const me = await api.me();
   const remotePlaylists = (await api.listMyPlaylists()).filter((p) => p.owner.id === me.id);
   const exports = repo.listExports();
+  const exportByKey = new Map(exports.map((e) => [e.canonicalKey, e] as const));
 
-  const sourcePlaylists = selectedSourcePlaylists(repo, cfg, opts);
+  const mirrored = selectedSourcePlaylists(repo, cfg, {});
+  const selected = new Set(selectedSourcePlaylists(repo, cfg, opts).map((p) => p.id));
 
   const playlists: PlaylistPlan[] = [];
+  /** ids the playlists this run acts on want liked → saved if not yet */
   const likeDesired = new Set<string>();
+  /** ids any mirrored playlist wants liked → never pruned, whatever `--playlist`/`--source` selected */
+  const likeNeeded = new Set<string>();
 
-  for (const sp of sourcePlaylists) {
-    const targetName = cfg.sync.playlist_prefix + sp.name;
-    const tracks = repo.playlistTracks(sp.id);
-    const matches = repo.matchesForKeys(tracks.map((t) => t.canonicalKey));
-    const exportByKey = new Map(exports.map((e) => [e.canonicalKey, e] as const));
-    const likeThis = sp.kind === "netease" ? cfg.netease.like_matched : cfg.local.like_matched;
-
-    const desired: DesiredItem[] = [];
-    const seen = new Set<string>();
-    for (const t of tracks) {
-      const m = matches.get(t.canonicalKey);
-      if (!m) continue;
-      let item: DesiredItem | null = null;
-      if (m.status === "matched" && m.spotifyUri && m.spotifyId) {
-        item = { uri: m.spotifyUri, kind: "spotify", canonicalKey: t.canonicalKey };
-        if (likeThis) likeDesired.add(m.spotifyId);
-      } else if (m.status === "local") {
-        const e = exportByKey.get(t.canonicalKey);
-        if (e) item = { uri: e.localUri, kind: "local", canonicalKey: t.canonicalKey };
-      }
-      if (item && !seen.has(item.uri)) {
-        seen.add(item.uri);
-        desired.push(item);
-      }
-    }
+  for (const sp of mirrored) {
+    const { desired, likes } = desiredItems(repo, cfg, sp, exportByKey);
+    for (const id of likes) likeNeeded.add(id);
+    if (!selected.has(sp.id)) continue;
+    for (const id of likes) likeDesired.add(id);
 
+    const targetName = cfg.sync.playlist_prefix + sp.name;
     const remote = await resolveRemotePlaylist(sp, targetName, remotePlaylists, deps);
     let remoteItems: RemoteItem[] = [];
     let snapshotId: string | null = null;
@@ -321,15 +319,53 @@ export async function buildPlan(deps: SyncDeps, opts: Pick<SyncOptions, "prune"
     );
   }
 
-  // Likes: everything desired that is not already saved; prune tool-liked ids no longer desired.
+  // Likes: everything desired that is not already saved; prune tool-liked ids no mirrored playlist wants any
+  // more. With nothing mirrored there is nothing to reconcile against, so nothing is pruned.
   const likeIds = [...likeDesired];
   const saved = await savedFlags(api, likeIds);
   const likes = {
     add: likeIds.filter((_, i) => !saved[i]),
-    prune: [...repo.likedIds()].filter((id) => !likeDesired.has(id)),
+    prune: mirrored.length === 0 ? [] : [...repo.likedIds()].filter((id) => !likeNeeded.has(id)),
   };
+  if (mirrored.length === 0 && (repo.likedIds().size > 0 || exports.length > 0)) {
+    log.warn("no playlist is mirrored (check netease.include_playlists / local.mirror_playlist); keeping every tool-liked track and export", {
+      liked: repo.likedIds().size,
+      exports: exports.length,
+    });
+  }
+
+  const planned = new Set<string>();
+  for (const p of playlists) if (p.spotifyId !== null) planned.add(p.spotifyId);
+  return { playlists, likes, exports: exportPlans, exportGc: planExportGc(repo, cfg, opts, planned), reviewPending: repo.countMatches().review };
+}
 
-  return { playlists, likes, exports: exportPlans, exportGc: planExportGc(repo, cfg, opts), reviewPending: repo.countMatches().review };
+/** What one source playlist wants on Spotify, in source order and deduped by uri, plus the ids it wants liked. */
+function desiredItems(repo: Repo, cfg: Config, sp: SourcePlaylistRow, exportByKey: ReadonlyMap<string, LocalExportRow>): { desired: DesiredItem[]; likes: string[] } {
+  const tracks = repo.playlistTracks(sp.id);
+  const matches = repo.matchesForKeys(tracks.map((t) => t.canonicalKey));
+  const likeThis = sp.kind === "netease" ? cfg.netease.like_matched : cfg.local.like_matched;
+  const desired: DesiredItem[] = [];
+  const likes: string[] = [];
+  const seen = new Set<string>();
+  for (const t of tracks) {
+    const m = matches.get(t.canonicalKey);
+    if (!m) continue;
+    let item: DesiredItem | null = null;
+    if (m.status === "matched" && m.spotifyUri && m.spotifyId) {
+      item = { uri: m.spotifyUri, kind: "spotify", canonicalKey: t.canonicalKey };
+      if (likeThis) likes.push(m.spotifyId);
+    } else if (m.status === "local" || m.status === "review") {
+      // `review` keeps the export already in place: a candidate that still needs a human (a re-search after
+      // retry_unmatched_after_days, say) must not undo the user's paste. Only `local` gets a new export.
+      const e = exportByKey.get(t.canonicalKey);
+      if (e) item = { uri: e.localUri, kind: "local", canonicalKey: t.canonicalKey };
+    }
+    if (item && !seen.has(item.uri)) {
+      seen.add(item.uri);
+      desired.push(item);
+    }
+  }
+  return { desired, likes };
 }
 
 /** Which of `ids` are already liked. `/me/tracks/contains` is 403 for some development-mode apps; then list the library instead. */
@@ -399,9 +435,14 @@ function planExports(repo: Repo, localKeys: string[], exports: LocalExportRow[],
     // An export is current when the source is unchanged and its recorded identity is complete
     // (rows written before the duration segment was known cannot match anything the client indexes).
     if (!force && existing && existing.contentHash === t.file.contentHash && parseLocalUri(existing.localUri)?.durationSec !== null) continue;
-    let base = sanitizeFilename(`${t.artists.join(", ") || "Unknown Artist"} - ${t.title}`);
+    const raw = `${t.artists.join(", ") || "Unknown Artist"} - ${t.title}`;
+    let base = sanitizeFilename(raw);
     if (!existing) {
-      for (let n = 2; usedNames.has(base.toLowerCase()); n++) base = sanitizeFilename(`${t.artists.join(", ") || "Unknown Artist"} - ${t.title} (${n})`);
+      // The suffix is appended after truncation, so a name at the length limit still gets a distinct one.
+      for (let n = 2; usedNames.has(base.toLowerCase()); n++) {
+        const suffix = ` (${n})`;
+        base = sanitizeFilename(raw, MAX_FILENAME - suffix.length) + suffix;
+      }
     } else {
       base = existing.exportPath.replace(/\.[^.\\/]+$/, "").replace(/^.*[\\/]/, "");
     }

package/src/util/fs.ts

@@ -1,7 +1,10 @@
 import { createReadStream } from "node:fs";
 
+/** Longest base name (without extension) an export file gets, in UTF-16 units (NTFS's limit is 255). */
+export const MAX_FILENAME = 150;
+
 /** Replace characters Windows/NTFS rejects and trim trailing dots/spaces. */
-export function sanitizeFilename(name: string, max = 150): string {
+export function sanitizeFilename(name: string, max = MAX_FILENAME): string {
   const cleaned = name
     .replace(/[<>:"/\\|?*\u0000-\u001f]/g, "_")
     .replace(/\s+/g, " ")