@scrymore/scry-deployer 0.6.1 → 0.7.0-next.20260926193255

package/README.md

@@ -2,31 +2,7 @@
 
 Deploy your Storybook to the cloud with one command. ⚡
 
-## Set up with your AI assistant
-
-From your application's repository, install the Scry setup skill:
-
-```bash
-npx skills add epinnock/scry-node --skill scry-setup
-```
-
-The current installer requires Node.js 22.20 or newer. Choose your assistant
-(Claude Code, Codex, Cursor, or another compatible agent), then ask:
-**“Set up Scry for this project and connect my assistant to its components.”**
-
-The skill handles deployment configuration, GitHub Actions, component indexing,
-MCP connections, and optional Figma linking. You can also ask for MCP alone.
-Complete account sign-in in your browser and keep API keys in your environment
-or CI secret store.
-
-See the [setup guide](https://docs.scrymore.com/guide/skill) for installation
-options, or inspect the [skill instructions](skills/scry-setup/SKILL.md).
-
-## Set up directly with the CLI
-
-`init` writes configuration and workflows, configures GitHub secrets, then
-commits and pushes. For local preparation before publishing, use the skill or
-the manual deployment path below. `--skip-gh-setup` still commits and pushes.
+## 🎯 Quick Start (5 seconds)
 
 ### 1. Get your credentials
 Visit the [Scry Dashboard](https://dashboard.scrymore.com) and:
@@ -102,7 +78,7 @@ This deploys your Storybook immediately without setting up GitHub Actions.
 npx @scrymore/scry-deployer init --projectId xxx --apiKey yyy
 
 # From GitHub (latest from main branch)
-npx github:epinnock/scry-node init --projectId xxx --apiKey yyy
+npx github:scryorg/scry-node init --projectId xxx --apiKey yyy
 ```
 
 ### Installing as a Dependency
@@ -114,18 +90,18 @@ If you prefer to install it as a development dependency:
 npm install @scrymore/scry-deployer --save-dev
 
 # From GitHub
-npm install github:epinnock/scry-node --save-dev
+npm install github:scryorg/scry-node --save-dev
 # or
-pnpm add github:epinnock/scry-node -D
+pnpm add github:scryorg/scry-node -D
 # or
-yarn add github:epinnock/scry-node --dev
+yarn add github:scryorg/scry-node --dev
 ```
 
 After installation, you can run commands using:
 
 ```bash
-# Using the scry-deployer binary
-npm exec -- scry-deployer init --projectId xxx --apiKey yyy
+# Using the storybook-deployer binary
+npx storybook-deployer init --projectId xxx --apiKey yyy
 
 # Using the scry alias
 npx scry init --projectId xxx --apiKey yyy
@@ -205,17 +181,50 @@ The CLI is configured through a combination of command-line options and environm
 |----------------|---------------------------------------|--------------------------------------------------------------|----------|--------------------------------------|
 | `--dir`        | `STORYBOOK_DEPLOYER_DIR`              | Path to the built Storybook directory (e.g., `storybook-static`). | Yes      | -                                    |
 | `--api-key`    | `STORYBOOK_DEPLOYER_API_KEY`          | The API key for the deployment service.                        | No       | -                                    |
-| `--api-url`    | `STORYBOOK_DEPLOYER_API_URL`          | Base URL for the deployment service API.                       | No       | `https://api.default-service.com/v1`  |
+| `--api-url`    | `STORYBOOK_DEPLOYER_API_URL`          | Base URL for the deployment service API.                       | No       | `https://storybook-deployment-service.epinnock.workers.dev` |
 | `--project`    | `STORYBOOK_DEPLOYER_PROJECT`          | The project name/identifier.                                   | No       | `main`                               |
 | `--version`    | `STORYBOOK_DEPLOYER_VERSION`          | The version identifier for the deployment.                     | No       | `latest`                             |
-| `--with-analysis` | `STORYBOOK_DEPLOYER_WITH_ANALYSIS` | Enable Storybook analysis (story crawling + screenshots). Enabled by default in generated workflows. | No       | `false`                              |
+| `--with-analysis` | `STORYBOOK_DEPLOYER_WITH_ANALYSIS` / `SCRY_WITH_ANALYSIS` | Capture screenshots and metadata so components are searchable. **On by default since 0.7.0.** | No       | on                                   |
+| `--no-analysis` | `STORYBOOK_DEPLOYER_ANALYSIS=false` | Host the Storybook without indexing it. The log says the build is NOT searchable. | No | - |
+| `--max-dropped` | `SCRY_MAX_DROPPED` (or `maxDropped` in `.storybook-deployer.json`) | How many stories may fail to capture before the deploy ends red. The deployer always passes it to scry-sbcov (0.5.2+); the stories that did capture are uploaded and queued first. | No | `0`: any dropped story ends the deploy red |
 | `--stories-dir` | `STORYBOOK_DEPLOYER_STORIES_DIR`     | Path to stories directory (optional, auto-detects .stories.* files). | No | Auto-detect                          |
 | `--screenshots-dir` | `STORYBOOK_DEPLOYER_SCREENSHOTS_DIR` | Directory for captured screenshots.                        | No       | `./screenshots`                      |
 | `--storybook-url` | `STORYBOOK_DEPLOYER_STORYBOOK_URL` | URL of running Storybook server for screenshot capture.        | No       | `http://localhost:6006`              |
+| `--capture-mode` | `SCRY_CAPTURE_MODE`                 | Screenshot framing forwarded to scry-sbcov: `root` (crop to the component) or `viewport`. | No | unset: sbcov decides (`root` from sbcov 0.6) |
+| `--capture-scale` | `SCRY_CAPTURE_SCALE`               | Screenshot device scale factor forwarded to scry-sbcov, `0 < n <= 4`. | No | unset: sbcov decides (`2` from sbcov 0.6) |
+| `--capture-viewport` | `SCRY_CAPTURE_VIEWPORT`         | Browser viewport `WIDTHxHEIGHT` forwarded to scry-sbcov.       | No | unset: sbcov decides (`1280x720`) |
 | `--verbose`    | `STORYBOOK_DEPLOYER_VERBOSE`          | Enable verbose logging for debugging purposes.                 | No       | `false`                              |
+| -              | `SCRY_NO_UPDATE_CHECK=1`              | Skip the check against npm `latest` (a one-line warning when this deployer is older; 2 s limit, never fails the deploy). | No | check on |
 | `--help`, `-h` | -                                     | Show the help message.                                       | -        | -                                    |
 | `--version`, `-v`| -                                     | Show the version number.                                     | -        | -                                    |
 
+### Exit codes and indexing (0.7.0)
+
+A deploy that was asked to index and will index nothing ends **red**. The Storybook is still
+uploaded and hosted in every case below, so the preview link works; the red run is the signal.
+
+| What happened | Log line | Exit code |
+|---|---|---|
+| Stories captured, metadata uploaded and queued | `⏳ Indexing has been queued, not finished.` | 0 |
+| Metadata upload rejected by the service | `❌ The metadata upload failed (<reason>), so NOTHING WILL BE INDEXED.` | 1 |
+| Metadata uploaded but not queued | `❌ Metadata was uploaded but not queued for processing, so NOTHING WILL BE INDEXED.` | 1 |
+| Analysis captured 0 stories (the empty archive is not uploaded, no build is queued) | `❌ Analysis captured 0 of N stories, so NOTHING WILL BE INDEXED.` plus the first capture error | 1 |
+| Analysis produced no archive (for example, no Playwright browser) | `❌ Analysis produced no metadata, so NOTHING WILL BE INDEXED.` | 1 |
+| scry-sbcov exited non-zero but wrote an archive (exit 3: more stories dropped than `--max-dropped`, default 0) | the archive is queued, then `❌ scry-sbcov dropped more stories than --max-dropped allows (exit 3)…` and `N of M stories were not captured (timeout 40, …)` | 1 |
+| scry-sbcov exited 0 but its `sbcov-manifest.json` lists more dropped stories than `--max-dropped` allows | the archive is queued, then `❌ N of M stories were not captured (…), more than --max-dropped K allows.` | 1 |
+| Some stories dropped, within `--max-dropped` | `scry-sbcov: 417/461 stories captured, 44 not captured (timeout 40, render error 4).` then the queued line | 0 |
+| scry-sbcov exited non-zero with no archive (exit 2: broken capture config) | `❌ Analysis produced no metadata…` with `Cause: scry-sbcov rejected the capture config (exit 2)` | 1 |
+| `--no-analysis` (or `--no-coverage` / `--coverage-report <file>` without `--with-analysis`) | `ℹ️  Analysis skipped (--no-analysis): this build is hosted but NOT searchable.` | 0 |
+| Any error before the upload (bad `--dir`, bad API key, invalid flag) | `❌ Error: …` | 1 |
+
+scry-sbcov's own exit codes (0.5.2+): **0** ok, **2** the capture config is broken, misspelt or
+unknown (no archive), **3** more stories dropped than `--max-dropped` (archive of the rest written).
+The deployer passes `--max-dropped 0` unless you set a value; with a scry-sbcov older than 0.5.2,
+which does not know the flag, it is not passed and the log says dropped stories cannot be counted.
+
+Before 0.7.0 the metadata-upload failure, the "not queued" case, an empty archive, a non-zero
+scry-sbcov exit and a workflow that simply forgot `--with-analysis` all ended green (ISSUES.md #50).
+
 ### Story File Auto-Detection
 
 The analysis feature now automatically detects `.stories.*` files anywhere in your project! You no longer need to specify a stories directory - the system intelligently searches for story files with these features:
@@ -284,6 +293,15 @@ The configuration file (`.storybook-deployer.json`) is automatically created in
 - `project` → `--project` CLI option
 - `version` → `--version` CLI option
 - `verbose` → `--verbose` CLI option
+- `captureMode` → `--capture-mode` CLI option
+- `captureScale` → `--capture-scale` CLI option
+- `captureViewport` → `--capture-viewport` CLI option (`"390x844"` or `{ "width": 390, "height": 844 }`)
+
+**Screenshot capture settings.** `captureMode`, `captureScale` and `captureViewport` are validated and passed to
+scry-sbcov as `--capture-mode`, `--capture-scale` and `--capture-viewport`. Only the ones you set are passed, so
+leaving them out keeps sbcov's defaults and any `scry-sbcov.config.*` in your project in charge. An invalid value
+fails the run. To keep whole-window 1x screenshots, set `"captureMode": "viewport", "captureScale": 1`. For
+`root` mode, mark the component with `data-scry-root` (see the scry-sbcov README, "Capture settings").
 
 **See [`.storybook-deployer.example.json`](.storybook-deployer.example.json) for a complete configuration file with all available options and their default values.**
 
@@ -371,40 +389,61 @@ Without analysis, only the static site is zipped and uploaded as `{project}-{ver
 
 ## Example CI/CD Integration (GitHub Actions)
 
-This tool is ideal for use in a GitHub Actions workflow. The API key should be stored as a [GitHub Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
+Let the deployer write the workflows for you (`init` for a new project, `update-workflows` to
+refresh existing ones; see below). The steps it generates, after your Storybook is built:
 
-**Basic deployment workflow:**
 ```yaml
-- name: Deploy Storybook
-  env:
-    STORYBOOK_DEPLOYER_API_URL: https://storybook-deployment-service.epinnock.workers.dev
-    STORYBOOK_DEPLOYER_PROJECT: ${{ github.event.repository.name }}
-    STORYBOOK_DEPLOYER_VERSION: ${{ github.sha }}
-  run: npx storybook-deploy --dir ./storybook-static
-```
-
-**Deployment with analysis:**
-```yaml
-- name: Start Storybook server
-  run: npm run storybook &
-  
-- name: Wait for Storybook
-  run: npx wait-on http://localhost:6006
-
-- name: Deploy Storybook with Analysis
-  env:
-    STORYBOOK_DEPLOYER_API_URL: https://storybook-deployment-service.epinnock.workers.dev
-    STORYBOOK_DEPLOYER_PROJECT: ${{ github.event.repository.name }}
-    STORYBOOK_DEPLOYER_VERSION: ${{ github.sha }}
+- name: Install the Scry deployer
+  id: scry
+  # Its own folder and a floor of ^0.7.0: the repo's own pin cannot pick an older deployer.
+  run: |
+    set -o pipefail
+    mkdir -p "$RUNNER_TEMP/scry"
+    npm i --no-save --no-audit --no-fund --ignore-scripts --prefix "$RUNNER_TEMP/scry" @scrymore/scry-deployer@^0.7.0
+    cd "$RUNNER_TEMP/scry"
+    echo "version=$(node -p "require('@scrymore/scry-deployer/package.json').version")" >> "$GITHUB_OUTPUT"
+    PW="$(npx --no-install playwright --version | awk '{print $2}')"
+    [ -n "$PW" ] || { echo "::error::the deployer's Playwright was not found"; exit 1; }
+    echo "playwright=$PW" >> "$GITHUB_OUTPUT"
+
+- name: Cache the deployer's Playwright browser
+  uses: actions/cache@v4
+  with:
+    path: ~/.cache/ms-playwright
+    key: scry-pw-${{ runner.os }}-${{ steps.scry.outputs.playwright }}
+
+- name: Install the deployer's Playwright browser
+  working-directory: ${{ runner.temp }}/scry
+  run: npx --no-install playwright install --with-deps chromium-headless-shell
+
+- name: Deploy to Scry
   run: |
-    npx storybook-deploy \
+    "$RUNNER_TEMP/scry/node_modules/.bin/scry-deployer" \
       --dir ./storybook-static \
       --with-analysis \
-      --storybook-url http://localhost:6006
-  # Note: --stories-dir is optional; story files are auto-detected
+      --coverage-base ${{ vars.SCRY_COVERAGE_BASE || github.event.before }}
+  env:
+    STORYBOOK_DEPLOYER_API_URL: ${{ vars.SCRY_API_URL }}
+    STORYBOOK_DEPLOYER_PROJECT: ${{ vars.SCRY_PROJECT_ID }}
+    STORYBOOK_DEPLOYER_API_KEY: ${{ secrets.SCRY_API_KEY }}
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-See the example workflow file: `.github/workflows/deploy-example.yml`
+Why these steps and in this order:
+
+- **The deployer goes into its own folder** (`$RUNNER_TEMP/scry`), so a version pinned in your
+  `package.json` or lockfile cannot select an old deployer, and a pnpm or yarn `node_modules`
+  is never touched. The same steps work for npm, pnpm, yarn and bun projects.
+- **The browser comes from the deployer's own Playwright**, installed after the deployer.
+  A bare `npx playwright install` resolves whatever Playwright is newest (or your project's)
+  and can download a browser build the analyzer does not look for; every story then fails
+  and nothing is indexed.
+- **Never call a bare `npx @scrymore/scry-deployer`** in CI: it runs whatever version your
+  repository pins, however old.
+
+The full generated files are in [`templates/workflows/`](templates/workflows/). The PR
+workflow also skips draft PRs, deploys when a PR is marked ready, and cancels a superseded run
+for the same PR.
 
 ### PR Preview Deployments
 
@@ -450,12 +489,12 @@ If you're installing from GitHub, the workflow file is already included.
 | Variable Name | Value | Example |
 |--------------|-------|---------|
 | `SCRY_PROJECT_ID` | Your project identifier | `my-storybook` or `company-design-system` |
-| `SCRY_API_URL` | Backend API endpoint for uploads | `https://api.scrymore.com` |
+| `SCRY_API_URL` | Backend API endpoint for uploads (the upload service) | `https://storybook-deployment-service.epinnock.workers.dev` |
 | `SCRY_VIEW_URL` | Base URL where users view deployed Storybooks | `https://view.scrymore.com` |
 
 **Note:** The `SCRY_VIEW_URL` is where users will access your deployed Storybook (e.g., `https://view.scrymore.com/{project}/pr-{number}/`). This is separate from `SCRY_API_URL`, which is the backend API endpoint used for uploads.
 
-**Note:** Generated workflows include `--with-analysis` by default for build processing service integration. To disable, add `STORYBOOK_DEPLOYER_WITH_ANALYSIS` as a repository variable set to `false`.
+**Note:** Generated workflows pass `--with-analysis`, and since 0.7.0 analysis is on by default anyway. A deploy that indexes nothing ends red (see "Exit codes and indexing"). To host a Storybook without indexing it, change the flag to `--no-analysis`. Any story that fails to capture ends the deploy red (after the rest are queued); to allow some, set the repository variable `SCRY_MAX_DROPPED`.
 
 **Step 3: Configure GitHub Actions Secrets (Optional)**
 
@@ -941,6 +980,20 @@ git remote set-url origin git@github.com:your-username/your-repo.git
 }
 ```
 
+### Regenerate your workflows (`update-workflows`)
+
+Workflows written by an older deployer can be missing the browser step or run an old
+deployer. Refresh them from the current templates, without an API key:
+
+```bash
+npx -y @scrymore/scry-deployer@^0.7.0 update-workflows            # rewrite both files
+npx -y @scrymore/scry-deployer@^0.7.0 update-workflows --commit   # and commit them
+```
+
+It detects your package manager from the lockfile and your Storybook build script from
+`package.json`, and overwrites `.github/workflows/deploy-storybook.yml` and
+`.github/workflows/deploy-pr-preview.yml`. Review the diff if you customised them.
+
 ### Want to customize the generated workflows?
 
 After running `init`, you can edit:
@@ -1040,6 +1093,6 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
 ## 🆘 Support
 
 Need help?
-- 📖 [Documentation](https://github.com/epinnock/scry-node)
-- 🐛 [Report an issue](https://github.com/epinnock/scry-node/issues)
-- 💬 [Discussions](https://github.com/epinnock/scry-node/discussions)
+- 📖 [Documentation](https://github.com/scryorg/scry-node)
+- 🐛 [Report an issue](https://github.com/scryorg/scry-node/issues)
+- 💬 [Discussions](https://github.com/scryorg/scry-node/discussions)