@nebulr-group/bridge-cli 0.6.5 → 1.0.0-alpha.0

package/dist/prompts/mechanisms.md

@@ -1,298 +0,0 @@
-# How Bridge works — the mechanisms and the levels
-
-One page for the rules every Bridge guide builds on. Read it before you write code against a limit, an upgrade prompt or a restyled sign-in page. The per-framework guides (`bridge guide svelte`, `bridge guide nestjs`, …) say *which file*; this page says *why it works* and *which level to pick*.
-
-Who gets which feature, and how plans, roles, limits and flags divide the work, is on its own page: `bridge guide fit-together` (MCP: resource `bridge://guides/fit-together`).
-
-The examples use the SvelteKit frontend (`@nebulr-group/bridge-svelte`) and the NestJS backend (`@nebulr-group/bridge-nestjs`). The other plugins carry the same surface in their own idiom: React and Next.js serve the pages with `<BridgeAuthRoutes>` and `<BridgeBillingRoutes>`, Angular with `...bridgeAuthRoutes()` and `...bridgeBillingRoutes()`, and Express answers limits with `bridge.requireQuota('exports')` and `bridge.syncQuota('tickets', { current })` (plus `bridge.requireEntitlement` for the one documented exception) — the same `402` / `403` bodies as the NestJS decorators. `bridge guide <framework>` has each one's files.
-
-## The whole integration
-
-What a developer's repo holds once Bridge is in. Nothing else is required; every other page Bridge needs, it serves.
-
-**Frontend (SvelteKit) — 15 lines in four files, plus one line of `.env`:**
-
-```env
-# .env
-VITE_BRIDGE_APP_ID=your-app-id
-```
-
-```ts
-// src/routes/+layout.ts
-import { bridgeBootstrap } from '@nebulr-group/bridge-svelte';
-export const ssr = false;
-export const load = bridgeBootstrap({ rules: [{ match: new RegExp('^/auth($|/)'), public: true }] });
-```
-
-```svelte
-<!-- src/routes/+layout.svelte -->
-<script lang="ts">
-  import { BridgeBootstrap } from '@nebulr-group/bridge-svelte';
-  import '@nebulr-group/bridge-svelte/styles';
-  let { children } = $props();
-</script>
-<BridgeBootstrap>
-  {@render children()}
-</BridgeBootstrap>
-```
-
-```svelte
-<!-- src/routes/auth/[...bridge]/+page.svelte — every sign-in page -->
-<script lang="ts">
-  import { BridgeAuthRoutes } from '@nebulr-group/bridge-svelte';
-</script>
-<BridgeAuthRoutes />
-```
-
-With plans, one more four-line file serves the subscription page, the paywall and both checkout return pages:
-
-```svelte
-<!-- src/routes/subscription/[...bridge]/+page.svelte -->
-<script lang="ts">
-  import { BridgeBillingRoutes } from '@nebulr-group/bridge-svelte';
-</script>
-<BridgeBillingRoutes />
-```
-
-**Backend (NestJS) — 4 lines, plus one line of environment.** The lines marked `// +` are Bridge's; the rest is what `nest new` already gave you:
-
-```env
-# .env
-BRIDGE_APP_ID=your-app-id
-```
-
-```ts
-// src/app.module.ts
-import { Module } from '@nestjs/common';
-import { BridgeModule } from '@nebulr-group/bridge-nestjs';                  // +
-import { ExportsController } from './exports.controller';
-
-@Module({
-  imports: [BridgeModule.forRoot({ guard: { global: true } })],            // + every route needs a signed-in user
-  controllers: [ExportsController],
-})
-export class AppModule {}
-```
-
-```ts
-// src/exports.controller.ts
-import { Controller, Post } from '@nestjs/common';
-import { RequireQuota } from '@nebulr-group/bridge-nestjs';                  // +
-
-@Controller('exports')
-export class ExportsController {
-  @Post()
-  @RequireQuota('exports')                                                  // + the plan limit
-  create() {
-    return { exported: true };
-  }
-}
-```
-
-`BRIDGE_APP_ID` must be in the process environment. NestJS does not read `.env` by itself: start with `node --env-file=.env dist/main.js`, or set it in your container or process manager.
-
-**Settings are read for you.** Each field resolves as *explicit option > environment > default*; an empty value counts as unset.
-
-| Frontend | Backend | When to set it |
-|---|---|---|
-| `VITE_BRIDGE_APP_ID` | `BRIDGE_APP_ID` | Always. Missing, Bridge refuses to start and names the variable |
-| `VITE_BRIDGE_API_BASE_URL` | `BRIDGE_API_BASE_URL` | Only for a non-production app (stage, local, self-hosted). Unset means production |
-| `VITE_BRIDGE_HOSTED_URL` | — | Only for a local or self-hosted Bridge. On Bridge's own domains it follows the API address (`api-stage` → `auth-stage`) |
-| `VITE_BRIDGE_DEBUG` | `BRIDGE_DEBUG` | `true` for console logging |
-
-## 1. Decide once, where the action happens
-
-Ask the developer first: **does this action call your server?**
-
-- **It calls your backend:** the backend handler counts it and refuses at the limit, because that is where the action happens. The frontend shows the count and the upgrade dialog, and does not count the same metric again.
-- **It happens in the browser** and never reaches a server of yours (local-first, data on the device): the browser counts it and gates the button (section 5). That is a first-class setup.
-
-Never both for one metric: it would be counted twice.
-
-## 2. A POST increments the limit
-
-The backend decorator **is** the increment. There is nothing else to wire: no "report usage" call after the insert, no counter in your database, no endpoint for the frontend.
-
-```ts
-@Post()
-@RequireQuota('exports')
-create() { /* your code */ }
-```
-
-- **Before the handler:** at the plan's limit the request is refused with `402` and a body the frontend understands (`{ code: 'QUOTA_EXCEEDED', metric, used, limit, fix }`). Your handler never runs.
-- **After the handler:** only when it answered **2xx**, Bridge records the use — exactly one write. A handler that throws or answers 4xx/5xx records nothing.
-- **Retries:** a request that sends an `Idempotency-Key` header is counted once per key, however often the client retries.
-- **Fail-closed:** if Bridge cannot answer, the request is refused with `503`, never let through unchecked.
-- A `metered` quota never refuses: past its allowance it bills per unit.
-
-## 3. Counter or gauge
-
-**If deleting it frees room, it's a gauge and your app counts it; if it happened, it's a counter and Bridge counts it.**
-
-| | Counter | Gauge |
-|---|---|---|
-| Examples | exports, API calls, AI completions, emails sent | tickets, projects, stored files, seats |
-| Who counts | Bridge, one event per successful request | Your app — you pass your own count |
-| Resets | every billing period ("40 of 100 this month") | never ("8 of 10 projects") |
-| Configure | `bridge plan quota set <plan> --metric exports --limit 100 --policy hard` (counter is the default) | `bridge plan quota set <plan> --metric tickets --limit 10 --policy hard --kind gauge` |
-| Backend | `@RequireQuota('exports')` | `@RequireQuota('tickets', { current })` on create, `@SyncQuota('tickets', { current })` on delete |
-
-```ts
-@Post()
-@RequireQuota('tickets', { current: (t, self: TicketsController) => self.tickets.countFor(t.id) })
-create() { /* … */ }
-
-@Delete(':id')
-@SyncQuota('tickets', { current: (t, self: TicketsController) => self.tickets.countFor(t.id) })
-remove() { /* … */ }
-```
-
-`current` returns your own count, and that count is what the limit is compared against, so Bridge's copy heals itself if it ever missed an update. There is no decrement and no reservation: every create and delete sends the whole count.
-
-**Seats** are a gauge the app names (e.g. `seats`) and marks as counted from membership: `bridge plan quota set <plan> --metric seats --limit 10 --policy hard --kind gauge --source membership`. Bridge answers it with the workspace's active members, pending invites included, read fresh each time; the app never reports it. Check it where invites happen: on the built-in team page with `<TeamManagementPanel seatsMetric="seats" />`, or with `@RequireQuota('seats')` on your own invite handler (it checks and writes nothing). Bridge's invite API does not refuse at the limit by itself. Never gate seats with a flag or an entitlement.
-
-`bridge plan quota list` shows every metric the app's plans limit, with its kind.
-
-**Every hard quota is also an entitlement** with the same name, true while there is room. So never pair `@RequireEntitlement('exports')` with `@RequireQuota('exports')`: at the cap the entitlement answers `403` before the quota can answer the `402` the frontend knows how to upsell. `@RequireQuota` is for a *limit*; `@RequireEntitlement` checks a plan *feature* (`analytics`, `sso`) without a flag, which is the exception (next paragraph).
-
-**A plan feature goes in the plan's features list.** `bridge plan feature add pro analytics --name "Analytics"` makes `analytics` true on `pro`, and false on every other plan. The pricing table and the upgrade dialog name it from the same list. Control the feature with a flag whose rule is `bridge:billing.entitlement.analytics eq true`, so changing what Pro sells is one edit on the plan and no flag rule has to follow. Checking it directly, without a flag, is the exception (section Exceptions, at the end). A hard quota with limit 1 that nothing counts still works the same way; it is the older way to do this. `app_active` is always there: true while the workspace's subscription is active, trialing, past due or cancelling at period end.
-
-## 4. Three ways to handle a limit in the UI
-
-Pick the lowest level that does the job. Each is optional; level 0 is on without code.
-
-| Level | What the page writes | What the user sees |
-|---|---|---|
-| **0 — nothing** | a plain button calling your API | Your backend refuses at the cap (`402`), and `<BridgeBootstrap>` opens an **upgrade dialog** naming the metric, linking to the subscription page. A workspace member who cannot manage billing is told to ask the owner instead |
-| **1 — one component** | `<QuotaGate metric="tickets">…</QuotaGate>` around the button; `<FeatureFlag key="analytics" upgrade>…</FeatureFlag>` around a paid feature | The button is disabled at a known hard cap with an upgrade line beside it; the paid feature shows on a plan that includes it, and elsewhere an "Upgrade to use this" button that opens the dialog when clicked |
-| **2 — your own UI** | `useQuota('tickets')`, and `<FeatureFlag key="analytics">` around what the plan sells | Whatever you build from the live numbers |
-
-```svelte
-<script lang="ts">
-  import { QuotaGate, FeatureFlag, useQuota } from '@nebulr-group/bridge-svelte';
-  const tickets = useQuota('tickets');
-</script>
-
-<!-- level 1 -->
-<QuotaGate metric="tickets">
-  <button onclick={createTicket}>New ticket</button>
-</QuotaGate>
-
-<!-- the flag's rule: bridge:billing.entitlement.analytics eq true -->
-<FeatureFlag key="analytics" defaultValue={false} upgrade>
-  <a href="/analytics">Analytics</a>
-</FeatureFlag>
-
-<!-- level 2 -->
-{#if tickets.loading}
-  Loading…
-{:else if tickets.unlimited}
-  Unlimited tickets
-{:else}
-  {tickets.used} of {tickets.limit} tickets
-{/if}
-```
-
-- No upgrade dialog opens by itself: it opens on a `402` from your backend, when someone opens a route whose flag is off because of the plan, or when they click an upgrade prompt. A page that only renders a hidden feature opens nothing.
-- "Not loaded yet" is never "zero" and never "not allowed": `useQuota` numbers stay `null` while `loading`, `<QuotaGate>` stays enabled while loading, and `<Entitled>` renders nothing (or its `loading` snippet) until `$entitlements.ready`.
-- The dialog catches a `402 QUOTA_EXCEEDED` from the page's own origin, from Bridge, and from any call made with `bridgeFetch()`; a backend on another origin is listed in `billing.apiOrigins`. `billing: { upgradeDialog: false }` turns it off, `billing: { upgradeDialog: MyDialog }` replaces it.
-- Do not write a quota `if`, a "limit reached" toast or a `/quota` endpoint of your own: level 0 already covers the refusal, and the frontend reads quota directly from Bridge.
-
-## 5. Counting in the browser
-
-When the action happens in the browser and never reaches a server of yours — local-first, mobile, data on the device — the frontend counts it:
-
-```ts
-import { bridge } from '@nebulr-group/bridge-svelte';
-
-bridge.usage.report('exports');                        // a counter: it happened
-await bridge.usage.set('projects', projects.length);   // a gauge: how many exist now
-```
-
-Put `<QuotaGate metric="exports">` around the button (section 4, level 1) so it stops at the limit, and the upgrade line sells the next plan.
-
-This is a complete, first-class way to run limits. When the action does call your backend, count it there instead (section 2), never in both places.
-
-## 6. Four levels of customising Bridge's pages
-
-The same ladder holds for the sign-in pages (`<BridgeAuthRoutes>`) and the subscription pages (`<BridgeBillingRoutes>`). The pages must end up looking like the app they sit in: rung 1, with the tokens taken from the app's own styles, is always applied, and rung 2 too when the app frames its pages in a card or shell. Climb further only as far as you need.
-
-| Rung | What you do | What you own |
-|---|---|---|
-| **0 — nothing** | Bridge's pages render inside your own `+layout.svelte` | Your navigation, header and shell already surround them |
-| **1 — tokens** | Set `--bridge-*` CSS variables in your CSS | Colours, radius, spacing |
-| **2 — frame and heading** | Pass the `frame(page, children)` and `heading(page)` snippets | Everything around the form on every page, and each page's heading |
-| **3 — take over one page** | Create that page's own route file, e.g. `src/routes/auth/login/+page.svelte` | That one page; SvelteKit prefers it over `[...bridge]`, every other page keeps working |
-| **4 — headless** | Build your own UI on `getBridgeAuth()` | Everything |
-
-```svelte
-<!-- rung 2: src/routes/auth/[...bridge]/+page.svelte -->
-<script lang="ts">
-  import { BridgeAuthRoutes } from '@nebulr-group/bridge-svelte';
-</script>
-
-<BridgeAuthRoutes>
-  {#snippet frame(page, children)}
-    <main class="auth-card">{@render children()}</main>
-  {/snippet}
-  {#snippet heading(page)}
-    <h1>{page === 'signup' ? 'Create your account' : 'Welcome back'}</h1>
-  {/snippet}
-</BridgeAuthRoutes>
-```
-
-`heading` replaces only each page's main step (the login credentials step, the signup form, the set-password form); sub-steps such as "Reset your password" keep their own, so two headings never stack. There are no per-page snippets: to change more than frame and heading, take over the page (rung 3). A sign-in page you own navigates itself after sign-in: `<LoginForm onLogin={() => goto(readReturnTo($page.url) ?? '/')} />`.
-
-**The token contract (rung 1).** These `--bridge-*` variables are the supported way to restyle the components; each has a built-in default. Set them on `:root` or on any wrapper.
-
-| Token | Default | Styles |
-|---|---|---|
-| `--bridge-primary` | `#4f46e5` | Primary buttons, selected plan interval, active workspace border |
-| `--bridge-primary-hover` | `#4338ca` | Primary button hover |
-| `--bridge-primary-fg` | `#ffffff` | Text on primary buttons |
-| `--bridge-primary-foreground` | `#ffffff` | Workspace avatar text; plan picker fallback when `--bridge-primary-fg` is unset |
-| `--bridge-primary-light` | `#eff6ff` | Active workspace background |
-| `--bridge-border` | `#d1d5db` | Input and secondary button borders |
-| `--bridge-border-radius` | `6px` | Corners of inputs, buttons, alerts, cards |
-| `--bridge-input-focus` | `#4f46e5` | Input focus ring |
-| `--bridge-foreground` | `#374151` | Password-toggle hover, workspace names |
-| `--bridge-muted` | `#6b7280` | Secondary text, hints, table headings |
-| `--bridge-bg` | `#ffffff` | Plan-change confirmation panel |
-| `--bridge-bg-muted` | `#f5f5f5` | MFA backup code |
-| `--bridge-muted-bg` | `#f3f4f6` | Workspace list hover, plan interval tabs (which fall back to `--bridge-bg-muted`) |
-| `--bridge-alert-error-bg` | `#fef2f2` | Error alert background |
-| `--bridge-alert-error-fg` | `#991b1b` | Error alert text |
-| `--bridge-alert-error-border` | `#fca5a5` | Error alert border |
-| `--bridge-alert-success-bg` | `#f0fdf4` | Success alert background |
-| `--bridge-alert-success-fg` | `#166534` | Success alert text |
-| `--bridge-alert-success-border` | `#86efac` | Success alert border |
-| `--bridge-auth-page-padding` | `3rem 1rem` | Padding of the default sign-in page container |
-| `--bridge-billing-page-width` | `60rem` | Width of the subscription pages and `<BridgePaywallPage>` |
-| `--bridge-billing-page-padding` | `3rem 1rem` | Padding of the subscription pages and `<BridgePaywallPage>` |
-| `--bridge-paywall-bg` | `rgba(15, 23, 42, 0.72)` | Backdrop of the `<BridgePaywall>` overlay |
-| `--bridge-paywall-panel-bg` | `#ffffff` | Panel of the `<BridgePaywall>` overlay |
-
-All default rules use `:where()`, so any selector of yours wins without `!important`. Leaving out `import '@nebulr-group/bridge-svelte/styles'` makes the components headless: plain HTML for you to style.
-
-## 7. Pages Bridge serves, and the one it only offers
-
-- **Sign-in:** `src/routes/auth/[...bridge]/+page.svelte` serves login, signup, the OAuth callback, set password (where signup verification and password-reset emails land), forgot password, magic link, passkey setup and workspace selection. Which methods appear comes from the app's settings at runtime, so turning magic links on needs no code. The pages render inside the app: `loginRoute: '/auth/login'` in `bridgeBootstrap()`. (If the developer explicitly asks for Bridge's hosted sign-in page, or the app already uses it, respect that: leave out `loginRoute`.)
-- **Subscription:** `src/routes/subscription/[...bridge]/+page.svelte` serves `/subscription`, the paywall `/subscription/plan`, and the checkout return pages `/subscription/success` and `/subscription/error`. Bridge's redirects and upgrade links point there by default.
-- **The paywall** redirects a signed-in workspace with no plan to `/subscription/plan` before any page renders — only when the app has plans and its `paymentsAutoRedirect` setting is on (the default). `bridge app update --payments-auto-redirect false` turns it off.
-- **A `/welcome` onboarding page is offered, never created unasked.** It is a product decision: ask the developer. Only if they say yes, add a one-line page rendering `<BridgePaywallPage />` and `billing: { paywallRoute: '/welcome' }` in `bridgeBootstrap()`.
-- Any other address under a catch-all gets the app's own 404.
-
-## Where the details live
-
-| Topic | Command |
-|---|---|
-| Sign-in and the sign-in pages | `bridge guide <framework>` · `bridge guide <framework> sdk-auth` (svelte, react, nextjs, angular) |
-| Plans, the subscription pages, the UI levels | `bridge guide svelte billing` |
-| Backend limits and entitlements | `bridge guide nestjs billing` · `bridge guide express billing` |
-| Backend sign-in and route protection | `bridge guide nestjs` · `bridge guide express` |
-| Feature flags | `bridge guide flags` |
-| Proving sign-in works | The developer signs up and signs in in the app; `bridge event auth-attempts --user <email>` explains a failure |
-
-## Exceptions
-
-Every gate in app code is a flag (`bridge guide fit-together`). Checking a plan feature without a flag (`@RequireEntitlement` on the backend, `<Entitled>` or `$entitlements.can` in the UI) exists for the rare case where the developer explicitly asks for no flag. It prints a one-time note in development; mark the line `// bridge-gate-exception: <reason>` so `check gates` leaves it.

