@hs-x/cli 0.1.0

package/README.md

@@ -0,0 +1,1001 @@
+# HS-X CLI Interfaces
+
+> **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 2026-05-20, shipped top-level commands are: `init`/`create`, `check`, `validate`, `deploy`, `promote`, `connect`, `secrets`, `login`, `whoami`, `logout`, `completion`, `api`, `account`, `audit`, `drift`, `checkpoint`/`logs`, `routing`, `rollback`, `dev`, `migrate`, `rollout`/`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 ADR-009 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`, `stream-relay`, `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.
+
+## First-run golden paths
+
+### Full runtime path
+
+This path creates or links a project, connects HubSpot and Cloudflare, creates a development environment, deploys the first runtime shell needed for portal-scoped dev routing, and then starts local dev.
+
+```bash
+npx hs-x create deal-enricher
+cd deal-enricher
+hs-x connect
+hs-x dev --portal 12345
+```
+
+`hs-x connect` 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.
+
+### Cloudflare-light card migration path
+
+For UI-only App Card migration, the CLI should not force Cloudflare before first value.
+
+```bash
+hs-x migrate cards ./legacy-app --project migrated-cards
+hs-x deploy --hubspot-only --env staging
+```
+
+If a migrated card needs a backend, the CLI explains the upgrade path:
+
+```bash
+hs-x connect cloudflare
+hs-x deploy --env staging
+```
+
+This path exists to keep the migration wedge honest: modern App Card preview/export/deploy first, Cloudflare only when runtime hosting is actually needed.
+
+## Account and project commands
+
+### `hs-x login` / `hs-x logout`
+
+> **Shipped as `hs-x login` / `hs-x logout` (no `auth` prefix).**
+
+```text
+hs-x login [--profile <name>] [--json]
+hs-x logout [--profile <name>]
+```
+
+### `hs-x accounts`
+
+```text
+hs-x accounts list [--json]
+hs-x accounts current [--json]
+hs-x accounts switch <account>
+```
+
+### `hs-x create`
+
+Workspace command. Creates a new project and optionally adds it to `hsx.workspace.json`.
+
+```text
+hs-x create <name> [--type workflow-action|sync-source|empty] [--app-name <name>] [--dir <path>] [--account <account>] [--monorepo] [--runtime byo-cloudflare|managed-cloudflare|hubspot-only]
+```
+
+```ts
+export interface CreateOptions {
+  name: string;
+  type: "workflow-action" | "sync-source" | "empty";
+  targetDir: string;
+  account?: string;
+  runtimePosture?: RuntimePosture;
+  addToWorkspace: boolean;
+  installDeps: boolean;
+}
+
+export interface CreateResult {
+  projectRoot: string;
+  packageManager: "pnpm" | "npm" | "yarn" | "bun";
+  filesCreated: string[];
+  workspaceUpdated: boolean;
+  nextSteps: string[];
+}
+```
+
+### `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[];
+}
+```
+
+## Development commands
+
+### `hs-x dev`
+
+Runs the local development loop. Default mode is portal-scoped proxy through the deployed runtime.
+
+```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 Phase 1 two-cloud deploy state machine from ADR-009. 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;
+}
+```
+
+Phase 1 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 ADR-008 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
+```
+
+## JSON output example
+
+`hs-x deploy --plan --json` emits one JSON document.
+
+```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": []
+}
+```
+
+## First implementation slice
+
+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.
+
+## Open CLI questions
+
+- 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 create` 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?