@cubis/foundry 0.3.83 → 0.3.84

package/workflows/skills/stripe-integration/references/subscription-lifecycle.md

@@ -1,209 +0,0 @@
-# Subscription Lifecycle
-
-Load this when implementing recurring billing, handling plan changes, managing trials, or building dunning logic.
-
-## Creating Subscriptions
-
-### Via Checkout Session
-
-```typescript
-const session = await stripe.checkout.sessions.create({
-  mode: 'subscription',
-  customer: customerId,
-  line_items: [{ price: 'price_monthly_pro', quantity: 1 }],
-  subscription_data: {
-    trial_period_days: 14,
-    metadata: { userId: 'user_123', plan: 'pro' },
-  },
-  success_url: 'https://app.example.com/welcome',
-  cancel_url: 'https://app.example.com/pricing',
-});
-```
-
-### Via API (for returning customers)
-
-```typescript
-const subscription = await stripe.subscriptions.create({
-  customer: customerId,
-  items: [{ price: 'price_monthly_pro' }],
-  default_payment_method: 'pm_xxx',
-  trial_period_days: 14,
-  payment_behavior: 'default_incomplete',
-  expand: ['latest_invoice.payment_intent'],
-});
-```
-
-- `default_incomplete` requires the client to confirm payment before activating. Use this for SCA compliance.
-- `allow_incomplete` activates immediately and creates a pending invoice. Use for trusted customers or free trials.
-
-## Subscription States
-
-```
-trialing -> active -> past_due -> canceled
-                   -> canceled (immediate)
-                   -> unpaid (after all retries)
-                   -> paused (manual)
-```
-
-- **trialing**: No charge yet. Transitions to `active` when trial ends and first payment succeeds.
-- **active**: Payment current. The desired steady state.
-- **past_due**: Payment failed but retries remain. User should still have access during grace period.
-- **canceled**: Terminal state. No more invoices. Access should be revoked.
-- **unpaid**: All retries exhausted. Configure this vs `canceled` in Stripe subscription settings.
-
-## Plan Changes (Upgrades and Downgrades)
-
-### Immediate Proration (Default)
-
-```typescript
-const subscription = await stripe.subscriptions.retrieve(subId);
-const baseItem = subscription.items.data[0];
-
-await stripe.subscriptions.update(subId, {
-  items: [{ id: baseItem.id, price: 'price_monthly_enterprise' }],
-  proration_behavior: 'create_prorations',
-});
-```
-
-- Stripe calculates unused time on the old plan as a credit and charges the remaining time on the new plan.
-- The proration appears as line items on the next invoice.
-
-### Proration Options
-
-| Behavior | Effect |
-|----------|--------|
-| `create_prorations` | Credit old plan, charge new plan prorated (default) |
-| `always_invoice` | Same as above but immediately creates and pays an invoice |
-| `none` | No proration. New price applies at next billing cycle |
-
-### Previewing Proration
-
-```typescript
-const preview = await stripe.invoices.retrieveUpcoming({
-  customer: customerId,
-  subscription: subId,
-  subscription_items: [
-    { id: itemId, price: 'price_monthly_enterprise' },
-  ],
-  subscription_proration_behavior: 'create_prorations',
-});
-
-console.log('Next invoice total:', preview.total); // in cents
-console.log('Proration line items:', preview.lines.data);
-```
-
-- Always show the proration preview to the user before confirming a plan change.
-
-## Trial Periods
-
-```typescript
-// Trial on subscription creation
-const sub = await stripe.subscriptions.create({
-  customer: customerId,
-  items: [{ price: 'price_monthly_pro' }],
-  trial_period_days: 14,
-});
-
-// Trial with explicit end date
-const sub = await stripe.subscriptions.create({
-  customer: customerId,
-  items: [{ price: 'price_monthly_pro' }],
-  trial_end: Math.floor(Date.now() / 1000) + 14 * 24 * 60 * 60,
-});
-
-// End trial immediately (start billing now)
-await stripe.subscriptions.update(subId, {
-  trial_end: 'now',
-});
-```
-
-- Collect a payment method during trial signup. Trials without payment methods have high churn.
-- Send a reminder email 3 days before trial ends using the `customer.subscription.trial_will_end` event.
-
-## Cancellation Patterns
-
-### Cancel at Period End (Recommended)
-
-```typescript
-await stripe.subscriptions.update(subId, {
-  cancel_at_period_end: true,
-});
-// User retains access until the end of the billing period
-// Stripe fires customer.subscription.updated immediately
-// Stripe fires customer.subscription.deleted at period end
-```
-
-### Cancel Immediately
-
-```typescript
-await stripe.subscriptions.cancel(subId);
-// Access should be revoked immediately
-// Stripe fires customer.subscription.deleted
-```
-
-### Reactivate Before Period End
-
-```typescript
-await stripe.subscriptions.update(subId, {
-  cancel_at_period_end: false,
-});
-```
-
-## Dunning Strategy
-
-Stripe retries failed payments automatically based on your Smart Retries configuration. Your application handles the user-facing communication.
-
-```typescript
-// Webhook: invoice.payment_failed
-async function handlePaymentFailed(invoice: Stripe.Invoice) {
-  const attemptCount = invoice.attempt_count;
-  const userId = invoice.subscription_details?.metadata?.userId;
-
-  switch (attemptCount) {
-    case 1:
-      await notify(userId, 'payment_failed_gentle', {
-        message: 'Your payment failed. We will retry automatically.',
-        updatePaymentUrl: await createPortalUrl(invoice.customer as string),
-      });
-      break;
-    case 2:
-      await notify(userId, 'payment_failed_urgent', {
-        message: 'Second payment attempt failed. Please update your payment method.',
-        daysUntilCancellation: 7,
-      });
-      break;
-    case 3:
-      await notify(userId, 'payment_failed_final', {
-        message: 'Final payment attempt failed. Your subscription will be cancelled.',
-      });
-      break;
-  }
-}
-```
-
-### Dunning Best Practices
-
-- Show an in-app banner for `past_due` subscriptions with a direct link to update payment.
-- Keep access active during the retry period (typically 1-3 weeks).
-- Send the Customer Portal URL so users can update their payment method without contacting support.
-- Configure Smart Retries in Stripe Dashboard for optimal retry timing.
-- Use `invoice.upcoming` webhook to warn users about upcoming charges 3 days before renewal.
-
-## Metered Billing
-
-```typescript
-// Report usage on a metered subscription item
-await stripe.subscriptionItems.createUsageRecord(
-  meteredItemId,
-  {
-    quantity: 150,          // units consumed
-    timestamp: timestamp,   // when usage occurred
-    action: 'increment',    // or 'set' to replace
-  }
-);
-```
-
-- Use `increment` for additive reporting (safer with retries).
-- Use `set` only when you maintain the canonical usage count and report the total.
-- Report usage before the billing period ends. Unreported usage is not billed.
-- Stripe aggregates usage records per billing period and adds them to the invoice.