package/dist/prompts/orientation.md

@@ -1,42 +0,0 @@
-# What Bridge does
-
-Relay this to the developer as it stands, then add one sentence about what their app has today (read it first: `get_app` and `get_setup_status`, or `bridge app get` and `bridge setup status`).
-
----
-
-Bridge runs everything between signup and invoice for your app, so you don't build it yourself.
-
-- **Login.** People sign up and sign in with a password, a magic link, a passkey, Google, GitHub and other providers, or their company's SSO, with optional two-factor. Bridge serves the pages; your app adds about fifteen lines. *Want to choose how people sign in?*
-- **Teams and workspaces.** Each customer gets a workspace and can invite teammates into it. You decide whether people create their own workspace or join by invitation. *Is your app for single users or for teams?*
-- **Roles and permissions.** Inside a workspace, each person's role carries privileges, and feature flags use them to decide who gets which page, endpoint or feature, the same in the browser and on your backend. *Who are the different kinds of people in a customer's workspace?*
-- **Payments and plans.** Plans with prices, trials, limits ("3 projects on Free, 50 on Pro") and the features each one sells, checkout through your own Stripe account, and an upgrade prompt when someone hits a limit or a feature their plan lacks. *Want to set up a free tier and a paid plan?*
-- **Feature control.** Feature flags switch any page, API endpoint or feature for everyone, a percentage of users, the plans that sell it, the people allowed to use it, or one customer, without a deploy. *Is there a feature you want to roll out carefully or sell on a higher plan?*
-- **Look and feel.** Sign-in and subscription pages in your colours and fonts, inside your own layout, and emails sent in your app's name. *Want the sign-in pages to look like the rest of your app?*
-- **Going live.** A readiness checklist that says exactly what still points at localhost or test keys, and a test sign-in that proves login works end to end. *Ready to check what stands between you and real users?*
-
----
-
-## Where to go next
-
-Each area has a decision guide: the questions to ask the developer, and the defaults to apply without asking.
-
-| Area | Decision guide | Journey |
-|---|---|---|
-| Login | `bridge guide decision login` | `bridge guide add-login` |
-| Teams and workspaces | `bridge guide decision teams` | `bridge guide add-teams` |
-| Roles and permissions | `bridge guide decision roles` | — |
-| Payments and plans | `bridge guide decision payments` | `bridge guide add-paid-plan` |
-| Feature control | `bridge guide decision feature-control` | `bridge guide add-feature-flag` |
-| Look and feel | `bridge guide decision look-and-feel` | — |
-| Going live | `bridge guide decision going-live` | `bridge guide go-live` |
-
-In an MCP client the same guides are the resources `bridge://guides/decisions/<area>` (areas: `login`, `teams`, `roles`, `payments`, `feature-control`, `look-and-feel`, `going-live`), and the journeys are the server's prompts of the same names.
-
-How roles, plans, limits and flags fit together, the rule every decision guide builds on: `bridge guide fit-together` (MCP: resource `bridge://guides/fit-together`). Read it before setting up any of them.
-
-How limits, upgrade prompts and page customisation actually work, for every area: `bridge guide mechanisms`.
-
-Two rules hold in every guide:
-
-1. **Product questions go to the developer.** What to charge, who may do what, what a plan includes, what users see: ask, and wait for the answer. Never guess them.
-2. **Mechanics you decide.** Where a guide gives a default, apply it and say why in one line. The developer can overrule it.