nixamp 0.28.45 → 0.30.1

package/src/server.ts

@@ -9,7 +9,9 @@
  * a WebSocket because SSE is plain HTTP: no dependency, and it reconnects on
  * its own when the laptop running the remote goes to sleep.
  */
-import { createReadStream, statSync } from "node:fs";
+import { publishChoice, shouldRecord } from "./publish-choice.ts";
+import { protocolArgs } from "./decoder-policy.ts";
+import { createReadStream, existsSync, statSync } from "node:fs";
 import { createServer as createHttpServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { createServer as createHttpsServer } from "node:https";
 import { randomBytes } from "node:crypto";
@@ -34,7 +36,7 @@ import {
 import { Ingest, normaliseFormat } from "./ingest.ts";
 import {
   BACKLOG_SECONDS, Channels, cleanId, generatedId, rememberChannels, rememberedChannels, rememberedNow,
-  type Channel, type ChannelInfo, type RememberedChannel,
+  type Channel, type ChannelInfo, type PullResume, type RememberedChannel,
 } from "./channels.ts";
 import { RtmpListeners } from "./rtmp-in.ts";
 import { Accounts, clearedCookie, sessionCookie, tokenFrom } from "./accounts.ts";
@@ -68,6 +70,11 @@ import { Directory, ENDED_TTL_MS, parseAnnouncement, type LineupEntry, type List
 import { ArtCache, coverArtOf, stillFrom } from "./art.ts";
 import { PartyLine, telnyxSms } from "./partyline.ts";
 import { HlsPackagers, segmentType, withKey } from "./hls.ts";
+import { refusedDestination } from "./destinations.ts";
+import { handleStations, isStationListenPath } from "./station-routes.ts";
+import { STATION_PAGE, STATION_PAGE_CSP, STATION_PAGE_HTML } from "./station-page.ts";
+import { StationRunner } from "./station-runner.ts";
+import { StationError, StationStore, channelOf, stationOfChannel, type Station } from "./stations.ts";
 import { CompressionService } from "./compression/service.ts";
 import { handleChannelCompression, handleCompressionApi, handleStaticRelay, type RouteContext } from "./compression/routes.ts";
 import { DEFAULT_SITE as NICHEDB, Enricher, type EnrichKind, FIXTURE_TTL_MS } from "./enrich.ts";
@@ -86,7 +93,7 @@ import { Porkbun, isIPv4, isIPv6, type DnsZone } from "./dns.ts";
 import { NameError, Names } from "./names.ts";
 import { AcmeIssuer, Certs } from "./certs.ts";
 import { claimName, fetchCert, humanizeSource, labelFor, readCertFiles, writeCertFiles } from "./naming.ts";
-import { forbiddenLibrary, readLibrary } from "./library.ts";
+import { forbiddenLibrary, readConfig, readLibrary, writeConfig } from "./library.ts";
 import { createThrottle, presentedCredential, type Throttle } from "@profullstack/throttle";
 import { Durable } from "./durable.ts";
 import { notifyAll, resendEmail, webPush, type Notification } from "./notify.ts";
@@ -1109,6 +1116,64 @@ export interface KnownSource {
   /** A picture and a line about it, from the site or the list that named it. */
   art?: string;
   about?: string;
+  /** A station's rotation (see PullResume.rotation). */
+  rotation?: PullResume["rotation"];
+  /** kbps for an audio rendition; 192 when unset. */
+  audioBitrate?: number;
+}
+
+/**
+ * A station's files, chosen by track index (as /api/folders/live takes them)
+ * or by a folder under the library; null when neither was given. Only files
+ * on this machine and inside the library: a station never reaches past it.
+ */
+export function selectStationFiles(engine: Engine, body: { items?: unknown; folder?: unknown }): string[] | null {
+  const root = engine.snapshot(false).root;
+  if (Array.isArray(body.items)) {
+    const indices = [...new Set(body.items.filter((one): one is number => Number.isInteger(one) && one >= 0))];
+    const files = indices.map((index) => engine.trackPath(index)).filter((one): one is string => typeof one === "string" && !isRemote(one));
+    if (indices.length !== body.items.length || files.length !== indices.length) {
+      throw new StationError("unknown_items", "one or more of those tracks are not files in this library");
+    }
+    return files;
+  }
+  if (typeof body.folder === "string") {
+    const folder = body.folder.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+    if (folder.split("/").includes("..")) throw new StationError("invalid_folder", "a folder inside the library, please");
+    const files: string[] = [];
+    const count = engine.snapshot(false).trackCount;
+    for (let index = 0; index < count; index++) {
+      const file = engine.trackPath(index);
+      if (!file || isRemote(file)) continue;
+      const served = relative(root, file).replaceAll("\\", "/");
+      if (served.startsWith("../")) continue;
+      if (folder === "" || served.startsWith(`${folder}/`)) files.push(file);
+    }
+    if (files.length === 0) throw new StationError("empty_folder", "that folder has no files that play");
+    return files;
+  }
+  return null;
+}
+
+const tracksByPath = new WeakMap<Engine, { revision: number; byPath: Map<string, { title: string; artist: string; album: string }> }>();
+
+/** What the library knows about one file: its tags, for a now-playing line. */
+export function trackFor(engine: Engine, file: string): { title: string; artist: string; album: string } | null {
+  const revision = engine.snapshot(false).revision;
+  let index = tracksByPath.get(engine);
+  if (!index || index.revision !== revision) {
+    const tracks = engine.snapshot().tracks ?? [];
+    const byPath = new Map<string, { title: string; artist: string; album: string }>();
+    tracks.forEach((track, at) => {
+      const path = engine.trackPath(at);
+      // Tags only: a title that is the file's own name is not a tag.
+      const named = track.title && !looksLikeFileName(track.title) ? track.title : "";
+      if (path) byPath.set(path, { title: named, artist: track.artist ?? "", album: track.album ?? "" });
+    });
+    index = { revision, byPath };
+    tracksByPath.set(engine, index);
+  }
+  return index.byPath.get(file) ?? null;
 }
 
 /** How many times a source that answers nothing is asked, and how far apart. */
@@ -1187,7 +1252,7 @@ export async function pullChannel(
       ]
     // No picture in it, so none is invented: MP3 is the thing every browser
     // plays and the thing a listener can join halfway through.
-    : ["-vn", "-c:a", "libmp3lame", "-b:a", "192k", "-f", "mp3"];
+    : ["-vn", "-c:a", "libmp3lame", "-b:a", `${known.audioBitrate ?? 192}k`, "-f", "mp3"];
   // A transport stream is read further into before it is decoded, and given
   // the timestamps a recording cut mid-stream does not carry. Ahead of the
   // caller's own input arguments, which are headers for the address itself.
@@ -1198,7 +1263,7 @@ export async function pullChannel(
   const tagged = looksLikeFileName(name) && codecs.tags?.title ? codecs.tags.title : name;
   const channel = channels.pull(
     id, tagged, source, encode, kind, true, undefined, opening, kind === "video" ? audio : "",
-    { live, position: known.position ?? 0, ...(playlist ? { playlist, playlistAt: known.playlistAt ?? 0 } : {}) },
+    { live, position: known.position ?? 0, ...(playlist ? { playlist, playlistAt: known.playlistAt ?? 0 } : {}), ...(known.rotation ? { rotation: known.rotation } : {}) },
     // Known before the first dial: whether the source is a transport stream
     // decides whether it can be read here for a source-boundary relay.
     assumed ? undefined : codecs,
@@ -1641,6 +1706,8 @@ async function readBytes(request: IncomingMessage, limit: number): Promise<Uint8
 }
 
 export interface HandlerOptions {
+  /** This server's stations and what keeps them on the air. */
+  stations?: { store: StationStore; runner: StationRunner };
   web: string | null;
   /** Branded clients on this same backend, keyed by an explicitly configured host. */
   webSites?: ReadonlyMap<string, import("./web-sites.ts").WebSite>;
@@ -1976,7 +2043,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
         json(response, 404, { error: "not found" });
         return;
       }
-      response.writeHead(302, { ...CORS, "set-cookie": keyCookie(offered), location: "/" });
+      response.writeHead(302, { ...CORS, "set-cookie": keyCookie(offered, (request.socket as { encrypted?: boolean }).encrypted === true || (options.secureCookies ?? false)), location: "/" });
       response.end();
       return;
     }
@@ -2563,14 +2630,23 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
     // port is open from another device before wondering whether the link is
     // wrong, and it says nothing about the library.
     const eventChannelRequest = Boolean(channelId && await eventForChannel());
+    // Whether this request holds only the listen key. A listener may browse
+    // and hear the library, but where it lives on this machine is the
+    // owner's business: the absolute path names the user account and the disk.
+    let listening = false;
     if (
       key !== null &&
       path !== "/api/health" &&
       path !== "/api/directory" &&
       !isSignInPath(path) &&
+      // A station's link is its own key, checked by the station.
+      !isStationListenPath(path) &&
+      !STATION_PAGE.test(path) &&
       !eventChannelRequest
     ) {
       let scope = scopeOf(keyFrom(request, url), key, listenKey);
+      // Kept for the routes below that answer a listener with less.
+      const settle = (): void => { listening = scope === "listen"; };
       // A key is how somebody who was invited proves it. It is not the only way
       // to be allowed in: the person who owns this server is allowed in whether
       // or not they still have the link, and their nixamp.com session says who
@@ -2596,12 +2672,63 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
         });
         return;
       }
+      settle();
       if (scope === "listen" && !allowedForListening(path)) {
         json(response, 403, { error: "this link can listen, not drive" });
         return;
       }
     }
 
