nixamp 0.29.1 → 0.30.3

package/dist/station-cli.js

@@ -0,0 +1,201 @@
+/**
+ * `nixamp station`: stations from a terminal, a script or a cron job.
+ *
+ * Talks to the daemon on this machine with its control key, or to another
+ * server with --url and --key, exactly as `nixamp admin` does. Every command
+ * takes --json for a script; without it, a line a person can read. Exit codes
+ * a script can branch on: 0 done, 1 the server said no (the reason and a
+ * stable code are printed), 2 the command was wrong, 3 the server could not
+ * be reached.
+ *
+ * Nothing here publishes as a side effect. `create` and `start` leave a
+ * station private; `publish` is its own command and says on what basis.
+ */
+import { resolveTarget } from "./admin.js";
+import { readState } from "./daemon.js";
+import { KEY_HEADER } from "./share.js";
+import { USAGE } from "./station-usage.js";
+export { USAGE };
+function flag(argv, name) {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+}
+function has(argv, name) {
+    return argv.includes(name);
+}
+class Unreachable extends Error {
+}
+export async function station(argv) {
+    const [command, id] = argv;
+    const json = has(argv, "--json");
+    if (!command || command === "help" || has(argv, "--help")) {
+        console.log(USAGE);
+        return command ? 0 : 2;
+    }
+    let target;
+    try {
+        target = resolveTarget(argv);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 3;
+    }
+    const headers = { "content-type": "application/json", ...(target.key ? { [KEY_HEADER]: target.key } : {}) };
+    const call = async (method, path, body) => {
+        let response;
+        try {
+            response = await fetch(`${target.url}${path}`, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+        }
+        catch (error) {
+            throw new Unreachable(`could not reach ${target.url}: ${error.message}`);
+        }
+        const text = await response.text();
+        let parsed = {};
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = { error: text };
+        }
+        return { status: response.status, body: parsed };
+    };
+    const needId = () => {
+        if (!id || id.startsWith("--")) {
+            console.error(`nixamp station ${command} needs a station id. \`nixamp station list\` shows them.`);
+            return null;
+        }
+        return id;
+    };
+    const show = (answer, line) => {
+        if (json) {
+            console.log(JSON.stringify(answer.body, null, 2));
+        }
+        else if (answer.status < 400) {
+            console.log(line(answer.body));
+        }
+        if (answer.status >= 400) {
+            if (!json)
+                console.error(`nixamp: ${String(answer.body["error"] ?? "refused")} (${String(answer.body["code"] ?? answer.status)})`);
+            return 1;
+        }
+        return 0;
+    };
+    const describe = (station) => {
+        const links = (station["links"] ?? {});
+        return [
+            `${String(station["name"])}  [${String(station["id"])}]`,
+            `  state       ${String(station["state"])} (wanted ${String(station["desired"])})`,
+            `  visibility  ${String(station["visibility"])}${station["listed"] ? ", listed in the directory" : ""}`,
+            `  rotation    ${station["shuffle"] ? "shuffle" : "in order"}${station["repeat"] ? ", repeating" : ", once"}; ${station["items"]?.length ?? 0} files at ${String(station["bitrate"])} kbps`,
+            ...(station["error"] ? [`  problem     ${String(station["error"])}`] : []),
+            ...(station["excluded"]?.length ? [`  left out   ${station["excluded"].length} files (nixamp station retry)`] : []),
+            ...(station["visibility"] !== "private" && links["page"] ? [`  listen      ${links["page"]}`] : []),
+        ].join("\n");
+    };
+    try {
+        switch (command) {
+            case "list": {
+                const answer = await call("GET", "/api/v1/stations?limit=200");
+                return show(answer, (body) => {
+                    const all = body["stations"] ?? [];
+                    return all.length === 0 ? "No stations yet. nixamp station create --name NAME --folder PATH" : all.map(describe).join("\n\n");
+                });
+            }
+            case "create": {
+                const name = flag(argv, "--name");
+                if (!name) {
+                    console.error("nixamp station create needs --name");
+                    return 2;
+                }
+                const items = flag(argv, "--items");
+                let folder = flag(argv, "--folder");
+                if (folder !== undefined) {
+                    // A path under the library is taken relative to it.
+                    const root = readState()?.source ?? "";
+                    if (root && folder.startsWith(root))
+                        folder = folder.slice(root.length);
+                }
+                if (items === undefined && folder === undefined) {
+                    console.error("nixamp station create needs --folder PATH or --items 0,1,2");
+                    return 2;
+                }
+                const bitrate = flag(argv, "--bitrate");
+                const answer = await call("POST", "/api/v1/stations", {
+                    name,
+                    ...(items !== undefined ? { items: items.split(",").map((one) => Number(one.trim())) } : { folder }),
+                    shuffle: has(argv, "--shuffle"),
+                    repeat: !has(argv, "--no-repeat"),
+                    ...(bitrate ? { bitrate: Number(bitrate) } : {}),
+                });
+                return show(answer, (body) => `Made (private, stopped):\n${describe(body["station"])}`);
+            }
+            case "show":
+            case "status": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                return show(await call("GET", `/api/v1/stations/${station}`), (body) => describe(body["station"]));
+            }
+            case "start":
+            case "stop":
+            case "skip":
+            case "retry": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                return show(await call("POST", `/api/v1/stations/${station}/${command}`, {}), (body) => describe(body["station"]));
+            }
+            case "publish": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                const basis = flag(argv, "--basis");
+                const unlisted = has(argv, "--unlisted");
+                const access = {
+                    visibility: unlisted ? "unlisted" : "public",
+                    listed: !unlisted && !has(argv, "--no-list"),
+                    ...(basis ? { rights: { basis, note: flag(argv, "--note") ?? "" } } : {}),
+                };
+                return show(await call("POST", `/api/v1/stations/${station}/access`, access), (body) => describe(body["station"]));
+            }
+            case "unpublish": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                const access = has(argv, "--private") ? { visibility: "private" } : { listed: false };
+                return show(await call("POST", `/api/v1/stations/${station}/access`, access), (body) => {
+                    const dropped = Number(body["dropped"] ?? 0);
+                    return `${describe(body["station"])}${dropped ? `\n  ${dropped} listener(s) disconnected; old links no longer work.` : ""}`;
+                });
+            }
+            case "link": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                const answer = has(argv, "--rotate")
+                    ? await call("POST", `/api/v1/stations/${station}/rotate-link`, {})
+                    : await call("GET", `/api/v1/stations/${station}`);
+                return show(answer, (body) => {
+                    const links = (body["station"]["links"] ?? {});
+                    return [`page    ${links["page"]}`, `stream  ${links["stream"]}`, `m3u     ${links["m3u"]}`].join("\n");
+                });
+            }
+            case "delete": {
+                const station = needId();
+                if (!station)
+                    return 2;
+                return show(await call("DELETE", `/api/v1/stations/${station}`), () => `Deleted ${station}. Its files were not touched.`);
+            }
+            default:
+                console.error(`nixamp station: no command "${command}".\n\n${USAGE}`);
+                return 2;
+        }
+    }
+    catch (error) {
+        if (error instanceof Unreachable) {
+            console.error(`nixamp: ${error.message}`);
+            return 3;
+        }
+        throw error;
+    }
+}

