cupsadmin/CLAUDE.md

# cupsadmin

A native replacement for the CUPS web interface (`http://localhost:631`) that Apple removed in
macOS 27. `cupsd`, `lpadmin`, `lpstat`, `lpoptions` and IPP Everywhere queues still work; only the
browser admin pages are gone. Two front ends share one library:

- **CupsKit** (`Sources/CupsKit`) — IPP client, PPD parser, CUPS tool wrappers, read-back checks.
  Pure logic: returns values or throws, never prints.
- **`cupsadmin`** (`Sources/cupsadmin`) — the CLI, a thin layer over CupsKit.
- **CUPS Admin.app** (`Sources/CUPSAdminApp`) — the SwiftUI app. The target is `CUPSAdminApp`, not
  `CUPSAdmin`: APFS is case-insensitive, so `Sources/CUPSAdmin` is the same folder as `Sources/cupsadmin`
  and the two executables would collide in `.build/`.

Private maintainer notes, if present, are in `CLAUDE.local.md` (gitignored).

## Architecture
- **Reads are IPP** with a small hand-written encoder/decoder (RFC 8010, `CupsKit/IPP`):
  CUPS-Get-Printers, Get-Printer-Attributes, Get-Jobs, Get-Job-Attributes, Cancel-Job,
  CUPS-Get-Default. This gives typed data (state reasons, `*-default`, `*-supported`, job state)
  instead of localized `lpstat` text.
- **Transport is the Unix socket `/private/var/run/cupsd`, not TCP 631.** On macOS 27 launchd
  socket-activates cupsd only on that socket; cupsd binds port 631 itself while running and exits
  after about a minute idle, so TCP fails whenever it's asleep. URLSession can't use AF_UNIX, so
  `UnixSocketHTTP.swift` speaks minimal HTTP/1.1 over POSIX sockets. PPDs are fetched the same way
  (`GET /printers/<queue>.ppd`).
- **Writes shell out** through `CupsTools`: `lpadmin`, `cupsenable`/`cupsdisable`,
  `cupsaccept`/`cupsreject`, `cancel`, `lp`, `lpmove`, `lpinfo`. `lpadmin` already handles
  `_lpadmin` authorization and IPP Everywhere PPD generation.
- **Queue defaults are written with `lpadmin -p <queue> -o key=value`** (into the queue's PPD /
  printers.conf, for every user) — never `lpoptions`. `~/.cups/lpoptions` is only read, to point out
  a per-user override.
- **Driver filter check** (`DriverFilters.swift`): resolves each `*cupsFilter`/`*cupsFilter2` program
  (bare names under `/usr/libexec/cups/filter`, skipping `maxsize(n)` and `-`) and reads its Mach-O header
  directly — any arm64 CPU type counts as native, including subtypes `lipo` can't name. Intel-only →
  "Driver needs Rosetta"; not found → "Driver filter missing" (shown first).
- **PPD options** keep their `*OpenGroup`, UI type and `*ParamCustom` type/range. Custom values are
  written as `Custom.<value>` and quoted when they contain spaces (unquoted, `lpadmin` silently truncates).
- **Quick actions** are vendor-neutral. `QuickActions.swift` defines the actions; what each writes comes
  from `Resources/driver-profiles.json` (embedded in code — the CLI is a single binary), matched on the
  PPD's `*Manufacturer`/`*NickName`, vendor profiles first and `generic` (standard PPD keywords, IPP
  Everywhere `*-default` attributes) last. A pair is used only if that queue supports the keyword and
  value; otherwise the action is unavailable with the reason. A profile's `unavailable` map gives
  the reason an action can't be done with that driver (e.g. Canon department IDs); its `inputs` map relabels
  the typed value and can add an optional second value (`{value2}`, e.g. the Xerox account ID). Use Letter Paper is
  titled ", Fit to Nearest Size" only when the profile also sets a fit option. `cupsadmin ppdreport
  <queue | file.ppd[.gz]>` shows a driver's keywords and which actions its profile enables.

