engine-dj-mcp 0.9.0

package/dist/store/connections.js

@@ -0,0 +1,116 @@
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, openSync, readSync, closeSync } from "node:fs";
+import { registerFunctions } from "../semantics.js";
+import { EngineErrorException, libraryNeedsRecovery } from "../errors.js";
+/**
+ * SQLite's rollback-journal header magic (see aJournalMagic in sqlite3
+ * source). A journal only needs recovery — is "hot" — once this has actually
+ * been written to disk. A live writer whose whole transaction still fits in
+ * the page cache never reaches this: nothing is hot until a page is forced
+ * out to the journal, which is why an *active* transaction from a concurrent
+ * writer (see the "concurrent writer" test) is a completely different case
+ * from a *hot* journal left by a killed one.
+ */
+const HOT_JOURNAL_MAGIC = "d9d505f920a163d7";
+/**
+ * True when `<mdbPath>-journal` exists and carries SQLite's real hot-journal
+ * magic, meaning a previous writer died mid-transaction with unflushed pages
+ * on disk. SQLite itself will refuse to open such a database read-only (it
+ * needs to roll the journal forward, which requires a write) and raises a
+ * raw, unhelpful "attempt to write a readonly database" error. This lets
+ * openQueryConnection detect the condition first and explain it instead.
+ */
+export function hasHotJournal(mdbPath) {
+    const journalPath = `${mdbPath}-journal`;
+    if (!existsSync(journalPath))
+        return false;
+    // A journal that exists but cannot be opened or read (a permissions
+    // problem on the sibling file, say) is "cannot determine", not "is hot".
+    // Folding that to false -- rather than throwing, or assuming the worst --
+    // is a deliberate choice: this function's only three callers use a true
+    // result to skip the real open/query attempt and report a specific,
+    // actionable claim ("launch Engine DJ to recover it") without ever
+    // checking the actual database. If the real problem is unrelated to a hot
+    // journal, that claim would be false, and a healthy library would be
+    // permanently unusable through this server for a reason relaunching
+    // Engine DJ cannot fix. Returning false instead lets the real attempt
+    // proceed and surface whatever is actually wrong through the paths that
+    // already handle it as a structured error (library_busy,
+    // query_process_crashed, ...).
+    let fd;
+    try {
+        fd = openSync(journalPath, "r");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const buf = Buffer.alloc(8);
+        const n = readSync(fd, buf, 0, 8, 0);
+        return n === 8 && buf.toString("hex") === HOT_JOURNAL_MAGIC;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * SQLite's "file:" URI filename syntax treats `#`, `?` and unescaped
+ * whitespace as delimiters, so a raw path can misparse even once it is no
+ * longer inside a SQL string literal. encodeURI leaves `#` alone (it is a
+ * legal URI character, just not inside our path segment), hence the extra
+ * replace.
+ */
+function toReadOnlyUri(p) {
+    return "file:" + encodeURI(p).replace(/#/g, "%23") + "?mode=ro";
+}
+/**
+ * Connection A — the one the model reaches through.
+ *
+ * m.db is the MAIN database and is opened readOnly, so the restriction is a
+ * property of the file descriptor rather than a PRAGMA. The inverse layout
+ * (sidecar as main, m.db attached read-only) was rejected: SQL-level
+ * `ATTACH '<m.db>' AS rw` escapes it and can write to the user's library.
+ * PRAGMA query_only was rejected too, because SQL can turn it back off.
+ *
+ * The attach path is bound as a parameter, not interpolated into the SQL
+ * text: a library directory containing an apostrophe (e.g. `Rock 'n' Roll`)
+ * breaks out of a string literal built by concatenation.
+ */
+export function openQueryConnection(mdbPath, sidecar) {
+    if (hasHotJournal(mdbPath)) {
+        // Never open the database writable to roll the journal forward
+        // ourselves: writing to the user's library is the one thing this
+        // project promises never to do. v1 detects and explains instead.
+        //
+        // The structured error is carried by the exception rather than
+        // flattened to its message: this runs inside the forked worker, where
+        // returning is not an option, and the parent used to re-stat the disk to
+        // rediscover what this function already knew.
+        throw new EngineErrorException(libraryNeedsRecovery());
+    }
+    const db = new DatabaseSync(mdbPath, { readOnly: true });
+    db.exec("PRAGMA busy_timeout = 3000");
+    if (sidecar)
+        db.prepare("ATTACH DATABASE ? AS side").run(toReadOnlyUri(sidecar));
+    registerFunctions(db, mdbPath);
+    return db;
+}
+/** Connection B — used only by our own rebuild code, never exposed to the model. */
+export function openSyncConnection(sidecar, mdbPath) {
+    const db = new DatabaseSync(sidecar);
+    db.exec("PRAGMA busy_timeout = 3000");
+    db.prepare("ATTACH DATABASE ? AS engine").run(toReadOnlyUri(mdbPath));
+    registerFunctions(db, mdbPath);
+    return db;
+}
+/** Re-attach the sidecar after an atomic swap; rename() alone is invisible. */
+export function reattachSidecar(db, sidecar) {
+    try {
+        db.exec("DETACH DATABASE side");
+    }
+    catch { /* not attached yet */ }
+    db.prepare("ATTACH DATABASE ? AS side").run(toReadOnlyUri(sidecar));
+}

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

@@ -0,0 +1,29 @@
+import { type EngineError } from "../errors.js";
+import type { LibraryInfo } from "../discovery.js";
+import type { QueryProcess } from "../proc/query-client.js";
+export interface FreshResult {
+    rebuilt: boolean;
+    indexed: number | null;
+    elapsed_ms: number;
+    generation: number;
+}
+/**
+ * Owns the sidecar's whole lifecycle: staleness probe, rebuild, atomic swap
+ * and the re-attach handshake with the live query process.
+ *
+ * The staleness probe reads the SQLite header change counter, not mtime and
+ * size: a restore that preserves mtime (rsync -t, Dropbox, Time Machine,
+ * Engine DJ Cloud) changes the file's contents while mtime and size stay
+ * identical, and an mtime/size probe would then never see the library as
+ * stale again.
+ */
+export declare class IndexManager {
+    #private;
+    private readonly lib;
+    private readonly qp;
+    private readonly baseDir;
+    constructor(lib: LibraryInfo, qp: QueryProcess, baseDir?: string);
+    get generation(): number;
+    get path(): string;
+    ensureFresh(): Promise<FreshResult | EngineError>;
+}

package/dist/store/index-manager.js

@@ -0,0 +1,187 @@
+import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { readChangeCounter } from "../probe.js";
+import { buildSidecar } from "../sidecar/build.js";
+import { SIDECAR_FORMAT } from "../sidecar/schema.js";
+import { sidecarDir } from "../paths.js";
+import { err } from "../errors.js";
+/**
+ * Owns the sidecar's whole lifecycle: staleness probe, rebuild, atomic swap
+ * and the re-attach handshake with the live query process.
+ *
+ * The staleness probe reads the SQLite header change counter, not mtime and
+ * size: a restore that preserves mtime (rsync -t, Dropbox, Time Machine,
+ * Engine DJ Cloud) changes the file's contents while mtime and size stay
+ * identical, and an mtime/size probe would then never see the library as
+ * stale again.
+ */
+export class IndexManager {
+    lib;
+    qp;
+    baseDir;
+    #generation = 0;
+    #attached = false;
+    constructor(lib, qp, baseDir = sidecarDir("")) {
+        this.lib = lib;
+        this.qp = qp;
+        this.baseDir = baseDir;
+    }
+    get generation() {
+        return this.#generation;
+    }
+    get path() {
+        return join(this.baseDir, this.lib.uuid, "index.db");
+    }
+    /**
+     * The change counter the sidecar on disk was built from, or null when
+     * there is no usable sidecar — which forces a rebuild.
+     *
+     * `index_format` is checked alongside it. The change counter alone answers
+     * "is the index's *content* current"; it cannot answer "does the index
+     * still mean what this code thinks it means". When a derived column's
+     * definition changes (has_cues did: from "a blob exists" to "a cue is
+     * set"), a library nobody has touched since keeps the same counter, and
+     * without this check the old meaning would be served from disk for as long
+     * as the user left their library alone. A sidecar predating the column
+     * fails the SELECT outright and lands in the same catch.
+     */
+    #storedCounter() {
+        if (!existsSync(this.path))
+            return null;
+        try {
+            const db = new DatabaseSync(this.path, { readOnly: true });
+            try {
+                const row = db
+                    .prepare("SELECT change_counter, generation, index_format FROM index_meta LIMIT 1")
+                    .get();
+                if (row?.generation)
+                    this.#generation = Number(row.generation);
+                if (!row || Number(row.index_format) !== SIDECAR_FORMAT)
+                    return null;
+                return Number(row.change_counter);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Hands the on-disk index to the live query process, unless it is already
+     * attached. A QueryProcess is constructed with no sidecar, so *every* path
+     * out of ensureFresh that leaves an existing index in service has to do
+     * this -- including the two that never rebuild anything (the index is
+     * already fresh; the library was busy and the previous index still
+     * serves). Without it those paths return a success/index_stale result
+     * while `side` is not attached at all, and the next tool query dies on
+     * "no such table: side.track_derived".
+     *
+     * The short-circuit also checks qp.hasSidecar, not just #attached: a
+     * worker respawn racing a failed setSidecar could otherwise leave
+     * #attached true while the live process actually has nothing attached,
+     * which would let this report success with nothing attached -- the same
+     * class of failure the comment above describes, just reached from the
+     * other side.
+     */
+    async #attach() {
+        if (this.#attached && this.qp.hasSidecar)
+            return true;
+        this.#attached = await this.qp.setSidecar(this.path);
+        return this.#attached;
+    }
+    async ensureFresh() {
+        if (!this.lib.supported) {
+            return err("unsupported_schema", `Schema ${this.lib.schema.join(".")} is not supported`, {
+                detail: "Supported versions are 3.0.0, 3.0.1 and 3.0.2",
+            });
+        }
+        let current;
+        try {
+            current = readChangeCounter(this.lib.path);
+        }
+        catch (e) {
+            return err("library_not_found", "Could not read the library header", { detail: String(e) });
+        }
+        if (this.#storedCounter() === current) {
+            // A fresh index on disk is not the same as a fresh index in service:
+            // on the first call of a new process nothing is attached yet, and the
+            // index built by a previous run would otherwise never be reached.
+            if (!(await this.#attach())) {
+                return err("index_stale", "The existing index could not be attached", {
+                    retry_after_ms: 5000,
+                });
+            }
+            // null, not a count: nothing was rebuilt this call, so there is no
+            // "tracks indexed just now" number to report. -1 previously stood in
+            // here and could be read by a caller as "minus one track indexed".
+            return { rebuilt: false, indexed: null, elapsed_ms: 0, generation: this.#generation };
+        }
+        // Captured before the directory/build attempt: distinguishes "the
+        // library was locked and we had nothing to fall back on" from "the
+        // library was locked but the previous index is still serving fine".
+        const hadPrevious = existsSync(this.path);
+        try {
+            mkdirSync(join(this.baseDir, this.lib.uuid), { recursive: true });
+        }
+        catch (e) {
+            // A permissions failure or full disk here must not throw out of
+            // ensureFresh: errors at this layer are structured returns, not
+            // exceptions.
+            return err("library_busy", "Could not create the sidecar directory", {
+                detail: String(e.message),
+            });
+        }
+        const tmp = `${this.path}.tmp`;
+        let built;
+        try {
+            built = buildSidecar({
+                mdbPath: this.lib.path,
+                outPath: tmp,
+                uuid: this.lib.uuid,
+                schema: this.lib.schema.join("."),
+                generation: this.#generation + 1,
+            });
+        }
+        catch (e) {
+            const message = String(e.message);
+            if (!/locked|busy/i.test(message)) {
+                return err("library_busy", "Could not rebuild the index", { detail: message });
+            }
+            // Serving the previous index beats refusing to answer: search while
+            // Engine DJ is open should keep working on a slightly old index. But
+            // say so honestly, and only after the previous index is genuinely in
+            // service -- on the very first build there is nothing to fall back on,
+            // and "the previous index is still in use" was previously reported
+            // even when nothing had ever been attached.
+            const serving = hadPrevious && (await this.#attach());
+            return err("index_stale", serving
+                ? "The library was busy; the previous index is still in use"
+                : "The library was busy; the index could not be built yet", { retry_after_ms: 5000 });
+        }
+        // rename() is invisible to an already-open connection: the query
+        // process keeps reading the old inode unless told to re-attach.
+        try {
+            renameSync(tmp, this.path);
+        }
+        catch (e) {
+            // A cross-device rename or a filesystem failure here must not throw:
+            // the freshly built file just never becomes the active index.
+            const serving = hadPrevious && (await this.#attach());
+            return err("index_stale", serving
+                ? "The rebuilt index could not be swapped in; the previous index is still in use"
+                : "The rebuilt index could not be swapped in; no index is available yet", { detail: String(e.message), retry_after_ms: 5000 });
+        }
+        this.#generation += 1;
+        // The swap replaced the inode, so an already-attached connection is
+        // still reading the old file: force the re-attach, do not short-circuit
+        // on #attached.
+        this.#attached = await this.qp.setSidecar(this.path);
+        if (!this.#attached) {
+            return err("index_stale", "The rebuilt index could not be attached", { retry_after_ms: 5000 });
+        }
+        return { rebuilt: true, generation: this.#generation, ...built };
+    }
+}

package/dist/tools/audit.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { type EngineError } from "../errors.js";
+import type { QueryProcess } from "../proc/query-client.js";
+export declare const AUDIT_CHECKS: readonly ["missing_files", "unavailable", "unanalyzed", "no_cues", "no_beatgrid", "missing_key", "suspicious_bpm", "duplicates", "empty_metadata", "orphan_entries"];
+export declare const AuditInput: z.ZodObject<{
+    checks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AuditInput = z.input<typeof AuditInput>;
+export declare function auditLibrary(qp: QueryProcess, mdbPath: string, raw: AuditInput): Promise<{
+    checks: {
+        name: string;
+        count: number;
+        sample_ids: number[];
+    }[];
+} | EngineError>;

package/dist/tools/audit.js

@@ -0,0 +1,148 @@
+// src/tools/audit.ts
+import { existsSync } from "node:fs";
+import { z } from "zod";
+import { err, isEngineError } from "../errors.js";
+import { absTrackPath } from "../paths.js";
+export const AUDIT_CHECKS = [
+    "missing_files",
+    "unavailable",
+    "unanalyzed",
+    "no_cues",
+    "no_beatgrid",
+    "missing_key",
+    "suspicious_bpm",
+    "duplicates",
+    "empty_metadata",
+    "orphan_entries",
+];
+export const AuditInput = z.object({ checks: z.array(z.string()).optional() });
+/**
+ * Counts plus a small sample, never rows: this result lands in an LLM's
+ * context. A library with thousands of unanalysed tracks would blow the
+ * context window if every offending id came back, and the model only needs
+ * to know there are thousands and see a handful — detail is fetched
+ * separately (get_tracks) once someone wants it.
+ */
+const SAMPLE = 10;
+const SQL_CHECKS = {
+    unavailable: { id: "t.id", body: `FROM Track t WHERE t.isAvailable = 0` },
+    unanalyzed: {
+        id: "t.id",
+        body: `FROM Track t WHERE t.isAnalyzed = 0 OR t.isAnalyzed IS NULL`,
+    },
+    // "No cue is set", not "no quickCues blob" -- and therefore read from the
+    // sidecar rather than computed here.
+    //
+    // SQL cannot decode a blob, and Engine writes a full eight-slot quickCues
+    // blob to every analysed track, so `length(quickCues) = 0` reported zero
+    // offenders on a reference library where 255 of 257 tracks have no cue at
+    // all. The check named the right thing and structurally could not report
+    // it -- the one shape of wrong answer this tool exists to avoid.
+    // side.track_derived.has_cues is decoded during the rebuild (see
+    // sidecar/build.ts), which is our code and not limited to SQL, so the
+    // check reads it from there.
+    //
+    // Every Track gets a track_derived row, so this still counts tracks,
+    // exactly as the LEFT JOIN version did. The sidecar is attached by the
+    // time any tool runs: every gated tool goes through IndexManager
+    // .ensureFresh first, and search_tracks has always read the same table.
+    no_cues: {
+        id: "d.track_id",
+        body: `FROM side.track_derived d WHERE d.has_cues = 0`,
+    },
+    // Still "empty OR NULL": a zero-length blob is not a beatgrid. Unlike
+    // quickCues, beatData has no "written but empty" state to see through --
+    // all 281 blobs in the reference library decode to a real two-marker grid
+    // whose implied tempo matches Track.bpmAnalyzed, so presence and a usable
+    // grid have not once disagreed. sidecar/build.ts records why decoding it
+    // as well would buy nothing.
+    no_beatgrid: {
+        id: "t.id",
+        body: `FROM Track t LEFT JOIN PerformanceData p ON p.trackId = t.id
+           WHERE COALESCE(length(p.beatData), 0) = 0`,
+    },
+    missing_key: { id: "t.id", body: `FROM Track t WHERE t.key = -1 OR t.key IS NULL` },
+    // bpm is stored at face value (not times 100, as rekordbox does).
+    suspicious_bpm: {
+        id: "t.id",
+        body: `FROM Track t
+           WHERE (t.bpmAnalyzed IS NOT NULL AND t.bpm IS NOT NULL
+                  AND ABS(t.bpmAnalyzed - t.bpm) > 1.0)
+              OR COALESCE(t.bpmAnalyzed, t.bpm) NOT BETWEEN 60 AND 200`,
+    },
+    empty_metadata: {
+        id: "t.id",
+        body: `FROM Track t
+           WHERE t.title IS NULL OR TRIM(t.title) = ''
+              OR t.artist IS NULL OR TRIM(t.artist) = ''`,
+    },
+    duplicates: {
+        id: "t.id",
+        body: `FROM Track t WHERE LOWER(TRIM(t.artist)) || '|' || LOWER(TRIM(t.title)) IN (
+             SELECT LOWER(TRIM(artist)) || '|' || LOWER(TRIM(title)) FROM Track
+             WHERE artist IS NOT NULL AND title IS NOT NULL
+             GROUP BY 1 HAVING COUNT(*) > 1)`,
+    },
+    orphan_entries: {
+        id: "e.id",
+        body: `FROM PlaylistEntity e LEFT JOIN Track t ON t.id = e.trackId WHERE t.id IS NULL`,
+    },
+};
+export async function auditLibrary(qp, mdbPath, raw) {
+    const parsed = AuditInput.safeParse(raw);
+    if (!parsed.success) {
+        return err("invalid_argument", "checks must be an array of check names");
+    }
+    // Distinguish "omitted" from "explicitly empty" before defaulting:
+    // omitting checks already means "run everything", so an empty array
+    // carries no coherent second meaning, and returning { checks: [] } would
+    // read to a model exactly like a clean bill of health on a library nobody
+    // examined.
+    if (parsed.data.checks && parsed.data.checks.length === 0) {
+        return err("invalid_argument", "checks cannot be an empty array", {
+            detail: "An empty list has no meaningful result; omit checks entirely to run every check.",
+        });
+    }
+    const requested = parsed.data.checks ?? [...AUDIT_CHECKS];
+    // A check name is not a value that flows into SQL — it only ever selects
+    // which fixed query text runs — but an unrecognised one must still be
+    // rejected outright rather than silently ignored, naming what was wrong.
+    const unknown = requested.filter((c) => !AUDIT_CHECKS.includes(c));
+    if (unknown.length) {
+        return err("invalid_argument", `Unknown audit checks: ${unknown.join(", ")}`, {
+            detail: `Known checks: ${AUDIT_CHECKS.join(", ")}`,
+        });
+    }
+    const out = [];
+    for (const name of requested) {
+        if (name === "missing_files") {
+            const res = await qp.run(`SELECT id, path FROM Track WHERE path IS NOT NULL`);
+            if (isEngineError(res))
+                return res;
+            const missing = [];
+            for (const row of res.rows) {
+                if (!existsSync(absTrackPath(mdbPath, String(row[1]))))
+                    missing.push(Number(row[0]));
+            }
+            out.push({ name, count: missing.length, sample_ids: missing.slice(0, SAMPLE) });
+            continue;
+        }
+        const check = SQL_CHECKS[name];
+        const counted = await qp.run(`SELECT COUNT(*) AS c ${check.body}`);
+        if (isEngineError(counted))
+            return counted;
+        // ORDER BY the id keeps the sample stable between calls; every id
+        // expression here is a primary key, so this is not an extra sort.
+        // SAMPLE is a module constant, never caller input, but bind it anyway
+        // rather than making an exception to "every value is a parameter".
+        const sampled = await qp.run(`SELECT ${check.id} AS id ${check.body} ORDER BY ${check.id} LIMIT ?`, [SAMPLE]);
+        if (isEngineError(sampled))
+            return sampled;
+        out.push({
+            name,
+            count: Number(counted.rows[0]?.[0] ?? 0),
+            sample_ids: sampled.rows.map((r) => Number(r[0])),
+        });
+    }
+    return { checks: out };
+}

package/dist/tools/libraries.d.ts

@@ -0,0 +1,40 @@
+import { type LibraryInfo } from "../discovery.js";
+import type { EngineError } from "../errors.js";
+/**
+ * A library entry as reported to a caller. `unreadable` is set when the most
+ * recent scan could not actually read this candidate (e.g. Engine DJ holds a
+ * write lock on it right now); the rest of the fields then still carry the
+ * last known-good read, the same way `supported: false` carries a library's
+ * version rather than hiding it -- so a caller can tell a broken server from
+ * a missing library, and now "present but unreadable" from "present and
+ * fine" too. Plain LibraryInfo (no `unreadable`) is always a valid entry.
+ */
+export type LibraryEntry = LibraryInfo & {
+    unreadable?: EngineError;
+};
+export interface LibraryReport {
+    path: string;
+    uuid: string;
+    schema: string;
+    supported: boolean;
+    track_count: number | null;
+    index_generation: number | null;
+    status: "ok" | "unreadable";
+    error: EngineError | null;
+}
+/**
+ * Always succeeds, including for unsupported schemas: a user staring at an
+ * empty list cannot tell a broken server from a missing library. A library
+ * that was discoverable before must not silently disappear because it is
+ * momentarily unreadable either -- see `status`/`error` below and
+ * LibraryEntry's `unreadable`.
+ *
+ * `path` is the absolute location of `m.db`, which carries the user's
+ * account name (see src/paths.ts's `redactPath`) -- unlike Track.path
+ * elsewhere in this codebase, this one really is routinely absolute, so
+ * redaction here is not defence in depth, it is the primary case.
+ */
+export declare function listLibraries(generations?: Map<string, number>, libs?: LibraryEntry[]): {
+    libraries: LibraryReport[];
+    supported_schemas: string[];
+};

package/dist/tools/libraries.js

@@ -0,0 +1,30 @@
+// src/tools/libraries.ts
+import { discoverLibraries, SUPPORTED_SCHEMAS } from "../discovery.js";
+import { redactPath } from "../paths.js";
+/**
+ * Always succeeds, including for unsupported schemas: a user staring at an
+ * empty list cannot tell a broken server from a missing library. A library
+ * that was discoverable before must not silently disappear because it is
+ * momentarily unreadable either -- see `status`/`error` below and
+ * LibraryEntry's `unreadable`.
+ *
+ * `path` is the absolute location of `m.db`, which carries the user's
+ * account name (see src/paths.ts's `redactPath`) -- unlike Track.path
+ * elsewhere in this codebase, this one really is routinely absolute, so
+ * redaction here is not defence in depth, it is the primary case.
+ */
+export function listLibraries(generations = new Map(), libs = discoverLibraries()) {
+    return {
+        libraries: libs.map((l) => ({
+            path: redactPath(l.path),
+            uuid: l.uuid,
+            schema: l.schema.join("."),
+            supported: l.supported,
+            track_count: l.trackCount,
+            index_generation: generations.get(l.uuid) ?? null,
+            status: l.unreadable ? "unreadable" : "ok",
+            error: l.unreadable ?? null,
+        })),
+        supported_schemas: [...SUPPORTED_SCHEMAS],
+    };
+}

package/dist/tools/performance.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { type EngineError } from "../errors.js";
+import type { QueryProcess } from "../proc/query-client.js";
+export declare const PerformanceInput: z.ZodObject<{
+    id: z.ZodNumber;
+}, z.core.$strip>;
+export type PerformanceInput = z.input<typeof PerformanceInput>;
+export declare function getTrackPerformance(qp: QueryProcess, raw: PerformanceInput): Promise<EngineError | {
+    sample_rate: number | null;
+    cues: import("../blobs/index.js").CuesResult;
+    loops: import("../blobs/index.js").LoopsResult;
+    beatgrid: import("../blobs/index.js").BeatgridResult;
+    waveform_summary: import("../blobs/index.js").WaveformSummary;
+    track_id: number;
+}>;

package/dist/tools/performance.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { err, isEngineError } from "../errors.js";
+import { decodePerformance } from "../blobs/index.js";
+export const PerformanceInput = z.object({ id: z.number().int().positive() });
+function asBuffer(v) {
+    if (v === null || v === undefined)
+        return null;
+    if (Buffer.isBuffer(v))
+        return v;
+    if (v instanceof Uint8Array)
+        return Buffer.from(v);
+    return null;
+}
+export async function getTrackPerformance(qp, raw) {
+    const parsed = PerformanceInput.safeParse(raw);
+    if (!parsed.success)
+        return err("invalid_argument", "id must be a positive integer");
+    const { id } = parsed.data;
+    // Track.length carries the duration the waveform summary reports. The
+    // waveform blob does carry its own point spacing, and that spacing times
+    // the point count matches this column to within a second on all 281 real
+    // tracks measured — but the blob has no sample rate of its own, so
+    // deriving seconds from it alone would still be a guess. LEFT JOIN so a
+    // PerformanceData row whose Track is missing still decodes.
+    const res = await qp.run(`SELECT p.quickCues, p.loops, p.beatData, p.overviewWaveFormData, t.length
+     FROM PerformanceData p LEFT JOIN Track t ON t.id = p.trackId
+     WHERE p.trackId = ?`, [id]);
+    if (isEngineError(res))
+        return res;
+    if (!res.rows.length) {
+        return err("decode_failed", `No performance data for track ${id}`, {
+            detail: "The track may not exist, or Engine has not analysed it yet",
+        });
+    }
+    const row = res.rows[0];
+    const [quickCues, loops, beatData, overviewWaveFormData, length] = row;
+    return {
+        track_id: id,
+        ...decodePerformance({
+            quickCues: asBuffer(quickCues),
+            loops: asBuffer(loops),
+            beatData: asBuffer(beatData),
+            overviewWaveFormData: asBuffer(overviewWaveFormData),
+            durationSeconds: typeof length === "number" ? length : null,
+        }),
+    };
+}

package/dist/tools/refresh.d.ts

@@ -0,0 +1,8 @@
+import type { IndexManager } from "../store/index-manager.js";
+import type { EngineError } from "../errors.js";
+export declare function refreshIndex(mgr: IndexManager): Promise<{
+    rebuilt: boolean;
+    indexed: number | null;
+    elapsed_ms: number;
+    generation: number;
+} | EngineError>;

package/dist/tools/refresh.js

@@ -0,0 +1,3 @@
+export async function refreshIndex(mgr) {
+    return mgr.ensureFresh();
+}