@terreno/mcp 57.1.0 → 57.3.0

package/src/docs/versioned/57.2.0/implementationPlans/billing-stripe.md

@@ -0,0 +1,158 @@
+# Implementation Plan: Stripe billing and subscriptions
+
+**Status:** Draft
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1025
+**Priority:** High
+**Effort:** Epic
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [org-management-ui](org-management-ui.md), inbound-webhooks (IP pending — hard dependency for Phase 3)
+**RTK deprecation flag:** None for the backend; the two screens in Phase 4 follow whatever
+data layer example-frontend uses at that time
+
+## Goal
+
+Terreno has no way to charge customers. This IP adds `@terreno/billing`, a Stripe-backed
+(decision D1: web-first) billing plugin: Stripe customers mapped to organizations,
+code-defined plans mapped to Stripe prices, Checkout and Billing Portal session routes,
+webhook-driven subscription/entitlement sync, and plan gating that plugs into the existing
+feature-flag layer — so `plan: "pro"` can gate features the same way segments do today.
+
+## Non-Goals
+
+- Mobile in-app purchases (`mobile-iap-revenuecat`, Future — the RevenueCat SDK ships in
+  the native baseline so it can land without another major).
+- Usage-based/metered billing, invoicing customization, tax configuration (Stripe Tax is
+  configured in Stripe, not by Terreno).
+- Payment methods beyond what Stripe Checkout/Portal handle.
+- Seat-count enforcement (lands with `invitations-and-seats` integration, Phase 5/future).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Package | New workspace package `@terreno/billing` with `stripe` as a real dependency (vendor-specific by design per D1; a provider abstraction is not warranted for one vendor) |
+| Billing subject | The **organization** (B2B); optional `subject: "user"` mode for consumer apps |
+| Plan definition | Code-defined `plans: [{id, name, stripePriceId, features: string[]}]` passed to `BillingApp` — plans are reviewed code, prices live in Stripe |
+| Checkout UX | Stripe-hosted Checkout + Billing Portal (web-first per D1); no custom card forms; `@stripe/stripe-react-native` payment sheet arrives with the IAP item if ever needed |
+| Source of truth | Stripe is authoritative; local `BillingSubscription` is a webhook-synced cache — no entitlement decision ever calls Stripe inline |
+| Entitlements | `getEntitlements(orgId)` service + a feature-flag segment factory (`planSegment("pro")`) plugging into `FeatureFlagsApp` segments; optional `RequiresPlan("pro")` permission |
+| Webhooks | Consumed through the inbound-webhooks framework with Stripe signature verification and event idempotency (`stripeEventId` unique index) |
+
+## Architecture
+
+```
+billing/
+  src/
+    billingApp.ts        # BillingApp TerrenoPlugin (routes, webhook registration)
+    billingService.ts    # getEntitlements, planSegment, RequiresPlan
+    stripeSync.ts        # webhook event handlers → model sync
+    models/
+      billingCustomer.ts   # orgId ↔ stripeCustomerId
+      billingSubscription.ts
+      billingEvent.ts      # processed webhook events (idempotency)
+```
+
+```typescript
+new BillingApp({
+  stripeSecretKey: env,
+  webhookSecret: env,
+  plans: [{id: "pro", name: "Pro", stripePriceId: "price_...", features: ["ai", "sso"]}],
+  subject: "organization",              // default
+  onSubscriptionChange?: (sub) => Promise<void>;
+})
+```
+
+Webhook events handled: `checkout.session.completed`,
+`customer.subscription.created|updated|deleted`, `invoice.payment_failed`,
+`invoice.paid`. Each handler is idempotent via `BillingEvent`.
+
+## Models
+
+Five-type pattern, descriptions, `createdUpdatedPlugin` + `isDeletedPlugin`.
+
+**BillingCustomer** — `organizationId` (ref, required, unique indexed),
+`stripeCustomerId` (string, unique indexed), `email` (string).
+
+**BillingSubscription** — `organizationId` (ref, required, indexed), `planId` (string —
+Terreno plan id), `stripeSubscriptionId` (string, unique), `status` (Stripe status enum:
+active/trialing/past_due/canceled/…), `currentPeriodEnd` (date), `cancelAtPeriodEnd`
+(boolean), `seats` (number, optional).
+
+**BillingEvent** — `stripeEventId` (string, unique), `type` (string), `processedAt`
+(date), `error` (string, optional).
+
+## APIs
+
+| Method | Path | Permissions | Notes |
+|---|---|---|---|
+| GET | `/billing/plans` | IsAuthenticated | Code-defined plans (no Stripe call) |
+| GET | `/billing/subscription` | IsOrgMember | Current org's subscription + entitlements |
+| POST | `/billing/checkoutSession` | IsOrgAdmin | `{planId}` → Stripe Checkout URL; creates customer on first use |
+| POST | `/billing/portalSession` | IsOrgAdmin | Stripe Billing Portal URL |
+| POST | `/billing/webhooks/stripe` | signature-verified | Via inbound-webhooks framework; raw body |
+
+## Notifications
+
+`invoice.payment_failed` fires `onSubscriptionChange` and sends a dunning email through
+`@terreno/comms` when a mail provider is configured (template `paymentFailed`).
+
+## UI
+
+Phase 4, kept deliberately thin: a plan-picker screen (`GET /billing/plans` + checkout
+redirect) and a billing settings card (current plan, status, portal link). Admin org
+settings show a billing placeholder until this IP ships (see `org-management-ui`).
+
+## Phases
+
+1. **Package + models:** `@terreno/billing` scaffold, three models, plan config
+   validation, unit tests.
+2. **Checkout + portal:** customer creation, session routes, `getEntitlements`,
+   `planSegment`, `RequiresPlan`, tests with mocked Stripe SDK.
+3. **Webhook sync** *(gated on inbound-webhooks)*: signature-verified event routes,
+   idempotent handlers, dunning email, `stripe-mock`/fixture tests.
+4. **UI + example + docs:** plan picker + billing settings in example-frontend, seeds
+   with Stripe test-mode instructions, `docs/how-to/add-billing.md`, SDK regen.
+
+## Feature Flags & Migrations
+
+New collections only. Entitlement gating composes with existing feature flags — a flag can
+target `planSegment("pro")` exactly like today's `pro-users` segment example.
+
+## Activity Log & User Updates
+
+Subscription lifecycle changes logged via `logger` + `BillingEvent`; org-facing billing
+history is the Stripe Portal's job, not Terreno's.
+
+## Not Included / Future Work
+
+- RevenueCat entitlement merge (`mobile-iap-revenuecat`).
+- Seat enforcement against Membership counts (`invitations-and-seats` follow-up).
+- Metered usage, coupons/promotions management, multi-currency handling beyond Stripe
+  defaults.
+
+## Files to Create / Modify
+
+- `billing/` (new workspace package), root `package.json` workspace + scripts
+- `example-backend/src/server.ts` — env-gated `BillingApp` registration
+- `example-frontend` — two screens + SDK regen
+- `docs/how-to/add-billing.md`, `docs/reference/billing.md`, env reference
+- `.github/workflows/billing-ci.yml`, `publish-on-tag.yml`
+
+## Task List
+
+See [docs/tasks/billing-stripe.md](../tasks/billing-stripe.md).
+
+## Acceptance Criteria
+
+- [ ] An org admin can create a Checkout session for a plan and, after the (test-mode)
+      webhook lands, `GET /billing/subscription` reports the active plan and entitlements.
+- [ ] Webhook events are signature-verified and idempotent: replaying the same
+      `stripeEventId` is a no-op.
+- [ ] A feature flag targeting `planSegment("pro")` evaluates true only for members of a
+      subscribed org; `RequiresPlan("pro")` returns 403 otherwise.
+- [ ] Subscription cancellation (portal) downgrades entitlements after the webhook, not
+      before.
+- [ ] Non-admin org members cannot create checkout/portal sessions.
+- [ ] Entitlement checks perform zero inline Stripe API calls.

