engine-dj-mcp 0.9.0 → 0.9.2

package/dist/blobs/index.d.ts

@@ -307,6 +307,18 @@ export declare function decodeBeatgrid(buf: Buffer | null): BeatgridResult;
  * `duration_seconds` still comes from Track.length rather than from the
  * blob: the overview carries a sample *count* but no sample rate, so a
  * duration derived from it alone would be a guess.
+ *
+ * `buckets` has no caller today that passes anything but the default, so a
+ * bad value here is unreachable in practice -- guarded anyway so it stays
+ * that way for the next caller rather than becoming a trap. A non-finite or
+ * non-positive value (0, negative, NaN, +/-Infinity) falls back to the
+ * default instead of reaching the bucket-size arithmetic below: 0 or a
+ * negative value there would clamp the *denominator*, not the bucket count,
+ * which maximises bucket size and collapses the whole track into one giant
+ * bucket -- the opposite of "more buckets"; NaN propagates through to a
+ * single bucket reporting a peak of 0 regardless of the actual audio. Both
+ * still come back `status: "ok"` -- a confident, wrong answer, not a
+ * request this function visibly declined to honour.
  */
 export declare function summariseWaveform(buf: Buffer | null, buckets?: number, durationSeconds?: number | null): WaveformSummary;
 export interface PerformanceRow {

package/dist/blobs/index.js

@@ -413,10 +413,23 @@ export function decodeBeatgrid(buf) {
  * `duration_seconds` still comes from Track.length rather than from the
  * blob: the overview carries a sample *count* but no sample rate, so a
  * duration derived from it alone would be a guess.
+ *
+ * `buckets` has no caller today that passes anything but the default, so a
+ * bad value here is unreachable in practice -- guarded anyway so it stays
+ * that way for the next caller rather than becoming a trap. A non-finite or
+ * non-positive value (0, negative, NaN, +/-Infinity) falls back to the
+ * default instead of reaching the bucket-size arithmetic below: 0 or a
+ * negative value there would clamp the *denominator*, not the bucket count,
+ * which maximises bucket size and collapses the whole track into one giant
+ * bucket -- the opposite of "more buckets"; NaN propagates through to a
+ * single bucket reporting a peak of 0 regardless of the actual audio. Both
+ * still come back `status: "ok"` -- a confident, wrong answer, not a
+ * request this function visibly declined to honour.
  */
 export function summariseWaveform(buf, buckets = 32, durationSeconds = null) {
     if (!buf || buf.length === 0)
         return { layout: LAYOUT_VERIFIED, status: "empty" };
+    const safeBuckets = Number.isFinite(buckets) && buckets > 0 ? buckets : 32;
     try {
         const data = qUncompress(buf);
         if (data.length === 0)
@@ -431,7 +444,7 @@ export function summariseWaveform(buf, buckets = 32, durationSeconds = null) {
         // bytes(): bounds-checked, so a count larger than the blob is refused
         // here rather than producing a silently short waveform.
         const points = r.bytes(entries * 3);
-        const size = Math.max(1, Math.ceil(entries / Math.max(1, buckets)));
+        const size = Math.max(1, Math.ceil(entries / safeBuckets));
         const profile = [];
         for (let i = 0; i < entries; i += size) {
             let peak = 0;

package/dist/discovery.js

@@ -2,13 +2,25 @@ import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
-import { err } from "./errors.js";
+import { err, isEngineError, libraryNeedsRecovery } from "./errors.js";
+import { hasHotJournal } from "./store/connections.js";
 import { libraryCandidates } from "./paths.js";
 export const SUPPORTED_SCHEMAS = ["3.0.0", "3.0.1", "3.0.2"];
 export function readLibraryInfo(mdbPath) {
     if (!existsSync(mdbPath)) {
         return err("library_not_found", `No Engine library database at ${mdbPath}`);
     }
+    if (hasHotJournal(mdbPath)) {
+        // Same check openQueryConnection makes before opening (store/connections.ts):
+        // recovering a hot journal needs a write, which this project never
+        // performs, even to probe a library. Caught here first so the specific,
+        // actionable library_needs_recovery reaches the caller instead of the
+        // SELECT below failing with the raw "attempt to write a readonly
+        // database" and landing in the generic library_unreadable catch --
+        // that conflation is exactly what made this condition hard to diagnose
+        // in practice.
+        return libraryNeedsRecovery();
+    }
     let db;
     try {
         // A plain path, never a hand-built "file:" URI. SQLite's URI syntax
@@ -39,8 +51,9 @@ export function readLibraryInfo(mdbPath) {
         // with Number(); nothing here forces an oversized column through it.
         stmt.setReadBigInts(true);
         const row = stmt.get();
+        // Not a version problem -- there is no row to read a version from.
         if (!row)
-            return err("unsupported_schema", "Information table is empty");
+            return err("library_unreadable", "Information table is empty");
         const schema = [
             Number(row.schemaVersionMajor ?? 0),
             Number(row.schemaVersionMinor ?? 0),
@@ -57,7 +70,12 @@ export function readLibraryInfo(mdbPath) {
         return { path: mdbPath, uuid: String(row.uuid ?? ""), schema, supported, trackCount };
     }
     catch (e) {
-        return err("unsupported_schema", "Could not read Information", {
+        // Whatever this is -- corruption, a permissions problem, a lock the
+        // open survived but the read did not -- it was never about the schema
+        // version: that is only known once this SELECT has actually returned a
+        // row, which it did not. The hot-journal case is carved out above, so
+        // this is the genuine remainder.
+        return err("library_unreadable", "Could not read Information", {
             detail: String(e.message),
         });
     }
@@ -91,7 +109,7 @@ export function probeLibraries(roots = defaultRoots()) {
             if (!existsSync(candidate))
                 continue;
             const info = readLibraryInfo(candidate);
-            out.push("error" in info
+            out.push(isEngineError(info)
                 ? { path: candidate, info: null, error: info }
                 : { path: candidate, info, error: null });
         }

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export declare const ERROR_CODES: readonly ["library_busy", "library_not_found", "unsupported_schema", "query_timeout", "query_process_crashed", "index_stale", "decode_failed", "invalid_argument", "library_needs_recovery"];
+export declare const ERROR_CODES: readonly ["library_busy", "library_not_found", "library_unreadable", "unsupported_schema", "query_timeout", "query_process_crashed", "index_stale", "decode_failed", "invalid_argument", "library_needs_recovery"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export interface EngineError {
     error: ErrorCode;

package/dist/errors.js

@@ -1,6 +1,17 @@
 export const ERROR_CODES = [
     "library_busy",
     "library_not_found",
+    // The library was found and opened, but a read against it failed for a
+    // reason that has nothing to do with schema version -- corruption, a
+    // permissions problem, an oversized column node:sqlite refuses to convert.
+    // Distinct from unsupported_schema (below), which is specifically "this
+    // version is outside the allowlist", and from library_needs_recovery,
+    // which is specifically a hot journal: discovery.ts checks for that first
+    // and reports it precisely, so this is only the remainder. Previously
+    // every one of these landed on unsupported_schema, which sent debugging
+    // toward "check the schema version" for a failure that was never about
+    // the schema at all.
+    "library_unreadable",
     "unsupported_schema",
     "query_timeout",
     "query_process_crashed",

package/dist/server.d.ts

@@ -4,9 +4,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * design (a permissions error on one candidate must not blank out every
  * other one). That means a hot journal on the *only* library on this
  * machine looks identical to no library existing at all -- both come back
- * as an empty list, verified: opening it raises "attempt to write a
- * readonly database", which readLibraryInfo currently folds into
- * unsupported_schema and then drops entirely.
+ * as an empty list, verified: readLibraryInfo (discovery.ts) does report a
+ * hot journal precisely, as library_needs_recovery, but discoverLibraries()
+ * still drops it along with every other unreadable candidate, by that same
+ * design.
  *
  * This walks the same candidate paths independently, purely to tell those
  * two cases apart, so `ready()` below can report library_needs_recovery

package/dist/server.js

@@ -1,5 +1,5 @@
 // src/server.ts
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -18,6 +18,21 @@ import { listLibraries } from "./tools/libraries.js";
 import { refreshIndex } from "./tools/refresh.js";
 import { err, isEngineError, libraryNeedsRecovery } from "./errors.js";
 const RO = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
+/**
+ * name/version reported to every client on initialize. Read from
+ * package.json rather than typed here, so the two cannot re-diverge the way
+ * they already have once (this constructor shipped 0.1.0 while package.json
+ * said 0.9.0).
+ *
+ * Resolved via import.meta.url, one directory up from this module, not by
+ * relative path from cwd: this runs under `npx` from an arbitrary working
+ * directory, and package.json sits next to dist/ (this module's compiled
+ * location) in both the repo (src/../package.json) and the installed
+ * layout (dist/../package.json) -- package.json is always included in the
+ * published tarball regardless of the "files" field, so this path exists
+ * in both places even though "files" lists only "dist".
+ */
+const PACKAGE_INFO = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 /**
  * Appended to every tool description that takes a `library`. The argument's
  * own schema description (see library-select.ts) is the authoritative text;
@@ -39,9 +54,10 @@ function reply(value) {
  * design (a permissions error on one candidate must not blank out every
  * other one). That means a hot journal on the *only* library on this
  * machine looks identical to no library existing at all -- both come back
- * as an empty list, verified: opening it raises "attempt to write a
- * readonly database", which readLibraryInfo currently folds into
- * unsupported_schema and then drops entirely.
+ * as an empty list, verified: readLibraryInfo (discovery.ts) does report a
+ * hot journal precisely, as library_needs_recovery, but discoverLibraries()
+ * still drops it along with every other unreadable candidate, by that same
+ * design.
  *
  * This walks the same candidate paths independently, purely to tell those
  * two cases apart, so `ready()` below can report library_needs_recovery
@@ -59,7 +75,7 @@ export function findHotJournalCandidate(roots) {
     return null;
 }
 export async function createServer(opts = {}) {
-    const server = new McpServer({ name: "engine-dj-mcp", version: "0.1.0" });
+    const server = new McpServer({ name: PACKAGE_INFO.name, version: PACKAGE_INFO.version });
     const libs = discoverLibraries(opts.roots);
     // Shared by every tool for the "no primary library" case, so refresh_index
     // cannot end up as the one call site that still flattens a hot journal
@@ -205,18 +221,30 @@ export async function createServer(opts = {}) {
      * null, not as "generation zero". A library nobody has queried yet has no
      * IndexManager at all and reports null for the same reason: listing the
      * libraries must not fork a query child per drive to fill in a number.
+     *
+     * Reads each known IndexManager's generation via peekGeneration(), not
+     * ensureFresh(): ensureFresh() also rebuilds when the library has
+     * changed, which is exactly right for a tool that is about to query the
+     * index and exactly wrong here. list_libraries is what a user reaches
+     * for when something looks broken, and list_libraries re-scans on every
+     * call (see below) -- so making it pay for a first, or renewed, index
+     * build on a big or currently-locked library would make the one
+     * diagnostic tool that must stay fast the one most likely to block.
+     * peekGeneration() only reads the sidecar already on disk, so this stays
+     * honest (a real, current generation number, never a fabricated one) and
+     * never forces work list_libraries does not itself need to answer.
      */
-    const libraryReport = async (discovered) => {
+    const libraryReport = (discovered) => {
         const generations = new Map();
         for (const state of states.values()) {
-            await state.mgr.ensureFresh(); // best effort: keeps a live library's generation accurate
-            if (state.mgr.generation > 0)
-                generations.set(state.lib.uuid, state.mgr.generation);
+            const generation = state.mgr.peekGeneration();
+            if (generation > 0)
+                generations.set(state.lib.uuid, generation);
         }
         return listLibraries(generations, discovered);
     };
     server.registerResource("schema", "engine://schema", { title: "Engine DJ schema and semantics", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, text: SCHEMA_NOTE }] }));
-    server.registerResource("libraries", "engine://libraries", { title: "Discovered Engine DJ libraries", mimeType: "application/json" }, async (uri) => ({ contents: [{ uri: uri.href, text: JSON.stringify(await libraryReport(libs), null, 2) }] }));
+    server.registerResource("libraries", "engine://libraries", { title: "Discovered Engine DJ libraries", mimeType: "application/json" }, async (uri) => ({ contents: [{ uri: uri.href, text: JSON.stringify(libraryReport(libs), null, 2) }] }));
     server.registerTool("search_tracks", {
         title: "Search tracks",
         description: "Search the Engine DJ library by text, tempo, key, rating, play history and analysis " +
@@ -320,7 +348,7 @@ export async function createServer(opts = {}) {
             "library; without it they use the supported library holding the most tracks.",
         inputSchema: {},
         annotations: RO,
-    }, async () => reply(await libraryReport(rescanLibraries())));
+    }, async () => reply(libraryReport(rescanLibraries())));
     server.registerTool("refresh_index", {
         title: "Refresh the search index",
         description: "Rebuild the search index if the library has changed. " + LIBRARY_SELECTION_NOTE,

package/dist/store/index-manager.d.ts

@@ -25,5 +25,17 @@ export declare class IndexManager {
     constructor(lib: LibraryInfo, qp: QueryProcess, baseDir?: string);
     get generation(): number;
     get path(): string;
+    /**
+     * The generation of whatever index currently exists on disk, read
+     * directly from the sidecar's own index_meta table -- never built,
+     * rebuilt or attached. This is the cheap half of ensureFresh() (the part
+     * that does not open the main library at all), used by list_libraries so
+     * that asking "what libraries do I have" is never the call that pays for
+     * a first (or renewed) index build: that cost belongs to whichever tool
+     * call actually needs a fresh index, through ensureFresh(). Returns 0,
+     * the same "not a real generation" value ensureFresh() reports before
+     * ever building one, when no usable sidecar exists yet.
+     */
+    peekGeneration(): number;
     ensureFresh(): Promise<FreshResult | EngineError>;
 }

package/dist/store/index-manager.js

@@ -33,6 +33,21 @@ export class IndexManager {
     get path() {
         return join(this.baseDir, this.lib.uuid, "index.db");
     }
+    /**
+     * The generation of whatever index currently exists on disk, read
+     * directly from the sidecar's own index_meta table -- never built,
+     * rebuilt or attached. This is the cheap half of ensureFresh() (the part
+     * that does not open the main library at all), used by list_libraries so
+     * that asking "what libraries do I have" is never the call that pays for
+     * a first (or renewed) index build: that cost belongs to whichever tool
+     * call actually needs a fresh index, through ensureFresh(). Returns 0,
+     * the same "not a real generation" value ensureFresh() reports before
+     * ever building one, when no usable sidecar exists yet.
+     */
+    peekGeneration() {
+        this.#storedCounter();
+        return this.#generation;
+    }
     /**
      * The change counter the sidecar on disk was built from, or null when
      * there is no usable sidecar — which forces a rebuild.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engine-dj-mcp",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Read-only MCP server for searching and auditing an Engine DJ library. Not affiliated with inMusic or Denon DJ.",
   "keywords": [
     "mcp",