@alphafox/cli 0.1.4 → 0.2.0

package/docs/release-supply-chain.md

@@ -1,49 +1,122 @@
 # Release: npm, Skills, supply chain (t101375)
 
+**Status:** Frozen (G0)  
+**Date:** 2026-08-13  
+**Canonical package:** `@alphafox/cli` on the public npmjs.org registry.
+
+This document freezes distribution policy. It supersedes the earlier draft that
+named `@alphafoxai/cli` (that name was never published; npmjs returns 404).
+
 ## Package
 
-| Field | Value |
-|-------|--------|
-| Name | `@alphafoxai/cli` |
-| Binary | `alphafox` |
-| Visibility | public npm (org `@alphafoxai`) |
-| Node | LTS ≥ 20 |
-| OS | macOS, Linux, Windows |
+| Field | Frozen value |
+|-------|----------------|
+| Name | `@alphafox/cli` |
+| Binary | `alphafox` (`bin/alphafox.js`) |
+| Registry | `https://registry.npmjs.org/` |
+| Visibility | **public** (`publishConfig.access=public`) |
+| npm org / owner | `@alphafox` scope; maintainer `alphafox <joe@alphafox.app>` |
+| License | MIT |
+| Node | LTS **≥ 20** (`engines.node`) |
+| OS | macOS, Linux, Windows (npm install; no standalone native binary in v1) |
+| Package contents | `bin/`, `dist/`, `skills/`, `README.md`, `docs/`, `LICENSE` |
+
+v1 does **not** ship independent GitHub Release binaries, so there is no extra
+binary signing/checksum channel. Integrity is npm pack integrity plus
+provenance (below).
+
+Do **not** republish under `@alphafoxai/cli` without a new ADR. Skills and docs
+that still mention that name are stale and must follow this freeze.
 
-## Publish rules
+## Publish rules (normative)
 
-- Publish **only** from CI on protected tags (`v*`)
-- Prefer npm **trusted publishing / OIDC provenance** — no long-lived npm tokens
-- 2FA required for org owners
-- Package contents: `dist/`, `skills/`, README, docs — **no** secrets, fixtures, private endpoints, or `.env`
+1. Publish **only** from CI on a protected git tag matching `v*` (example:
+   `v0.2.0`). Humans must not `npm publish` from a laptop for any release
+   after this freeze, except an explicit incident rollback documented in the
+   change ticket.
+2. CI MUST use npm **trusted publishing / OIDC provenance**. Long-lived npm
+   tokens are forbidden for publish.
+3. npm org owners MUST have 2FA. Publish permission is CI identity plus owners;
+   no shared user tokens in git or chat.
+4. Package tarball MUST NOT contain secrets, test fixtures with credentials,
+   `.env`, private endpoints, or internal-only hostnames.
+5. `prepublishOnly` builds from the tagged SHA. The published `CLI_VERSION`
+   (or equivalent) MUST equal the npm version.
+
+### Grandfathered 0.1.x
+
+npmjs currently has `@alphafox/cli@0.1.0`–`0.1.5` (latest `0.1.5`). Those
+tarballs have registry signatures and **no** provenance attestations
+(`dist.attestations` is empty). They were published by the human npm user
+`alphafox`. They remain installable but are **not** the compliance target.
+The next minor/patch that this policy covers MUST be the first
+OIDC-provenance release.
 
 ## Skills distribution
 
-- Co-versioned inside the npm package under `skills/`
-- Compatibility: Skills major aligns with CLI major; `contractVersion` must match API or CLI fails closed
+- Skills ship **inside** the same npm tarball under `skills/` (co-versioned).
+- Skills major aligns with CLI major. There is no separate Skills registry
+  in v1 and no silent download of a different Skills version at runtime.
+- `contractVersion` on the CLI profile MUST match the Public API
+  `contractVersion` (or the documented compatible range). Mismatch → fail
+  closed; do not download an older contract or degrade quietly.
+
+## Compatibility / channels / deprecation
+
+| Channel | npm dist-tag | Meaning |
+|---------|--------------|---------|
+| stable | `latest` | Supported release |
+| prerelease | `next` | Opt-in only |
 
-## Support matrix
+- Breaking API/contract/minCLI/maxCLI changes: announce ≥ **30 days** before
+  `latest` moves; keep the previous compatible CLI installable on npm.
+- Incompatible CLI ↔ API ↔ contract: CLI exits non-zero with a machine-readable
+  error. No silent skip, no automatic down-version.
+- Emergency unpublish is a last resort (npm unpublish window). Preferred:
+  `npm deprecate @alphafox/cli@<bad> "<reason>; use <good>"` and tell
+  operators to install the last good version.
 