package/workflows/skills/stripe-integration/references/webhook-handling.md

@@ -1,163 +0,0 @@
-# Webhook Handling
-
-Load this when setting up Stripe webhook endpoints, processing events, or debugging delivery issues.
-
-## Endpoint Setup
-
-### Express/Next.js Webhook Route
-
-The critical requirement is receiving the **raw request body** for signature verification. Parsed JSON bodies will fail verification.
-
-```typescript
-// Next.js App Router
-export async function POST(req: NextRequest) {
-  const rawBody = await req.text(); // raw body, not req.json()
-  const signature = req.headers.get('stripe-signature')!;
-
-  let event: Stripe.Event;
-  try {
-    event = stripe.webhooks.constructEvent(
-      rawBody,
-      signature,
-      process.env.STRIPE_WEBHOOK_SECRET!
-    );
-  } catch (err) {
-    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
-  }
-
-  // Process event...
-  return NextResponse.json({ received: true });
-}
-```
-
-```typescript
-// Express.js -- must use raw body parser for the webhook route
-app.post(
-  '/webhooks/stripe',
-  express.raw({ type: 'application/json' }),
-  (req, res) => {
-    const event = stripe.webhooks.constructEvent(
-      req.body,
-      req.headers['stripe-signature']!,
-      process.env.STRIPE_WEBHOOK_SECRET!
-    );
-    // Process event...
-    res.json({ received: true });
-  }
-);
-```
-
-- Never apply JSON body parsing middleware to the webhook route.
-- Return HTTP 200 immediately. Process the event asynchronously.
-- Stripe retries on non-2xx responses with exponential backoff for up to 3 days.
-
-## Event Idempotency
-
-Stripe guarantees at-least-once delivery. Your handler must be idempotent.
-
-```typescript
-async function processEvent(event: Stripe.Event) {
-  // Strategy 1: Deduplicate by event ID
-  const processed = await db.processedEvent.findUnique({
-    where: { stripeEventId: event.id },
-  });
-  if (processed) return; // already handled
-
-  // Strategy 2: Check object version (for updates)
-  if (event.type === 'customer.subscription.updated') {
-    const sub = event.data.object as Stripe.Subscription;
-    const local = await db.subscription.findUnique({
-      where: { stripeId: sub.id },
-    });
-    // Skip if local version is newer (based on Stripe's created timestamp)
-    if (local && local.lastEventTimestamp >= event.created) return;
-  }
-
-  await handleEvent(event);
-
-  await db.processedEvent.create({
-    data: {
-      stripeEventId: event.id,
-      type: event.type,
-      processedAt: new Date(),
-    },
-  });
-}
-```
-
-## Essential Events by Feature
-
-### Checkout
-
-| Event | When | Action |
-|-------|------|--------|
-| `checkout.session.completed` | Payment succeeds | Activate order or subscription |
-| `checkout.session.expired` | Session unused for 24h | Clean up pending records |
-| `checkout.session.async_payment_succeeded` | Bank transfer clears | Activate order |
-| `checkout.session.async_payment_failed` | Bank transfer fails | Notify user |
-
-### Subscriptions
-
-| Event | When | Action |
-|-------|------|--------|
-| `customer.subscription.created` | New subscription | Record in database |
-| `customer.subscription.updated` | Plan change, status change | Sync local state |
-| `customer.subscription.deleted` | Subscription cancelled | Revoke access |
-| `invoice.payment_succeeded` | Recurring payment works | Confirm active status |
-| `invoice.payment_failed` | Payment retry fails | Send dunning email |
-| `invoice.upcoming` | 3 days before renewal | Notify user (optional) |
-
-### Payment Intents
-
-| Event | When | Action |
-|-------|------|--------|
-| `payment_intent.succeeded` | Payment confirmed | Fulfill order |
-| `payment_intent.payment_failed` | Card declined | Show error to user |
-| `payment_intent.requires_action` | 3DS challenge needed | Redirect user |
-
-## Webhook Security
-
-```typescript
-// Always verify signatures
-const event = stripe.webhooks.constructEvent(rawBody, signature, secret);
-
-// Rotate webhook secrets during key rotation:
-// 1. Add new endpoint with new secret
-// 2. Verify against both secrets during transition
-// 3. Remove old endpoint after confirming delivery
-function verifyWithFallback(body: string, sig: string): Stripe.Event {
-  try {
-    return stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
-  } catch {
-    return stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET_OLD!);
-  }
-}
-```
-
-## Local Development with Stripe CLI
-
-```bash
-# Listen to all events
-stripe listen --forward-to localhost:3000/api/webhooks/stripe
-
-# Listen to specific events only
-stripe listen --events checkout.session.completed,invoice.payment_failed \
-  --forward-to localhost:3000/api/webhooks/stripe
-
-# Trigger a specific event sequence
-stripe trigger payment_intent.succeeded
-
-# Replay a specific event from your Stripe account
-stripe events resend evt_xxxxxxxxxxxxx
-```
-
-- The CLI prints the webhook signing secret on startup. Use it as `STRIPE_WEBHOOK_SECRET` for local development.
-- CLI-forwarded events use a different signing secret than your production webhook endpoint.
-
-## Debugging Delivery Issues
-
-1. Check the Stripe Dashboard under Developers > Webhooks for failed deliveries.
-2. Look at the HTTP response code and body your endpoint returned.
-3. Verify the raw body is passed to `constructEvent`, not a parsed JSON object.
-4. Confirm the webhook secret matches the endpoint (test vs live, CLI vs dashboard).
-5. Check that no middleware is transforming the request body before your handler.