## Build and test
```
swift build                          # debug build of everything
.build/debug/cupsadmin printers      # run the CLI
./test.sh                            # Swift Testing via the Command Line Tools (see flags inside)
./build.sh --build-only              # universal CLI + app bundle, ad-hoc signed, no identities needed
./build.sh --screenshots             # regenerate docs/screenshots/app-jobs.png from temporary demo queues
./build.sh                           # release: sign, payload-free PKG, notarize, staple, spctl
```
- Only the Command Line Tools are required. Universal builds are per-triple
  (`swift build -c release --triple arm64-apple-macosx14.0` and `x86_64-…`) plus `lipo`;
  `--arch arm64 --arch x86_64` needs full Xcode.
- Package: tools-version 6.0, Swift 5 language mode, macOS 14 minimum.
- `build.sh` reads `CODESIGN_APP_IDENTITY`, `CODESIGN_PKG_IDENTITY`, `NOTARY_PROFILE` (and optional
  `CODESIGN_TEAM_ID`) from the environment or an untracked `build.env`. Never hard-code identities.
- PKG layout: the app is a payload (`pkgbuild --root` with a staging `Applications/` that is really
  root:admin 775 and `--ownership preserve`, `BundleIsRelocatable` false), so it gets a receipt and the
  package records the system's own ownership. `--ownership recommended` would record Applications as
  root:wheel — don't use it. The CLI is not a payload: the binary ships in Scripts and `pkg/postinstall`
  copies it, because a `/usr/local/bin` payload entry would reset a Homebrew-owned folder. The build
  verifies both BOM ownership entries. The app is notarized and stapled before packaging; the PKG after.
- The app icon master is `Icon/AppIcon-1024.png`; `build.sh` generates `AppIcon.icns` from it. Don't redraw it.
- Live tests are opt-in and write to queues: `CUPSKIT_LIVE_QUEUE=<queue>`, `CUPSKIT_LIVE_JOBS=<a>,<b>`,
  `CUPSKIT_LIVE_QUICK=<ricoh>,<generic>`, `CUPSKIT_LIVE_DELETE=1` (deletes a queue name that never existed; writes nothing). Use throwaway queues (e.g. `lpd://127.0.0.1/…`, paused) and
  delete them afterwards; the live tests restore what they change. Offline tests use vendor PPDs from
  `CUPSKIT_PPD_DIRS` (colon-separated, e.g. Canon/HP PPDs extracted with `pkgutil --expand-full`, not
  installed) and `/Library/Printers/PPDs`, and skip when they aren't there.

## Conventions
- **US spelling everywhere** — code, UI, CLI output, docs (color, canceled, gray).
- **No third-party dependencies.** No Xcode project.
- **CLI status lines on every exit path:** `started HH:MM:SS`, exactly one `OK: …` or `ERROR: …`, and
  `finished HH:MM:SS (total N min)` — on stderr, so tables on stdout pipe cleanly. Exit 0 success,
  1 runtime error or not applied, 2 usage error. Existing command output is a contract: don't change it
  casually. Scripts (`build.sh`, `test.sh`) print the same started/finished lines.
- **Read back after every write.** Re-query cupsd and compare; a change that didn't take is reported
  (`NOT APPLIED`, non-zero exit, or a red X with the reason) — never silent.
- **App feedback:** every action updates the bottom status line with its timing ("Set 3 options on
  Office in 0.4 s", "ERROR: …") and logs the same through `os_log` (subsystem `edu.wku.cupsadmin.app`).
  Failures show the tool output and, for permission errors, the `_lpadmin` fix. The exact command is
  visible before it runs. Destructive actions confirm and name the object.
- **Secrets:** passcode/password options written as queue defaults land in a world-readable PPD — warn,
  and mask them in displayed commands. Never commit `build.env`, `dist/`, notary output or `CLAUDE.local.md`.
- **Native SwiftUI and macOS idioms only:** `NavigationSplitView`, sortable/resizable `Table`,
  `Form` with `.formStyle(.grouped)`, standard sheets, alerts and confirmation dialogs, SF Symbols,
  system fonts, semantic colors (`.primary`, `.secondary`, `.green`/`.blue`/`.red` state dots),
  `ContentUnavailableView` empty states. No custom chrome, no web-style cards, no emoji. Must look right
  in light and dark mode. Tables and text are selectable and copyable.