engine-dj-mcp 0.9.2 → 0.11.0

package/dist/blobs/index.js

@@ -6,13 +6,15 @@
 // The layouts below were derived from, and checked against, a real Engine DJ
 // library: 257 analysed tracks on a USB export plus 24 in the local history
 // database, 281 blobs of each kind. What each check proved is recorded next
-// to the decoder it justifies. `loops` is the one field whose *contents*
-// could not be checked — see decodeLoops.
+// to the decoder it justifies. `loops` was the last field to be checked: its
+// contents needed a library with a loop actually saved in one, which arrived
+// later than the rest — see decodeLoops.
 //
 // Framing: `quickCues`, `beatData` and `overviewWaveFormData` are Qt
 // qCompress frames (4-byte big-endian uncompressed length, then a raw zlib
 // stream); the declared length matched the inflated length for all 281 of
-// each. `loops` is NOT compressed and NOT framed — it is 192 raw bytes, and
+// each. `loops` is NOT compressed and NOT framed — 192 raw bytes plus any
+// label text its slots carry, and
 // running it through the qCompress path reads its little-endian int64 count
 // of 8 as a big-endian length of 134217728 and hands zlib bytes it rejects.
 //
@@ -35,10 +37,12 @@ import { qUncompress, Reader, DecodeError } from "./qcompress.js";
  * sample count. `status: "ok"` on a verified field is a claim about the
  * values, not merely about the parse.
  *
- * `"unverified"` still means what it always did: the bytes parsed without
- * contradicting the layout, and nothing more. It survives on `loops` because
- * no track in the 281 examined has a loop set, so while the slot structure is
- * pinned down, the meaning of a *populated* slot is untested.
+ * `"unverified"` means the bytes parsed without contradicting the layout, and
+ * nothing more. No field carries it today: `loops` was the last one, and it
+ * held the marker only for as long as no library available had a loop saved in
+ * it. One saved loop supplied the missing prediction — see `decodeLoops` — and
+ * the marker is kept here because it is what a future field decoded from an
+ * unpopulated example would deserve.
  *
  * The marker is about the *bytes*: which offset holds which field, and what
  * the numbers there mean. It is not a claim about every English word this