package/workflows/skills/t3-stack/SKILL.md

@@ -1,76 +0,0 @@
----
-name: t3-stack
-description: "Use when building or maintaining T3 Stack apps with Next.js App Router, tRPC, Prisma, NextAuth.js, Tailwind CSS, and end-to-end type safety."
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: Claude Code, Codex, GitHub Copilot
----
-
-# T3 Stack
-
-## Purpose
-
-Guide the design and implementation of production-grade full-stack TypeScript applications using the T3 Stack (Next.js + tRPC + Prisma + NextAuth.js + Tailwind CSS). Every instruction prioritizes end-to-end type safety, minimal client-side JavaScript, and secure-by-default session management.
-
-## When to Use
-
-- Scaffolding a new T3 Stack project or adding features to an existing one.
-- Designing tRPC routers, procedures, and middleware chains.
-- Writing Prisma schemas, queries, or migrations for a T3 application.
-- Configuring NextAuth.js providers, callbacks, and session strategies.
-- Connecting server components to tRPC queries with type-safe data fetching.
-- Reviewing T3 Stack code for type holes, security gaps, or performance regressions.
-
-## Instructions
-
-1. **Confirm the runtime stack before writing code** because T3 projects vary across Next.js versions (Pages Router vs. App Router), tRPC versions (v10 vs. v11), and Prisma versions (v5 vs. v6). Mismatched assumptions cause subtle type errors.
-
-2. **Initialize tRPC with a root router and typed caller** so that every procedure inherits shared context (session, database client) and the front end gets full autocompletion without manual type imports.
-
-3. **Define Prisma models before writing tRPC procedures** because the schema is the single source of truth for database shape, and tRPC input/output types should derive from or validate against it.
-
-4. **Use Zod schemas for every tRPC input and output** because runtime validation at the API boundary catches malformed data that TypeScript alone cannot enforce at runtime.
-
-5. **Create reusable tRPC middleware for authentication and authorization** so that protected procedures declare their requirements declaratively rather than scattering session checks across every handler.
-
-6. **Wire NextAuth.js session into the tRPC context** so that every procedure has access to the authenticated user without redundant session lookups or prop drilling.
-
-7. **Prefer server-side tRPC callers in React Server Components** because calling tRPC on the server avoids a network round-trip, keeps secrets off the client, and feeds data directly into the RSC render tree.
-
-8. **Use `@tanstack/react-query` integration for client components only** because client-side cache, optimistic updates, and mutations require a query client that does not exist in server components.
-
-9. **Keep Prisma client as a singleton** by instantiating it once in a `db.ts` module with a global cache guard, because Next.js hot-reload in development creates many Prisma Client instances that exhaust database connections.
-
-10. **Apply Tailwind CSS with utility-first composition and `cn()` helper** because consistent styling requires a merge strategy that handles conditional classes and avoids specificity conflicts.
-
-11. **Write integration tests that exercise the full tRPC-to-Prisma path** because unit-testing procedures in isolation misses query bugs, middleware ordering issues, and session edge cases.
-
-12. **Configure environment variables with `@t3-oss/env-nextjs`** so that missing or mistyped environment variables fail at build time rather than silently producing undefined values at runtime.
-
-13. **Separate public and protected routers explicitly** because a single misconfigured middleware chain can expose private data, and explicit separation makes the boundary auditable.
-
-14. **Handle tRPC errors with structured error codes and messages** so that the client can display meaningful feedback and retry logic can distinguish transient failures from permanent ones.
-
-15. **Use Prisma transactions for multi-step mutations** because partial writes without a transaction leave the database in an inconsistent state when any step fails.
-
-16. **Deploy with connection pooling (PgBouncer or Prisma Accelerate)** because serverless environments create a new database connection per invocation, quickly exhausting the connection limit.
-
-## Output Format
-
-Provide implementation code, schema definitions, configuration snippets, and architectural guidance as appropriate. Include file paths relative to the project root. When generating tRPC routers, always show the Zod input schema alongside the procedure.
-
-## References
-
-| File                              | Load when                                                                                     |
-| --------------------------------- | --------------------------------------------------------------------------------------------- |
-| `references/trpc-patterns.md`    | Designing tRPC routers, procedures, middleware, error handling, or server-side callers.       |
-| `references/prisma-t3-patterns.md` | Writing Prisma schemas, queries, relations, or configuring the singleton client in T3.     |
-| `references/auth-strategies.md`  | Configuring NextAuth.js providers, callbacks, session strategies, or wiring auth into tRPC.  |
-
-## Examples
-
-- "Set up a new T3 Stack project with Google OAuth and a Prisma PostgreSQL schema."
-- "Add a tRPC router for CRUD operations on a blog post model with auth middleware."
-- "Review my T3 Stack app for type safety gaps between tRPC and Prisma."

