@hs-x/cli 0.2.0 → 0.2.1

package/README.md

@@ -1,1027 +1,138 @@
-# HS-X CLI Interfaces
+# @hs-x/cli
 
-> **Status: design doc, not a current-state reference.**
->
-> This file is the CLI *contract* — what `hs-x` will look like at completion. Many sections below describe commands, flags, or packages that are **not yet implemented**. For the actually-shipped CLI surface, run `hs-x --help` or read `packages/cli/src/index.ts` (the dispatch switch is the source of truth).
->
-> Sections that drift from current implementation are marked inline with `[NOT YET IMPLEMENTED]` or `[PARTIAL]`. As of v1 (2026-06), shipped top-level commands are: `init` (alias `create`), `check`, `validate`, `deploy`, `connect`, `secrets`, `link`, `unlink`, `login`, `whoami`, `logout`, `completion`, `api`, `account`/`accounts`, `audit`, `drift`, `checkpoint`/`logs`, `routing`/`route`/`routes`, `promote`, `rollback`, `dev`, `migrate`, `flags`, `doctor`, `status`, `history`, `update`/`upgrade`. The planned monorepo package layout below does **not** match the actual `packages/` tree — see the workspace for the real list.
-
-*Working draft. This is the CLI contract for `hs-x` after the SDK/interface review pass. It assumes a monorepo implementation and keeps the CLI as orchestration over reusable packages. The CLI is the human surface, the CI surface, and the coding-agent surface; every command that matters must have stable JSON output and a matching MCP tool.*
-
-## What changed in this pass
-
-This update folds in the root docs, `sdk/README.md`, and the current review findings that were missing from the first CLI draft:
-
-- first-run setup needs a single `hs-x connect` golden path;
-- portal-scoped dev routing requires an initial deployed runtime, so `dev` cannot pretend it is purely local;
-- the migration/card path should support Cloudflare-light or HubSpot-only first value where possible;
-- deploys use attestation-gated promotion, compatibility classification, rollback, and promotion;
-- metadata iteration needs an explicit command path (`dev upload` or `deploy --metadata-only`);
-- dev overrides should be exact capability matches in v1, not wildcard by default;
-- data-plane drift needs first-class commands (`doctor`, `drift`, `repair`);
-- sync needs operational commands (`status`, `run`, `pause`, `resume`, `reset`, `diff`);
-- CLI JSON must stay token-efficient for agents.
-
-## Design goals
-
-- One CLI surface for humans, CI, and coding agents.
-- Commands are thin orchestration over reusable workspace packages.
-- Every project-bound command resolves account, project, environment, and runtime posture the same way.
-- Every high-value command has stable `--json` output and predictable exit codes.
-- Interactive prompts are optional; CI and agents can pass flags or environment variables instead.
-- The CLI understands monorepos without forcing every package to be an HS-X app.
-- Every command that mutates HubSpot, Cloudflare, or rollout state prints a plan in human mode and emits a structured plan in JSON mode.
-- The CLI is honest about external prerequisites: HubSpot developer/test portal, Cloudflare account, Workers Paid primitives, and Cloudflare DNS/custom-domain requirements.
-
-## Monorepo package layout
-
-> **[PLANNED — does not match current `packages/` tree]** The actual workspace uses a smaller set of packages (`checkpoint`, `codegen`, `control-plane`, `design`, `e2e`, `email`, `fixtures`, `hubspot-cli`, `hubspot-client`, `hubspot-mock`, `mcp`, `runtime`, `sdk`, `studio`, `types`, `validator`). The breakdown below reflects the target decomposition, not what exists today.
-
-The CLI package owns command registration, option parsing, prompts, and rendering. It does not own the core logic.
-
-```text
-packages/
-  cli/                    # `hs-x` binary; command registration, prompts, rendering
-  common/                 # ids, diagnostics, errors, result envelopes, exit codes
-  config/                 # workspace/project discovery, project links, account resolution
-  sdk/                    # public `@hs-x/sdk` authoring API
-  compiler/               # source discovery, capability graph, hsmeta generation
-  validator/              # `hs-x validate` rules and autofix engine
-  types-generator/        # `hs-x types` implementation
-  refs/                   # generated @hs-x/refs support
-  deployer/               # deploy state machine, attestation-gated promotion, rollback
-  dev-server/             # dev loop, tunnel, override registration, wrangler/local-dev-lib orchestration
-  hubspot/                # @hubspot/local-dev-lib wrapper and HubSpot API adapters
-  cloudflare/             # Cloudflare account checks, route/domain checks, credential lease use
-  control-client/         # typed control-plane API client
-  observability/          # Checkpoint logs, AE/D1/R2 readers, live tail rendering
-  sync-engine/            # sync operational controls exposed by `hs-x sync ...`
-  migration/              # legacy app/card migration and rollout scaffolding
-```
-
-The same packages should be usable by the MCP server, tests, Studio export/deploy flows, scripts in CI, and future programmatic APIs.
-
-## Workspace and project discovery
-
-A monorepo can contain several HS-X apps plus shared packages.
-
-```text
-repo/
-  hsx.workspace.json
-  packages/shared/
-  apps/deal-enricher/
-    hsx.config.ts
-    hsx.account.json
-  apps/support-copilot/
-    hsx.config.ts
-    hsx.account.json
-```
-
-`hsx.workspace.json`:
-
-```ts
-export interface HsxWorkspaceConfig {
-  version: 1;
-  projects: HsxWorkspaceProjectRef[];
-  defaultProject?: string;
-}
-
-export interface HsxWorkspaceProjectRef {
-  /** Stable local name used by `--project`. */
-  name: string;
-  /** Path relative to the workspace root. */
-  path: string;
-  /** Optional default environment for project-bound commands. */
-  defaultEnv?: HsxEnvironmentName;
-}
-```
-
-Example:
-
-```json
-{
-  "version": 1,
-  "defaultProject": "deal-enricher",
-  "projects": [
-    { "name": "deal-enricher", "path": "apps/deal-enricher", "defaultEnv": "staging" },
-    { "name": "support-copilot", "path": "apps/support-copilot" }
-  ]
-}
-```
-
-If `hsx.workspace.json` is absent, the resolver walks upward from `cwd` until it finds `hsx.config.ts`.
-
-### Resolver rules
-
-Project-bound commands resolve the project in this order:
-
-1. `--project <name-or-path>`
-2. `HSX_PROJECT`
-3. nearest parent containing `hsx.config.ts`
-4. workspace `defaultProject`
-5. fail with a list of known projects
-
-Project-bound commands include:
-
-```text
-dev, deploy, promote, rollback, types, validate, rollout, logs,
-sync, upgrade, check, doctor, drift, checkpoint, repair, optimize
-```
-
-Account resolution is project-bound once `hsx.account.json` exists. A globally active account is only a fallback for unlinked project creation/linking. If a user passes `--account` that conflicts with the linked project account, the CLI fails closed.
-
-```ts
-export interface ResolvedProjectContext {
-  workspaceRoot: string;
-  projectRoot: string;
-  projectName: string;
-  configPath: string;
-  link?: ProjectLinkFile;
-  account: ResolvedAccount;
-  environment: HsxEnvironmentName;
-  runtimePosture: RuntimePosture;
-  invokedFrom: string;
-}
-
-export type RuntimePosture = "byo-cloudflare" | "managed-cloudflare" | "hubspot-only";
-```
-
-`hubspot-only` is for Cloudflare-light paths such as App Card migration or UI-only projects that do not need an external backend. If a command requires Workers, DOs, KV, D1, Queues, or routes, it upgrades the posture requirement and explains why.
-
-## Local account/project link
-
-`hsx.account.json` is repository-local state, not app config. It is the link file written by `hs-x connect` and read by project-bound commands.
-
-```ts
-export interface ProjectLinkFile {
-  version: 1;
-  accountId: string;
-  accountSlug: string;
-  projectId: string;
-  projectSlug: string;
-  hubspotAppId?: string;
-  defaultEnvironment: HsxEnvironmentName;
-  runtimePosture: RuntimePosture;
-  environments: Record<HsxEnvironmentName, LinkedEnvironment>;
-  linkedAt: string;
-}
-
-export type HsxEnvironmentName = "development" | "staging" | "production" | (string & {});
-
-export interface LinkedEnvironment {
-  environmentId: string;
-  hubspotProjectId?: string;
-  cloudflareAccountId?: string;
-  routeBaseUrl?: string;
-  activeDeployId?: string;
-  lastManifestHash?: string;
-}
-```
-
-Human output starts with a resolved context header. JSON output includes the same context in `context`.
-
-```text
-Account:       client-a
-Project:       deal-enricher
-Environment:   staging
-Runtime:       BYO Cloudflare
-Cloudflare:    Client A Production CF
-Active deploy: deploy_abc123 / rev_green
-```
-
-## Shared command contract
-
-All commands build a `CommandContext` before doing work.
-
-```ts
-export interface CommandContext {
-  mode: "human" | "json";
-  cwd: string;
-  project?: ResolvedProjectContext;
-  account?: ResolvedAccount;
-  auth: AuthSession;
-  io: CommandIO;
-  control: ControlPlaneClient;
-  clock: Clock;
-}
-
-export interface CommandIO {
-  stdout(message: string): void;
-  stderr(message: string): void;
-  prompt<T>(request: PromptRequest<T>): Promise<T>;
-  spinner<T>(label: string, task: () => Promise<T>): Promise<T>;
-}
-```
-
-Commands return a typed result. The renderer converts the result to human text or JSON.
-
-```ts
-export interface CommandResult<T = unknown> {
-  ok: true;
-  command: string;
-  context: ResultContext;
-  data: T;
-  warnings?: HsxDiagnostic[];
-}
-
-export interface CommandFailure {
-  ok: false;
-  command: string;
-  context?: Partial<ResultContext>;
-  error: HsxErrorEnvelope;
-  diagnostics?: HsxDiagnostic[];
-}
-
-export interface ResultContext {
-  account?: { id: string; slug: string; name: string };
-  project?: { id?: string; slug?: string; name: string; root: string };
-  environment?: string;
-  runtimePosture?: RuntimePosture;
-}
-```
-
-JSON mode writes exactly one JSON document to stdout. Progress logs go to stderr or are suppressed.
-
-## Global flags and environment variables
-
-```text
---project <name-or-path>       Select a project in a monorepo.
---account <slug-or-id>         Select an HS-X account; project-bound commands fail if this conflicts with the linked project.
---env <name>                   Select an environment; defaults from project link or workspace.
---json                         Emit stable machine-readable JSON.
---quiet, -q                    Suppress progress output without changing output format.
---no-telemetry                 Disable CLI telemetry for this invocation.
---no-update-check              Disable the non-blocking version hint for this invocation.
---no-color                     Disable ANSI output.
---yes                          Accept safe prompts; never accepts breaking/semantic deploy changes.
---non-interactive              Disable prompts; missing required values become errors.
---profile <name>               Select local auth profile.
---cwd <path>                   Run as if invoked from another directory; useful for agents/CI.
-```
-
-Environment equivalents:
-
-```text
-HSX_PROJECT
-HSX_ACCOUNT_ID
-HSX_ENV
-HSX_PROFILE
-HSX_TOKEN                  # CI/service auth
-HSX_HUBSPOT_PAK            # HubSpot developer personal access key for CLI/local-dev-lib operations
-HSX_HUBSPOT_DEVELOPER_API_KEY
-                           # HubSpot developer API key for hapikey endpoints only
-HSX_HUBSPOT_APP_ID         # HubSpot app id for app-scoped OAuth client secret setup
-HSX_HUBSPOT_CLIENT_ID      # HubSpot OAuth client id from the app's projects page
-HSX_HUBSPOT_CLIENT_SECRET  # HubSpot OAuth client secret from the app's projects page
-HSX_TELEMETRY_DISABLED=1
-HSX_TELEMETRY_OPTOUT=1
-HSX_UPDATE_CHECK_DISABLED=1
-HSX_NON_INTERACTIVE=1
-NO_COLOR=1
-```
-
-Local state follows XDG paths by default:
-
-```text
-$XDG_CONFIG_HOME/hs-x/config.json              # connected accounts
-$XDG_CONFIG_HOME/hs-x/cloudflare-oauth.json    # Cloudflare OAuth refresh tokens
-$XDG_STATE_HOME/hs-x/history.jsonl             # command history
-$XDG_CACHE_HOME/hs-x/update-check.json         # self-update check cache
-```
-
-`HSX_STORE_PATH`, `HSX_CLOUDFLARE_OAUTH_STORE_PATH`,
-`HSX_HISTORY_PATH`, and `HSX_UPDATE_CHECK_CACHE_PATH` override the
-defaults for tests and local development.
-
-## CLI telemetry
-
-The CLI sends one redacted command-completion event to the HS-X control plane
-after each packaged command run. The event includes command name, optional
-subcommand, CLI version, output mode, OS, architecture, runtime, CI boolean,
-exit code, and duration. It does not include args, paths, account ids, project
-ids, portal ids, env vars, request/response bodies, stack traces, or credential
-material. Delivery is best-effort, short-timeout, and never changes command
-behavior.
-
-Disable it with `--no-telemetry`, `HSX_TELEMETRY_DISABLED=1`,
-`HSX_TELEMETRY_OPTOUT=1`, or `DO_NOT_TRACK=1`.
-
-## Self-update hints
-
-Packaged CLI runs check the npm registry at most once every 24 hours and append
-a one-line update hint to stderr when a newer version exists. The check is
-best-effort, short-timeout, skipped in `--json`, `--json-stream`, and
-`--quiet`, and disabled by `--no-update-check`,
-`HSX_UPDATE_CHECK_DISABLED=1`, or `NO_UPDATE_NOTIFIER=1`.
-
-## HubSpot Developer Auth
-
-The CLI keeps HubSpot developer-account credentials distinct:
-
-- **Developer personal access key (PAK):** used as bearer auth for HubSpot CLI / `@hubspot/local-dev-lib` operations such as projects, builds, deploys, migration reads, and card-view swaps. Pass `--pak`, set `HSX_HUBSPOT_PAK`, or run HubSpot's `hs accounts auth` so `hs-x` can discover the PAK from local HubSpot CLI config.
-- **Developer API key (HAPIKEY):** used as the `hapikey` query parameter only for endpoints that explicitly document developer API key access. Pass `--developer-api-key` or set `HSX_HUBSPOT_DEVELOPER_API_KEY`.
-- **Per-install app tokens:** OAuth/static bearer tokens for installed portal runtime access. These are not developer-account CLI credentials and should not be used with `hs-x api hubspot`.
-
-For raw calls, `hs-x api hubspot <path>` accepts PAK-only, HAPIKEY-only, or both. When both are present, the request includes bearer auth and the `hapikey` query parameter.
+The command-line tool for HS-X, a type-safe HubSpot app framework that deploys
+to Cloudflare Workers. Installing this package puts the `hs-x` command on your
+PATH: it scaffolds projects, runs the local dev loop, and deploys to your own
+HubSpot developer app and your own Cloudflare account.
 
 ## Install
 
 ```bash
 npm i -g @hs-x/cli
+hs-x --version
 ```
 
