amethyst/.claude/skills/amy-expert/SKILL.md

---

name: amy-expert description: amy CLI in cli/: adding an amy <verb> command, Main.kt dispatch, Output.emit/--json contract, exit codes 0/1/2/124, ~/.amy layout, cli/tests harnesses. Use when touching cli/. Enforces the thin-assembly rule: logic goes to commons/quartz.

amy CLI

cli/ is a non-interactive JVM client over quartz + commons. Its --json output and exit codes are a public API that the interop harnesses depend on. The long-form contract is cli/DEVELOPMENT.md ("Public contract", "How to add a command", "Output-shape conventions", "Testing", "Full on-disk layout"); this skill is the short version plus the traps.

Rules

1. Thin assembly layer. No protocol, filter assembly, state machines or encryption in cli/. Protocol goes to quartz/; business logic to commons/, extracted from amethyst/ first in its own commit if needed (references/extraction-recipe.md). A commands/*.kt file over ~200 lines is a smell. cli may depend on :geode (for amy serve), never on :commonsUI, :amethyst or :desktopApp.
2. Output goes through Output (cli/src/main/kotlin/…/cli/Output.kt).
   • Output.emit(mapOf(...)): the map is the --json shape (one line, one object, stable snake_case keys); the default text render comes from the same map and has no contract.
   • return Output.error("code", "detail"): the return value is the exit code (bad_args 2, timeout 124, anything else 1). Errors go to stderr (error: code: detail, or a JSON object under --json).
   • Exit codes 0 ok, 1 runtime, 2 bad args, 124 await timeout. runCli in Main.kt also maps a thrown IllegalArgumentException to 2 and AwaitTimeout to 124.
   • Never println results; System.err.println is for progress logs only.
   • Adding a --json key is safe. Renaming or removing one is breaking: say so in the commit, and update cli/README.md and the fixtures under cli/tests/.
   • Publishes: RawEventSupport.publishGuard(ack, id) then + RawEventSupport.ackFields(ack) (published_to + rejected_by: [{relay, reason}]). Don't hand-roll the projection.
   • Reuse an error code from the canonical list in cli/DEVELOPMENT.md before minting one.
3. Non-interactive. Everything is a flag; a network wait is an explicit await verb with --timeout. The only TTY fallback is PassphraseProvider (after --passphrase-file and $AMY_PASSPHRASE); don't add more.
4. ~/.amy/ is the whole state, reloaded on every run; no in-process caches across runs. ~/.amy/shared/events-store/ (one event store for all accounts), ~/.amy/<account>/ (identity.json, state.json, aliases.json, marmot/), ~/.amy/current (written by amy use NAME). Account selection is the global --account NAME; --name stays free for subcommands. New persisted state goes through Config.kt / stores/FileStores.kt / a named helper like Aliases.kt.
5. $HOME, not user.home. DataDir.DEFAULT_ROOT (Config.kt) reads $HOME; JDK 21's user.home comes from getpwuid and ignores it, which would break harness isolation (HOME=$(mktemp -d) amy --account alice init). JVM tests use the amy.home system property seam instead.

Adding a command

Copy the shape of a real one, e.g. commands/FollowCommand.kt: a USAGE constant, parse with Args (positional, flag, longFlag, …, then args.rejectUnknown()), Context.open(dataDir).use { ctx -> ctx.prepare(); … }, call into commons/quartz, publish with ctx.publish or read with ctx.drain, emit one map. Commands are suspend fun; main already runs runBlocking. Multi-verb groups dispatch through route(...) in commands/Router.kt.

Wire-up: a branch in Main.kt's dispatch (marmot sub-verbs go in marmotDispatch), lines in printUsage() and printVerbList(), a row in cli/README.md, the status in cli/ROADMAP.md, and a harness case under cli/tests/ when wire behaviour changes.

Don't re-invent what exists: user identifiers via ctx.requireUserHex (or quartz nip05DnsIdentifiers/resolveUserHexOrNull); rendering via commons rendering/ (EventRendererRegistry, json/JsonEventFormatter); event lookup and loading via commons relayClient/oneshot/ (OneShotNoteCache, EventLocator, ThreadLoader, NotificationsLoader, over OneShotRelayAccess; amy's adapter is NoteSupport.access(ctx)); builders in commons actions/ and model/.

Where things live

• cli/src/main/kotlin/com/vitorpamplona/amethyst/cli/: Main.kt (dispatch, global flags, usage), Args.kt, Output.kt, Config.kt (DataDir, identity, state), Context.kt (per-run wiring), stores/, secrets/, and commands/ (~110 files, one per verb or group, plus cashu/, graperank/, trust/). Run ls on commands/ rather than trusting a list.
• cli/README.md (user tour), cli/DEVELOPMENT.md (contract), cli/ROADMAP.md, cli/plans/.
• Build: ./gradlew :cli:installDist → cli/build/install/amy/bin/amy. JVM contract tests: ./gradlew :cli:test (ArgsTest, ExitCodeContractTest, JsonContractTest, harness in CliResult.kt).
• cli/tests/: shell harnesses (lib.sh, headless/helpers.sh, one directory per suite: dm/, marmot/, notes/, cache/, git/, …), most against an embedded amy serve relay with a fresh $HOME. See cli/tests/README.md.