npm package: @stackwright-pro/launch-stackwright-pro
Description: Launch a new Stackwright Pro project with OpenAPI integration, auth, and the otter raft
Latest version: 0.3.0

# launch-stackwright-pro

🚢 Scaffold a new **Stackwright Pro** project in one command — complete with
OpenAPI integration, RBAC auth, mock users, and the otter raft ready to build
your site for you.

## How It Works

This package uses the **scaffold hooks system** (`@stackwright-pro/scaffold-hooks`)
to automatically wire up Pro features:

1. **Import hooks** → Auto-registers Pro packages during scaffolding
2. **Call `scaffold()`** → Hooks automatically add:
   - Pro dependencies (`@stackwright-pro/mcp`, `@stackwright-pro/otters`, etc.)
   - MCP server configuration in `.code-puppy.json`
   - Role-based dev scripts (`dev:admin`, `dev:analyst`, `dev:viewer`)
3. **Post-processing** → Copies Pro templates, adds auth config, generates README

## Quick Start

```bash
npx launch-stackwright-pro my-app --yes
cd my-app
pnpm install
pnpm dev
```

### With an OpenAPI Spec

```bash
npx launch-stackwright-pro my-app --spec ./my-api.yaml --yes
```

The spec gets copied into `specs/` and wired into `stackwright.yml`. The
prebuild script generates types & a client on the first `pnpm dev`.

## What Gets Created

```
my-app/
├── pages/
│   ├── _app.tsx              # Pro _app with AuthProvider
│   ├── _document.tsx
│   ├── index.ts
│   └── [...slug].tsx
├── lib/
│   └── mock-auth.ts          # Dev-mode mock users (admin/analyst/viewer)
├── scripts/
│   └── prebuild.js           # Reads stackwright.yml → runs OpenAPI plugin
├── specs/                    # Only if --spec was provided
│   └── <your-spec>.yaml
├── .stackwright/
│   └── otters/               # 🦦 Brand, foreman, page, & theme otters
├── stackwright.yml           # Theme + auth + integrations config
├── next.config.js            # Pro config (transpile pro pkgs + yaml-loader)
├── yaml.d.ts                 # TS declarations for YAML imports
└── package.json              # OSS + Pro dependencies (via scaffold hooks)
```

## CLI Options

```
launch-stackwright-pro [directory]

Options:
  --name <name>        Project name (used in package.json)
  --title <title>      Site title shown in the app bar and browser tab
  --theme <themeId>    Theme ID (e.g., corporate, creative, minimal)
  --force              Overwrite existing directory
  --skip-otters        Skip otter raft setup
  -y, --yes            Skip prompts, use defaults
  --spec <path>        Path to an OpenAPI spec (YAML or JSON)
  --spec-name <name>   Name for the API integration (default: derived from filename)
  -V, --version        Output the version number
  -h, --help           Display help
```

## Role-Based Dev Scripts

The scaffolded project includes convenience scripts for developing against
different mock roles:

```bash
pnpm dev            # No mock auth — unauthenticated
pnpm dev:admin      # MOCK_USER=admin
pnpm dev:analyst    # MOCK_USER=analyst
pnpm dev:viewer     # MOCK_USER=viewer
```

## What's Different from OSS `launch-stackwright`?

| Feature             | OSS | Pro |
| ------------------- | --- | --- |
| Base scaffold       | ✅  | ✅  |
| Otter raft          | ✅  | ✅  |
| RBAC auth           | ❌  | ✅  |
| Mock users          | ❌  | ✅  |
| OpenAPI integration | ❌  | ✅  |
| Prebuild code-gen   | ❌  | ✅  |
| YAML config loading | ❌  | ✅  |

## Scaffold Hooks

The `@stackwright-pro/scaffold-hooks` package handles Pro package injection
automatically via the hooks system:

| Hook                      | What It Does                                             |
| ------------------------- | -------------------------------------------------------- |
| `pro-dependencies`        | Adds `@stackwright-pro/*` packages, fixes workspace refs |
| `pro-mcp-config`          | Configures Pro MCP server in `.code-puppy.json`          |
| `verify-pro-installation` | Prints success message after install                     |

## Docs

See the main [Stackwright Pro documentation](https://github.com/Per-Aspera-LLC/stackwright-pro)
for architecture details, auth deep-dives, and deployment guides.