-This installs the `hs-x` command on your PATH. Both Node and Bun run it. You can also invoke it without a global install via `bunx @hs-x/cli <command>`.
+Node 20+ and Bun can both run it. The npm package is `@hs-x/cli`; the installed
+command is `hs-x`. If you prefer not to install anything globally, every command
+also works through `bunx @hs-x/cli <command>`.
 
-## First-run golden path
-
-This is the unlinked, direct-to-HubSpot path: scaffold a project, install its deps, point it at your HubSpot dev app and a Cloudflare API token, run the local loop, then deploy to your own Cloudflare and HubSpot.
+## Thirty seconds
 
 ```bash
-npm i -g @hs-x/cli
-hs-x init deal-enricher
-cd deal-enricher
+hs-x init deal-tagger     # scaffold a project (default template: workflow action)
+cd deal-tagger
 bun install
-# set HubSpot dev-app credentials + a Cloudflare API token
-# (HSX_HUBSPOT_CLIENT_ID / HSX_HUBSPOT_CLIENT_SECRET, CLOUDFLARE_API_TOKEN, etc.)
-hs-x dev      # local development loop
-hs-x deploy   # deploy to your own Cloudflare + HubSpot
+hs-x connect              # bind a HubSpot developer account and a Cloudflare account
+hs-x dev                  # local dev loop
+hs-x deploy               # deploy to your HubSpot app and your Cloudflare account
 ```
 
