@thirdfy/agent-cli 0.1.48 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-05-23
+
+### Changed
+
+- **npm README** — replaced the multi-version release wall with `## What's new in vX.Y.Z` (current semver only) and a CHANGELOG link; removed maintainer publish instructions from the npm homepage.
+- **`validate:public-docs`** — enforces README/npm surface rules (current version heading, CHANGELOG link, no maintainer publish strings, max inline version highlights).
+- **Cursor rules** — `npm-readme-surface.mdc` plus updates to public-docs and release flow rules; maintainer publish detail stays in `docs/releasing.md` / `docs-dev/publishing.md`.
+
+## [0.2.1] - 2026-05-23
+
+### Changed
+
+- **Commander.js is now the active router**: `program.parseAsync()` registers all commands via `src/cli/manifest.mjs`, shared option bundles under `src/cli/options/`, and JSON-aware `exitOverride` handling. Handlers and envelopes remain 1:1 with 0.2.0.
+- Removed `dispatch.mjs` and the hybrid `parseArgs()` + `mergeCommanderGlobals()` entry path.
+- Unknown CLI flags now error via Commander (previously ignored by the hand-rolled parser).
+- Thirdfy API `GET /api/v1/agent/cli/capabilities` `profileDefaults.personal` aligned to `agent_wallet` (matches CLI `PROFILE_DEFAULTS`).
+
+### Added
+
+- `src/runtime/` — organized CLI runtime layer: `main.mjs` (orchestration), `errors.mjs`, `onboardingHints.mjs`, `execution/*`, `actions/selection.mjs`, plus command factories under `src/commands/` (`discovery`, `telemetry`, `credentials`, `agent`, `doctor`, `prompt`). `bin/thirdfy-agent.mjs` remains a thin entrypoint.
+- `npm run validate:provider-parity`, `validate:cli-manifest-handlers`, `validate:runtime-boundaries`, `validate:release-preflight` (also `prepublishOnly`), and optional `validate:live-api-capabilities` when `THIRDFY_API_BASE` is set.
+- Provider parity also asserts DogeOS provider ids (`dogeos-barkswap`, `dogeos-laika`, `dogeos-ecosystem`) in CLI selection + MCP.
+- `test/commander-routing.test.cjs` — `-V`, `--version --json`, unknown command/option envelopes, `help onboarding`.
+
+### Fixed
+
+- `-V` / `--version` no longer print the full Commander help tree before the version string (early argv handling before `parseAsync`).
+
+### Agent / operator notes
+
+- **No argv path or JSON envelope changes** for documented commands; Hermes/OpenClaw/cron scripts need no changes.
+- Optional Fly pin after publish: `THIRDFY_AGENT_CLI_PACKAGE=@thirdfy/agent-cli@0.2.1`.
+
+## [0.2.0] - 2026-05-23
+
+### Changed
+
+- Modular CLI layout: `src/core/` (HTTP, context, envelope, run modes), `src/commands/` (execute, delegation, wallet, bootstrap, polymarket, hyperliquid), `src/cli/` (help + initial Commander globals).
+
+### Added
+
+- `commander` dependency; `npm run validate:npm-pack` guards published tarball paths.
+- `npm run e2e:local-api:smoke` — fail-fast smoke against a local Thirdfy API (`THIRDFY_API_BASE`, default `http://127.0.0.1:3000`).
+
+### Agent / operator notes
+
+- **No argv or JSON envelope changes** for Hermes, OpenClaw, or cron scripts that invoke `thirdfy-agent` as a subprocess.
+
 ## [0.1.48] - 2026-05-23
 
 ### Fixed

package/README.md

@@ -40,11 +40,12 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## Release notes
+## What's new in v0.2.2
 
-Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **v0.1.48** fixes earn provider filtering so generic `deposit_earn_position` / `withdraw_earn_position` rows only appear for matching adapters (not unrelated morpho/vaults-fyi filters). **v0.1.47** adds CapyFi, FX, and bridge provider discovery hints. **v0.1.46** routes `polymarket status` through `get_polymarket_funding_status` with config `agentKey` and defaults dry-run to `place-polymarket-order` (pairs with API **v3.4.37**). **v0.1.45** adds `polymarket status`, `polymarket setup`, and `polymarket dry-run` for agent-scoped setup/geoblock preflight (pairs with API **v3.4.35**). **v0.1.44** adds Aegis provider hints for Base and Unichain earn reads and fail-closed Engine writes (pairs with API **v3.4.28**). **v0.1.43** injects Hyperliquid `userAddress` from the managed execution wallet for solo `agent_wallet` reads when omitted (pairs with API **v3.4.27**). **v0.1.42** persists API `executionWallets` from email login, updates `doctor auth` / onboarding help for agent execution wallet funding vs owner embedded auth wallet, and documents Bridge2 `FUND_AGENT_EXECUTION_WALLET` remediation (pairs with API **v3.4.25**). **v0.1.41** documents Hyperliquid `get_hyperliquid_funding_status` as setup step 0, Bridge2 sender custody, and `deposit_hyperliquid_bridge --estimated-amount-usd` (pairs with API **v3.4.24**). **v0.1.40** fixes email/bootstrap credential persistence when the API returns nested registration payloads, so owner-session onboarding can save the hidden execution identity without exposing a raw agent API key. **v0.1.39** makes `agent_wallet` the fresh solo default, adds framework guidance for Hermes/OpenClaw/Claude Managed Agents, clarifies Gator/ERC-7710 delegation flows, and keeps BYOW/self plus hybrid/thirdfy mode switching explicit. **v0.1.38** is a **documentation and metadata patch**: it republishes to npm so the package homepage matches the updated `README.md` on `main`, and aligns root `package-lock.json` version fields with `package.json`. **v0.1.37** adds **email OTP** `thirdfy-agent login email` (send code, then complete with `--code --accept-terms`), **`help onboarding`**, **`doctor auth`**, **`wallet list`**, and **masked `whoami`** output so agents and operators get first-run guidance without dumping secrets. Earlier releases added provider discovery parity, portfolio analytics, managed-wallet swap normalization, and **self/build-tx** swap human-decimal `amountIn` parity when using `amountInHuman` + `tokenInDecimals`.
+- **npm README cleanup** — the registry homepage is user-facing again: one **What's new** section for the current version, full history in [CHANGELOG.md](./CHANGELOG.md) (no multi-version release wall or maintainer publish steps on npm).
+- **Public docs validation** — `npm run validate:public-docs` enforces README/npm surface rules before publish.
 
