George Lambert
46f2bcd43e
Implements macOS v0: verae-print stamp + install-macos PDF menu items.
Saves {name}.pdf, {name}-verae-timestamp-{RECEIPTID}.pdf, and .verae.json.
Channels: verae (api.veraetime.net JWT) and zapier (zap.verae.ai xVerae- + attachPdf).
87 lines
4.6 KiB
Markdown
87 lines
4.6 KiB
Markdown
# 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
|
|
- [x] CLI `verae-print stamp` writes `{name}.pdf`, `{name}-verae-timestamp-{RECEIPTID}.pdf`, `{name}.verae.json`.
|
|
- [x] Dual channel: `verae` (api.veraetime.net JWT) and `zapier` (zap.verae.ai xVerae- + attachPdf).
|
|
- [x] `verae-print install-macos` installs PDF Services apps (Verae + Zapier).
|
|
- [ ] Optional Save/Print/Both dialog (v0 auto-saves to `~/Documents/Verae Timestamps`).
|
|
- [ ] 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
|
|
```
|