-The CLI works direct-to-HubSpot without the HS-X platform. The control plane, dashboard, and billing are opt-in. Deployed apps run in *your* Cloudflare account.
-
-### Platform-linked setup with `hs-x connect`
-
-If you opt into the HS-X platform, `hs-x connect` is the broader golden path: it links the project to an HS-X account and walks HubSpot and Cloudflare setup. It is intentionally broad. It handles or guides:
-
-- local HS-X auth;
-- HS-X account selection;
-- HubSpot auth and developer/test portal selection;
-- Cloudflare setup based on tier: create or attach an HS-X-managed CF account, connect an existing CF account via OAuth, or accept a pasted API token;
-- Workers Paid / required primitive check, with an explicit downgrade path to the no-DO subset when possible;
-- `permittedUrls.fetch` strategy selection: custom domain on Cloudflare DNS, explicit `*.workers.dev` URLs with the refactor caveat, or deferred development-only setup;
-- environment creation;
-- first stub Worker deploy per declared runtime capability, so portal-scoped dev routing has a deployed interception point;
-- test-portal validation to avoid accidentally targeting a production customer portal;
-- `hsx.account.json` writing.
+The CLI works direct-to-HubSpot out of the box. You provide the HubSpot and
+Cloudflare credentials, the CLI talks to both platforms directly, and nothing
+requires an HS-X platform account. The control plane, dashboard, and billing are
+opt-in: `hs-x login` authenticates an HS-X account and `hs-x link` attaches an
+already-deployed project to it.
 
