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). 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>`. 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.