@arcadiasystems/morse-cli 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,7 +4,69 @@ All notable changes to `@arcadiasystems/morse-cli` are documented here. The
 format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - unreleased
+## [0.3.0] - 2026-06-04
+
+Event-based file listing, wrapping the SDK 0.3.0 reconcile helpers. Purely
+additive; all existing commands are unchanged.
+
+### Added
+
+- `morse file list`: list files owned by an address (default: the active
+  account), or, with `--accessible`, files decryptable via allowlist membership.
+  `--address <addr>` queries another address, `--hydrate` fetches the full record
+  per file (adds `blobId`; one read each), `--limit <n>` caps results, `--json`
+  emits the summary array.
+- Event fetching via `cli/events.ts`: a paginator over `suix_queryEvents` feeding
+  the SDK's pure `reconcileFilesOwnedBy` / `reconcileFilesAccessibleBy` helpers.
+  `--indexer-url <url>` overrides the event source (any endpoint that speaks
+  `suix_queryEvents`).
+
+### Changed
+
+- Depends on `@arcadiasystems/morse-sdk` `^0.3.0`.
+
+### Notes
+
+- Listing reads `suix_queryEvents`, a deprecated Sui JSON-RPC endpoint Mysten is
+  sunsetting; on the public RPC it may degrade over time. Use `--indexer-url` to
+  point at your own indexer. Results are best-effort and eventually consistent.
+- Summaries omit `blobId`/`blobObjectId` (not in the `FileCreated` event); use
+  `--hydrate` to fetch them.
+
+## [0.2.0] - 2026-06-04
+
+Wraps the allowlist + encrypted-file surface from `@arcadiasystems/morse-sdk`
+0.2.0. Existing publication / collection / entry / cap commands are unchanged.
+
+### Added
+
+- `morse allowlist` group: `create`, `add-member`, `remove-member`,
+  `transfer-cap`, `delete`, `get`, `list-caps`. The admin Cap is auto-resolved
+  from the active account when `--cap` is omitted (mirrors OwnerCap/PublisherCap
+  resolution). `transfer-cap` and `delete` confirm unless `--yes`.
+- `morse file` group: `upload` (encrypt with `--allowlist` or `--public`, upload
+  to Walrus, and register; prints a seal id for encrypted files), `register`
+  (register metadata for a blob already on Walrus), `download` (fetch content,
+  decrypting in place for encrypted files via `--seal-id`), `get`, `update`,
+  `transfer-ownership`, `delete`.
+- `entry read` / `entry decrypt` / `file download` accept `--via-aggregator` to
+  read through the Walrus aggregator HTTP service instead of the storage-node
+  protocol (more reliable when nodes are flaky; trades client-side blob
+  verification for operator trust).
+
+### Changed
+
+- Depends on `@arcadiasystems/morse-sdk` `^0.2.0` (testnet `packageId` updated to
+  the contracts v2 deployment).
+
+### Notes
+
+- A file's seal id is not recoverable from its ciphertext; save the value
+  printed by `file upload` to decrypt later.
+- Listing files accessible by allowlist membership is not exposed (encrypted
+  files are shared objects with no owner index); it needs event indexing.
+
+## [0.1.0] - 2026-05-29
 
 ### Added
 

package/README.md