-### Cloudflare-light card migration path
+Deployed Workers run in your Cloudflare account, and the generated
+`.hs-x/alchemy.run.ts` (checked into your repo) describes the Cloudflare
+resources your app owns — the app keeps running even if you stop using HS-X.
 
-For UI-only App Card migration, the CLI should not force Cloudflare before first value.
+## Commands
 
-```bash
-hs-x migrate cards ./legacy-app --project migrated-cards
-hs-x deploy --hubspot-only --env staging
-```
+Grouped the way `hs-x help` prints them.
 
-If a migrated card needs a backend, the CLI explains the upgrade path:
+Start:
 
-```bash
-hs-x connect cloudflare
-hs-x deploy --env staging
-```
+| Command | What it does |
+| --- | --- |
+| `hs-x init [name]` | Create a new HS-X project |
+| `hs-x connect` | Link this project to HubSpot and Cloudflare |
+| `hs-x doctor` | Diagnose local setup |
+| `hs-x check` | Validate project source |
 
-This path exists to keep the migration wedge honest: modern App Card preview/export/deploy first, Cloudflare only when runtime hosting is actually needed.
+Develop:
 
-## Account and project commands
+| Command | What it does |
+| --- | --- |
+| `hs-x dev` | Start the local dev server |
+| `hs-x api <path>` | Call HubSpot or the HS-X control plane |
+| `hs-x flags` | Manage feature flags |
+| `hs-x migrate` | Migrate legacy HubSpot apps |
 
-### `hs-x login` / `hs-x logout`
+Deploy:
 
-> **Shipped as `hs-x login` / `hs-x logout` (no `auth` prefix).**
+| Command | What it does |
+| --- | --- |
+| `hs-x deploy` | Deploy the project |
+| `hs-x promote` | Promote a deploy to an environment |
+| `hs-x rollback` | Roll back an environment |
+| `hs-x routes` | Show active deploy routes |
 
-```text
-hs-x login [--profile <name>] [--json]
-hs-x logout [--profile <name>]
-```
+Observe:
 
-### `hs-x accounts`
+| Command | What it does |
+| --- | --- |
+| `hs-x status` | Show project health |
+| `hs-x logs` | Stream runtime and deploy telemetry |
+| `hs-x drift` | Show project drift |
+| `hs-x audit list` | List redacted account audit rows |
+| `hs-x history` | Show recent command runs |
 
-```text
-hs-x accounts list [--json]
-hs-x accounts current [--json]
-hs-x accounts switch <account>
-```
+Account:
 
-### `hs-x init`
+| Command | What it does |
+| --- | --- |
+| `hs-x login` | Authenticate with an HS-X account token |
+| `hs-x accounts` | Manage HS-X accounts |
+| `hs-x whoami` | Show the active HS-X account |
+| `hs-x logout` | Remove the active HS-X account |
+| `hs-x link` | Attach this project to your HS-X account |
+| `hs-x unlink` | Clear the session; keep local project state |
 
-Scaffolds a new HS-X project in a new directory named after the project. `hs-x create` is an accepted alias.
+Config:
 
-```text
-hs-x init [name] [--type workflow-action|sync-source|empty] [--app-name <name>] [--yes] [--no-install] [--force] [--cwd <dir>] [--quiet] [--json]
-```
-
-Flags:
-
-- `--name <name>` — project directory and config name (a positional argument is also accepted).
-- `--type <type>` — app type: `workflow-action` (default), `sync-source`, or `empty`. `--template <id>` is also accepted (`deals-tagger` is the workflow-action template).
-- `--app-name <name>` — HubSpot app display name; defaults from the project name. `--display-name` is an accepted alias.
-- `--yes`, `-y` — accept defaults: install dependencies and skip prompts.
-- `--no-install` — skip the dependency install step.
-- `--force` — overwrite an existing `hsx.config.ts` at the target.
-- `--cwd <dir>` — run as if invoked from `<dir>`.
-- `--quiet`, `-q` — suppress progress output.
-- `--json` — emit a JSON result.
-
-A scaffold writes `package.json`, `tsconfig.json`, `.gitignore`, `hsx.config.ts`, and one or more `src/workers/*.ts` files. The generated `package.json` depends on `@hs-x/sdk` and `@hs-x/runtime` from npm (no `workspace:*`, no per-project `hs-x` devDependency — the CLI is installed globally). The `.gitignore` ignores `.hs-x/*` except `.hs-x/alchemy.run.ts`, which is tracked as the leaveability artifact.
-
-When invoked without `--type` in an interactive terminal, `init` prompts for the project name, the template, the HubSpot app name, and whether to install dependencies. In `--json` or non-interactive mode it falls back to defaults (project name `hsx-app`, the workflow-action template) and skips prompts.
-
-The JSON result has the shape:
-
-```json
-{
-  "ok": true,
-  "command": "init",
-  "project": {
-    "name": "deal-enricher",
-    "appName": "Deal Enricher",
-    "root": "/abs/path/deal-enricher",
-    "template": "deals-tagger",
-    "installed": true
-  }
-}
-```
-
-### `hs-x connect`
-
-Golden-path setup command.
-
-```text
-hs-x connect [--project <name-or-path>] [--account <account>] [--hubspot-portal <portalId>] [--cloudflare-account <id>] [--runtime byo-cloudflare|managed-cloudflare|hubspot-only] [--env development] [--non-interactive]
-```
-
-```ts
-export interface ConnectOptions {
-  projectSelector?: string;
-  account?: string;
-  hubspotPortalId?: string;
-  cloudflareAccountId?: string;
-  runtimePosture?: RuntimePosture;
-  environment?: HsxEnvironmentName;
-  provisionDevRuntime: boolean;
-}
-
-export interface ConnectResult {
-  projectLinked: boolean;
-  account: { id: string; slug: string };
-  hubspot: { portalId?: string; appId?: string; projectId?: string };
-  cloudflare?: { accountId: string; workersPaidRequired: boolean; routeBaseUrl?: string };
-  environment: HsxEnvironmentName;
-  devRuntimeReady: boolean;
-  nextSteps: string[];
-}
-```
-
-Subcommands for explicit setup:
-
-```text
-hs-x connect hubspot --account-id <id> --developer-account-id <id> --display-name <name> [--pak <token>] [--developer-api-key <key>]  # advanced alias for HubSpot-only setup
-hs-x connect cloudflare [--account <id>] [--domain <domain>] [--accept-workers-dev]
-hs-x connect domain [--domain <domain>] [--zone <zoneId>]  # [NOT YET IMPLEMENTED]
-```
-
-### `hs-x secrets`
-
-Stores scoped app secrets that deploy copies into the tenant Cloudflare runtime. HubSpot install OAuth secrets are scoped by HS-X account, project, environment, and HubSpot app id so one Cloudflare account can host multiple HubSpot apps safely.
-
-```text
-hs-x secrets hubspot-oauth set --account-id <id> --project-id <id> --hubspot-app-id <id> --client-id <id> --client-secret <secret> [--env production|staging|dev]
-```
-
-The secret is never echoed. On deploy, HS-X also provisions or reuses the scoped tenant install KV namespace and writes `HSX_TOKEN_KEY` as a Worker secret for encrypted install-token storage. The same operation is available through the control-plane API, dashboard, and MCP.
-
-### `hs-x project` — [NOT YET IMPLEMENTED]
-
-> No `project` command exists today. Linking is currently done through `hs-x connect`; project status flows live under other commands.
-
-```text
-hs-x project link [--project <name-or-path>] --account <account> [--remote-project <slug-or-id>] [--env <name>]
-hs-x project status [--project <name>] [--json]
-hs-x project unlink [--project <name>]
-```
-
-```ts
-export interface ProjectStatusResult {
-  linked: boolean;
-  account?: { id: string; slug: string; cloudflareAccountId?: string };
-  project?: { id: string; slug: string; root: string };
-  environments: Array<{
-    name: HsxEnvironmentName;
-    hubspotProjectId?: string;
-    routeBaseUrl?: string;
-    activeDeployId?: string;
-    driftState?: DriftState;
-  }>;
-  activeDevOverrides: DevOverrideSummary[];
-}
-```
+| Command | What it does |
+| --- | --- |
+| `hs-x secrets` | Store app secrets for runtime deploys |
+| `hs-x completion <shell>` | Generate shell completion (bash, zsh, fish) |
+| `hs-x update` | Check for a newer CLI release |
+| `hs-x help` | Show command help |
 
