engine-dj-mcp 0.9.0

package/dist/discovery.d.ts

@@ -0,0 +1,36 @@
+import { type EngineError } from "./errors.js";
+export declare const SUPPORTED_SCHEMAS: readonly ["3.0.0", "3.0.1", "3.0.2"];
+export interface LibraryInfo {
+    path: string;
+    uuid: string;
+    schema: [number, number, number];
+    supported: boolean;
+    trackCount: number | null;
+}
+export declare function readLibraryInfo(mdbPath: string): LibraryInfo | EngineError;
+export declare function defaultRoots(): string[];
+/** One candidate path's read outcome: either a readable library, or why it
+ * currently is not. `path` is always the candidate location, even on
+ * failure, so a caller can correlate this against a previous successful
+ * probe of the same path. */
+export interface LibraryProbe {
+    path: string;
+    info: LibraryInfo | null;
+    error: EngineError | null;
+}
+/**
+ * Walks the same candidate paths as discoverLibraries(), but -- unlike it --
+ * reports every candidate that exists on disk, including ones readLibraryInfo
+ * could not read right now. discoverLibraries() drops those by design (see
+ * below); this is for a caller that needs to tell "not there" apart from
+ * "there but currently unreadable", e.g. to keep reporting a library that
+ * was seen before while Engine DJ holds a write lock on it.
+ */
+export declare function probeLibraries(roots?: string[]): LibraryProbe[];
+/**
+ * Reports only libraries it could actually read, by design: a permissions
+ * error (or a mid-write lock) on one candidate must not blank out every
+ * other one. Built on probeLibraries(); see that function for a version that
+ * also reports what could not be read and why.
+ */
+export declare function discoverLibraries(roots?: string[]): LibraryInfo[];

package/dist/discovery.js

