PrintToVeraeTimeStamp — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Ship a "Verae Timestamp" virtual printer for macOS, Linux, and Windows per docs/superpowers/specs/2026-10-03-print-to-verae-timestamp.md.

Tech stack: Go 1.26 (core + helper + CLI), pdfcpu (page split, incremental update, attachments), skip2/go-qrcode, Fyne or Wails for cross-platform helper UI (decide in Task 1), CUPS backend in Go (static binary), Windows port monitor in C/C++ (minimal) or IPP service in Go.

Global constraints

Digests only to Verae. Never document bytes.
Backend/port-monitor code does no networking; it only spools.
Canonical JSON (fixed struct tags) for manifests so digests are reproducible.
All binaries signed per platform before release.

Repository layout

Path	Role
`cmd/verae-print/`	CLI: `stamp`, `verify`, `login`, `spool-watch`
`cmd/verae-print-helper/`	Per-user helper (tray/menu-bar UI)
`cmd/cups-backend-verae/`	CUPS backend (macOS + Linux)
`internal/hash/`	Doc + per-page + manifest hashing
`internal/veraeapi/`	Client: `/api/timestamp`, `/api/status`, `/api/hash`, `/api/verify`
`internal/receipt/`	Receipt JSON, offline queue
`internal/pdfout/`	Certificate page render, incremental-update embedding
`internal/spool/`	Spool protocol (job.pdf + job.json), watcher
`platform/macos/`	PDF Service app, LaunchAgent, pkg scripts, PPD
`platform/linux/`	PPD/lpadmin scripts, systemd user unit, deb/rpm
`platform/windows/`	Port monitor or IPP service, MSI (WiX)

Task 1: Spike & decisions

Confirm Verae API certificate PDF availability (open question 1); record in spec.
Prove incremental update with pdfcpu keeps original byte prefix intact (hash test).
Decide helper UI toolkit (Fyne vs Wails) and Windows path (port monitor vs local IPP).
Commit docs: spike results.

Task 2: Core library (`internal/hash`, `internal/veraeapi`, `internal/receipt`)

Tests: deterministic page hashes; API client against httptest (immediate certificate, existing, job polling, 401); offline queue retry.
Implement; reuse request/response shapes from Datacube-Fuse internal/stamp/global.go.
Commit feat(core): hashing, Verae client, receipts.

Task 3: CLI `verae-print stamp|verify|login`

stamp file.pdf → .verae.json (+ --embed, --cert).
verify file.pdf|file.stamped.pdf.
Commit feat(cli): stamp and verify.

Task 4: PDF outputs (`internal/pdfout`)

Certificate page (name, digest, time UTC + local, id, verify URL, QR, page-hash list).
Incremental-update embed + attachment; verify prefix hash in tests.
Commit feat(pdf): certificate page and embedded receipt.

Task 5: macOS v0 — PDF Services

App bundle in ~/Library/PDF Services/ calling the core; Save/Print/Both dialog.
Commit feat(macos): PDF Services entry.

Task 6: Spool protocol + helper

internal/spool: job dir format, atomic hand-off, per-user dirs 0700.
Helper: watch spool, process, dialog, settings, forward printing (lp / Windows print API), keychain token storage.
Commit feat(helper): spool watcher and UI.

Task 7: CUPS backend (macOS v1 + Linux)

Go backend: read job from stdin/file arg, write to spool for job user, exit 0; lpadmin install scripts and PPD.
Linux packaging (deb/rpm), systemd user unit; macOS LaunchAgent + signed/notarized pkg.
Commit feat(cups): verae backend and installers.

Task 8: Windows

Per Task 1 decision: Print-to-PDF driver + port monitor writing to spool, or local IPP service.
Tray helper build, WiX MSI, Authenticode signing.
Commit feat(windows): virtual printer and installer.

Task 9: Docs + release

User guide per OS, verification guide, screenshots.
CI builds for all three platforms; release artifacts.
Commit docs: user guide and release.

Order

Task 1 → Task 2 → Task 3 → Task 4 → Task 5 (macOS quick win)
                         └→ Task 6 → Task 7 (macOS v1 + Linux) → Task 8 (Windows) → Task 9

4.3 KiB Raw Blame History