@duffcloudservices/cli 0.1.1 → 0.1.3

package/README.md

@@ -1,158 +1,180 @@
-# @duffcloudservices/cli
-
-Command-line interface for initializing and managing DCS (Duff Cloud Services) customer sites.
-
-## Installation
-
-```bash
-npm install -g @duffcloudservices/cli
-# or
-pnpm add -g @duffcloudservices/cli
-```
-
-## Quick Start
-
-```bash
-# 1. Authenticate with Google OAuth
-dcs login
-
-# 2. Initialize a new customer site
-cd /path/to/customer-site
-dcs init --site-slug my-site --site-name "My Site"
-
-# 3. Validate configuration
-dcs validate
-
-# 4. Generate integration plans
-dcs plans
-```
-
-## Commands
-
-### Authentication
-
-```bash
-# Login with Google OAuth (device flow)
-dcs login
-
-# Check current user
-dcs whoami
-
-# Logout and clear credentials
-dcs logout
-```
-
-### Site Management
-
-```bash
-# List sites you have access to
-dcs sites list
-
-# Show details for a specific site
-dcs sites show my-site
-```
-
-### Initialization
-
-```bash
-# Initialize DCS integration in current directory
-dcs init --site-slug my-site --site-name "My Site"
-
-# Specify target directory
-dcs init -s my-site -n "My Site" -t ./my-site
-
-# Specify framework (vue or astro)
-dcs init -s my-site -n "My Site" -f astro
-
-# Preview without creating files
-dcs init -s my-site -n "My Site" --dry-run
-
-# Overwrite existing files
-dcs init -s my-site -n "My Site" --force
-```
-
-### Validation
-
-```bash
-# Validate .dcs configuration files
-dcs validate
-
-# Validate a specific directory
-dcs validate -t ./my-site
-
-# Show verbose output
-dcs validate -v
-```
-
-### Integration Plans
-
-```bash
-# Generate AI-assisted integration plans
-dcs plans
-
-# Regenerate existing plans
-dcs plans --force
-```
-
-## Generated Files
-
-The `init` command creates the following structure:
-
-```
-.dcs/
-├── site.yaml          # Site identity and Azure config
-├── pages.yaml         # Page registry for CMS
-├── content.yaml       # Text content (managed by Portal)
-├── seo.yaml           # SEO configuration (managed by Portal)
-└── SECTION-CONVENTIONS.md
-
-.github/
-└── copilot-instructions.md
-
-.plans/
-├── README.md
-├── 00-audit-site.md
-├── 01-create-use-text-content.md
-├── 02-integrate-home-page.md
-├── 03-integrate-remaining-pages.md
-├── 04-capture-snapshots.md
-└── 05-verify-deployment.md
-```
-
-## Authentication Flow
-
-The CLI uses OAuth 2.0 Device Authorization Grant (RFC 8628):
-
-1. Run `dcs login`
-2. CLI displays a URL and code
-3. Open URL in browser, enter code
-4. Sign in with Google
-5. CLI receives and stores tokens securely
-
-Tokens are stored encrypted in your OS keychain/credential store.
-
-## Site Access Validation
-
-Before creating configuration files, the CLI validates:
-
-1. You're authenticated
-2. You have access to the specified site (or can create it)
-3. You have editor/admin permissions
-
-This prevents creating configs for sites you don't have access to.
-
-## Next Steps After Init
-
-1. **Install CMS package**: `pnpm add @duffcloudservices/cms`
-2. **Configure Vite plugins** in your build config
-3. **Follow the plans** in `.plans/` directory
-4. **Register site** in DCS Portal
-
-## Requirements
-
-- Node.js >= 18.0.0
-- DCS Portal account with Google OAuth
-
-## License
-
-MIT © Duff Cloud Services
+# @duffcloudservices/cli
+
+Command-line interface for initializing and managing DCS (Duff Cloud Services) customer sites.
+
+## Installation
+
+```bash
+npm install -g @duffcloudservices/cli
+# or
+pnpm add -g @duffcloudservices/cli
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate with Google OAuth
+dcs login
+
+# 2. Initialize a new customer site
+cd /path/to/customer-site
+dcs init --site-slug my-site --site-name "My Site"
+
+# 3. Validate configuration
+dcs validate
+
+# 4. Generate integration plans
+dcs plans
+```
+
+## Commands
+
+### Authentication
+
+```bash
+# Login with Google OAuth (device flow)
+dcs login
+
+# Check current user
+dcs whoami
+
+# Logout and clear credentials
+dcs logout
+```
+
+### Site Management
+
+```bash
+# List sites you have access to
+dcs sites list
+
+# Show details for a specific site
+dcs sites show my-site
+```
+
+### Initialization
+
+```bash
+# Initialize DCS integration in current directory
+dcs init --site-slug my-site --site-name "My Site"
+
+# Specify target directory
+dcs init -s my-site -n "My Site" -t ./my-site
+
+# Specify framework (vue or astro)
+dcs init -s my-site -n "My Site" -f astro
+
+# Preview without creating files
+dcs init -s my-site -n "My Site" --dry-run
+
+# Overwrite existing files
+dcs init -s my-site -n "My Site" --force
+```
+
+### Validation
+
+```bash
+# Validate .dcs configuration files
+dcs validate
+
+# Validate a specific directory
+dcs validate -t ./my-site
+
+# Show verbose output
+dcs validate -v
+```
+
+### Integration Plans
+
+```bash
+# Generate AI-assisted integration plans
+dcs plans
+
+# Regenerate existing plans
+dcs plans --force
+```
+
+### Page Snapshot Capture
+
+```bash
+# Capture all pages listed in .dcs/pages.yaml
+dcs capture-snapshots --target ./customer-site --base-url http://localhost:5173
+
+# Capture only selected page slugs
+dcs capture-snapshots --target ./customer-site --base-url http://localhost:5173 --pages home,about
+```
+
+Snapshot output uses a fixed portal contract:
+
+| File | Portal use | Capture behavior |
+| --- | --- | --- |
+| `site-snapshots/{pageSlug}/full-page.png` | Expanded page dialog with auto-scroll | Full scrollable page after a lazy-load pass |
+| `site-snapshots/{pageSlug}/thumbnail.png` | Pages grid cards | Header/hero-focused 16:9 top crop captured at the site desktop viewport |
+| `site-snapshots/{pageSlug}/sections/{sectionId}.png` | Visual-editor section overlays | Individual `data-section` element screenshots |
+
+Keep these names stable across customer-site scripts. Site-specific flexibility belongs in `.dcs/pages.yaml` (`snapshot.viewport`, `waitAfterLoad`, page paths) and in environment variables such as `SITE_PREVIEW_URL`, not in alternate artifact names.
+
+For managed CSS-style backgrounds, render a real image layer with `data-dcs-image-key` and a matching `.dcs/content.yaml` key. Snapshot capture records those markers as editable image keys, which keeps background images visible in full-page screenshots and replaceable from the visual editor.
+
+## Generated Files
+
+The `init` command creates the following structure:
+
+```
+.dcs/
+├── site.yaml          # Site identity and Azure config
+├── pages.yaml         # Page registry for CMS
+├── content.yaml       # Text content (managed by Portal)
+├── seo.yaml           # SEO configuration (managed by Portal)
+└── SECTION-CONVENTIONS.md
+
+.github/
+└── copilot-instructions.md
+
+.plans/
+├── README.md
+├── 00-audit-site.md
+├── 01-create-use-text-content.md
+├── 02-integrate-home-page.md
+├── 03-integrate-remaining-pages.md
+├── 04-capture-snapshots.md
+└── 05-verify-deployment.md
+```
+
+## Authentication Flow
+
+The CLI uses OAuth 2.0 Device Authorization Grant (RFC 8628):
+
+1. Run `dcs login`
+2. CLI displays a URL and code
+3. Open URL in browser, enter code
+4. Sign in with Google
+5. CLI receives and stores tokens securely
+
+Tokens are stored encrypted in your OS keychain/credential store.
+
+## Site Access Validation
+
+Before creating configuration files, the CLI validates:
+
+1. You're authenticated
+2. You have access to the specified site (or can create it)
+3. You have editor/admin permissions
+
+This prevents creating configs for sites you don't have access to.
+
+## Next Steps After Init
+
+1. **Install CMS package**: `pnpm add @duffcloudservices/cms`
+2. **Configure Vite plugins** in your build config
+3. **Follow the plans** in `.plans/` directory
+4. **Register site** in DCS Portal
+
+## Requirements
+
+- Node.js >= 18.0.0
+- DCS Portal account with Google OAuth
+
+## License
+
+MIT © Duff Cloud Services