-**Maintainers — npm:** follow [docs/releasing.md](./docs/releasing.md). From a clone with gitignored `.env`, use `npm run publish:npm:local -- --dry-run` then `npm run publish:npm:local`. Or run `npm run release:npm` after exporting tokens in the shell. Never commit npm tokens — use [.env.example](./.env.example) as a template only.
+Older highlights (Commander routing, stricter flags): see [CHANGELOG.md](./CHANGELOG.md) · [GitHub Releases](https://github.com/thirdfy/agent-cli/releases).
 
 ## Quick start
 
@@ -62,6 +63,15 @@ thirdfy-agent intent-status --intent-id "<intentId>" --json
 
 By default, the CLI targets production (`https://api.thirdfy.com`). Use `--api-base` (or `THIRDFY_API_BASE`) only for staging/dev/custom deployments.
 
+### Local API smoke
+
+With Thirdfy API running locally (default `http://127.0.0.1:3000`):
+
+```bash
+export THIRDFY_API_BASE=http://127.0.0.1:3000
+npm run e2e:local-api:smoke
+```
+
 ## Auth model
 
 - `AGENT_API_KEY`: execution identity for `preflight`, `run`, `self-exec`, and policy-aware discovery.
@@ -303,6 +313,12 @@ Provider and venue guides are kept outside `README` so this page stays stable as
 - Delegation execution helpers: `delegation balance`, `delegation redeem`
 - Account: `credits balance`
 
+## CLI routing (Commander + runtime)
+
+Since **v0.2.1**, [`bin/thirdfy-agent.mjs`](./bin/thirdfy-agent.mjs) is a thin entrypoint. Routing lives in [`src/cli/manifest.mjs`](./src/cli/manifest.mjs) (Commander `parseAsync`); behavior and handler wiring live in [`src/runtime/`](./src/runtime/). JSON envelopes, subcommand paths, and global flags (`--json`, `--api-base`, `--run-mode`, …) match **0.1.x** for documented flows. **Unknown flags now error** instead of being silently ignored. Built-in Commander `help` is disabled so `thirdfy-agent help onboarding` keeps working.
+
+Maintainers validating releases locally: `npm run validate:release-preflight`. After API deploy: `THIRDFY_API_BASE=https://api.thirdfy.com npm run validate:live-api-capabilities`.
+
 ## Where to find what is supported
 
 - Full command groups and usage map: [`docs/command-reference.md`](./docs/command-reference.md)
@@ -419,29 +435,15 @@ Managed-self execution performs strict wallet preflight and returns deterministi
 - Creator platform (agent registration and keys):
   [thirdfy.com/creator](https://thirdfy.com/creator)
 
-## Development
+## Contributing
+
+From a git clone of this repository:
 
 ```bash
-npm run validate:cli-contract-schemas
+npm ci
+npm run validate:public-docs
 npm test
 npm run smoke:cli
-npm run e2e:self:managed-custody-validation
-npm run e2e:managed:delegation:parity
 ```
 
-## Release
-
-Version history and user-facing notes: [CHANGELOG.md](./CHANGELOG.md) (for example [v0.1.39](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.39) — agent-wallet solo default, framework guidance, and delegation UX; [v0.1.38](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.38) — npm README + lockfile metadata alignment; [v0.1.37](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.37) — email OTP login, onboarding help, auth doctor, wallet list, masked `whoami`). **Before every version bump or npm publish:** update this **README** (release notes paragraph, quick start, and command groups) so the npm package page matches what ships; keep `CHANGELOG.md`, [command reference](./docs/command-reference.md), and MCP summaries aligned when discovery or onboarding surfaces change.
-
-```bash
-npm version patch
-npm publish --access public
-git push origin main --follow-tags
-```
-
-Release contract:
-
-- Keep `package.json` version and `CHANGELOG.md` synchronized in the release PR.
-- The git tag must be `vX.Y.Z` and match `package.json` exactly.
-- Push the matching tag so the [Release workflow](.github/workflows/release.yml) creates or aligns the GitHub release entry.
-- If npm already contains that version, the workflow skips republishing and still creates/aligns the GitHub release when triggered by the tag.
+Version history lives in [CHANGELOG.md](./CHANGELOG.md). Maintainer publish steps: [docs/releasing.md](./docs/releasing.md).