+    // Whether this request may administer: the control key, an open server,
+    // or the owner's nixamp.com session. Asked by the routes that do not go
+    // through the admin gate further down.
+    const controlOf = async (): Promise<{ allowed: boolean; account: string }> => {
+      if (key === null) return { allowed: true, account: "" };
+      if (scopeOf(keyFrom(request, url), key, listenKey) === "control") return { allowed: true, account: "" };
+      if (options.owner) {
+        const session = tokenFrom(request.headers) || url.searchParams.get("session") || "";
+        if (session !== "" && (await options.owner.check(false, session)).allowed) {
+          return { allowed: true, account: (await options.owner.accountFor(session)) || "" };
+        }
+      }
+      return { allowed: false, account: "" };
+    };
+
+    // The page a station's link opens. The same bytes for every station: it
+    // reads its id and token from its own address.
+    if (options.stations && STATION_PAGE.test(path) && (request.method === "GET" || request.method === "HEAD")) {
+      response.writeHead(200, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-cache",
+        "content-security-policy": STATION_PAGE_CSP,
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+      });
+      response.end(request.method === "HEAD" ? undefined : STATION_PAGE_HTML);
+      return;
+    }
+
+    if (options.stations && (path === "/api/v1/stations" || path.startsWith("/api/v1/stations/"))) {
+      const control = await controlOf();
+      const encrypted = (request.socket as { encrypted?: boolean }).encrypted === true;
+      const forwarded = behindProxy ? String(request.headers["x-forwarded-proto"] ?? "").split(",")[0]?.trim() : "";
+      const scheme = forwarded === "https" || encrypted ? "https" : "http";
+      await handleStations(request, response, path, url, {
+        store: options.stations.store,
+        runner: options.stations.runner,
+        channels: options.channels!,
+        canControl: control.allowed,
+        account: control.account,
+        select: (body) => selectStationFiles(engine, body),
+        trackFor: (file) => trackFor(engine, file),
+        base: `${scheme}://${request.headers.host ?? "localhost"}`,
+        json,
+        readBody,
+        headers: CORS,
+      });
+      return;
+    }
+
     if (path === "/api/health") {
       json(response, 200, { name: "nixamp", version: options.version, media: options.media });
       return;
@@ -4258,7 +4385,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
           // offering something that always failed.
           carries: options.carries !== false && Boolean(options.channels),
         },