-| Platform | Install | Keychain |
-|----------|---------|----------|
-| macOS | npm global / npx | Keychain Access |
-| Linux | npm global / npx | Secret Service or file fallback 0600 |
-| Windows | npm global / npx | Credential Manager (file fallback until implemented) |
+## Support matrix (install / update / uninstall)
 
-## Channels
+| Platform | Install | Update | Uninstall | Secrets |
+|----------|---------|--------|-----------|---------|
+| macOS | `npm install -g @alphafox/cli` or `npx @alphafox/cli` | `npm update -g @alphafox/cli` or pin `@<version>` | `npm uninstall -g @alphafox/cli` | Keychain Access |
+| Linux | same | same | same | Secret Service, or file fallback mode `0600` |
+| Windows | same | same | same | Credential Manager (`CredWrite`/`CredRead`); file fallback mode `0600` if unavailable |
 
-- `latest` — stable
-- `next` — prerelease
-- Deprecation window: ≥ 30 days for breaking contract changes
+Fresh-machine acceptance (release checklist, not optional):
+
+```bash
+npm install -g @alphafox/cli@<version>
+npm view @alphafox/cli@<version> --json   # attestations present after first OIDC release
+alphafox version
+alphafox doctor
+alphafox schema me.whoami
+```
 
 ## Rollback
 
 ```bash
-npm install -g @alphafoxai/cli@<previous>
+npm install -g @alphafox/cli@<previous-compatible>
 alphafox version
 alphafox doctor
 ```
 
+Failed install leaves the previous global binary in place (npm does not
+half-replace). If `doctor` fails after a successful install, roll back with
+the command above. Do not point the CLI at a different environment to “make
+it work”.
+
 ## SBOM / audit
 
