engine-dj-mcp 0.9.2 → 0.11.0

package/dist/server.js

@@ -1,23 +1,26 @@
 // src/server.ts
 import { existsSync, readFileSync } from "node:fs";
-import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { discoverLibraries, defaultRoots, probeLibraries } from "./discovery.js";
-import { libraryCandidates, sidecarDir } from "./paths.js";
+import { libraryCandidates, libraryTag, sidecarDir } from "./paths.js";
 import { LibraryArg, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
 import { hasHotJournal } from "./store/connections.js";
 import { QueryProcess } from "./proc/query-client.js";
 import { IndexManager } from "./store/index-manager.js";
 import { searchTracks, SearchInput } from "./tools/search.js";
 import { getTracks, GetTracksInput } from "./tools/tracks.js";
+import { getPlaylists, GetPlaylistsInput, getPlaylistTracks, GetPlaylistTracksInput, } from "./tools/playlists.js";
 import { getTrackPerformance, PerformanceInput } from "./tools/performance.js";
 import { auditLibrary, AuditInput, AUDIT_CHECKS } from "./tools/audit.js";
 import { runSql, RunSqlInput } from "./tools/sql.js";
 import { listLibraries } from "./tools/libraries.js";
 import { refreshIndex } from "./tools/refresh.js";
+import { CreatePlaylistInput, runCreatePlaylist } from "./tools/write-playlist.js";
 import { err, isEngineError, libraryNeedsRecovery } from "./errors.js";
 const RO = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
+const RW = { readOnlyHint: false, destructiveHint: false, idempotentHint: false };
 /**
  * name/version reported to every client on initialize. Read from
  * package.json rather than typed here, so the two cannot re-diverge the way
@@ -62,8 +65,10 @@ function reply(value) {
  * This walks the same candidate paths independently, purely to tell those
  * two cases apart, so `ready()` below can report library_needs_recovery
  * instead of the misleading library_not_found -- never to open the file:
- * recovering a hot journal requires a write, and this project never writes
- * to the user's library, even to heal it.
+ * recovering a hot journal requires a write, and nothing here opens a
+ * library writably to heal one. Not even create_playlist, which refuses a
+ * library in this state outright (store/write.ts) rather than letting
+ * SQLite roll the journal forward on its way in.
  */
 export function findHotJournalCandidate(roots) {
     for (const root of roots) {
@@ -151,8 +156,7 @@ export async function createServer(opts = {}) {
         const first = knownList().find((l) => l.uuid === lib.uuid);
         if (!first || first.path === lib.path)
             return opts.sidecarBaseDir;
-        const tag = createHash("sha256").update(lib.path).digest("hex").slice(0, 12);
-        return join(opts.sidecarBaseDir ?? sidecarDir(""), "duplicate-uuid", tag);
+        return join(opts.sidecarBaseDir ?? sidecarDir(""), "duplicate-uuid", libraryTag(lib.path));
     };
     /** Lazily creates -- and thereafter reuses -- one query child per library. */
     const stateFor = (lib) => {
@@ -254,6 +258,8 @@ export async function createServer(opts = {}) {
             "flags.has_cues means a hot cue is actually set (the blob is decoded when the index " +
             "is built), not merely that Engine analysed the track; flags.has_beatgrid means a " +
             "beatData blob is present. " +
+            "playlist: {id} or {name} narrows the search to one playlist -- results still come " +
+            "back by relevance or id, not in playlist order; use get_playlist_tracks for that. " +
             LIBRARY_SELECTION_NOTE,
         inputSchema: { ...SearchInput.shape, library: LibraryArg },
         annotations: RO,
@@ -275,19 +281,64 @@ export async function createServer(opts = {}) {
             return reply(state);
         return reply(await getTracks(state.qp, args));
     });
+    server.registerTool("get_playlists", {
+        title: "List playlists",
+        description: "The library's playlist tree, in the order Engine DJ displays it -- taken from the " +
+            "Playlist.nextListId chain, which is where that order actually lives (the PlaylistPath " +
+            "view's `position` column runs the other way). " +
+            "Flat and in pre-order, so reading top to bottom is exactly the sidebar: `depth` and " +
+            "`path` carry the nesting, `parent_id` names the folder. " +
+            "is_folder means the list has child lists (Engine has no folder flag; a folder is a " +
+            "playlist other playlists sit under), so an emptied folder reads as an empty playlist. " +
+            "track_count is entries in that list alone, never rolled up from children, and " +
+            "missing_count is how many of them name a track that is not in this library. " +
+            "`warnings` appears when a link chain is broken or cyclic; nothing is ever dropped " +
+            "from the list because of one. " +
+            LIBRARY_SELECTION_NOTE,
+        inputSchema: { ...GetPlaylistsInput.shape, library: LibraryArg },
+        annotations: RO,
+    }, async (args) => {
+        const state = await acquire(args.library);
+        if (isEngineError(state))
+            return reply(state);
+        return reply(await getPlaylists(state.qp, args));
+    });
+    server.registerTool("get_playlist_tracks", {
+        title: "Get the tracks in a playlist",
+        description: "The tracks of one playlist, in playlist order -- from the PlaylistEntity.nextEntityId " +
+            "chain, not from row ids, so a track dragged up the list comes back where the DJ put it. " +
+            "Name the playlist with playlist_id, or with playlist_name (exactly one of the two). A " +
+            "name that matches several playlists is refused with every candidate's id and full path " +
+            "rather than picked between -- names are unique only within a folder, so pass the full " +
+            "`path` from get_playlists to disambiguate. " +
+            "Each row carries `position`, its 1-based place in the playlist. An entry whose track is " +
+            "not in this library comes back as { position, entry_id, track_id, missing: true } and " +
+            "keeps its slot, so entry_count still matches the playlist's own length; missing_count " +
+            "says how many of those there are. That is ordinary, not corruption -- entries outlive " +
+            "their tracks and arrive from other drives (see audit_library's orphan_entries). " +
+            "Same fields, limit and cursor conventions as search_tracks. " +
+            LIBRARY_SELECTION_NOTE,
+        inputSchema: { ...GetPlaylistTracksInput.shape, library: LibraryArg },
+        annotations: RO,
+    }, async (args) => {
+        const state = await acquire(args.library);
+        if (isEngineError(state))
+            return reply(state);
+        return reply(await getPlaylistTracks(state.qp, args));
+    });
     server.registerTool("get_track_performance", {
         title: "Get cues, loops and beatgrid",
         description: "Decode PerformanceData for one track: hot cues, the main cue, saved loops, the " +
             "beatgrid and a coarse waveform profile. Each field carries its own decode status " +
             "and its own layout marker. " +
-            "layout: \"verified\" (cues, beatgrid, waveform_summary) means the binary layout was " +
+            "layout: \"verified\" (every field) means the binary layout was " +
             "confirmed against a real Engine DJ library -- cue positions land inside the track, " +
-            "the beatgrid's implied tempo matches the analysed BPM, and the waveform's declared " +
-            "point spacing multiplies back out to the track's sample count -- so status: \"ok\" " +
-            "there is a claim about the values, not just about the parse. " +
-            "layout: \"unverified\" (loops) still means only that the bytes parsed: the loop slot " +
-            "structure is known, but no library was available with a loop actually saved, so " +
-            "loop bounds must not be reported to a user as fact. " +
+            "the beatgrid's implied tempo matches the analysed BPM, the waveform's declared " +
+            "point spacing multiplies back out to the track's sample count, and a saved loop " +
+            "spans a whole number of beats at that same analysed BPM -- so status: \"ok\" " +
+            "is a claim about the values, not just about the parse. " +
+            "layout: \"unverified\" would mean only that the bytes parsed; no field returns it " +
+            "today. " +
             "Positions are sample offsets; sample_rate at the top level converts them to " +
             "seconds, and cue/loop items carry the seconds already. Only hot-cue and loop slots " +
             "that hold something are listed -- slots is how many the track has in total, so " +
@@ -362,6 +413,40 @@ export async function createServer(opts = {}) {
             return reply(lib);
         return reply(await refreshIndex(stateFor(lib).mgr));
     });
+    // Registered only under --allow-writes. A client that never enables it sees
+    // exactly the read-only server it saw before this feature existed, which is
+    // what keeps the README's promise true by default.
+    if (opts.allowWrites) {
+        server.registerTool("create_playlist", {
+            title: "Create a playlist",
+            description: "Create a new playlist in this Engine DJ library from track ids returned by " +
+                "search_tracks or get_tracks -- track_ids sets both membership and order. " +
+                "Unlike every other tool here, this WRITES to the library, so do not call it " +
+                "speculatively: only call it once you actually intend to add the playlist. " +
+                "To undo it, delete the playlist in Engine DJ -- Engine's own delete trigger and " +
+                "cascade remove the playlist and its entries cleanly. " +
+                "backup_path in the result names a whole-database snapshot taken before the first " +
+                "write of this session; it is a recovery route for a damaged library, NOT an undo. " +
+                "Restoring it reverts the entire library to that moment, discarding everything " +
+                "Engine DJ has written since (play counts, imports, cue and beatgrid edits). " +
+                "No existing playlist or entry is ever modified; this only adds a new one. " +
+                "Fails with playlist_exists if a top-level playlist already has that title, and " +
+                "with library_busy if Engine DJ or a player is holding a conflicting lock on the " +
+                "library right then -- nothing is written in that case, so retry rather than " +
+                "treating it as permanent. On any error, `detail` is \"not_committed\" when the " +
+                "library is unchanged and \"committed_unverified\" when the write may have gone " +
+                "through but could not be verified. track_ids may be empty (an empty playlist); a " +
+                "track id may appear at most once. " +
+                LIBRARY_SELECTION_NOTE,
+            inputSchema: { ...CreatePlaylistInput.shape, library: LibraryArg },
+            annotations: RW,
+        }, async (args) => {
+            const state = await acquire(args.library);
+            if (isEngineError(state))
+                return reply(state);
+            return reply(await runCreatePlaylist(state.lib.path, state.lib.uuid, args, join(homedir(), ".engine-dj-mcp", "backups")));
+        });
+    }
     /**
      * There was previously no way to shut this down at all: createServer
      * forked a query child and handed back an McpServer whose close() knows
@@ -400,9 +485,11 @@ Tables live in \`m.db\` (attached as \`main\`); the search index lives in \`side
 More than one library can be connected at once — the local one under
 \`~/Music\` and one per USB drive. \`list_libraries\` reports each with a
 \`uuid\` and a \`path\`, and every tool that reads library data
-(\`search_tracks\`, \`get_tracks\`, \`get_track_performance\`,
-\`audit_library\`, \`run_sql\`, \`refresh_index\`) takes an optional
-\`library\` argument naming one of them: either the \`uuid\` or the
+(\`search_tracks\`, \`get_tracks\`, \`get_playlists\`,
+\`get_playlist_tracks\`, \`get_track_performance\`, \`audit_library\`,
+\`run_sql\`, \`refresh_index\`) takes an optional
+\`library\` argument naming one of them — as does \`create_playlist\`, when
+the server was started with \`--allow-writes\` — either the \`uuid\` or the
 \`path\`, in the \`~/...\` form \`list_libraries\` prints or the absolute
 one. A value matching neither comes back as \`library_not_found\` listing
 the libraries that are selectable.
@@ -430,8 +517,6 @@ other.
 - \`Track.path\` is relative to the \`Engine Library\` folder and usually
   contains \`..\`. The SQL function \`abs_path(path)\` resolves it against
   this library's location; the home prefix comes back folded to \`~\`.
-- Playlists are singly linked lists: order lives in \`Playlist.nextListId\`
-  and \`PlaylistEntity.nextEntityId\`, not in any position column.
 - A track's natural key across drives is \`(originDatabaseUuid, originTrackId)\`.
 - \`PerformanceData\`'s blob columns are binary and cannot be read with SQL.
   Engine writes \`quickCues\`, \`loops\`, \`beatData\` and
@@ -441,6 +526,41 @@ other.
   \`get_track_performance\` decodes one track's blobs; for the whole library,
   \`side.track_derived.has_cues\` below holds the decoded answer.
 
+## Playlists
+Order is a **singly linked list**, in both directions of the structure, and
+there is no position column anywhere:
+- \`Playlist.nextListId\` orders sibling lists within one \`parentListId\`.
+- \`PlaylistEntity.nextEntityId\` orders the entries within one \`listId\`.
+Both chains terminate at \`0\`.
+
+The schema ships a \`PlaylistPath\` view with a column named \`position\`.
+**Do not use it for display order.** Its \`OrderedList\` CTE anchors on
+\`WHERE nextListId = 0\` and counts upwards from the *tail*, so ordering by
+it yields the sidebar reversed — measured on a real library of 16 playlists,
+\`PlaylistPath\` order is exactly the reverse of the chain, and the chain is
+what Engine DJ draws. \`get_playlists\` and \`get_playlist_tracks\` walk the
+chains; write the same recursive walk if you go via \`run_sql\`, and never
+\`ORDER BY id\` — ids happen to agree with the chain until the first time
+someone drags a track up a playlist.
+
+Nesting is \`Playlist.parentListId\` (\`0\` at the top level). There is no
+folder flag: an Engine folder is just a \`Playlist\` row that other rows
+name as their parent. \`Playlist.isPersisted\` marks a list saved to the
+device rather than a transient one; both values occur on lists Engine
+displays, so nothing is filtered on it. Titles are unique only within a
+parent (\`UNIQUE (title, parentListId)\`), so a bare name can match several
+playlists — the full \`path\` \`get_playlists\` reports is unique.
+
+\`PlaylistEntity.trackId\` may name a track that is not in this library:
+entries outlive their tracks and travel between drives (\`databaseUuid\`
+records which library an entry came from). On the reference library 105 of
+202 entries are such holes. \`audit_library\`'s \`orphan_entries\` counts
+them; \`get_playlist_tracks\` keeps them in place, flagged \`missing\`.
+
+Rule-based **smartlists** live in a separate \`Smartlist\` table, keyed by
+uuid with its own \`nextListUuid\` ordering and a JSON \`rules\` column.
+Nothing here reads it — a smartlist is not reported by \`get_playlists\`.
+
 ## SQL functions
 Registered on the query connection, all deterministic:
 \`camelot(key)\`, \`key_name(key)\`, \`tempo(bpmAnalyzed, bpm)\`,

package/dist/store/backup.d.ts

@@ -0,0 +1,2 @@
+import { type EngineError } from "../errors.js";
+export declare function snapshotLibrary(mdbPath: string, uuid: string, baseDir: string): Promise<string | EngineError>;

package/dist/store/backup.js

@@ -0,0 +1,72 @@
+// src/store/backup.ts
+//
+// A snapshot taken before the first write of a session, so a user who does
+// not like the result has a known way back. It is taken through SQLite's own
+// backup API rather than a file copy: that is correct even while Engine DJ
+// holds the database open, which a cp is not.
+//
+// Snapshots live under ~/.engine-dj-mcp/backups/ and never inside the user's
+// Engine Library folder -- the rule that no file is created there holds for
+// writes exactly as it did for reads.
+import { DatabaseSync, backup } from "node:sqlite";
+import { mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { err } from "../errors.js";
+import { libraryTag } from "../paths.js";
+/** How many snapshots to keep per library before deleting the oldest. */
+const KEEP = 10;
+/**
+ * Monotonic counter to ensure unique, sortable filenames even in tight loops.
+ * The ISO string alone provides only millisecond precision, so rapid-fire calls
+ * in the same millisecond would collide. The counter serves as an infallible
+ * tiebreaker: calls within the same millisecond are ordered by counter value,
+ * and calls across milliseconds are already separated by the ISO string. This
+ * ordering is essential: rotation immediately deletes the text-sorted oldest,
+ * so an inverted sort would delete the snapshot we just handed back.
+ */
+let counter = 0;
+/**
+ * A filename-safe, sortable stamp. Sorting the directory listing as text
+ * therefore orders snapshots by age, which is what rotation relies on.
+ */
+function stamp() {
+    const iso = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${iso}-${String(++counter).padStart(10, "0")}`;
+}
+export async function snapshotLibrary(mdbPath, uuid, baseDir) {
+    let src;
+    try {
+        mkdirSync(baseDir, { recursive: true });
+        src = new DatabaseSync(mdbPath, { readOnly: true });
+        // uuid *and* a hash of the file's own path. Keyed on uuid alone, a
+        // library and its clone on a second drive -- same uuid, different drive,
+        // an ordinary thing for a DJ to have -- shared one namespace and one
+        // KEEP-slot window: writes to either evicted the other's snapshots, and
+        // a returned backup_path did not say which drive it came from. This is
+        // the same tag server.ts's sidecarBaseFor uses to keep two such
+        // libraries' indexes apart (see paths.ts).
+        const prefix = `${uuid}-${libraryTag(mdbPath)}-`;
+        const dest = join(baseDir, `${prefix}${stamp()}.db`);
+        await backup(src, dest);
+        src.close();
+        src = undefined;
+        const mine = readdirSync(baseDir)
+            .filter((f) => f.startsWith(prefix) && f.endsWith(".db"))
+            .sort();
+        for (const old of mine.slice(0, Math.max(0, mine.length - KEEP))) {
+            rmSync(join(baseDir, old), { force: true });
+        }
+        return dest;
+    }
+    catch (e) {
+        return err("library_unreadable", `Could not snapshot ${mdbPath} before writing: ${String(e)}`);
+    }
+    finally {
+        try {
+            src?.close();
+        }
+        catch {
+            /* already closed */
+        }
+    }
+}

package/dist/store/write.d.ts

@@ -0,0 +1,37 @@
+import { DatabaseSync } from "node:sqlite";
+import { type EngineError } from "../errors.js";
+export interface CreatePlaylistResult {
+    playlist_id: number;
+    title: string;
+    tracks_added: number;
+    backup_path: string;
+}
+export interface OriginRef {
+    uuid: string;
+    trackId: number;
+}
+/** Test seam only: forget this process's snapshots so a test can start clean. */
+export declare function resetSessionSnapshots(): void;
+/**
+ * Read the chain back starting from a row we know is the head, because we
+ * inserted it first. Re-deriving the head as "the row nothing points at"
+ * would be the same assumption the write just made, so it could not catch a
+ * write that made it wrongly.
+ *
+ * This, together with `sameOrder`, confirms that the *links* survived the
+ * round trip in the order given -- it does not independently confirm the
+ * *values* are correct. The comparison target is `refs`, the same array
+ * `resolveOrigins` produced and the write consumed, so a `resolveOrigins`
+ * that resolved every id wrongly (e.g. to the local row id instead of the
+ * origin pair) would write wrong values, read the same wrong values back,
+ * and pass this check. Catching that class of bug is what the
+ * re-originated-track test is for, not this readback.
+ */
+export declare function walkFrom(db: DatabaseSync, listId: number, headId: number): OriginRef[];
+export declare function sameOrder(a: OriginRef[], b: OriginRef[]): boolean;
+export declare function createPlaylist(mdbPath: string, uuid: string, input: {
+    title: string;
+    trackIds: number[];
+}, opts: {
+    backupDir: string;
+}): Promise<CreatePlaylistResult | EngineError>;