engine-dj-mcp 0.15.0 → 0.17.1

package/dist/store/track-metadata.js

@@ -0,0 +1,143 @@
+// src/store/track-metadata.ts
+//
+// update_track_metadata against a real library. The decisions live in
+// track-metadata-plan.ts; this module reads rows, applies a plan and verifies
+// it. Order (spec §6): hot journal, input rules, read-only pre-check, then --
+// only if something would change -- the shared write transaction, where every
+// row is read and planned AGAIN under the lock and that second reading decides.
+import { DatabaseSync } from "node:sqlite";
+import { err, isEngineError, libraryNeedsRecovery } from "../errors.js";
+import { redactPath } from "../paths.js";
+import { hasHotJournal } from "./connections.js";
+import { NOT_COMMITTED, mapWriteError, rollback, withWriteTransaction, } from "./write.js";
+import { planUpdates, sameStored, validateUpdates, TEXT_FIELDS, } from "./track-metadata-plan.js";
+const MAX_SAFE = Number.MAX_SAFE_INTEGER;
+/**
+ * Types and ranges are settled in SQL, before a value reaches JS: node:sqlite
+ * throws on an INTEGER beyond 2^53, and a REAL rating or a TEXT year is not a
+ * value this tool could put back. Such a column comes back null and is listed
+ * in `inexpressible`. The empty-origin test is the fix-origin trigger's own
+ * WHEN, evaluated by SQLite, so it agrees with the trigger on TEXT '' (spec §3.3).
+ */
+const READ_ROW = `SELECT id,
+  CASE WHEN typeof(genre) = 'text' THEN genre END AS genre, typeof(genre) AS genre_t,
+  CASE WHEN typeof(comment) = 'text' THEN comment END AS comment, typeof(comment) AS comment_t,
+  CASE WHEN typeof(label) = 'text' THEN label END AS label, typeof(label) AS label_t,
+  CASE WHEN typeof(year) = 'integer' AND year BETWEEN -${MAX_SAFE} AND ${MAX_SAFE} THEN year END AS year,
+  (typeof(year) = 'null' OR (typeof(year) = 'integer' AND year BETWEEN -${MAX_SAFE} AND ${MAX_SAFE})) AS year_ok,
+  CASE WHEN typeof(rating) = 'integer' AND rating BETWEEN 0 AND 255 THEN rating END AS rating,
+  (typeof(rating) = 'null' OR (typeof(rating) = 'integer' AND rating BETWEEN 0 AND 255)) AS rating_ok,
+  (IFNULL(originTrackId, 0) = 0 OR IFNULL(originDatabaseUuid, '') = '') AS origin_empty,
+  CAST(originDatabaseUuid AS TEXT) || '|' || CAST(originTrackId AS TEXT) AS origin
+  FROM Track WHERE id = ?`;
+function readRows(db, ids) {
+    const stmt = db.prepare(READ_ROW);
+    const out = new Map();
+    for (const id of ids) {
+        const r = stmt.get(id);
+        if (!r)
+            continue;
+        const inexpressible = [];
+        for (const f of TEXT_FIELDS) {
+            if (r[`${f}_t`] !== "text" && r[`${f}_t`] !== "null")
+                inexpressible.push(f);
+        }
+        if (!r.year_ok)
+            inexpressible.push("year");
+        if (!r.rating_ok)
+            inexpressible.push("rating");
+        out.set(id, {
+            id,
+            genre: r.genre,
+            comment: r.comment,
+            label: r.label,
+            year: r.year,
+            rating: r.rating,
+            inexpressible,
+            originEmpty: r.origin_empty === 1,
+            origin: r.origin,
+        });
+    }
+    return out;
+}
+export async function updateTrackMetadata(mdbPath, uuid, input, opts) {
+    const { updates } = input;
+    const ids = updates.map((u) => u.id);
+    const subject = `${updates.length} track${updates.length === 1 ? "" : "s"}`;
+    // First, before anything opens the file: see createPlaylist in write.ts.
+    if (hasHotJournal(mdbPath))
+        return { ...libraryNeedsRecovery(), detail: NOT_COMMITTED };
+    const invalid = validateUpdates(updates);
+    if (invalid)
+        return invalid;
+    // Not the authority -- the transaction re-plans. This only spares a
+    // snapshot for a call that is going to refuse anyway, or has nothing to do.
+    let pre;
+    let precheck;
+    try {
+        precheck = new DatabaseSync(mdbPath, { readOnly: true });
+        pre = planUpdates(updates, readRows(precheck, ids));
+    }
+    catch (e) {
+        return mapWriteError(e, subject, mdbPath);
+    }
+    finally {
+        try {
+            precheck?.close();
+        }
+        catch {
+            /* never opened */
+        }
+    }
+    if (isEngineError(pre))
+        return pre;
+    if (pre.writes.length === 0) {
+        // Spec §5.5: no transaction, no snapshot, so no backup_path -- and
+        // withWriteTransaction is not here to fill in `library`.
+        return {
+            updated: 0,
+            unchanged: pre.unchanged.length,
+            changed: [],
+            undo: [],
+            undo_complete: true,
+            library: { uuid, path: redactPath(mdbPath) },
+        };
+    }
+    return withWriteTransaction(mdbPath, uuid, subject, opts, (db) => {
+        // Under BEGIN IMMEDIATE. Engine may have changed any of these rows while
+        // the snapshot was being copied; what is read here decides (spec §6.5).
+        const rows = readRows(db, ids);
+        const plan = planUpdates(updates, rows);
+        if (isEngineError(plan)) {
+            rollback(db);
+            return plan;
+        }
+        for (const w of plan.writes) {
+            // Column names come from the FieldName union, never from caller text.
+            const assignments = w.fields.map((f) => `${f} = ?`).join(", ");
+            // Set as Engine sets it on its own tag edits (spec §3.9, measured).
+            db.prepare(`UPDATE Track SET ${assignments}, isMetadataOfPackedTrackChanged = 1 WHERE id = ?`).run(...w.fields.map((f) => w.set[f] ?? null), w.id);
+        }
+        const after = readRows(db, plan.writes.map((w) => w.id));
+        for (const w of plan.writes) {
+            const got = after.get(w.id);
+            const landed = got !== undefined &&
+                got.origin === rows.get(w.id).origin &&
+                w.fields.every((f) => sameStored(f, got[f], w.set[f] ?? null));
+            if (!landed) {
+                rollback(db);
+                return err("library_unreadable", `Track ${w.id} did not read back as written; nothing was changed.`, {
+                    detail: NOT_COMMITTED,
+                });
+            }
+        }
+        const result = {
+            updated: plan.writes.length,
+            unchanged: plan.unchanged.length,
+            changed: plan.writes.map((w) => ({ id: w.id, fields: w.fields })),
+            undo: plan.undo.length > 0 ? [{ tool: "update_track_metadata", arguments: { updates: plan.undo } }] : [],
+            undo_complete: true,
+        };
+        return result;
+    });
+}

