prompt/AGENTS.md

# AGENTS.md

Prompt is a native macOS app written in Swift/SwiftUI. Single executable
SwiftPM package, no external dependencies (all Apple frameworks). It is a
Copper-style (shadcn) capture panel: prompts and photos live in sections,
clicking an item copies it back to the clipboard.

## Architecture

- `Sources/Prompt/App.swift` — `@main` entry using a bare
  `Settings { EmptyView() }` scene; the app owns its `NSStatusItem` manually
  (same reason as SimpleTopBar: placement control on notched Macs, seeded via
  `NSStatusItem Preferred Position Prompt`). Left click toggles the panel,
  right click shows the menu (accessibility state, launch at login, open data
  folder, quit). Contains the single-instance guard and `LoginItem`
  (`SMAppService`).
- `Sources/Prompt/Store.swift` — `@MainActor` `ObservableObject` singleton.
  Data model: `Section` → `[PromptItem]`, item content is
  `.text(String)` or `.image(String)` (filename). Persists to
  `~/Library/Application Support/Prompt/store.json`; images are PNG files in
  `Images/` next to it, cached in an `NSCache`. Owns all mutations (add,
  toggle done, edit, delete, move, merge, clear done) and clipboard writes
  (`copy`, `copyAsList`). Saves on every mutation.
- `Sources/Prompt/PanelView.swift` — the panel UI. Header (section switcher,
  search, add photos, close), item list, composer. Composer `# Name` creates/
  switches sections. Click = copy; Cmd+click = multi-select; right-click =
  context menu (Copy, Copy as List, Done, Edit, Open, Merge, Move To, Delete).
  Drop target for images/files.
- `Sources/Prompt/PanelController.swift` — owns the floating `NSPanel`
  (`.nonactivatingPanel`, `.floating`, right-edge docked, frame autosaved as
  `PromptPanel`), the Cmd+V image-paste monitor, and `EditWindowController`
  (separate edit window with a `TextEditor`).
- `Sources/Prompt/HotkeyManager.swift` — double-Shift detection via a
  CGEvent tap on `flagsChanged` (left Shift ×2 = capture, right Shift ×2 =
  toggle panel), plus Carbon `RegisterEventHotKey` fallbacks (Cmd+Shift+Space
  toggle, Cmd+Shift+C capture) that work without Accessibility.
- `Sources/Prompt/Capture.swift` — selection capture: backs up every
  pasteboard item, simulates Cmd+C, polls `changeCount` for ≤0.5s, reads the
  string, restores the backup. Runs off the main thread (hotkey dispatches to
  a global queue); only the store append hops back to main.
- `Sources/Prompt/SyncService.swift` — optional sync client. Holds the group
  code and server URL in `UserDefaults` (`sync.code`, `sync.serverURL`,
  `sync.version`), pushes the whole store as JSON, and polls every 5s.
- `Server/main.go` — the Go sync backend (single file, `net/http` + `lib/pq`).
  Also ships `Server/README.md` (self-hosting) and `Server/prompt-sync.service`
  (systemd unit). Logs one line per request, creates its schema on startup, and
  shuts down gracefully on SIGTERM so a redeploy cannot cut off a push.

## Sync protocol

No authentication by design: a sync group is named by an 8-digit code
(`1234-5678`) that doubles as the shared secret. The server stores the client
payload as opaque `JSONB`; it never parses note contents.

| Endpoint | Behaviour |
| --- | --- |
| `POST /api/codes` | Generates a unique code and inserts an empty group |
| `GET /api/sync/{code}` | `{"version":N,"updatedAt":…,"data":{…}\|null}`, 404 if unknown |
| `GET /api/sync/{code}/version` | `{"version":N}` — the cheap poll |
| `PUT /api/sync/{code}` | Upserts the payload, returns the incremented version |
| `GET /healthz` | Liveness |

Client rules:

- Payload = `{sections, activeSectionID, images}`, where `images` maps a
  filename to base64 PNG so photos travel with the notes.
- Polling is two-step: `GET /version` every 5s (tiny) and the full payload only
  when the version moved. Fetching the payload unconditionally would re-download
  every base64 photo every 5 seconds.
- Version counter is server-owned; the client stores the last version it saw
  in `sync.version` and only applies a remote payload when `remote.version >
  lastVersion`.
- **Never push a payload that came from the server.** `pushNow()` compares a
  sorted-keys encoding against `lastSyncedPayload` and skips identical
  payloads. Without this, applying a remote change would immediately push it
  back, bump the version, and the two Macs would ping-pong forever. The
  `applyingRemote` flag alone is not enough: the save-triggered push is
  dispatched asynchronously, so it runs *after* the flag is cleared.
- Conflict resolution is last-writer-wins at whole-store granularity. That is
  acceptable for personal use; it is not a merge.
- `apply()` writes incoming images, deletes image files no longer referenced,
  and replaces the store in one shot.
