@khalido/home 0.2.0 → 0.2.2

package/docs/cast.md

@@ -109,7 +109,7 @@ No host: a group's host changes with its leader. All entries fold into one `cast
 - `announce(target, clip, { volume?, timeoutMs? })`, target a device or group, `clip` a URL or bytes with their type (KO's own dictation as recorded, or TTS output; the library never synthesises) served by `serveClip`. The result names each member it could not restore. Read status, set volume, launch Default Media Receiver (`CC1AD845`), `LOAD` the clip, wait for `IDLE`/`FINISHED` (with a timeout), then restore: a prior Default Media Receiver `contentId` is re-loaded at its `currentTime`, an idle device gets `STOP`, then the volume. Spotify, YouTube and other apps cannot be resumed generically (our launch ends their session); the result says so.
 - `castUrl(name, url)` launches DashCast (`84912283`, pychromecast's list) with the URL. HA casts its dashboard with its own registered receiver (`A078F6B0`), a hint at DashCast's limits. KO's own receiver costs a one-off Cast SDK fee and must be published (unpublished ones run only on serial-registered devices). Try DashCast first.
 
-**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3 or AAC; not AIFF; a 24 kHz mono WAV failed on audio-only Nest speakers, live 2026-11-09): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
+**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3 or AAC; not AIFF; a 24 kHz mono WAV failed on audio-only Nest speakers, live 2026-11-09; `announce` now rewrites WAV bytes as 48 kHz 16-bit stereo, which played on every audio-only speaker and display here, 2026-11-12): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
 
 **CLI.** `home status`: `cast  7 · Display A idle 47% · TV B standby · Whole house (3, led by Display A) idle`. `home probe`: this probe.
 

package/docs/cli.md

@@ -12,12 +12,14 @@ home scene <name> [in <room>]  # a scene; name the room when several have one by
 home pair                     # waits 60 s for the bridge's button, counting down; prints the env lines to set
 home daikin on | off           # power only: the AC comes back as it was last left
 home daikin cool | heat | auto [°C] | dry | fan  # mode, on, and the setpoint: the one given, else cool 25 and heat 27; prints what the unit then reports. Live on KO's unit: on, and dry to cool at 25 (2026-11-11); the rest untried
-                              # --dry-run on a hue or daikin write (lights, light, room, scene, daikin …): check it and print what would be sent; nothing is sent. Refused on every other command
+                              # --dry-run on a write (lights, light, room, scene, daikin, cast, spotify, printers print): check it and print what would be sent; nothing is sent. Refused on every other command
 home enphase login            # once a year: mints the Enphase owner token into ~/.config/home/ (0600)
 home discover [--json] [--passes n]  # which smart-home devices answer here (mDNS + Daikin UDP), which this package supports, then with a config how they match it; two passes 5 s apart
 home cache [clear]            # the addresses kept between runs, or delete them so the next run discovers afresh
 home config check [path]      # validate a home config: what it would set up, secrets as set or unset by name, every problem
 home discover --write [path]  # with a config (the path, else --config or HOME_CONFIG): match what answers by identity, add new devices, update moved hosts and renamed Cast names in place
+home printers print <file.pdf> [printer]   # PDF as is, or rendered to PWG Raster with pdftoppm when the printer takes no PDF; --dry-run
+home printers identify | cancel <job>       # the printer shows itself; stop a job
 home probe                    # read-only, no keys: Hue's public config, Daikin by UDP broadcast, the IQ Gateway's /info, each weather source, each Cast device's and printer's status
 home locate "<street address>" [--write [path]]  # latitude and longitude from OpenStreetMap's Nominatim; --write sets them in the config's location (and timezone, when absent, to this machine's)
 home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100]  # exit 1 if any didn't play; play a clip, then put back what was playing and the volume

package/docs/decisions.md