-CI should generate SBOM (e.g. `cyclonedx` / `npm sbom`) and fail on critical vulns in runtime deps.
+CI MUST emit an SBOM (`npm sbom` or CycloneDX) from the tagged SHA and fail
+the release job on **critical** vulnerabilities in **runtime** dependencies.
+Dev-only advisories do not block publish. SBOM is an artifact of the release
+workflow, not a file committed to `main` by default.
+
+## Out of scope (v1)
+
+- Private npm / GitHub Packages as the user install path
+- Homebrew / scoop / standalone signed binaries
+- Separate Skills marketplace
+- Automation-token distribution (ADR 0004)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphafox/cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Alphafox CLI \u2014 Agent/Human entry for the public Application API.",
   "type": "commonjs",
   "bin": {
@@ -18,8 +18,10 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/postbuild.cjs",
+    "generate:catalog": "node scripts/generate-catalog.mjs",
+    "check:catalog-drift": "node scripts/generate-catalog.mjs --check",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node scripts/build-mvp-web-bundle.mjs && tsc -p tsconfig.test.json && node --test dist-test/**/*.test.js",
+    "test": "npm run check:catalog-drift && npm run build && node scripts/build-mvp-web-bundle.mjs && tsc -p tsconfig.test.json && node --test dist-test/**/*.test.js",
     "test:mvp": "node scripts/build-mvp-web-bundle.mjs && tsc -p tsconfig.test.json && node --test dist-test/tests/mvp-oauth-web-handlers.test.js",
     "alphafox": "node dist/cli.js",
     "prepublishOnly": "npm run build"

package/skills/account/SKILL.md

@@ -1,21 +1,23 @@
 ---
 name: alphafox-account
 description: Account, wallet, and subscription read paths.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Account / wallet
 
+Always `--format json --no-input`. These paths are read-first. Wallet mutations are write/high-risk — `--dry-run` then `--yes`; never auto-retry.
+
 ```bash
-alphafox api GET /api/v1/wallet
-alphafox api GET /api/v1/account/exchange-uids
-alphafox api GET /api/v1/subscriptions/me
-alphafox api GET /api/v1/managed-wallets
+alphafox api GET /api/v1/wallet --format json --no-input
+alphafox api GET /api/v1/account/exchange-uids --format json --no-input
+alphafox api GET /api/v1/subscriptions/me --format json --no-input
+alphafox api GET /api/v1/managed-wallets --format json --no-input
 ```
 
 ## operationIds
 
 - `wallet.get`
 - `account.exchange_uids.list`
-- `subscriptions.me.get`
+- `subscriptions.me.get` (facade `GET /api/v1/subscriptions/me`)
 - `managed_wallets.list`

package/skills/admin/SKILL.md

@@ -1,18 +1,23 @@
 ---
 name: alphafox-admin
 description: Admin-only operations reusing Web role authorization.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Admin
 
-Requires admin role on the server. CLI confirmation does not grant privilege.
+Requires admin role on the server. CLI confirmation does not grant privilege. Not available to automation (v1 deferred). Always `--format json --no-input`.
 
 ```bash
-alphafox api GET /api/v1/admin/users
+alphafox api GET /api/v1/admin/users --format json --no-input
 ```
 
-High-risk admin writes: `--dry-run` then `--yes`. Not available to automation (v1 deferred).
+High-risk admin writes: `--dry-run` then `--yes`. If the operator is not admin, expect `403` and stop.
+
+## Recovery
+
+- `401`: re-auth. `403`: not admin — do not escalate by switching profiles.
+- Uncataloged admin POST/PATCH/DELETE still require `--yes` (unknown risk).
 
 ## operationIds
 

package/skills/alphafox-shared/SKILL.md

@@ -1,20 +1,22 @@
 ---
 name: alphafox-shared
 description: Shared Alphafox CLI rules for Agents — auth, profiles, envelopes, risk gates, and public operationIds only.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Alphafox shared Agent contract
 
+Co-versioned with `@alphafox/cli`. Query compatibility with `alphafox version --format json` (`version`, `contractVersion`, `catalogVersion`) and `alphafox catalog`.
+
 ## Install / identity
 
 ```bash
-npx @alphafoxai/cli version
-npx @alphafoxai/cli doctor
+npx @alphafox/cli version --format json --no-input
+npx @alphafox/cli doctor --format json --no-input
 ```
 
 - Default profile: `production`. Use `--profile staging|local` explicitly.
-- Tokens: OS keychain only. Never pass `--token`. Never read tokens from config JSON.
+- Tokens: OS keychain only (macOS Keychain, Linux Secret Service, Windows Credential Manager). Never pass `--token`. Never read tokens from config JSON.
 - Automation tokens are **not supported in v1** (interactive Device Flow / PKCE only).
 
 ## Output
@@ -25,35 +27,42 @@ Always use:
 alphafox … --format json --no-input
 ```
 
-Parse the JSON envelope: `ok === true` for success. Errors land on **stderr** with `ok: false` and may include HTTP `status` + `requestId`.
+Optional: `--jq '<filter>'` requires the `jq` binary; missing jq fails closed (does not print the unfiltered envelope).
+
+Parse the JSON envelope: `ok === true` for success. Errors land on **stderr** with `ok: false` and may include HTTP `status` + `requestId`. Stream watch uses JSONL. Do not parse human tables.
 
 ## Auth
 
 ```bash
-alphafox auth login --no-wait
-# show verification_uri to the user, then:
-alphafox auth login --device-code <device_code>
-alphafox auth status --verify
-alphafox whoami
+alphafox auth login --no-wait --format json --no-input
+# show verification_uri / user_code to the human, then:
+alphafox auth login --device-code <device_code> --format json --no-input
+alphafox auth status --verify --format json --no-input
+alphafox whoami --format json --no-input
 ```
 
+Local browser: `alphafox auth login --browser --format json --no-input` (loopback 127.0.0.1). If the browser cannot open, copy `authorizeUrl` from the error; do not invent a Device Flow retry unless the operator is headless.
+
+Wrong environment / missing permission / missing `--yes`: stop. Do not retry with a different profile.
+
 ## Commands
 
 1. Prefer typed catalog: `alphafox schema <operationId>` then invoke domain commands.
 2. Raw escape hatch only for allowlisted facade:
 
 ```bash
-alphafox api GET /api/v1/me
+alphafox api GET /api/v1/me --format json --no-input
 ```
 
-Forbidden: `/backend`, `/control-plane`, `/signal-center`, internal secrets, non-`/api/v1` product routes.
+Forbidden: `/backend`, `/control-plane`, `/signal-center`, internal secrets, non-`/api/v1` product routes, `--token`.
 
 ## Risk
 
-- `high-risk-write` requires `--yes` (exit code `10` if missing).
+- `high-risk-write` and uncataloged mutations (`unknown`) require `--yes` (exit code `10` if missing).
 - Prefer `--dry-run` first for trader start/stop, withdrawals, admin writes.
 - Never auto-retry unknown write outcomes.
+- CLI `--yes` is UX only; the server still enforces role, ownership, and scopes.
 
 ## Public operationIds only
 
-Skills must reference registry `operationId`s (see `alphafox schema` / `alphafox catalog`). Do not hardcode internal service URLs.
+Skills must reference registry `operationId`s (see `alphafox schema` / `alphafox catalog`). Shortcuts may only compose those operationIds. Do not hardcode internal service URLs or invent a second catalog.

package/skills/auth/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-auth
 description: Login, status, logout, whoami, and environment isolation for Alphafox CLI.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Auth Skill
@@ -10,24 +10,39 @@ version: 0.1.0
 
 User needs to sign in, verify session, switch profile, or revoke tokens.
 
+Always `--format json --no-input`. Never `--token`.
+
 ## Workflows
 
 ### Device Flow (headless / Agent)
 
-1. `alphafox auth login --no-wait --format json`
+1. `alphafox auth login --no-wait --format json --no-input`
 2. Present `verification_uri` / `user_code` to the human.
-3. After approval: `alphafox auth login --device-code <device_code>`
-4. `alphafox whoami` / `alphafox auth status --verify`
+3. After approval: `alphafox auth login --device-code <device_code> --format json --no-input`
+4. `alphafox whoami --format json --no-input` / `alphafox auth status --verify --format json --no-input`
+
+### Browser loopback (human, local machine)
+
+1. `alphafox auth login --browser --format json --no-input`
+2. CLI binds `127.0.0.1` and opens the system browser. Do not copy codes or verifiers.
+3. After the localhost callback, `alphafox whoami` / `alphafox auth status --verify`
+4. If the browser cannot open, the error includes a copyable `authorizeUrl`. Do not retry as Device Flow unless the human is headless.
 
 ### Status / logout
 
-- `alphafox auth status --verify`
-- `alphafox auth logout` (server revoke + local keychain clear)
+- `alphafox auth status --verify --format json --no-input`
+- `alphafox auth logout --format json --no-input` (server revoke + local keychain clear). If `remoteRevoke` is `failed`, local tokens are still cleared but exit is non-zero — do not claim a full logout.
+
+### Recovery
+
+- `401` / `expired_token`: re-run Device Flow or browser login. Do not reuse a token from another profile.
+- Cross-env: production tokens are rejected on staging/local. Switch `--profile` only with explicit operator intent.
 
 ## Safety
 
 - Fail closed on cross-environment tokens (prod token never hits staging).
 - Do not copy refresh tokens into CI (automation deferred — ADR 0004).
+- Scopes: `openid` `profile` `offline_access` at grant time.
 
 ## operationIds
 

package/skills/exchange/SKILL.md

@@ -1,16 +1,23 @@
 ---
 name: alphafox-exchange
 description: Exchange connectors list and connection management via Public API.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Exchange connectors
 
+Always `--format json --no-input`. List is `exchange-connectors:read`.
+
 ```bash
-alphafox api GET /api/v1/exchange-connectors
+alphafox api GET /api/v1/exchange-connectors --format json --no-input
 ```
 
-Writes that create/disable connectors may be `high-risk-write` — use `--dry-run` / `--yes`.
+Writes that create/disable connectors may be `high-risk-write` — use `--dry-run` / `--yes`. Uncataloged connector POST is treated as unknown risk and still needs `--yes`.
+
+## Recovery
+
+- `403` / wrong resource: stop. Do not retry with production tokens on staging.
+- Never log connector secrets from request bodies.
 
 ## operationIds
 

package/skills/market/SKILL.md

@@ -1,14 +1,19 @@
 ---
 name: alphafox-market
 description: Market data and spread-radar readonly queries.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Market
 
+Always `--format json --no-input`. Prefer readonly scopes. No mock success if upstream fails.
+
 ```bash
-alphafox api GET /api/v1/market/symbols
-alphafox api GET /api/v1/spread-radar/pairs
+alphafox api GET /api/v1/spread-radar/pairs --format json --no-input
+alphafox api GET /api/v1/market/symbols --format json --no-input
 ```
 
-Prefer readonly scopes. No mock success if upstream fails.
+## operationIds
+
+- `spread_radar.pairs.list`
+- `market.symbols.list`

package/skills/notification/SKILL.md

@@ -1,16 +1,21 @@
 ---
 name: alphafox-notification
 description: Notification channels and subscriptions.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Notification
 
+Always `--format json --no-input`. List is `notification:read`. Channel create/replace/delete may be write or high-risk — `--dry-run` / `--yes`.
+
 ```bash
-alphafox api GET /api/v1/notification/channels
-alphafox api GET /api/v1/notification/subscriptions
+alphafox api GET /api/v1/notification/channels --format json --no-input
+alphafox api GET /api/v1/notification/subscriptions --format json --no-input
 ```
 
+If a path is not allowlisted, stop with the structured error. Do not call notification internals.
+
 ## operationIds
 
 - `notification.channels.list`
+- `notification.subscriptions.list`

package/skills/strategy/SKILL.md

@@ -1,35 +1,41 @@
 ---
 name: alphafox-strategy
 description: Strategy definitions, chats, and backtests via public operationIds.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Strategy / Chat / Backtest
 
+Always `--format json --no-input`. Read scopes `trading:read` / `backtests:read`; writes `chats:write` / `backtests:write`.
+
 ## Read
 
 ```bash
-alphafox schema trading.strategy_definitions.list
-alphafox api GET /api/v1/trading/strategy-definitions
+alphafox schema trading.strategy_definitions.list --format json --no-input
+alphafox api GET /api/v1/trading/strategy-definitions --format json --no-input
 ```
 
 ## Write (ordinary)
 
 ```bash
-alphafox api POST /api/v1/chats --body '{"strategyGenerationMode":"simple"}'
+alphafox api POST /api/v1/chats --body '{"strategyGenerationMode":"simple"}' --format json --no-input
 ```
 
-Requires auth. Sends `Idempotency-Key` when available.
+Requires auth. Sends `Idempotency-Key` when available. Duplicate key → `409`; do not invent a new key unless the operator asks to create another chat.
 
 ## Long-running backtest
 
 ```bash
-alphafox api POST /api/v1/backtests --body '{...}'
-alphafox api GET /api/v1/backtests/{backtestId}
-alphafox api GET /api/v1/backtests/{backtestId}/stream
-alphafox api POST /api/v1/backtests/{backtestId}/cancel --body '{}'
+alphafox api POST /api/v1/backtests --body '{"chatId":"<chat-id>"}' --format json --no-input
+alphafox api GET /api/v1/backtests/{backtestId} --format json --no-input
+alphafox api GET /api/v1/backtests/{backtestId}/stream --format jsonl --no-input
+alphafox api POST /api/v1/backtests/{backtestId}/cancel --body '{}' --format json --no-input
 ```
 
+`backtests.create` requires `chatId`. `strategyId` is optional: the facade resolves a compiled strategy on that chat. A chat with no compiled strategy returns `CHAT_HAS_NO_COMPILED_STRATEGY` (not `JOB_NOT_FOUND`). Optional `backtestSettings` overlays chat settings when it is a settingsJson object.
+
+If the stream drops, `GET` the backtest by id — do not assume success. Cancel is explicit; interruption must remain queryable.
+
 ## operationIds
 
 - `trading.strategy_definitions.list`

package/skills/trading/SKILL.md

@@ -1,25 +1,35 @@
 ---
 name: alphafox-trading
 description: Traders list and high-risk start/stop with confirmation gates.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Trading
 
+Always `--format json --no-input`. Read first. Writes need scopes `trading:write`; start/stop also `trading:high-risk`.
+
 ## Read
 
 ```bash
-alphafox api GET /api/v1/trading/traders
+alphafox api GET /api/v1/trading/traders --format json --no-input
 ```
 
 ## High-risk write
 
 ```bash
-alphafox api POST /api/v1/trading/traders/{traderId}/start --body '{}' --dry-run
-alphafox api POST /api/v1/trading/traders/{traderId}/start --body '{}' --yes
+alphafox api POST /api/v1/trading/traders/{traderId}/start --body '{}' --dry-run --format json --no-input
+alphafox api POST /api/v1/trading/traders/{traderId}/start --body '{}' --yes --format json --no-input
 ```
 
-Without `--yes`, CLI exits `10` with `confirmation_required`.
+Without `--yes`, CLI exits `10` with `confirmation_required`. Server still checks role/ownership.
+
+Stop: `POST /api/v1/trading/traders/{traderId}/stop` with the same `--dry-run` then `--yes` sequence.
+
+## Recovery
+
+- `403`: missing scope or not owner — stop, do not retry `--yes`.
+- `409`: trader already in the requested state — report, do not loop start/stop.
+- Unknown HTTP after a write: do not auto-retry.
 
 ## operationIds