@woodsportal/hubspot-kit 1.0.26 → 1.0.27

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.0.27 — 2026-06-07
+
+### Docs
+- Expanded README: full command reference, workflows, project layout, documentation index
+- Aligned `GETTING-STARTED.md` and `HUBSPOT-CLI-SETUP.md` (`defaultPortal` = portal name)
+
 ## 1.0.26 — 2026-06-07
 
 ### CLI

package/README.md

@@ -1,64 +1,271 @@
 # WoodsCLI
 
-> HubSpot CMS dev kit by WoodsPortal — modules and themes.  
-> `npm i @woodsportal/hubspot-kit` · `wp dev`
+**HubSpot CMS dev kit by WoodsPortal** — local preview, module field editing, Vite build pipelines, and HubSpot upload/watch for **custom modules** and **themes**.
 
-WoodsCLI (`wp`) is the development CLI for **HubSpot CMS custom modules** (React/JS + `fields.json`) and **themes** (templates, CSS, theme fields). It wraps `@hubspot/cli` for upload/watch and adds local preview, Content/Styles field editing (**Ctrl+Shift+Z**), and hybrid CDN or monolith build pipelines.
+```bash
+npm i -D @woodsportal/hubspot-kit@^1.0.27
+npx wp --version
+```
+
+The `wp` CLI wraps [`@hubspot/cli`](https://developers.hubspot.com/docs/cms/developer-reference/local-development-cli) for CMS operations and adds WoodsPortal-specific tooling: hybrid CDN or monolith module builds, the **module-config overlay** (**Ctrl+Shift+Z** / **Cmd+Shift+Z**), and a `.wphs/` local workspace.
+
+---
+
+## What you get
+
+| Capability | Command / artifact |
+|------------|-------------------|
+| Scaffold module or theme | `wp init` |
+| Local SPA + field editor | `wp dev` (`wp local`) |
+| HubSpot file sync | `wp watch`, `wp upload` |
+| Full ship pipeline | `wp deploy` (build → CDN publish → upload) |
+| Project health check | `wp doctor` |
+| Portal switching | `wp portal use` |
+| CI / regression gates | `wp examples smoke`, `wp regression smoke`, `wp audit *` |
+
+**Reference implementation:** [woodsportal-client-frontend](https://github.com/Digital-Woods/digitalwoods.io-woodsportal-client-frontend) — advanced hybrid CDN module with a full app adapter.
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|--------|
+| **Node.js 20+** | Enforced by `wp doctor` |
+| **HubSpot CLI** | `npm i -g @hubspot/cli` — required for upload/watch/deploy |
+| **HubSpot CMS portal** | Design Manager access; PAT or OAuth via `wp auth` |
+| **Project config** | `woodscli.json` at repo root (created by `wp init` or `wp adopt`) |
 
-## Two tracks
+Local preview (`wp dev`) runs **without** HubSpot credentials. Upload, watch, and deploy need a valid project `hubspot.config.yml`.
 
-| Track | `projectType` | Quick start |
-|-------|---------------|-------------|
-| **Module (hybrid CDN)** | `module-hybrid-cdn` | `wp init -t module-hybrid-cdn` → `wp dev` → `wp deploy` |
-| **Module (monolith)** | `module-monolith` | `wp init -t module-monolith` → `wp dev` → `wp build --hubspot-only` |
-| **Theme** | `theme-starter` | `wp init -t theme-starter` → `wp dev` → `wp upload` |
+---
 
-WoodsPortal client-frontend is the **reference advanced module** (hybrid CDN + full app adapter).
+## Install
 
-## Quick start
+**New project** (scaffold includes the kit):
 
 ```bash
-npx wp init -t module-hybrid-cdn
-cd my-project && npm install
-wp setup        # copy hubspot.config.yml, .env.*, CDN templates
+npx wp init -t module-hybrid-cdn -n my-portal-module
+cd my-portal-module && npm install
+```
+
+**Existing consumer** (add dev dependency):
+
+```bash
+npm i -D @woodsportal/hubspot-kit@^1.0.27
+# or: yarn add -D @woodsportal/hubspot-kit@^1.0.26
+```
+
+Use scripts that call `wp` directly, or rely on `node_modules/.bin/wp` after install.
+
+---
+
+## Project types
+
+| Track | `projectType` | Build output | Typical ship flow |
+|-------|---------------|--------------|-------------------|
+| **Module (hybrid CDN)** | `module-hybrid-cdn` | `dist/cdn/*` + `module.outDir` | `wp deploy` |
+| **Module (monolith)** | `module-monolith` | Single bundle in `module.outDir` | `wp build` → `wp upload` |
+| **Theme** | `theme-starter` | Theme folder under `theme.srcDir` | `wp upload` |
+
+Init templates live under `templates/` in this package. Hybrid CDN splits vendor/app chunks for jsDelivr; monolith sets `cdn.mode: none` and skips CDN publish on deploy.
+
+---
+
+## Quick start (greenfield)
+
+```bash
+npx wp init -t module-hybrid-cdn -n my-portal-module
+cd my-portal-module && npm install
+
+wp setup          # hubspot.config.yml, .env.*, CDN files, vite shims (never overwrites)
+wp doctor         # Node, config, .wphs/, HubSpot CLI
+wp auth           # HubSpot login — updates hubspot.config.yml
+wp portal use     # interactive default portal (or: wp portal use <name>)
+
+wp dev            # http://localhost:3000 — alias: wp local
+```
+
+**Module overlay:** open the dev server, press **Ctrl+Shift+Z** (Windows/Linux) or **Cmd+Shift+Z** (macOS) to edit Content/Styles fields against `fields.json`.
+
+---
+
+## Existing repository
+
+```bash
+wp adopt            # detect module/theme layout, add woodscli.json + .wphs/
+wp setup
+wp migrate --yes    # if you still have legacy .dev/ or woodsportal.hs.json
 wp doctor
-wp dev          # alias: wp local
 ```
 
-Existing repo:
+Legacy filename `woodsportal.hs.json` is **not** read — migrate to `woodscli.json` with `wp migrate --yes`.
+
+---
+
+## Day-to-day workflows
+
+### Local development
+
+```bash
+wp dev                    # Vite HMR + module-config overlay
+wp dev -p 3001            # custom port
+```
+
+### Watch HubSpot folder (CMS sync)
+
+```bash
+wp watch                  # hs cms watch on module.outDir (builds if output missing)
+wp watch --rebuild        # rebuild on src/ + public/ changes, then watch
+```
+
+`wp watch` does not use progress spinners so **Ctrl+C** and HubSpot TTY output stay reliable.
+
+### Build and ship
 
 ```bash
-wp adopt
-wp migrate --yes   # if migrating from .dev/
+wp build                  # default --tier dev
+wp build --cdn-only       # hybrid CDN chunks only
+wp build --hubspot-only   # module bundle only (monolith-friendly)
+
+wp publish --tier dev     # push CDN mirror (hybrid only)
+wp upload --tier dev      # hs cms upload
+wp deploy --tier dev      # build + publish + upload (skips CDN when cdn.mode: none)
 ```
 
-## Commands
+Tiers: `dev` | `stg` | `prod`. Production upload requires confirmation (`--yes` or `WP_HS_CONFIRM_PROD=1`). See [docs/BUILD-MODES.md](./docs/BUILD-MODES.md).
+
+---
+
+## HubSpot authentication
+
+1. `wp setup` copies `hubspot.config.yml.example` → `hubspot.config.yml` (gitignored).
+2. `wp auth` runs `hs auth` (browser / PAT flow).
+3. `wp portal list` shows configured portals; `wp portal use <name>` sets `defaultPortal`.
+
+Run auth and portal commands from the **project root** so HubSpot CLI reads `./hubspot.config.yml`.
+
+Full guide: [docs/HUBSPOT-CLI-SETUP.md](./docs/HUBSPOT-CLI-SETUP.md)
+
+---
+
+## Command reference
+
+Global flags (all commands): `--project <path>`, `--ci`, `--json`, `--verbose`, `--quiet`, `--dry-run`, `-y/--yes`.
+
+### Project lifecycle
 
 | Command | Description |
 |---------|-------------|
-| `wp setup` | Copy missing `hubspot.config.yml`, `.env.*`, CDN config, vite shims |
-| `wp dev` | Local Vite server + CMS dev tool |
-| `wp build` | CDN + module (or theme no-op); default `--tier dev` |
-| `wp deploy` | Build, publish CDN, upload module; default `--tier dev` |
-| `wp adopt` | Detect module/theme and add config + `.wphs/` |
-| `wp migrate` | `.dev/` → `.wphs/` |
-| `wp examples smoke` | Run examples matrix (CI) |
-| `wp audit secrets` | Scan for hardcoded credentials |
+| `wp init [-t template] [-n name] [--router hash\|browser\|none]` | Scaffold `module-hybrid-cdn`, `module-monolith`, or `theme-starter` |
+| `wp adopt` | Add WoodsCLI config to an existing module/theme repo |
+| `wp migrate` | Move legacy `.dev/` / `woodsportal.hs.json` → `.wphs/` + `woodscli.json` |
+| `wp setup [--tier dev\|stg\|prod]` | Copy missing config, env, CDN, and vite shim files |
+| `wp doctor` | Prerequisite checks (interactive progress on TTY) |
+| `wp config validate` | Validate `woodscli.json` (zod) |
 
-See [docs/CLI-REFERENCE.md](./docs/CLI-REFERENCE.md), [docs/MODULES.md](./docs/MODULES.md), [docs/THEMES.md](./docs/THEMES.md), [docs/EXAMPLES.md](./docs/EXAMPLES.md).
+### HubSpot account
 
-## Config
+| Command | Description |
+|---------|-------------|
+| `wp auth` | `hs auth` — add or refresh portal credentials |
+| `wp portal list` / `wp portal ls` | List `portals[]` and current `defaultPortal` |
+| `wp portal use [name]` | `hs accounts use` — name or portalId; interactive if name omitted |
 
-**Config:** `woodscli.json` at project root. Legacy `woodsportal.hs.json` → run `wp migrate --yes`.
+### Develop and sync
 
-Local workspace: **`.wphs/`** only. Consumer hook: **`wphs.adapter.ts`**.
+| Command | Description |
+|---------|-------------|
+| `wp dev` / `wp local` | Local Vite dev server + module-config UI |
+| `wp watch [--rebuild] [--tier dev\|stg\|prod]` | `hs cms watch` on built module/theme output |
+| `wp fields sync [--direction pull\|push]` | Sync `fields.json` with local cache |
 
-HubSpot upload/watch: **`hubspot.config.yml`** — [setup guide](./docs/HUBSPOT-CLI-SETUP.md).
+### Build and deploy
 
-## Prerequisites
+| Command | Description |
+|---------|-------------|
+| `wp build [--tier] [--cdn-only] [--hubspot-only] [--cdn-esm]` | CDN + module (or theme no-op) |
+| `wp publish [--tier] [--dry-run]` | Verify CDN endpoint and push jsDelivr mirror |
+| `wp upload [--tier]` | `hs cms upload` using paths from `woodscli.json` |
+| `wp deploy [--tier] [--skip-publish]` | Full pipeline: build → publish → upload |
+
+### Quality and CI
+
+| Command | Description |
+|---------|-------------|
+| `wp regression smoke [--skip-doctor]` | Config validate + consumer boundary checks |
+| `wp examples list` | List scenarios from `examples/manifest.json` |
+| `wp examples smoke [--scenario id] [--tier static\|live]` | Examples matrix (used in kit CI) |
+| `wp audit ship-bundle` | Fail if dev-only strings appear in `dist/` |
+| `wp audit parity [--baseline dir]` | Compare `dist/` to baseline snapshot |
+| `wp audit baseline [--baseline dir]` | Capture parity baseline under `.wphs/` |
+| `wp audit secrets` | Scan for hardcoded PATs / credentials |
+
+Detailed flags and exit codes: [docs/CLI-REFERENCE.md](./docs/CLI-REFERENCE.md)
+
+---
+
+## Project layout
+
+```
+my-project/
+├── woodscli.json           # WoodsCLI project config (required)
+├── hubspot.config.yml      # HubSpot CLI portals (gitignored; from wp setup)
+├── wphs.adapter.ts         # Consumer adapter hook (modules)
+├── vite.config.dev.mjs     # Re-exports kit dev preset
+├── vite.config.hubspot.mjs # or vite.config.monolith.mjs
+├── .wphs/                  # Local workspace (module-config, cache, audit)
+├── src/                     # App source
+├── public/                  # fields.json, module.html (modules)
+└── dist/                    # Build output (cdn + module.outDir)
+```
+
+| File / dir | Purpose |
+|------------|---------|
+| `woodscli.json` | `projectType`, module/theme paths, CDN mode, env tiers |
+| `.wphs/` | Module-config overlay state, fixtures, audit baseline |
+| `wphs.adapter.ts` | Bridge to your app (routing, API, HubSpot context) |
+| `hubspot.config.yml` | Portal names, PATs, `defaultPortal` |
+
+Config field reference: [docs/CONFIG-REFERENCE.md](./docs/CONFIG-REFERENCE.md)
+
+---
+
+## Documentation
+
+| Doc | Topic |
+|-----|--------|
+| [GETTING-STARTED.md](./docs/GETTING-STARTED.md) | First-run walkthrough |
+| [CLI-REFERENCE.md](./docs/CLI-REFERENCE.md) | All commands, flags, exit codes |
+| [HUBSPOT-CLI-SETUP.md](./docs/HUBSPOT-CLI-SETUP.md) | PAT, auth, portals |
+| [MODULES.md](./docs/MODULES.md) | Module build paths and overlay |
+| [THEMES.md](./docs/THEMES.md) | Theme starter workflow |
+| [BUILD-MODES.md](./docs/BUILD-MODES.md) | CDN vs monolith, tiers, prod guards |
+| [ADAPTER.md](./docs/ADAPTER.md) | `wphs.adapter.ts` contract |
+| [EXAMPLES.md](./docs/EXAMPLES.md) | Examples smoke matrix |
+| [TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) | Common failures |
+| [RUNBOOK.md](./docs/RUNBOOK.md) | Ops and release notes |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | PR and verify workflow |
+
+---
+
+## Develop the kit
+
+```bash
+git clone https://github.com/Digital-Woods/digitalwoods.io-woodsportal-hubspot-kit.git
+cd digitalwoods.io-woodsportal-hubspot-kit
+npm ci
+npm run verify    # typecheck + test + examples smoke + build
+```
+
+Link locally in a consumer:
+
+```bash
+npm i -D @woodsportal/hubspot-kit@file:../digitalwoods.io-woodsportal-hubspot-kit
+```
 
-Node 20+, `@hubspot/cli`, HubSpot account with CMS.
+---
 
 ## License
 
-MIT — Digital Woods
+MIT — [Digital Woods](https://github.com/Digital-Woods)

package/dist/cli.js

@@ -520,7 +520,7 @@ var VITE_DEV_PEER_DEPS = {
   tailwindcss: "^4.0.6"
 };
 var KIT_DEV_DEP = "@woodsportal/hubspot-kit";
-var KIT_DEV_DEP_VERSION = "^1.0.26";
+var KIT_DEV_DEP_VERSION = "^1.0.27";
 var MODULE_CONFIG_UI_DEPS = [
   "@dnd-kit/core",
   "@dnd-kit/sortable",