diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index c255ce180..aecdccd51 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -3,12 +3,13 @@ ## Project Overview Amethyst is a Nostr Client for Android that was made for Android-only and has been slowly switching -over to a Kotlin Multiplatform project. This project has 4 main modules: `quartz`, `commons`, -`amethyst` and `desktopApp`. Quartz should contain implementations of Nostr specifications and -utilities to help implement them. Commons stores shared code between Amethyst Android (`amethyst`) -and Amethyst Desktop (`desktopApp`). The Desktop App is designed to be mouse first and so uses a -completely different screen and navigation architecture while sharing the back end components with -the android counterpart. +over to a Kotlin Multiplatform project. This project has 5 main modules: `quartz`, `commons`, +`amethyst`, `desktopApp`, and `cli`. Quartz should contain implementations of Nostr specifications +and utilities to help implement them. Commons stores shared code between Amethyst Android +(`amethyst`) and Amethyst Desktop (`desktopApp`). The Desktop App is designed to be mouse first and +so uses a completely different screen and navigation architecture while sharing the back end +components with the android counterpart. `cli` ships `amy`, a non-interactive JVM command-line +client that drives the same `quartz` + `commons` code — used by humans, agents, and interop tests. ## Architecture @@ -27,6 +28,7 @@ amethyst/ │ └── jvmMain/ # Desktop-specific UI utilities ├── desktopApp/ # Desktop JVM application (layouts, navigation) ├── amethyst/ # Android app (layouts, navigation) +├── cli/ # Amy — non-interactive CLI (JVM only, no Compose) └── ammolite/ # Support module (unused) ``` @@ -34,6 +36,11 @@ amethyst/ - `quartz/` = Nostr business logic, protocol, data (no UI) - `commons/` = Shared UI components, icons, composables, flows and ViewModels - `amethyst/` & `desktopApp/` = Platform-native layouts and navigation +- `cli/` = Thin assembly layer over `quartz/` + `commons/` (no new logic allowed) + +**Plans per module:** design docs for new subsystems live in the owning +module's `plans/YYYY-MM-DD-.md` (e.g. `cli/plans/`, `commons/plans/`). +The global `docs/plans/` folder is frozen — don't add new plans there. ## Tech Stack @@ -66,6 +73,7 @@ Specialized skills provide domain expertise with bundled resources and patterns: | `feed-patterns` | Feeds & DAL | `FeedFilter`, `AdditiveComplexFeedFilter`, `FeedViewModel` family | | `auth-signers` | `NostrSigner` implementations | Local, NIP-46 bunker, NIP-55 Android external signer | | `quartz-integration` | Quartz as an external library | Gradle setup, `NostrClient`, `KeyPair`, for external projects | +| `amy-expert` | Amy CLI (`cli/` module) | Adding `amy ` commands, JSON output contract, extracting logic from `amethyst/` into `commons/` so CLI can call it | | `find-missing-translations` | Utility | Extract untranslated Android strings | | `find-non-lambda-logs` | Utility | Audit Log calls for lambda overloads | diff --git a/.claude/skills/amy-expert/SKILL.md b/.claude/skills/amy-expert/SKILL.md new file mode 100644 index 000000000..bf423a025 --- /dev/null +++ b/.claude/skills/amy-expert/SKILL.md @@ -0,0 +1,168 @@ +--- +name: amy-expert +description: Patterns for extending `amy`, the Amethyst CLI in `cli/`. Use when adding an `amy ` command, touching files under `cli/src/main/kotlin/…/cli/`, wiring a new subcommand into `Main.kt`, writing an interop test script that drives Amy, or extracting logic out of `amethyst/` into `commons/` so a CLI command can call it. Enforces the thin-assembly-layer rule (no Nostr protocol or business logic inside `cli/`), the JSON-output contract (single-line object on stdout, exit codes 0/1/2/124), and the extract-from-Android recipe. Complements `nostr-expert` (protocol in Quartz), `kotlin-multiplatform` (expect/actual for extraction), and `feed-patterns` / `account-state` / `relay-client` (where the business logic should end up). NOT for general Nostr or Kotlin work — those have their own skills. +--- + +# Amy CLI Expert + +Practical patterns for touching the `cli/` module without breaking +its public contract. + +## When to use this skill + +- Adding a new `amy ` subcommand. +- Editing anything under `cli/src/main/kotlin/…/cli/`. +- Writing a shell script or test harness that drives Amy. +- Extracting code out of `amethyst/` so the CLI can call it (this is + the single most common reason an Amy feature request stalls). +- Deciding whether a piece of logic belongs in `cli/` vs `commons/` + vs `quartz/` (answer: almost never `cli/`). + +**Not for:** general Nostr protocol work (`nostr-expert`), general +Kotlin (`kotlin-expert`), Compose UI (`compose-expert`), Android-only +flows (`android-expert`), gradle/build (`gradle-expert`). + +## The rules that matter + +Amy has a small number of hard rules. Any change that breaks them is +a breaking change to the CLI's public API, and breaks the interop- +test harnesses that depend on it. + +### Rule 1 — `cli/` is a thin assembly layer + +No new Nostr protocol, filter assembly, state machines, or encryption +lives in `cli/`. Ever. If you need logic that doesn't exist yet: + +- Protocol piece (event kind, tags, signing)? Add it to `quartz/`. +- Business logic (state, defaults, ordering, filter assembly)? + Add it to `commons/` — extract from `amethyst/` first if needed + (see Rule 5). + +A `commands/*.kt` file longer than ~200 lines is a code smell. +Either the command is doing too many things, or the logic has +leaked in from where it should have lived. + +### Rule 2 — stdout JSON, stderr humans + +- Every success: one line, one JSON object on stdout, via + `Json.writeLine(mapOf(...))`. +- Every failure: `Json.error("code", "detail")` → single-line JSON + on stderr, non-zero exit. +- Exit codes: `0` success · `1` runtime · `2` bad args · `124` await + timeout. +- Keys are stable, snake_case. Adding a key is safe; renaming or + removing one is a breaking change and needs the commit message to + say so. + +See `references/output-conventions.md`. + +### Rule 3 — Non-interactive, ever + +No `readLine()`, no TTY prompts, no hidden interactive behaviour. +Passwords, names, keys, anything — all flags. Any network wait is +an explicit `await` verb with `--timeout`. + +### Rule 4 — Data-dir is the whole world + +State is reloaded from `--data-dir PATH` on every invocation. No +singletons, no in-process caches that survive across runs. This is +what lets 100 parallel interop scenarios share a harness safely. + +Files live in well-known locations — see +`cli/README.md § Data-dir layout`. Don't add unstructured state; if +you need new persisted state, add it to `Config.kt` or +`stores/FileStores.kt` with a named JSON schema. + +### Rule 5 — Extract before adding + +If the command you're about to add needs logic from `amethyst/`, +land the extraction first, in its own commit: + +1. Identify the class in `amethyst/src/main/java/…/`. +2. List its Android-only dependencies (`Context`, `SharedPreferences`, + `WorkManager`, `Log`, `Bitmap`, `Uri`, …). +3. For each, choose: inline, platform-abstract via expect/actual, or + take-as-constructor-arg. +4. Move the file to `commons/commonMain/…`. +5. Update the Android caller to use the new location. Add a JVM test. +6. **Then** add the `cli/commands/…` file. + +Full checklist: `references/extraction-recipe.md`. + +## Standard command shape + +Every new command follows the same shape — parse args, open Context, +prepare, call into commons/quartz, publish or drain, emit one JSON +line. The template is in `references/command-template.md`; copy it +rather than re-deriving it. + +Wire-up checklist: +1. New file in `cli/commands/` with the `object` pattern. +2. Add a branch in `Commands.kt`. +3. Add a branch in `Main.kt`'s `dispatch` (or under `marmotDispatch` + / a new group dispatcher). +4. Extend `printUsage()` in `Main.kt`. +5. Add the row to `cli/README.md`'s command table. +6. Update `cli/ROADMAP.md` — move the row from 🆕 / 📦 to ✅. + +If you change output shape: note it in the commit message, bump the +example in `README.md`, update any interop fixtures. + +## Where things live + +``` +cli/ +├── README.md # user-facing: commands, JSON contract, quick start +├── DEVELOPMENT.md # touch-the-code: architecture, conventions, testing +├── ROADMAP.md # parity matrix + ordered milestones +├── plans/ # dated design docs (use for new subsystems) +└── src/main/kotlin/…/cli/ + ├── Main.kt # argv dispatch + ├── Args.kt # flag parser + ├── Json.kt # stdout/stderr JSON + ├── Config.kt # Identity, RelayConfig, RunState, DataDir + ├── Context.kt # per-run wiring — the backbone + ├── stores/ # file-backed persistence + └── commands/ # one file per top-level verb group +``` + +Shared logic consumed by Amy lives in `commons/`: +- `commons/account/` — account bootstrap +- `commons/marmot/` — MLS / group state +- `commons/defaults/` — default relays, kinds +- Consult `commons/plans/` for cross-cutting design work in flight. + +## Common mistakes to refuse + +- **Adding protocol logic to `cli/`.** Push back, offer to extract. +- **Silently changing a JSON key.** Flag as breaking. +- **Using `println` or `print`.** Use `Json.writeLine` / `Json.error`. + Plain `System.err.println` is fine for progress logs but never for + user-consumable output. +- **`runBlocking` inside a command** — the top-level `main` already + does that. Commands are `suspend fun`. +- **Depending on `:amethyst` or `:desktopApp`.** Never. If you need + something from there, Rule 5. +- **Re-inventing identifier parsing.** Use `Context.requireUserHex` + or `resolveUserHexOrNull` in `quartz/nip05DnsIdentifiers/`. +- **Re-inventing publish-and-confirm.** Use `Context.publish`. +- **Re-inventing one-shot subscription.** Use `Context.drain`. + +## Plans & design docs + +Cross-cutting design work goes in dated plan docs, in the module +that owns the code being created — not in `docs/plans/`, which is +frozen. + +- `cli/plans/` — Amy-specific subsystems. +- `commons/plans/` — shared code Amy consumes (e.g. + `2026-04-21-event-renderer.md`). + +## Cross-references + +- [`cli/README.md`](../../../cli/README.md) +- [`cli/DEVELOPMENT.md`](../../../cli/DEVELOPMENT.md) +- [`cli/ROADMAP.md`](../../../cli/ROADMAP.md) +- `references/command-template.md` +- `references/extraction-recipe.md` +- `references/output-conventions.md` diff --git a/.claude/skills/amy-expert/references/command-template.md b/.claude/skills/amy-expert/references/command-template.md new file mode 100644 index 000000000..3d46073a2 --- /dev/null +++ b/.claude/skills/amy-expert/references/command-template.md @@ -0,0 +1,98 @@ +# Command-file template + +Copy this shape for every new Amy verb. Resist the urge to deviate — +the uniform shape is what makes commands easy to audit and test. + +## Single-verb command + +```kotlin +package com.vitorpamplona.amethyst.cli.commands + +import com.vitorpamplona.amethyst.cli.Args +import com.vitorpamplona.amethyst.cli.Context +import com.vitorpamplona.amethyst.cli.DataDir +import com.vitorpamplona.amethyst.cli.Json + +object NotePublishCommand { + suspend fun run(dataDir: DataDir, rest: Array): Int { + val args = Args(rest) + val text = args.positional(0, "text") + + val ctx = Context.open(dataDir) + try { + ctx.prepare() + + val event = com.vitorpamplona.amethyst.commons.note + .buildTextNote(ctx.signer, text) + val ack = ctx.publish(event, ctx.outboxRelays()) + + Json.writeLine(mapOf( + "event_id" to event.id, + "kind" to event.kind, + "published_to" to ack.filterValues { it }.keys.map { it.url }, + "rejected_by" to ack.filterValues { !it }.keys.map { it.url }, + )) + return 0 + } finally { + ctx.close() + } + } +} +``` + +## Multi-verb group + +When a feature has several verbs (`note publish`, `note show`, +`note react`), group them: + +```kotlin +object NoteCommands { + suspend fun dispatch(dataDir: DataDir, tail: Array): Int { + if (tail.isEmpty()) return Json.error("bad_args", "note ") + val rest = tail.drop(1).toTypedArray() + return when (tail[0]) { + "publish" -> NotePublishCommand.run(dataDir, rest) + "show" -> NoteShowCommand.run(dataDir, rest) + "react" -> NoteReactCommand.run(dataDir, rest) + else -> Json.error("bad_args", "note ${tail[0]}") + } + } +} +``` + +Each verb gets its own file. Once a single file crosses ~200 lines, +split it — see `GroupCommands.kt` and its siblings as the reference. + +## Wire-up checklist + +For every new command: + +1. File under `cli/commands/`. +2. Branch in `Commands.kt`: + ```kotlin + suspend fun note(dataDir: DataDir, tail: Array): Int = + NoteCommands.dispatch(dataDir, tail) + ``` +3. Branch in `Main.kt`'s top-level `dispatch`: + ```kotlin + "note" -> Commands.note(dataDir, tail) + ``` +4. Line in `printUsage()` explaining the verb. +5. Row in `cli/README.md`'s command table. +6. Status flip in `cli/ROADMAP.md` (🆕 / 📦 → ✅). + +## What not to do + +- No `runBlocking` in a command body — `main()` already does it. +- No `println` / `print` for command output — use + `Json.writeLine(...)`. `System.err.println(...)` is fine for + progress logs (they're already disposable). +- No swallowing errors — let exceptions bubble; `main()` translates + them to `{"error":...}` + exit code. +- No holding a connection open across invocations — every run opens + a fresh `Context` and closes it in `finally`. +- No blocking reads for user input — take a flag. + +## Output-shape rules + +See `output-conventions.md`. diff --git a/.claude/skills/amy-expert/references/extraction-recipe.md b/.claude/skills/amy-expert/references/extraction-recipe.md new file mode 100644 index 000000000..2c3b2daa3 --- /dev/null +++ b/.claude/skills/amy-expert/references/extraction-recipe.md @@ -0,0 +1,137 @@ +# Extract-from-Android recipe + +The single most common reason an Amy feature request stalls: the +logic it needs lives in `amethyst/` with Android-only imports. You +cannot call it from `cli/`. You have to move it first. + +This recipe is how. + +## When to extract + +Before writing a new command, ask: + +1. Does the piece of logic I need exist in `quartz/` or `commons/`? + - **Yes** → use it. + - **No, but it's in `amethyst/`** → extract. This file. + - **No, it doesn't exist anywhere** → design it in `commons/` + directly. Write a plan doc under `commons/plans/` if it's a + new subsystem. + +2. Never duplicate `amethyst/` logic into `cli/`. That's a debt you + will pay later when the Android caller drifts. + +## Recipe + +Land this as its own commit, **before** the commit that adds the +CLI command. + +### Step 1 — Find the class + +```bash +grep -rn "fun followUser\|class FollowListManager" amethyst/src/main/java/ +``` + +Identify the minimum unit to move. Sometimes it's a whole file, +sometimes one function. Prefer the smallest unit that makes the +command possible. + +### Step 2 — List Android-only dependencies + +Walk the imports. The usual offenders: + +| Dependency | Treatment | +|---|---| +| `android.content.Context` | Often accidental — inline if only used for logging or preferences. Otherwise, invert as constructor arg. | +| `android.content.SharedPreferences` | Abstract behind an interface in `commons/`; Android actual uses SharedPreferences, JVM actual uses a JSON file. | +| `androidx.work.WorkManager` | Rarely shareable — if the CLI needs it, simplify the flow to not require background scheduling. | +| `android.util.Log` | Replace with `quartz` `PlatformLog` (already multiplatform). | +| `android.graphics.Bitmap` | Almost never needed by Amy. Keep in Android and split the function. | +| `android.net.Uri` | Replace with `kotlinx.io` path types or a plain `String`. | +| `androidx.compose.*` | Must stay out of `commons/commonMain` unless you're in a Compose-Multiplatform module. Amy doesn't depend on Compose. | + +### Step 3 — Pick a migration strategy per dependency + +- **Inline-able.** One call, trivial. Delete it. +- **Platform-abstractable.** Add `expect` in `commons/commonMain/` + + `actual` in `commons/androidMain/` + `actual` in `commons/jvmMain/`. + See `kotlin-multiplatform` skill for the mechanics and for the + `jvmAndroid` source-set pattern used throughout this repo. +- **Inversion-of-control.** Take the Android dependency as a + constructor arg with an interface type. Amy supplies a JVM flavour; + Android supplies the Context-backed one. + +### Step 4 — Move the code + +```bash +# Target location depends on what it is: +# - Protocol → quartz/src/commonMain/kotlin/… +# - Business logic → commons/src/commonMain/kotlin/… +# - UI → commons/src/commonMain/… (needs Compose Multiplatform) +git mv amethyst/src/main/java/com/.../FollowListManager.kt \ + commons/src/commonMain/kotlin/com/.../FollowListManager.kt +``` + +Update package declarations. Run `./gradlew spotlessApply`. + +### Step 5 — Update the Android caller + +The amethyst/ caller now imports from the new location. Often this +is the only code change visible in the Android app. + +If the Android caller was using a concrete Android-backed +dependency, it now supplies that concrete dependency explicitly. + +### Step 6 — Add a JVM test + +In `commons/src/commonTest/kotlin/…` or `commons/src/jvmTest/kotlin/…` +(depending on what the code exercises), add a test that runs on JVM. +This guards against Android-only imports sneaking back in, and it's +the only way to be sure Amy can now call the code. + +### Step 7 — Commit + +Single commit, descriptive: + +> refactor(follow): extract FollowListManager to commons for CLI reuse +> +> Move FollowListManager from amethyst/model/nip02FollowLists/ to +> commons/commonMain/.../followLists/. Android's SharedPreferences +> dependency is inverted behind FollowListStore (interface); Android +> keeps the SharedPreferences-backed actual, new JvmFollowListStore +> writes JSON to disk. No behaviour change on Android. + +### Step 8 — Now add the CLI command + +Separate commit. Follows the pattern in `command-template.md`. + +## Cautionary notes + +- **Don't extract speculatively.** Only extract what the current + command needs. A feature-complete port can happen later; right now + the goal is to unblock one command without adding surface area you + don't have a second caller for. +- **Android is allowed to keep side-effects.** Notifications, + background services, Intents, camera, permissions dialogs — those + stay in `amethyst/`. Amy's job isn't to replicate UX, it's to + exercise the protocol underneath. +- **Check the consumers.** Sometimes the "logic" you want is already + partially in `commons/`, and the `amethyst/` class is just a thin + wrapper. In that case, re-use the `commons/` class directly and + delete the wrapper or keep it if Android genuinely needs it. +- **Tests first if you're nervous.** Copy the existing + `amethyst/`-side test (if any), make it JVM-only by removing + Android imports, and watch it pass after the move. + +## Red flags during extraction + +Stop and reconsider if: + +- The Android class is 1000+ lines. Extract only the piece the CLI + needs; leave the rest for a follow-up. +- You need `Context` in 30 places. It's probably being used as a + grab-bag; sort by actual use (strings, preferences, services, …) + and abstract those individually. +- You find yourself writing `expect class` with a dozen methods. A + fine-grained interface is usually clearer than a monolithic + expect-actual. +- You're about to add a Compose import to `cli/`. Stop. diff --git a/.claude/skills/amy-expert/references/output-conventions.md b/.claude/skills/amy-expert/references/output-conventions.md new file mode 100644 index 000000000..dc812bb33 --- /dev/null +++ b/.claude/skills/amy-expert/references/output-conventions.md @@ -0,0 +1,114 @@ +# Output conventions + +Amy's JSON contract is its public API. Follow these rules. + +## Channels + +| Stream | What goes here | +|---|---| +| **stdout** | Exactly one JSON object per successful invocation. Nothing else. | +| **stderr** | Human progress logs, warnings, per-relay ACK traces, stack traces, `printUsage()` output. Safe to discard. Not machine-consumed. | + +If a command needs to emit structured data for machines, it goes on +stdout. If it needs to explain what it's doing to a human watching, +stderr. + +## Exit codes + +| Code | Meaning | +|---|---| +| `0` | Success. Stdout has a JSON object. | +| `1` | Runtime error. Stderr has `{"error":"...","detail":"..."}`. | +| `2` | Bad arguments. Stderr has a JSON error object and/or usage. | +| `124` | `await` timed out. | + +Throw the right exception type in commands: + +- `IllegalArgumentException` → exit 2 automatically. +- `AwaitTimeout` → exit 124 automatically. +- Anything else → exit 1. + +The top-level `main()` in `Main.kt` handles the translation. Don't +try-catch at the command level unless you're converting a third-party +exception into one of the above. + +## Object shape + +### Top-level + +Always an object. Never an array, never a primitive, never a +newline-delimited stream. + +```json +{ "event_id": "...", "kind": 1, "published_to": [...] } +``` + +### Keys + +- Stable snake_case. +- Additive evolution is safe; renaming or removing a key is a + breaking change. +- Don't nest unnecessarily. `{"data":{...}}` is noise. + +### Identifiers + +| Thing | Form | +|---|---| +| Event ID | 64-char lowercase hex string. Key name: `event_id`. | +| Pubkey (primary subject) | hex **and** bech32. Keys: `pubkey` + `npub`. | +| Pubkey (secondary reference) | hex only. Key: `pubkey`. | +| Relay URL | Normalized string (`wss://…`). Never an object. | +| Timestamps | Unix seconds, integer. Key names end in `_at`. | +| Group ID (Marmot) | Hex string. Key: `group_id`. | + +### Collections + +- Pluralise: `messages`, `members`, `admins`, `events`. +- Always an array (possibly empty), never `null`. +- Order: oldest-first unless there's a good reason otherwise — state + it in the key name (`messages_newest_first`) if you flip it. + +### Booleans + +- Use `true`/`false`, not `0`/`1`, not `"yes"`. +- Name keys so `true` is the expected/successful state: + `is_member`, `published`, `accepted`. + +### Publish results + +When a command publishes an event, the canonical output shape is: + +```json +{ + "event_id": "", + "kind": 1, + "published_to": ["wss://relay.a/", "wss://relay.b/"], + "rejected_by": ["wss://relay.c/"] +} +``` + +`published_to` is relays that ACK'd `true`. `rejected_by` is relays +that ACK'd `false`. Relays that didn't answer before the timeout +appear in neither — add `timed_out_on` if you need to surface them. + +### Error shape + +```json +{ "error": "code", "detail": "free-form explanation" } +``` + +- `error` is a short, stable, lower_snake code. Agents can branch on + it. +- `detail` is free text — OK to change between versions. +- Common codes today: `bad_args`, `no_identity`, `exists`, `bad_key`, + `not_member`, `timeout`, `runtime`. Reuse before inventing. + +## Never + +- `println(...)` of anything except `Json.writeLine(...)`. +- Multi-line JSON (pretty-printed). One line, always. +- Mixing stdout lines — one command invocation emits one stdout line. + If you need progress updates, they go on stderr. +- Machine output to stderr. The whole point is clean separation. +- Silent fallbacks — if a relay rejects your publish, say so in the + JSON. diff --git a/cli/DEVELOPMENT.md b/cli/DEVELOPMENT.md new file mode 100644 index 000000000..2d5b990c2 --- /dev/null +++ b/cli/DEVELOPMENT.md @@ -0,0 +1,239 @@ +# Developing Amy + +How to touch the `cli/` module without breaking its public contract. + +- What Amy is and what's already shipped: [README.md](./README.md). +- What to build next and in what order: [ROADMAP.md](./ROADMAP.md). +- Plans for cross-cutting work: see this module's `plans/` folder + and `commons/plans/` for shared-code work consumed by Amy. + +The rule this doc defends: **`cli/` is a thin assembly layer**. If +you're writing Nostr protocol logic, filter building, state machines, +or encryption in here, stop — that code belongs in `quartz/` or +`commons/`. + +--- + +## Design principles + +1. **Non-interactive.** One verb = one JSON object on stdout = one + exit code. No REPL, no daemon, no prompts. Any network wait is an + explicit `await` verb with a `--timeout`. +2. **Thin command layer.** Each file in `commands/` parses args, + calls into `commons/` or `quartz/`, and prints JSON. A file longer + than ~200 lines is a code smell — the logic is living in the wrong + module. +3. **Everything persistent is on-disk.** No in-memory caches that + survive between invocations. Every run reloads cursors, MLS state, + identity, and relay config. This is what makes Amy safe to run + from CI and from 100 parallel interop scenarios. +4. **Shared defaults.** When Amethyst picks a default relay, kind, or + tag — Amy calls the same helper. No hand-rolled duplicates. If the + helper doesn't exist yet, extract it to `commons/` first. +5. **JSON is the public API.** Output-shape changes are breaking + changes. Version them explicitly in commit messages; update interop + fixtures. + +--- + +## Architecture + +``` +cli/src/main/kotlin/com/vitorpamplona/amethyst/cli/ +├── Main.kt # argv → subcommand dispatch +├── Args.kt # tiny flag parser (no framework) +├── Json.kt # single-line stdout + error printer +├── Config.kt # Identity, RelayConfig, RunState, DataDir +├── Context.kt # per-run wiring: signer + NostrClient + +│ # MarmotManager + publish/drain/sync helpers +├── stores/FileStores.kt # File-backed MLS / KP / message stores +└── commands/ + ├── Commands.kt # dispatcher + ├── InitCommands.kt # init, whoami + ├── CreateCommand.kt # full bootstrap (→ commons/account/) + ├── LoginCommand.kt # nsec/ncryptsec/mnemonic/npub/nprofile/hex/nip05 + ├── RelayCommands.kt # add/list/publish-lists + ├── KeyPackageCommands.kt # marmot key-package publish / check + ├── GroupCommands.kt # marmot group create/list/show/… + ├── GroupCreateCommand.kt + ├── GroupReadCommands.kt + ├── GroupAddMemberCommand.kt + ├── GroupMembershipCommands.kt + ├── GroupMetadataCommands.kt + ├── MessageCommands.kt # marmot message send / list + └── AwaitCommands.kt # poll-until-condition helpers +``` + +**Dependencies:** `:quartz` + `:commons` + kotlinx-coroutines + OkHttp ++ Jackson. **No Android, no Compose.** Amy compiles on any JDK 21 +host. Never add a Gradle dependency on `:amethyst` or `:desktopApp`. + +**`Context.kt` is the backbone.** Most commands follow this template: + +```kotlin +val ctx = Context.open(dataDir) +try { + ctx.prepare() // restore MLS state + connect relays + ctx.syncIncoming() // pull new gift-wraps + group events + // ...call into commons/ or quartz/ to build an event... + val ack = ctx.publish(event, targets) + Json.writeLine(mapOf(...)) +} finally { + ctx.close() // flush RunState, disconnect +} +``` + +--- + +## How to add a command + +Rule of thumb: **no new logic in `cli/`**. Every command is an +assembly of things that already work elsewhere. + +### 1. Audit (mandatory) + +Before writing anything, answer three questions: + +1. Is the Nostr-protocol piece (event kind, tags, encryption) + already in `quartz/`? If not, add it there first. +2. Is the business logic (state, default values, ordering, filter + assembly) already in `commons/`? If not, extract it from + `amethyst/` into `commons/` in a preceding commit. See the + [extraction recipe](#extract-from-android) below. +3. What is the smallest signed event or query this command has to + produce? That shape is the JSON your command will echo. + +### 2. Extract from Android + +The single most important recurring task for Amy's growth. Most +Amethyst features today live in `amethyst/src/main/java/…/model/` or +`…/service/` with Android-only imports (`Context`, `SharedPreferences`, +`WorkManager`, `Log`, `Bitmap`). Amy cannot call those directly — they +have to move. + +1. Identify the class in `amethyst/` (e.g. `ReactionPost.kt`). +2. List its Android dependencies. +3. For each dependency, choose: + - **Inline-able** (one call, trivial): delete. + - **Platform-abstractable**: add `expect`/`actual` in + `commons/commonMain/…` + `commons/androidMain/…` + + `commons/jvmMain/…`. (See `kotlin-multiplatform` skill.) + - **Inversion-of-control**: take it as a constructor arg. Amy + supplies a JVM flavour. +4. Move the file to `commons/commonMain/…`. +5. Update the Android caller to use the new location. Add a JVM test. +6. Only now, add the `cli/commands/…` file that calls it. + +**What to keep in `amethyst/`:** screens, navigation, Android-specific +side-effects (notifications, background services, camera, Intents). +Everything else is a candidate to move. + +### 3. Command file template + +```kotlin +package com.vitorpamplona.amethyst.cli.commands + +import com.vitorpamplona.amethyst.cli.Args +import com.vitorpamplona.amethyst.cli.Context +import com.vitorpamplona.amethyst.cli.DataDir +import com.vitorpamplona.amethyst.cli.Json + +object NoteCommands { + suspend fun dispatch(dataDir: DataDir, tail: Array): Int { + if (tail.isEmpty()) return Json.error("bad_args", "note ") + val rest = tail.drop(1).toTypedArray() + return when (tail[0]) { + "publish" -> publish(dataDir, rest) + else -> Json.error("bad_args", "note ${tail[0]}") + } + } + + private suspend fun publish(dataDir: DataDir, rest: Array): Int { + val args = Args(rest) + val text = args.positional(0, "text") + val ctx = Context.open(dataDir) + try { + ctx.prepare() + val event = com.vitorpamplona.amethyst.commons.note.buildTextNote(ctx.signer, text) + val ack = ctx.publish(event, ctx.outboxRelays()) + Json.writeLine(mapOf( + "event_id" to event.id, + "kind" to event.kind, + "published_to" to ack.filterValues { it }.keys.map { it.url }, + )) + return 0 + } finally { ctx.close() } + } +} +``` + +Wire it into `Commands.kt`, add a top-level branch in `Main.kt`'s +`dispatch`, and extend `printUsage()`. Keep [README.md](./README.md)'s +command table and [ROADMAP.md](./ROADMAP.md)'s parity matrix in sync. + +### 4. Output-shape conventions + +- Top-level object always. +- Stable snake_case keys. +- Event IDs as hex strings (not npub-style). +- Pubkeys as hex (`"pubkey":…`) **and** bech32 when the pubkey is the + primary subject (`"npub":…`). +- Relay URLs as strings, normalized, never objects. +- Lists of events under a plural key (`"messages"`, `"members"`). +- Errors via `Json.error("code","detail")` — single lower_snake code, + free-form detail. + +--- + +## Testing + +Most of what Amy does is already exercised by tests in `quartz` and +`commons` — the protocol, the builders, the state machines. The thin +Amy-specific layer still needs its own coverage: + +| Layer | Test approach | +|---|---| +| Argument parsing (`Args`, flag forms, `--data-dir=…` vs `--data-dir …`) | Plain JVM unit tests in `cli/src/test/kotlin/`. | +| Error / exit-code contract (bad args → 2, await timeout → 124, runtime → 1) | Table-driven tests invoking `main(argv)` with captured stdout/stderr. | +| JSON output shape (each command's keys and types) | Snapshot tests: run a command against a throwaway data-dir, assert the JSON matches a golden file. | +| File layout on disk (`identity.json`, `relays.json`, `groups/*.mls`, `keypackages.bundle`) | Structural assertions after a command sequence. | +| Round-trip between two data-dirs on a local relay | End-to-end shell scripts under `cli/src/test/resources/scripts/`. Spin up `nostr-rs-relay`, run Alice + Bob, assert await verbs resolve. | +| Interop with other clients | External harness consumes Amy as a binary; out of scope here but the JSON contract is what keeps it stable. | + +**What not to test here:** event signing, filter assembly, MLS +correctness, NIP-44 encryption. Those belong in `quartz`/`commons`. +If an Amy bug can only be caught here, it's a contract violation +(wrong key name, wrong exit code), not a protocol bug. + +**Interop-test script template:** + +```bash +set -euo pipefail +TMP=$(mktemp -d) +A=$TMP/alice; B=$TMP/bob + +amy --data-dir "$A" create --name Alice +amy --data-dir "$B" create --name Bob + +# ... the scenario under test ... + +amy --data-dir "$B" marmot await message "$GID" --match "hello" --timeout 60 +``` + +If an Amethyst scenario cannot be scripted through Amy yet, that's +a gap — add it to [ROADMAP.md](./ROADMAP.md). + +--- + +## Housekeeping + +- Run `./gradlew spotlessApply` before every commit. +- Keep three things in sync: `printUsage()` in `Main.kt`, the command + table in [README.md](./README.md), and the parity matrix in + [ROADMAP.md](./ROADMAP.md). They drift fast. +- Never add a Gradle dependency on `:amethyst` or `:desktopApp`. If + you need something from there, move it to `commons/` first. +- Never introduce a blocking prompt (`readLine()`, interactive + password input). Take it as a flag. +- Keep each command file small. Past ~200 lines, split — the Marmot + `group` verbs are already a cautionary tale. diff --git a/cli/README.md b/cli/README.md new file mode 100644 index 000000000..6304b15d9 --- /dev/null +++ b/cli/README.md @@ -0,0 +1,183 @@ +# Amy — Amethyst CLI + +`amy` is the non-interactive command-line face of Amethyst. It speaks the +same Nostr protocol as the Android and Desktop apps, shares the same +`quartz` and `commons` code, and aims to eventually expose every feature +the GUI offers as a command you can script. + +Amy exists for three audiences at once: + +1. **Humans** using Amethyst from a terminal or remote shell. +2. **Agents / LLMs** driving a Nostr account through a deterministic, + JSON-typed interface — no interactive prompts, no screen scraping. +3. **Interop test harnesses** that put Amethyst side-by-side with the + other ~100 Nostr clients publishing and consuming the same events. + Any flow that is tested in the Amethyst app should be reproducible + through `amy` — that's the bar. + +> Today Amy covers identity, relay config, account bootstrap, and +> Marmot / MLS group chat (MIP-00 / NIP-445). Everything else from the +> Android app is on the roadmap — see [ROADMAP.md](./ROADMAP.md). +> +> To extend Amy, see [DEVELOPMENT.md](./DEVELOPMENT.md). + +--- + +## Output contract + +What every caller — user, script, agent, CI — can rely on: + +- **stdout is JSON. One line. One object.** Stable snake_case keys. + Pipe it into `jq`, parse it from Python, hand it to an agent. +- **stderr is for humans.** Progress, warnings, per-relay ACK traces. + Safe to discard. +- **Exit codes are the real signal.** + - `0` — success + - `1` — runtime error (JSON `{"error":"…","detail":"…"}` on stderr) + - `2` — bad arguments + - `124` — `await` timed out +- **No interactive prompts, ever.** Passwords, names, keys — all flags. +- **Data-dir is the whole world.** All state (identity, relays, MLS + epochs, message archives, run cursors) lives under `--data-dir PATH`. + Delete to reset; copy to move; `AMETHYST_CLI_DATA` env var overrides + the default `./amethyst-cli-data`. + +The rationale behind each of these lives in +[DEVELOPMENT.md](./DEVELOPMENT.md). Breaking any of them is a breaking +change to Amy's public API. + +--- + +## Install + +Until Amy ships as a signed native binary (see +[cli/plans/2026-04-21-cli-distribution.md](./plans/2026-04-21-cli-distribution.md)), +run it from source: + +```bash +# One-shot run — positional args go after `--args`, quoted as one string +./gradlew :cli:run --quiet --args="whoami" + +# Or build a runnable distribution and use the generated launch script +./gradlew :cli:installDist +./cli/build/install/amy/bin/amy whoami +``` + +The `installDist` tree under `cli/build/install/amy/` is self-contained +(JVM launcher + jars) and is what downstream packaging will wrap. + +**Requirements:** JDK 21. + +--- + +## Quick start + +```bash +# 1. Create a data-dir with a full Amethyst-style account. +# Generates a keypair, seeds default NIP-65 / inbox / key-package +# relays, and publishes the nine bootstrap events. +amy --data-dir ./alice create --name "Alice" + +# 2. Publish a fresh MLS KeyPackage so others can invite you. +amy --data-dir ./alice marmot key-package publish + +# 3. Create a group, invite someone, send a message. +amy --data-dir ./alice marmot group create --name "Test Group" +amy --data-dir ./alice marmot group add npub1...bob +amy --data-dir ./alice marmot message send "hello" + +# 4. On the receiving side — poll until Bob sees the invite. +amy --data-dir ./bob marmot await group --name "Test Group" --timeout 60 +amy --data-dir ./bob marmot message list +``` + +Compose with `jq` to chain commands: + +```bash +GID=$(amy --data-dir ./alice marmot group create --name "Test" | jq -r .group_id) +``` + +For an interop-test script template, see +[DEVELOPMENT.md § Testing](./DEVELOPMENT.md#testing). + +--- + +## Command reference + +Run `amy --help` for the canonical list. As of today: + +| Verb | Summary | +|---|---| +| `init [--nsec NSEC]` | Create or import a bare identity. Does not publish anything. | +| `create [--name NAME]` | Provision a full account + publish the nine Amethyst bootstrap events. | +| `login KEY [--password X] [--private]` | Import `nsec` / `ncryptsec` / BIP-39 mnemonic / `npub` / `nprofile` / hex / NIP-05. Read-only when no secret material is supplied. | +| `whoami` | Print the identity stored in `--data-dir`. | +| `relay add URL [--type T]` | `T = nip65 \| inbox \| key_package \| all`. | +| `relay list` | Dump configured relays by bucket. | +| `relay publish-lists` | Publish kind:10002 (NIP-65) + kind:10050 (DM inbox). | +| `marmot key-package publish` | Publish a fresh MLS KeyPackage (kind:30443). | +| `marmot key-package check NPUB` | Fetch someone else's KeyPackage from their advertised relays. | +| `marmot group create [--name NAME]` | New empty group with you as sole admin. | +| `marmot group list` | All groups you're a member of. | +| `marmot group show GID` | Full group state (members, admins, epoch, metadata). | +| `marmot group members GID` | Members only. | +| `marmot group admins GID` | Admins only. | +| `marmot group add GID NPUB [NPUB…]` | Fetch KeyPackages for the npubs and commit an add. | +| `marmot group rename GID NAME` | Commit a metadata change. | +| `marmot group promote GID NPUB` | Make an existing member an admin. | +| `marmot group demote GID NPUB` | Revoke admin. | +| `marmot group remove GID NPUB` | Remove a member. | +| `marmot group leave GID` | Self-remove. | +| `marmot message send GID TEXT` | Publish a kind:9 inner event into the group. | +| `marmot message list GID [--limit N]` | Decrypted inner events, oldest first. | +| `marmot await key-package NPUB` | Block until a KeyPackage is seen on relays. | +| `marmot await group --name NAME` | Block until we're added to a group with that name. | +| `marmot await member GID NPUB` | Block until NPUB is in GID's member set. | +| `marmot await admin GID NPUB` | Block until NPUB is an admin of GID. | +| `marmot await message GID --match TEXT` | Block until a message containing `TEXT` lands. | +| `marmot await rename GID --name NAME` | Block until GID's name matches. | +| `marmot await epoch GID --min N` | Block until GID's MLS epoch is ≥ N. | + +All `await` verbs accept `--timeout SECS` (default 30). Timeout exits 124 +so scripts can distinguish "condition never happened" from "the command +itself crashed". + +### Global flags + +- `--data-dir PATH` — defaults to `./amethyst-cli-data` or + `$AMETHYST_CLI_DATA`. Always an absolute path after resolution. +- `--help` / `-h` — usage summary. + +--- + +## Data-dir layout + +``` +/ +├── identity.json # nsec/npub/hex — the account +├── relays.json # nip65 / inbox / key_package buckets +├── state.json # sync cursors (giftWrapSince, groupSince) +├── keypackages.bundle # MLS KeyPackage bundles (NostrSignerInternal) +└── groups/ + ├── .mls # MLS group state per group + └── .log # decrypted inner events (one JSON per line) +``` + +All files are plain JSON or framed binary — human-inspectable, easy to +diff across two data-dirs in a test run. + +--- + +## Troubleshooting + +- **`no identity`** — run `init`, `create`, or `login` first, or pass a + different `--data-dir`. +- **`not_member`** — the group GID is unknown to this data-dir. Run + `marmot group list` to confirm, or `marmot await group --name …` to + wait for an invite to arrive. +- **Hang on a network verb** — Amy connects to the relays in + `relays.json`; verify with `amy relay list`. Every network-bound + operation has a timeout — use `--timeout` for `await`, or wrap the + whole command in `timeout(1)` if you're scripting. +- **Nothing seems to publish** — inspect stderr; each publish prints + per-relay `OK` / `REJECT` via the `[cli] …` traces. diff --git a/cli/ROADMAP.md b/cli/ROADMAP.md new file mode 100644 index 000000000..fe42a3f40 --- /dev/null +++ b/cli/ROADMAP.md @@ -0,0 +1,109 @@ +# Amy Roadmap + +The live checklist for growing `amy` from a Marmot test-bed into a +full command-line mirror of Amethyst. + +**How to use this file:** update it in the same PR that ships a +feature. Move rows between tables, adjust ordering, add non-goals. +This is the single source of truth for "what's left". + +- How the CLI is used today: [README.md](./README.md) +- How to implement an item: [DEVELOPMENT.md](./DEVELOPMENT.md) +- Ongoing design plans: [plans/](./plans/) +- Shared work consumed here: [../commons/plans/](../commons/plans/) + +--- + +## North-star goal + +> For every feature of the Amethyst Android app, there is a way to +> exercise it through `amy`, with byte-identical on-relay behaviour. + +Why: + +- Interop tests against the ~100 other Nostr clients need a + reproducible harness that does not require running Android. +- Agents and LLMs can script real Amethyst flows without a GUI. +- Regressions in shared logic (signing, encryption, filter building, + event parsing) become shell-scriptable. +- Power users get a command-line Amethyst for free. + +**Non-goal:** Amy is not a second Nostr client implementation. It is +a thin assembly layer over `quartz` + `commons`. Protocol and business +logic in `cli/` are bugs. + +--- + +## Parity matrix + +Status legend: ✅ shipped · 📦 logic lives in `commons/`, needs a command · +🆕 needs extraction from `amethyst/` first · ⚠️ blocked (see Notes). + +| Area | Status | Notes | +|---|---|---| +| Identity create / import (`nsec`, `ncryptsec`, mnemonic, `npub`, `nprofile`, hex, NIP-05) | ✅ | `LoginCommand` + Quartz NIP-05 / NIP-06 / NIP-49 | +| Account bootstrap (nine events) | ✅ | `commons/account/AccountBootstrapEvents.kt` | +| Relay config + NIP-65 / NIP-10050 publish | ✅ | `RelayCommands` | +| MLS KeyPackage publish + fetch | ✅ | `commons/marmot/MarmotManager` | +| Marmot group create / add / rename / promote / demote / remove / leave | ✅ | `commons/marmot/` | +| Marmot message send / list | ✅ | `commons/marmot/` | +| `await` polling (KP / group / member / admin / message / rename / epoch) | ✅ | `AwaitCommands` | +| NIP-01 note publish (`amy note publish TEXT`) | 🆕 | Needs a `commons/` builder wrapper. | +| NIP-01 feed read (`amy feed home`, `amy feed hashtag #X`, `amy feed profile NPUB`) | 🆕 | Extract `FeedFilter` usage from `amethyst/ui/dal/` into `commons/` entry points. | +| NIP-02 follow list add / remove / list | 🆕 | Logic in `amethyst/model/nip02FollowLists/`. | +| NIP-09 event deletion | 🆕 | Builder exists in quartz. | +| NIP-17 DMs send / list / read | 🆕 | Gift-wrap path is already in `commons/` via Marmot — generalise. | +| NIP-18 reposts / quotes | 🆕 | | +| NIP-25 reactions | 🆕 | | +| NIP-51 lists (bookmarks, mute, follow sets) | 🆕 | `amethyst/model/nip51Lists/` | +| NIP-57 zaps (send + verify) | 🆕 | Needs LN-URL plumbing; `amethyst/service/lnurl/`. | +| NIP-65 outbox model queries | 🆕 | | +| NIP-72 communities | 🆕 | | +| NIP-78 app-specific data (settings sync) | 🆕 | | +| Long-form (NIP-23) publish / read | 🆕 | | +| Live activities / chess (NIP-53 / NIP-64) | 🆕 | | +| Blossom uploads (NIP-B7) | 🆕 | | +| NIP-47 Wallet Connect | 🆕 | | +| NIP-46 bunker signer | 🆕 | Needs a signers abstraction in Amy. | +| Profile view (`amy profile show NPUB`) | ⚠️ | Blocked on event-renderer plan in `commons/plans/`. | +| Thread view (`amy thread show EVENT_ID`) | ⚠️ | Same. | +| Notifications feed | 🆕 | | +| Search (NIP-50) | 🆕 | | + +--- + +## Order of operations + +Proposed sequencing. Each step is one PR. Each step should extract +at least one file from `amethyst/` into `commons/`; if it doesn't +move anything, re-audit — you're probably duplicating logic. + +1. **Event rendering core** in `commons/commonMain/.../rendering/` + with renderers for kinds 0 / 1 / 3 / 6 / 7 / 10002 / 10050. + Unblocks all the 🆕 and ⚠️ read-path rows below. + Design: `commons/plans/2026-04-21-event-renderer.md`. +2. **`amy note publish` / `amy note show` / `amy note react`** — + smallest end-to-end write+read loop outside Marmot. +3. **`amy feed home|profile|hashtag|thread`** reading through the + renderer. +4. **`amy follow add|remove|list`** (NIP-02) — proves extraction of + list-building logic from `amethyst/model/`. +5. **`amy dm send|list`** (NIP-17) — reuses the gift-wrap path already + exercised by Marmot. +6. **`amy list bookmarks|mute|pin …`** (NIP-51). +7. **`amy zap send|verify`** (NIP-57). +8. **Distribution** — Homebrew + Scoop + `.deb` in the same release + pipeline as desktop. Plan: `cli/plans/2026-04-21-cli-distribution.md`. +9. **Test suite** — end-to-end against a local relay. +10. **Everything else in the matrix.** + +--- + +## Non-goals + +- Interactive TUI or REPL. +- Native image (GraalVM) until Quartz has a pure-Kotlin signer + fallback — `secp256k1-kmp-jni-*` needs JNI today. +- A Gradle dependency on `:amethyst` or `:desktopApp`. Ever. +- Re-implementing any Nostr protocol piece that's already in + `quartz/` or in another client's library. diff --git a/cli/plans/2026-04-21-cli-distribution.md b/cli/plans/2026-04-21-cli-distribution.md new file mode 100644 index 000000000..9726d6c16 --- /dev/null +++ b/cli/plans/2026-04-21-cli-distribution.md @@ -0,0 +1,89 @@ +--- +title: "feat(cli): native distribution across macOS / Windows / Linux" +type: feat +status: proposed +date: 2026-04-21 +owner: cli +--- + +# feat(cli): native distribution + +## Overview + +Today `amy` ships only as `./gradlew :cli:run` or a raw `installDist` +tree. Fine for dogfooding, not fine for the interop-test audience, +who need a single-binary install on every OS. + +Goal: publish `amy---` artefacts on every GitHub +release, wrapped in the native package managers users already have. + +## Target matrix + +| OS / channel | Strategy | Notes | +|---|---|---| +| macOS (arm64 + x64) | `brew install amy-nostr` | Homebrew formula pointing at a tarball of `installDist` + a jlink'd JRE. Mirrors the existing `amethyst-nostr` cask. | +| Windows | `winget install VitorPamplona.Amy` + `scoop install amy` | `.zip` with `amy.bat` launcher + jlink JRE. | +| Debian / Ubuntu | `.deb` via `jpackage --type deb` | Depends on libc only; jlink JRE bundled. | +| Fedora / RHEL / openSUSE | `.rpm` via `jpackage --type rpm` | Same. | +| Arch | AUR `amy-nostr-bin` | Wrap the `.tar.gz`. | +| Any Linux | `.tar.gz` + AppImage | AppImage for users without a package manager. | +| Nix / NixOS | `nixpkgs` entry | Wrapper around `installDist`. | +| Zapstore | Extend `zapstore.yaml` | Signed by the same Nostr key as the Android app. | +| GitHub Release | All of the above attached as assets | Use `scripts/asset-name.sh` for consistent naming. | + +## Shortest path to first release + +1. Extend the existing `desktopApp` `jpackage` flow to also produce an + `amy---` artefact. Reuse the signing and + notarisation already configured for the desktop build. +2. CI matrix: macos-14 (arm64), macos-13 (x64), windows-latest, + ubuntu-latest. Each runner produces one tarball + one native + installer (`.dmg` / `.msi` / `.deb`). +3. Publish as release assets; no package-manager submission yet. +4. Only after the artefacts are stable (no path churn, no JRE + incompatibilities): submit Homebrew formula, winget manifest, + Scoop bucket, AUR PKGBUILD. + +## Why not GraalVM native-image + +Tempting for startup time but loses FFI to `secp256k1-kmp-jni-*`, +which is how Quartz signs today. Revisit when Quartz ships a +pure-Kotlin fallback signer. + +## Auto-update + +Out of scope for v1. Package managers handle it (`brew upgrade`, +`winget upgrade`, etc). Revisit if manual-install users complain. + +## Size budget + +Target: **< 80 MB installed** with a jlink'd runtime. If we cross +that, audit transitive deps — Amy should not pull in Compose or +Android libs. Verify with `./gradlew :cli:installDist && du -sh +cli/build/install/amy/` on CI and fail the build over a threshold. + +## Risks + +- **Code signing on macOS and Windows** costs real money and requires + secrets rotation. Reuse the desktop app's existing signing setup + rather than standing up a separate keychain. +- **Package-manager review latency.** Homebrew / winget reviews can + take days. Ship tarballs first; submissions later. +- **JRE size.** A jlink'd JDK 21 image is ~40 MB; adding OkHttp + + Jackson + Quartz should land well under the 80 MB budget, but a + bad transitive dep can double it overnight. + +## Open questions + +- Single brew cask `amethyst-nostr` with an `amy` formula alongside, + or a separate `amy-nostr` tap? Probably separate — different update + cadence, different audience. +- Should Amy ship in the same release as the desktop app, or on its + own cadence? Leaning same release — shared CI, shared version — + until the surfaces diverge. + +## Out of scope + +- In-app auto-update UX (no CLI auto-update). +- macOS app notarization of the CLI (only signing). Notarization is + for bundled `.app` GUIs. diff --git a/commons/plans/2026-04-21-event-renderer.md b/commons/plans/2026-04-21-event-renderer.md new file mode 100644 index 000000000..5baf5ac51 --- /dev/null +++ b/commons/plans/2026-04-21-event-renderer.md @@ -0,0 +1,147 @@ +--- +title: "feat(commons): cross-platform event renderer" +type: feat +status: proposed +date: 2026-04-21 +owner: commons +consumers: cli, desktopApp, amethyst +--- + +# feat(commons): cross-platform event renderer + +## Overview + +Introduce a `commons/commonMain/.../rendering/` subsystem that turns a +`quartz` `Event` into a structured, UI-agnostic `RenderedEvent` value. +Three consumers plug into the same output: + +- **Amy** (`cli/`) — serialises `RenderedEvent` to stable JSON. +- **Desktop** (`desktopApp/`) — feeds `RenderedEvent` into Compose views. +- **Amethyst Android** (`amethyst/`) — same, but Android-native layouts. + +This is a `commons/`-owned subsystem because it's consumed by three +modules. Amy drives the need first (it can't read any event it can't +render), but the interface isn't Amy-specific. + +## Problem + +Today every surface that displays a Nostr event re-parses the raw +event structure. Kind:1 rendering, mention resolution, thread roots, +image extraction, hashtag indexing — each lives inline in Compose +components in `amethyst/ui/note/`. Amy cannot share any of it because +it can't depend on Compose or on `amethyst/`. + +Consequences: +- `amy note show` cannot exist without either (a) duplicating the + parsing or (b) extracting it somewhere `cli/` can call. +- Option (b) is the right answer and also fixes Desktop, which is + currently duplicating Android's parsing in a slightly different way. + +## Design + +```kotlin +// commons/commonMain/.../rendering/EventRenderer.kt +interface EventRenderer { + fun render(event: E, ctx: RenderContext): RenderedEvent +} + +data class RenderedEvent( + val kind: Int, + val eventId: HexKey, + val author: AuthorRef, + val createdAt: Long, + val title: String?, + val summary: String?, + val body: List, // text, mention, link, image, video, code + val mentions: List, + val media: List, + val replyTo: EventRef?, + val root: EventRef?, + val raw: Event, // escape hatch +) + +object EventRendererRegistry { + fun register(kind: Int, renderer: EventRenderer<*>) + fun render(event: Event, ctx: RenderContext): RenderedEvent +} +``` + +- Registry keyed by `event.kind`. Default renderer dumps raw tags + + content so nothing is ever un-renderable. +- Per-kind specialised renderers cover what Amethyst displays + specially: 0, 1, 3, 6, 7, 9, 445, 1059 (unwrapped), 10002, 10050, + 30023, 30043, 30311 … +- `RenderContext` carries anything kind-specific needs that's not on + the event itself: a pubkey → metadata lookup, a NIP-05 resolver, a + media-preview cache, etc. Default implementation in `commons/` + with test-friendly no-op behaviour. +- Formatters are separate: + - `JsonEventFormatter.format(rendered): String` — Amy's output. + - `@Composable Render(rendered)` — Desktop + Android. + - `TextEventFormatter.format(rendered): String` — optional + human-readable terminal mode (`amy note show EID --format text`). + +## Migration strategy + +1. Land the interface and `RenderedEvent` data model. No consumers. +2. Port a single kind (kind:1) end-to-end: + - Renderer in `commons/commonMain/.../rendering/`. + - JSON formatter in `commons/commonMain/.../rendering/json/`. + - Compose formatter in `commons/commonMain/.../rendering/compose/`. + - Unit tests in `commonTest`. +3. Desktop and Amethyst switch their kind:1 path to the new renderer. + Delete the old inline parsing. +4. Repeat for kind:0, kind:7, kind:3, kind:6, kind:10002, kind:10050 + (this unblocks Amy's feed commands). +5. Then the long tail. + +Each step is small and reversible. Each step deletes duplicated +parsing somewhere. + +## Consumer touch-points + +- **Amy** — `cli/commands/NoteCommands.kt#show`: + ```kotlin + val rendered = EventRendererRegistry.render(event, ctx.renderCtx) + Json.writeLine(JsonEventFormatter.toMap(rendered)) + ``` +- **Desktop** — replace ad-hoc parsing in `desktopApp/.../note/*` with + `EventRendererRegistry.render(event, renderCtx)` + `Render(rendered)`. +- **Android** — same swap in `amethyst/ui/note/*`. + +## Test strategy + +- `commonTest`: golden tests per kind. A fixture event → a fixture + `RenderedEvent`. Same fixtures feed both formatters. +- JSON formatter tests become Amy's snapshot tests for free. + +## Open questions + +- `RenderContext` scope: should async lookups (pubkey metadata) be + inside the renderer or pre-resolved by the caller? Leaning pre- + resolved — renderers stay pure, caller decides hydration policy. +- Do we render gift-wraps at all, or only their unwrapped inner + events? Leaning: unwrap first in `quartz`/`commons`, then render + the inner event. Outer kind:1059 gets a trivial default renderer. +- `BodySpan` granularity: does rich-text parsing (hashtag, mention, + link detection) live inside the kind-specific renderer or in a + shared post-processor? Leaning post-processor so every text-bearing + kind gets it for free. + +## Risks + +- Scope creep: this is a new subsystem. Keep the first PR tiny + (interface + default renderer only, zero consumers). +- Compose lock-in: the `@Composable Render` surface must live in + `commons/commonMain/` to avoid forcing Amy to see Compose. Verify + that's possible with Compose Multiplatform 1.10.3 — if not, split + into `commons-render-core` (pure Kotlin) + `commons-render-compose`. + +## Out of scope + +- Event authoring / composition (new-post editor). Renderer is + read-only. +- Relay-subscription plumbing. Renderer takes an already-received + `Event`, not a filter. +- Media loading (image download, video playback). Renderer emits + `MediaRef`; the consumer decides what to do with it.