@thirdfy/agent-cli 0.1.48 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+### 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.
+- Maintainer-only operator docs (provider platform audit, Hermes post-publish smoke) moved out of npm-facing `docs/` paths.
+- `npm run validate:provider-parity` — CI guard for earn/capyfi/fx/bridge/trading/hyperliquid/polymarket/bitfinex hints (reads `src/runtime/providerHints.mjs`).
+- `npm run validate:cli-manifest-handlers` and `npm run validate:runtime-boundaries` — manifest handler coverage and import-boundary checks.
+- `npm run validate:release-preflight` — full publish gate (lint, validators, tests, npm pack, smoke); `prepublishOnly` runs it.
+- `npm run validate:live-api-capabilities` — optional post-deploy check when `THIRDFY_API_BASE` is set (`profileDefaults`, DogeOS chain routing).
+- Provider parity script also asserts DogeOS provider ids (`dogeos-barkswap`, `dogeos-laika`, `dogeos-ecosystem`) in CLI selection + MCP.
+
+### Changed
+
+- Thirdfy API `GET /api/v1/agent/cli/capabilities` `profileDefaults.personal` aligned to `agent_wallet` (matches CLI `PROFILE_DEFAULTS`).
+
+### Fixed
+
+- `-V` / `--version` no longer print the full Commander help tree before the version string (early argv handling before `parseAsync`).
+- Commander regression tests for clean `-V` / `--version` output.
+
+## [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).
+
+### Added
+
+- `test/commander-routing.test.cjs` — `-V`, `--version --json`, unknown command/option envelopes, `help onboarding`.
+
+### 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

@@ -42,7 +42,7 @@ npx @thirdfy/agent-cli --help
 
 ## Release notes
 
-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`.
+Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **v0.2.1** ships full [Commander.js](https://github.com/tj/commander.js) routing (`parseAsync`, manifest-registered subcommands, JSON-aware errors) with **1:1 argv/envelope behavior** vs 0.1.x — Hermes/OpenClaw/cron scripts need no changes; optional Fly pin `@thirdfy/agent-cli@0.2.1` after publish. Unknown flags now error instead of being silently ignored. **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`.
 
 **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.
 
@@ -62,6 +62,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 +312,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)