fluncle 0.138.0 → 0.140.0

package/bin/fluncle.mjs

@@ -561,7 +561,7 @@ function parseVersion(version) {
 var currentVersion;
 var init_version = __esm(() => {
   init_output();
-  currentVersion = "0.138.0".trim() ? "0.138.0".trim() : "0.1.0";
+  currentVersion = "0.140.0".trim() ? "0.140.0".trim() : "0.1.0";
 });
 
 // src/update-notifier.ts
@@ -2189,7 +2189,7 @@ function parseVersion2(version) {
 var currentVersion2, latestReleaseUrl = "https://api.github.com/repos/mauricekleine/fluncle/releases/latest";
 var init_version2 = __esm(() => {
   init_output();
-  currentVersion2 = "0.138.0".trim() ? "0.138.0".trim() : "0.1.0";
+  currentVersion2 = "0.140.0".trim() ? "0.140.0".trim() : "0.1.0";
 });
 
 // ../../packages/registry/src/index.ts
@@ -2945,6 +2945,17 @@ var init_src = __esm(() => {
       probeConfig: { cadenceMs: 30 * MINUTE_MS, cronName: "fluncle-rank", kind: "cron" },
       weights: { status: "hidden" }
     },
+    {
+      command: "fluncle admin backfills label-images",
+      exposedContent: [
+        "resolve each pending label's own logo (Discogs → Wikidata → cover floor) → its own R2 image"
+      ],
+      kind: "cron",
+      name: "cron.label-images",
+      operatorNotes: "every 60m, run by a rave-02 HOST systemd timer (docs/agents/hermes/label-images-timer/). The DURABLE other half of the label entity: the crawler MINTS new labels every few minutes (each `image_state='pending'`) and the one-shot operator backfill only seeded the labels that already existed, so this cron is what gives every freshly-minted label its OWN logo instead of a borrowed album cover. METADATA ONLY — a label logo is internal, reversible, nominative-use trademark (the album-art posture); it certifies nothing and publishes nothing (agent tier, the `backfill_discogs` precedent). Worker-paced (the box holds no Discogs key / MusicBrainz budget): one bounded batch per tick walks each label's MB identity → its curated Discogs/Wikidata url-rels → downloads the logo once into R2, up the ladder Discogs → Wikidata → none (the freshest-cover floor). The `labels` row carries the durable reliability state (image_state/image_attempted_at/image_failures), so a resolved/none label is terminal and a vendor throttle just circuit-breaks and resumes next tick. Zero LLM tokens. Source: docs/agents/hermes/scripts/label-images-sweep.*. See docs/label-entity.md.",
+      probeConfig: { cadenceMs: 60 * MINUTE_MS, cronName: "fluncle-label-images", kind: "cron" },
+      weights: { status: "hidden" }
+    },
     {
       command: "fluncle admin tracks capture-audio --queue",
       exposedContent: [
@@ -3655,7 +3666,8 @@ __export(exports_admin_tracks, {
   captureQueueCommand: () => captureQueueCommand,
   backfillLastfmCommand: () => backfillLastfmCommand,
   backfillDiscogsCommand: () => backfillDiscogsCommand,
-  backfillAppleMusicCommand: () => backfillAppleMusicCommand
+  backfillAppleMusicCommand: () => backfillAppleMusicCommand,
+  backfillAppleCatalogueCommand: () => backfillAppleCatalogueCommand
 });
 async function fetchAdminTracks(options) {
   const {
@@ -3835,6 +3847,10 @@ async function backfillAppleMusicCommand(limit, dryRun, cursor) {
   }
   return adminApiPost(`/api/admin/backfill/apple-music?${params.toString()}`);
 }
+async function backfillAppleCatalogueCommand(limit, dryRun) {
+  const params = new URLSearchParams({ dryRun: String(dryRun), limit: String(limit) });
+  return adminApiPost(`/api/admin/backfill/apple-catalogue?${params.toString()}`);
+}
 async function vehiclesCommand(limit) {
   const tracks = await fetchAdminTracks({ hasVideo: true, max: limit, order: "desc" });
   return tracks.map((track) => ({
@@ -5688,6 +5704,7 @@ var exports_admin_catalogue = {};
 __export(exports_admin_catalogue, {
   crawlStatusCommand: () => crawlStatusCommand,
   crawlCatalogueCommand: () => crawlCatalogueCommand,
+  clearWrongAudioCommand: () => clearWrongAudioCommand,
   catalogueRankCommand: () => catalogueRankCommand,
   catalogueListCommand: () => catalogueListCommand
 });
@@ -5698,12 +5715,17 @@ async function catalogueRankCommand(options) {
 }
 async function catalogueListCommand(options) {
   const params = new URLSearchParams;
-  params.set("lens", options.lens === "capture" ? "capture" : "ear");
+  params.set("lens", options.lens === "capture" ? "capture" : options.lens === "quarantine" ? "quarantine" : "ear");
   if (options.limit) {
     params.set("limit", options.limit);
   }
   return adminApiGet(`/api/admin/catalogue?${params.toString()}`);
 }
+async function clearWrongAudioCommand(trackId) {
+  return adminApiPost("/api/admin/catalogue/wrong-audio/clear", {
+    trackId
+  });
+}
 async function crawlCatalogueCommand(limit, maxHop, dryRun) {
   const params = new URLSearchParams({ limit: String(limit), maxHop: String(maxHop) });
   if (dryRun) {
@@ -8750,10 +8772,19 @@ function addAdminCommands(program2) {
     const { catalogueRankCommand: catalogueRankCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
     await runCatalogueRank(options, catalogueRankCommand2);
   });
-  catalogue.command("list").description("The ranked catalogue: closest to a finding (ear), or next to capture").option("--lens <lens>", "ear (default) or capture", "ear").option("--limit <limit>", "Rows (default 50, max 200)").option("--json", "Print JSON", false).action(async (options) => {
+  catalogue.command("list").description("The ranked catalogue: closest to a finding (ear), next to capture, or wrong audio").option("--lens <lens>", "ear (default), capture, or quarantine", "ear").option("--limit <limit>", "Rows (default 50, max 200)").option("--json", "Print JSON", false).action(async (options) => {
     const { catalogueListCommand: catalogueListCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
     await runCatalogueList(options, catalogueListCommand2);
   });
+  catalogue.command("clear-wrong-audio").description("Overrule the wrong-audio quarantine on one catalogue row (operator)").argument("<trackId>", "The catalogue track id to keep").option("--json", "Print JSON", false).action(async (trackId, options) => {
+    const { clearWrongAudioCommand: clearWrongAudioCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
+    const { cleared } = await clearWrongAudioCommand2(trackId);
+    if (options.json) {
+      printJson({ cleared, ok: true });
+      return;
+    }
+    console.log(cleared ? `Kept ${trackId}. Its audio re-embeds and rejoins the ranking on the next sweep.` : `${trackId} was not quarantined \u2014 nothing to clear.`);
+  });
   catalogue.command("crawl").description("Run one bounded, resumable pass of the catalogue crawler").option("--dry-run", "Report the seed plan and write nothing at all", false).option("--limit <limit>", "Frontier nodes to expand this pass", "10").option("--max-hop <maxHop>", "Graph distance from a seed label (0-3)", "2").option("--json", "Print JSON", false).action(async (options) => {
     const { crawlCatalogueCommand: crawlCatalogueCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
     await runCrawlCatalogue(options, crawlCatalogueCommand2);
@@ -8782,6 +8813,10 @@ function addAdminCommands(program2) {
     const { backfillAppleMusicCommand: backfillAppleMusicCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
     await runBackfillAppleMusic(options, backfillAppleMusicCommand2);
   });
+  backfill.command("apple-catalogue").description("Resolve Apple URLs + album facts for catalogue tracks (batched exact ISRC)").option("--dry-run", "Report the eligible set without resolving or writing", false).option("--limit <limit>", "Max catalogue rows to resolve", "50").option("--json", "Print JSON", false).action(async (options) => {
+    const { backfillAppleCatalogueCommand: backfillAppleCatalogueCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
+    await runBackfillAppleCatalogue(options, backfillAppleCatalogueCommand2);
+  });
   backfill.command("artists").description("Back-fill the artist entity (artists + track_artists) for existing findings").option("--dry-run", "Report which findings would be upserted without touching the DB", false).option("--limit <limit>", "Max findings to process", "50").option("--json", "Print JSON", false).action(async (options) => {
     const { backfillArtistsCommand: backfillArtistsCommand2 } = await Promise.resolve().then(() => (init_admin_artists(), exports_admin_artists));
     await runBackfillArtists(options, backfillArtistsCommand2);
@@ -9202,23 +9237,30 @@ async function runBackfillAppleMusic(options, backfillAppleMusicCommand2) {
   let cursor;
   let dryRun = options.dryRun;
   let throttled = false;
+  let breakerTripped = false;
   let configured = true;
+  let albumFactsWritten = 0;
   while (resolved.length + unresolved.length + failed.length < limit) {
     const remaining = limit - (resolved.length + unresolved.length + failed.length);
     const result = await backfillAppleMusicCommand2(remaining, options.dryRun, cursor);
     dryRun = result.dryRun;
     configured = result.configured;
+    albumFactsWritten += result.albumFactsWritten;
     resolved.push(...result.resolved);
     unresolved.push(...result.unresolved);
     failed.push(...result.failed);
     skipped.push(...result.skipped);
     if (!options.json) {
       const verb2 = result.dryRun ? "would resolve" : "resolved";
-      console.log(`  \u2026${verb2} ${result.resolvedCount}; ${result.unresolvedCount} unresolved; ${result.failedCount} failed; ${result.skippedCount} skipped`);
+      console.log(`  \u2026${verb2} ${result.resolvedCount}; ${result.unresolvedCount} unresolved; ${result.failedCount} failed; ${result.skippedCount} skipped; ${result.albumFactsWritten} album facts`);
     }
     if (!result.configured) {
       break;
     }
+    if (result.breakerTripped) {
+      breakerTripped = true;
+      break;
+    }
     if (result.rateLimited) {
       throttled = true;
       break;
@@ -9230,6 +9272,8 @@ async function runBackfillAppleMusic(options, backfillAppleMusicCommand2) {
   }
   if (options.json) {
     printSweepJson({
+      albumFactsWritten,
+      breakerTripped,
       configured,
       dryRun,
       failed,
@@ -9248,7 +9292,7 @@ async function runBackfillAppleMusic(options, backfillAppleMusicCommand2) {
     return;
   }
   const verb = dryRun ? "Would resolve" : "Resolved";
-  console.log(`${verb} ${resolved.length} Apple Music URL(s); ${unresolved.length} unresolved; ${failed.length} failed; ${skipped.length} skipped.`);
+  console.log(`${verb} ${resolved.length} Apple Music URL(s); ${unresolved.length} unresolved; ${failed.length} failed; ${skipped.length} skipped; ${albumFactsWritten} album facts.`);
   for (const item of resolved) {
     console.log(`  ${item.logId}: ${item.url}`);
   }
@@ -9259,6 +9303,72 @@ async function runBackfillAppleMusic(options, backfillAppleMusicCommand2) {
     process.exitCode = 1;
   }
 }
+async function runBackfillAppleCatalogue(options, backfillAppleCatalogueCommand2) {
+  const limit = parseListLimit(options.limit);
+  const resolved = [];
+  const unresolved = [];
+  const failed = [];
+  let dryRun = options.dryRun;
+  let throttled = false;
+  let breakerTripped = false;
+  let configured = true;
+  let albumFactsWritten = 0;
+  while (resolved.length + unresolved.length + failed.length < limit) {
+    const remaining = limit - (resolved.length + unresolved.length + failed.length);
+    const result = await backfillAppleCatalogueCommand2(remaining, options.dryRun);
+    dryRun = result.dryRun;
+    configured = result.configured;
+    albumFactsWritten += result.albumFactsWritten;
+    resolved.push(...result.resolved);
+    unresolved.push(...result.unresolved);
+    failed.push(...result.failed);
+    if (!options.json) {
+      const verb2 = result.dryRun ? "would resolve" : "resolved";
+      console.log(`  \u2026${verb2} ${result.resolvedCount}; ${result.unresolvedCount} unresolved; ${result.failedCount} failed; ${result.albumFactsWritten} album facts`);
+    }
+    if (!result.configured) {
+      break;
+    }
+    if (result.breakerTripped) {
+      breakerTripped = true;
+      break;
+    }
+    if (result.rateLimited) {
+      throttled = true;
+      break;
+    }
+    if (result.resolvedCount === 0 && result.unresolvedCount === 0 && result.failedCount === 0) {
+      break;
+    }
+  }
+  if (options.json) {
+    printSweepJson({
+      albumFactsWritten,
+      breakerTripped,
+      configured,
+      dryRun,
+      failed,
+      rateLimited: throttled,
+      resolved,
+      resolvedCount: resolved.length,
+      unresolved,
+      unresolvedCount: unresolved.length
+    }, failed.length);
+    return;
+  }
+  if (!configured) {
+    console.log("Apple catalogue backfill is not configured (the Worker's MusicKit secrets are unset) \u2014 nothing resolved.");
+    return;
+  }
+  const verb = dryRun ? "Would resolve" : "Resolved";
+  console.log(`${verb} ${resolved.length} catalogue Apple URL(s); ${unresolved.length} unresolved; ${failed.length} failed; ${albumFactsWritten} album facts.`);
+  for (const item of failed) {
+    console.log(`  ${item.trackId}: ${item.error}`);
+  }
+  if (failed.length > 0) {
+    process.exitCode = 1;
+  }
+}
 async function runBackfillArtists(options, backfillArtistsCommand2) {
   const limit = parseListLimit(options.limit);
   const upserted = [];
@@ -10269,7 +10379,8 @@ async function runCatalogueRank(options, catalogueRankCommand2) {
     printJson({ ok: true, summary });
     return;
   }
-  console.log(`Ranked ${summary.scored} against ${summary.embeddedFindings} embedded findings; prioritized ${summary.prioritized} for capture. ${summary.remaining} still stale.`);
+  const quarantine = summary.quarantined > 0 ? ` Quarantined ${summary.quarantined} as wrong audio.` : "";
+  console.log(`Ranked ${summary.scored} against ${summary.embeddedFindings} embedded findings; prioritized ${summary.prioritized} for capture.${quarantine} ${summary.remaining} still stale.`);
 }
 async function runCatalogueList(options, catalogueListCommand2) {
   const { summary, tracks } = await catalogueListCommand2({
@@ -10281,20 +10392,28 @@ async function runCatalogueList(options, catalogueListCommand2) {
     return;
   }
   if (tracks.length === 0) {
-    console.log("Nothing out there yet.");
+    console.log(options.lens === "quarantine" ? "No wrong-audio captures." : "Nothing out there yet.");
     return;
   }
   for (const track of tracks) {
     const identity = `${track.artists.join(", ")} \u2014 ${track.title}`;
+    if (options.lens === "quarantine") {
+      const collided = track.nearestFinding;
+      const why2 = collided ? `its audio came back as ${collided.logId ? `${collided.logId} ` : ""}${collided.artists.join(", ")} \u2014 ${collided.title}` : "its audio matched a track already in the archive";
+      console.log(`wrong-audio  ${identity.padEnd(52)} ${why2}`);
+      continue;
+    }
+    const dup = track.duplicateOf;
+    const dupWhy = dup ? `already in the archive \u2014 ${dup.logId ? `${dup.logId} ` : ""}${dup.artists.join(", ")} \u2014 ${dup.title}` : null;
     if (options.lens === "capture") {
       const reason = track.captureReason;
-      const why2 = reason?.kind === "artist" ? `${reason.name} is already in the archive` : reason?.kind === "label" ? `${reason.name} already carries a finding` : reason?.kind === "seed-label" ? `${reason.name} is a label the crawler digs from` : reason?.kind === "skipped-label" ? `${reason.name} is not your lane \u2014 ranked last, kept anyway` : "nothing ties it to the archive yet";
+      const why2 = dupWhy ?? (reason?.kind === "artist" ? `${reason.name} is already in the archive` : reason?.kind === "label" ? `${reason.name} already carries a finding` : reason?.kind === "seed-label" ? `${reason.name} is a label the crawler digs from` : reason?.kind === "skipped-label" ? `${reason.name} is not your lane \u2014 ranked last, kept anyway` : "nothing ties it to the archive yet");
       console.log(`${String(track.capturePriority ?? 0)}  ${identity.padEnd(52)} ${why2}`);
       continue;
     }
     const match = track.nearestFinding;
     const score = track.nearestFindingScore?.toFixed(2) ?? "\u2014";
-    const why = match ? `closest to ${match.logId ? `${match.logId} ` : ""}${match.artists.join(", ")} \u2014 ${match.title}` : "nothing to compare it to yet";
+    const why = dupWhy ?? (match ? `closest to ${match.logId ? `${match.logId} ` : ""}${match.artists.join(", ")} \u2014 ${match.title}` : "nothing to compare it to yet");
     console.log(`${score}  ${identity.padEnd(52)} ${why}`);
   }
 }

package/package.json

@@ -31,5 +31,5 @@
     "url": "git+https://github.com/mauricekleine/fluncle.git"
   },
   "type": "module",
-  "version": "0.138.0"
+  "version": "0.140.0"
 }