@audiofool/moondog 0.1.0 → 0.2.0-beta.3

package/src/surfaces/cli/import-guides.mjs

@@ -6,4 +6,6 @@ export const IMPORT_GUIDE_URLS = Object.freeze({
   youtube: "https://takeout.google.com/",
   qq: "https://y.qq.com/",
   netease: "https://music.163.com/",
+  lastfm: "https://www.last.fm/",
+  lastfmApi: "https://www.last.fm/api/account/create",
 });

package/src/surfaces/cli/listener-profile-command.mjs

@@ -0,0 +1,92 @@
+import { sanitizeTerminalText } from "./format-output.mjs";
+import { N_, screenTranslator } from "../../i18n/index.mjs";
+
+export const savedProfileActions = new Set(["build", "saved", "explain"]);
+
+const kindLabels = { observation: N_("measured"), hypothesis: N_("interpretation"), listener_assertion: N_("your choice") };
+
+function builtLine(value, tr) {
+  const coverage = value.coverage?.coverage ?? {};
+  const concerns = value.verification?.state === "flagged" ? value.verification.checks.at(-1).issues.length : 0;
+  const check = value.verification?.state === "revised" ? tr("checked and revised once")
+    : concerns ? tr.n(concerns, "checked; one concern remains", "checked; {count} concerns remain") : tr("checked");
+  const built = [
+    tr("Built {date}", { date: value.built_at.slice(0, 10) }),
+    ...(Number.isInteger(coverage.effective_listening_events) ? [tr.n(coverage.effective_listening_events, "from {count} play", "from {count} plays")] : []),
+  ].join(" ");
+  const span = coverage.earliest_played_at && coverage.latest_played_at
+    ? `, ${tr("{first} to {last}", { first: coverage.earliest_played_at.slice(0, 10), last: coverage.latest_played_at.slice(0, 10) })}` : "";
+  return `${built}${span} · ${check}`;
+}
+
+function formatSaved(value, prefix, allFindings = false, tr) {
+  if (value.state === "missing") return tr("No saved reading yet. Use {prefix} build with a connected model.", { prefix });
+  const lines = [
+    `# ${tr("Your saved listening profile · v{version}", { version: value.sequence })}`,
+    value.state === "stale" ? tr("Evidence, choices or analysis changed. Use {prefix} build to update this reading.", { prefix }) : builtLine(value, tr),
+    "", value.summary, "",
+  ];
+  // The TUI renders this text as Markdown, which renumbers an ordered list from its
+  // first item. Ascending finding numbers keep the shown numbers valid for explain.
+  const displayed = allFindings ? value.claims : [...new Map([
+    ...(value.highlights ?? []), ...(value.listener_assertions ?? []),
+  ].map(claim => [claim.claim_id, claim])).values()].sort((a, b) => a.finding_number - b.finding_number);
+  for (const [index, claim] of displayed.entries()) {
+    lines.push(`${claim.finding_number ?? value.offset + index + 1}. ${claim.statement}`,
+      `   ${kindLabels[claim.kind] ? tr.marked(kindLabels[claim.kind]) : claim.kind.replaceAll("_", " ")} · ${claim.scope} · ${claim.uncertainty}`);
+  }
+  if (value.state === "current" && value.verification?.state === "flagged") {
+    lines.push("", tr("The final check still flagged:"), ...value.verification.checks.at(-1).issues.map(issue => `- ${issue.problem}`));
+  }
+  lines.push("", tr("Use {prefix} explain <number> for a finding's evidence.", { prefix }));
+  if (!allFindings && value.total_claims > displayed.length) lines.push(tr("All {count} findings: {prefix} saved 0", { count: value.total_claims, prefix }));
+  else if (allFindings && value.next_offset !== null) lines.push(tr("More findings: {prefix} saved {offset}", { prefix, offset: value.next_offset }));
+  return lines.join("\n");
+}
+
+function formatEvidence(entry) {
+  const { data } = entry;
+  const label = data.label ?? data.name ?? data.title ?? data.year ?? data.evidence_kind ?? entry.section;
+  const fields = Object.entries(data).filter(([key]) => !["label", "name", "title"].includes(key))
+    .map(([key, value]) => `${key.replaceAll("_", " ")}: ${typeof value === "object" ? JSON.stringify(value) : value}`);
+  return `- ${label} (${entry.section.replaceAll("_", " ")})\n  ${fields.join(" · ")}`;
+}
+
+export async function runListenerProfileCommand({
+  application, args, json = false, output = process.stdout, commandPrefix = "moondog profile",
+  signal, onProgress, runtimeFactory, tr = screenTranslator("en"),
+} = {}) {
+  const [action, ...values] = args ?? [];
+  let result;
+  let rendered;
+  if (action === "build") {
+    if (values.length > 1 || (values.length === 1 && values[0] !== "--force")) {
+      throw new Error(tr("Usage: {prefix} build [--force].", { prefix: commandPrefix }));
+    }
+    result = await application.buildListenerProfile({ force: values[0] === "--force", signal, onProgress, runtimeFactory });
+    rendered = result.state === "no_evidence" ? tr("Import your music first with /import.")
+      : `${result.state === "unchanged" ? tr("Your saved reading already matches the current evidence.") : tr("Saved your new listening profile.")}\n\n${formatSaved(result.revision, commandPrefix, false, tr)}`;
+  } else if (action === "saved") {
+    if (values.length > 1 || (values.length === 1 && !/^\d+$/u.test(values[0]))) {
+      throw new Error(tr("Usage: {prefix} saved [offset].", { prefix: commandPrefix }));
+    }
+    result = await application.getListenerProfile({ offset: Number(values[0] ?? 0) });
+    rendered = formatSaved(result, commandPrefix, values.length > 0, tr);
+  } else if (action === "explain") {
+    if (values.length !== 1 || !/^[1-9]\d*$/u.test(values[0]) || !Number.isSafeInteger(Number(values[0]))) {
+      throw new Error(tr("Usage: {prefix} explain <finding-number>.", { prefix: commandPrefix }));
+    }
+    const page = await application.getListenerProfile({ offset: Number(values[0]) - 1, limit: 1 });
+    if (!page.claims.length) throw new Error(tr("That finding is not in your saved profile. Open /profile saved first."));
+    result = await application.getListenerProfile({ claimId: page.claims[0].claim_id, revisionId: page.revision_id });
+    rendered = [
+      `# ${result.state === "stale" ? tr("Finding {number} · profile v{version} · needs update", { number: values[0], version: result.sequence })
+        : tr("Finding {number} · profile v{version}", { number: values[0], version: result.sequence })}`,
+      result.claim.statement, "", tr("Scope: {scope}", { scope: result.claim.scope }), tr("Uncertainty: {uncertainty}", { uncertainty: result.claim.uncertainty }),
+      "", tr("Supporting evidence:"), ...result.supporting_evidence.map(formatEvidence),
+      ...(result.contradicting_evidence.length ? ["", tr("Conflicting evidence:"), ...result.contradicting_evidence.map(formatEvidence)] : []),
+    ].join("\n");
+  } else throw new Error("Unknown saved profile command");
+  output.write(`${sanitizeTerminalText(json ? JSON.stringify(result, null, 2) : rendered)}\n`);
+  return result;
+}