package/src/docs/versioned/57.2.0/implementationPlans/build-terreno-app-validation.md

@@ -0,0 +1,154 @@
+# Implementation Plan: Dogfooding Run and Launch Blog Post
+
+**Status:** Draft — key decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1015
+**Priority:** High (this is the program's acceptance test)
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md), [`ai-dev-loop-boost`](ai-dev-loop-boost.md), [`deploy-to-vercel`](deploy-to-vercel.md), [`docs-reference-coverage`](docs-reference-coverage.md)
+**RTK deprecation flag:** **Blocked** — the build must be performed against the supported stack (syncdb + Better Auth). A dogfooding run on the deprecated data layer would produce a friction log and a blog post that are both obsolete on publication.
+
+## Goal
+
+Prove the launch claim by testing it, then publish the result. The [`build-terreno-app`](../../.rulesync/skills/build-terreno-app/SKILL.md) skill is the harness; this IP is the run, the fixes that come out of it, and the blog post.
+
+The program's launch gate is: **if an agent following only public documentation and published skills cannot build and deploy a real universal app, the launch is not ready.** This IP executes that test. Its most likely outcome is a list of documentation gaps, which is exactly what it is for.
+
+## Non-Goals
+
+- Writing the skill (already done — this IP runs it).
+- Shipping the demo app as a maintained Terreno example. It is a blog-post artifact, not a fourth example app to keep updated.
+- Marketing beyond the blog post.
+- Building every app concept. One run, one app.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| B1 | App concept | **Pantry** — leads on syncdb conflict resolution |
+| B2 | Public demo repo? | **A** — `flourishhealth/terreno-pantry` |
+| B3 | Who performs the run? | **C** if capacity; else **A** |
+| B4 | Runs before publish | **B** — two runs with fix cycle between |
+| B5 | Publication venue | **A** — docs site blog only |
+| B6 | Name the model? | **A** — yes, with version |
+
+## Architecture
+
+### Run structure
+
+```mermaid
+flowchart TD
+  R1["Run 1<br/>fresh session, public sources only"]
+  L1["Friction log 1<br/>gaps by severity"]
+  F["Fix cycle<br/>docs, skills, MCP"]
+  R2["Run 2<br/>fresh session, fresh environment"]
+  L2["Friction log 2<br/>+ repeat-gap analysis"]
+  G{"Blocking or<br/>major gaps left?"}
+  B["Blog post"]
+  LAUNCH["Launch gate: passed"]
+  R1 --> L1 --> F --> R2 --> L2 --> G
+  G -->|"yes"| F
+  G -->|"no"| B --> LAUNCH
+```
+
+The loop between the gap check and the fix cycle is the point. Exiting after one pass would mean publishing a launch claim that was never re-tested.
+
+### What counts as passing
+
+| Gate | Threshold |
+|------|-----------|
+| Blocking gaps | zero |
+| Major gaps | zero at launch; any found in run 1 must be fixed and confirmed in run 2 |
+| Minor gaps | acceptable, all filed as issues |
+| App completeness | every slice in the chosen concept working on web and one native target |
+| Differentiators | all six demonstrated with artifacts (AI, offline, realtime, admin, universal, feature flags) |
+| Deployment | public URL, all four verification checks passing |
+| Debug loop | the deliberate bug found via `last_error` / `read_logs` without reading framework source |
+
+The debug-loop gate is the one that most directly tests the AI-native pillar. If the agent has to read `@terreno/api` source to diagnose a bug in its own app, the pillar is not real yet.
+
+### Fix routing
+
+Gaps found in a run do not get fixed inside this IP. They route to the IP that owns the surface:
+
+| Gap type | Routes to |
+|----------|-----------|
+| Tutorial wrong or incomplete | [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md) |
+| Reference page missing or wrong | [`docs-reference-coverage`](docs-reference-coverage.md) |
+| MCP tool or agent-loop gap | [`ai-dev-loop-boost`](ai-dev-loop-boost.md) |
+| Deployment guide or skill gap | [`deploy-to-vercel`](deploy-to-vercel.md) / [`deploy-to-gcp`](deploy-to-gcp.md) |
+| Bootstrap output wrong | [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) (agent surfaces) or the MCP server |
+| Positioning inconsistency | [`positioning-django-rails-universal`](positioning-django-rails-universal.md) |
+| Genuine framework bug | a new issue, triaged normally |
+
+This keeps ownership clear and prevents this IP from absorbing the whole program.
+
+## Models / APIs
+
+None in Terreno. The demo app's models come from the chosen concept and live in its own repository.
+
+## Notifications
+
+None.
+
+## UI
+
+The demo app's screens live in its own repository. No changes to `@terreno/ui` unless the run finds a bug, which routes out per the table above.
+
+## Phases
+
+1. **Run 1** — fresh session, public sources only, friction log produced.
+2. **Triage** — classify every gap, route to owning IPs, file issues.
+3. **Fix cycle** — owning IPs land their fixes (tracked, not performed here).
+4. **Run 2** — fresh session and fresh environment, second friction log, repeat-gap analysis.
+5. **Gate** — confirm zero blocking and zero major gaps, or loop back to phase 3.
+6. **Blog post** — draft, artifact review, fact check, publish.
+7. **Retrospective** — record what the harness itself got wrong so the skill improves.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- A recurring dogfooding cadence (worth doing quarterly; propose separately once the first run has calibrated the effort).
+- Building the other four app concepts.
+- Maintaining the demo app past the post.
+- Comparative benchmarks against other frameworks.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/explanation/dogfooding-results.md` (the public summary of both runs)
+- The demo app repository (outside this repo, per B2)
+
+**Modify**
+
+- `.rulesync/skills/build-terreno-app/SKILL.md` and its references (retrospective improvements)
+- `website/blog/` (the post, if the docs site gains a blog)
+- Whichever documents the fix cycle touches — owned by their IPs
+
+## Task List
+
+See [`docs/tasks/build-terreno-app-validation.md`](../tasks/build-terreno-app-validation.md).
+
+## Acceptance Criteria
+
+- [ ] Run 1 completed with a friction log classifying every gap by severity, phase, and suggested fix.
+- [ ] Every blocking and major gap from run 1 is filed as an issue and routed to an owning IP.
+- [ ] Run 2 completed in a fresh environment after fixes, with its own friction log.
+- [ ] Run 2 reports zero blocking gaps and zero major gaps.
+- [ ] Any gap appearing in both runs is called out explicitly with an explanation of why the fix did not work.
+- [ ] The demo app implements every slice of the chosen concept and runs on web and one native target.
+- [ ] All six differentiators are demonstrated with artifacts in `/opt/cursor/artifacts/`.
+- [ ] The deliberate bug was found using only `last_error` and `read_logs`, without reading framework source, and the elapsed time is recorded.
+- [ ] The app is deployed to a public URL with all four verification checks passing.
+- [ ] `BLOG_DRAFT.md` follows the outline, includes a "what did not work" section with three real gaps, and names the model and version used.
+- [ ] Every claim in the post is verified against an artifact by someone who did not perform the run.
+- [ ] `docs/explanation/dogfooding-results.md` publishes both runs' gap counts and what changed between them.
+- [ ] The `build-terreno-app` skill is updated with retrospective improvements, and mirrors are regenerated.

package/src/docs/versioned/57.2.0/implementationPlans/comms-abstraction-research.md

@@ -0,0 +1,48 @@
+# Research: comms-abstraction (finish pass)
+
+**Date:** 2026-08-20
+**Scope:** Reconcile the Draft IP with shipped `@terreno/comms` and name remaining roast work.
+
+## Shipped (do not re-plan)
+
+- Package scaffold, console adapters, `CommsApp`, `getCommsService()`, `PushToken` + routes,
+  `GET /comms/messages`, example-backend registration, CI/publish, reference docs, rules.
+- PRs: #1037 (foundation), #1050 (SendGrid adapter — owned by `comms-adapter-sendgrid`).
+- `SendResult.errorCode` / `errorClass` exist; `CommsMessage` stores them.
+- Mail-only inline retry on `errorClass: "transient"`.
+- Partial hooks: `onSend`, `onError`, `onRetry`, `onDeliveryEvent` (the last is never invoked).
+- Recipients redacted at rest (`redactRecipients`, default true).
+- Push pruning uses `isPermanentFailure`, not `errorClass`.
+
+## Gaps vs original IP (remaining)
+
+| Contract | IP | Code today |
+|---|---|---|
+| `beforeSend` mutate/cancel | specified | missing |
+| `onOptOut` / `OptOutEvent` | specified | missing |
+| `recordDeliveryEvent` / `recordOptOut` | implied (adapters feed events) | missing; `onDeliveryEvent` dead |
+| `CommsHookContext` | message, userId, isRetry, messageId | `{channel, provider, isRetry?}` |
+| `onRetry` | `(context, attempt)` | `(context, result)` — **keep shipped signature** |
+| Inline retry | all send paths | mail only; SMS/push/verification rethrow |
+| `attempts[]`, payload, retry links | dashboard-ready fields | missing |
+| `status: cancelled` | specified | not in enum |
+| Push prune | permanent failure | `isPermanentFailure` only |
+
+## Options considered (finish pass)
+
+Remaining work keeps the original IP as the contract. Shrink-to-code was rejected: the
+admin-dashboard IP depends on attempt history, payload retention, and `beforeSend`. A
+follow-up IP was rejected: the fields were already in this plan.
+
+Non-breaking choices for a published package:
+
+- Keep `onRetry(context, result)`; put `attempt` on `CommsHookContext`.
+- Keep `isPermanentFailure` as an adapter alias; facade also prunes on `errorClass: "permanent"`.
+- Unify provider throws to `SendResult` (no rethrow) so retry can run on every channel.
+
+## References
+
+- `comms/src/types.ts`, `commsService.ts`, `models/commsMessage.ts`
+- [comms-admin-dashboard.md](comms-admin-dashboard.md)
+- [comms-adapter-sendgrid.md](comms-adapter-sendgrid.md)
+- Roadmap: https://github.com/FlourishHealth/terreno/issues/1018