package/dist/store/write.d.ts

@@ -65,6 +65,22 @@ export interface OriginRef {
     uuid: string;
     trackId: number;
 }
+/**
+ * `detail` discriminator values for the EngineError this module returns.
+ * Stable across releases so a caller can decide "is the library still what
+ * it was" without parsing message prose. Everything before COMMIT --
+ * including validation that never reaches the database at all -- collapses
+ * to the same NOT_COMMITTED answer. COMMITTED_UNVERIFIED is produced by
+ * exactly two things, and both mean "the playlist may be on disk": the
+ * post-commit check reporting anything but "ok", and anything thrown from
+ * the COMMIT itself onwards. It is also the only case that carries
+ * backup_path, because it is the only case where restoring from a snapshot
+ * is ever the right next step.
+ *
+ * These two strings are part of the tool's contract; see src/errors.ts.
+ */
+/** Exported for src/store/track-metadata*.ts; the string is part of the tool contract. */
+export declare const NOT_COMMITTED = "not_committed";
 /** Test seam only: forget this process's snapshots so a test can start clean. */
 export declare function resetSessionSnapshots(): void;
 /**
@@ -125,7 +141,74 @@ export declare function checkChain(rows: {
     id: number;
     next: number;
 }[]): ChainCheck;
+/**
+ * Roll back, swallowing a failure of the rollback itself.
+ *
+ * Every caller is already returning a specific error -- the chain did not read
+ * back, the library is busy -- and a ROLLBACK that throws on the way out would
+ * replace that reason with its own, telling the user about a failed rollback
+ * instead of what actually went wrong. Nothing is lost by ignoring it:
+ * db.close() in the finally block ends any transaction still open, and SQLite
+ * discards an uncommitted one on close.
+ */
+/** Exported for src/store/track-metadata.ts. */
+export declare function rollback(db: DatabaseSync): void;
 export declare function sameOrder(a: OriginRef[], b: OriginRef[]): boolean;