@@ -165,3 +165,10 @@ KO's decisions on this package, newest block last. They override every other doc
 - **Spotify playing on another device reads as `elsewhere`, not `playing`** (KO, 2026-11-11; chota raised it three times). Soloist reports the account's playback, not the box's, so `playing` while inactive is a silent speaker. `speakerState`, `spotifyText` and `spotifyChanges` all go through one test, `playingElsewhere`. Paused while inactive is left as Soloist says: nothing live shows whose pause it is. Soloist never names the other device, so where is a join with Cast by track name (`spotifyElsewhere`), passed to `spotifyText(state, on)` by `homeDevices`, which sees both parts; the speaker's own part can't know it, so `home status` says "another Spotify device".
 - **`home.add` replaces by name and starts the part over** (KO, 2026-11-11; chota pairs Hue from a chat). The old run ends before the new one starts, so a device never has two streams; the new part is a bare `connecting`, since the old state belonged to another key or address. No type widening: a `loadHome` home is already typed for every connector, so `add` takes the home's own integration type. `remove` fires no `onChange`: a change needs an `after`.
 - **Dry run is an option on each write, not a separate client** (KO, 2026-11-12; chota asked, since KO's rule is no device write without his OK at the time). It runs the read and every check a real write runs, so a wrong name or an unreachable light fails the same way, and returns the request instead of sending it, in the same `{ state, confirmed }` shape with `wouldSend` added. Hue and Daikin first, chota's lights and aircon tools; Cast and Spotify when a tool needs them.
+
+## Printing (2026-11-12)
+
+- **The library sends bytes; the CLI makes them.** `printJob` takes a document already in a format the printer lists. Many AirPrint printers (KO's Brother) take no PDF, only PWG Raster or Apple's URF, so a PDF has to be rendered. Rendering a PDF needs a PDF engine, which is not runtime-neutral; it lives in `src/cli/printers.ts` as poppler's `pdftoppm`, the one new tool. `pwgRaster` packs the pixels and stays in the library, so a consumer with its own renderer can print.
+- **PWG Raster, not URF.** PWG 5102.4 is a published standard; URF is Apple's and undocumented. 8-bit grey only, until a colour printer is here.
+- **Validate-Job before every Print-Job**, so a wrong attribute fails before paper moves; **`one-sided` sent explicitly**; **a timed-out Print-Job is never resent**, since the printer may have taken it.
+- **No write lane yet.** The writes are one-shot calls on an address, not methods on the integration: nothing calls them in a loop. When a consumer prints from a long-running process, put them on the integration with a lane, slot per job so two prints never merge.

package/docs/ideas.md

@@ -61,6 +61,8 @@ Two ideas from KO, 2026-10-14, not yet decided:
 
 ## Spotify search and library (KO, 2026-11-08)
 
+A signed-in account's playlists and library are now [khalido/home.ts#2](https://github.com/khalido/home.ts/issues/2).
+
 Soloist plays URIs; it can't search or read a library. Starting music by name ("play some Seal", "my Soft 90s playlist") needs Spotify's cloud Web API beside it: search returns a URI, and the spotify connector's `play(uri)` plays it. **KO's call, 2026-11-08: search lives in chota-bot, not here.** This library turns a box into a speaker; the bot owns its music search tool. chota-bot checked live that catalogue search works with client credentials, no user sign-in, on a development-mode app, and that Soloist played the URI it found. The notes below stay as the research.
 
 - **Search without a user** (catalogue only): the Client Credentials flow reaches "only endpoints that do not access user information" ([client credentials](https://developer.spotify.com/documentation/web-api/tutorials/client-credentials-flow)). The search reference names no flow, but the scopes page lists search under `user-read-private`, so whether an app-only token can search is unsettled: one test call answers it. Search needs a `market`. Since February 2026 a development-mode app gets at most 10 results per search ([migration guide](https://developer.spotify.com/documentation/web-api/tutorials/february-2026-migration-guide)).

package/docs/using.md

@@ -74,7 +74,7 @@ A write changes someone's house: make one only when a person asked for it. Write
 | hue       | `.client.put(kind, id, body)`, `.client.recallScene(id)`                                                           | the bridge's answer, for what the typed writes don't cover                                       |
 
 - **`confirmed`** is true once the device reported what was asked. False is a result, not an error: the write was sent and the device hasn't shown it yet, and `state` is how it stood.
-- **Dry run.** `opts` is `{ dryRun: true }` on Hue's and the Daikin's writes: every check made before sending runs (the name, the range, a lost light; a colour off the gamut shows moved in the body) and nothing is sent. The device can still refuse a real write that a dry run passed. The result has `wouldSend`, the request it would make (Hue: `{ method, path, body }`; Daikin adds `sets`, `{ on?, mode?, targetC? }`), `state` as things stand now, and `confirmed: false`, so check `wouldSend` first. A wrong name still throws with the names that exist. For testing a bot end to end with people home; `home … --dry-run` does the same from the terminal.
+- **Dry run.** `opts` is `{ dryRun: true }` on Hue's, the Daikin's, Cast's and Spotify's writes: every check made before sending runs (the name, the range, a lost light; a colour off the gamut shows moved in the body) and nothing is sent. The device can still refuse a real write that a dry run passed. The result has `wouldSend`, the request it would make (Hue: `{ method, path, body }`; Daikin adds `sets`, `{ on?, mode?, targetC? }`; Spotify: the WebSocket commands in order), `state` as things stand now, and `confirmed: false`, so check `wouldSend` first. Cast's `setVolume`, `setMuted` and `stop` resolve `{ wouldSend }` (each `{ device, channel, payload }`), and `announce` its usual result with `played: false`, `why: "dry run"`, `wouldSend` and, in `notRestored`, what the real one could not put back (an app it would interrupt); nothing is served. Spotify's `duck` and `interrupt` run `fn`, touch nothing, and say in `why` what they would have done, so `duck(() => cast.announce(…, { dryRun: true }), { to: 20, dryRun: true })` tests an announcement end to end without a sound. A wrong name still throws with the names that exist. For testing a bot end to end with people home; `home … --dry-run` does the same from the terminal.
 - **Use the returned state.** The Daikin's part in the snapshot is from its last poll and can be 120 s behind, unless you call `home.refresh("daikin")`.
 - **Daikin defaults.** `mode("cool")` is 25 °C and `mode("heat")` 27 (`DEFAULT_TARGET_C`); `mode("cool", 23)` for another. `power(true)` brings the unit back as it was last left.
 - **A target** for Cast is a device's or group's name or id. A clip is `{ url, type? }` or `{ bytes, type }`; bytes need `castServe`.

package/llms.txt

@@ -11,8 +11,8 @@ The library never reads the environment or a file: callers pass addresses, keys
 - **Why a part is down:** `part.status` (`connected`, `disconnected`, `unavailable`) and, when `unavailable`, `part.reason` (`auth`, `config`, `crashed`). Errors are `ConnectorError` with a typed `code`.
 - **Hue** (`@khalido/home/hue`): `pairWhenPressed` waits for the bridge's button and returns `{ key }`; Signify's root certificates are in the package, so `hue({ host, bridgeId, key })` needs no file. Writes by name: `client.light(name, change)`, `client.room(name, change)`, `client.scene(name, room?)`, `client.allOff()`, with `change` `{ on?, brightness?, color?, kelvin?, transitionMs? }`, each resolving `{ state, confirmed }`. `{ dryRun: true }` as the last argument checks and returns `wouldSend` without sending.
 - **Daikin** (`@khalido/home/daikin`): `client.power(on)` and `client.mode(mode, targetC?)` resolve `{ state, confirmed }`, and take `{ dryRun: true }` last; cool defaults to 25 °C and heat to 27.
-- **Cast** (`@khalido/home/cast`): `castStatus(state)` and `castFree(state, targets, { forms? })`, on the Cast part's state, say what is playing and where an announcement would disturb nothing; `castFreeSpeakers(state)` is the one call for every free speaker and display; `announce`, `announceAll`, `setVolume`, `setMuted`, `stop`.
-- **Spotify Soloist** (`@khalido/home/spotify`): `play`, `pause`, `setVolume` and the rest resolve `{ state, confirmed }`; `duck` and `interrupt` wrap an announcement. `speakerState(part)` is `elsewhere` when the music is on another Spotify device.
+- **Cast** (`@khalido/home/cast`): `castStatus(state)` and `castFree(state, targets, { forms? })`, on the Cast part's state, say what is playing and where an announcement would disturb nothing; `castFreeSpeakers(state)` is the one call for every free speaker and display; `announce`, `announceAll`, `setVolume`, `setMuted`, `stop`. Its writes take `{ dryRun: true }`.
+- **Spotify Soloist** (`@khalido/home/spotify`): `play`, `pause`, `setVolume` and the rest resolve `{ state, confirmed }`; `duck` and `interrupt` wrap an announcement. Every write takes `{ dryRun: true }`. `speakerState(part)` is `elsewhere` when the music is on another Spotify device.
 - **Discovery** (`@khalido/home/finders`, Node-side): `FINDERS`, one finder per connector, and `fileCache`. **Node** needs the fetches in `@khalido/home/node`.
 - **The command:** `home`, `home devices`, `home <connector>`, and writes such as `home daikin cool`, `home room <name> on`, `home cast announce`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khalido/home",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "home.ts: small, typed home automation for TypeScript: Hue, Daikin, Enphase, Google Cast, AirPrint printers and a Spotify Soloist speaker on the local network; Amber prices, Up Bank spending and the weather from the cloud.",
   "license": "MIT",
   "author": "Khalid Omar",

package/skills/draw-home/README.md

@@ -1,5 +1,7 @@
 # draw-home: references
 
+Where the skill is going, from a floor plan PDF to a live view: [khalido/home.ts#3](https://github.com/khalido/home.ts/issues/3).
+
 Good drawing references to read before drawing a home, newest idea first. All are skills or kits for coding agents; read for craft, keep this skill's contract (`SKILL.md` section 3) where they disagree.
 
 | Reference                                                                                                                                                     | What it is                                                                                                                                                                                                                                                                                                                                         | Use it for                                                                                                                                                                          | Licence                                                          |

package/skills/use-home/SKILL.md

@@ -10,7 +10,7 @@ description: Use the `home` command and the @khalido/home library to see and run
 ## Rules
 
 - **Reads are free.** `home`, `home <connector>` with no verb, `home devices`, `home discover`, `home probe`, `home up spend` and every `--json` read touch nothing.
-- **Writes only on request.** Lights, AC, speakers, Up categories and tags, webhooks: run one only when the person asked for that change, then read back and report the state it left. Never write to "test" something: `--dry-run` on a Hue or Daikin write (`home room …`, `home scene …`, `home lights off`, `home daikin …`) checks it and prints what it would send, sending nothing; other commands refuse the flag.
+- **Writes only on request.** Lights, AC, speakers, printing, Up categories and tags, webhooks: run one only when the person asked for that change, then read back and report the state it left. Never write to "test" something: `--dry-run` on a write (`home room …`, `home scene …`, `home lights off`, `home daikin …`, `home cast …`, `home spotify …`, `home printers print …`) checks it and prints what it would send, sending nothing (a print's dry run also asks the printer to validate the job, which prints nothing); other commands refuse the flag.
 - **Never print a key, token or password**, not even part of one. Say "set" or "unset". Env names are fine; values are not.
 - **Nothing private into a public repo**: no IPs, MACs, serials, device or room names, Up transactions or balances. A real `home.jsonc`, `home.svg` and floor plan live in a private folder.
 - **Show values as read.** A missing field is unknown, not zero. An `anomaly` is something odd the device said: report it, never smooth it.

package/src/cli/cast.ts

@@ -13,6 +13,7 @@ import {
   resolvedFrom,
 } from "../connectors/cast/index.ts";
 import { findCast } from "../connectors/cast/state.ts";
+import type { CastDryRun, CastRequest } from "../connectors/cast/writes.ts";
 import { serveClip } from "../connectors/cast/serve.ts";
 import { tlsConnect } from "../connectors/cast/tls.ts";
 import { addressBook } from "../discover.ts";
@@ -114,14 +115,32 @@ export const CAST_OPTIONS: [string, string, { type: unknown[] }?][] = [
 /** How long a write waits for the device to report the change before saying it was only sent. */
 const SHOWN_MS = 2000;
 
-/** One write, then the device's line once it reports what was asked, or that it has not yet. */
+/** A dry run's messages, one line each: `would send <device> <channel> <payload>`. */
+const dryLines = (sends: CastRequest[], who = "") =>
+  sends.length
+    ? sends.forEach((r) =>
+        console.log(
+          `${who}would send ${r.device} ${r.channel} ${JSON.stringify(r.payload)}`,
+        ),
+      )
+    : console.log(`${who}nothing to send`);
+
+/** One write, then the device's line once it reports what was asked, or that it has not yet. Dry: what would be sent. */
 const wrote = (
   name: string,
-  write: (c: ReturnType<typeof castNow>) => Promise<void>,
+  write: (
+    c: ReturnType<typeof castNow>,
+    options: { dryRun: boolean },
+  ) => Promise<CastDryRun | undefined>,
   shown: (d: CastDevice) => boolean,
+  dryRun: boolean,
 ) =>
   withCast(async (c, state) => {
-    await write(c);
+    const dry = await write(c, { dryRun });
+    if (dry) {
+      console.log("dry run, nothing sent:");
+      return dryLines(dry.wouldSend);
+    }
     const now = () => {
       const s = state();
       const d = s && findCast(s.devices, name);
@@ -140,29 +159,32 @@ const wrote = (
   });
 
 export const castVerbs: Verbs = {
-  async volume([name, value]) {
+  async volume([name, value], o) {
     if (!name) usage(CAST_USAGE);
     const level = percentLevel(value);
     await wrote(
       name!,
-      (c) => c.setVolume(name!, level),
+      (c, dry) => c.setVolume(name!, level, dry),
       (d) => d.volume !== undefined && Math.abs(d.volume - level) < 0.006,
+      !!o.dryRun,
     );
   },
-  async mute([name, value]) {
+  async mute([name, value], o) {
     if (!name || (value !== "on" && value !== "off")) usage(CAST_USAGE);
     await wrote(
       name!,
-      (c) => c.setMuted(name!, value === "on"),
+      (c, dry) => c.setMuted(name!, value === "on", dry),
       (d) => d.muted === (value === "on"),
+      !!o.dryRun,
     );
   },
-  async stop([name]) {
+  async stop([name], o) {
     if (!name) usage(CAST_USAGE);
     await wrote(
       name!,
-      (c) => c.stop(name!),
+      (c, dry) => c.stop(name!, dry),
       (d) => d.idle === true,
+      !!o.dryRun,
     );
   },
   async announce(_, o) {
@@ -209,13 +231,21 @@ export const castVerbs: Verbs = {
       type = "audio/mp4";
     }
     const results = await withCast((c) =>
-      c.announceAll(to, { bytes, type }, { volume }),
+      c.announceAll(to, { bytes, type }, { volume, dryRun: !!o.dryRun }),
     );
-    if (results.some((r) => !r.played)) process.exitCode = 1; // docs/cli.md: 1 is a failure, so a script can tell
+    const failed = results.some((r) => (o.dryRun ? !r.wouldSend : !r.played));
+    if (failed) process.exitCode = 1; // docs/cli.md: 1 is a failure, so a script can tell
     if (o.json) return printJson(to.length === 1 ? results[0] : results);
     const named = results.length > 1;
+    if (o.dryRun) console.log("dry run, nothing sent:");
     for (const r of results) {
       const who = named ? `${r.target}: ` : "";
+      if (r.wouldSend) {
+        dryLines(r.wouldSend, who);
+        for (const n of r.notRestored)
+          console.log(`${who}would not restore: ${n.name}: ${n.why}`);
+        continue;
+      }
       console.log(`${who}${r.played ? "played" : `not played: ${r.why}`}`);
       if (r.restored.length)
         console.log(`${who}restored: ${r.restored.join(", ")}`);

package/src/cli/context.ts

@@ -38,7 +38,7 @@ export const usage = (message: string): never => fail(message, "usage");
 /** The options cac parses: the global ones, and each command's own. */
 export type Options = {
   json?: boolean;
-  /** `--dry-run`: Hue and Daikin writes check and say what they would send, and send nothing. */
+  /** `--dry-run`: Hue, Daikin, Cast, Spotify and printer writes check and say what they would send, and send nothing. */
   dryRun?: boolean;
   config?: string;
   write?: string | true;

package/src/cli/enphase.ts

@@ -7,8 +7,16 @@ import {
   tokenExpiry,
 } from "../connectors/enphase/index.ts";
 import { daysLeft } from "../connectors/enphase/client.ts";
-import { writePrivate } from "../finders.ts";
-import { env, fail, homeTimeZone, TOKEN_FILE, type Verbs } from "./context.ts";
+import { addressBook } from "../discover.ts";
+import { FINDERS, writePrivate } from "../finders.ts";
+import {
+  addresses,
+  env,
+  fail,
+  homeTimeZone,
+  TOKEN_FILE,
+  type Verbs,
+} from "./context.ts";
 
 /** The cached Enphase token, or undefined if `home enphase login` has not run. A corrupt file throws, naming it. */
 export function enphaseToken(): { token: string; expiresAt: Date } | undefined {
@@ -31,12 +39,30 @@ export function enphaseToken(): { token: string; expiresAt: Date } | undefined {
   }
 }
 
-/** Enphase as an integration from IQ_GATEWAY_HOST and the token file, for `home status`. */
-export function enphaseFromEnv() {
+/**
+ * Enphase as an integration for `home status`: IQ_GATEWAY_HOST, else the address cache, else the first gateway mDNS finds.
+ * With the gateway's serial from the cache, a read that fails is followed by discovery at once, so an IQ_GATEWAY_HOST left
+ * behind by a DHCP move still reads, and its detail says where the gateway went.
+ */
+export async function enphaseFromEnv() {
   const t =
     enphaseToken() ?? fail("no Enphase token", "auth", "home enphase login");
+  const book = addressBook(addresses.cache);
+  const serial = Object.keys(book.entries())
+    .find((k) => k.startsWith("enphase:"))
+    ?.slice("enphase:".length);
+  const cached = serial ? book.fresh("enphase", serial) : undefined;
+  const host =
+    env.IQ_GATEWAY_HOST ??
+    cached?.host ??
+    (await FINDERS.enphase())[0]?.host ??
+    fail("no gateway found by mDNS; set IQ_GATEWAY_HOST", "network");
   return enphase({
-    host: env.IQ_GATEWAY_HOST!,
+    host,
+    serial,
+    find: FINDERS.enphase,
+    seen: (h) => book.seen("enphase", serial, { host: h }),
+    hostCached: true, // an env address is as likely stale as a cached one: look again after one failure
     token: t.token,
     fetch: bunGatewayFetch(),
     timeZone: homeTimeZone(),

package/src/cli/main.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 // `home`: the terminal layer. Commands come from cac; one `home <connector>` per manifest, its verbs from src/cli/<connector>.ts.
 import { cac } from "cac";
-import { ConnectorError, errorText } from "../connector.ts";
+import { errorText, isRejectedKey } from "../connector.ts";
 import { MANIFESTS } from "../manifests.ts";
 import { cacheCommand } from "./cache.ts";
 import { CAST_OPTIONS, CAST_USAGE, castVerbs } from "./cast.ts";
@@ -19,6 +19,7 @@ import { discover } from "./discover.ts";
 import { enphaseVerbs } from "./enphase.ts";
 import { CHANGE_USAGE, hueVerbs } from "./hue.ts";
 import { locate } from "./locate.ts";
+import { PRINTERS_USAGE, printersVerbs } from "./printers.ts";
 import { probe } from "./probe.ts";
 import { SPOTIFY_USAGE, spotifyVerbs } from "./spotify.ts";
 import { devices, status } from "./status.ts";
@@ -56,9 +57,18 @@ const VERBS: Record<
   },
   daikin: { verbs: daikinVerbs, usage: DAIKIN_USAGE, options: [DRY_RUN] },
   enphase: { verbs: enphaseVerbs, usage: "usage: home enphase login" },
-  cast: { verbs: castVerbs, usage: CAST_USAGE, options: CAST_OPTIONS },
+  cast: {
+    verbs: castVerbs,
+    usage: CAST_USAGE,
+    options: [...CAST_OPTIONS, DRY_RUN],
+  },
   up: { verbs: upVerbs, usage: UP_USAGE, options: UP_OPTIONS },
-  spotify: { verbs: spotifyVerbs, usage: SPOTIFY_USAGE },
+  spotify: { verbs: spotifyVerbs, usage: SPOTIFY_USAGE, options: [DRY_RUN] },
+  printers: {
+    verbs: printersVerbs,
+    usage: PRINTERS_USAGE,
+    options: [DRY_RUN],
+  },
 };
 
 const cli = cac("home");
@@ -157,8 +167,7 @@ function describe(e: unknown): {
   if (e instanceof CliError) return { error, code: e.code, fix: e.fix };
   if (e instanceof Error && e.name === "CACError")
     return { error, code: "usage" }; // cac: a missing argument or an unknown option
-  if (e instanceof ConnectorError && (e.status === 401 || e.status === 403))
-    return { error, code: "auth" };
+  if (isRejectedKey(e)) return { error, code: "auth" };
   // A timeout, or a socket error Bun and Node tag with a code (ECONNREFUSED, ENOTFOUND). A bare TypeError is more likely a bug.
   const socket =
     typeof (e as { code?: unknown })?.code === "string" &&

package/src/cli/printers.ts

@@ -1,9 +1,34 @@
 // Printers without a config: what `home status`, `home printers` and `home probe` run. Cached addresses first, then
-// discovery (AirPrint over mDNS) finds the rest. Read-only; the integration has no writes yet.
-import { printers } from "../connectors/printers/index.ts";
+// discovery (AirPrint over mDNS) finds the rest.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename } from "node:path";
+import {
+  cancelJob,
+  getPrinterAttributes,
+  identifyPrinter,
+  type PrinterAddress,
+  type PrintJob,
+  printJob,
+  validateJob,
+} from "../connectors/printers/client.ts";
+import { attributesOf } from "../connectors/printers/codec.ts";
+import {
+  printerList,
+  printers,
+  type PrintersState,
+} from "../connectors/printers/index.ts";
+import {
+  type GreyPage,
+  mediaPixels,
+  pwgRaster,
+  type RasterMedia,
+} from "../connectors/printers/raster.ts";
+import { printerKey } from "../connectors/printers/state.ts";
 import { addressBook } from "../discover.ts";
 import { FINDERS } from "../finders.ts";
-import { addresses } from "./context.ts";
+import { settle } from "../home.ts";
+import { addresses, fail, usage, type Verbs } from "./context.ts";
 
 /** Every printer the address cache knows plus whatever discovery finds, read once. */
 export function printersNow() {
@@ -19,3 +44,229 @@ export function printersNow() {
     seen: (uuid, a) => book.seen("printers", uuid, a),
   });
 }
+
+// `home printers identify | print | cancel`: the writes. A printer that lists no PDF gets PWG Raster, rendered here with
+// poppler's pdftoppm (the one tool this needs; `brew install poppler`, `apt install poppler-utils`).
+// Live 2026-11-12 on a Brother HL-L2350DW (Bun 1.4.4): identify, validate and one A4 page.
+
+export const PRINTERS_USAGE =
+  "usage: home printers identify [printer] | print <file.pdf> [printer] | cancel <job> [printer]";
+
+/** One printer by name or UUID, or the only one there is; with its address. */
+async function onePrinter(name: string | undefined) {
+  const part = (await settle([printersNow()], { ms: 15_000 })).printers!;
+  const all = printerList(
+    (part.state as PrintersState | undefined) ?? { printers: {}, asOf: "" },
+  );
+  const p = name
+    ? (all.find((x) => x.uuid === printerKey(name)) ??
+      all.find((x) => x.name.toLowerCase() === name.toLowerCase()))
+    : all.length === 1
+      ? all[0]
+      : undefined;
+  if (!p)
+    return fail(
+      name
+        ? `no printer named ${name}; \`home printers\` lists them`
+        : all.length
+          ? `${all.length} printers: name one (${all.map((x) => x.name).join(", ")})`
+          : "no printer found; `home discover` looks for them",
+      name || !all.length ? "error" : "usage",
+    );
+  if (p.state === "offline" || !p.host)
+    return fail(`${p.name} is offline`, "network");
+  const address: PrinterAddress = {
+    host: p.host,
+    port: p.port,
+    rp: p.rp,
+    secure: p.ipps,
+  };
+  return { printer: p, address };
+}
+
+/** What the printer takes, asked for once before a print. */
+async function capabilities(address: PrinterAddress) {
+  const a = attributesOf(
+    await getPrinterAttributes(fetch, address, {
+      requested: [
+        "document-format-supported",
+        "pwg-raster-document-resolution-supported",
+        "pwg-raster-document-type-supported",
+        "media-ready",
+        "media-default",
+      ],
+    }),
+  );
+  const strings = (k: string) =>
+    (a[k] ?? []).filter((v): v is string => typeof v === "string");
+  const dpis = (a["pwg-raster-document-resolution-supported"] ?? []).flatMap(
+    (r) =>
+      typeof r === "object" && "x" in r && r.units === "dpi" && r.x === r.y
+        ? [r.x]
+        : [],
+  );
+  return {
+    formats: strings("document-format-supported"),
+    rasterTypes: strings("pwg-raster-document-type-supported"),
+    dpis,
+    media: strings("media-ready")[0] ?? strings("media-default")[0],
+  };
+}
+
+/**
+ * A PDF's pages as 8-bit grey, one at a time, each fitted to the media and centred on white, through pdfinfo and
+ * pdftoppm. A page's `/Rotate` is applied, as pdftoppm does; a landscape page is shrunk to fit, not turned.
+ */
+function renderPdf(
+  file: string,
+  media: RasterMedia,
+): { count: number; pages: Iterable<GreyPage> } {
+  const run = (command: string, args: string[]) => {
+    const r = spawnSync(command, args, { maxBuffer: 1 << 30 });
+    if (r.error)
+      fail(
+        `${command} is not installed: it renders the PDF for a printer that takes no PDF`,
+        "error",
+        process.platform === "darwin"
+          ? "brew install poppler"
+          : "sudo apt install poppler-utils",
+      );
+    if (r.status !== 0) fail(`${command}: ${r.stderr.toString().trim()}`);
+    return r.stdout;
+  };
+  const info = run("pdfinfo", ["-l", "9999", file]).toString();
+  const turned = new Map(
+    [...info.matchAll(/^Page\s+(\d+) rot:\s+(\d+)/gm)].map((m) => [
+      Number(m[1]),
+      Number(m[2]) % 180 === 90,
+    ]),
+  );
+  const sizes = [
+    ...info.matchAll(/^Page\s+(\d+) size:\s+([\d.]+) x ([\d.]+) pts/gm),
+  ].map((m) =>
+    turned.get(Number(m[1]))
+      ? { w: Number(m[3]), h: Number(m[2]) }
+      : { w: Number(m[2]), h: Number(m[3]) },
+  );
+  if (!sizes.length) fail(`${file}: pdfinfo found no pages`);
+  const out = mediaPixels(media);
+  function* pages(): Generator<GreyPage> {
+    for (const [i, size] of sizes.entries()) {
+      // The largest resolution at which the page fits the media, so nothing is cut off; never above the printer's.
+      const r = Math.min(
+        media.dpi,
+        (out.width / size.w) * 72,
+        (out.height / size.h) * 72,
+      );
+      const pgm = run("pdftoppm", [
+        "-gray",
+        "-r",
+        r.toFixed(3),
+        "-f",
+        String(i + 1),
+        "-l",
+        String(i + 1),
+        "-singlefile",
+        file,
+      ]);
+      const head = /^P5\s+(\d+)\s+(\d+)\s+255\s/.exec(
+        pgm.subarray(0, 64).toString("latin1"),
+      );
+      if (!head)
+        return fail(`pdftoppm: page ${i + 1} is not an 8-bit grey image`);
+      const w = Number(head[1]);
+      const h = Number(head[2]);
+      // A pixel over is rounding; more means the size was misread, and a clipped page must not print.
+      if (w > out.width + 1 || h > out.height + 1)
+        return fail(
+          `page ${i + 1} rendered at ${w} × ${h}, larger than ${media.name} (${out.width} × ${out.height}); nothing sent`,
+        );
+      const pixels = new Uint8Array(out.width * out.height).fill(255);
+      const left = Math.max(0, Math.floor((out.width - w) / 2));
+      const top = Math.max(0, Math.floor((out.height - h) / 2));
+      const from = pgm.subarray(head[0].length);
+      for (let y = 0; y < Math.min(h, out.height); y++)
+        pixels.set(
+          from.subarray(y * w, y * w + Math.min(w, out.width)),
+          (top + y) * out.width + left,
+        );
+      yield { ...out, pixels };
+    }
+  }
+  return { count: sizes.length, pages: pages() };
+}
+
+const STATES: Record<number, string> = {
+  3: "pending",
+  4: "held",
+  5: "printing",
+  6: "stopped",
+  7: "cancelled",
+  8: "aborted",
+  9: "completed",
+};
+
+export const printersVerbs: Verbs = {
+  async identify([name, extra], o) {
+    if (o.dryRun) usage("home printers identify has no dry run");
+    if (extra) usage(PRINTERS_USAGE);
+    const { printer, address } = await onePrinter(name);
+    await identifyPrinter(fetch, address);
+    console.log(`${printer.name}: identify sent`);
+  },
+
+  async print([file, name, extra], o) {
+    if (!file || extra) return usage(PRINTERS_USAGE);
+    if (!/\.pdf$/i.test(file)) return usage(`${file}: only a PDF prints`);
+    if (!existsSync(file)) return usage(`${file}: no such file`);
+    const { printer, address } = await onePrinter(name);
+    const can = await capabilities(address);
+    const job: PrintJob = {
+      format: "application/pdf",
+      name: basename(file),
+      media: can.media,
+    };
+    let document: Uint8Array | undefined;
+    let what = `${basename(file)} as PDF`;
+    if (!can.formats.includes("application/pdf")) {
+      const dpi = can.dpis.includes(600) ? 600 : can.dpis[0];
+      if (!can.formats.includes("image/pwg-raster") || !dpi)
+        return fail(
+          `${printer.name} takes neither PDF nor PWG Raster (it lists ${can.formats.join(", ") || "nothing"})`,
+        );
+      if (!can.rasterTypes.includes("sgray_8"))
+        return fail(
+          `${printer.name}'s PWG Raster is ${can.rasterTypes.join(", ")}; only sgray_8 is built`,
+        );
+      if (!can.media)
+        return fail(`${printer.name} reports no media loaded or default`);
+      const { count, pages } = renderPdf(file, { name: can.media, dpi });
+      document = pwgRaster(pages, { name: can.media, dpi }, count);
+      job.format = "image/pwg-raster";
+      what = `${count} page${count === 1 ? "" : "s"} of ${can.media} at ${dpi} dpi as PWG Raster (${Math.round(document.length / 1024)} kB)`;
+    }
+    await validateJob(fetch, address, job); // prints nothing: a dry run checks the job as the printer would
+    if (o.dryRun)
+      return console.log(
+        `dry run, no job sent: the printer accepts it; would print ${what} on ${printer.name}`,
+      );
+    const done = await printJob(
+      fetch,
+      address,
+      job,
+      document ?? readFileSync(file),
+    );
+    console.log(
+      `${printer.name}: job ${done.jobId ?? "?"} ${STATES[done.state ?? 0] ?? "sent"} · ${what}`,
+    );
+  },
+
+  async cancel([id, name, extra], o) {
+    if (o.dryRun) usage("home printers cancel has no dry run");
+    const job = Number(id);
+    if (!Number.isInteger(job) || extra) return usage(PRINTERS_USAGE);
+    const { printer, address } = await onePrinter(name);
+    await cancelJob(fetch, address, job);
+    console.log(`${printer.name}: job ${job} cancelled`);
+  },
+};

package/src/cli/spotify.ts

@@ -7,7 +7,7 @@ import {
   type SpotifyState,
   spotifyText,
 } from "../connectors/spotify/index.ts";
-import { env, fail, usage, type Verbs } from "./context.ts";
+import { env, fail, type Options, usage, type Verbs } from "./context.ts";
 
 /** SOLOIST_MAX_VOLUME as a number 0–100, or undefined when unset. */
 function maxVolume(): number | undefined {
@@ -55,23 +55,27 @@ async function withSpotify<T>(
   }
 }
 
-/** What a write left, in a line: the speaker as Soloist then reported it, or that it has not reported the change yet. */
-const said = ({ state, confirmed }: Applied) =>
+/** What a write left, in a line: the speaker as Soloist then reported it, that it has not reported the change yet, or what a dry run would send. */
+const said = ({ state, confirmed, wouldSend }: Applied) =>
   console.log(
-    confirmed
-      ? spotifyText(state)
-      : `sent; Soloist has not reported it yet (${spotifyText(state)})`,
+    wouldSend
+      ? `dry run, nothing sent: ${wouldSend.length ? `would send ${wouldSend.map((r) => JSON.stringify(r)).join(", then ")}` : "nothing to send"} (now ${spotifyText(state)})`
+      : confirmed
+        ? spotifyText(state)
+        : `sent; Soloist has not reported it yet (${spotifyText(state)})`,
   );
 
+const dry = (o: Options) => ({ dryRun: !!o.dryRun });
+
 export const spotifyVerbs: Verbs = {
-  activate: () => withSpotify((s) => s.activate()).then(said),
-  pause: () => withSpotify((s) => s.pause()).then(said),
-  next: () => withSpotify((s) => s.next()).then(said),
-  play: ([link]) => withSpotify((s) => s.play(link)).then(said),
-  async volume([value]) {
+  activate: (_, o) => withSpotify((s) => s.activate(dry(o))).then(said),
+  pause: (_, o) => withSpotify((s) => s.pause(dry(o))).then(said),
+  next: (_, o) => withSpotify((s) => s.next(dry(o))).then(said),
+  play: ([link], o) => withSpotify((s) => s.play(link, dry(o))).then(said),
+  async volume([value], o) {
     const n = Number(value);
     if (value === undefined || value.trim() === "" || !(n >= 0 && n <= 100))
       usage(SPOTIFY_USAGE);
-    said(await withSpotify((s) => s.setVolume(n)));
+    said(await withSpotify((s) => s.setVolume(n, dry(o))));
   },
 };