vibes-plug 1.0.0 → 2.5.0

package/skills/saas-transformer/references/feature_gating_patterns.md

@@ -1,137 +1,137 @@
-# Feature Gating & Usage Limits Patterns
-
-Standard patterns for restricting access to features and enforcing quotas based on plan configurations.
-
----
-
-## 1. Feature Map Definitions
-
-Define a clear schema mapping plans to features and usage limits.
-
-```typescript
-export interface PlanConfig {
-  name: string;
-  maxMembers: number;
-  maxProjects: number;
-  features: {
-    advancedReporting: boolean;
-    apiAccess: boolean;
-    customDomain: boolean;
-  };
-}
-
-export const PLAN_CONFIGS: Record<string, PlanConfig> = {
-  free: {
-    name: 'Free',
-    maxMembers: 1,
-    maxProjects: 3,
-    features: {
-      advancedReporting: false,
-      apiAccess: false,
-      customDomain: false
-    }
-  },
-  pro: {
-    name: 'Professional',
-    maxMembers: 10,
-    maxProjects: 50,
-    features: {
-      advancedReporting: true,
-      apiAccess: true,
-      customDomain: false
-    }
-  },
-  enterprise: {
-    name: 'Enterprise',
-    maxMembers: 100,
-    maxProjects: 999999,
-    features: {
-      advancedReporting: true,
-      apiAccess: true,
-      customDomain: true
-    }
-  }
-};
-```
-
----
-
-## 2. Server-side Gate Keepers (Next.js Actions / Routes)
-
-Implement standard assertions in your data access layer.
-
-```typescript
-import { getWorkspaceSubscription } from './billing';
-import { PLAN_CONFIGS } from './plan-configs';
-import { db } from './db';
-import { projects } from './db/schema';
-import { count, eq } from 'drizzle-orm';
-
-// Feature gate assertion
-export async function assertHasFeature(workspaceId: string, feature: keyof PlanConfig['features']) {
-  const { plan, isActive } = await getWorkspaceSubscription(workspaceId);
-  const activePlan = isActive ? plan : 'free';
-  
-  const hasFeature = PLAN_CONFIGS[activePlan]?.features[feature];
-  if (!hasFeature) {
-    throw new Error(`Your plan (${activePlan}) does not support the feature: ${feature}`);
-  }
-}
-
-// Usage limits assertion
-export async function assertWithinProjectLimit(workspaceId: string) {
-  const { plan, isActive } = await getWorkspaceSubscription(workspaceId);
-  const activePlan = isActive ? plan : 'free';
-  
-  const limit = PLAN_CONFIGS[activePlan].maxProjects;
-  
-  const [projectCount] = await db
-    .select({ val: count() })
-    .from(projects)
-    .where(eq(projects.workspaceId, workspaceId));
-
-  if (projectCount.val >= limit) {
-    throw new Error(`Project limit reached (${projectCount.val}/${limit}). Please upgrade your plan.`);
-  }
-}
-```
-
----
-
-## 3. UI Graceful Degradation / Upgrade Banner
-
-Wrap component gates clean in React to encourage high conversion paths.
-
-```tsx
-import React from 'react';
-import { Button } from '@/components/ui/button';
-
-interface UpgradeGuardProps {
-  hasFeature: boolean;
-  featureName: string;
-  children: React.ReactNode;
-}
-
-export function UpgradeGuard({ hasFeature, featureName, children }: UpgradeGuardProps) {
-  if (hasFeature) {
-    return <>{children}</>;
-  }
-
-  return (
-    <div className="relative border border-dashed border-gray-300 rounded-lg p-8 text-center bg-gray-50/50">
-      <div className="absolute inset-0 bg-white/40 backdrop-blur-[1px] rounded-lg" />
-      <div className="relative z-10 max-w-sm mx-auto">
-        <h3 className="text-lg font-semibold text-gray-900">Unlock {featureName}</h3>
-        <p className="mt-2 text-sm text-gray-500">
-          This feature is available on our Professional and Enterprise plans. Upgrade today to scale.
-        </p>
-        <div className="mt-4">
-          <Button href="/settings/billing" variant="default">
-            View Pricing Plans
-          </Button>
-        </div>
-      </div>
-    </div>
-  );
-}
-```
+# Feature Gating & Usage Limits Patterns
+
+Standard patterns for restricting access to features and enforcing quotas based on plan configurations.
+
+---
+
+## 1. Feature Map Definitions
+
+Define a clear schema mapping plans to features and usage limits.
+
+```typescript
+export interface PlanConfig {
+  name: string;
+  maxMembers: number;
+  maxProjects: number;
+  features: {
+    advancedReporting: boolean;
+    apiAccess: boolean;
+    customDomain: boolean;
+  };
+}
+
+export const PLAN_CONFIGS: Record<string, PlanConfig> = {
+  free: {
+    name: 'Free',
+    maxMembers: 1,
+    maxProjects: 3,
+    features: {
+      advancedReporting: false,
+      apiAccess: false,
+      customDomain: false
+    }
+  },
+  pro: {
+    name: 'Professional',
+    maxMembers: 10,
+    maxProjects: 50,
+    features: {
+      advancedReporting: true,
+      apiAccess: true,
+      customDomain: false
+    }
+  },
+  enterprise: {
+    name: 'Enterprise',
+    maxMembers: 100,
+    maxProjects: 999999,
+    features: {
+      advancedReporting: true,
+      apiAccess: true,
+      customDomain: true
+    }
+  }
+};
+```
+
+---
+
+## 2. Server-side Gate Keepers (Next.js Actions / Routes)
+
+Implement standard assertions in your data access layer.
+
+```typescript
+import { getWorkspaceSubscription } from './billing';
+import { PLAN_CONFIGS } from './plan-configs';
+import { db } from './db';
+import { projects } from './db/schema';
+import { count, eq } from 'drizzle-orm';
+
+// Feature gate assertion
+export async function assertHasFeature(workspaceId: string, feature: keyof PlanConfig['features']) {
+  const { plan, isActive } = await getWorkspaceSubscription(workspaceId);
+  const activePlan = isActive ? plan : 'free';
+  
+  const hasFeature = PLAN_CONFIGS[activePlan]?.features[feature];
+  if (!hasFeature) {
+    throw new Error(`Your plan (${activePlan}) does not support the feature: ${feature}`);
+  }
+}
+
+// Usage limits assertion
+export async function assertWithinProjectLimit(workspaceId: string) {
+  const { plan, isActive } = await getWorkspaceSubscription(workspaceId);
+  const activePlan = isActive ? plan : 'free';
+  
+  const limit = PLAN_CONFIGS[activePlan].maxProjects;
+  
+  const [projectCount] = await db
+    .select({ val: count() })
+    .from(projects)
+    .where(eq(projects.workspaceId, workspaceId));
+
+  if (projectCount.val >= limit) {
+    throw new Error(`Project limit reached (${projectCount.val}/${limit}). Please upgrade your plan.`);
+  }
+}
+```
+
+---
+
+## 3. UI Graceful Degradation / Upgrade Banner
+
+Wrap component gates clean in React to encourage high conversion paths.
+
+```tsx
+import React from 'react';
+import { Button } from '@/components/ui/button';
+
+interface UpgradeGuardProps {
+  hasFeature: boolean;
+  featureName: string;
+  children: React.ReactNode;
+}
+
+export function UpgradeGuard({ hasFeature, featureName, children }: UpgradeGuardProps) {
+  if (hasFeature) {
+    return <>{children}</>;
+  }
+
+  return (
+    <div className="relative border border-dashed border-gray-300 rounded-lg p-8 text-center bg-gray-50/50">
+      <div className="absolute inset-0 bg-white/40 backdrop-blur-[1px] rounded-lg" />
+      <div className="relative z-10 max-w-sm mx-auto">
+        <h3 className="text-lg font-semibold text-gray-900">Unlock {featureName}</h3>
+        <p className="mt-2 text-sm text-gray-500">
+          This feature is available on our Professional and Enterprise plans. Upgrade today to scale.
+        </p>
+        <div className="mt-4">
+          <Button href="/settings/billing" variant="default">
+            View Pricing Plans
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```