@@ -252,23 +256,27 @@ export function hasCueSet(buf) {
  *                                                (23 bytes with an empty label)
  *
  * Evidence for the framing and the slot grid: 8 + 8×23 = 192, the size of
- * all 281 real blobs, every one of which parsed to exactly its last byte;
+ * every unpopulated real blob, each of which parsed to exactly its last byte;
  * the little-endian count reads as 8, and the little-endian -1.0 sentinel
  * (`000000000000f0bf`) appears at the offsets this layout predicts in all
  * 2248 slots. Reading the count big-endian gives 134217728, which is what
  * made every real track decode as `unsupported` before.
  *
- * This layout keeps `layout: "unverified"`. Not one of the 2248 slots is
- * populated — this library has no saved loops — so while the slot grid is
- * pinned down by 2248 sentinels, the six bytes after each slot's two doubles
- * are zero everywhere, and nothing here distinguishes start/end from
- * end/start, or fixes the order of the flag and colour bytes. A populated
- * loop is the one thing the available data cannot exercise, so it is not
- * claimed as verified.
+ * The sentinels pin the slot grid, but an empty slot cannot say which double
+ * is the start, what unit the doubles are in, or what the six trailing bytes
+ * mean — so this layout carried `unverified` for as long as no library had a
+ * saved loop in it. The `saved-loop` golden fixture is that loop, and it
+ * settles all three at once. Its slot reads label "Loop 1", start 2129416.08
+ * and end 2203430.06, which at the 44100 Hz `beatData` declares for the track
+ * is 1.678321678 s — exactly four beats at the 143 BPM Engine analysed, to
+ * 3.6e-15 s. Nothing but the right field order, the right unit and the right
+ * endianness lands on a whole number of beats, so the layout is verified.
+ * The trailing bytes read `01 01` (start set, end set) and four colour bytes,
+ * which is the same tail `quickCues` slots carry.
  */
 export function decodeLoops(buf, sampleRate) {
     const rate = usableRate(sampleRate);
-    return guard(buf, LAYOUT_UNVERIFIED, "raw", (r) => {
+    return guard(buf, LAYOUT_VERIFIED, "raw", (r) => {
         const slots = boundedCount(r, true, MAX_ITEMS, `loop slot count`);
         const items = [];
         for (let i = 0; i < slots; i++) {

package/dist/discovery.js

@@ -12,8 +12,9 @@ export function readLibraryInfo(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,
+        // recovering a hot journal needs a write, and discovery never opens a
+        // library writably -- not to probe one, and not to heal one. 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 --

package/dist/errors.d.ts

@@ -1,10 +1,29 @@
-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 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", "playlist_exists", "unknown_track", "duplicate_track"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export interface EngineError {
     error: ErrorCode;
     message: string;
+    /**
+     * Free text almost everywhere (store/index-manager.ts passes a raw
+     * `e.message` through it), with one exception that is part of the tool
+     * contract: on an error from the write path (store/write.ts) this is
+     * always exactly `"not_committed"` -- the library is byte-for-byte what it
+     * was -- or `"committed_unverified"` -- the write may have landed and could
+     * not be confirmed, and `backup_path` below is then set. Those two strings
+     * are reserved on that path and must stay stable, because a client reads
+     * them to decide whether their library changed.
+     */
     detail?: string;
     retry_after_ms?: number;
+    /**
+     * Path to a pre-write snapshot the caller can restore from. Only ever set
+     * by the write path, and only on the errors a client cannot safely ignore:
+     * `detail === "committed_unverified"`. It is a whole-database snapshot, so
+     * restoring it is a recovery route for a damaged library and not an undo
+     * of one playlist -- it reverts everything Engine DJ wrote since it was
+     * taken.
+     */
+    backup_path?: string;
 }
 export declare function err(error: ErrorCode, message: string, extra?: Omit<EngineError, "error" | "message">): EngineError;
 /**

package/dist/errors.js

@@ -19,6 +19,14 @@ export const ERROR_CODES = [
     "decode_failed",
     "invalid_argument",
     "library_needs_recovery",
+    // Write-path codes. There is no writes_not_enabled code: the tool is not
+    // registered at all without --allow-writes, and the MCP SDK's own
+    // dispatcher rejects a call to an unregistered tool name before any
+    // handler in this project runs, so this project never gets the chance to
+    // report that condition itself.
+    "playlist_exists",
+    "unknown_track",
+    "duplicate_track",
 ];
 export function err(error, message, extra = {}) {
     return { error, message, ...extra };

package/dist/index.js

@@ -3,11 +3,17 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
 async function main() {
-    const server = await createServer();
+    // MCP clients configure a server as a command plus an args array, so a flag
+    // is visible in that configuration and greppable; an environment variable
+    // would not be. Writes are off unless this is present.
+    const allowWrites = process.argv.includes("--allow-writes");
+    // stderr is not the protocol channel, so this is safe for stdio transport,
+    // and it puts the mode in the client's log where a user can check it.
+    console.error(`engine-dj-mcp: writes ${allowWrites ? "ENABLED (--allow-writes)" : "disabled"}`);
+    const server = await createServer({ allowWrites });
     await server.connect(new StdioServerTransport());
 }
 main().catch((e) => {
-    // stderr is not the protocol channel, so this is safe for stdio transport.
     console.error("engine-dj-mcp failed to start:", e);
     process.exit(1);
 });

package/dist/paths.d.ts

@@ -1,4 +1,15 @@
 export declare function sidecarDir(uuid: string): string;
+/**
+ * A short, stable tag for one library *file*, for use wherever a uuid alone
+ * would collide. A library copied onto a second drive carries the original's
+ * uuid -- an ordinary thing for a DJ to do -- so uuid is not unique across
+ * mounted volumes while the path of `m.db` always is.
+ *
+ * Shared by the sidecar layout (server.ts's sidecarBaseFor) and the backup
+ * filenames (store/backup.ts) so the two cannot drift into different ideas
+ * of which library they are talking about.
+ */
+export declare function libraryTag(mdbPath: string): string;
 /** Engine stores Track.path relative to the `Engine Library` folder, usually with `..`. */
 export declare function absTrackPath(mdbPath: string, relative: string): string;
 /** Candidate locations of `m.db` beneath a filesystem root. */

package/dist/paths.js

@@ -1,8 +1,22 @@
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 export function sidecarDir(uuid) {
     return join(homedir(), ".engine-dj-mcp", uuid);
 }
+/**
+ * A short, stable tag for one library *file*, for use wherever a uuid alone
+ * would collide. A library copied onto a second drive carries the original's
+ * uuid -- an ordinary thing for a DJ to do -- so uuid is not unique across
+ * mounted volumes while the path of `m.db` always is.
+ *
+ * Shared by the sidecar layout (server.ts's sidecarBaseFor) and the backup
+ * filenames (store/backup.ts) so the two cannot drift into different ideas
+ * of which library they are talking about.
+ */
+export function libraryTag(mdbPath) {
+    return createHash("sha256").update(mdbPath).digest("hex").slice(0, 12);
+}
 /** Engine stores Track.path relative to the `Engine Library` folder, usually with `..`. */
 export function absTrackPath(mdbPath, relative) {
     const engineLibrary = dirname(dirname(mdbPath)); // .../Engine Library/Database2/m.db

package/dist/playlists.d.ts

@@ -0,0 +1,240 @@
+import { type EngineError } from "./errors.js";
+import type { QueryProcess } from "./proc/query-client.js";
+/**
+ * Engine stores both playlist order and playlist-entry order as singly
+ * linked lists, not as a position column:
+ *
+ *   Playlist.nextListId       — the next sibling under the same parentListId
+ *   PlaylistEntity.nextEntityId — the next entry in the same listId
+ *
+ * Both terminate at 0.
+ *
+ * The schema also ships a `PlaylistPath` view carrying a column literally
+ * called `position`, which is the obvious thing to reach for and is wrong.
+ * Its `OrderedList` CTE anchors on `WHERE nextListId = 0` and counts
+ * *upwards from the tail*, then orders by that count ascending — so its
+ * `position` runs backwards. Measured on the reference library (16
+ * playlists): walking the chain yields
+ *   ACID Beach, KatyaBar, Electro 1, Old Fasion 1A 120-130, Playlist, ...
+ * which is what Engine DJ shows in its sidebar, while the view's position
+ * order is that list exactly reversed (asserted in tests/playlists.test.ts
+ * against the same shape). The chain is the source of truth; the view is
+ * never read by this project.
+ *
+ * Everything here therefore walks the chain — defensively. These are linked
+ * lists inside a file this server does not own and never writes: a
+ * half-completed Engine write, a sync conflict or a partially restored
+ * backup can leave a cycle, a link to a row that is gone, or two
+ * disconnected runs. None of those may hang the walk, and none may come
+ * back as a silently short list that reads like a complete one.
+ */
+/**
+ * The predicate that connects one `PlaylistEntity` (`e`) to its `Track` (`t`).
+ *
+ * A playlist entry does not name a local row id. It carries
+ * `(databaseUuid, trackId)`, which identifies the track **in the library the
+ * entry was made in**, and `Track` preserves that same identity in
+ * `(originDatabaseUuid, originTrackId)` — a pair that need not equal, and
+ * usually does not equal, `Track.id`. Engine's own schema says as much: the
+ * pair carries `CONSTRAINT C_originDatabaseUuid_originTrackId UNIQUE`, making
+ * it the track's natural key across drives, and a pair of triggers
+ * (`trigger_after_insert_Track_fix_origin` and its update twin) stamps it
+ * from `Information.uuid` whenever a row arrives without one. Engine's
+ * application binary embeds the same join verbatim:
+ *
+ *   SELECT COUNT(DISTINCT databaseUuid || trackId) FROM PlaylistEntity
+ *   JOIN Track ON (originDatabaseUuid, originTrackId) = (databaseUuid, trackId)
+ *
+ * Joining on `e.trackId = t.id` instead reads naturally and is wrong in both
+ * directions. Measured on the reference USB library (257 tracks, 16
+ * playlists, 202 entries): the id join reports 105 of 202 entries as orphans
+ * where the pair join finds 0, because 178 entries name a *third* library
+ * (`33be3313-…`) that is neither of the two attached and only 91 of the 257
+ * tracks carry this database's own uuid — a healthy library reported as
+ * riddled with holes, and one 43-entry playlist reduced to a single playable
+ * track. In the other direction it silently answers with the *wrong track*
+ * whenever a foreign entry's `trackId` happens to collide with a local row
+ * id, and calls a genuinely missing entry present.
+ *
+ * Written once and shared, so the three places that ask the question cannot
+ * drift apart. It names the aliases `t` and `e`; every call site uses them.
+ */
+export declare const ENTRY_TRACK_MATCH = "t.originDatabaseUuid = e.databaseUuid AND t.originTrackId = e.trackId";
+/** One node of an Engine linked list. `next` is 0 at the end of the chain. */
+export interface Linked {
+    id: number;
+    next: number;
+}
+export interface ChainOrder<T> {
+    order: T[];
+    warnings: string[];
+}
+/**
+ * Orders one linked-list group, and says so when it could not.
+ *
+ * The contract that matters: `order` always contains **every** input node,
+ * exactly once. A chain defect degrades the *order* and raises a warning; it
+ * never drops a node, because a caller cannot tell a truncated list from a
+ * short one, and `get_playlist_tracks` returning 30 of 43 entries with no
+ * complaint is a worse answer than returning 43 in a partly-guessed order
+ * with an explanation attached.
+ *
+ * Walk termination does not rely on a magic iteration cap: every step either
+ * marks one previously unseen node visited or stops, so the walk is bounded
+ * by the group size by construction. Anything the walk could not reach is
+ * appended in id order.
+ *
+ * `subject` prefixes the warnings, so a caller reading a whole tree can tell
+ * which playlist was malformed.
+ */
+export declare function orderByChain<T extends Linked>(nodes: readonly T[], subject: string): ChainOrder<T>;
+/** A `Playlist` row, as this module needs it. */
+export interface PlaylistRow extends Linked {
+    title: string;
+    parent: number;
+    isPersisted: boolean;
+    entryCount: number;
+    missingCount: number;
+}
+/**
+ * One playlist as reported to a caller.
+ *
+ * `is_folder` is derived, not stored: the schema has no folder flag, and
+ * Engine's own folders are simply `Playlist` rows that other `Playlist` rows
+ * name as their `parentListId`. So this means "has at least one child list",
+ * which is exactly what Engine draws as a folder -- with one honest
+ * consequence: a folder a DJ has emptied is indistinguishable from a
+ * playlist with no tracks, and is reported as the latter.
+ *
+ * `track_count` is entries in this list itself, never a total rolled up from
+ * children, so it matches the number Engine shows beside the playlist.
+ * `missing_count` is how many of those entries name a track that is not in
+ * this library -- see `get_playlist_tracks` for why that is routine rather
+ * than a corruption.
+ */
+export interface PlaylistItem {
+    id: number;
+    name: string;
+    /** Full path from the top of the tree, `/`-separated. Unique across the tree. */
+    path: string;
+    parent_id: number | null;
+    depth: number;
+    is_folder: boolean;
+    is_persisted: boolean;
+    track_count: number;
+    missing_count: number;
+}
+/**
+ * Flattens the playlist forest into Engine's own display order: each sibling
+ * group in `nextListId` chain order, each list immediately followed by its
+ * own children (pre-order), which is exactly what an expanded Engine sidebar
+ * shows top to bottom.
+ *
+ * Flat-plus-`depth`-plus-`path` rather than nested `children` arrays: the
+ * order Engine displays is then readable in a single pass down the array
+ * without reconstructing a traversal, the result truncates to a genuine
+ * prefix of the sidebar, and `path` gives every list a unique handle that a
+ * bare name does not (see `findPlaylistByName`).
+ */
+export declare function buildPlaylistTree(rows: readonly PlaylistRow[]): {
+    items: PlaylistItem[];
+    warnings: string[];
+};
+export interface PlaylistTree {
+    items: PlaylistItem[];
+    warnings: string[];
+    /** Playlists in the library, even when more were found than were returned. */
+    total: number;
+    truncated: boolean;
+}
+/**
+ * Reads every playlist plus its entry counts, and orders the result.
+ *
+ * The counts come from one grouped pass over `PlaylistEntity` rather than a
+ * correlated subquery per playlist, and `missing_count` is computed in the
+ * same pass: "how many of these can I actually play" is not a rare question
+ * and must not cost a second round trip per list.
+ *
+ * `missing` is an EXISTS semi-join on the natural key (see
+ * ENTRY_TRACK_MATCH), not a LEFT JOIN to Track. Membership is the whole
+ * question, and a semi-join cannot inflate `n`: a joined row set would count
+ * one entry twice if two tracks ever answered to the same origin key, which
+ * Engine's UNIQUE constraint forbids but this server has no way to enforce
+ * on a file it does not own.
+ */
+export declare function loadPlaylistTree(qp: QueryProcess): Promise<PlaylistTree | EngineError>;
+/**
+ * Every list matching a caller-supplied name, most specific interpretation
+ * first.
+ *
+ * `Playlist` is unique on `(title, parentListId)` only, so a bare name is
+ * genuinely ambiguous the moment a DJ uses folders -- "House" under
+ * *Warmup* and "House" under *Peak* are two different playlists and neither
+ * is the obvious winner. A full path is unique by construction, so it is
+ * tried first and gives a caller a way to say precisely which one they mean;
+ * a bare title is tried next and may legitimately return several, which the
+ * caller turns into an error rather than an arbitrary pick.
+ *
+ * Case-insensitive matching is a fallback tier, not the primary rule: a
+ * library containing both "Peak" and "peak" as siblings is legal, and an
+ * exact match must win outright rather than being reported as ambiguous
+ * against its own differently-cased neighbour.
+ */
+export declare function findPlaylistByName(items: readonly PlaylistItem[], name: string): PlaylistItem[];
+export interface PlaylistSelector {
+    id?: number;
+    name?: string;
+}
+/** The argument names to quote back in an error, so each tool blames its own. */
+export interface SelectorNames {
+    id: string;
+    name: string;
+}
+export interface ResolvedPlaylist {
+    playlist: PlaylistItem;
+    /** Chain warnings raised while building the tree this playlist came from. */
+    warnings: string[];
+}
+/**
+ * Turns "id or name" into one specific playlist, or an actionable error.
+ *
+ * Ambiguity is never resolved by picking: two playlists really can share a
+ * name, and quietly answering about the wrong one is the failure mode this
+ * whole function exists to prevent. The error names every candidate with its
+ * id and its full path, so the retry is a copy-paste rather than a guess.
+ *
+ * Deliberately reuses `invalid_argument` rather than adding an error code:
+ * the taxonomy is closed (see errors.ts), and "the playlist you named is not
+ * in this library" is a problem with the argument, reported the same way an
+ * unknown field name is -- with the recognised values in `detail`.
+ */
+export declare function resolvePlaylist(qp: QueryProcess, sel: PlaylistSelector, names?: SelectorNames): Promise<ResolvedPlaylist | EngineError>;
+/** One entry of a playlist, in playlist order. */
+export interface OrderedEntry extends Linked {
+    /**
+     * `PlaylistEntity.trackId` — the track's `originTrackId` in the library
+     * `databaseUuid` names, **not** a local `Track.id`. The two halves only
+     * mean anything together (see ENTRY_TRACK_MATCH), and together they need
+     * not name a track this library holds.
+     */
+    trackId: number;
+    /** The library this entry was made in. Null only in a malformed row. */
+    databaseUuid: string | null;
+    /** 1-based position within the playlist. */
+    position: number;
+}
+export interface PlaylistEntries {
+    entries: OrderedEntry[];
+    warnings: string[];
+}
+/**
+ * Every entry of one playlist, in `nextEntityId` chain order.
+ *
+ * The whole playlist is read before a page is cut from it, because position
+ * *is* the ordering: there is no indexed column to seek on, so a page can
+ * only be taken from an already-ordered list. That is affordable -- the
+ * reference library's largest playlist is 43 entries and `PlaylistEntity` is
+ * three integers wide -- and it is bounded by MAX_ENTRIES rather than by
+ * hope.
+ */
+export declare function loadPlaylistEntries(qp: QueryProcess, playlist: PlaylistItem): Promise<PlaylistEntries | EngineError>;