engine-dj-mcp 0.11.3 → 0.15.0

package/dist/store/write.d.ts

@@ -4,8 +4,63 @@ export interface CreatePlaylistResult {
     playlist_id: number;
     title: string;
     tracks_added: number;
+    library: LibraryRef;
     backup_path: string;
 }
+/**
+ * Which library a write actually landed in. Two connected libraries -- a USB
+ * drive and its copy on the computer -- is the ordinary setup, so "which one
+ * did that go to" is a question every write result has to answer on its own,
+ * without the caller re-deriving it from an argument it may not have passed.
+ *
+ * It is also the context `undo` needs: an undo reverses the edit in this
+ * library and cannot reach a copy Engine DJ has since propagated to another
+ * one (measured 2026-09-01, see README).
+ */
+export interface LibraryRef {
+    uuid: string;
+    /** The m.db path, in the `~/...` form list_libraries prints. */
+    path: string;
+}
+/**
+ * What editing an existing playlist's entries returns. One shape for
+ * add/remove/reorder alike -- each op leaves the fields it did not touch
+ * undefined rather than the module growing a result type per verb.
+ */
+export interface EditResult {
+    playlist_id: number;
+    tracks_added?: number;
+    tracks_removed?: number;
+    positions?: number[];
+    removed?: {
+        position: number;
+        track_id: number | null;
+    }[];
+    undo: UndoStep[];
+    /**
+     * Whether replaying every step of `undo` puts the playlist back exactly as
+     * it was. Always present, never inferred from `undo`'s length: a client
+     * that read a missing field as false -- or a full-looking `undo` as
+     * complete -- would get the one question that matters here backwards.
+     *
+     * False only for removeTracksFromPlaylist, and only for a removal that
+     * included an entry whose stored origin pair matches no track in this
+     * library. Such an entry has no track id to hand back to
+     * add_tracks_to_playlist, so no undo step for it can exist; `undo_note`
+     * then names those positions. The steps that *are* emitted still run, and
+     * still restore everything else to its original position.
+     */
+    undo_complete: boolean;
+    /** Set only when `undo_complete` is false: which positions have no way back, and why. */
+    undo_note?: string;
+    library: LibraryRef;
+    backup_path: string;
+}
+/** One step of the tool call that would undo an edit, in the shape a client replays it. */
+export interface UndoStep {
+    tool: string;
+    arguments: Record<string, unknown>;
+}
 export interface OriginRef {
     uuid: string;
     trackId: number;
@@ -28,6 +83,48 @@ export declare function resetSessionSnapshots(): void;
  * re-originated-track test is for, not this readback.
  */
 export declare function walkFrom(db: DatabaseSync, listId: number, headId: number): OriginRef[];
+/**
+ * One playlist's `PlaylistEntity` rows, in the shape `checkChain` wants: an
+ * entry id and the id it links to (0 for "links to nothing").
+ *
+ * Shared by every op that edits an *existing* playlist's entries --
+ * createPlaylist never calls this, because it builds a chain from nothing
+ * rather than reading one back.
+ */
+export declare function readChain(db: DatabaseSync, listId: number): {
+    id: number;
+    next: number;
+}[];
+export interface ChainCheck {
+    ok: boolean;
+    reason?: string;
+    /** Entry ids head to tail. Meaningful only when `ok`. */
+    order: number[];
+}
+/**
+ * Whether one playlist's entry chain is sound enough to edit.
+ *
+ * Deliberately not `orderByChain` from src/playlists.ts. That function's
+ * contract is that it returns every node it was given, degrading a damaged
+ * chain to a warning, because a reader that silently returned 30 of 43
+ * entries would be worse than one that guesses an order and says so. An edit
+ * needs the opposite: a yes or no.
+ *
+ * Four conditions, and each is needed because different breakages trip
+ * different ones. Checking only that the walk covered every row is the trap:
+ * a list severed into two runs has two heads, and walking from both covers
+ * everything -- measured, on a chain broken on purpose, as "5 of 5" while the
+ * walk from the real head reached 2. Checking coverage without also checking
+ * that the walk *ended* is a second, subtler version of the same trap: a row
+ * whose next points back into an already-linked interior row (two
+ * predecessors, no row pointing at 0) can visit every row and still never
+ * terminate -- the walk stops only because it revisits a row it has already
+ * seen, not because it reached the end.
+ */
+export declare function checkChain(rows: {
+    id: number;
+    next: number;
+}[]): ChainCheck;
 export declare function sameOrder(a: OriginRef[], b: OriginRef[]): boolean;
 export declare function createPlaylist(mdbPath: string, uuid: string, input: {
     title: string;
@@ -35,3 +132,92 @@ export declare function createPlaylist(mdbPath: string, uuid: string, input: {
 }, opts: {
     backupDir: string;
 }): Promise<CreatePlaylistResult | EngineError>;
+/** Where `addTracksToPlaylist`'s `at` can put the new run. */
+export type InsertAt = "end" | "start" | {
+    after_position: number;
+};
+/**
+ * Adds one or more tracks to an existing playlist, at the start, the end, or
+ * after a named position in its current order.
+ *
+ * Shares its skeleton with createPlaylist: a read-only pre-check first (cheap
+ * enough to rule out the common failure modes without ever opening the
+ * library for writing), then withWriteTransaction. Where createPlaylist
+ * builds a chain from nothing, this extends one that already exists, so it
+ * also has to confirm that chain is sound before it touches it -- twice. The
+ * pre-check gates it once, both to fail fast (and skip the snapshot) for a
+ * playlist that cannot be edited at all, and because validating `at` needs
+ * to know how many entries the playlist currently has. The transaction gates
+ * it again after BEGIN IMMEDIATE, because that lock is the first moment
+ * nothing else can change the chain -- gating on the pre-check's read alone,
+ * or reusing the insert position it computed, would be trusting one that
+ * could already be stale.
+ */
+export declare function addTracksToPlaylist(mdbPath: string, uuid: string, input: {
+    listId: number;
+    trackIds: number[];
+    at: InsertAt;
+}, opts: {
+    backupDir: string;
+}): Promise<EditResult | EngineError>;
+/**
+ * Removes one or more tracks from an existing playlist by their current
+ * position.
+ *
+ * `trigger_before_delete_PlaylistEntity` (see gen-library.ts's copy of it,
+ * taken verbatim from a real 3.0.2 library) relinks each deleted row's
+ * predecessor onto its successor as SQLite processes the delete -- verified
+ * for a row removed at the head, the middle and the tail, and, by
+ * construction of the trigger itself, for a batch that removes several
+ * rows, adjacent or not, in one statement. So this function does no chain
+ * maintenance of its own; writing any would just be fighting Engine's own
+ * trigger. What it does own is checking that the trigger's job actually
+ * landed: its `WHEN OLD.trackId > 0` means a row with trackId <= 0 is
+ * deleted *without* relinking, leaving its predecessor pointing at a row
+ * that is now gone. No real library measured has such a row, but the
+ * post-delete check below is the only thing that would ever notice one --
+ * and it checks the surviving order against what was expected, not only
+ * that some sound chain is left, because "sound" and "right" are different
+ * questions and only the second one is what the caller asked for.
+ *
+ * Shares createPlaylist/addTracksToPlaylist's skeleton: a read-only
+ * pre-check first, then withWriteTransaction.
+ */
+export declare function removeTracksFromPlaylist(mdbPath: string, uuid: string, input: {
+    listId: number;
+    positions: number[];
+    expectTrackIds?: (number | null)[];
+}, opts: {
+    backupDir: string;
+}): Promise<EditResult | EngineError>;
+/**
+ * Reorders an existing playlist's entries to a caller-given permutation of
+ * its current order.
+ *
+ * Unlike add/remove, this rewrites links only -- no INSERT, no DELETE -- so
+ * none of Engine's PlaylistEntity triggers fire and there is no trigger
+ * behaviour to trust or verify here, only the links this function writes
+ * itself. `order[i]` names the *current* 1-based position of the track that
+ * should end up at position `i + 1` (see validatePermutation for why the
+ * spec takes a full permutation rather than a move instruction). Only the
+ * entries whose successor actually changes get an UPDATE -- measured on a
+ * real library, moving an entry from the middle to the front took exactly
+ * two updates, and the identity permutation writes no PlaylistEntity row at
+ * all. It is still not a no-op: like every other op here it stamps
+ * `Playlist.lastEditTime`, and the session's snapshot is copied before the
+ * body ever runs, so the identity case costs a timestamp and (once per
+ * session) a snapshot. Left that way deliberately -- "did this permutation
+ * change anything" can only be answered honestly after BEGIN IMMEDIATE, by
+ * which point the snapshot is already taken, and an edit that reports
+ * success without touching lastEditTime would be the one op whose result
+ * Engine cannot see.
+ *
+ * Shares createPlaylist/addTracksToPlaylist/removeTracksFromPlaylist's
+ * skeleton: a read-only pre-check first, then withWriteTransaction.
+ */
+export declare function reorderPlaylist(mdbPath: string, uuid: string, input: {
+    listId: number;
+    order: number[];
+}, opts: {
+    backupDir: string;
+}): Promise<EditResult | EngineError>;