roon-mcp 0.1.0

package/dist/ZoneService.test.js

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { ZoneService } from "./ZoneService.js";
+import { RoonMcpError } from "./types.js";
+function zone(partial) {
+    return {
+        display_name: partial.zone_id,
+        state: "stopped",
+        outputs: [{ output_id: `o:${partial.zone_id}`, zone_id: partial.zone_id, display_name: partial.zone_id }],
+        ...partial,
+    };
+}
+/** Builds a ZoneService backed by a stub RoonClient returning the given zones. */
+function serviceWith(zones, defaultZone) {
+    const stub = {
+        waitForCore: async () => undefined,
+        getTransport: () => ({
+            get_zones: (cb) => cb(false, { zones }),
+            subscribe_zones: () => { },
+        }),
+    };
+    return new ZoneService(stub, undefined, defaultZone);
+}
+test("listZones maps Roon zones to the public shape", async () => {
+    const svc = serviceWith([zone({ zone_id: "z1", display_name: "Office", state: "playing" })]);
+    const [z] = await svc.listZones();
+    assert.deepEqual(z, {
+        zoneId: "z1",
+        displayName: "Office",
+        state: "playing",
+        outputIds: ["o:z1"],
+        isDefaultCandidate: true,
+    });
+});
+test("resolveZone returns the only zone without a preferred name", async () => {
+    const svc = serviceWith([zone({ zone_id: "z1", display_name: "Kitchen" })]);
+    const res = await svc.resolveZone();
+    assert.equal(res.zoneId, "z1");
+});
+test("resolveZone prefers an exact name match over a substring", async () => {
+    const svc = serviceWith([
+        zone({ zone_id: "z1", display_name: "Office" }),
+        zone({ zone_id: "z2", display_name: "Office Speakers" }),
+    ]);
+    const res = await svc.resolveZone("Office");
+    assert.equal(res.zoneId, "z1");
+});
+test("resolveZone returns ambiguity when a fuzzy name matches several zones", async () => {
+    const svc = serviceWith([
+        zone({ zone_id: "z1", display_name: "Living Room" }),
+        zone({ zone_id: "z2", display_name: "Living Room Sub" }),
+    ]);
+    const res = await svc.resolveZone("living");
+    assert.equal("ambiguous" in res && res.ambiguous, true);
+});
+test("resolveZone falls back to an Office zone with no preferred name", async () => {
+    const svc = serviceWith([
+        zone({ zone_id: "z1", display_name: "Kitchen" }),
+        zone({ zone_id: "z2", display_name: "Home Office" }),
+    ]);
+    const res = await svc.resolveZone();
+    assert.equal(res.zoneId, "z2");
+});
+test("resolveZone prefers the currently playing zone when no name match", async () => {
+    const svc = serviceWith([
+        zone({ zone_id: "z1", display_name: "Kitchen", state: "stopped" }),
+        zone({ zone_id: "z2", display_name: "Bedroom", state: "playing" }),
+    ]);
+    const res = await svc.resolveZone();
+    assert.equal(res.zoneId, "z2");
+});
+test("resolveZone throws ZONE_NOT_FOUND when there are no zones", async () => {
+    const svc = serviceWith([]);
+    await assert.rejects(svc.resolveZone(), (e) => e instanceof RoonMcpError && e.code === "ZONE_NOT_FOUND");
+});
+test("resolveTarget passes an explicit id through unchanged (output id preserved)", async () => {
+    const svc = serviceWith([
+        zone({ zone_id: "z1", display_name: "Office" }),
+        zone({ zone_id: "z2", display_name: "Kitchen" }),
+    ]);
+    const out = await svc.resolveTarget("o:z2");
+    assert.equal(out.targetId, "o:z2"); // caller's output id, not the zone id
+    assert.equal(out.zone.zoneId, "z2");
+});
+test("resolveTarget rejects an unknown explicit id with ZONE_NOT_FOUND", async () => {
+    const svc = serviceWith([zone({ zone_id: "z1", display_name: "Office" })]);
+    await assert.rejects(svc.resolveTarget("nope"), (e) => e instanceof RoonMcpError && e.code === "ZONE_NOT_FOUND");
+});
+test("resolveTarget uses the configured default zone (by name) when none is passed", async () => {
+    const svc = serviceWith([zone({ zone_id: "z1", display_name: "Kitchen" }), zone({ zone_id: "z2", display_name: "Office" })], "Office");
+    const out = await svc.resolveTarget();
+    assert.equal(out.targetId, "z2");
+});
+test("resolveTarget honours a default given as a zone id", async () => {
+    const svc = serviceWith([zone({ zone_id: "z1", display_name: "Kitchen" }), zone({ zone_id: "z2", display_name: "Office" })], "z1");
+    const out = await svc.resolveTarget();
+    assert.equal(out.targetId, "z1");
+});
+test("resolveTarget falls back to the single zone when no default is set", async () => {
+    const svc = serviceWith([zone({ zone_id: "z1", display_name: "Kitchen" })]);
+    const out = await svc.resolveTarget();
+    assert.equal(out.targetId, "z1");
+});
+test("resolveTarget throws ZONE_AMBIGUOUS when no default and several zones", async () => {
+    const svc = serviceWith([
+        zone({ zone_id: "z1", display_name: "Kitchen", state: "stopped" }),
+        zone({ zone_id: "z2", display_name: "Bedroom", state: "stopped" }),
+    ]);
+    await assert.rejects(svc.resolveTarget(), (e) => e instanceof RoonMcpError && e.code === "ZONE_AMBIGUOUS");
+});
+//# sourceMappingURL=ZoneService.test.js.map