-## Development commands
+Run `hs-x <command> --help` for command-specific flags. Most commands accept
+`--json` for machine-readable output, and prompts can be skipped in scripts
+with `--yes` where a command confirms before changing anything.
 
-### `hs-x dev`
+## Connecting accounts
 
-Runs the local development loop. Default mode is portal-scoped proxy through the deployed runtime.
+`hs-x connect` walks HubSpot and Cloudflare setup back to back; each side is
+also available on its own.
 
-```text
-hs-x dev --portal <portalId> [--project <name>] [--env development] [--capability <id> ...] [--ttl 2h] [--quick-tunnel] [--dev-deploy] [--mock] [--allow-production-portal]
-```
-
-```ts
-export interface DevOptions {
-  portalId?: string;
-  capabilities: string[];          // exact capability ids in v1
-  ttlSeconds: number;
-  tunnel: "named" | "quick" | "dev-deploy" | "mock";
-  watch: boolean;
-  openHubSpotPreview: boolean;
-  allowProductionPortal: boolean;
-}
-
-export interface DevSessionResult {
-  sessionId: string;
-  portalId?: string;
-  environment: HsxEnvironmentName;
-  tunnelUrl?: string;
-  overrides: DevOverrideSummary[];
-  processes: Array<{ name: "wrangler" | "cloudflared" | "hubspot"; pid?: number; status: string }>;
-  warnings: HsxDiagnostic[];
-}
-```
-
-Rules:
-
-- v1 dev overrides are exact `(portalId, capabilityId, developerSession)` matches. No wildcard `*` override by default.
-- Production/customer portals are blocked unless `--allow-production-portal` is passed and the command is interactive or explicitly confirmed.
-- `hs-x dev` checks that a deployed dev runtime exists. If not, it offers to run the dev-runtime setup portion of `hs-x connect`.
-- DO-heavy paths warn in tunnel mode and recommend `--dev-deploy`.
-- UI extensions hot-reload through HubSpot's `hs project dev` / `@hubspot/local-dev-lib` underneath.
-
-Related commands:
-
-```text
-hs-x dev status [--project <name>] [--portal <portalId>] [--json]
-hs-x dev stop --portal <portalId> [--capability <id>]        # [NOT YET IMPLEMENTED]
-hs-x dev cleanup [--expired] [--all]
-hs-x dev doctor [--json]                                     # use top-level `hs-x doctor`
-hs-x dev upload [--metadata-only]                            # [NOT YET IMPLEMENTED]
-```
-
-`hs-x dev upload` is the metadata iteration escape hatch for workflow action inputs/outputs/labels, agent metadata, card metadata, and other `*-hsmeta.json` changes. Handler iteration should not require metadata upload; metadata iteration does.
-
-## Deploy, promotion, and rollback
-
-### `hs-x deploy`
-
-Runs the two-cloud deploy state machine. A deploy records a candidate, uploads Cloudflare and HubSpot assets through local execution, waits for runtime attestation to report healthy drift, then promotes the deploy in control-plane state. Full router-based revisioned routing is deferred.
-
-```text
-hs-x deploy [--project <name>] [--env staging|production] [--plan] [--diff] [--resume <deployId>] [--breaking] [--semantic-change] [--expected-rps <n>] [--metadata-only] [--hubspot-only] [--json]
-```
-
-> **[PARTIAL]** The shipped flag set diverges from this prototype. Actual flags include `--cloudflare-deploy`, `--cloudflare-dry-run`, `--hubspot-upload-only`, `--promote-when-healthy`, `--record-local`, `--local-control-plane`, `--portal-schema-fixture`, `--no-manage-schema`, `--json`. Run `hs-x deploy --help` for the current set; the flags marked `--breaking`, `--semantic-change`, `--resume`, `--expected-rps`, `--metadata-only` are design-only.
-
-```ts
-export interface DeployOptions {
-  environment: HsxEnvironmentName;
-  planOnly: boolean;
-  diffOnly: boolean;
-  resumeDeployId?: string;
-  allowBreaking: boolean;
-  allowSemanticChange: boolean;
-  expectedRps?: number;
-  metadataOnly: boolean;
-  hubspotOnly: boolean;
-}
-
-export interface DeployPlanResult {
-  deployId: string;
-  planOnly: true;
-  compatibility: CompatibilityReport;
-  stateMachine: DeployStepPreview[];
-  resources: PlannedResourceChange[];
-  routes: PlannedRouteChange[];
-  hubspotAssets: PlannedHubSpotAssetChange[];
-  estimatedCost: CostEstimate;
-  drift?: DriftReport;
-  requiredConfirmations: RequiredConfirmation[];
-}
-
-export interface DeployResult {
-  deployId: string;
-  environment: HsxEnvironmentName;
-  activeDeployId: string;
-  previousDeployId?: string;
-  steps: DeployStepResult[];
-  manifestPath: string;
-  manifestHash: string;
-  dashboardUrl?: string;
-}
-```
-
-Deploy state machine:
-
-```text
-plan_requested
-plan_received
-preflight
-apply_cloudflare
-deploy_worker
-upload_hubspot
-verify_hubspot
-record
-attest
-promote_when_healthy
-reconcile_flags
-active
-```
-
-Compatibility classes:
-
-```ts
-export type CompatibilityClass =
-  | "additive-safe"
-  | "compatible-with-shim"
-  | "breaking"
-  | "semantic";
-```
-
-Rules:
-
-- `--yes` does not accept `breaking` or `semantic` changes. Those require explicit flags.
-- `--metadata-only` updates HubSpot metadata without changing Worker code when safe.
-- `--hubspot-only` is allowed only for projects/capabilities with no Cloudflare runtime needs.
-- `--plan` includes cost shape, Workers Paid requirements, streaming polling cost, custom-domain/permitted URL warnings, and drift status.
-- If drift is detected, deploy offers `hs-x repair` first rather than silently deploying on top of drift.
-- `--portal-schema-fixture <path>` runs the schema planner against deterministic observed schema JSON.
-- `--portal-schema-live` reads the target portal schema through the HubSpot developer client; `--apply-schema` applies only the managed `WILL CREATE` / `WILL ALTER` actions from that plan.
-
-### `hs-x promote`
-
-Promotes an already-built/tested artifact between environments.
-
-```text
-hs-x promote <from-env> <to-env> [--project <name>] [--deploy <deployId>] [--plan] [--json]
-```
-
-```ts
-export interface PromoteResult {
-  fromEnvironment: HsxEnvironmentName;
-  toEnvironment: HsxEnvironmentName;
-  deployId: string;
-  promotedDeployId: string;
-  hubspotUploadRequired: boolean;
-  steps: DeployStepResult[];
-}
-```
-
-`promote` should preserve the artifact identity. It is not a rebuild unless the target environment requires environment-specific generated metadata.
-
-### `hs-x rollback`
-
-```text
-hs-x rollback [--project <name>] --env production [--to <deployId>] [--plan] [--json]
-```
-
-```ts
-export interface RollbackResult {
-  environment: HsxEnvironmentName;
-  fromDeployId: string;
-  toDeployId: string;
-  activeDeployId: string;
-  warnings: HsxDiagnostic[];
-}
-```
-
-Rollback promotes a prior recorded deploy through the control plane and marks the former active deploy rolled back. Rollbacks past one deploy boundary warn about card/backend contract drift and require explicit force.
-
-## Drift and runtime health commands
-
-BYO Cloudflare means runtime resources can drift. These commands are project-bound.
-
-```text
-hs-x doctor [--project <name>] [--env <name>] [--json]
-hs-x drift [--project <name>] [--env <name>] [--json]
-hs-x logs [--project <name>] [--env <name>] [--json]
-hs-x repair [--project <name>] [--env <name>] [--plan] [--json]   # [NOT YET IMPLEMENTED]
-```
-
-```ts
-export type DriftState =
-  | "healthy"
-  | "drifted"
-  | "credential_revoked"
-  | "resource_missing"
-  | "unknown_code"
-  | "billing_untrusted"
-  | "unknown";
-
-export interface DriftReport {
-  state: DriftState;
-  manifestHash?: string;
-  observedManifestHash?: string;
-  resources: DriftResourceFinding[];
-  billingTrust: "trusted" | "ae-only" | "manual-review";
-}
-```
-
-`doctor` runs checks and summarizes. `drift` shows resource-by-resource differences. `checkpoint` reads the project Checkpoint telemetry view: aggregate invocation counts, latency percentiles, recent failures, sampled successes, and the backing observability sources. `repair` offers to recreate missing HS-X resources or remove drift-introduced resources, with explicit confirmation for destructive changes.
-
-## Type generation — [NOT YET IMPLEMENTED]
-
-> No `hs-x types` command exists today. Type generation runs implicitly via `hs-x check`/`hs-x validate`. The standalone command is planned.
-
-```text
-hs-x types [--project <name>] [--portal <portalId>] [--out .hs-x/types.ts] [--watch] [--json]
-```
-
-```ts
-export interface TypesOptions {
-  portalId?: string;
-  outputPath: string;
-  includeCustomObjects: boolean;
-  includeAppObjects: boolean;
-}
-
-export interface TypesResult {
-  outputPath: string;
-  moduleAlias: "@hs-x/types";
-  schemaVersion: string;
-  objects: Array<{ name: string; properties: number; source: "standard" | "portal" | "app" }>;
-  diagnostics: HsxDiagnostic[];
-}
-```
-
-Rules:
-
-- Marketplace apps get strict standard/app object/event types and permissive custom-property access.
-- Private/single-portal apps can generate portal-exact types.
-- `hs-x upgrade` runs `hs-x types` automatically.
-
-## Validation
-
-```text
-hs-x validate [--project <name>] [--fix] [--format text|json|sarif] [--json]
-```
-
-```ts
-export interface ValidateOptions {
-  fix: boolean;
-  format: "text" | "json" | "sarif";
-  rules?: string[];
-}
-
-export interface ValidateResult {
-  status: "passed" | "passed-with-warnings" | "failed";
-  diagnostics: HsxDiagnostic[];
-  fixesApplied: FixSummary[];
-}
-```
-
-Important rule groups:
-
-- declared scopes vs SDK-mediated calls and annotated raw calls;
-- direct HubSpot `fetch` warnings/errors;
-- explicit `agent.expose` required;
-- workflow resolved-input validity;
-- batched delivery invalid in no-DO profile;
-- card backend `hubspot.fetch` envelope;
-- streaming backend polling/cost warnings;
-- sync identity/tombstone/retry requirements;
-- generated ref alias (`@hs-x/refs`) usage;
-- dev override exact-match rules;
-- marketplace certification checks under `hs-x check`.
-
-## Logs and observability
-
-```text
-hs-x logs [--project <name>] [--env <name>] [--capability <id>] [--portal <portalId>] [--since 15m] [--follow] [--json]
-hs-x runs failures [--project <name>] [--env <name>] [--since 1h] [--json]      # [NOT YET IMPLEMENTED]
-hs-x runs sampled [--project <name>] [--env <name>] [--since 15m] [--json]      # [NOT YET IMPLEMENTED]
-hs-x metrics [--project <name>] [--env <name>] [--since 24h] [--json]           # [NOT YET IMPLEMENTED]
-```
-
-> `hs-x logs` is aliased to `hs-x checkpoint` today. `runs` and `metrics` top-level commands are planned.
-
-```ts
-export interface LogRecord {
-  timestamp: string;
-  level: "debug" | "info" | "warn" | "error";
-  deployId?: string;
-  capabilityId?: string;
-  portalId?: string;
-  runId?: string;
-  fingerprint?: string;
-  message: string;
-  fields?: Record<string, unknown>;
-}
-```
-
-UI/CLI labels must be honest:
-
-- invocation totals: complete AE-backed aggregates;
-- recent failures: exemplar rows plus complete occurrence counts;
-- trace exemplars: persisted examples for a fingerprint;
-- recent sampled successes: sampled, labeled as sampled;
-- live tail: Cloudflare Workers Logs tail.
-
-Avoid promising “last 50 runs” unless the result is actually complete.
-
-## Rollout and flags
-
-```text
-hs-x flags list [--project <name>] [--env <name>]                         # [NOT YET IMPLEMENTED]
-hs-x flags set <flag> --portal <portalId> --value on|off|<json>
-hs-x flags get <flag> --portal <portalId>
-hs-x flags promote <flag> --percent <n>                                   # [NOT YET IMPLEMENTED]
-hs-x flags history <flag> [--json]                                        # [NOT YET IMPLEMENTED]
-```
-
-> Today only `flags set` and `flags get` ship; `list`, `promote`, `history` are planned. The command is also aliased as `hs-x rollout`.
-
-```ts
-export interface RolloutFlagState {
-  flagKey: string;
-  environment: HsxEnvironmentName;
-  defaultValue: unknown;
-  portalOverrides: number;
-  rollout?: { percent: number; salt: string };
-  hubspotCardFlagState?: "synced" | "pending" | "error";
-}
-```
-
-Flag updates are per-portal rollout controls, not emergency global kill switches unless a stronger non-KV path is implemented.
-
-## Migration commands
-
-```text
-hs-x migrate inspect <path-or-app-id> [--json]
-hs-x migrate cards <path-or-app-id> [--project <name>] [--no-cloudflare] [--json]
-hs-x migrate app <path-or-app-id> [--project <name>] [--json]
-hs-x migrate report [--project <name>] [--json]
-```
-
-```ts
-export interface MigrationInspectResult {
-  source: string;
-  detected: Array<"classic-crm-card" | "project-card" | "serverless-function" | "workflow-action" | "settings-page">;
-  automatable: MigrationFinding[];
-  manualWork: MigrationFinding[];
-  cloudflareRequired: boolean;
-}
-
-export interface MigrationResult {
-  projectRoot: string;
-  createdFiles: string[];
-  rolloutFlags: string[];
-  cloudflareRequired: boolean;
-  nextSteps: string[];
-}
-```
-
-The App Card migration wedge should work before the full runtime where possible. If a card backend or function migration requires Cloudflare, the CLI should say exactly which migrated feature caused that requirement.
-
-## Sync operations — [NOT YET IMPLEMENTED]
-
-> No `hs-x sync` command exists today; the entire subcommand surface below is planned.
-
-Sync commands are operational controls over deployed sync capabilities.
-
-```text
-hs-x sync list [--project <name>] [--env <name>] [--json]
-hs-x sync status <syncId> --portal <portalId> [--json]
-hs-x sync run <syncId> --portal <portalId> [--cursor <cursor>] [--json]
-hs-x sync pause <syncId> --portal <portalId>
-hs-x sync resume <syncId> --portal <portalId>
-hs-x sync reset <syncId> --portal <portalId> [--confirm]
-hs-x sync diff <syncId> --portal <portalId> [--limit <n>] [--json]
-hs-x sync deadletter <syncId> --portal <portalId> [--json]
-hs-x sync retry <syncId> --portal <portalId> <record-id> [--json]
-```
-
-```ts
-export interface SyncStatusResult {
-  syncId: string;
-  portalId: string;
-  state: "idle" | "running" | "paused" | "error" | "backing_off";
-  cursor?: unknown;
-  lastRun?: string;
-  recordsProcessed?: number;
-  deadLetterCount: number;
-  mappingVersion: string;
-}
-```
-
-## Certification and optimization
-
-```text
-hs-x check [--project <name>] [--env <name>] [--marketplace] [--json]
-hs-x optimize [--project <name>] [--plan] [--write] [--json]   # [NOT YET IMPLEMENTED]
-```
-
-`check` audits marketplace readiness and should clearly separate automatable findings from human/process requirements such as demo videos, security questionnaire, verified domain, active install count, and review responses.
-
-`optimize` is reviewable, never silent. It can flag N+1 HubSpot calls, unbatched writes, missing cursors, over-broad scopes, and expensive streaming/card patterns, then offer a diff under `--write`.
-
-## Upgrade — [PARTIAL]
-
-> `hs-x update` / `hs-x upgrade` ships as a self-update helper for the CLI binary itself. The platform-version migration flow described below (with `--to`, `--plan`) is **not yet implemented**.
-
-```text
-hs-x upgrade [--project <name>] --to 2026.09 [--plan] [--json]
-```
-
-Upgrade changes SDK channel, platform version, generated types, generated HubSpot metadata, and migration rules. It should emit a compatibility plan before writing.
-
-## Diagnostics and exit codes
-
-```ts
-export interface HsxDiagnostic {
-  code: string;
-  severity: "info" | "warning" | "error";
-  message: string;
-  file?: string;
-  line?: number;
-  column?: number;
-  rule?: string;
-  fix?: { title: string; safe: boolean };
-}
-```
-
-Exit codes:
-
-```text
-0  success
-1  generic failure
-2  validation failed
-3  authentication or authorization failed
-4  project/account/environment resolution failed
-5  deploy plan refused because of breaking or semantic changes
-6  external dependency unavailable (HubSpot, Cloudflare, tunnel, DNS)
-7  non-interactive command needed input
-8  command interrupted; resume may be available
-9  runtime drift detected; repair required before requested operation
-10 command unsupported for current runtime posture
+```bash
+hs-x connect hubspot      # HubSpot developer account: PAK, or discovered from `hs accounts auth`
+hs-x connect cloudflare   # Cloudflare: browser OAuth flow, or --auth-method api-token
 ```
 
-## JSON output example
+For HubSpot, the CLI discovers credentials from the official HubSpot CLI config
+when you have run `hs accounts auth`, or accepts a developer personal access key
+via `--pak`. For Cloudflare, an interactive run uses a browser
+authorization-code flow by default; `--auth-method api-token` accepts a scoped
+API token you create in the Cloudflare dashboard and paste back, which also
+suits CI and headless shells.
 
-`hs-x deploy --plan --json` emits one JSON document.
+## Migrating an existing app
 
-```json
-{
-  "ok": true,
-  "command": "deploy",
-  "context": {
-    "account": { "id": "acct_123", "slug": "client-a", "name": "Client A" },
-    "project": { "id": "proj_456", "slug": "deal-enricher", "name": "deal-enricher", "root": "/repo/apps/deal-enricher" },
-    "environment": "staging",
-    "runtimePosture": "byo-cloudflare"
-  },
-  "data": {
-    "deployId": "deploy_abc123",
-    "planOnly": true,
-    "compatibility": {
-      "additiveSafe": 4,
-      "compatibleWithShim": [],
-      "breaking": [],
-      "semantic": []
-    },
-    "stateMachine": [
-      { "name": "plan_received", "status": "pending" },
-      { "name": "apply_cloudflare", "status": "pending" },
-      { "name": "deploy_worker", "status": "pending" },
-      { "name": "upload_hubspot", "status": "pending" },
-      { "name": "record", "status": "pending" },
-      { "name": "attest", "status": "pending" },
-      { "name": "promote_when_healthy", "status": "pending" }
-    ],
-    "estimatedCost": {
-      "currency": "USD",
-      "monthly": 12.4,
-      "notes": ["streaming backend ai-summary: estimate assumes 100 concurrent streams at 400ms polling"]
-    },
-    "drift": { "state": "healthy" }
-  },
-  "warnings": []
-}
-```
+`hs-x migrate run` takes a legacy HubSpot app (platform versions 2023.2, 2025.1,
+or 2025.2) and generates a 2026.03 HS-X project as a net-new duplicate you can
+test with `hs-x dev`. Your original app keeps running untouched until you cut
+over. See `hs-x migrate --help` for the inspect, report, cards, and swap-cards
+subcommands.
 
-## First implementation slice
+## Docs
 
-1. Create `packages/common` with result envelopes, diagnostics, ids, error envelopes, and exit codes.
-2. Create `packages/config` with workspace discovery, project discovery, `hsx.account.json` parsing, runtime posture, and account conflict handling.
-3. Create `packages/cli` with global flag parsing, JSON/human renderers, and placeholder commands.
-4. Implement `hs-x project status --json` first because it exercises monorepo/project/account resolution without HubSpot or Cloudflare mutation.
-5. Implement `hs-x connect --plan` / dry-run checks next: auth state, HubSpot presence, Cloudflare prerequisite detection, route/domain choice, and what would be provisioned.
-6. Implement `hs-x validate --json` with config/workspace/SDK declaration checks.
-7. Implement `hs-x deploy --plan --json` using compiler manifests before mutating HubSpot or Cloudflare.
-8. Implement Cloudflare-light `hs-x migrate cards` and `hs-x deploy --hubspot-only` if the migration artifacts allow it.
-9. Wire real deploy execution, dev routing, drift/repair, and sync operations package by package behind the same command contracts.
+Guides and reference live at [hs-x.dev/docs](https://hs-x.dev/docs). The
+getting-started guide goes from an empty directory to a live HubSpot card in
+about fifteen minutes.
 
-## Open CLI questions
+## License
 
-- Managed-CF tier: does it ship early or remain an explicit future runtime posture?
-- `hs-x dev upload` vs `hs-x deploy --metadata-only`: should both exist or should one alias the other?
-- Exact first-run dev runtime: does `hs-x connect` always deploy a shell Worker, or only when a capability requires runtime hosting?
-- HubSpot-only migration: which legacy card shapes can truly deploy without Cloudflare?
-- Fresh-clone generated refs: should `hs-x init` install a stub `@hs-x/refs` package or rely on generated `.hs-x/refs` after first `dev`/`deploy`?
-- How much of `hs-x check` belongs in `validate` vs a marketplace-specific command?
+Apache-2.0