package/skills/saas-transformer/references/saas_transformation_checklist.md

@@ -1,121 +1,121 @@
-# SaaS Transformation Checklist
-
-Detailed verification checkpoints and implementation patterns for converting a single-tenant application to a multi-tenant SaaS platform.
-
----
-
-## Phase 1: Discovery & Analysis
-
-- [ ] **Data Model Mapping**: Extract all relationships. Identify which tables are "global" (shared reference data, e.g., plan configurations, country list) and which are "tenant-specific" (user data, posts, transactions).
-- [ ] **Auth Audit**: Check if the app uses native session storage, custom cookies, or third-party auth. Identify where users are created and stored.
-- [ ] **API Access Points**: Audit all public and internal route files. Note down endpoints that lack authentication.
-- [ ] **Pricing Strategy Fit**: Document the exact plan rules.
-  - *Example*: Free Plan has 1 project limit. Pro Plan has unlimited projects.
-
----
-
-## Phase 2: Multi-Tenancy Foundation
-
-### PostgreSQL Row-Level Security (RLS) Pattern
-When using a shared-schema model, configure your tables to automatically isolate data.
-
-```sql
--- 1. Enable RLS
-ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
-ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
-
--- 2. Create helper function to retrieve current tenant from session context
-CREATE OR REPLACE FUNCTION auth.current_tenant_id()
-RETURNS UUID AS $$
-  SELECT NULLIF(current_setting('app.current_tenant_id', true), '')::UUID;
-$$ LANGUAGE sql STABLE;
-
--- 3. Apply policies using membership lookup
-CREATE POLICY tenant_isolation_policy ON projects
-  AS RESTRICTIVE
-  USING (
-    workspace_id = auth.current_tenant_id()
-  );
-```
-
-### Middleware Connection Context Setting (Node.js/Express Example)
-Ensure every database transaction or connection sets the `app.current_tenant_id` session configuration.
-
-```typescript
-import { Request, Response, NextFunction } from 'express';
-import { db } from '../lib/db';
-
-export async function tenantMiddleware(req: Request, res: Response, next: NextFunction) {
-  const tenantId = req.headers['x-tenant-id'] || req.user?.workspaceId;
-  
-  if (!tenantId) {
-    return res.status(400).json({ error: 'Tenant context missing' });
-  }
-
-  // Inject session variable inside transaction wrapper or pool client
-  await db.execute(sql`SET LOCAL app.current_tenant_id = ${tenantId}`);
-  next();
-}
-```
-
----
-
-## Phase 3: Authentication & Authorization
-
-- [ ] **Workspace Member Resolution**: Ensure a user is mapped to multiple workspaces via a join table (`workspace_members`).
-- [ ] **Role-Based Checkpoint**:
-  ```typescript
-  export function requireRole(allowedRoles: ('owner' | 'admin' | 'member')[]) {
-    return (req: Request, res: Response, next: NextFunction) => {
-      const userRole = req.user?.role;
-      if (!userRole || !allowedRoles.includes(userRole)) {
-        return res.status(403).json({ error: 'Permission denied' });
-      }
-      next();
-    };
-  }
-  ```
-
----
-
-## Phase 4: Billing & Subscription
-
-- [ ] **Stripe Event Handling Idempotency**: Save all processed Stripe Event IDs to a database log table to prevent processing webhooks twice.
-- [ ] **Dunning Flow**: Set up Stripe triggers for `invoice.payment_failed` to send a dynamic link allowing the user to update their payment card in one click.
-
----
-
-## Phase 5: Workspace & Team Management
-
-- [ ] **Invitation Tokens**: Generate cryptographically secure invite tokens using standard library utilities:
-  ```typescript
-  import crypto from 'crypto';
-  const token = crypto.randomBytes(32).toString('hex');
-  ```
-- [ ] **Workspace Switcher Logic**: When changing workspaces, update the session token (or JWT) and redirect the user back to the application dashboard to force frontend hydration with new data.
-
----
-
-## Phase 6: SaaS Frontend & Landing
-
-- [ ] **Responsive Navigation**: Use dynamic dashboard layouts that collapse sidebars on mobile touchpoints.
-- [ ] **SEO Configuration**: Output unique structured data per landing section.
-
----
-
-## Phase 7: API Layer & Feature Gating
-
-- [ ] **Feature Flags**: Guard pages and controls using a hook pattern:
-  ```typescript
-  const { hasFeature } = useSubscription();
-  if (!hasFeature('advanced-export')) {
-    return <UpgradeBanner featureName="Advanced Export" />;
-  }
-  ```
-
----
-
-## Phase 8: Production Hardening & Launch
-
-- [ ] **Rollback Runbook**: Create rollback scripts for DB migrations.
-- [ ] **Cascade Deletion Tests**: Ensure deleting a workspace cleans up all child tables cleanly without foreign-key orphan exceptions.
+# SaaS Transformation Checklist
+
+Detailed verification checkpoints and implementation patterns for converting a single-tenant application to a multi-tenant SaaS platform.
+
+---
+
+## Phase 1: Discovery & Analysis
+
+- [ ] **Data Model Mapping**: Extract all relationships. Identify which tables are "global" (shared reference data, e.g., plan configurations, country list) and which are "tenant-specific" (user data, posts, transactions).
+- [ ] **Auth Audit**: Check if the app uses native session storage, custom cookies, or third-party auth. Identify where users are created and stored.
+- [ ] **API Access Points**: Audit all public and internal route files. Note down endpoints that lack authentication.
+- [ ] **Pricing Strategy Fit**: Document the exact plan rules.
+  - *Example*: Free Plan has 1 project limit. Pro Plan has unlimited projects.
+
+---
+
+## Phase 2: Multi-Tenancy Foundation
+
+### PostgreSQL Row-Level Security (RLS) Pattern
+When using a shared-schema model, configure your tables to automatically isolate data.
+
+```sql
+-- 1. Enable RLS
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
+
+-- 2. Create helper function to retrieve current tenant from session context
+CREATE OR REPLACE FUNCTION auth.current_tenant_id()
+RETURNS UUID AS $$
+  SELECT NULLIF(current_setting('app.current_tenant_id', true), '')::UUID;
+$$ LANGUAGE sql STABLE;
+
+-- 3. Apply policies using membership lookup
+CREATE POLICY tenant_isolation_policy ON projects
+  AS RESTRICTIVE
+  USING (
+    workspace_id = auth.current_tenant_id()
+  );
+```
+
+### Middleware Connection Context Setting (Node.js/Express Example)
+Ensure every database transaction or connection sets the `app.current_tenant_id` session configuration.
+
+```typescript
+import { Request, Response, NextFunction } from 'express';
+import { db } from '../lib/db';
+
+export async function tenantMiddleware(req: Request, res: Response, next: NextFunction) {
+  const tenantId = req.headers['x-tenant-id'] || req.user?.workspaceId;
+  
+  if (!tenantId) {
+    return res.status(400).json({ error: 'Tenant context missing' });
+  }
+
+  // Inject session variable inside transaction wrapper or pool client
+  await db.execute(sql`SET LOCAL app.current_tenant_id = ${tenantId}`);
+  next();
+}
+```
+
+---
+
+## Phase 3: Authentication & Authorization
+
+- [ ] **Workspace Member Resolution**: Ensure a user is mapped to multiple workspaces via a join table (`workspace_members`).
+- [ ] **Role-Based Checkpoint**:
+  ```typescript
+  export function requireRole(allowedRoles: ('owner' | 'admin' | 'member')[]) {
+    return (req: Request, res: Response, next: NextFunction) => {
+      const userRole = req.user?.role;
+      if (!userRole || !allowedRoles.includes(userRole)) {
+        return res.status(403).json({ error: 'Permission denied' });
+      }
+      next();
+    };
+  }
+  ```
+
+---
+
+## Phase 4: Billing & Subscription
+
+- [ ] **Stripe Event Handling Idempotency**: Save all processed Stripe Event IDs to a database log table to prevent processing webhooks twice.
+- [ ] **Dunning Flow**: Set up Stripe triggers for `invoice.payment_failed` to send a dynamic link allowing the user to update their payment card in one click.
+
+---
+
+## Phase 5: Workspace & Team Management
+
+- [ ] **Invitation Tokens**: Generate cryptographically secure invite tokens using standard library utilities:
+  ```typescript
+  import crypto from 'crypto';
+  const token = crypto.randomBytes(32).toString('hex');
+  ```
+- [ ] **Workspace Switcher Logic**: When changing workspaces, update the session token (or JWT) and redirect the user back to the application dashboard to force frontend hydration with new data.
+
+---
+
+## Phase 6: SaaS Frontend & Landing
+
+- [ ] **Responsive Navigation**: Use dynamic dashboard layouts that collapse sidebars on mobile touchpoints.
+- [ ] **SEO Configuration**: Output unique structured data per landing section.
+
+---
+
+## Phase 7: API Layer & Feature Gating
+
+- [ ] **Feature Flags**: Guard pages and controls using a hook pattern:
+  ```typescript
+  const { hasFeature } = useSubscription();
+  if (!hasFeature('advanced-export')) {
+    return <UpgradeBanner featureName="Advanced Export" />;
+  }
+  ```
+
+---
+
+## Phase 8: Production Hardening & Launch
+
+- [ ] **Rollback Runbook**: Create rollback scripts for DB migrations.
+- [ ] **Cascade Deletion Tests**: Ensure deleting a workspace cleans up all child tables cleanly without foreign-key orphan exceptions.