package/dist/station-mcp.d.ts

@@ -0,0 +1,294 @@
+export declare const STATION_TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            server: {
+                type: "string";
+                description: string;
+            };
+            idempotencyKey?: undefined;
+            name?: undefined;
+            description?: undefined;
+            folder?: undefined;
+            items?: undefined;
+            shuffle?: undefined;
+            repeat?: undefined;
+            bitrate?: undefined;
+            action?: undefined;
+            visibility?: undefined;
+            listed?: undefined;
+            basis?: undefined;
+            note?: undefined;
+            id?: undefined;
+            private?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            server: {
+                type: "string";
+                description: string;
+            };
+            id: {
+                type: "string";
+                description: string;
+            };
+            idempotencyKey?: undefined;
+            name?: undefined;
+            description?: undefined;
+            folder?: undefined;
+            items?: undefined;
+            shuffle?: undefined;
+            repeat?: undefined;
+            bitrate?: undefined;
+            action?: undefined;
+            visibility?: undefined;
+            listed?: undefined;
+            basis?: undefined;
+            note?: undefined;
+            private?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            server: {
+                type: "string";
+                description: string;
+            };
+            name: {
+                readonly type: "string";
+            };
+            folder: {
+                type: "string";
+                description: string;
+            };
+            items: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            description: {
+                readonly type: "string";
+            };
+            shuffle: {
+                type: string;
+            };
+            repeat: {
+                type: string;
+                description: string;
+            };
+            bitrate: {
+                type: string;
+                description: string;
+            };
+            idempotencyKey: {
+                type: "string";
+                description: string;
+            };
+            action?: undefined;
+            visibility?: undefined;
+            listed?: undefined;
+            basis?: undefined;
+            note?: undefined;
+            id?: undefined;
+            private?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            idempotencyKey?: undefined;
+            server: {
+                type: "string";
+                description: string;
+            };
+            id: {
+                type: "string";
+                description: string;
+            };
+            name: {
+                readonly type: "string";
+            };
+            description: {
+                readonly type: "string";
+            };
+            folder: {
+                readonly type: "string";
+            };
+            items: {
+                description?: undefined;
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            shuffle: {
+                type: string;
+            };
+            repeat: {
+                description?: undefined;
+                type: string;
+            };
+            bitrate: {
+                description?: undefined;
+                type: string;
+            };
+            action?: undefined;
+            visibility?: undefined;
+            listed?: undefined;
+            basis?: undefined;
+            note?: undefined;
+            private?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            idempotencyKey?: undefined;
+            name?: undefined;
+            description?: undefined;
+            folder?: undefined;
+            items?: undefined;
+            shuffle?: undefined;
+            repeat?: undefined;
+            bitrate?: undefined;
+            server: {
+                type: "string";
+                description: string;
+            };
+            id: {
+                type: "string";
+                description: string;
+            };
+            action: {
+                type: string;
+                enum: string[];
+            };
+            visibility?: undefined;
+            listed?: undefined;
+            basis?: undefined;
+            note?: undefined;
+            private?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            idempotencyKey?: undefined;
+            name?: undefined;
+            description?: undefined;
+            folder?: undefined;
+            items?: undefined;
+            shuffle?: undefined;
+            repeat?: undefined;
+            bitrate?: undefined;
+            action?: undefined;
+            server: {
+                type: "string";
+                description: string;
+            };
+            id: {
+                type: "string";
+                description: string;
+            };
+            visibility: {
+                type: string;
+                enum: string[];
+            };
+            listed: {
+                type: string;
+                description: string;
+            };
+            basis: {
+                type: string;
+                enum: string[];
+            };
+            note: {
+                readonly type: "string";
+            };
+            private?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            idempotencyKey?: undefined;
+            name?: undefined;
+            description?: undefined;
+            folder?: undefined;
+            items?: undefined;
+            shuffle?: undefined;
+            repeat?: undefined;
+            bitrate?: undefined;
+            action?: undefined;
+            visibility?: undefined;
+            listed?: undefined;
+            basis?: undefined;
+            note?: undefined;
+            server: {
+                type: "string";
+                description: string;
+            };
+            id: {
+                type: "string";
+                description: string;
+            };
+            private: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+})[];
+interface Result {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}
+export interface StationToolOptions {
+    fetcher?: typeof fetch;
+    /** Where the local daemon is and its key; the tests hand these in. */
+    local?: {
+        url: string;
+        key: string | null;
+    } | null;
+    session?: {
+        site: string;
+        token: string;
+    } | null;
+}
+export declare function isStationTool(name: string): boolean;
+export declare function callStationTool(name: string, args: Record<string, unknown>, options?: StationToolOptions): Promise<Result>;
+export {};

