fluncle 0.130.0 → 0.132.0

package/bin/fluncle.mjs

@@ -561,7 +561,7 @@ function parseVersion(version) {
 var currentVersion;
 var init_version = __esm(() => {
   init_output();
-  currentVersion = "0.130.0".trim() ? "0.130.0".trim() : "0.1.0";
+  currentVersion = "0.132.0".trim() ? "0.132.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.130.0".trim() ? "0.130.0".trim() : "0.1.0";
+  currentVersion2 = "0.132.0".trim() ? "0.132.0".trim() : "0.1.0";
 });
 
 // ../../packages/registry/src/index.ts
@@ -2537,6 +2537,21 @@ var init_src = __esm(() => {
       url: `${SITE}/api/v1/search`,
       weights: { web: "secondary" }
     },
+    {
+      apiFormat: "application/json",
+      discoveryUrl: `${SITE}/api/v1/openapi.json`,
+      exposedContent: [
+        "search Fluncle's archive: a coordinate (004.7.2I), an artist/label/album name, a bare word (FTS5), or a natural-language query",
+        "sonic search — 'tracks that sound like <a real track>', ranked by MuQ embedding distance"
+      ],
+      kind: "api",
+      name: "api.search.archive",
+      operatorNotes: "The public read behind the ⌘K dialog (search_archive), and the primary navigation once the archive is deep. Four resolution tiers; only the fourth reaches an LLM (OpenRouter, 3s deadline) and it emits FILTERS, never rows. With no OPENROUTER_API_KEY it degrades to full-text and still answers — so it probes green unprovisioned.",
+      probeConfig: { cadenceMs: PROBE_CADENCE_MS, kind: "http", timeoutMs: PROBE_TIMEOUT_MS },
+      route: "/api/v1/search/archive",
+      url: `${SITE}/api/v1/search/archive?q=netsky`,
+      weights: { web: "primary" }
+    },
     {
       apiFormat: "application/json",
       discoveryUrl: `${SITE}/api/v1/openapi.json`,
@@ -2821,6 +2836,15 @@ var init_src = __esm(() => {
       name: "cli.tracks-get",
       weights: { cli: "tertiary" }
     },
+    {
+      command: "fluncle tracks similar",
+      exposedContent: [
+        "the findings that sound nearest to one (the sonic neighbourhood, off the MuQ audio embedding), each with its note"
+      ],
+      kind: "cli",
+      name: "cli.tracks-similar",
+      weights: { cli: "tertiary" }
+    },
     {
       command: "fluncle about",
       exposedContent: ["Fluncle, and where to find him"],
@@ -2888,6 +2912,28 @@ var init_src = __esm(() => {
       probeConfig: { cadenceMs: 24 * 60 * MINUTE_MS, cronName: "fluncle-cluster", kind: "cron" },
       weights: { status: "hidden" }
     },
+    {
+      command: "fluncle admin catalogue crawl",
+      exposedContent: [
+        "walk the MusicBrainz release graph outward from the operator's enabled seed labels → uncertified catalogue rows"
+      ],
+      kind: "cron",
+      name: "cron.crawl",
+      operatorNotes: "every 10m, run by a rave-02 HOST systemd timer (docs/agents/hermes/crawl-timer/). METADATA ONLY — it writes a `tracks` row with no `findings` row, so it certifies nothing (no Log ID, no note, no video, no public surface) and it captures no audio. Worker-paced (the box holds no MusicBrainz budget): one bounded pass per tick over the durable `crawl_frontier`, so a crawl is a marathon the SCHEDULE finishes and a reboot mid-label costs one node, not one crawl. The boundary gate is the operator's seed-label allowlist + graph distance (hop 0-2), never genre inference; a label the walk discovers enters `undecided` and is NOT crawled until he rules on it. Zero LLM tokens. Source: docs/agents/hermes/scripts/crawl-sweep.*. See docs/catalogue-crawler.md.",
+      probeConfig: { cadenceMs: 10 * MINUTE_MS, cronName: "fluncle-crawl", kind: "cron" },
+      weights: { status: "hidden" }
+    },
+    {
+      command: "fluncle admin catalogue rank",
+      exposedContent: [
+        "score each stale catalogue track against every embedded finding → its nearest finding + capture priority"
+      ],
+      kind: "cron",
+      name: "cron.rank",
+      operatorNotes: "every 30m, run by a rave-02 HOST systemd timer (docs/agents/hermes/rank-timer/). THE EAR's schedule, and it lands with the crawler on purpose: a timer ranking an empty table would be a /status row that means nothing, and the crawler is what creates rows. All the vector arithmetic runs in SQL inside the Worker; the sweep DRAINS (it loops while `remaining > 0` up to a tick budget), so a crawl that just landed 700 rows is ranked by the next tick. Self-healing: staleness is a fingerprint of the finding corpus, so logging or embedding a finding re-ranks the catalogue with no invalidation call. Writes DERIVED columns on catalogue rows only — it cannot certify. Zero LLM tokens. Source: docs/agents/hermes/scripts/rank-sweep.*. See docs/the-ear.md.",
+      probeConfig: { cadenceMs: 30 * MINUTE_MS, cronName: "fluncle-rank", kind: "cron" },
+      weights: { status: "hidden" }
+    },
     {
       command: "fluncle admin tracks capture-audio --queue",
       exposedContent: [
@@ -3184,6 +3230,7 @@ __export(exports_track, {
   trackSocialUpdateCommand: () => trackSocialUpdateCommand,
   trackSocialShowCommand: () => trackSocialShowCommand,
   trackSocialCaptureCommand: () => trackSocialCaptureCommand,
+  trackSimilarCommand: () => trackSimilarCommand,
   trackRequeueVideoCommand: () => trackRequeueVideoCommand,
   trackPurgeVideoCommand: () => trackPurgeVideoCommand,
   trackObserveCommand: () => trackObserveCommand,
@@ -3198,6 +3245,10 @@ __export(exports_track, {
 async function trackGetCommand(idOrLogId) {
   return publicApiGet(`/api/tracks/${encodeURIComponent(idOrLogId)}`);
 }
+async function trackSimilarCommand(idOrLogId, limit) {
+  const query = limit === undefined ? "" : `?limit=${encodeURIComponent(String(limit))}`;
+  return publicApiGet(`/api/tracks/${encodeURIComponent(idOrLogId)}/similar${query}`);
+}
 async function trackGetAdminCommand(idOrLogId) {
   return adminApiGet(`/api/admin/tracks/${encodeURIComponent(idOrLogId)}`);
 }
@@ -3401,6 +3452,9 @@ async function trackContextCommand(idOrLogId, options = {}) {
 }
 async function trackNoteCommand(idOrLogId, options) {
   const body = { note: options.note };
+  if (options.dryRun) {
+    body.dryRun = true;
+  }
   return adminApiPost(`/api/admin/tracks/${encodeURIComponent(idOrLogId)}/note`, body);
 }
 var DEFAULT_VIDEO_MODEL = "anthropic/claude-opus-4-8", DEFAULT_VIDEO_REASONING = "high", FOUND_BASE = "https://found.fluncle.com", VIDEO_FIELDS, RERENDER_CONTRACT_FIELDS, RERENDER_ADVISORY_FIELDS, FOOTAGE_FIELDS, PLATE_FIELDS, NON_FILE_OPTIONS;
@@ -5364,6 +5418,8 @@ var init_auth_lastfm = __esm(() => {
 // src/commands/admin-catalogue.ts
 var exports_admin_catalogue = {};
 __export(exports_admin_catalogue, {
+  crawlStatusCommand: () => crawlStatusCommand,
+  crawlCatalogueCommand: () => crawlCatalogueCommand,
   catalogueRankCommand: () => catalogueRankCommand,
   catalogueListCommand: () => catalogueListCommand
 });
@@ -5380,6 +5436,16 @@ async function catalogueListCommand(options) {
   }
   return adminApiGet(`/api/admin/catalogue?${params.toString()}`);
 }
+async function crawlCatalogueCommand(limit, maxHop, dryRun) {
+  const params = new URLSearchParams({ limit: String(limit), maxHop: String(maxHop) });
+  if (dryRun) {
+    params.set("dryRun", "true");
+  }
+  return adminApiPost(`/api/admin/catalogue/crawl?${params.toString()}`);
+}
+async function crawlStatusCommand() {
+  return adminApiGet("/api/admin/catalogue/crawl");
+}
 var init_admin_catalogue = __esm(() => {
   init_api();
 });
@@ -7970,6 +8036,10 @@ function addTrackCommands(program2) {
     const { trackGetCommand: trackGetCommand2 } = await Promise.resolve().then(() => (init_track(), exports_track));
     await runTrackGet(idOrLogId, options, trackGetCommand2);
   });
+  tracks.command("similar").description("The findings that sound nearest to one (the sonic neighbourhood)").argument("[idOrLogId]").option("--limit <limit>", "Number of neighbours to show", "6").option("--json", "Print JSON", false).allowExcessArguments().action(async (idOrLogId, options) => {
+    const { trackSimilarCommand: trackSimilarCommand2 } = await Promise.resolve().then(() => (init_track(), exports_track));
+    await runTrackSimilar(idOrLogId, options, trackSimilarCommand2);
+  });
 }
 function addAdminCommands(program2) {
   const admin = configureCommand(program2.command("admin", { hidden: true }).description("Operator commands"));
@@ -8098,7 +8168,7 @@ function addAdminCommands(program2) {
     const { trackContextCommand: trackContextCommand2 } = await Promise.resolve().then(() => (init_track(), exports_track));
     await runTrackContext(idOrLogId, options, trackContextCommand2);
   });
-  adminTrack.command("note").description("Author the editorial note for a finding (fills an empty note only)").argument("[idOrLogId]").option("--queue", "Show the note worklist (context'd findings with no note yet), oldest first", false).option("--limit <limit>", "Number of findings to show with --queue", "10").option("--script <text>", "The voice-gated editorial note").option("--script-file <file>", "Read the editorial note from a file").option("--json", "Print JSON", false).allowExcessArguments().action(async (idOrLogId, options) => {
+  adminTrack.command("note").description("Author the editorial note for a finding (fills an empty note only)").argument("[idOrLogId]").option("--queue", "Show the note worklist (context'd findings with no note yet), oldest first", false).option("--limit <limit>", "Number of findings to show with --queue", "10").option("--script <text>", "The voice-gated editorial note").option("--script-file <file>", "Read the editorial note from a file").option("--dry-run", "Run the voice + echo gates and report the verdict without storing anything", false).option("--json", "Print JSON", false).allowExcessArguments().action(async (idOrLogId, options) => {
     if (options.queue) {
       const { noteQueueCommand: noteQueueCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
       await runAdminNoteQueue(options, noteQueueCommand2);
@@ -8321,7 +8391,7 @@ function addAdminCommands(program2) {
     const { galaxyMapWriteCommand: galaxyMapWriteCommand2 } = await Promise.resolve().then(() => (init_galaxies(), exports_galaxies));
     await runGalaxyMapWrite(options, galaxyMapWriteCommand2);
   });
-  const catalogue = configureCommand(admin.command("catalogue").description("The catalogue (uncertified tracks) + its ranking"));
+  const catalogue = configureCommand(admin.command("catalogue").description("The catalogue (uncertified tracks): the crawler + its ranking"));
   catalogue.action(() => {
     catalogue.outputHelp();
   });
@@ -8333,6 +8403,14 @@ function addAdminCommands(program2) {
     const { catalogueListCommand: catalogueListCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
     await runCatalogueList(options, catalogueListCommand2);
   });
+  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);
+  });
+  catalogue.command("status").description("The crawl frontier's state, the catalogue's size, and the seed set").option("--json", "Print JSON", false).action(async (options) => {
+    const { crawlStatusCommand: crawlStatusCommand2 } = await Promise.resolve().then(() => (init_admin_catalogue(), exports_admin_catalogue));
+    await runCrawlStatus(options, crawlStatusCommand2);
+  });
   const backfill = configureCommand(admin.command("backfills").description("Backfill operator-only archives"));
   backfill.action(() => {
     backfill.outputHelp();
@@ -8452,9 +8530,12 @@ async function runTrackContext(idOrLogId, options, trackContextCommand2) {
 async function runTrackNote(idOrLogId, options, trackNoteCommand2) {
   const note = options.scriptFile ? readFileSync6(options.scriptFile, "utf8") : options.script;
   if (!idOrLogId || !note || !note.trim()) {
-    throw new Error("Usage: fluncle admin tracks note <track_id|log_id> (--script <text> | --script-file <file>) [--json]");
+    throw new Error("Usage: fluncle admin tracks note <track_id|log_id> (--script <text> | --script-file <file>) [--dry-run] [--json]");
   }
-  const result = await trackNoteCommand2(idOrLogId, { note: note.trim() });
+  const result = await trackNoteCommand2(idOrLogId, {
+    dryRun: options.dryRun,
+    note: note.trim()
+  });
   if (options.json) {
     printJson(result);
     return;
@@ -8463,9 +8544,39 @@ async function runTrackNote(idOrLogId, options, trackNoteCommand2) {
     console.log(`A note is already on file for ${result.logId}. The operator's note stands.`);
     return;
   }
+  if (result.dryRun) {
+    console.log(`Both gates passed for ${result.logId}. Nothing was stored (dry run).`);
+    console.log(`  ${result.note}`);
+    if (result.echo?.logId) {
+      const reading = result.echo.phrase ? `lifts "${result.echo.phrase}" from ${result.echo.logId}` : `${Math.round(result.echo.overlap * 100)}% word overlap with ${result.echo.logId}`;
+      console.log(`  echo: ${reading}`);
+    }
+    return;
+  }
   console.log(`Authored the note for ${result.logId}:`);
   console.log(`  ${result.note}`);
 }
+async function runTrackSimilar(idOrLogId, options, trackSimilarCommand2) {
+  if (!idOrLogId) {
+    throw new Error("Missing id. Usage: fluncle tracks similar <track_id|log_id> [--limit <n>] [--json]");
+  }
+  const limit = options.limit ? Number.parseInt(options.limit, 10) : undefined;
+  const result = await trackSimilarCommand2(idOrLogId, limit !== undefined && Number.isFinite(limit) ? limit : undefined);
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+  if (result.findings.length === 0) {
+    console.log("Nothing sounds near this one yet. It may still be waiting on its embedding.");
+    return;
+  }
+  for (const finding of result.findings) {
+    console.log(`${finding.logId ?? "\u2014"}  ${finding.artists.join(", ")} \u2014 ${finding.title}`);
+    if (finding.note) {
+      console.log(`  ${finding.note}`);
+    }
+  }
+}
 function printSweepJson(payload, failedCount) {
   printJson({ ...payload, failedCount, ok: failedCount === 0 });
   if (failedCount > 0) {
@@ -8630,6 +8741,41 @@ async function runBackfillLastfm(options, backfillLastfmCommand2) {
     process.exitCode = 1;
   }
 }
+async function runCrawlCatalogue(options, crawlCatalogueCommand2) {
+  const limit = parseListLimit(options.limit);
+  const maxHop = Number.parseInt(options.maxHop ?? "2", 10);
+  const result = await crawlCatalogueCommand2(limit, Number.isInteger(maxHop) && maxHop >= 0 ? maxHop : 2, options.dryRun);
+  if (options.json) {
+    printJson(result);
+  } else if (result.dryRun) {
+    console.log(`Dry run: would seed ${result.seeded} enabled label(s); ${result.frontierPending} node(s) pending. Nothing written.`);
+  } else {
+    console.log(`Expanded ${result.expanded} node(s) at hop \u2264 ${result.maxHop}: ${result.tracksFound} track(s) found, ${result.tracksWritten} written, ${result.tracksSkipped} already held.`);
+    console.log(`  +${result.seeded} seed(s), +${result.nodesEnqueued} node(s) enqueued, ${result.frontierPending} pending, ${result.failed} failed.`);
+    console.log(`  ${result.anchorsFilled} Spotify anchor(s) filled.`);
+    if (result.labelsDiscovered.length > 0) {
+      console.log(`  New labels to rule on: ${result.labelsDiscovered.join(", ")} (they are NOT crawled until enabled).`);
+    }
+    if (result.rateLimited) {
+      console.log("  MusicBrainz throttled the pass. Stopped clean; the next tick resumes.");
+    }
+  }
+  if (result.rateLimited) {
+    process.exitCode = 1;
+  }
+}
+async function runCrawlStatus(options, crawlStatusCommand2) {
+  const result = await crawlStatusCommand2();
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+  const { frontier, frontierByKind } = result;
+  console.log(`Catalogue: ${result.catalogueTracks} uncertified track(s); ${result.anchorsPending} awaiting a Spotify anchor.`);
+  console.log(`Frontier: ${frontier.pending} pending, ${frontier.done} done, ${frontier.failed} failed, ${frontier.skipped} skipped (${frontierByKind.label} label, ${frontierByKind.artist} artist, ${frontierByKind.release} release).`);
+  console.log(`Seeds (${result.seedLabels.length}): ${result.seedLabels.join(", ") || "none enabled"}.`);
+  console.log(`Awaiting your ruling: ${result.labelsUndecided} label(s).`);
+}
 async function runBackfillDiscogs(options, backfillDiscogsCommand2) {
   const limit = parseListLimit(options.limit);
   const resolved = [];
@@ -10105,6 +10251,7 @@ var stringOptions = new Set([
   "--kind",
   "--lens",
   "--limit",
+  "--max-hop",
   "--metrics",
   "--mime",
   "--model",

package/package.json

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