@kashdao/cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to `@kashdao/cli` will be documented in this file.
+
+The format is based on [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).
+
+While the package is `0.x`, minor versions may include breaking changes —
+breaking changes are explicitly called out in the entry. See the
+**Stability promise** section of `README.md` for what is and is not part
+of the SemVer-stable contract.
+
+The runtime contract surface (error envelope, version manifest, config
+envelope, command tree) is also pinned by `tests/unit/contracts.test.ts`
+— any drift there forces a deliberate update to both the schema and
+the test, which surfaces in this changelog.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-20
+
+Initial public release.
+
+### Added
+
+- **`kash setup`** — interactive first-run wizard (masked API key
+  prompt, profile selection, shell-completion install, health probe,
+  scope canary). Non-interactive via `--yes --api-key <key>`. Re-runnable
+  on existing configs (updates, not duplicates).
+- **Multi-profile support** — `~/.kash/config.json` holds named profiles
+  (`default`, `live`, `test`, etc.). Switch via `--profile <name>`,
+  `KASH_PROFILE=<name>`, or `kash config use <name>`. Per-profile
+  `apiKey`, `baseUrl`, `defaultChainId`, plus protocol-mode fields
+  (`rpcUrl`, `smartAccount`, `bundlerUrl`, `bundlerProvider`,
+  `signerKeyRef`, `customChain`).
+- **Auto-routing** — a `kash_test_*` API key auto-routes to staging
+  (`api-staging.kash.bot`); a `kash_live_*` key routes to production
+  (`api.kash.bot`). Mirrors `@kashdao/sdk`'s `inferBaseUrlFromApiKey()`.
+  Explicit `--base-url` or `KASH_BASE_URL` always wins.
+- **Two orchestration modes — both fully non-custodial.** On every
+  path: Kash never holds funds, never moves funds, never holds keys,
+  and never signs anything. User funds always live in accounts the
+  user controls. See SECURITY.md § Non-custodial design for the full
+  statement.
+  - **Kash-orchestrated (default)** — uses the Kash public REST API
+    (`kash markets`, `kash quote`, `kash trade`, `kash portfolio`,
+    `kash webhooks`, `kash auth`, `kash trace`, `kash account`). The
+    API key is a scoped, revocable delegation the user issues against
+    their own Privy-managed smart account.
+  - **Self-orchestrated (`kash protocol ...`)** — wraps
+    `@kashdao/protocol-sdk` (signer + RPC + bundler all consumer-side).
+    Zero Kash backend dependency. Lazy-loaded — adds no cold-start
+    cost for users who stay on the Kash-orchestrated path.
+- **JSON-everywhere** — every command accepts `--json` for a stable
+  machine-readable envelope (single object on stdout, errors on stderr).
+  `kash docs --json` returns the full command tree for tooling.
+- **Idempotency** — `--auto-idempotency-key` on trade commands, or pass
+  `--idempotency-key <uuid>` manually. Replays return the cached
+  response.
+- **Webhook ops** — `kash webhooks list`, `redeliver <eventId>`,
+  `rotate-secret`, `replay <file>` (offline signature preview).
+- **Trade lifecycle** — `kash trade buy/sell`, `--dry-run` preview,
+  `--wait` polling until terminal, `kash trade status <id>`,
+  `kash trade confirm <id> --token <token>` for high-value flows,
+  `kash trade list --filter`.
+- **High-value confirmation flow** — gracefully handles
+  `pending_confirmation` responses with a `--token` prompt or
+  `--auto-confirm` for trusted contexts.
+- **`kash trace <correlationId>`** — end-to-end request-id trace from a
+  trade or webhook delivery, walks the event chain across services.
+- **Typed errors + recovery hints** — every error includes a code, a
+  recovery suggestion (e.g., DNS errors against `api.kash.bot` suggest
+  using a test key), and a `kash explain <CODE>` reference.
+- **Shell completion** — bash, zsh, fish via the `omelette` integration.
+  Installed during `kash setup` (skippable with `--yes`).
+- **Cross-platform install** — npm (`npm i -g @kashdao/cli`), pnpm,
+  or yarn. A Homebrew tap (`kashdao/tap`) is planned for the
+  production launch.

package/CONTRIBUTING.md