package/dist/station-mcp.js

@@ -0,0 +1,173 @@
+/**
+ * Stations as MCP tools: what `nixamp station` does, for an agent.
+ *
+ * The same API and the same rules as the CLI and the page. On this machine
+ * the tools use the daemon's control key, which is what being on the machine
+ * means; for another server they send this machine's nixamp.com session,
+ * which the server accepts only if that account owns it. Publishing is its
+ * own tool and asks for the basis, exactly as for a person.
+ */
+import { daemonUrl, readState } from "./daemon.js";
+import { readSession } from "./session.js";
+import { KEY_HEADER } from "./share.js";
+const STRING = { type: "string" };
+const ID = { ...STRING, description: "The station's id (10 characters), from station_list." };
+const SERVER = { ...STRING, description: "A nixamp server's address; this machine's daemon when omitted." };
+export const STATION_TOOLS = [
+    {
+        name: "station_list",
+        description: "List this server's stations: id, name, state (live, stopped, offline...), visibility and listening link.",
+        inputSchema: { type: "object", properties: { server: SERVER } },
+    },
+    {
+        name: "station_get",
+        description: "One station in full: files, rotation, state, any problem, and its links.",
+        inputSchema: { type: "object", properties: { server: SERVER, id: ID }, required: ["id"] },
+    },
+    {
+        name: "station_create",
+        description: "Make a station from a folder in the library (path relative to it, \"\" for all of it) or from track indexes. It starts private and stopped; nothing is published.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                server: SERVER,
+                name: STRING,
+                folder: { ...STRING, description: "A folder under the library, e.g. \"Albums/Late Night\"." },
+                items: { type: "array", items: { type: "integer" }, description: "Track indexes, as /api/state lists them." },
+                description: STRING,
+                shuffle: { type: "boolean" },
+                repeat: { type: "boolean", description: "Round and round (default) or once." },
+                bitrate: { type: "integer", description: "kbps: 64, 96, 128 (default), 160, 192, 256 or 320." },
+                idempotencyKey: { ...STRING, description: "Asking again with the same key returns the same station." },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "station_update",
+        description: "Rename, describe, change files or rotation. Edits to the files land on the next track.",
+        inputSchema: {
+            type: "object",
+            properties: { server: SERVER, id: ID, name: STRING, description: STRING, folder: STRING, items: { type: "array", items: { type: "integer" } }, shuffle: { type: "boolean" }, repeat: { type: "boolean" }, bitrate: { type: "integer" } },
+            required: ["id"],
+        },
+    },
+    {
+        name: "station_control",
+        description: "start, stop or skip a station, or retry the files it left out. Starting does not publish.",
+        inputSchema: {
+            type: "object",
+            properties: { server: SERVER, id: ID, action: { type: "string", enum: ["start", "stop", "skip", "retry"] } },
+            required: ["id", "action"],
+        },
+    },
+    {
+        name: "station_publish",
+        description: "Make a station unlisted (a link) or public (and listed in the nixamp.com directory). Public needs the basis on which it may be broadcast: owned, permission, licensed or public-domain. A declaration, not legal clearance.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                server: SERVER,
+                id: ID,
+                visibility: { type: "string", enum: ["unlisted", "public"] },
+                listed: { type: "boolean", description: "In the directory (public only). Default true for public." },
+                basis: { type: "string", enum: ["owned", "permission", "licensed", "public-domain"] },
+                note: STRING,
+            },
+            required: ["id", "visibility"],
+        },
+    },
+    {
+        name: "station_unpublish",
+        description: "Take a station out of the directory, or make it private: its links stop working and listeners are disconnected.",
+        inputSchema: { type: "object", properties: { server: SERVER, id: ID, private: { type: "boolean" } }, required: ["id"] },
+    },
+];
+const say = (value, isError = false) => ({ content: [{ type: "text", text: value }], ...(isError ? { isError: true } : {}) });
+export function isStationTool(name) {
+    return STATION_TOOLS.some((tool) => tool.name === name);
+}
+function line(station) {
+    const links = (station["links"] ?? {});
+    const problem = station["error"] ? `; problem: ${String(station["error"])}` : "";
+    const link = station["visibility"] !== "private" && links["page"] ? `\n  listen: ${links["page"]}` : "";
+    return `${String(station["name"])} [${String(station["id"])}] ${String(station["state"])}, ${String(station["visibility"])}${station["listed"] ? " and listed" : ""}${problem}${link}`;
+}
+export async function callStationTool(name, args, options = {}) {
+    const send = options.fetcher ?? fetch;
+    const server = typeof args["server"] === "string" ? args["server"].replace(/\/+$/, "") : "";
+    let base = server;
+    const headers = { "content-type": "application/json" };
+    if (server === "") {
+        const local = options.local === undefined ? (() => { const state = readState(); return state ? { url: daemonUrl(state), key: state.key } : null; })() : options.local;
+        if (!local)
+            return say("No nixamp daemon runs on this machine. Start one (nixamp daemon start ~/Music) or pass `server`.", true);
+        base = local.url;
+        if (local.key)
+            headers[KEY_HEADER] = local.key;
+    }
+    else {
+        const session = options.session === undefined ? readSession() : options.session;
+        if (!session)
+            return say("Another server's stations need this machine signed in as its owner: nixamp login.", true);
+        headers["authorization"] = `Bearer ${session.token}`;
+    }
+    const id = typeof args["id"] === "string" ? args["id"] : "";
+    const call = async (method, path, body) => {
+        const response = await send(`${base}${path}`, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+        const parsed = (await response.json().catch(() => ({})));
+        return { ok: response.ok, body: parsed };
+    };
+    const refused = (body) => say(`${String(body["error"] ?? "refused")} (${String(body["code"] ?? "error")})`, true);
+    const pick = (keys) => Object.fromEntries(keys.filter((key) => args[key] !== undefined).map((key) => [key, args[key]]));
+    try {
+        if (name === "station_list") {
+            const answer = await call("GET", "/api/v1/stations?limit=200");
+            if (!answer.ok)
+                return refused(answer.body);
+            const all = answer.body["stations"] ?? [];
+            return say(all.length === 0 ? "No stations on this server yet." : all.map(line).join("\n"));
+        }
+        if (!/^[a-z0-9]{10}$/.test(id) && name !== "station_create")
+            return say("Which station? Pass its id from station_list.", true);
+        if (name === "station_get") {
+            const answer = await call("GET", `/api/v1/stations/${id}`);
+            return answer.ok ? say(JSON.stringify(answer.body["station"], null, 2)) : refused(answer.body);
+        }
+        if (name === "station_create") {
+            const answer = await call("POST", "/api/v1/stations", pick(["name", "folder", "items", "description", "shuffle", "repeat", "bitrate", "idempotencyKey"]));
+            return answer.ok ? say(`Made, private and stopped: ${line(answer.body["station"])}`) : refused(answer.body);
+        }
+        if (name === "station_update") {
+            const answer = await call("PATCH", `/api/v1/stations/${id}`, pick(["name", "description", "folder", "items", "shuffle", "repeat", "bitrate"]));
+            return answer.ok ? say(line(answer.body["station"])) : refused(answer.body);
+        }
+        if (name === "station_control") {
+            const action = String(args["action"] ?? "");
+            if (!["start", "stop", "skip", "retry"].includes(action))
+                return say("action is start, stop, skip or retry", true);
+            const answer = await call("POST", `/api/v1/stations/${id}/${action}`, {});
+            return answer.ok ? say(line(answer.body["station"])) : refused(answer.body);
+        }
+        if (name === "station_publish") {
+            const visibility = args["visibility"] === "public" ? "public" : "unlisted";
+            const answer = await call("POST", `/api/v1/stations/${id}/access`, {
+                visibility,
+                listed: visibility === "public" && args["listed"] !== false,
+                ...(typeof args["basis"] === "string" ? { rights: { basis: args["basis"], note: typeof args["note"] === "string" ? args["note"] : "" } } : {}),
+            });
+            return answer.ok ? say(line(answer.body["station"])) : refused(answer.body);
+        }
+        if (name === "station_unpublish") {
+            const answer = await call("POST", `/api/v1/stations/${id}/access`, args["private"] === true ? { visibility: "private" } : { listed: false });
+            if (!answer.ok)
+                return refused(answer.body);
+            const dropped = Number(answer.body["dropped"] ?? 0);
+            return say(`${line(answer.body["station"])}${dropped ? `\n${dropped} listener(s) disconnected.` : ""}`);
+        }
+    }
+    catch (error) {
+        return say(`Could not reach ${base}: ${error.message}`, true);
+    }
+    return say(`No such tool: ${name}`, true);
+}