package/src/surfaces/cli/listening-menu.mjs

@@ -5,6 +5,7 @@ import {
   truncateToWidth,
   visibleWidth,
 } from "@earendil-works/pi-tui";
+import { screenTranslator } from "../../i18n/index.mjs";
 
 function paintLine(value, width, theme) {
   const clipped = truncateToWidth(value, width, "");
@@ -16,7 +17,8 @@ function paintLine(value, width, theme) {
 
 /** A searchable Pi menu that keeps its own contents inside the viewport. */
 export class ListeningMenu {
-  constructor({ items, title, getTheme, getRows, currentValue }) {
+  constructor({ items, title, getTheme, getRows, currentValue, getText = () => screenTranslator("en") }) {
+    this.getText = getText;
     this.items = items;
     this.title = title;
     this.getTheme = getTheme;
@@ -125,9 +127,10 @@ export class ListeningMenu {
     const title = theme.bold(truncateToWidth(this.title, titleWidth, ""));
     const heading = title + " ".repeat(Math.max(1, inner - visibleWidth(title) - count.length)) + theme.muted(count);
     const search = this.input.render(inner)[0];
+    const tr = this.getText();
     const hint = theme.muted(inner >= 55
-      ? "type to filter  ↑↓ choose  enter select  esc back"
-      : inner >= 29 ? "↑↓ choose  enter ↵  esc back" : "↑↓  ↵  esc");
+      ? tr("type to filter  ↑↓ choose  enter select  esc back")
+      : inner >= 29 ? tr("↑↓ choose  enter ↵  esc back") : "↑↓  ↵  esc");
     let lines;
     if (budget < 4) {
       // An exceptionally short terminal has no room for separate chrome rows.
@@ -144,7 +147,7 @@ export class ListeningMenu {
       // The title owns the item count; omit SelectList's additional scroll-info row.
       const candidates = this.filteredItems.length
         ? this.select.render(inner).slice(0, this.capacity)
-        : [theme.muted("Nothing matches. Backspace to widen the search.")];
+        : [theme.muted(tr("Nothing matches. Backspace to widen the search."))];
       let labels = [heading, search];
       if (compactBox) {
         const labelWidth = Math.max(1, Math.floor(inner / 2));

package/src/surfaces/cli/profile-command.mjs

@@ -1,3 +1,4 @@
+import { screenTranslator } from "../../i18n/index.mjs";
 import { access } from "node:fs/promises";
 
 import {
@@ -11,6 +12,10 @@ export function profileCorrectionHelpText(commandPrefix = "moondog profile") {
 
 Commands:
 
+- \`${commandPrefix} build [--force]\` - build or resume a saved reading with your connected model
+- \`${commandPrefix} saved [offset]\` - read saved findings, including after a restart
+- \`${commandPrefix} explain <number>\` - inspect a saved finding's evidence
+
 - \`${commandPrefix} corrections [--all] [--json]\` - everything you've told me; add --all to include earlier choices
 - \`${commandPrefix} correct --artist <name> (--like|--avoid) [--note <text>] [--json]\` - like an artist, or keep them out
 - \`${commandPrefix} correct --track <title> --by <artist> (--like|--avoid) [--note <text>] [--json]\` - like a track, or keep it out
@@ -107,14 +112,14 @@ function writeLine(output, value = "") {
   output.write(`${sanitizeTerminalText(value)}\n`);
 }
 
-function formatCorrections(value) {
+function formatCorrections(value, tr) {
   const lines = [
-    "# What you've told me",
+    `# ${tr("What you've told me")}`,
     "",
-    `${value.active} ${value.active === 1 ? "choice" : "choices"} in effect.`,
+    tr.n(value.active, "{count} choice in effect.", "{count} choices in effect."),
   ];
   if (value.corrections.length === 0) {
-    lines.push("", "Nothing yet. Open a song or artist in /taste to like it or keep it out.");
+    lines.push("", tr("Nothing yet. Open a song or artist in /taste to like it or keep it out."));
     return lines.join("\n");
   }
   lines.push("");
@@ -122,8 +127,11 @@ function formatCorrections(value) {
     const target = item.artist_credit
       ? `${item.label} - ${item.artist_credit}`
       : item.label;
+    const choice = item.entity_type === "track"
+      ? item.stance === "avoid" ? tr("Keep out track") : tr("Like track")
+      : item.stance === "avoid" ? tr("Keep out artist") : tr("Like artist");
     lines.push(
-      `- ${item.stance === "avoid" ? "Keep out" : "Like"} ${item.entity_type}: ${target}${item.state === "active" ? "" : ` (${item.state})`}`,
+      `- ${choice}: ${target}${item.state === "active" ? "" : ` (${item.state})`}`,
       `  ${String(item.occurred_at).slice(0, 10)} · \`${item.correction_id}\``,
     );
     if (item.note) lines.push(`  "${item.note}"`);
@@ -131,22 +139,22 @@ function formatCorrections(value) {
   return lines.join("\n");
 }
 
-function formatCorrection(value, commandPrefix) {
+function formatCorrection(value, commandPrefix, tr) {
   const target = value.artist_credit
     ? `${value.label} - ${value.artist_credit}`
     : value.label;
   return [
-    value.stance === "avoid" ? `Noted. I'll keep ${target} out.` : `Noted. You like ${target}.`,
-    ...(value.superseded_correction_id ? ["This replaces what you told me before about it."] : []),
-    "Your profile is updated. Your listening history stays as it was.",
-    `To undo it: ${commandPrefix} retract ${value.correction_id}`,
+    value.stance === "avoid" ? tr("Noted. I'll keep {name} out.", { name: target }) : tr("Noted. You like {name}.", { name: target }),
+    ...(value.superseded_correction_id ? [tr("This replaces what you told me before about it.")] : []),
+    tr("Your profile is updated. Your listening history stays as it was."),
+    tr("To undo it: {command}", { command: `${commandPrefix} retract ${value.correction_id}` }),
   ].join("\n");
 }
 
-function formatRetraction(value) {
+function formatRetraction(value, tr) {
   return [
-    `Undone. I'll read ${value.label} from your listening again.`,
-    "Your profile is updated. Your listening history stays as it was.",
+    tr("Undone. I'll read {name} from your listening again.", { name: value.label }),
+    tr("Your profile is updated. Your listening history stays as it was."),
   ].join("\n");
 }
 
@@ -169,6 +177,7 @@ export async function runProfileCommand({
   openStore = openListeningHistoryStore,
   now = () => new Date(),
   commandPrefix = "moondog profile",
+  tr = screenTranslator("en"),
 } = {}) {
   const options = parseProfileArguments(args ?? []);
   if (!options.action || options.action === "help") {
@@ -193,11 +202,11 @@ export async function runProfileCommand({
       corrections: [],
       writes: "none",
     };
-    writeLine(output, json ? JSON.stringify(empty, null, 2) : formatCorrections(empty));
+    writeLine(output, json ? JSON.stringify(empty, null, 2) : formatCorrections(empty, tr));
     return empty;
   }
   if (options.action === "retract" && !databasePresent) {
-    throw new Error("There's nothing to undo yet.");
+    throw new Error(tr("There's nothing to undo yet."));
   }
   if (
     options.action === "correct" &&
@@ -206,7 +215,7 @@ export async function runProfileCommand({
     preferredSubjectId = await resolvePreferredSubjectId();
     if (!preferredSubjectId) {
       throw new Error(
-        "There's no profile to change yet. Bring in your music with /import first.",
+        tr("There's no profile to change yet. Bring in your music with /import first."),
       );
     }
   }
@@ -224,7 +233,7 @@ export async function runProfileCommand({
       };
       writeLine(
         output,
-        json ? JSON.stringify(empty, null, 2) : formatCorrections(empty),
+        json ? JSON.stringify(empty, null, 2) : formatCorrections(empty, tr),
       );
       return empty;
     }
@@ -236,7 +245,7 @@ export async function runProfileCommand({
     }
     if (!subjectId) {
       throw new Error(
-        "There's no profile to change yet. Bring in your music with /import first.",
+        tr("There's no profile to change yet. Bring in your music with /import first."),
       );
     }
     let value;
@@ -278,10 +287,10 @@ export async function runProfileCommand({
       json
         ? JSON.stringify(value, null, 2)
         : options.action === "corrections"
-          ? formatCorrections(value)
+          ? formatCorrections(value, tr)
           : options.action === "correct"
-            ? formatCorrection(value, commandPrefix)
-            : formatRetraction(value),
+            ? formatCorrection(value, commandPrefix, tr)
+            : formatRetraction(value, tr),
     );
     return value;
   } finally {

package/src/surfaces/cli/seasons-chart.mjs

@@ -0,0 +1,87 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import { formatListeningTime, sanitizeTerminalText } from "./format-output.mjs";
+
+// The last twelve quarters as bars: listening time per quarter, or plays when the history
+// didn't record how long every play lasted, with its new songs and leading artist beside
+// each bar. Every terminal draws the bars with block characters.
+// In Moondog's own window (MOONDOG_HOST=app), each bar row also carries an invisible
+// OSC 7717 mark: block id, row, bar width, and the chart's numbers, so any row that is
+// in view is enough. The window paints graphics over exactly those cells; the labels
+// and details stay terminal text. A marked region keeps a blank cell on each side,
+// which the graphics may bleed into.
+export const BLOCK_MARK = 7717;
+const EIGHTHS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"];
+let charts = 0;
+
+function textBar(fraction, width) {
+  const eighths = Math.round(Math.max(0, Math.min(1, fraction)) * width * 8);
+  return "█".repeat(Math.floor(eighths / 8)) + EIGHTHS[eighths % 8];
+}
+
+function inline(value) {
+  return sanitizeTerminalText(String(value ?? "")).replace(/\s+/gu, " ").trim();
+}
+
+export class SeasonsChart {
+  constructor(seasons, { getTheme, tr, environment = process.env }) {
+    this.seasons = seasons.filter((season) => /^\d{4}-Q[1-4]$/u.test(season?.key ?? "")).slice(-12);
+    this.getTheme = getTheme;
+    this.tr = tr;
+    this.marked = environment.MOONDOG_HOST === "app";
+    this.id = `seasons-${(charts += 1)}`;
+  }
+
+  invalidate() {}
+
+  render(width) {
+    const theme = this.getTheme();
+    const tr = this.tr;
+    // Minutes compare quarters only when every quarter with plays has them. Otherwise every
+    // bar counts plays: Last.fm and ListenBrainz record no play lengths, and unknown isn't zero.
+    const timed = this.seasons.every((season) => !(season.event_count > 0) || Number.isFinite(season.listening_minutes));
+    const amounts = this.seasons.map((season) => {
+      const amount = timed ? season.listening_minutes : season.event_count;
+      return Number.isFinite(amount) ? amount : 0;
+    });
+    const most = Math.max(1, ...amounts);
+    const details = this.seasons.map((season) => {
+      if (!Number.isInteger(season.event_count) || season.event_count === 0) return tr("nothing in your history");
+      const artist = inline(season.leading_artist?.name);
+      return [
+        timed ? formatListeningTime(season.listening_minutes, tr) : tr.n(season.event_count, "{count} play", "{count} plays"),
+        season.first_observed_tracks > 0 ? tr("{count} new", { count: tr.number(season.first_observed_tracks) }) : null,
+        artist || null,
+      ].filter(Boolean).join(" · ");
+    });
+    const detailWidth = Math.min(28, Math.max(...details.map((detail) => visibleWidth(detail))));
+    // " 2024 Q3  bars  details": the bars take what the label and a short detail leave.
+    const barWidth = Math.max(8, Math.min(30, width - 1 - 7 - 2 - 2 - detailWidth));
+    const payload = btoa(JSON.stringify({
+      kind: "seasons",
+      measure: timed ? "minutes" : "plays",
+      rows: this.seasons.map((season, row) => ({
+        quarter: Number(season.key.slice(-1)),
+        amount: amounts[row],
+        fraction: amounts[row] / most,
+        newSongs: Number.isInteger(season.first_observed_tracks) ? season.first_observed_tracks : 0,
+        empty: !(season.event_count > 0),
+      })),
+      colors: {
+        ink: theme.palette.foreground,
+        muted: theme.palette.muted,
+        faint: theme.palette.faint,
+        paper: theme.palette.background,
+      },
+    }));
+    return this.seasons.map((season, row) => {
+      const [year, quarter] = season.key.split("-");
+      // The year shows where it changes, so the column reads as a calendar.
+      const label = row === 0 || quarter === "Q1" ? `${year} ${quarter}` : `     ${quarter}`;
+      const bar = amounts[row] > 0 ? textBar(amounts[row] / most, barWidth) : "·";
+      const mark = this.marked ? `\x1b]${BLOCK_MARK};${this.id};${row};${barWidth};${payload}\x07` : "";
+      const line = ` ${theme.muted(label)}  ${mark}${theme.text(bar)}${" ".repeat(Math.max(0, barWidth - visibleWidth(bar)))}  ${theme.muted(details[row])}`;
+      return truncateToWidth(line, width, "");
+    });
+  }
+}

package/src/surfaces/cli/spotify-command.mjs

@@ -16,9 +16,10 @@ import {
   projectSpotifyRecentActivity,
 } from "../../integrations/spotify/recent-activity.mjs";
 import { readSpotifyHistoryArchive } from "../../integrations/spotify/history-archive.mjs";
+import { projectSpotifyLibrarySnapshot } from "../../integrations/spotify/library-snapshot.mjs";
 import { sanitizeTerminalText } from "./format-output.mjs";
 
-const readCommands = new Set(["account", "now", "devices", "queue", "recent"]);
+const readCommands = new Set(["account", "now", "devices", "queue", "recent", "library"]);
 const writeCommands = new Set([
   "play",
   "pause",
@@ -50,6 +51,8 @@ Commands:
 - \`moondog spotify account|now|devices|queue [--json]\`
 - \`moondog spotify recent [--limit <1-50>] [--after <ms>|--before <ms>] [--json]\`
 - \`moondog spotify sync-recent [--limit <1-50>] [--json]\`
+- \`moondog spotify library [--json]\`
+- \`moondog spotify sync-library [--json]\`
 - \`moondog spotify import-history <spotify-history.zip> [--json]\`
 - \`moondog spotify play [spotify-uri] [--json]\`
 - \`moondog spotify pause|next|previous [--json]\`
@@ -260,7 +263,7 @@ function formatPlain(action, value) {
       `Redirect URI: ${SPOTIFY_DEFAULT_REDIRECT_URI}`,
     ];
     if (value.state === "stored") {
-      const purpose = value.scope_purpose === "recent_listening" ? "reading recent plays" : "playback and playlists";
+      const purpose = value.scope_purpose === "recent_listening" ? "reading recent plays" : "playback, playlists and top artists/tracks";
       lines.push(
         value.scopes_sufficient
           ? `Permissions for ${purpose}: all set`
@@ -351,6 +354,26 @@ function formatPlain(action, value) {
       `- ${value.inserted_track_refs ?? 0} songs new to your profile`,
     ].join("\n");
   }
+  if (action === "library") {
+    return [
+      "# Your Spotify library",
+      `- ${value.saved_tracks?.length ?? 0} saved songs, ${value.saved_albums?.length ?? 0} saved albums`,
+      `- ${value.followed_artists?.length ?? 0} followed artists`,
+      `- ${value.playlists?.length ?? 0} of your own playlists`,
+      `- Top artists and tracks for the last four weeks, six months and year`,
+    ].join("\n");
+  }
+  if (action === "sync-library") {
+    if (value.already_imported) return "Your Spotify library hasn't changed since the last sync.";
+    return [
+      "# Your Spotify library is in",
+      `- ${value.preview.savedTracks} saved songs, ${value.preview.savedAlbums} saved albums, ${value.preview.followedArtists} followed artists`,
+      `- ${value.preview.playlistTracks} songs across ${value.preview.playlists} of your own playlists`,
+      `- ${value.preview.topArtists} top artists and ${value.preview.topTracks} top tracks from Spotify`,
+      ...(value.preview.truncated.length ? [`- Very large library: stopped reading ${value.preview.truncated.join(", ").replaceAll("_", " ")} at Moondog's limit`] : []),
+      ...(value.preview.skippedPlaylists ? [`- ${value.preview.skippedPlaylists} playlists couldn't be read and were skipped`] : []),
+    ].join("\n");
+  }
   if (action === "import-history") {
     const extended =
       value.data_scope === "lifetime_extended_streaming_history";
@@ -478,7 +501,8 @@ function createRuntimeResolver({
       const auth = await this.authentication();
       client = createSpotifyWebApiClient({
         fetchImpl,
-        tokenProvider: () => auth.getAccessToken(),
+        tokenProvider: (options) => auth.getAccessToken(options),
+        refreshAccessToken: (options) => auth.refreshAccessToken(options),
       });
       return client;
     },
@@ -507,11 +531,12 @@ function createRuntimeResolver({
   };
 }
 
-async function runReadCommand(action, service, input) {
+async function runReadCommand(action, service, input, { signal, onProgress } = {}) {
   if (action === "account") return service.account();
   if (action === "now") return service.currentPlayer();
   if (action === "devices") return service.devices();
   if (action === "recent") return service.recentActivity(input);
+  if (action === "library") return service.librarySnapshot({ signal, onProgress });
   return service.queue();
 }
 
@@ -601,6 +626,7 @@ export async function runSpotifyCommand({
   spotify,
   signalTarget = process,
   signal,
+  onProgress,
 } = {}) {
   const options = parseArguments(args, json);
   const action = options.action;
@@ -617,6 +643,7 @@ export async function runSpotifyCommand({
     "logout",
     "resolve",
     "sync-recent",
+    "sync-library",
     "import-history",
     ...readCommands,
     ...writeCommands,
@@ -793,7 +820,7 @@ export async function runSpotifyCommand({
         : (exactArguments(action, options.rest, 0), undefined);
     const service = await runtime.service();
     const result = await externalCall(
-      () => runReadCommand(action, service, input),
+      () => runReadCommand(action, service, input, { signal, onProgress }),
       `Spotify ${action} could not be read.`,
     );
     emit(stdout, action, result, options.json);
@@ -814,10 +841,12 @@ export async function runSpotifyCommand({
     const service = await runtime.service();
     const page = await externalCall(
       () =>
+        // Read Spotify's whole window: the cursor moves past whatever a shorter read leaves out.
         service.recentActivity({
+          limit: 50,
           ...input,
           ...(cursor !== null ? { after: cursor } : {}),
-        }),
+        }, { signal }),
       "Spotify recent activity could not be read.",
     );
     const currentTime = now();
@@ -839,6 +868,25 @@ export async function runSpotifyCommand({
     return result;
   }
 
+  if (action === "sync-library") {
+    exactArguments(action, options.rest, 0);
+    if (!recentActivityStore || typeof recentActivityStore.ingestImport !== "function") {
+      throw commandError("Spotify library storage is unavailable.");
+    }
+    if (typeof subjectId !== "string" || !subjectId.trim()) {
+      throw commandError("A trusted local music subject is required for a library sync.");
+    }
+    const service = await runtime.service();
+    const snapshot = await externalCall(() => service.librarySnapshot({ signal, onProgress }), "Your Spotify library could not be read.");
+    const currentTime = now();
+    if (!Number.isFinite(currentTime)) throw commandError("Spotify library capture time is unavailable.");
+    const projected = projectSpotifyLibrarySnapshot({ subjectId, snapshot, capturedAt: new Date(currentTime).toISOString() });
+    const receipt = await externalCall(() => recentActivityStore.ingestImport(projected.bundle), "Your Spotify library could not be stored.");
+    const result = { ...receipt, preview: projected.preview };
+    emit(stdout, action, result, options.json);
+    return result;
+  }
+
   const service = await runtime.service();
   const result = await externalCall(
     () => runWriteCommand(action, options.rest, service),