+/**
+ * Turns whatever node:sqlite throws into an EngineError. Shared by every op
+ * in this module -- the read-only pre-check and the write transaction below
+ * it both open a connection to the same file and can hit the same failure
+ * modes (the library gone missing mid-session, Engine holding the lock, a
+ * foreign or corrupt schema), and a caller whose promise is typed
+ * `Promise<... | EngineError>` must never see one of them escape as a
+ * rejection instead.
+ *
+ * `subject` is whatever this write is named for in its own messages -- a new
+ * playlist's title for createPlaylist, `playlist ${listId}` for an op that
+ * edits one that already exists.
+ *
+ * Every path that reaches this function is one where the library is
+ * unchanged: the transaction either never opened or is rolled back by the
+ * caller, and a failure at or after COMMIT is answered before this is ever
+ * called (see classifyWriteFailure, below). That is what lets the fallback
+ * below say "nothing was changed" without qualification -- it used to say
+ * `Writing "X" failed`, which reads as a half-write even when the failure was
+ * "file is not a database" and not one byte was attempted.
+ */
+/** Exported for src/store/track-metadata.ts. */
+export declare function mapWriteError(e: unknown, subject: string, mdbPath: string): EngineError;
+/**
+ * Owns everything past the read-only pre-check that every write op in this
+ * module does identically: snapshot, open, `PRAGMA foreign_keys = ON`,
+ * `BEGIN IMMEDIATE`, commit, verify, and classify whatever went wrong.
+ * `body` does the one thing that differs between ops -- the INSERTs and
+ * UPDATEs specific to what this write is -- against the open `db` it is
+ * handed, and returns either the result to hand back (minus `backup_path`,
+ * which this function fills in once it knows COMMIT succeeded) or an
+ * `EngineError`. A body that has already written something rolls back before
+ * returning that error, but this function rolls back on that branch too
+ * rather than relying on it: `rollback` is a no-op when there is no
+ * transaction left to undo, and a body that forgot would otherwise leave the
+ * open transaction to `db.close()` -- correct today, and only by accident.
+ *
+ * `isEngineError`, not a second return channel, is what tells `body`'s
+ * success value apart from its failure one: this module already exports
+ * that check for callers, so reusing it here means a body never has to wrap
+ * its result to disambiguate the two.
+ */
+/** Exported for src/store/track-metadata.ts. */
+export declare function withWriteTransaction<T extends object>(mdbPath: string, uuid: string, subject: string, opts: {
+    backupDir: string;
+    /**
+     * Test seam only. Runs after the snapshot and before the write connection
+     * opens -- the window in which Engine DJ can still change a row this call
+     * already pre-checked. No production caller passes it.
+     */
+    beforeLock?: () => void;
+}, body: (db: DatabaseSync) => T | EngineError): Promise<(T & {
+    library: LibraryRef;
+    backup_path: string;
+}) | EngineError>;
 export declare function createPlaylist(mdbPath: string, uuid: string, input: {
     title: string;
     trackIds: number[];

package/dist/store/write.js

@@ -1,7 +1,8 @@
 // src/store/write.ts
 //
-// The only code in this project that writes to a user's Engine library, and
-// it runs only when the server was started with --allow-writes.
+// Writes to a user's Engine library, together with src/store/track-metadata.ts
+// (which reuses withWriteTransaction, mapWriteError and rollback from here).
+// Both run only when the server was started with --allow-writes.
 //
 // The read path is deliberately not reused. Queries run in a forked child
 // whose connection is opened readOnly: true, and that guarantee is the
@@ -29,7 +30,8 @@ import { redactPath } from "../paths.js";
  *
  * These two strings are part of the tool's contract; see src/errors.ts.
  */
-const NOT_COMMITTED = "not_committed";
+/** Exported for src/store/track-metadata*.ts; the string is part of the tool contract. */
+export const NOT_COMMITTED = "not_committed";
 const COMMITTED_UNVERIFIED = "committed_unverified";
 /**
  * One snapshot per library per process, which is what "before the first write
@@ -266,7 +268,8 @@ function gateChain(db, listId) {
  * db.close() in the finally block ends any transaction still open, and SQLite
  * discards an uncommitted one on close.
  */
-function rollback(db) {
+/** Exported for src/store/track-metadata.ts. */
+export function rollback(db) {
     try {
         db.exec("ROLLBACK");
     }
@@ -298,7 +301,8 @@ export function sameOrder(a, b) {
  * `Writing "X" failed`, which reads as a half-write even when the failure was
  * "file is not a database" and not one byte was attempted.
  */
-function mapWriteError(e, subject, mdbPath) {
+/** Exported for src/store/track-metadata.ts. */
+export function mapWriteError(e, subject, mdbPath) {
     const msg = e.message ?? String(e);
     const isUniqueViolation = /UNIQUE constraint failed/i.test(msg);
     // The constraint's *name* never appears in the message SQLite raises --
@@ -409,7 +413,8 @@ function classifyWriteFailure(e, commit, subject, mdbPath, backupPath, db, open)
  * that check for callers, so reusing it here means a body never has to wrap
  * its result to disambiguate the two.
  */
-async function withWriteTransaction(mdbPath, uuid, subject, opts, body) {
+/** Exported for src/store/track-metadata.ts. */
+export async function withWriteTransaction(mdbPath, uuid, subject, opts, body) {
     // Snapshot here, before the write connection is even opened, not after
     // BEGIN IMMEDIATE. Taking it with RESERVED held meant a full-database copy
     // -- tens of seconds on a multi-gigabyte USB library -- ran while every
@@ -431,6 +436,7 @@ async function withWriteTransaction(mdbPath, uuid, subject, opts, body) {
     if (typeof snapshot !== "string")
         return { ...snapshot, detail: NOT_COMMITTED };
     const backupPath = snapshot;
+    opts.beforeLock?.();
     let db;
     let open = false;
     let commit = "not yet";
@@ -453,7 +459,29 @@ async function withWriteTransaction(mdbPath, uuid, subject, opts, body) {
         // Filled in here, alongside backup_path, for the same reason: it is the
         // one place that knows the write succeeded, and doing it per-op would let
         // a new op ship without it.
-        return { ...result, library: { uuid, path: redactPath(mdbPath) }, backup_path: backupPath };
+        const library = { uuid, path: redactPath(mdbPath) };
+        // Every undo step carries the library too, and for a sharper reason than
+        // symmetry: a caller replaying an undo sends `undo.arguments` and nothing
+        // else, so without it the replay resolves whatever library is the default
+        // at replay time. A USB drive and its copy hold the same playlist ids and
+        // the same track ids, so such a replay lands on the wrong disk and
+        // expect_track_ids agrees -- both sides having been edited the same way.
+        //
+        // By path, not by uuid: a library and its clone on a second drive share a
+        // uuid (see store/backup.ts, which tags snapshots by path for exactly
+        // that), and a uuid could not say which of the two to undo in. A path
+        // names one. If that drive has since moved, the replay fails loudly with
+        // library_not_found rather than quietly editing the other copy.
+        //
+        // Injected here rather than in each op so a new op cannot ship without it.
+        const withUndo = result;
+        if (Array.isArray(withUndo.undo)) {
+            withUndo.undo = withUndo.undo.map((step) => ({
+                ...step,
+                arguments: { library: library.path, ...step.arguments },
+            }));
+        }
+        return { ...result, library, backup_path: backupPath };
     }
     catch (e) {
         return classifyWriteFailure(e, commit, subject, mdbPath, backupPath, db, open);

package/dist/tools/search.js

@@ -32,6 +32,12 @@ export const FIELD_SQL = {
     label: "t.label",
     year: "t.year",
     rating: "t.rating",
+    // Engine stores 0, 20, 40, 60, 80, 100 -- measured: four stars set in Engine
+    // came back as 80. `rating` hands that back as it is; `rating_stars` is the
+    // same thing in the units a person uses, so a caller never has to know the
+    // factor. A value no Engine writes (a third-party tagger's 55) rounds to the
+    // nearest star here and stays exact in `rating`.
+    rating_stars: "CAST(ROUND(COALESCE(t.rating, 0) / 20.0) AS INTEGER)",
     length: "t.length",
     path: "t.path",
     filename: "t.filename",
@@ -296,13 +302,16 @@ export async function searchTracks(qp, raw) {
             filterParams.push(input.key.mode === "minor" ? "%A" : "%B");
         }
     }
+    // In stars, which is what README has always documented and what a person
+    // means. Compared against the raw column, `min: 4` matched 20, 40, 60, 80
+    // and 100 -- every rated track -- and `max: 3` matched only unrated ones.
     if (input.rating?.min !== undefined) {
         filterWhere.push("t.rating >= ?");
-        filterParams.push(input.rating.min);
+        filterParams.push(input.rating.min * 20);
     }
     if (input.rating?.max !== undefined) {
         filterWhere.push("t.rating <= ?");
-        filterParams.push(input.rating.max);
+        filterParams.push(input.rating.max * 20);
     }
     if (input.played?.never)
         filterWhere.push("(t.timeLastPlayed IS NULL OR t.isPlayed = 0)");

package/dist/tools/write-track-metadata.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { type TrackUpdate } from "../store/track-metadata-plan.js";
+export declare const UpdateTrackMetadataInput: z.ZodObject<{
+    updates: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        genre: z.ZodOptional<z.ZodString>;
+        comment: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        year: z.ZodOptional<z.ZodNumber>;
+        rating_stars: z.ZodOptional<z.ZodNumber>;
+        rating_raw: z.ZodOptional<z.ZodNumber>;
+        expect: z.ZodOptional<z.ZodObject<{
+            genre: z.ZodOptional<z.ZodString>;
+            comment: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            year: z.ZodOptional<z.ZodNumber>;
+            rating_raw: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export declare function runUpdateTrackMetadata(mdbPath: string, uuid: string, args: {
+    updates: TrackUpdate[];
+}, backupDir: string): Promise<import("../errors.js").EngineError | (import("../store/track-metadata.js").TrackMetadataResult & {
+    library: import("../store/write.js").LibraryRef;
+    backup_path?: string;
+})>;

package/dist/tools/write-track-metadata.js

@@ -0,0 +1,42 @@
+// src/tools/write-track-metadata.ts
+import { z } from "zod";
+import { updateTrackMetadata } from "../store/track-metadata.js";
+import { MAX_UPDATES } from "../store/track-metadata-plan.js";
+/**
+ * Types and the per-call cap only (spec §7.1). Every other rule -- ranges,
+ * which depend on whether `expect` is present, and the rating_raw restore
+ * rule -- lives in the store, so it comes back as a structured
+ * invalid_argument instead of a bare SDK validation message. `.strict()` makes
+ * a misnamed field such as `rating` an error rather than silently ignored.
+ */
+const Expect = z
+    .object({
+    genre: z.string().optional(),
+    comment: z.string().optional(),
+    label: z.string().optional(),
+    year: z.number().int().optional(),
+    rating_raw: z.number().int().optional(),
+})
+    .strict();
+export const UpdateTrackMetadataInput = z.object({
+    updates: z
+        .array(z
+        .object({
+        id: z.number().int().positive(),
+        genre: z.string().optional(),
+        comment: z.string().optional(),
+        label: z.string().optional(),
+        year: z.number().int().optional(),
+        rating_stars: z.number().int().optional(),
+        rating_raw: z.number().int().optional(),
+        expect: Expect.optional(),
+    })
+        .strict())
+        .max(MAX_UPDATES)
+        .describe("One entry per track: its id from search_tracks or get_tracks, and only the fields to change. " +
+        '"" clears a text field. rating_stars is 0-5. rating_raw and expect exist for replaying an undo; ' +
+        "you do not need them for an ordinary edit."),
+});
+export async function runUpdateTrackMetadata(mdbPath, uuid, args, backupDir) {
+    return updateTrackMetadata(mdbPath, uuid, { updates: args.updates }, { backupDir });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engine-dj-mcp",
-  "version": "0.15.0",
+  "version": "0.17.1",
   "description": "MCP server for an Engine DJ library: search and audit it, read cues and beatgrids, and build playlists when you ask. Not affiliated with inMusic or Denon DJ.",
   "keywords": [
     "mcp",
@@ -19,11 +19,11 @@
   "author": "Mikhail Chereshnev <venuttv@gmail.com>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Venut-Labs/engine-dj-mcp.git"
+    "url": "git+https://github.com/Venut-Technologies/engine-dj-mcp.git"
   },
-  "homepage": "https://github.com/Venut-Labs/engine-dj-mcp#readme",
+  "homepage": "https://github.com/Venut-Technologies/engine-dj-mcp#readme",
   "bugs": {
-    "url": "https://github.com/Venut-Labs/engine-dj-mcp/issues"
+    "url": "https://github.com/Venut-Technologies/engine-dj-mcp/issues"
   },
   "type": "module",
   "engines": {