@hs-x/cli 0.1.1 → 0.1.3

package/README.md

@@ -4,7 +4,7 @@
 >
 > 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.
+> 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.*
 
@@ -15,7 +15,7 @@ This update folds in the root docs, `sdk/README.md`, and the current review find
 - 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;
+- 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`);
@@ -35,7 +35,7 @@ This update folds in the root docs, `sdk/README.md`, and the current review find
 
 ## 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.
+> **[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.
 
@@ -324,20 +324,34 @@ The CLI keeps HubSpot developer-account credentials distinct:
 
 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
+## Install
 
-### Full runtime path
+```bash
+npm i -g @hs-x/cli
+```
+
+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>`.
 
-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.
+## 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.
 
 ```bash
-npx hs-x create deal-enricher
+npm i -g @hs-x/cli
+hs-x init deal-enricher
 cd deal-enricher
-hs-x connect
-hs-x dev --portal 12345
+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` is intentionally broad. It handles or guides:
+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;
@@ -387,31 +401,43 @@ hs-x accounts current [--json]
 hs-x accounts switch <account>
 ```
 
-### `hs-x create`
+### `hs-x init`
 
-Workspace command. Creates a new project and optionally adds it to `hsx.workspace.json`.
+Scaffolds a new HS-X project in a new directory named after the project. `hs-x create` is an accepted alias.
 
 ```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]
+hs-x init [name] [--type workflow-action|sync-source|empty] [--app-name <name>] [--yes] [--no-install] [--force] [--cwd <dir>] [--quiet] [--json]
 ```
 
-```ts
-export interface CreateOptions {
-  name: string;
-  type: "workflow-action" | "sync-source" | "empty";
-  targetDir: string;
-  account?: string;
-  runtimePosture?: RuntimePosture;
-  addToWorkspace: boolean;
-  installDeps: boolean;
-}
+Flags:
 
-export interface CreateResult {
-  projectRoot: string;
-  packageManager: "pnpm" | "npm" | "yarn" | "bun";
-  filesCreated: string[];
-  workspaceUpdated: boolean;
-  nextSteps: string[];
+- `--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
+  }
 }
 ```
 
@@ -545,7 +571,7 @@ hs-x dev upload [--metadata-only]                            # [NOT YET IMPLEMEN
 
 ### `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.
+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]
@@ -591,7 +617,7 @@ export interface DeployResult {
 }
 ```
 
-Phase 1 state machine:
+Deploy state machine:
 
 ```text
 plan_requested
@@ -625,7 +651,7 @@ Rules:
 - `--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-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`
@@ -997,5 +1023,5 @@ Exit codes:
 - `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`?
+- 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?

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA2D9C,wBAAsB,MAAM,CAC1B,IAAI,GAAE,SAAS,MAAM,EAA0B,EAC/C,GAAG,SAAgB,GAClB,OAAO,CAAC,SAAS,CAAC,CAubpB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAiDA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA6D9C,wBAAsB,MAAM,CAC1B,IAAI,GAAE,SAAS,MAAM,EAA0B,EAC/C,GAAG,SAAgB,GAClB,OAAO,CAAC,SAAS,CAAC,CAmFpB"}