package/dist/ZoneService.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZoneService.test.js","sourceRoot":"","sources":["../src/ZoneService.test.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { BrowseSessionManager } from "./BrowseSessionManager.js";
+import { GenreService } from "./GenreService.js";
+import { PlaybackService } from "./PlaybackService.js";
+import { RoonClient } from "./RoonClient.js";
+import { RoonMcpServer } from "./RoonMcpServer.js";
+import { SearchService } from "./SearchService.js";
+import { TrackExpansionService } from "./TrackExpansionService.js";
+import { ZoneService } from "./ZoneService.js";
+import { createStderrLogger } from "./logger.js";
+// node-roon-api logs discovery chatter via console.log. On a stdio MCP server
+// stdout is reserved for JSON-RPC, so route all console output to stderr.
+for (const method of ["log", "info", "debug", "warn"]) {
+    console[method] = (...args) => {
+        process.stderr.write(`${args.map(String).join(" ")}\n`);
+    };
+}
+async function main() {
+    // One structured logger shared across services; emits [roon-call] lines to
+    // stderr so stdout stays reserved for the MCP JSON-RPC stream.
+    const logger = createStderrLogger();
+    const roon = new RoonClient();
+    // Optional configured default zone (a zone/output id or display-name) used
+    // when a playback call omits its zoneId.
+    const defaultZone = process.env.ROON_DEFAULT_ZONE?.trim() || undefined;
+    const zones = new ZoneService(roon, logger, defaultZone);
+    const browse = new BrowseSessionManager(roon, logger);
+    const genres = new GenreService(browse);
+    const tracks = new TrackExpansionService(browse);
+    const search = new SearchService(browse, genres, tracks);
+    const playback = new PlaybackService(browse, zones, roon, tracks, logger);
+    const server = new RoonMcpServer(roon, zones, search, tracks, playback);
+    const shutdown = () => {
+        void server.stop().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await server.start();
+}
+main().catch((err) => {
+    process.stderr.write(`[roon-mcp] fatal: ${err instanceof Error ? err.stack : err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,8EAA8E;AAC9E,0EAA0E;AAC1E,KAAK,MAAM,MAAM,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAU,EAAE,CAAC;IAC/D,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAe,EAAE,EAAE;QACvC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,2EAA2E;IAC3E,+DAA+D;IAC/D,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,UAAU,EAAE,CAAC;IAC9B,2EAA2E;IAC3E,yCAAyC;IACzC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACvE,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1E,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAExE,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAEhC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACtF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/locator.d.ts

@@ -0,0 +1,58 @@
+import type { BrowseHierarchy } from "node-roon-api-browse";
+/**
+ * A path back to a flat-search result:
+ *   q  search query that produced the result
+ *   g  index into the (selectable) top-level search groups
+ *   i  index into that group's (selectable) child items
+ *   t  optional index into the ordered tracks expanded from item (g,i)
+ */
+export interface SearchLocator {
+    q: string;
+    g: number;
+    i: number;
+    t?: number;
+}
+/**
+ * A path back to a genre node in the `genres` hierarchy:
+ *   ge  ordered genre node titles from the root, e.g.
+ *       ["Electronic", "Trance", "Psytrance"]
+ *   a   optional index into the genre's "Albums" container (which album)
+ *   t   optional index into that album's track list (which track)
+ *
+ * A genre has no track list of its own, so its tracks are addressed two levels
+ * down: album `a`, then track `t` within it. Both are set together for an
+ * expanded genre track; a bare `{ ge }` is the genre node itself.
+ */
+export interface GenreLocator {
+    ge: string[];
+    a?: number;
+    t?: number;
+}
+export type Locator = SearchLocator | GenreLocator;
+/** True for a genre locator (re-navigated via the `genres` hierarchy). */
+export declare function isGenreLocator(loc: Locator): loc is GenreLocator;
+/** Which browse hierarchy a locator is re-navigated in. */
+export declare function hierarchyForLocator(loc: Locator): BrowseHierarchy;
+/**
+ * Encode a locator as an opaque token suitable for an MCP itemKey. Accepts
+ * either shape so callers re-encoding a possibly-genre locator (e.g. adding a
+ * track index) don't have to branch; `encodeGenreLocator` is a convenience for
+ * building genre locators from a path.
+ */
+export declare function encodeLocator(loc: Locator): string;
+/**
+ * Encode a genre locator. With no coords it points at the genre node itself;
+ * with `{ a, t }` it points at track `t` of album `a` inside the genre.
+ */
+export declare function encodeGenreLocator(path: string[], coords?: {
+    a?: number;
+    t?: number;
+}): string;
+/** Decode a locator token, or return null if it isn't one (e.g. a raw key). */
+export declare function decodeLocator(token: string): Locator | null;
+/**
+ * Derive a track locator by extending a search-item locator with a track index.
+ * Genre tracks are addressed by (album, track) — build those with
+ * `encodeGenreLocator` and coords instead.
+ */
+export declare function withTrackIndex(loc: SearchLocator, t: number): SearchLocator;

package/dist/locator.js

@@ -0,0 +1,88 @@
+// Roon browse item keys are *level-scoped*: the Core invalidates them as soon
+// as you pop out of the list they belong to. `search_music` has to drill into
+// several result groups (Artists, Albums, …) and pop back between them, so by
+// the time it returns, every raw key it collected is already dead — unusable by
+// a later `play_now` / `get_tracks_for` / `enqueue_and_play` call.
+//
+// To make the keys durable across MCP calls we hand back a *locator* instead: a
+// self-describing token that records how to re-reach the item. Playback/
+// expansion decode it and re-navigate from scratch in one uninterrupted browse
+// session, where the live keys are valid at the moment they're used. This trades
+// a re-navigation per action for correctness, and removes any dependence on
+// fragile server-side session state.
+//
+// Two locator shapes exist:
+//   - a *search* locator re-reached via the flat `search` hierarchy (a query
+//     plus the indices to drill);
+//   - a *genre* locator re-reached via the dedicated `genres` hierarchy (a path
+//     of genre node titles to drill from the root). Genres don't appear in the
+//     flat search, so they need their own navigation path (see GenreService).
+const PREFIX = "rl1:";
+/** True for a genre locator (re-navigated via the `genres` hierarchy). */
+export function isGenreLocator(loc) {
+    return Array.isArray(loc.ge);
+}
+/** Which browse hierarchy a locator is re-navigated in. */
+export function hierarchyForLocator(loc) {
+    return isGenreLocator(loc) ? "genres" : "search";
+}
+/**
+ * Encode a locator as an opaque token suitable for an MCP itemKey. Accepts
+ * either shape so callers re-encoding a possibly-genre locator (e.g. adding a
+ * track index) don't have to branch; `encodeGenreLocator` is a convenience for
+ * building genre locators from a path.
+ */
+export function encodeLocator(loc) {
+    const json = JSON.stringify(loc);
+    return PREFIX + Buffer.from(json, "utf8").toString("base64url");
+}
+/**
+ * Encode a genre locator. With no coords it points at the genre node itself;
+ * with `{ a, t }` it points at track `t` of album `a` inside the genre.
+ */
+export function encodeGenreLocator(path, coords) {
+    const loc = { ge: path };
+    if (coords?.a !== undefined)
+        loc.a = coords.a;
+    if (coords?.t !== undefined)
+        loc.t = coords.t;
+    return encodeLocator(loc);
+}
+/** Decode a locator token, or return null if it isn't one (e.g. a raw key). */
+export function decodeLocator(token) {
+    if (!token.startsWith(PREFIX))
+        return null;
+    try {
+        const json = Buffer.from(token.slice(PREFIX.length), "base64url").toString("utf8");
+        const obj = JSON.parse(json);
+        // Genre locator: a path of node titles.
+        if (Array.isArray(obj.ge) && obj.ge.every((s) => typeof s === "string")) {
+            const loc = { ge: obj.ge };
+            if (typeof obj.a === "number")
+                loc.a = obj.a;
+            if (typeof obj.t === "number")
+                loc.t = obj.t;
+            return loc;
+        }
+        // Search locator: query + group/item indices.
+        if (typeof obj.q === "string" && typeof obj.g === "number" && typeof obj.i === "number") {
+            const loc = { q: obj.q, g: obj.g, i: obj.i };
+            if (typeof obj.t === "number")
+                loc.t = obj.t;
+            return loc;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Derive a track locator by extending a search-item locator with a track index.
+ * Genre tracks are addressed by (album, track) — build those with
+ * `encodeGenreLocator` and coords instead.
+ */
+export function withTrackIndex(loc, t) {
+    return { q: loc.q, g: loc.g, i: loc.i, t };
+}
+//# sourceMappingURL=locator.js.map

package/dist/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../src/locator.ts"],"names":[],"mappings":"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"}

package/dist/locator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/locator.test.js

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { decodeLocator, encodeGenreLocator, encodeLocator, hierarchyForLocator, isGenreLocator, withTrackIndex, } from "./locator.js";
+test("a search locator round-trips through encode/decode", () => {
+    const token = encodeLocator({ q: "Tycho", g: 1, i: 2 });
+    const loc = decodeLocator(token);
+    assert.ok(loc && !isGenreLocator(loc));
+    assert.deepEqual(loc, { q: "Tycho", g: 1, i: 2 });
+    assert.equal(hierarchyForLocator(loc), "search");
+});
+test("a genre locator round-trips and reports the genres hierarchy", () => {
+    const token = encodeGenreLocator(["Electronic", "Trance", "Psytrance"]);
+    const loc = decodeLocator(token);
+    assert.ok(loc && isGenreLocator(loc));
+    assert.deepEqual(loc.ge, ["Electronic", "Trance", "Psytrance"]);
+    assert.equal(loc.a, undefined);
+    assert.equal(loc.t, undefined);
+    assert.equal(hierarchyForLocator(loc), "genres");
+});
+test("a genre track locator carries the (album, track) coordinates", () => {
+    const token = encodeGenreLocator(["Electronic", "Trance", "Psytrance"], { a: 2, t: 5 });
+    const loc = decodeLocator(token);
+    assert.ok(loc && isGenreLocator(loc));
+    assert.equal(loc.a, 2);
+    assert.equal(loc.t, 5);
+});
+test("withTrackIndex extends a search locator with a track index", () => {
+    const search = decodeLocator(encodeLocator({ q: "x", g: 0, i: 0 }));
+    assert.ok(!isGenreLocator(search));
+    const searchT = withTrackIndex(search, 3);
+    assert.equal(searchT.t, 3);
+});
+test("a non-locator token decodes to null", () => {
+    assert.equal(decodeLocator("341:0"), null);
+    assert.equal(decodeLocator("rl1:not-base64-json"), null);
+});
+//# sourceMappingURL=locator.test.js.map

package/dist/locator.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.test.js","sourceRoot":"","sources":["../src/locator.test.ts"],"names":[],"mappings":"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"}

package/dist/logger.d.ts

@@ -0,0 +1,23 @@
+export interface RoonCallLogger {
+    /**
+     * Time and log a single Roon API call. Emits one structured line when `fn`
+     * settles (level `info` on success, `error` on rejection) and then
+     * returns/rethrows `fn`'s result unchanged — so callers' error codes are
+     * preserved for downstream retry/skip logic.
+     *
+     * @param op        Short operation name, e.g. "browse" or "get_zones".
+     * @param params    Request parameters, logged as-is (Roon browse params hold
+     *                  no secrets). Pass `{}` when there are none.
+     * @param fn        The async call to time.
+     * @param summarize Optional: derive a compact result summary to log instead
+     *                  of the full (often large) response body.
+     */
+    call<T>(op: string, params: unknown, fn: () => Promise<T>, summarize?: (result: T) => unknown): Promise<T>;
+}
+/** A no-op logger: runs the call without emitting anything. Default in tests. */
+export declare const silentLogger: RoonCallLogger;
+/**
+ * Logger that writes one `[roon-call] {json}` line per call to stderr (or any
+ * injected sink, for tests). Undefined fields are dropped to keep lines compact.
+ */
+export declare function createStderrLogger(sink?: (line: string) => void): RoonCallLogger;

package/dist/logger.js

@@ -0,0 +1,56 @@
+// Structured, per-call logging for Roon API calls (Milestone 5 hardening).
+//
+// stdout is reserved for the MCP JSON-RPC stream, so every diagnostic line goes
+// to stderr. Each Roon API call (browse / load / get_zones / change_settings)
+// is wrapped in `call(...)`, which emits one compact JSON line on completion —
+// success or failure — including the elapsed time. Retries therefore show up
+// naturally as repeated lines for the same op.
+/** A no-op logger: runs the call without emitting anything. Default in tests. */
+export const silentLogger = {
+    call: (_op, _params, fn) => fn(),
+};
+/**
+ * Logger that writes one `[roon-call] {json}` line per call to stderr (or any
+ * injected sink, for tests). Undefined fields are dropped to keep lines compact.
+ */
+export function createStderrLogger(sink = (line) => void process.stderr.write(line)) {
+    return {
+        async call(op, params, fn, summarize) {
+            const started = Date.now();
+            try {
+                const result = await fn();
+                sink(format({
+                    lvl: "info",
+                    op,
+                    ms: Date.now() - started,
+                    params,
+                    result: summarize ? summarize(result) : undefined,
+                }));
+                return result;
+            }
+            catch (err) {
+                const e = err;
+                sink(format({
+                    lvl: "error",
+                    op,
+                    ms: Date.now() - started,
+                    params,
+                    error: {
+                        code: typeof e?.code === "string" ? e.code : undefined,
+                        message: typeof e?.message === "string" ? e.message : String(err),
+                    },
+                }));
+                throw err;
+            }
+        },
+    };
+}
+function format(record) {
+    const clean = { t: new Date().toISOString() };
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined)
+            clean[key] = value;
+    }
+    return `[roon-call] ${JSON.stringify(clean)}\n`;
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,+EAA+E;AAC/E,6EAA6E;AAC7E,+CAA+C;AAwB/C,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAmB;IAC1C,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE;CACjC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA+B,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAExE,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS;YAClC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;gBAC1B,IAAI,CACF,MAAM,CAAC;oBACL,GAAG,EAAE,MAAM;oBACX,EAAE;oBACF,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;oBACxB,MAAM;oBACN,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;iBAClD,CAAC,CACH,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,GAA4C,CAAC;gBACvD,IAAI,CACF,MAAM,CAAC;oBACL,GAAG,EAAE,OAAO;oBACZ,EAAE;oBACF,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;oBACxB,MAAM;oBACN,KAAK,EAAE;wBACL,IAAI,EAAE,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;wBACtD,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;qBAClE;iBACF,CAAC,CACH,CAAC;gBACF,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,MAA+B;IAC7C,MAAM,KAAK,GAA4B,EAAE,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;IACvE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC9C,CAAC;IACD,OAAO,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC;AAClD,CAAC"}

package/dist/logger.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/logger.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createStderrLogger, silentLogger } from "./logger.js";
+function captureLogger() {
+    const lines = [];
+    return { logger: createStderrLogger((l) => lines.push(l)), lines };
+}
+/** Parse the JSON payload out of a `[roon-call] {json}\n` line. */
+function parse(line) {
+    const json = line.replace(/^\[roon-call] /, "").trimEnd();
+    return JSON.parse(json);
+}
+test("logs one info line with op, params, summary and timing on success", async () => {
+    const { logger, lines } = captureLogger();
+    const result = await logger.call("browse", { hierarchy: "search", item_key: "k1" }, async () => ({ action: "list" }), (r) => ({ action: r.action }));
+    assert.deepEqual(result, { action: "list" });
+    assert.equal(lines.length, 1);
+    const rec = parse(lines[0]);
+    assert.equal(rec.lvl, "info");
+    assert.equal(rec.op, "browse");
+    assert.deepEqual(rec.params, { hierarchy: "search", item_key: "k1" });
+    assert.deepEqual(rec.result, { action: "list" });
+    assert.equal(typeof rec.ms, "number");
+    assert.equal(typeof rec.t, "string");
+});
+test("logs an error line and rethrows the original error", async () => {
+    const { logger, lines } = captureLogger();
+    const boom = Object.assign(new Error("kaboom"), { code: "BROWSE_FAILED" });
+    await assert.rejects(logger.call("load", { offset: 0 }, async () => {
+        throw boom;
+    }), (e) => e === boom);
+    assert.equal(lines.length, 1);
+    const rec = parse(lines[0]);
+    assert.equal(rec.lvl, "error");
+    assert.equal(rec.op, "load");
+    assert.deepEqual(rec.error, { code: "BROWSE_FAILED", message: "kaboom" });
+});
+test("omits the result field when no summarizer is given", async () => {
+    const { logger, lines } = captureLogger();
+    await logger.call("get_zones", {}, async () => ({ zones: [] }));
+    const rec = parse(lines[0]);
+    assert.ok(!("result" in rec));
+});
+test("silentLogger runs the call but emits nothing", async () => {
+    let ran = false;
+    const out = await silentLogger.call("browse", {}, async () => {
+        ran = true;
+        return 7;
+    });
+    assert.equal(ran, true);
+    assert.equal(out, 7);
+});
+//# sourceMappingURL=logger.test.js.map

package/dist/logger.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.test.js","sourceRoot":"","sources":["../src/logger.test.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+export type MusicItemType = "artist" | "album" | "track" | "genre" | "playlist" | "radio" | "unknown";
+export type ZoneState = "playing" | "paused" | "stopped" | "loading" | "unknown";
+export interface RoonZone {
+    zoneId: string;
+    displayName: string;
+    state: ZoneState;
+    outputIds: string[];
+    isDefaultCandidate: boolean;
+}
+export interface SearchMusicInput {
+    query: string;
+    type?: MusicItemType;
+    limit?: number;
+    /** When true and type is "genre", also sample a track mix from streaming services (e.g. TIDAL). */
+    includeStreaming?: boolean;
+}
+export interface MusicCandidate {
+    itemKey: string;
+    title: string;
+    subtitle?: string;
+    type: MusicItemType;
+    score: number;
+    available: boolean;
+    sourceGroup?: string;
+}
+export interface SearchMusicOutput {
+    query: string;
+    candidates: MusicCandidate[];
+    broadened: boolean;
+    message?: string;
+}
+export interface GetTracksForInput {
+    /** Opaque, session-scoped item key from a recent `search_music` result. */
+    itemKey: string;
+    limit?: number;
+}
+export interface TrackCandidate {
+    itemKey: string;
+    title: string;
+    artist?: string;
+    album?: string;
+    durationSec?: number;
+    available: boolean;
+}
+export interface GetTracksForOutput {
+    sourceItemKey: string;
+    tracks: TrackCandidate[];
+    skipped: Array<{
+        itemKey?: string;
+        reason: string;
+    }>;
+}
+export interface PlayNowInput {
+    /**
+     * Zone id or any of its output ids (from `list_zones`). Optional: when
+     * omitted the server falls back to the configured default zone
+     * (`ROON_DEFAULT_ZONE`), then to the single/Office/playing heuristics.
+     */
+    zoneId?: string;
+    /** Opaque, session-scoped item key from a recent `search_music` result. */
+    itemKey: string;
+    shuffle?: boolean;
+}
+export interface EnqueueAndPlayInput {
+    /** Zone id or output id (from `list_zones`); see `PlayNowInput.zoneId`. */
+    zoneId?: string;
+    /** Ordered, session-scoped item keys (e.g. from `get_tracks_for`). */
+    itemKeys: string[];
+    shuffle?: boolean;
+}
+export interface PlaybackResult {
+    ok: boolean;
+    zoneId: string;
+    /** Items started/queued by this call. `play_now` queues exactly one. */
+    queued: number;
+    skipped: Array<{
+        itemKey: string;
+        reason: string;
+    }>;
+    /** Best-effort "now playing" line read just after the action; may be stale. */
+    nowPlaying?: string;
+    message?: string;
+}
+export interface EnqueueAndPlayOutput extends PlaybackResult {
+    /** Number of item keys the caller asked to queue. */
+    requested: number;
+}
+export type RoonMcpErrorCode = "NO_CORE_PAIRED" | "ZONE_NOT_FOUND" | "ZONE_AMBIGUOUS" | "BROWSE_FAILED" | "INVALID_ITEM_KEY" | "NO_SEARCH_RESULTS" | "NO_PLAYABLE_ITEMS" | "NO_PLAY_ACTION" | "ACTION_FAILED" | "PARTIAL_QUEUE";
+export declare class RoonMcpError extends Error {
+    readonly code: RoonMcpErrorCode;
+    readonly details?: unknown | undefined;
+    constructor(code: RoonMcpErrorCode, message: string, details?: unknown | undefined);
+}

package/dist/types.js

@@ -0,0 +1,13 @@
+// Public domain types shared across services and MCP tool boundaries.
+// Kept aligned with the implementation plan's TypeScript interfaces.
+export class RoonMcpError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "RoonMcpError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,qEAAqE;AAmHrE,MAAM,OAAO,YAAa,SAAQ,KAAK;IAEnB;IAEA;IAHlB,YACkB,IAAsB,EACtC,OAAe,EACC,OAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAkB;QAEtB,YAAO,GAAP,OAAO,CAAU;QAGjC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}