@nebulr-group/bridge-cli 0.1.3 → 0.4.0-beta.0

package/dist/prompts/auth-master-integration-prompt.md

@@ -0,0 +1,251 @@
+# Bridge Auth — Master Integration Prompt
+
+You are integrating **Bridge Authentication** (auth, tenant management, RBAC) into a user's application. Your job is to detect the project structure, identify the technologies, and apply the right per-framework integration for each.
+
+This prompt is framework-agnostic. It orchestrates discovery, confirmation, and verification — the actual install commands, file shapes, and code snippets live in the per-framework guides fetched in Step 4.
+
+> **Related master prompts** — if the user asked for flags or billing specifically (not auth), stop here and route them:
+> - Feature Flags 2.0 only → `bridge guide flags`
+> - Billing 2.0 only → `bridge guide billing`
+>
+> If they want auth + flags + billing wired together, run this prompt first, then chain `bridge guide flags` and `bridge guide billing` at the end (or whichever subset they want).
+
+## Step 0 — Authenticate
+
+Run `bridge auth login` and wait for it to print "Logged in as <email>". Once it exits, proceed to Step 1.
+
+---
+
+**At the end of this integration you will output a success message that looks like this:**
+
+```
+   ██████╗ ██████╗ ██╗██████╗  ██████╗ ███████╗
+   ██╔══██╗██╔══██╗██║██╔══██╗██╔════╝ ██╔════╝
+   ██████╔╝██████╔╝██║██║  ██║██║  ███╗█████╗
+   ██╔══██╗██╔══██╗██║██║  ██║██║   ██║██╔══╝
+   ██████╔╝██║  ██║██║██████╔╝╚██████╔╝███████╗
+   ╚═════╝ ╚═╝  ╚═╝╚═╝╚═════╝  ╚═════╝ ╚══════╝
+
+  ──────────────────────────────────────────────
+   Congratulations — [project-name] now has superpowers.
+   ...
+    ✅  You know who's calling
+        [token-description]
+   ...
+  ──────────────────────────────────────────────
+    Here is what I actually did:
+    [what-i-actually-did]
+
+    And here is what I changed:
+    [what-i-changed]
+  ──────────────────────────────────────────────
+```
+
+As you work through the steps below, track the following so you have it ready:
+- **`[project-name]`** — folder name and/or `package.json` name for each project integrated
+- **`[token-description]`** — the identifiers the developer uses to access the authenticated user in their framework (e.g. stores for Svelte, hooks for React, decorators for NestJS)
+- **`[what-i-actually-did]`** — high-level outcomes: what works now that didn't before
+- **`[what-i-changed]`** — every package installed, file created or modified, and URL configured, with exact values
+
+## Step 1 — Discover projects
+
+Scan the current directory and its immediate subdirectories for `package.json` files. For each one:
+
+1. **Detect the package manager** — check for lock files in this order:
+   - `bun.lock` or `bun.lockb` → use `bun`
+   - `pnpm-lock.yaml` → use `pnpm`
+   - `yarn.lock` → use `yarn`
+   - `package-lock.json` or none → use `npm`
+
+2. **Detect frontend framework** (from `dependencies` + `devDependencies`):
+   - `svelte` or `@sveltejs/kit` → **SvelteKit**
+   - `react` + `next` → **Next.js**
+   - `react` (without next) → **React**
+   - `@angular/core` → **Angular**
+
+3. **Detect backend framework** (from `dependencies`):
+   - `@nestjs/core` → **NestJS**
+   - `express` (without @nestjs/core) → **Express**
+
+4. **Detect existing auth** (from `dependencies` + `devDependencies`):
+   - `@nebulr/nblocks-svelte`, `@nebulr/nblocks-react`, etc. → **nblocks (predecessor to Bridge — migration needed)**
+   - `@nebulr-group/bridge-svelte`, `@nebulr-group/bridge-react`, `@nebulr-group/bridge-nestjs`, etc. → **Bridge already installed — check if wiring is complete (see Step 1b)**
+   - `next-auth`, `@auth0/*`, `@clerk/*`, `lucia`, `passport` → **third-party auth present — warn user**
+
+5. **Record for each project:**
+   - Path (relative to working directory)
+   - Type: `frontend` or `backend`
+   - Framework + version
+   - Package manager
+   - Existing auth (if any)
+
+## Step 1b — Check if Bridge is already integrated
+
+If Step 1 detected a Bridge plugin (`@nebulr-group/bridge-<framework>`) in `dependencies`, the integration may already be partially or fully complete. Don't guess from the dependency alone — audit the wiring.
+
+**Delegate the audit to the per-framework guide.** Each plugin's guide ships an "Integration audit" section that lists the exact files / providers / route shapes the framework requires. Run:
+
+```
+bridge guide <framework>              # hosted-auth audit checklist
+bridge guide <framework> sdk-auth     # SDK-auth audit checklist (in-app forms)
+```
+
+The framework guide tells you precisely what must exist (bootstrap call, provider wrapping, callback routes, environment variables). Apply that checklist to the project on disk.
+
+**General decision matrix** (independent of framework):
+
+- **Wiring complete AND all required auth routes present** → Bridge is fully integrated. Skip to **Step 6b** and output the success message.
+- **Bootstrap wiring complete BUT auth routes missing** → Bridge is partially integrated. The missing routes silently break signup verification, password reset, or SSO callback. Tell the user explicitly which files are missing (the framework guide lists them by name). Add only what's missing — do not regenerate existing routes.
+- **Bootstrap wiring incomplete** (regardless of route state) → Offer to complete the initial setup (proceed to Step 4).
+- **Bridge is NOT installed** → Continue with Steps 2–6 for fresh setup.
+
+When you find missing pieces, list each one explicitly to the user — they need to know what's broken and why (e.g., "the signup verification email route is missing — every new signup is currently hitting a 404 after clicking the verification link").
+
+## Step 2 — Present findings and confirm
+
+Show the user what you found. Example:
+
+```
+I detected the following projects:
+
+1. ./my-app-ui — SvelteKit 5 (frontend, bun)
+   Existing auth: @nebulr/nblocks-svelte (will migrate to Bridge)
+
+2. ./my-app-api — NestJS 11 (backend, bun)
+   No existing auth detected
+
+Which projects should I integrate? (all / select by number)
+```
+
+Wait for confirmation before proceeding. If the user selects specific projects, only integrate those.
+
+**Auth approach (frontend projects only):**
+
+After confirming which projects to integrate, ask about the auth approach:
+
+```
+Which auth approach do you want for the frontend?
+
+- Hosted (default) — Bridge handles the login page. Fastest setup, zero UI to build.
+- SDK — In-app login/signup forms. Full control over the auth UX.
+```
+
+Note the user's choice. It determines which guide to fetch in Step 4:
+- **Hosted** → `bridge guide <framework>` (default)
+- **SDK** → `bridge guide <framework> sdk-auth`
+
+## Step 3 — Get Bridge app context
+
+Run these commands to get the app configuration:
+
+```bash
+bridge app get
+bridge info auth-config
+```
+
+Extract and note:
+- `appId` — needed by both frontend and backend
+- Enabled auth methods (password, magic link, SSO providers, passkeys, MFA)
+- App URLs (apiUrl, uiUrl, callbackUrl)
+
+If `bridge` CLI is not available or not configured, ask the user for the `appId` directly. They can find it in the Bridge dashboard.
+
+## Step 3b — Configure the Bridge app for the frontend
+
+Detect the frontend URL from dev scripts in `package.json` (e.g., `--port 3000`, `--port 5173`). **Show the detected URL to the user and ask for confirmation before proceeding.** Then configure the Bridge app so it accepts OAuth callbacks and CORS requests from the frontend:
+
+```bash
+bridge app update \
+  --ui-url <frontend-url> \
+  --default-callback-uri <frontend-url>/auth/oauth-callback \
+  --redirect-uris <frontend-url>/auth/oauth-callback \
+  --allowed-origins <frontend-url>
+```
+
+If the hosted cloud-views UI is on a different origin (e.g., `http://localhost:3091` in local dev, `https://app.thebridge.dev` in prod), add it to `--allowed-origins` as well:
+
+```bash
+bridge app update --allowed-origins <frontend-url>,<hosted-url>
+```
+
+Without this, the Bridge API will reject the OAuth redirect (invalid redirect_uri) and block CORS requests from the frontend (origin not allowed).
+
+## Step 4 — Fetch and apply per-framework guides
+
+For each confirmed project, fetch the framework-specific integration prompt.
+
+**Frontend projects** — use the auth approach chosen in Step 2:
+
+| Framework | Hosted (default) | SDK |
+|-----------|-------------------|-----|
+| SvelteKit | `bridge guide svelte` | `bridge guide svelte sdk-auth` |
+| React | `bridge guide react` | `bridge guide react sdk-auth` |
+| Next.js | `bridge guide nextjs` | `bridge guide nextjs sdk-auth` |
+| Angular | `bridge guide angular` | `bridge guide angular sdk-auth` |
+
+**Backend projects:**
+
+| Framework | Command |
+|-----------|---------|
+| NestJS | `bridge guide nestjs` |
+| Express | `bridge guide express` |
+
+Follow the per-framework guide instructions verbatim. Pass these values from Step 3:
+- `appId` — same for all projects
+- `packageManager` — detected in Step 1 (use it for all install commands)
+
+**Order:** Frontend first, then backend. This lets you verify login works before adding backend guards.
+
+## Step 5 — Route protection defaults
+
+When setting up route protection, apply these sensible defaults:
+
+**Frontend:**
+- `defaultAccess: 'protected'` — everything requires login by default
+- Mark as public: auth routes only (`/auth/*`) — the OAuth callback must be accessible
+- Do NOT make other routes public by default. The user can relax this later for specific pages
+
+**Backend:**
+- `guard.global: true` with `defaultAccess: 'protected'`
+- Mark as public: health check endpoints, public read-only APIs
+- Use the framework's current-user accessor on endpoints that need user identity (the per-framework guide names it: `@CurrentUser()` for NestJS, `req.user` for Express, etc.)
+
+Tell the user: "I've set up default route protection. You can refine which routes are public or protected using the Bridge CLI (`bridge role list`, `bridge flag list`) or by editing the route config directly."
+
+## Step 6 — Verify
+
+For each integrated project:
+
+1. **Build check** — run the project's build command (from `package.json` scripts)
+2. **Config check** — confirm the `appId` environment variable is set
+3. **Route check** — confirm protected routes have guards and public routes are accessible
+
+If anything fails, diagnose and fix before moving on. Once the checks pass, move on to the summary in Step 6b — do NOT just dump a list of changed files at the user.
+
+## Step 6b — Tell the developer what they just got
+
+Run `bridge guide integration-success` to fetch the success message template, then output it personalised for this project.
+
+**Substitutions (always apply):**
+
+- `[project-name]` → the `name` field from the project's `package.json`
+- `[bridge-plugin]` → the installed Bridge plugin (e.g. `bridge-svelte`, `bridge-react`, `bridge-nestjs`)
+- `[dev-url]` → the frontend dev server URL detected in Step 3b (e.g. `http://localhost:5173`)
+
+**Personalisation rules:**
+
+- Fill in every `[placeholder]` using the substitution guide at the bottom of the template. For `[what-i-actually-did]` and `[what-i-changed]`, draw from what you actually observed and changed during Steps 1–6 — the examples in the guide are illustrative only. Strip the `AGENT SUBSTITUTION GUIDE` section before outputting — it must never be shown to the developer.
+- If both a frontend and a backend were integrated, group the bottom two sections by project rather than merging them into a flat list.
+- **DO NOT write any text before the banner.** The very first character of your response must be the first character of the ASCII art. No "Perfect!", no "Here's your success message:", no transition sentence, no acknowledgement — nothing. Start with the `█` character. If you find yourself typing an intro, stop and delete it.
+- **If the build is broken** or auth doesn't actually work end-to-end, prepend a single "Heads up:" line before the banner. Never bury bad news under it.
+
+After delivering the message, the integration is complete.
+
+## Step 7 — Offer follow-on tracks
+
+After auth is wired and the success banner is printed, the developer commonly wants flags and billing next. Mention these one-liners so they know how to continue:
+
+- **Feature Flags 2.0** → `bridge guide flags` (auto-detects framework, sets up flag evaluation, telemetry, realtime)
+- **Billing 2.0** → `bridge guide billing` (subscriptions, plan selector, quota banners, webhook receiver)
+
+Do not run them automatically — the developer decides when they want each track.