@@ -0,0 +1,159 @@
+# Contributing to `@kashdao/cli`
+
+Thanks for considering a contribution. The CLI is the customer-facing
+entry point for both humans and AI agents using the Kash API — every
+behaviour here is something an integration may have pinned, so we hold
+the bar high.
+
+## How development works
+
+This repo (`KashDAO/cli`) is the **public mirror** of the CLI. The
+canonical source lives inside Kash's private monorepo, and is synced
+to this repo on every release. Pull requests land here in the public
+mirror, get reviewed, and once accepted are re-imported into the
+monorepo.
+
+That's the same model Stripe (`stripe/stripe-cli`), GitHub
+(`cli/cli`), and AWS use — public client, private server.
+
+What that means in practice:
+
+- ✅ Open issues and PRs in this repo.
+- ✅ Comment on PRs, request changes, propose alternatives.
+- ❌ The full Kash backend isn't visible from this repo. The CLI
+  speaks to `https://api.kash.bot/v1` like any other consumer (or
+  directly on-chain for `kash protocol …` and `kash eoa …`).
+
+## Quick start
+
+```sh
+git clone https://github.com/KashDAO/cli.git
+cd cli
+pnpm install
+pnpm build
+pnpm test
+node dist/index.js --version
+```
+
+Requires Node 22+ and pnpm 9+.
+
+## What's in scope
+
+✅ Welcome:
+
+- Bug fixes — especially in error envelope construction, output
+  formatting, and the contract surface (`kash version`,
+  `kash schema`, `kash docs`, `kash explain`).
+- New examples under `examples/` for novel integration patterns.
+- Better help text, JSON schema docs, and `--help` examples.
+- Test coverage for edge cases (TTY detection, NDJSON streaming,
+  signal handling, BOM-aware stdin).
+- Cold-start performance (stay lazy on heavy deps).
+
+🟡 Discuss first (open an issue):
+
+- New commands or subcommands.
+- New flags on existing commands.
+- Changes to the contract surface — `CliErrorEnvelopeSchema`,
+  `VersionManifestSchema`, `CliConfigEnvelopeSchema`, the
+  `CliCapabilitySchema` enum, or any `kash *--json` shape that
+  agents may have pinned.
+- New error codes in `src/error-catalog.ts` or changes to existing
+  recovery `actions[]`.
+- Bumping the minimum Node version.
+
+❌ Out of scope:
+
+- Wrapping the CLI in a programmatic Node API. Use
+  [`@kashdao/sdk`](https://www.npmjs.com/package/@kashdao/sdk) or
+  [`@kashdao/protocol-sdk`](https://www.npmjs.com/package/@kashdao/protocol-sdk)
+  directly — the CLI exists for shells and agents, not as a library.
+- New runtime dependencies. The bundle is small by design; if you
+  need a small utility, write it inline.
+- Auto-formatters / lint plugins beyond what `eslint.config.js`
+  already configures.
+
+## Standards
+
+- **Stable JSON contracts.** Every `--json` output is pinned to a
+  Zod schema in `src/cli-schemas.ts`. Adding a field is a minor
+  bump; removing or renaming one is a breaking change. Both are
+  flagged by `tests/unit/contracts.test.ts`.
+- **Two audiences, both first-class.** Humans get colored tables,
+  spinners, and tab completion; agents get `--json --quiet` with
+  structured errors. Don't optimise one path at the cost of the
+  other.
+- **Errors are typed.** Throw `CliError` / `CliValidationError` from
+  `src/errors.ts`; never throw plain `Error`. Every code in
+  `src/error-catalog.ts` carries a `recoverable` flag and an
+  `actions[]` array of recovery hints.
+- **Output through `src/utils/output.ts`.** Direct `console.log`
+  bypasses `--quiet` handling and chalk detection. The ESLint config
+  enforces this everywhere except inside `output.ts` itself.
+- **Lazy-load heavy deps.** Cold start matters. The protocol-sdk and
+  viem are loaded only on the first `kash protocol …` or
+  `kash eoa …` invocation. Don't add top-level imports of `viem` or
+  `@kashdao/protocol-sdk` to commands that don't need them.
+- **`run_command` actions with `<placeholder>` tokens MUST set
+  `template: true`.** Agents auto-shell concrete commands; templated
+  ones are surfaced for substitution. The contract test enforces
+  this.
+
+## Workflow
+
+1. **Fork** this repo and create a feature branch:
+   `git checkout -b feat/add-xyz`.
+2. **Make the change.** Run `pnpm typecheck`, `pnpm lint`, and
+   `pnpm test` after each substantial edit.
+3. **Add tests.** Cover happy path + at least one failure mode.
+   If you touch a schema in `src/cli-schemas.ts`, update
+   `tests/unit/contracts.test.ts` to pin the new shape.
+4. **Document.** Update the README, the `kash <cmd> --help` text,
+   and `CHANGELOG.md` under `[Unreleased]`.
+5. **Open a PR** with a short summary explaining the _why_, not
+   just the _what_. Link any related issue.
+
+There is **no automated CI on this public mirror** for v0.x — the
+maintainers run typecheck, lint, the unit + component suite, and
+the runtime smoke (`scripts/runtime-smoke.mjs`) locally before
+merging your PR.
+
+## Testing
+
+```sh
+pnpm test                 # unit + component
+pnpm typecheck
+pnpm lint
+pnpm build && node scripts/runtime-smoke.mjs   # built-binary smoke
+```
+
+The component suite under `tests/component/` drives the real binary
+through Commander; no API mocks are needed for the contract surface.
+The unit suite under `tests/unit/` covers envelope shapes, the error
+catalog, install-script behaviour, and per-command flag matrices.
+
+`tests/unit/contracts.test.ts` is the gatekeeper for the SemVer-stable
+contract surface. If your PR causes a failure there, the contract
+shape has drifted — update both the schema in `src/cli-schemas.ts`
+AND the contract test deliberately, document the change in CHANGELOG,
+and call it out in the PR description.
+
+## Commit messages
+
+Conventional commits:
+
+```
+feat: add `kash mcp serve` (Model Context Protocol)
+fix: honour --quiet on early SIGPIPE
+docs: document --refuse-private-addresses on webhooks replay
+test: cover the BOM-aware stdin path
+```
+
+(No scope needed — everything here is the CLI.)
+
+## Questions
+
+- General product questions: [GitHub Discussions](https://github.com/KashDAO/cli/discussions)
+- Security vulnerabilities: see [SECURITY.md](./SECURITY.md) —
+  please don't open public issues for security findings.
+- Anything else: open an issue and we'll route it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 KashDAO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.