-        channels: (options.channels?.list() ?? []).map((one) => ({
+        channels: (options.channels?.list() ?? []).filter((one) => !stationOfChannel(one.id)).map((one) => ({
           id: one.id,
           name: one.name,
           via: one.via,
@@ -4631,11 +4758,32 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
         json(response, 429, { error: `this server is already carrying ${MAX_ON_DEMAND} channels on demand; try again in a minute` });
         return;
       }
-      const resolved = known ?? await resolveLink(options.ytdlp ?? null, link, { cookies: options.cookies ?? "" });
+      // A member's link is fetched from inside the owner's network, so it has
+      // to lead somewhere public: the link, every hop of a playlist, and
+      // whatever yt-dlp says the media is. The owner's is theirs to aim.
+      const guard = liveBy && !known ? (one: string) => refusedDestination(one) : undefined;
+      if (guard) {
+        const refused = await guard(link);
+        if (refused) {
+          json(response, 403, { error: refused });
+          return;
+        }
+      }
+      const resolved = known ?? await resolveLink(options.ytdlp ?? null, link, { cookies: options.cookies ?? "", guard });
       if ("error" in resolved) {
-        json(response, 422, { error: resolved.error });
+        json(response, guard && resolved.error.includes("private network") ? 403 : 422, { error: resolved.error });
         return;
       }
+      if (guard) {
+        const reached = [resolved.media, resolved.audio, ...(resolved.playlist ?? [])].filter((one) => one && /^(https?|rtmps?):\/\//i.test(one));
+        for (const one of [...new Set(reached)].slice(0, 200)) {
+          const refused = await guard(one);
+          if (refused) {
+            json(response, 403, { error: refused });
+            return;
+          }
+        }
+      }
       links.set(link, resolved);
       // A channel already on -- put back by a restart, which forgets where
       // it came from -- learns its picture and its line from the link pasted
@@ -4868,7 +5016,8 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       // on, and the address a channel is pulled from is the one thing about
       // it that is not theirs to have.
       json(response, 200, {
-        channels: options.channels.list().map(({ source: _source, ...shown }) => shown),
+        // Stations answer for themselves, under /api/v1/stations.
+        channels: options.channels.list().filter((one) => !stationOfChannel(one.id)).map(({ source: _source, ...shown }) => shown),
         listeners: options.channels.listeners,
       });
       return;
@@ -4881,6 +5030,12 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       const rest = path.slice("/api/channels/".length);
       const [rawId, action, file] = rest.split("/");
       const id = cleanId(rawId);
+      // A station's channel is heard through the station's own link, which
+      // knows whether it is private. Through here, only by its owner.
+      if (stationOfChannel(id) && !(await controlOf()).allowed) {
+        json(response, 404, { error: "nothing is playing on that channel" });
+        return;
+      }
       const event = await eventForChannel();
       if (event) {
         const account = await options.accounts?.whoIs(tokenFrom(request.headers)) ?? null;
@@ -5494,7 +5649,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
     }
 
     if (path === "/api/state") {
-      json(response, 200, engine.snapshot());
+      json(response, 200, listening ? { ...engine.snapshot(), root: "" } : engine.snapshot());
       return;
     }
 
@@ -5562,7 +5717,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
         "x-accel-buffering": "no",
       });
       const send = (snapshot: Snapshot): void => {
-        response.write(`data: ${JSON.stringify(snapshot)}\n\n`);
+        response.write(`data: ${JSON.stringify(listening ? { ...snapshot, root: "" } : snapshot)}\n\n`);
       };
       const unsubscribe = engine.subscribe(send);
       // A comment line keeps proxies from closing an idle stream.
@@ -6039,6 +6194,7 @@ async function liveAudio(
         // A live source has no beginning to seek from.
         ...(from > 1 && !isRemote(source) ? ["-ss", String(from)] : []),
         "-re",
+        ...protocolArgs(source),
         "-i", source,
         ...(asVideo
           // Copied where it can be, because a room full of viewers is a room
@@ -6157,6 +6313,7 @@ function pipeFfmpeg(
       // when they are handed to it for a file on disk.
       ...(isRemote(source) ? ["-reconnect", "1", "-reconnect_streamed", "1", "-reconnect_delay_max", "5"] : []),
       ...inputArgs,
+      ...protocolArgs(source),
       "-i", source,
       ...outputArgs,
       "-",
@@ -6341,6 +6498,10 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   // still works after a restart -- and a server is restarted to pick up a new
   // version, which is to say often. `--new-key` mints a fresh pair and forgets
   // the old one, which is the way to revoke a link that got out.
+  // Whether this port had keys before this start: a server that has run
+  // here before, whose directory listing (see publishChoice) is kept.
+  const established = existsSync(join(stateDir(), "keys.json")) &&
+    (() => { try { return String(options.port) in (JSON.parse(readFileSync(join(stateDir(), "keys.json"), "utf8")) as object); } catch { return false; } })();
   const remembered = options.key ? rememberedKeys(stateDir(), options.port, options.newKey) : null;
   const key = remembered?.key ?? null;
   // Kept whether or not it is published, so `nixamp admin` and the operator
@@ -6373,6 +6534,9 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   // same ffmpeg that carries the channels. No ffmpeg, no outro, and a show
   // that ends closes its channel as before.
   const outro = new Outro({ ffmpeg: tools.ffmpeg, dir: join(stateDir(), "outro"), onEvent: (message) => console.log(message) });
+  // Made once the channels exist; told of every channel that ends, so a
+  // station that died is brought back and one that was stopped is not.
+  let stationRunner: StationRunner | null = null;
   const channels = new Channels({
     ffmpeg: tools.ffmpeg,
     ffprobe: tools.ffprobe,
@@ -6383,8 +6547,25 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     onEnd: (info) => {
       console.log(`  "${info.id}" stopped.`);
       art.forget(info.id);
+      stationRunner?.onChannelEnd(info);
     },
   });
+  const stationStore = new StationStore(StationStore.fileFor(stateDir(), options.port));
+  stationRunner = new StationRunner({
+    store: stationStore,
+    channels,
+    pull: async (channelId, name, files, known) =>
+      Boolean(await pullChannel(channels, tools.ffprobe, channelId, name, files[0]!, [], "", {
+        playlist: files,
+        live: true,
+        rotation: known.rotation,
+        audioBitrate: known.audioBitrate,
+      })),
+    // The library as it is now, or as it was chosen while it is still being read.
+    roots: () => [engine.snapshot(false).root || chosen].filter((one) => one !== ""),
+    log: (line) => console.log(line),
+  });
+  const stations = { store: stationStore, runner: stationRunner };
   // Channels as HLS, on demand, for Safari on a phone: one ffmpeg copying a
   // channel's fragments into short files while somebody is asking for them.
   // What things are, from nichedb.dev, remembered beside the keys so a
@@ -6433,6 +6614,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
       if (!channel) console.log(`  "${one.id}" is already on.`);
     });
   }
+  stationRunner.restore();
   // Where each film has got to, written down every so often, so a restart
   // picks it up from about there rather than from the start. Only when it
   // has changed: a server carrying nothing but live television writes
@@ -6975,6 +7157,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     media: options.media,
     owner,
     channels,
+    stations,
     rememberChannels: remembering,
     catalogs,
     publishUrls: () => publishUrls,
@@ -7404,6 +7587,12 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
    * A declaration rather than an assignment, so it exists from the moment the
    * function is entered -- the port is open well before this line is reached.
    */
+  /** The station behind this channel, when its owner made it public and listed it. */
+  function listedStation(channelId: string): Station | undefined {
+    const station = stationStore.get(stationOfChannel(channelId));
+    return station && station.visibility === "public" && station.listed ? station : undefined;
+  }
+
   function makePublisher(): Publisher | null {
     if (!publishable_) return null;
     const listen = shareLink(publishable_.url, listenKey, false);
@@ -7427,10 +7616,20 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
         // which channels are on. A directory row that says "5,717 files,
         // live: CNN" is one somebody can decide about; "5717 tracks" was not.
         playing: () => engine.snapshot(false).playing,
-        channels: () => channels.list().map((one) => one.name),
+        // Stations only when their owner listed them; every other channel as before.
+        channels: () => channels.list().filter((one) => !stationOfChannel(one.id) || listedStation(one.id)).map((one) => one.name),
         // The same with what a link preview needs: the id a join link names
         // a channel by, a picture, a line.
-        lineup: () => channels.list().map((one) => lineupEntry(listen, one)),
+        lineup: () => channels.list()
+          .filter((one) => !stationOfChannel(one.id) || listedStation(one.id))
+          .map((one) => {
+            const entry = lineupEntry(listen, one);
+            const station = listedStation(one.id);
+            // A station is listened to through its own link, never the server's.
+            return station
+              ? { ...entry, listen: `${publishable_!.url}/station/${station.id}?t=${encodeURIComponent(station.listenToken)}` }
+              : entry;
+          }),
         // From `nixamp login`. The directory will not list a stream it cannot
         // attribute to somebody, because a listing is now a phone code that
         // costs money to answer.
@@ -7475,10 +7674,20 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     // public at all.
     //
     // Still asked when a person is at the terminal to answer, because that is
-    // somebody who can say no.
-    const wanted = options.publish === "yes" || !process.stdin.isTTY
-      ? true
-      : await confirm(`\n  List this stream at ${DEFAULT_DIRECTORY}/directory so anyone can find it?\n  It publishes ${listen} — listen only, not the controls.`);
+    // somebody who can say no -- and since 0.29 the answer is kept, so a
+    // daemon started later does what the person said, not what it guesses.
+    const recorded = readConfig().publish;
+    const choice = publishChoice(options.publish, recorded, Boolean(process.stdin.isTTY), established);
+    const wanted = choice === "ask"
+      ? await confirm(`\n  List this stream at ${DEFAULT_DIRECTORY}/directory so anyone can find it?\n  It publishes ${listen} — listen only, not the controls.`)
+      : choice === "yes";
+    if (shouldRecord(options.publish, recorded)) {
+      try { writeConfig({ publish: wanted }); } catch { /* unwritable state: asked again next time */ }
+    }
+    if (!wanted && options.publish === "ask") {
+      console.log("");
+      console.log(`  Not listed at ${DEFAULT_DIRECTORY}/directory. Start with --publish to list it.`);
+    }
 
     if (wanted) {
       publisher = makePublisher();

package/src/share.ts

@@ -136,11 +136,12 @@ export function keyFrom(request: IncomingMessage, url: URL): string | null {
 }
 
 /** The Set-Cookie for a browser that just opened the link. */
-export function keyCookie(key: string): string {
+export function keyCookie(key: string, secure = false): string {
   // HttpOnly because nothing in the page reads it: the browser attaches it to
-  // every same-origin request by itself. No Secure, because the whole point is
-  // a plain-http address on your own network.
-  return `${KEY_COOKIE}=${encodeURIComponent(key)}; Path=/; Max-Age=31536000; SameSite=Lax; HttpOnly`;
+  // every same-origin request by itself. Secure only when the link was opened
+  // over https: a plain-http address on your own network is still a thing,
+  // and a Secure cookie there would never be sent back.
+  return `${KEY_COOKIE}=${encodeURIComponent(key)}; Path=/; Max-Age=31536000; SameSite=Lax; HttpOnly${secure ? "; Secure" : ""}`;
 }
 
 /**

package/src/station-cli.ts

@@ -0,0 +1,195 @@
+/**
+ * `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.ts";
+import { readState } from "./daemon.ts";
+import { KEY_HEADER } from "./share.ts";
+
+import { USAGE } from "./station-usage.ts";
+
+export { USAGE };
+
+function flag(argv: string[], name: string): string | undefined {
+  const at = argv.indexOf(name);
+  return at === -1 ? undefined : argv[at + 1];
+}
+
+function has(argv: string[], name: string): boolean {
+  return argv.includes(name);
+}
+
+interface Answer {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+class Unreachable extends Error {}
+
+export async function station(argv: string[]): Promise<number> {
+  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 as Error).message);
+    return 3;
+  }
+  const headers: Record<string, string> = { "content-type": "application/json", ...(target.key ? { [KEY_HEADER]: target.key } : {}) };
+  const call = async (method: string, path: string, body?: unknown): Promise<Answer> => {
+    let response: 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 as Error).message}`);
+    }
+    const text = await response.text();
+    let parsed: Record<string, unknown> = {};
+    try { parsed = JSON.parse(text) as Record<string, unknown>; } catch { parsed = { error: text }; }
+    return { status: response.status, body: parsed };
+  };
+  const needId = (): string | null => {
+    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: Answer, line: (body: Record<string, unknown>) => string): number => {
+    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: Record<string, unknown>): string => {
+    const links = (station["links"] ?? {}) as Record<string, string>;
+    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"] as unknown[] | undefined)?.length ?? 0} files at ${String(station["bitrate"])} kbps`,
+      ...(station["error"] ? [`  problem     ${String(station["error"])}`] : []),
+      ...((station["excluded"] as unknown[] | undefined)?.length ? [`  left out   ${(station["excluded"] as unknown[]).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"] as Record<string, unknown>[] | undefined) ?? [];
+          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"] as Record<string, unknown>)}`);
+      }
+      case "show":
+      case "status": {
+        const station = needId();
+        if (!station) return 2;
+        return show(await call("GET", `/api/v1/stations/${station}`), (body) => describe(body["station"] as Record<string, unknown>));
+      }
+      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"] as Record<string, unknown>));
+      }
+      case "publish": {
+        const station = needId();
+        if (!station) return 2;
+        const basis = flag(argv, "--basis");
+        const unlisted = has(argv, "--unlisted");
+        const access: Record<string, unknown> = {
+          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"] as Record<string, unknown>));
+      }
+      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"] as Record<string, unknown>)}${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"] as Record<string, unknown>)["links"] ?? {}) as Record<string, string>;
+          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;
+  }
+}