package/dist/prompts/billing/master.md

@@ -0,0 +1,269 @@
+# Billing 2.0 — Master Integration Prompt
+
+You are integrating **Bridge Billing** into a user's application — plan selection, Stripe Checkout, subscription state, lifecycle notices (trial / dunning / cancel), and usage quota counters.
+
+This prompt is framework-agnostic. It orchestrates discovery, pricing model setup, and verification — the actual install commands and code snippets live in the per-framework guides fetched in Step 4.
+
+> **Related master prompts** — if the user hasn't set up auth yet, stop here and route them:
+> - Auth first → `bridge guide`
+>
+> If they want auth + billing wired together, run `bridge guide` first, then come back here.
+
+## Step 0 — Authenticate
+
+Run `bridge auth login` and wait for it to print "Logged in as <email>". Once it exits, proceed to Step 1.
+
+## Step 1 — Discover projects
+
+Scan the current directory and its immediate subdirectories for `package.json` files. For each one:
+
+1. **Package manager** — from lock file (`bun.lock` → `bun`, `pnpm-lock.yaml` → `pnpm`, `yarn.lock` → `yarn`, `package-lock.json` → `npm`)
+
+2. **Framework** — from `dependencies` + `devDependencies`:
+   - `svelte` or `@sveltejs/kit` → **SvelteKit**
+   - `react` + `next` → **Next.js**
+   - `react` (without next) → **React**
+   - `@angular/core` → **Angular**
+   - `@nestjs/core` → **NestJS**
+   - `express` (without `@nestjs/core`) → **Express**
+
+3. **Bridge Auth installed?** — look for `@nebulr-group/bridge-<framework>` in dependencies. Billing is scoped to a workspace/tenant and requires Bridge Auth. If not present, stop and run `bridge guide` first.
+
+4. **Billing already wired?** — check whether a subscription/plan route exists (typically `/subscription` or `/plan`) and whether `bridge plan list` returns at least one plan. If billing looks complete, jump to **Step 1b**.
+
+5. **Existing billing system?** — look for `stripe`, `@stripe/*`, `paddle-*`, `lemon-squeezy`, `chargebee`. Flag any found.
+
+## Step 1b — Audit existing billing wiring
+
+If Step 1 found billing already partially or fully set up, audit it before doing anything:
+
+- Run `bridge plan list` — are plans defined?
+- Check for a subscription route with `<PlanSelector>` mounted
+- Check the root layout for `<BridgeBillingNotice />`
+
+**Decision:**
+- **Fully wired** (plans exist, selector mounted, notice in layout) → skip to **Step 6** and output the success message
+- **Partially wired** → tell the user exactly what's missing and only add what's absent
+- **Plans missing** → continue from Step 3 (pricing model)
+
+## Step 2 — Present findings and confirm
+
+Show the user what you found:
+
+```
+I detected the following projects:
+
+1. ./my-app — SvelteKit 5 (frontend, bun)
+   Bridge Auth: ✅ installed
+   Billing: not yet wired
+   Existing billing system: none
+
+Which projects should I wire billing into? (all / select by number)
+```
+
+Wait for confirmation before proceeding.
+
+## Step 3 — Understand the pricing model
+
+Ask the developer to describe their pricing in plain language:
+
+> "Describe your plans — names, prices, and what each plan includes or limits. For example: 'Free plan with 100 AI completions per month. Pro at $29/month with 1000 completions and advanced analytics. 14-day free trial on Pro.'"
+
+From their answer, map everything to confirmation tables before creating anything.
+
+**Plans:**
+
+| key | name | trial |
+|-----|------|-------|
+| `free` | Free | — |
+| `pro` | Pro | 14d |
+
+**Prices** (a plan can have several — one per currency + interval):
+
+| plan | amount | currency | interval |
+|------|--------|----------|----------|
+| `pro` | 29 | USD | month |
+| `pro` | 290 | USD | year |
+
+> **A single plan can carry both a monthly and a yearly price.** When the
+> developer gives two intervals for one tier (e.g. "$29/month or $290/year"),
+> that is **ONE plan with two prices** — never separate `pro-monthly` /
+> `pro-yearly` plans. A free plan simply has no price rows.
+
+**Quotas** (per-resource limits that differ between plans):
+
+| plan | metric | limit | policy |
+|------|--------|-------|--------|
+| `free` | `ai_completions` | 100 | hard |
+| `pro` | `ai_completions` | 1000 | hard |
+
+Use `hard` when overage should be blocked. Use `metered` when overage should bill via Stripe.
+
+**Entitlements** (features on for some plans, off for others):
+
+| plan | key | value |
+|------|-----|-------|
+| `free` | `advanced_analytics` | off |
+| `pro` | `advanced_analytics` | on |
+
+If there are no per-plan limits or feature differences, the quotas and entitlements tables are empty — skip those commands below.
+
+**Do not create anything until the developer confirms all tables.**
+
+## Step 3b — Create plans, connect Stripe, then set prices
+
+Once confirmed, create the plans (no prices here — `plan create` never takes a price):
+
+```bash
+bridge plan create --key free --name "Free"
+bridge plan create --key pro --name "Pro" --trial --trial-days 14
+```
+
+Verify: `bridge plan list`
+
+If any plan will have a price, connect Stripe **before** setting prices (so each price syncs to Stripe):
+
+```bash
+bridge stripe status
+```
+
+If not connected, ask the developer for their Stripe keys (from `dashboard.stripe.com/apikeys`):
+
+```bash
+bridge stripe connect --secret-key sk_test_... --publishable-key pk_test_...
+```
+
+Now set prices — **one command per Prices-table row**. `plan price set` is idempotent
+(keyed on currency + interval), so a tier with monthly **and** yearly pricing is just two
+calls against the same plan key:
+
+```bash
+bridge plan price set pro --amount 29 --currency usd --interval month
+bridge plan price set pro --amount 290 --currency usd --interval year
+```
+
+Then create quotas and entitlements from the confirmed tables:
+
+```bash
+bridge plan quota set <plan> --metric <key> --limit <n> --policy <hard|metered>
+bridge plan entitlement set <plan> --key <key> --value <true|false>
+```
+
+Run one command per row.
+
+## Step 4 — Fetch and apply the per-framework guide
+
+The per-framework prompts are **not** bundled in the CLI — each plugin ships its own at
+`mcp/billing-prompt.md`, which the commands below fetch. For each confirmed project, fetch the
+framework-specific guide and follow it verbatim:
+
+| Framework | Command |
+|-----------|---------|
+| SvelteKit | `bridge guide billing --framework svelte` |
+| React | `bridge guide billing --framework react` |
+| Next.js | `bridge guide billing --framework nextjs` |
+| Angular | `bridge guide billing --framework angular` |
+| NestJS | `bridge guide billing --framework nestjs` |
+| Express | `bridge guide billing --framework express` |
+
+If the CLI returns a 404, the plugin hasn't published its billing guide yet — tell the user, don't improvise inline.
+
+Wire frontend first, then backend.
+
+**When the per-framework guide is complete, do not stop — return here and continue with Step 4b.**
+
+## Step 4b — Plan-selection paywall (on by default)
+
+By default, a signed-in tenant that hasn't chosen a plan is redirected to a dedicated
+welcome page and can't use the app until they pick one. **Set this up unless the developer
+opts out** — it's the expected first-run experience.
+
+- The per-framework guide (Step 4) creates a welcome route that renders `<PlanSelector>`
+  and registers it as `billing.paywallRoute`. Confirm that part ran.
+- The app-level flag `paymentsAutoRedirect` drives the redirect and is **`true` by
+  default** — there is nothing to switch on.
+
+If the developer does **not** want a forced paywall, disable it with one command:
+
+```bash
+bridge app update --payments-auto-redirect false
+```
+
+With the paywall off, users can enter the app without choosing a plan; any `<PlanSelector>`
+or `/subscription` route you mounted still works for self-serve upgrades.
+
+## Step 5 — Verify
+
+For each integrated project, the agent verifies — do not hand this to the developer:
+
+1. Run the project's build command — no TypeScript or import errors
+2. Navigate to the subscription route — plan cards render with correct prices, and a tier with monthly + yearly pricing shows both intervals (not two separate plans)
+3. Select the free plan — subscription updates immediately, no redirect
+4. Select a paid plan — Stripe Checkout opens
+5. Complete a test payment — redirected back with the updated plan showing
+6. Cancel a payment — redirected back to the subscription page
+7. Paywall (unless opted out): sign in as a new tenant with no plan — you land on the welcome route and can't reach the app until a plan is chosen
+
+If anything fails, diagnose and fix before moving on.
+
+## Step 6 — Tell the developer what they just got
+
+**Do not skip this step.** Output the banner below, personalised. The very first character of your response must be `█` — no intro sentence, no "Here's your summary:", nothing before it. If something is broken, prepend a single "Heads up:" line before the `█`.
+
+```
+   ██████╗ ██████╗ ██╗██████╗  ██████╗ ███████╗
+   ██╔══██╗██╔══██╗██║██╔══██╗██╔════╝ ██╔════╝
+   ██████╔╝██████╔╝██║██║  ██║██║  ███╗█████╗
+   ██╔══██╗██╔══██╗██║██║  ██║██║   ██║██╔══╝
+   ██████╔╝██║  ██║██║██████╔╝╚██████╔╝███████╗
+   ╚═════╝ ╚═╝  ╚═╝╚═╝╚═════╝  ╚═════╝ ╚══════╝
+
+  ──────────────────────────────────────────────
+   Billing is live in [project-name].
+
+    ✅  Plans — [plan-names]
+    ✅  Plan selector — [plan-selector-route]
+    ✅  Paywall — [paywall-summary]
+    ✅  Lifecycle notices — auto-render on trial / payment failure / cancel
+    ✅  Quotas and entitlements — [quota-summary]
+  ──────────────────────────────────────────────
+    Here is what I actually did:
+    [what-i-actually-did]
+
+    And here is what I changed:
+    [what-i-changed]
+  ──────────────────────────────────────────────
+    Plan selection is required by default. To let users into the app without
+    picking a plan first, disable the paywall:
+      bridge app update --payments-auto-redirect false
+  ──────────────────────────────────────────────
+```
+
+Fill every `[placeholder]` with real values from the integration:
+- `[project-name]` — folder name and/or `package.json` name
+- `[plan-names]` — the plan keys (e.g. `free`, `premium`)
+- `[plan-selector-route]` — route where `<PlanSelector>` is mounted
+- `[paywall-summary]` — e.g. "new users sent to `/welcome` to pick a plan" (or "off — `paymentsAutoRedirect false`")
+- `[quota-summary]` — metric keys and limits, or "none"
+- `[what-i-actually-did]` / `[what-i-changed]` — every file created or modified, every command run
+
+## Step 7 — Offer follow-on tracks
+
+After the success banner, mention what they can add next:
+
+- **Webhook receiver** — receive subscription and quota events on your backend: `bridge guide billing --framework <name>`
+- **Usage ingestion** — report usage from your backend: same guide, backend section
+- **Portal** — let users manage their payment method or cancel: covered in the per-framework guide
+
+Do not run these automatically — the developer decides when they want each.
+
+---
+
+## Reference — enforcement policies
+
+| Policy | At-cap behavior | When to use |
+|--------|-----------------|-------------|
+| `hard` | Entitlement flips off at cap; no overage | Seat counts, included features |
+| `metered` | Overage bills as a Stripe metered price; usage continues | API calls, storage |
+
+The server always accepts `/usage/ingest` — hard policy means no metered price + entitlement gate, not server-side rejection.