@khalido/home 0.1.3 → 0.2.1

package/src/cli/hue.ts

@@ -1,16 +1,20 @@
-// `home lights off`, `home room`, `home scene`, `home pair` (also as `home hue <verb>`): one write to the bridge each.
+// `home lights off`, `home light`, `home room`, `home scene`, `home pair` (also as `home hue <verb>`): one write to the bridge each,
+// then what the bridge reports. The name lookups and the checks are the library's (`client.light`, `room`, `scene`).
 import { readFileSync } from "node:fs";
 import { hostname } from "node:os";
 import {
   bunPinnedFetch,
-  groups,
-  homeGroupedLightId,
+  type GroupView,
+  type HueApplied,
+  type HueRequest,
+  HueError,
   hue,
   hueClient,
-  pair,
-  scenes,
+  hueText,
+  type LightChange,
+  type LightView,
+  pairWhenPressed,
 } from "../connectors/hue/index.ts";
-import { snapshotFrom } from "../connectors/hue/state.ts";
 import { FINDERS } from "../finders.ts";
 import { env, fail, usage, type Verbs } from "./context.ts";
 
@@ -24,12 +28,9 @@ export async function bridge(): Promise<{ host: string; id: string }> {
   return { host: env.HUE_BRIDGE_HOST ?? b.host, id: env.HUE_BRIDGE_ID ?? b.id };
 }
 
+/** HUE_CA_FILE when set; else undefined, and the package's own copy of Signify's roots is used. */
 export const ca = () =>
-  env.HUE_CA_FILE
-    ? readFileSync(env.HUE_CA_FILE, "utf8")
-    : fail(
-        "set HUE_CA_FILE to Signify's root CA (see src/connectors/hue/README.md)",
-      );
+  env.HUE_CA_FILE ? readFileSync(env.HUE_CA_FILE, "utf8") : undefined;
 
 const key = () =>
   env.HUE_APPLICATION_KEY ??
@@ -50,72 +51,159 @@ async function client() {
   });
 }
 
