fluncle 0.129.0 → 0.131.0

package/bin/fluncle.mjs

@@ -561,7 +561,7 @@ function parseVersion(version) {
 var currentVersion;
 var init_version = __esm(() => {
   init_output();
-  currentVersion = "0.129.0".trim() ? "0.129.0".trim() : "0.1.0";
+  currentVersion = "0.131.0".trim() ? "0.131.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.129.0".trim() ? "0.129.0".trim() : "0.1.0";
+  currentVersion2 = "0.131.0".trim() ? "0.131.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`,
@@ -2888,6 +2903,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: [
@@ -3570,6 +3607,7 @@ var init_track2 = __esm(() => {
 var exports_admin_tracks = {};
 __export(exports_admin_tracks, {
   vehiclesCommand: () => vehiclesCommand,
+  trackWorkCommand: () => trackWorkCommand,
   requeueAnalysisCommand: () => requeueAnalysisCommand,
   queueCommand: () => queueCommand,
   observeQueueCommand: () => observeQueueCommand,
@@ -3671,6 +3709,15 @@ async function embedQueueCommand(limit) {
 async function captureQueueCommand(limit) {
   return fetchAdminTracks({ captureQueue: true, max: limit, order: "desc" });
 }
+async function trackWorkCommand(options) {
+  const params = new URLSearchParams({
+    kind: options.kind,
+    limit: String(Math.min(Math.max(1, options.limit), 200)),
+    scope: options.scope
+  });
+  const response = await adminApiGet(`/api/admin/tracks/work?${params.toString()}`);
+  return response.tracks ?? [];
+}
 async function requeueAnalysisCommand(options) {
   const findings = await fetchAdminTracks({ max: options.max, order: "asc" });
   const stale = findings.filter((track) => track.analyzedFrom !== "full");
@@ -5354,6 +5401,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
 });
@@ -5370,6 +5419,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();
 });
@@ -8016,6 +8075,10 @@ function addAdminCommands(program2) {
     const { captureQueueCommand: captureQueueCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
     await runAdminCaptureQueue(options, captureQueueCommand2);
   });
+  adminTracks.command("work").description("The audio pipeline's worklist for one stage, in capture-priority order").requiredOption("--kind <kind>", "Pipeline stage: analyze | capture | embed").option("--scope <scope>", "Which half of the archive: all | catalogue | findings", "all").option("--limit <limit>", "Rows to show", "10").option("--json", "Print JSON", false).action(async (options) => {
+    const { trackWorkCommand: trackWorkCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
+    await runAdminTrackWork(options, trackWorkCommand2);
+  });
   adminTracks.command("requeue-analysis").description("Re-queue findings whose BPM/key are preview-grade (dry-run; --apply to flip)").option("--apply", "Actually flip statuses (default is a dry-run preview)", false).option("--limit <limit>", "Cap the archive walk (default: the whole archive)").option("--json", "Print JSON", false).action(async (options) => {
     const { requeueAnalysisCommand: requeueAnalysisCommand2 } = await Promise.resolve().then(() => (init_admin_tracks(), exports_admin_tracks));
     await runAdminRequeueAnalysis(options, requeueAnalysisCommand2);
@@ -8307,7 +8370,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();
   });
@@ -8319,6 +8382,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();
@@ -8616,6 +8687,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 = [];
@@ -9734,6 +9840,42 @@ async function runAdminCaptureQueue(options, captureQueueCommand2) {
   console.log(trackRows2(tracks).join(`
 `));
 }
+var TRACK_WORK_KINDS = new Set(["analyze", "capture", "embed"]);
+var TRACK_WORK_SCOPES = new Set(["all", "catalogue", "findings"]);
+async function runAdminTrackWork(options, trackWorkCommand2) {
+  const kind = options.kind?.trim().toLowerCase() ?? "";
+  const scope = options.scope?.trim().toLowerCase() ?? "all";
+  if (!TRACK_WORK_KINDS.has(kind)) {
+    console.error(`--kind must be one of: analyze, capture, embed (got "${options.kind}")`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!TRACK_WORK_SCOPES.has(scope)) {
+    console.error(`--scope must be one of: all, catalogue, findings (got "${options.scope}")`);
+    process.exitCode = 1;
+    return;
+  }
+  const tracks = await trackWorkCommand2({
+    kind,
+    limit: parseListLimit(options.limit),
+    scope
+  });
+  if (options.json) {
+    printJson({ ok: true, tracks });
+    return;
+  }
+  if (tracks.length === 0) {
+    console.log(`Nothing to ${kind}. The ${scope} queue is drained.`);
+    return;
+  }
+  const noun = tracks.length === 1 ? "track" : "tracks";
+  console.log(`${tracks.length} ${noun} to ${kind} (${scope}), in drain order:`);
+  for (const track of tracks) {
+    const who = track.logId ?? `${track.trackId} \xB7 catalogue`;
+    const rung = track.capturePriority === null ? "" : ` \xB7 p${track.capturePriority}`;
+    console.log(`  ${who}${rung} \u2014 ${track.artists.join(", ")} \u2014 ${track.title}`);
+  }
+}
 var REQUEUE_ANALYSIS_ARCHIVE_CAP = 1e6;
 function parseRequeueAnalysisLimit(value) {
   if (value === undefined) {
@@ -10055,6 +10197,7 @@ var stringOptions = new Set([
   "--kind",
   "--lens",
   "--limit",
+  "--max-hop",
   "--metrics",
   "--mime",
   "--model",
@@ -10075,6 +10218,7 @@ var stringOptions = new Set([
   "--scheduled-for",
   "--script",
   "--script-file",
+  "--scope",
   "--seed",
   "--soundcloud-url",
   "--source",

package/package.json

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