# vibe-provision

Provision external SaaS services from YAML. One command to set up Clerk, Stripe, Resend and inject `.env`.

> "AI can write code, but it can't click dashboards." — vibe-provision solves that.

## Quick Start

```bash
# 1. Generate a config template
npx vibe-provision init

# 2. Authenticate with providers (one-time)
npx vibe-provision auth

# 3. Provision resources and generate .env
npx vibe-provision up
```

That's it. Your `.env` is ready — run your dev server.

`vp` is a short alias: `npx vp up` works too.

## vibe.yaml

```yaml
project: my-saas-app

output:
  - .env
  - vercel        # auto-inject env vars to Vercel
  - terraform     # generate terraform.tfvars.json

services:
  auth:
    provider: clerk
    config:
      app_name: "My SaaS App"
      redirect_urls:
        - http://localhost:3000/callback

  payments:
    provider: stripe
    config:
      products:
        - name: "Pro Plan"
          prices:
            - amount: 1900
              currency: usd
              interval: month
      webhooks:
        events:
          - checkout.session.completed
          - customer.subscription.updated

  email:
    provider: resend
    config:
      domain: my-app.com

  database:
    provider: neon
    config:
      region: aws-ap-northeast-1

  cache:
    provider: upstash
    config:
      region: ap-northeast-1
```

AI (Cursor, Claude Code, etc.) can generate this file alongside your app code.

## Supported Providers

| Provider | Category | What it creates | Auth method |
|---|---|---|---|
| Clerk | Auth | Redirect URL config + env vars | API key paste |
| Stripe | Payments | Products, Prices, Webhook Endpoints | API key paste |
| Resend | Email | Domain registration | API key paste |
| Supabase | DB + Auth | Project + API keys | Access token |
| Neon | Postgres | Project + database | API key |
| Upstash | Redis | Database | Email + API key |

## Output Targets

Control where env vars are written via the `output` section:

| Target | Description |
|---|---|
| `.env` | Local `.env` file (default) |
| `vercel` | Vercel environment variables via CLI |
| `terraform` | `.vibe-provision/terraform.tfvars.json` with merge semantics |

## Environment-Specific Config

Use `--env` to manage multiple environments:

```bash
npx vp up --env dev      # merges vibe.yaml + vibe.dev.yaml → .env.dev
npx vp up --env staging  # merges vibe.yaml + vibe.staging.yaml → .env.staging
npx vp up --env prod     # merges vibe.yaml + vibe.prod.yaml → .env.prod
npx vp up                # uses vibe.yaml only → .env
```

**Base config** (`vibe.yaml`) holds shared settings. **Override files** (`vibe.{env}.yaml`) deep-merge on top:

```yaml
# vibe.dev.yaml — only override what differs
services:
  payments:
    provider: stripe
    config:
      webhooks:
        url: https://dev.example.com/api/webhooks/stripe
```

## MCP Server (AI Agent Integration)

vibe-provision includes an MCP server so AI agents (Claude Code, Cursor) can provision services directly.

### Setup

Add to your `.mcp.json` (global or per-project):

```json
{
  "mcpServers": {
    "vibe-provision": {
      "command": "npx",
      "args": ["vibe-provision", "mcp"]
    }
  }
}
```

### Available Tools

| Tool | Description |
|---|---|
| `vibe_provision_status` | Check auth and provisioning state for all providers |
| `vibe_provision_up` | Provision resources and generate .env (requires prior auth) |
| `vibe_provision_add` | Add a new service to vibe.yaml |

### Example Flow

```
User: "Add Stripe payments to my app"
  → AI generates vibe.yaml with stripe config
  → AI calls vibe_provision_status → "stripe: NOT authenticated"
  → AI: "Run npx vp auth in your terminal"
  → User authenticates (one-time)
  → AI calls vibe_provision_up → Products, Prices, Webhooks created
  → .env updated, app ready to run
```

## Idempotency

`vibe-provision up` is safe to run multiple times. It tracks created resources in `.vibe-provision/state.json` and skips anything that already exists.

## How It Works

1. **`init`** — generates a `vibe.yaml` template
2. **`auth`** — walks you through authenticating each provider, stores credentials locally in `~/.vibe-provision/auth/`
3. **`up`** — reads `vibe.yaml`, calls provider APIs to create resources, writes to configured output targets

Credentials never leave your machine.

## Examples

- **[saas-starter-simple](./examples/saas-starter-simple/)** — Next.js + Clerk + Stripe + Resend, direct webhook handling
- **[saas-starter](./examples/saas-starter/)** — Same stack + [qhook](https://github.com/totte-dev/qhook) for production webhook processing

## Development

```bash
npm install
npm run lint          # type check
npm test              # run tests (47 tests)
npm run dev -- init   # run CLI in dev mode
```

## License

[FSL-1.1-Apache-2.0](./LICENSE) — Free to use for any purpose except competing hosted services. Converts to Apache 2.0 on 2028-03-26.