-/** Find one room, zone or scene by name, case-insensitively; a miss lists what exists. */
-function byName<T extends { name?: string }>(
-  items: T[],
-  name: string,
-  what: string,
-): T {
-  return (
-    items.find((i) => i.name?.toLowerCase() === name.toLowerCase()) ??
-    fail(`no ${what} "${name}"; have: ${items.map((i) => i.name).join(", ")}`)
+/** What a write left, in a line: the light or room as the bridge then reported it, or that it has not reported the change yet. */
+const said = ({
+  state,
+  confirmed,
+  wouldSend,
+}: HueApplied<LightView | GroupView>) =>
+  console.log(
+    wouldSend
+      ? dryLine(wouldSend, hueText(state))
+      : confirmed
+        ? hueText(state)
+        : `sent; the bridge has not reported it yet (${hueText(state)})`,
   );
+const dryLine = (r: HueRequest, now: string) =>
+  `dry run, nothing sent: would PUT ${r.path} ${JSON.stringify(r.body)} (now ${now})`;
+
+export const CHANGE_USAGE = "[on|off] [<1-100>] [<kelvin>k] [<hex colour>]";
+/** The words after a name as a change: `on`, `off`, `40` (brightness), `2700k` (white), `ff8800` (colour), in any order. */
+export function changeFrom(words: string[], usageLine: string): LightChange {
+  const change: LightChange = {};
+  for (const w of words) {
+    if (w === "on" || w === "off") {
+      if (change.on !== undefined && change.on !== (w === "on"))
+        usage(`on or off, not both; ${usageLine}`);
+      change.on = w === "on";
+    } else if (/^\d{1,3}%?$/.test(w))
+      change.brightness = Number.parseInt(w, 10);
+    else if (/^\d{4,5}k$/i.test(w)) change.kelvin = Number.parseInt(w, 10);
+    else if (/^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.test(w)) change.color = w;
+    else
+      usage(
+        `"${w}" is not on, off, a brightness, a temperature like 2700k or a colour like ff8800; ${usageLine}`,
+      );
+  }
+  if (!words.length) usage(usageLine);
+  return change;
 }
 
+/** A change the bridge can't make (an unknown name, a value off the light's range) is a usage error; anything else passes through. */
+const orUsage = (e: unknown): never => {
+  if (e instanceof HueError && e.code === "invalid") usage(e.message);
+  throw e;
+};
+
+/** How long `home pair` waits for the button: time to walk to the bridge. */
+const PAIR_WAIT_MS = 60_000;
+
 export const hueVerbs: Verbs = {
-  async lights([state]) {
-    if (state !== "off") usage("usage: home lights off");
-    const c = await client();
-    const id =
-      homeGroupedLightId(snapshotFrom(await c.get(), "")) ??
-      fail("the bridge has no home group");
-    await c.put("grouped_light", id, { on: { on: false } });
+  async lights([word], o) {
+    if (word !== "off") usage("usage: home lights off");
+    const { state, confirmed, wouldSend } = await (
+      await client()
+    )
+      .allOff({ dryRun: !!o.dryRun })
+      .catch(orUsage);
+    const on = state.filter((l) => l.on && l.reachable !== false).length;
+    console.log(
+      wouldSend
+        ? dryLine(wouldSend, `${on} of ${state.length} on`)
+        : confirmed
+          ? `${state.length} lights off`
+          : `sent; the bridge still reports ${on} of ${state.length} on`,
+    );
   },
 
-  async room([name, value]) {
-    if (!name || !value) usage("usage: home room <name> on|off|<1-100>");
-    const c = await client();
-    const room = byName(
-      groups(snapshotFrom(await c.get(), "")),
-      name!,
-      "room or zone",
+  async light([name, ...words], o) {
+    const line = `usage: home light <name> ${CHANGE_USAGE}`;
+    if (!name) usage(line);
+    const change = changeFrom(words, line);
+    said(
+      await (
+        await client()
+      )
+        .light(name!, change, { dryRun: !!o.dryRun })
+        .catch(orUsage),
     );
-    if (!room.groupedLightId) fail(`${room.name} has no grouped light`);
-    const level = Number(value);
-    if (value !== "on" && value !== "off" && !(level >= 1 && level <= 100))
-      usage(`brightness must be 1-100, got ${value}`);
-    const body =
-      value === "on" || value === "off"
-        ? { on: { on: value === "on" } }
-        : { on: { on: true }, dimming: { brightness: level } };
-    await c.put("grouped_light", room.groupedLightId!, body);
   },
 
-  async scene(words) {
-    const name = words.join(" ") || usage("usage: home scene <name>");
+  async room([name, ...words], o) {
+    const line = `usage: home room <name> ${CHANGE_USAGE}`;
+    if (!name) usage(line);
+    const change = changeFrom(words, line);
+    said(
+      await (
+        await client()
+      )
+        .room(name!, change, { dryRun: !!o.dryRun })
+        .catch(orUsage),
+    );
+  },
+
+  async scene(words, o) {
+    const line = "usage: home scene <name> [in <room>]";
+    if (!words.length) usage(line);
     const c = await client();
-    await c.recallScene(
-      byName(scenes(snapshotFrom(await c.get(), "")), name, "scene").id,
+    // "Relax in Bedroom" is the scene Relax in that room, unless a scene is named all of it.
+    const at = words.lastIndexOf("in");
+    const dry = { dryRun: !!o.dryRun };
+    const whole = () => c.scene(words.join(" "), undefined, dry);
+    said(
+      await (
+        at > 0 && at < words.length - 1
+          ? whole().catch(() =>
+              c.scene(
+                words.slice(0, at).join(" "),
+                words.slice(at + 1).join(" "),
+                dry,
+              ),
+            )
+          : whole()
+      ).catch(orUsage),
     );
   },
 
-  async pair() {
+  async pair(_, o) {
+    if (o.dryRun) usage("home pair has no dry run");
     const b = await bridge();
-    const { key } = await pair({
+    console.error(`Hue bridge ${b.id.slice(-6).toUpperCase()} at ${b.host}.`);
+    // The countdown redraws one line on a terminal; piped, it is one line said once.
+    const live = process.stderr.isTTY;
+    const until = Date.now() + PAIR_WAIT_MS;
+    const prompt = () =>
+      `Press the link button on the bridge: ${Math.max(0, Math.ceil((until - Date.now()) / 1000))} s left`;
+    let tick: ReturnType<typeof setInterval> | undefined;
+    const { key } = await pairWhenPressed({
       host: b.host,
       fetch: bunPinnedFetch(b.id, ca()),
       deviceType: `home#${hostname().slice(0, 19)}`,
-    }).catch((e) =>
-      e.code === "link_button"
-        ? fail(
-            "press the link button on the bridge, then pair again within 30 s",
-            "auth",
-            "home pair",
-          )
-        : Promise.reject(e),
-    );
+      timeoutMs: PAIR_WAIT_MS,
+      onWaiting() {
+        if (!live) return console.error(prompt());
+        process.stderr.write(prompt());
+        tick = setInterval(
+          () => process.stderr.write(`\r\x1b[K${prompt()}`),
+          1000,
+        );
+      },
+    })
+      .finally(() => {
+        clearInterval(tick);
+        if (tick) process.stderr.write("\r\x1b[K");
+      })
+      .catch((e) =>
+        e.code === "link_button"
+          ? fail(
+              `no button press detected in ${PAIR_WAIT_MS / 1000} s; nothing was changed`,
+              "auth",
+              "home pair",
+            )
+          : Promise.reject(e),
+      );
     console.error(
-      "Paired. Put this in your shell environment (never in a repo):",
+      "Paired. Put these in your shell environment or .env (never in a repo):",
     );
     console.log(
       `HUE_APPLICATION_KEY=${key}\nHUE_BRIDGE_HOST=${b.host}\nHUE_BRIDGE_ID=${b.id}`,

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";
@@ -14,23 +14,32 @@ import {
   usage,
   type Verbs,
 } from "./context.ts";
+import { DAIKIN_USAGE, daikinVerbs } from "./daikin.ts";
 import { discover } from "./discover.ts";
 import { enphaseVerbs } from "./enphase.ts";
-import { hueVerbs } from "./hue.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 { status } from "./status.ts";
+import { devices, status } from "./status.ts";
 import { UP_OPTIONS, UP_USAGE, upVerbs } from "./up.ts";
 
 const HUE_HELP: Record<string, string> = {
   lights: "lights off: one write to the whole-home group",
-  room: "room <name> on|off|<1-100>",
-  scene: "scene <name>",
-  pair: "pair: press the bridge's button first; prints the env lines to set",
+  light: `light <name> ${CHANGE_USAGE}`,
+  room: `room <name> ${CHANGE_USAGE}: every light in a room or zone, one write`,
+  scene: "scene <name> [in <room>]",
+  pair: "pair: waits 60 s for the bridge's button, counting down; prints the env lines to set",
 };
 
 /** Each connector's verbs beyond its status, the usage a wrong one prints, and any options of its own. */
+/** Only where a write reads it: on any other command cac refuses it, so `--dry-run` never lets a real write through. */
+const DRY_RUN: [string, string] = [
+  "--dry-run",
+  "check the write and print what would be sent; send nothing",
+];
+
 const VERBS: Record<
   string,
   {
@@ -41,14 +50,21 @@ const VERBS: Record<
 > = {
   hue: {
     verbs: hueVerbs,
+    options: [DRY_RUN],
     usage: `usage: home hue ${Object.values(HUE_HELP)
       .map((h) => h.split(":")[0])
       .join(" | ")}`,
   },
+  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 },
   up: { verbs: upVerbs, usage: UP_USAGE, options: UP_OPTIONS },
   spotify: { verbs: spotifyVerbs, usage: SPOTIFY_USAGE },
+  printers: {
+    verbs: printersVerbs,
+    usage: PRINTERS_USAGE,
+    options: [DRY_RUN],
+  },
 };
 
 const cli = cac("home");
@@ -66,6 +82,12 @@ const statusCommand = cli
   .alias("doctor")
   .alias("!") // cac's marker for the default command: `home` alone runs status
   .action((o: Options) => status(o));
+cli
+  .command(
+    "devices",
+    "every device the connectors read, one line each: its state, its room, and why when it isn't available",
+  )
+  .action((o: Options) => devices(o));
 cli
   .command(
     "discover",
@@ -123,10 +145,11 @@ for (const m of MANIFESTS) {
   );
 }
 // Hue's verbs also stand alone, as typed before the CLI had `home hue`: `home lights off`, `home room …`, `home scene …`, `home pair`.
-for (const [verb, run] of Object.entries(hueVerbs))
-  cli
-    .command(`${verb} [...args]`, `Hue: ${HUE_HELP[verb]}`)
-    .action((args: string[], o: Options) => run(args, o));
+for (const [verb, run] of Object.entries(hueVerbs)) {
+  const c = cli.command(`${verb} [...args]`, `Hue: ${HUE_HELP[verb]}`);
+  if (verb !== "pair") c.option(...DRY_RUN);
+  c.action((args: string[], o: Options) => run(args, o));
+}
 
 cli.help();
 
@@ -140,8 +163,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" &&
@@ -150,7 +172,15 @@ function describe(e: unknown): {
     e instanceof Error &&
     (e.name === "TimeoutError" || e.name === "AbortError" || socket)
   )
-    return { error, code: "network" };
+    return {
+      // macOS answers "no route to host" for a LAN address when the terminal app lacks the Local Network permission.
+      error:
+        (e as { code?: string }).code === "EHOSTUNREACH" &&
+        process.platform === "darwin"
+          ? `${error} If the device is up, allow this terminal under System Settings > Privacy & Security > Local Network.`
+          : error,
+      code: "network",
+    };
   return { error, code: "error" };
 }
 

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`);
+  },
+};