@@ -0,0 +1,111 @@
+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 { 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}`);
+    }
+    let db;
+    try {
+        // A plain path, never a hand-built "file:" URI. SQLite's URI syntax
+        // treats `#` and `?` as delimiters, so a library under a folder named
+        // `Rock 'n' Roll #1 Mix` truncated at the `#` and failed to open --
+        // discoverLibraries then dropped it and the server reported
+        // library_not_found, while openQueryConnection on the same file worked.
+        // The `readOnly` flag is the actual guarantee; the `?mode=ro` in the URI
+        // was redundant with it, and duplicated store/connections.ts's escaping
+        // rules badly enough to drift.
+        db = new DatabaseSync(mdbPath, { readOnly: true });
+    }
+    catch (e) {
+        return err("library_busy", "Could not open the Engine library", {
+            detail: String(e.message),
+            retry_after_ms: 5000,
+        });
+    }
+    try {
+        // SELECT * on purpose: the Information column set differs between versions.
+        const stmt = db.prepare("SELECT * FROM Information LIMIT 1");
+        // Information.currentPlayedIndiciator is a 64-bit value on a real
+        // library (measured: -8676408967926364917, far outside
+        // Number.MAX_SAFE_INTEGER), and node:sqlite throws instead of returning
+        // it unless a statement opts into BigInt reads. Without this, SELECT *
+        // threw on every real library and discoverLibraries() silently dropped
+        // all of them. Only the small schema/id fields below are ever converted
+        // with Number(); nothing here forces an oversized column through it.
+        stmt.setReadBigInts(true);
+        const row = stmt.get();
+        if (!row)
+            return err("unsupported_schema", "Information table is empty");
+        const schema = [
+            Number(row.schemaVersionMajor ?? 0),
+            Number(row.schemaVersionMinor ?? 0),
+            Number(row.schemaVersionPatch ?? 0),
+        ];
+        const supported = SUPPORTED_SCHEMAS.includes(schema.join("."));
+        let trackCount = null;
+        try {
+            trackCount = Number(db.prepare("SELECT COUNT(*) c FROM Track").get().c);
+        }
+        catch {
+            trackCount = null; // 1.x has no Track table; still listable.
+        }
+        return { path: mdbPath, uuid: String(row.uuid ?? ""), schema, supported, trackCount };
+    }
+    catch (e) {
+        return err("unsupported_schema", "Could not read Information", {
+            detail: String(e.message),
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+export function defaultRoots() {
+    const roots = [join(homedir(), "Music")];
+    try {
+        for (const vol of readdirSync("/Volumes"))
+            roots.push(join("/Volumes", vol));
+    }
+    catch {
+        // /Volumes does not exist off macOS; ignore.
+    }
+    return roots;
+}
+/**
+ * Walks the same candidate paths as discoverLibraries(), but -- unlike it --
+ * reports every candidate that exists on disk, including ones readLibraryInfo
+ * could not read right now. discoverLibraries() drops those by design (see
+ * below); this is for a caller that needs to tell "not there" apart from
+ * "there but currently unreadable", e.g. to keep reporting a library that
+ * was seen before while Engine DJ holds a write lock on it.
+ */
+export function probeLibraries(roots = defaultRoots()) {
+    const out = [];
+    for (const root of roots) {
+        for (const candidate of libraryCandidates(root)) {
+            if (!existsSync(candidate))
+                continue;
+            const info = readLibraryInfo(candidate);
+            out.push("error" in info
+                ? { path: candidate, info: null, error: info }
+                : { path: candidate, info, error: null });
+        }
+    }
+    return out;
+}
+/**
+ * Reports only libraries it could actually read, by design: a permissions
+ * error (or a mid-write lock) on one candidate must not blank out every
+ * other one. Built on probeLibraries(); see that function for a version that
+ * also reports what could not be read and why.
+ */
+export function discoverLibraries(roots = defaultRoots()) {
+    return probeLibraries(roots)
+        .map((p) => p.info)
+        .filter((info) => info !== null);
+}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+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 type ErrorCode = (typeof ERROR_CODES)[number];
+export interface EngineError {
+    error: ErrorCode;
+    message: string;
+    detail?: string;
+    retry_after_ms?: number;
+}
+export declare function err(error: ErrorCode, message: string, extra?: Omit<EngineError, "error" | "message">): EngineError;
+/**
+ * The single source for this text. It was previously written out by hand in
+ * three files, and the one place that built a structured error (connections.ts)
+ * threw away everything but `.message` -- forcing query-client.ts to re-stat
+ * the disk to work out which condition it was looking at.
+ */
+export declare const LIBRARY_NEEDS_RECOVERY_MESSAGE: string;
+export declare function libraryNeedsRecovery(): EngineError;
+/**
+ * An EngineError travelling as an exception, for the one place that has to
+ * throw: openQueryConnection runs inside the forked worker, where a return
+ * value has nowhere to go. The structured error rides along intact --
+ * across the IPC boundary too, since the worker forwards `engineError` in
+ * its startup-failure message -- so no caller has to re-derive the condition
+ * by string-matching a message or by going back to the filesystem.
+ */
+export declare class EngineErrorException extends Error {
+    readonly engineError: EngineError;
+    constructor(engineError: EngineError);
+}
+export declare function isEngineError(value: unknown): value is EngineError;

package/dist/errors.js

@@ -0,0 +1,49 @@
+export const ERROR_CODES = [
+    "library_busy",
+    "library_not_found",
+    "unsupported_schema",
+    "query_timeout",
+    "query_process_crashed",
+    "index_stale",
+    "decode_failed",
+    "invalid_argument",
+    "library_needs_recovery",
+];
+export function err(error, message, extra = {}) {
+    return { error, message, ...extra };
+}
+/**
+ * The single source for this text. It was previously written out by hand in
+ * three files, and the one place that built a structured error (connections.ts)
+ * threw away everything but `.message` -- forcing query-client.ts to re-stat
+ * the disk to work out which condition it was looking at.
+ */
+export const LIBRARY_NEEDS_RECOVERY_MESSAGE = "The Engine library was closed uncleanly and has an unrecovered journal. " +
+    "Launch Engine DJ once so it can recover the library, then retry.";
+export function libraryNeedsRecovery() {
+    return err("library_needs_recovery", LIBRARY_NEEDS_RECOVERY_MESSAGE);
+}
+/**
+ * An EngineError travelling as an exception, for the one place that has to
+ * throw: openQueryConnection runs inside the forked worker, where a return
+ * value has nowhere to go. The structured error rides along intact --
+ * across the IPC boundary too, since the worker forwards `engineError` in
+ * its startup-failure message -- so no caller has to re-derive the condition
+ * by string-matching a message or by going back to the filesystem.
+ */
+export class EngineErrorException extends Error {
+    engineError;
+    constructor(engineError) {
+        super(engineError.message);
+        this.engineError = engineError;
+        this.name = "EngineErrorException";
+    }
+}
+export function isEngineError(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.message === "string" &&
+        typeof v.error === "string" &&
+        ERROR_CODES.includes(v.error));
+}

package/dist/guard.d.ts

@@ -0,0 +1,31 @@
+import { type EngineError } from "./errors.js";
+/**
+ * run_sql executes through prepare(), which ignores everything after the first
+ * semicolon. exec() runs every statement and would let "SELECT 1; VACUUM INTO"
+ * slip past a leading-statement check, so run_sql must never use it. We still
+ * reject chained statements outright, because a query that relies on the tail
+ * being dropped is a query whose author misunderstood what will run.
+ */
+export declare function checkStatement(sql: string): EngineError | null;
+/**
+ * Wraps rather than negotiates with the inner query. Appending a LIMIT only
+ * when the scanner found none at the top level let any caller-supplied
+ * LIMIT satisfy the check regardless of its size -- including one nested
+ * inside a subquery, which this scanner cannot distinguish from a
+ * top-level LIMIT at all (it has no parenthesis-depth tracking, by design,
+ * since it only needs to find keywords and quoted spans). For example,
+ * "SELECT * FROM Track WHERE id IN (SELECT id FROM Track LIMIT 1)" reads
+ * as "already limited" and was left untouched, however many rows the outer
+ * WHERE actually matched.
+ *
+ * Composing "SELECT * FROM (<sql>) LIMIT n" bounds the result no matter
+ * what the inner statement contains, because the wrapper is the outermost
+ * statement executed. A genuinely smaller inner LIMIT still wins: SQLite
+ * applies it to the subquery first, so fewer than n rows ever reach the
+ * wrapper's own LIMIT.
+ *
+ * Only SELECT and WITH can be wrapped this way -- PRAGMA (the only other
+ * statement checkStatement allows through) would become invalid SQL if
+ * wrapped, which is why the leading keyword is still checked here at all.
+ */
+export declare function enforceLimit(sql: string, limit: number): string;

package/dist/guard.js

@@ -0,0 +1,236 @@
+import { err } from "./errors.js";
+/**
+ * Scans a SQL statement character by character, tracking string literals,
+ * identifiers, and comments. Returns analysis needed for validation.
+ */
+function scanStatement(sql) {
+    let i = 0;
+    let firstTokenIndex = -1;
+    let hasChainedStatement = false;
+    let semicolonCount = 0;
+    let lastSemicolonIndex = -1;
+    while (i < sql.length) {
+        const ch = sql[i];
+        // Skip whitespace
+        if (/\s/.test(ch)) {
+            i++;
+            continue;
+        }
+        // Line comment: -- to newline
+        if (ch === "-" && sql[i + 1] === "-") {
+            i += 2;
+            while (i < sql.length && sql[i] !== "\n")
+                i++;
+            if (i < sql.length)
+                i++; // skip newline
+            continue;
+        }
+        // Block comment: /* to */
+        if (ch === "/" && sql[i + 1] === "*") {
+            i += 2;
+            while (i < sql.length && !(sql[i] === "*" && sql[i + 1] === "/"))
+                i++;
+            if (i < sql.length)
+                i += 2; // skip */
+            continue;
+        }
+        // Single-quoted string: '...' with '' as escaped quote
+        if (ch === "'") {
+            i++;
+            while (i < sql.length) {
+                if (sql[i] === "'") {
+                    if (sql[i + 1] === "'") {
+                        i += 2; // escaped quote ''
+                    }
+                    else {
+                        i++; // end of string
+                        break;
+                    }
+                }
+                else {
+                    i++;
+                }
+            }
+            continue;
+        }
+        // Double-quoted identifier: "..." with "" as escaped quote
+        if (ch === '"') {
+            i++;
+            while (i < sql.length) {
+                if (sql[i] === '"') {
+                    if (sql[i + 1] === '"') {
+                        i += 2; // escaped quote ""
+                    }
+                    else {
+                        i++; // end of identifier
+                        break;
+                    }
+                }
+                else {
+                    i++;
+                }
+            }
+            continue;
+        }
+        // Backtick-quoted identifier: `...`
+        if (ch === "`") {
+            i++;
+            while (i < sql.length && sql[i] !== "`")
+                i++;
+            if (i < sql.length)
+                i++; // skip closing backtick
+            continue;
+        }
+        // Bracket-quoted identifier: [...]
+        if (ch === "[") {
+            i++;
+            while (i < sql.length && sql[i] !== "]")
+                i++;
+            if (i < sql.length)
+                i++; // skip closing bracket
+            continue;
+        }
+        // Semicolon - statement separator (top-level, outside quotes/comments)
+        if (ch === ";") {
+            semicolonCount++;
+            lastSemicolonIndex = i;
+            i++;
+            continue;
+        }
+        // Real token found
+        if (firstTokenIndex === -1) {
+            firstTokenIndex = i;
+        }
+        const restOfStatement = sql.substring(i);
+        const wordMatch = restOfStatement.match(/^([a-zA-Z_]\w*)/);
+        // Skip this token
+        if (wordMatch) {
+            i += wordMatch[1].length;
+        }
+        else {
+            i++;
+        }
+    }
+    // Check for statement chaining: more than one semicolon, or real content after semicolon (besides whitespace/comments)
+    // We allow one optional trailing semicolon
+    if (semicolonCount > 1) {
+        hasChainedStatement = true;
+    }
+    else if (semicolonCount === 1 && lastSemicolonIndex !== -1) {
+        // Check if there's real content after the top-level semicolon (besides whitespace/comments)
+        const afterSemicolon = sql.substring(lastSemicolonIndex + 1);
+        let j = 0;
+        while (j < afterSemicolon.length) {
+            const c = afterSemicolon[j];
+            if (/\s/.test(c)) {
+                j++;
+                continue;
+            }
+            if (c === "-" && afterSemicolon[j + 1] === "-") {
+                j += 2;
+                while (j < afterSemicolon.length && afterSemicolon[j] !== "\n")
+                    j++;
+                continue;
+            }
+            if (c === "/" && afterSemicolon[j + 1] === "*") {
+                j += 2;
+                while (j < afterSemicolon.length && !(afterSemicolon[j] === "*" && afterSemicolon[j + 1] === "/"))
+                    j++;
+                j += 2;
+                continue;
+            }
+            // Found real content after semicolon
+            hasChainedStatement = true;
+            break;
+        }
+    }
+    return { firstTokenIndex, hasChainedStatement, lastSemicolonIndex };
+}
+/**
+ * run_sql executes through prepare(), which ignores everything after the first
+ * semicolon. exec() runs every statement and would let "SELECT 1; VACUUM INTO"
+ * slip past a leading-statement check, so run_sql must never use it. We still
+ * reject chained statements outright, because a query that relies on the tail
+ * being dropped is a query whose author misunderstood what will run.
+ */
+export function checkStatement(sql) {
+    const scan = scanStatement(sql);
+    // Reject chained statements
+    if (scan.hasChainedStatement) {
+        return err("invalid_argument", "Only a single SQL statement is allowed", { detail: sql });
+    }
+    // Extract first keyword
+    if (scan.firstTokenIndex === -1) {
+        return null; // Empty or only comments/whitespace - allow
+    }
+    const rest = sql.substring(scan.firstTokenIndex);
+    const keywordMatch = rest.match(/^([a-zA-Z_]\w*)/);
+    if (!keywordMatch)
+        return null;
+    const keyword = keywordMatch[1].toUpperCase();
+    // Reject VACUUM, ATTACH, DETACH
+    if (keyword === "VACUUM" || keyword === "ATTACH" || keyword === "DETACH") {
+        return err("invalid_argument", "VACUUM, ATTACH and DETACH are not permitted", { detail: sql });
+    }
+    // Check PRAGMA statements
+    if (keyword === "PRAGMA") {
+        // Find the pragma name - skip past PRAGMA keyword and whitespace
+        let pragmaStart = scan.firstTokenIndex + 6; // length of "PRAGMA"
+        while (pragmaStart < sql.length && /\s/.test(sql[pragmaStart]))
+            pragmaStart++;
+        // Skip optional schema qualifier (main., temp., side., engine.)
+        if (pragmaStart < sql.length) {
+            const schemaMatch = sql.substring(pragmaStart).match(/^(main|temp|side|engine)\./i);
+            if (schemaMatch) {
+                pragmaStart += schemaMatch[0].length;
+            }
+        }
+        // Extract pragma name
+        const pragmaNameMatch = sql.substring(pragmaStart).match(/^([a-zA-Z_]\w*)/);
+        if (!pragmaNameMatch)
+            return null;
+        const pragmaName = pragmaNameMatch[1].toUpperCase();
+        const allowedPragmas = ["TABLE_INFO", "TABLE_LIST", "INDEX_LIST", "INDEX_INFO", "FOREIGN_KEY_LIST"];
+        if (!allowedPragmas.includes(pragmaName)) {
+            return err("invalid_argument", "Only read-only PRAGMA introspection is permitted", { detail: sql });
+        }
+    }
+    return null;
+}
+/**
+ * Wraps rather than negotiates with the inner query. Appending a LIMIT only
+ * when the scanner found none at the top level let any caller-supplied
+ * LIMIT satisfy the check regardless of its size -- including one nested
+ * inside a subquery, which this scanner cannot distinguish from a
+ * top-level LIMIT at all (it has no parenthesis-depth tracking, by design,
+ * since it only needs to find keywords and quoted spans). For example,
+ * "SELECT * FROM Track WHERE id IN (SELECT id FROM Track LIMIT 1)" reads
+ * as "already limited" and was left untouched, however many rows the outer
+ * WHERE actually matched.
+ *
+ * Composing "SELECT * FROM (<sql>) LIMIT n" bounds the result no matter
+ * what the inner statement contains, because the wrapper is the outermost
+ * statement executed. A genuinely smaller inner LIMIT still wins: SQLite
+ * applies it to the subquery first, so fewer than n rows ever reach the
+ * wrapper's own LIMIT.
+ *
+ * Only SELECT and WITH can be wrapped this way -- PRAGMA (the only other
+ * statement checkStatement allows through) would become invalid SQL if
+ * wrapped, which is why the leading keyword is still checked here at all.
+ */
+export function enforceLimit(sql, limit) {
+    const scan = scanStatement(sql);
+    // Extract first keyword
+    if (scan.firstTokenIndex === -1) {
+        return sql; // Empty or only comments/whitespace - return unchanged
+    }
+    const rest = sql.substring(scan.firstTokenIndex);
+    const keywordMatch = rest.match(/^([a-zA-Z_]\w*)/);
+    if (!keywordMatch)
+        return sql;
+    const keyword = keywordMatch[1].toUpperCase();
+    if (keyword !== "SELECT" && keyword !== "WITH")
+        return sql;
+    const trimmed = sql.trim().replace(/;\s*$/, "");
+    return `SELECT * FROM (${trimmed}) LIMIT ${limit}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = await createServer();
+    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/library-select.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { type EngineError } from "./errors.js";
+import type { LibraryInfo } from "./discovery.js";
+/**
+ * The `library` argument every library-touching tool accepts. Optional
+ * everywhere: a DJ with one library must never have to name it.
+ *
+ * Both a uuid and a path are accepted because `list_libraries` reports both,
+ * and neither a person nor a model can be expected to know which of the two
+ * fields is the "real" identifier. The description says so explicitly --
+ * a model reads this string and nothing else before choosing what to pass.
+ */
+export declare const LIBRARY_ARG_DESCRIPTION: string;
+export declare const LibraryArg: z.ZodOptional<z.ZodString>;
+/**
+ * The default when no `library` was given: the supported library with the
+ * most tracks.
+ *
+ * Root-scan order -- the previous rule -- puts ~/Music ahead of /Volumes,
+ * so a DJ whose real collection lives on a USB drive got the near-empty
+ * local library that Engine DJ creates on install, with no way to ask for
+ * the other one. Track count is the one signal available at discovery time
+ * that actually tracks "the library this person works in".
+ *
+ * Ties break on root-scan order, so the choice is deterministic rather than
+ * dependent on Map or filesystem iteration order. `trackCount` is null only
+ * when the Track table could not be read at all (a 1.x library); such a
+ * library is never `supported`, but treat null as "fewer than zero tracks"
+ * anyway so a known count always beats an unknown one.
+ *
+ * Falls back to the first library of any kind -- including an unsupported
+ * one -- so that ensureFresh's specific, actionable `unsupported_schema`
+ * reaches the caller instead of the generic `library_not_found` that "no
+ * supported library" would otherwise collapse into.
+ */
+export declare function pickDefaultLibrary(libs: readonly LibraryInfo[]): LibraryInfo | null;
+/**
+ * Resolves a caller-supplied `library` value: uuid first, then filesystem
+ * path. Returns null when it matches neither -- the caller decides what
+ * kind of error that is, since it also knows what else is (or is not) on
+ * this machine.
+ *
+ * uuid comparison is case- and whitespace-insensitive: Engine writes uuids
+ * in one case and a caller may well retype or re-case one. Path comparison
+ * goes through expandHome + resolve, so `~/Music/...` (the form
+ * list_libraries prints), the absolute form, and a path with a redundant
+ * `.` or trailing separator all name the same library.
+ *
+ * A path match is exact on the m.db file, not a prefix: a value that merely
+ * *contains* a library path must not select it.
+ */
+export declare function findLibrary(libs: readonly LibraryInfo[], requested: string): LibraryInfo | null;
+/**
+ * The error for a `library` value that matched nothing. It names what was
+ * passed and lists what is actually selectable, because the two ways to get
+ * here -- a typo, and a drive that is no longer mounted -- are told apart by
+ * seeing the list, not by being told "not found".
+ *
+ * Deliberately reuses `library_not_found` rather than introducing a code:
+ * the taxonomy is closed, and this is the same condition ("the library you
+ * are asking about is not here") arrived at from a different direction.
+ */
+export declare function libraryNotFound(requested: string, libs: readonly LibraryInfo[]): EngineError;

package/dist/library-select.js

@@ -0,0 +1,97 @@
+// src/library-select.ts
+import { resolve } from "node:path";
+import { z } from "zod";
+import { err } from "./errors.js";
+import { expandHome, redactPath } from "./paths.js";
+/**
+ * The `library` argument every library-touching tool accepts. Optional
+ * everywhere: a DJ with one library must never have to name it.
+ *
+ * Both a uuid and a path are accepted because `list_libraries` reports both,
+ * and neither a person nor a model can be expected to know which of the two
+ * fields is the "real" identifier. The description says so explicitly --
+ * a model reads this string and nothing else before choosing what to pass.
+ */
+export const LIBRARY_ARG_DESCRIPTION = "Which library to use: either the uuid or the path reported by list_libraries " +
+    "(the reported ~/... form is accepted, as is the absolute path). Omit it to use " +
+    "the supported library holding the most tracks.";
+export const LibraryArg = z.string().min(1).optional().describe(LIBRARY_ARG_DESCRIPTION);
+/**
+ * The default when no `library` was given: the supported library with the
+ * most tracks.
+ *
+ * Root-scan order -- the previous rule -- puts ~/Music ahead of /Volumes,
+ * so a DJ whose real collection lives on a USB drive got the near-empty
+ * local library that Engine DJ creates on install, with no way to ask for
+ * the other one. Track count is the one signal available at discovery time
+ * that actually tracks "the library this person works in".
+ *
+ * Ties break on root-scan order, so the choice is deterministic rather than
+ * dependent on Map or filesystem iteration order. `trackCount` is null only
+ * when the Track table could not be read at all (a 1.x library); such a
+ * library is never `supported`, but treat null as "fewer than zero tracks"
+ * anyway so a known count always beats an unknown one.
+ *
+ * Falls back to the first library of any kind -- including an unsupported
+ * one -- so that ensureFresh's specific, actionable `unsupported_schema`
+ * reaches the caller instead of the generic `library_not_found` that "no
+ * supported library" would otherwise collapse into.
+ */
+export function pickDefaultLibrary(libs) {
+    let best = null;
+    for (const lib of libs) {
+        if (!lib.supported)
+            continue;
+        if (best === null || (lib.trackCount ?? -1) > (best.trackCount ?? -1))
+            best = lib;
+    }
+    return best ?? libs[0] ?? null;
+}
+/**
+ * Resolves a caller-supplied `library` value: uuid first, then filesystem
+ * path. Returns null when it matches neither -- the caller decides what
+ * kind of error that is, since it also knows what else is (or is not) on
+ * this machine.
+ *
+ * uuid comparison is case- and whitespace-insensitive: Engine writes uuids
+ * in one case and a caller may well retype or re-case one. Path comparison
+ * goes through expandHome + resolve, so `~/Music/...` (the form
+ * list_libraries prints), the absolute form, and a path with a redundant
+ * `.` or trailing separator all name the same library.
+ *
+ * A path match is exact on the m.db file, not a prefix: a value that merely
+ * *contains* a library path must not select it.
+ */
+export function findLibrary(libs, requested) {
+    const wanted = requested.trim();
+    if (!wanted)
+        return null;
+    const byUuid = libs.find((l) => l.uuid && l.uuid.toLowerCase() === wanted.toLowerCase());
+    if (byUuid)
+        return byUuid;
+    // resolve() turns a relative value into something rooted at the process
+    // cwd, which matches no library path -- exactly the intended outcome for
+    // a value that is neither a uuid nor a real path.
+    const wantedPath = resolve(expandHome(wanted));
+    return libs.find((l) => resolve(l.path) === wantedPath) ?? null;
+}
+/**
+ * The error for a `library` value that matched nothing. It names what was
+ * passed and lists what is actually selectable, because the two ways to get
+ * here -- a typo, and a drive that is no longer mounted -- are told apart by
+ * seeing the list, not by being told "not found".
+ *
+ * Deliberately reuses `library_not_found` rather than introducing a code:
+ * the taxonomy is closed, and this is the same condition ("the library you
+ * are asking about is not here") arrived at from a different direction.
+ */
+export function libraryNotFound(requested, libs) {
+    const known = libs.filter((l) => l.uuid);
+    return err("library_not_found", `No Engine DJ library matches "${requested}"`, {
+        detail: known.length
+            ? `Known libraries (uuid -- path): ${known
+                .map((l) => `${l.uuid} -- ${redactPath(l.path)}`)
+                .join("; ")}. Pass a uuid or a path exactly as list_libraries reports it.`
+            : "No Engine DJ library was discovered on this machine; call list_libraries to see what is visible.",
+    });
+}