- `Prompt --sync-check` runs `SyncService.runDiagnostic()`: pushes any local
  change and prints local vs remote versions, then exits. Use it to debug a
  second Mac without the UI.

## Commands

```bash
swift build                          # debug build
swift run Prompt                     # dev run (menu bar icon appears)
./Prompt.app/Contents/MacOS/Prompt --sync-check   # push + report sync state, then exit
./build-app.sh 0.1.0                 # release build + .app bundle + icon + codesign
./release.sh 0.1.0                   # build-app.sh + dist/Prompt.zip + notarize + sha256
scripts/make-icon.sh                 # regenerate Prompt.app/Contents/Resources/Icon.icns

# sync server (Go, needs Postgres)
createdb prompt_sync
cd Server && go run .                # :8080, PROMPT_SYNC_DATABASE_URL / PROMPT_SYNC_ADDR
```

There is no test target and no linter/formatter configured. Verification =
`swift build`, `go build ./...`, and manual run (`--sync-check` for sync).

## Bundle build & signing

`build-app.sh` does: release build → handwritten `Info.plist` (NOT generated
from `Package.swift`) → `make-icon.sh` → `codesign`. It resolves a
`Developer ID Application` identity from the login keychain and falls back to
ad-hoc signing (`-`) if none is present. `LSUIElement` is true → no Dock icon.
Bundle id is `dev.tzgyn.prompt`.

## Release process

Notarization is **required**: an unnotarized build is not a release. Never
publish one, and never suggest quarantine workarounds (`xattr -dr
com.apple.quarantine`, `brew install --cask --no-quarantine`). `release.sh`
enforces this — it fails if it cannot notarize, and refuses to print a sha256
unless `spctl` reports `source=Notarized Developer ID`. `PROMPT_SKIP_NOTARY=1`
exists only for a local dev build and prints a "NOT FOR PUBLICATION" warning.

1. `./release.sh <version>` — builds, notarizes, staples, zips `Prompt.app` to
   `dist/Prompt.zip`, and prints its sha256 (it does not tag or upload). Uses
   the `PROMPT_NOTARY_*` env vars, defaulting to the shared Kapture App Store
   Connect key at `~/.config/kapture/AuthKey_K5KXMMSB28.p8`.
2. Commit and push `main`.
3. `tea releases create --tag v<version> --title "Prompt <version>" --note "<what changed>" --asset dist/Prompt.zip --repo TZGyn/prompt --login gitea.tzgyn.dev`.
4. Add/update `~/.cache/homebrew-tap/Casks/prompt.rb` (`version` + `sha256`),
   push the tap, then
   `git -C /opt/homebrew/Library/Taps/tzgyn/homebrew-tap pull --ff-only` and
   `brew audit --cask tzgyn/tap/prompt`.
5. Verify by downloading the release asset back, comparing the sha256 with the
   cask, and unzipping with `ditto -x -k` (not `unzip`, which adds `._*` files
   and breaks the signature check) then `spctl -a -vv Prompt.app`.

**Always print the upgrade script after any release or version bump:**

```bash
brew update
brew upgrade --cask prompt
```

## Gotchas

- **Never bind bare keys as `.keyboardShortcut` in the panel** (Space, Delete,
  plain Cmd+C). SwiftUI key equivalents are matched before text input and
  would steal characters from the composer TextField. Only Cmd-modified
  shortcuts that TextFields don't use are bound (Cmd+F/K/N, Shift+Cmd+C).
  This is why Copy has no in-panel shortcut: click-to-copy is the primary
  gesture, matching Copper's intent.
- The panel is a `.nonactivatingPanel`; its `canBecomeKey` override is what
  lets the composer TextField take focus. Don't replace it with a plain
  NSWindow config without rechecking that typing works without the app
  becoming active.
- The Cmd+V paste monitor only intercepts when the pasteboard has an image
  AND no string, so pasting text into the composer is never swallowed.
- CGEvent tap callbacks run off-main; `HotkeyManager` hops to main before
  firing. The tap is re-enabled on `tapDisabledByTimeout`.
- `Store` is `@MainActor`; anything reaching it from monitors/callbacks must
  go through `Task { @MainActor in }`.
- `captureSelection()` blocks up to 0.5s polling the pasteboard — keep it off
  the main thread (the hotkey handler already dispatches to a global queue).
- The double-Shift tap needs Accessibility; without it the event tap silently
  fails and only the Carbon fallbacks work. The panel banner and the status
  menu both surface the permission state.
- `Info.plist` sets `NSAllowsArbitraryLoads` because the sync server URL is
  user-supplied and is often plain HTTP (LAN address, self-hosted box). ATS
  would otherwise block it with a confusing error.
- The server keeps `data` as opaque `JSONB`, so the payload shape can evolve
  without a migration — but both Macs should run the same app version, since a
  newer client writing unknown fields will round-trip them to an older one.
- `.gitignore` covers `.build/`, `Prompt.app/`, `dist/` — build artifacts
  should never be committed.