package/workflows/skills/t3-stack/evals/assertions.md

@@ -1,48 +0,0 @@
-# T3 Stack Eval Assertions
-
-## Eval 1: tRPC Router with Prisma Queries
-
-This eval tests the core T3 Stack workflow: building a tRPC router backed by Prisma with proper authentication middleware.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                       |
-|---|----------|-------------------------------------------------|------------------------------------------------------------------------------------------------------|
-| 1 | contains | `z.object` — Zod schema usage                  | Runtime validation at the tRPC boundary is non-negotiable. TypeScript types vanish at runtime.       |
-| 2 | contains | `protectedProcedure` — Auth middleware          | Mutations that modify data must require authentication. Using publicProcedure here is a security bug.|
-| 3 | contains | `prisma` — Prisma client usage                  | The T3 Stack convention is Prisma for all database access. Raw SQL or other ORMs break type safety.  |
-| 4 | contains | `TRPCError` — Structured error handling         | Generic throws produce unhelpful client errors. TRPCError codes enable proper client-side handling.  |
-| 5 | contains | `ctx.session` — Session context access           | The session must flow through tRPC context, not be fetched inside each procedure independently.      |
-
-### What a passing response looks like
-
-- A `projectRouter` with five procedures (list, getById, create, update, delete).
-- Zod schemas for inputs with proper field types (string, number, optional).
-- `publicProcedure` for read operations, `protectedProcedure` for writes.
-- Prisma queries using `findMany` with pagination, `findUnique`, `create`, `update`, `delete`.
-- `TRPCError` thrown for not-found and unauthorized cases with descriptive messages.
-- `ctx.session.user.id` used to scope queries to the authenticated user.
-
----
-
-## Eval 2: NextAuth Session with tRPC Context
-
-This eval tests the authentication integration layer: NextAuth.js configuration wired into the tRPC context.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                       |
-|---|----------|-------------------------------------------------|------------------------------------------------------------------------------------------------------|
-| 1 | contains | `PrismaAdapter` — Database-backed auth          | Persisting auth state in the database (not just JWTs) enables account linking and session management.|
-| 2 | contains | `GoogleProvider` — OAuth provider setup          | The eval specifically requests Google OAuth. Must configure with env vars, not hardcoded secrets.    |
-| 3 | contains | `getServerSession` — Server-side session fetch   | tRPC context must fetch the session server-side for security and performance.                        |
-| 4 | contains | `callbacks` — Session/JWT callbacks              | Without callbacks, the session object lacks the user ID needed by tRPC procedures.                   |
-| 5 | contains | `NEXTAUTH_SECRET` — Secure secret reference      | Hardcoded secrets are a critical vulnerability. Must reference environment variables.                 |
-
-### What a passing response looks like
-
-- An `authOptions` object with `PrismaAdapter`, Google and GitHub providers, and session/JWT callbacks.
-- A `createTRPCContext` function that calls `getServerSession(authOptions)` and passes the session to context.
-- A `protectedProcedure` middleware that checks `ctx.session` and throws `UNAUTHORIZED` if missing.
-- A sample procedure that accesses `ctx.session.user.id` to return the user profile from Prisma.
-- Environment variable references for `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `NEXTAUTH_SECRET`.

package/workflows/skills/t3-stack/evals/evals.json

@@ -1,66 +0,0 @@
-[
-  {
-    "name": "trpc-router-with-prisma-queries",
-    "description": "Validate that the skill produces a tRPC router with Prisma queries that follows T3 Stack conventions: Zod input validation, singleton Prisma client, proper error handling, and end-to-end type safety.",
-    "input": "Create a tRPC router for a 'projects' resource in a T3 Stack app. The Prisma model has id, name, description, ownerId, createdAt, and updatedAt fields. Include list (paginated), getById, create, update, and delete procedures. The create, update, and delete procedures should require authentication.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "z.object",
-        "description": "Every procedure input must use Zod schema validation to enforce runtime type safety at the API boundary."
-      },
-      {
-        "type": "contains",
-        "value": "protectedProcedure",
-        "description": "Mutation procedures (create, update, delete) must use protectedProcedure middleware to enforce authentication."
-      },
-      {
-        "type": "contains",
-        "value": "prisma",
-        "description": "Procedures must use the Prisma client for database operations rather than raw SQL or other ORMs."
-      },
-      {
-        "type": "contains",
-        "value": "TRPCError",
-        "description": "Error handling must use structured TRPCError with appropriate error codes (NOT_FOUND, UNAUTHORIZED, etc.)."
-      },
-      {
-        "type": "contains",
-        "value": "ctx.session",
-        "description": "Protected procedures must access the authenticated user through ctx.session, which is wired from NextAuth.js into the tRPC context."
-      }
-    ]
-  },
-  {
-    "name": "nextauth-session-with-trpc-context",
-    "description": "Validate that the skill correctly configures NextAuth.js session handling and wires it into the tRPC context for a T3 Stack application.",
-    "input": "Configure NextAuth.js with GitHub and Google OAuth providers for a T3 Stack app. Wire the session into the tRPC context so that protected procedures can access the user. Include the Prisma adapter for persisting accounts and sessions. Show the auth configuration, tRPC context creation, and a protected procedure that returns the current user's profile.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "PrismaAdapter",
-        "description": "NextAuth.js must use the Prisma adapter to persist user accounts, sessions, and verification tokens in the database."
-      },
-      {
-        "type": "contains",
-        "value": "GoogleProvider",
-        "description": "The auth configuration must include Google OAuth provider setup with client ID and secret from environment variables."
-      },
-      {
-        "type": "contains",
-        "value": "getServerSession",
-        "description": "The tRPC context must retrieve the session using getServerSession (or getServerAuthSession) so that procedures have access to the authenticated user."
-      },
-      {
-        "type": "contains",
-        "value": "callbacks",
-        "description": "NextAuth.js must configure session and JWT callbacks to include user ID in the session object for downstream use in tRPC procedures."
-      },
-      {
-        "type": "contains",
-        "value": "NEXTAUTH_SECRET",
-        "description": "The configuration must reference NEXTAUTH_SECRET environment variable for secure token signing, never a hardcoded value."
-      }
-    ]
-  }
-]