@@ -6,7 +6,7 @@ content entries from your terminal, signing with a locally encrypted key.
 Content is stored on [Walrus](https://walrus.xyz); private entries are encrypted
 with [Seal](https://github.com/MystenLabs/seal).
 
-> Status: v0.1.0, targeting Sui testnet. The command surface is stable; mainnet
+> Status: v0.3.0, targeting Sui testnet. The command surface is stable; mainnet
 > support lands when the contracts are frozen.
 
 ## Requirements
@@ -187,13 +187,13 @@ and `-C, --collection <name>`, both defaulting to the active context.
 | Command | Purpose |
 | --- | --- |
 | `entry get <entryId> [-P …] [-C …]` | Fetch a single entry's metadata. |
-| `entry read <entryId> [revisionIndex] [--out <path>] [-P …] [-C …]` | Fetch a public entry's content to stdout or a file. |
+| `entry read <entryId> [revisionIndex] [--out <path>] [--via-aggregator] [-P …] [-C …]` | Fetch a public entry's content to stdout or a file. |
 | `entry list [-P …] [-C …]` | List entries (paginated). |
 | `entry scan [-P …] [-C …]` | List every entry (auto-paginated). |
 | `entry add <name> --file <path> [-P …] [-C …]` | Upload content and add a new entry; prints a viewable link. |
 | `entry delete <entryId> [-P …] [-C …]` | Delete an entry. |
 | `entry add-encrypted <name> --file <path> [-P …] [-C …]` | Encrypt, upload, and add a new entry. |
-| `entry decrypt <entryId> [revisionIndex] [--out <path>] [-P …] [-C …]` | Decrypt an encrypted revision. |
+| `entry decrypt <entryId> [revisionIndex] [--out <path>] [--via-aggregator] [-P …] [-C …]` | Decrypt an encrypted revision. |
 
 `add`, `add-encrypted`, and the revision commands accept `--file <path>` (or `-`
 for stdin), `--stdin`, and `--content-type <type>` (inferred from the file
@@ -228,6 +228,49 @@ OwnerCap and PublisherCap IDs are auto-resolved from the active account when the
 `--owner-cap` / `--publisher-cap` override is omitted. Destructive operations
 (`delete`, `revoke`, `destroy`, `transfer`) confirm interactively unless `--yes`.
 
+### allowlist
+
+Per-wallet allowlists gate who can decrypt encrypted files. The admin Cap is
+auto-resolved from the active account when `--cap` is omitted.
+
+| Command | Purpose |
+| --- | --- |
+| `allowlist create --name <name>` | Create an allowlist; transfers its admin Cap to you. |
+| `allowlist add-member <addr> -a <id> [--cap <id>]` | Add a wallet that may decrypt. |
+| `allowlist remove-member <addr> -a <id> [--cap <id>]` | Remove a wallet. |
+| `allowlist transfer-cap <recipient> -a <id> [--cap <id>] [-y]` | Hand off admin rights. |
+| `allowlist delete -a <id> [--cap <id>] [-y]` | Delete an allowlist (dependent files become undecryptable). |
+| `allowlist get <id>` | Show an allowlist's name and members. |
+| `allowlist list-caps [address]` | List allowlist admin Caps held by an address. |
+
+### file
+
+| Command | Purpose |
+| --- | --- |
+| `file upload <path> --name <n> [-a <id>] [--public] [--content-type <m>] [--epochs <n>]` | Upload to Walrus and register; `-a` encrypts, `--public` is world-readable. |
+| `file register --blob-id <id> --name <n> --content-type <m> --size <bytes> [-a <id>] [--public] [--blob-object-id <id>]` | Register metadata for a blob already on Walrus. |
+| `file download <file> [--out <path>] [--seal-id <hex>] [--via-aggregator]` | Download content; decrypts in place when encrypted. |
+| `file list [--address <addr>] [--accessible] [--hydrate] [--limit <n>] [--indexer-url <url>]` | List files owned by (or, with `--accessible`, decryptable by) an address. |
+| `file get <file>` | Fetch a file's on-chain metadata. |
+| `file update <file> --name <n> --content-type <m>` | Update name and MIME (owner only). |
+| `file transfer-ownership <file> <newOwner> [-y]` | Transfer the metadata right (not decrypt access). |
+| `file delete <file> [-y]` | Delete the metadata record (the Walrus blob expires on its own lease). |
+
+Encrypting a file (`file upload -a <allowlist>`) prints a **seal id**. It is not
+recoverable from the ciphertext, so save it: `file download` needs it (via
+`--seal-id`) plus allowlist membership to decrypt.
+
+`file list` reconstructs the file set from contract events. Encrypted files are
+shared objects with no on-chain owner index, so listing is event-derived, not a
+direct query. By default the command reads events via `suix_queryEvents` on the
+configured Sui RPC. That endpoint is **deprecated** (Mysten is sunsetting it), so
+listing may degrade or stop working on the public RPC over time; point
+`--indexer-url <url>` at any source that speaks `suix_queryEvents` (a self-hosted
+indexer, a third-party endpoint) to stay in control. Results are best-effort and
+eventually consistent (subject to indexer lag and retention). `EncryptedFileSummary`
+rows omit `blobId`/`blobObjectId`; add `--hydrate` to fetch the full record per
+file (one read each) when you need them.
+
 ## Output and scripting
 
 - Human-readable output goes to stdout; progress, warnings, and prompts go to
@@ -257,6 +300,7 @@ OwnerCap and PublisherCap IDs are auto-resolved from the active account when the
   - [`encrypt-decrypt.sh`](./examples/encrypt-decrypt.sh): encrypt with Seal and decrypt back.
   - [`delegation.sh`](./examples/delegation.sh): issue a PublisherCap to a delegate, then revoke it.
   - [`ci-noninteractive.sh`](./examples/ci-noninteractive.sh): env-var auth, `--yes`, and `--json` parsing.
+  - [`files.sh`](./examples/files.sh): allowlist + encrypted file round-trip (create allowlist, add a member, upload, download/decrypt, plus a public file).
 
 ## Limitations
 
@@ -266,6 +310,11 @@ OwnerCap and PublisherCap IDs are auto-resolved from the active account when the
   retrieved with `entry decrypt`, not `entry read`. A shareable Walrus link is
   printed by `entry add` (the `viewUrl` field), since the content id is known at
   upload time.
+- `entry read` and `entry decrypt` default to reading from Walrus storage nodes,
+  which verifies the bytes against the on-chain blob id. Pass `--via-aggregator`
+  to read through the Walrus aggregator HTTP service instead: more reliable when
+  storage nodes are flaky (common on testnet), at the cost of trusting the
+  aggregator's bytes (no client-side verification).
 - Mainnet is not yet deployed; use `testnet`.
 
 ## Publishing
@@ -289,6 +338,23 @@ then `npm publish` (the package is `publishConfig.access: public`). `npm publish
 ships `dist`, `docs`, `README.md`, `LICENSE`, and `CHANGELOG.md` (see the `files`
 allowlist). Publish the SDK first; the CLI depends on `@arcadiasystems/morse-sdk`.
 
+## Development
+
+| Command | What it does |
+| --- | --- |
+| `bun run test:unit` | In-process tests only (no subprocesses); ~2s, for a tight edit loop. |
+| `bun run test:cli` | Subprocess CLI-smoke tests (`test/cli/`); spawns the real bin. |
+| `bun test` | The full hermetic suite (unit + CLI smoke), no network. |
+| `bun run typecheck` | `tsc --noEmit`. |
+| `bun run lint` | Biome check. |
+| `bun run coverage` | Run the suite with coverage and enforce the floor. |
+| `bun run check` | Typecheck, lint, and the coverage gate (the CI gate). |
+| `bun run test:e2e` | Live testnet lifecycle. Opt-in: needs `MORSE_PRIVATE_KEY` (or `.env.testnet`) funded with testnet SUI and WAL. Set `MORSE_E2E_AGGREGATOR=1` to route the read steps through `--via-aggregator`. |
+
+The test layering, coverage policy, and anti-flake rules are described in
+`CLAUDE.md`. CI runs `check` and `build` on every push and PR that touches the
+package (`.github/workflows/cli-ci.yml`); the live e2e is excluded from CI.
+
 ## License
 
 MIT