@contractspec/example.saas-boilerplate 0.0.0-canary-20260113170453

package/src/dashboard/dashboard.presentation.ts

@@ -0,0 +1,56 @@
+import { definePresentation, StabilityEnum } from '@contractspec/lib.contracts';
+
+/**
+ * Main dashboard presentation for the SaaS application.
+ */
+export const SaasDashboardPresentation = definePresentation({
+  meta: {
+    key: 'saas.dashboard',
+    version: '1.0.0',
+    title: 'SaaS Dashboard',
+    description:
+      'Main SaaS dashboard with project overview, usage stats, and quick actions',
+    domain: 'saas-boilerplate',
+    owners: ['@saas-team'],
+    tags: ['dashboard', 'overview'],
+    stability: StabilityEnum.Beta,
+    goal: 'Overview of SaaS activity and metrics',
+    context: 'Main dashboard',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'SaasDashboard',
+  },
+  targets: ['react', 'markdown'],
+  policy: {
+    flags: ['saas.enabled'],
+  },
+});
+
+/**
+ * Settings panel presentation.
+ */
+export const SettingsPanelPresentation = definePresentation({
+  meta: {
+    key: 'saas.settings',
+    version: '1.0.0',
+    title: 'Settings Panel',
+    description: 'Organization and user settings panel',
+    domain: 'saas-boilerplate',
+    owners: ['@saas-team'],
+    tags: ['settings', 'config'],
+    stability: StabilityEnum.Beta,
+    goal: 'Configure organization and user settings',
+    context: 'Settings section',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'SettingsPanel',
+  },
+  targets: ['react'],
+  policy: {
+    flags: ['saas.enabled'],
+  },
+});

package/src/dashboard/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Dashboard domain - main SaaS dashboard and settings panels.
+ */
+
+export {
+  SaasDashboardPresentation,
+  SettingsPanelPresentation,
+} from './dashboard.presentation';

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './saas-boilerplate.docblock';

package/src/docs/saas-boilerplate.docblock.ts

@@ -0,0 +1,98 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const saasBoilerplateDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.examples.saas-boilerplate.goal',
+    title: 'SaaS Boilerplate — Goal',
+    summary:
+      'Multi-tenant SaaS foundation with orgs, members, projects, settings, and usage.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/examples/saas-boilerplate/goal',
+    tags: ['saas', 'goal'],
+    body: `## Why it matters
+- Provides a regenerable SaaS base: orgs, members, projects, settings, usage/billing.
+- Avoids drift across identity, settings, and usage capture.
+
+## Business/Product goal
+- Ship SaaS faster with tenant isolation, RBAC, and usage metering baked in.
+- Keep audit/notifications ready for compliance and customer comms.
+
+## Success criteria
+- Spec changes to org/project/settings/usage regenerate UI/API/events cleanly.
+- Tenant isolation and RBAC stay enforced; usage data is captured with PII scopes.`,
+  },
+  {
+    id: 'docs.examples.saas-boilerplate.usage',
+    title: 'SaaS Boilerplate — Usage',
+    summary: 'How to seed, extend, and regenerate the SaaS base.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/saas-boilerplate/usage',
+    tags: ['saas', 'usage'],
+    body: `## Setup
+1) Seed (if available) or create orgs, members, and projects via UI.
+2) Configure Notifications for invites and project events; set policy.pii for sensitive fields.
+
+## Extend & regenerate
+1) Adjust schemas (project metadata, settings, usage records) in spec.
+2) Regenerate to sync UI/API/events and usage metering.
+3) Use Feature Flags to roll out new settings or billing fields gradually.
+
+## Guardrails
+- Keep tenant/role context explicit in contracts and presentations.
+- Emit events for invites, project changes, and usage records; log in Audit Trail.
+- Redact sensitive user/org data in markdown/JSON outputs.`,
+  },
+  {
+    id: 'docs.examples.saas-boilerplate.reference',
+    title: 'SaaS Boilerplate — Reference',
+    summary:
+      'Entities, contracts, events, and presentations for the SaaS starter.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/saas-boilerplate',
+    tags: ['saas', 'reference'],
+    body: `## Entities
+- Organization, Member, Role, Project, AppSettings, UserSettings, BillingUsage.
+
+## Contracts
+- org/project CRUD, invites, role assignment, usage recording.
+
+## Events
+- org.created, member.invited/accepted, project.created/updated, usage.recorded.
+
+## Presentations
+- Org/project dashboards, member management, settings screens, usage views.
+
+## Notes
+- Tenant isolation is mandatory; enforce via RBAC/policies.
+- Usage/Metering drives billing/limits; keep units explicit.`,
+  },
+  {
+    id: 'docs.examples.saas-boilerplate.constraints',
+    title: 'SaaS Boilerplate — Constraints & Safety',
+    summary:
+      'Internal guardrails for tenancy, RBAC, usage metering, and regeneration.',
+    kind: 'reference',
+    visibility: 'internal',
+    route: '/docs/examples/saas-boilerplate/constraints',
+    tags: ['saas', 'constraints', 'internal'],
+    body: `## Constraints
+- Tenant isolation and RBAC must remain explicit in spec; no implicit defaults in code.
+- Events to emit: org.created, member.invited/accepted, project.created/updated, usage.recorded.
+- Regeneration must not change billing/usage semantics without spec diffs.
+
+## PII & Settings
+- Mark PII (user emails, names) for redaction; keep settings scoped to org/member.
+- Avoid leaking secrets/config in markdown/JSON presentations.
+
+## Verification
+- Add fixtures for usage recording and role changes.
+- Ensure Audit/Notifications remain wired for invites/project updates.
+- Use Feature Flags for new settings/billing fields; default safe/off.`,
+  },
+];
+
+registerDocBlocks(saasBoilerplateDocBlocks);

package/src/example.ts

@@ -0,0 +1,38 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'saas-boilerplate',
+    version: '1.0.0',
+    title: 'SaaS Boilerplate',
+    description:
+      'Multi-tenant SaaS foundation with orgs, projects, settings, billing usage, and RBAC.',
+    kind: 'template',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['saas', 'multi-tenant', 'billing', 'rbac'],
+  },
+  docs: {
+    rootDocId: 'docs.examples.saas-boilerplate',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.saas-boilerplate',
+    feature: './feature',
+    contracts: './contracts',
+    presentations: './presentations',
+    handlers: './handlers',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: {
+      enabled: true,
+      modes: ['playground', 'specs', 'builder', 'markdown', 'evolution'],
+    },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/handlers/index.ts

@@ -0,0 +1,23 @@
+/**
+ * SaaS Boilerplate Handlers - re-exports from domain modules for backward compatibility.
+ */
+
+// Billing handlers
+export {
+  mockGetSubscriptionHandler,
+  mockRecordUsageHandler,
+  mockGetUsageSummaryHandler,
+  mockCheckFeatureAccessHandler,
+} from '../billing/billing.handler';
+
+// Project handlers
+export {
+  mockCreateProjectHandler,
+  mockGetProjectHandler,
+  mockListProjectsHandler,
+  mockUpdateProjectHandler,
+  mockDeleteProjectHandler,
+} from '../project/project.handler';
+
+// Runtime handlers (PGLite)
+export * from './saas.handlers';

package/src/handlers/saas.handlers.ts

@@ -0,0 +1,300 @@
+/**
+ * Runtime-local SaaS Boilerplate handlers
+ *
+ * Database-backed handlers for project and billing management.
+ */
+import type { DatabasePort } from '@contractspec/lib.runtime-sandbox';
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { web } from '@contractspec/lib.runtime-sandbox';
+const { generateId } = web;
+
+// ============ Types ============
+
+export interface Project {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  name: string;
+  description?: string;
+  status: 'DRAFT' | 'ACTIVE' | 'ARCHIVED';
+  tier: 'FREE' | 'PRO' | 'ENTERPRISE';
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface Subscription {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  plan: 'FREE' | 'PRO' | 'ENTERPRISE';
+  status: 'ACTIVE' | 'PAST_DUE' | 'CANCELED';
+  billingCycle: 'MONTHLY' | 'YEARLY';
+  currentPeriodStart: Date;
+  currentPeriodEnd: Date;
+  cancelAtPeriodEnd: boolean;
+}
+
+export interface ListProjectsInput {
+  projectId: string;
+  organizationId?: string;
+  status?: Project['status'] | 'all';
+  search?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ListProjectsOutput {
+  items: Project[];
+  total: number;
+  hasMore: boolean;
+}
+
+export interface CreateProjectInput {
+  name: string;
+  description?: string;
+  tier?: Project['tier'];
+}
+
+export interface UpdateProjectInput {
+  id: string;
+  name?: string;
+  description?: string;
+  status?: Project['status'];
+}
+
+// ============ Row Types ============
+
+interface ProjectRow extends Record<string, unknown> {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  name: string;
+  description: string | null;
+  status: string;
+  tier: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface SubscriptionRow extends Record<string, unknown> {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  plan: string;
+  status: string;
+  billingCycle: string;
+  currentPeriodStart: string;
+  currentPeriodEnd: string;
+  cancelAtPeriodEnd: number;
+}
+
+function rowToProject(row: ProjectRow): Project {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    name: row.name,
+    description: row.description ?? undefined,
+    status: row.status as Project['status'],
+    tier: row.tier as Project['tier'],
+    createdAt: new Date(row.createdAt),
+    updatedAt: new Date(row.updatedAt),
+  };
+}
+
+function rowToSubscription(row: SubscriptionRow): Subscription {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    plan: row.plan as Subscription['plan'],
+    status: row.status as Subscription['status'],
+    billingCycle: row.billingCycle as Subscription['billingCycle'],
+    currentPeriodStart: new Date(row.currentPeriodStart),
+    currentPeriodEnd: new Date(row.currentPeriodEnd),
+    cancelAtPeriodEnd: Boolean(row.cancelAtPeriodEnd),
+  };
+}
+
+// ============ Handler Factory ============
+
+export function createSaasHandlers(db: DatabasePort) {
+  /**
+   * List projects
+   */
+  async function listProjects(
+    input: ListProjectsInput
+  ): Promise<ListProjectsOutput> {
+    const {
+      projectId,
+      organizationId,
+      status,
+      search,
+      limit = 20,
+      offset = 0,
+    } = input;
+
+    let whereClause = 'WHERE projectId = ?';
+    const params: (string | number)[] = [projectId];
+
+    if (organizationId) {
+      whereClause += ' AND organizationId = ?';
+      params.push(organizationId);
+    }
+
+    if (status && status !== 'all') {
+      whereClause += ' AND status = ?';
+      params.push(status);
+    }
+
+    if (search) {
+      whereClause += ' AND (name LIKE ? OR description LIKE ?)';
+      params.push(`%${search}%`, `%${search}%`);
+    }
+
+    const countResult = (
+      await db.query(
+        `SELECT COUNT(*) as count FROM saas_project ${whereClause}`,
+        params
+      )
+    ).rows as unknown as { count: number }[];
+    const total = countResult[0]?.count ?? 0;
+
+    const rows = (
+      await db.query(
+        `SELECT * FROM saas_project ${whereClause} ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
+        [...params, limit, offset]
+      )
+    ).rows as unknown as ProjectRow[];
+
+    return {
+      items: rows.map(rowToProject),
+      total,
+      hasMore: offset + rows.length < total,
+    };
+  }
+
+  /**
+   * Get a single project
+   */
+  async function getProject(id: string): Promise<Project | null> {
+    const rows = (
+      await db.query(`SELECT * FROM saas_project WHERE id = ?`, [id])
+    ).rows as unknown as ProjectRow[];
+    return rows[0] ? rowToProject(rows[0]) : null;
+  }
+
+  /**
+   * Create a project
+   */
+  async function createProject(
+    input: CreateProjectInput,
+    context: { projectId: string; organizationId: string }
+  ): Promise<Project> {
+    const id = generateId('proj');
+    const now = new Date().toISOString();
+
+    await db.execute(
+      `INSERT INTO saas_project (id, projectId, organizationId, name, description, status, tier, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        context.projectId,
+        context.organizationId,
+        input.name,
+        input.description ?? null,
+        'DRAFT',
+        input.tier ?? 'FREE',
+        now,
+        now,
+      ]
+    );
+
+    const rows = (
+      await db.query(`SELECT * FROM saas_project WHERE id = ?`, [id])
+    ).rows as unknown as ProjectRow[];
+
+    return rowToProject(rows[0]!);
+  }
+
+  /**
+   * Update a project
+   */
+  async function updateProject(input: UpdateProjectInput): Promise<Project> {
+    const now = new Date().toISOString();
+    const updates: string[] = ['updatedAt = ?'];
+    const params: (string | null)[] = [now];
+
+    if (input.name !== undefined) {
+      updates.push('name = ?');
+      params.push(input.name);
+    }
+
+    if (input.description !== undefined) {
+      updates.push('description = ?');
+      params.push(input.description);
+    }
+
+    if (input.status !== undefined) {
+      updates.push('status = ?');
+      params.push(input.status);
+    }
+
+    params.push(input.id);
+
+    await db.execute(
+      `UPDATE saas_project SET ${updates.join(', ')} WHERE id = ?`,
+      params
+    );
+
+    const rows = (
+      await db.query(`SELECT * FROM saas_project WHERE id = ?`, [input.id])
+    ).rows as unknown as ProjectRow[];
+
+    if (!rows[0]) {
+      throw new Error('NOT_FOUND');
+    }
+
+    return rowToProject(rows[0]);
+  }
+
+  /**
+   * Delete a project
+   */
+  async function deleteProject(id: string): Promise<void> {
+    await db.execute(`DELETE FROM saas_project WHERE id = ?`, [id]);
+  }
+
+  /**
+   * Get subscription for an organization
+   */
+  async function getSubscription(input: {
+    projectId: string;
+    organizationId?: string;
+  }): Promise<Subscription | null> {
+    let query = `SELECT * FROM saas_subscription WHERE projectId = ?`;
+    const params: string[] = [input.projectId];
+
+    if (input.organizationId) {
+      query += ' AND organizationId = ?';
+      params.push(input.organizationId);
+    }
+
+    query += ' LIMIT 1';
+
+    const rows = (await db.query(query, params))
+      .rows as unknown as SubscriptionRow[];
+    return rows[0] ? rowToSubscription(rows[0]) : null;
+  }
+
+  return {
+    listProjects,
+    getProject,
+    createProject,
+    updateProject,
+    deleteProject,
+    getSubscription,
+  };
+}
+
+export type SaasHandlers = ReturnType<typeof createSaasHandlers>;

package/src/index.ts

@@ -0,0 +1,76 @@
+// SaaS Boilerplate Example
+// Demonstrates ContractSpec principles for a complete SaaS application
+
+// Export all domain modules
+export * from './billing';
+export * from './project';
+export * from './settings';
+export * from './dashboard';
+
+// Export feature and example metadata
+export * from './saas-boilerplate.feature';
+export * from './ui';
+export {
+  createSaasHandlers,
+  type SaasHandlers,
+} from './handlers/saas.handlers';
+export { default as example } from './example';
+
+// Import docs for registration
+import './docs';
+
+// Schema composition configuration
+import { identityRbacSchemaContribution } from '@contractspec/lib.identity-rbac';
+import { jobsSchemaContribution } from '@contractspec/lib.jobs';
+import { auditTrailSchemaContribution } from '@contractspec/module.audit-trail';
+import { notificationsSchemaContribution } from '@contractspec/module.notifications';
+import type { ModuleSchemaContribution } from '@contractspec/lib.schema';
+import {
+  ProjectEntity,
+  ProjectMemberEntity,
+  ProjectStatusEnum,
+} from './project/project.entity';
+import {
+  SettingsEntity,
+  FeatureFlagEntity,
+  SettingsScopeEnum,
+} from './settings';
+import {
+  SubscriptionEntity,
+  BillingUsageEntity,
+  UsageLimitEntity,
+  SubscriptionStatusEnum,
+} from './billing/billing.entity';
+
+/**
+ * SaaS boilerplate schema contribution.
+ */
+export const saasBoilerplateSchemaContribution: ModuleSchemaContribution = {
+  moduleId: '@contractspec/example.saas-boilerplate',
+  entities: [
+    ProjectEntity,
+    ProjectMemberEntity,
+    SettingsEntity,
+    FeatureFlagEntity,
+    SubscriptionEntity,
+    BillingUsageEntity,
+    UsageLimitEntity,
+  ],
+  enums: [ProjectStatusEnum, SettingsScopeEnum, SubscriptionStatusEnum],
+};
+
+/**
+ * Complete schema composition for SaaS Boilerplate.
+ * Use with `database schema:compose` to generate Prisma schema.
+ */
+export const schemaComposition = {
+  modules: [
+    identityRbacSchemaContribution,
+    jobsSchemaContribution,
+    auditTrailSchemaContribution,
+    notificationsSchemaContribution,
+    saasBoilerplateSchemaContribution,
+  ],
+  provider: 'postgresql' as const,
+  outputPath: './prisma/schema/generated.prisma',
+};

package/src/presentations/index.ts

@@ -0,0 +1,36 @@
+/**
+ * SaaS Boilerplate Presentations - re-exports from domain modules for backward compatibility.
+ */
+
+// Billing presentations
+export {
+  SubscriptionPresentation,
+  UsageDashboardPresentation,
+} from '../billing/billing.presentation';
+
+// Project presentations
+export {
+  ProjectListPresentation,
+  ProjectDetailPresentation,
+} from '../project/project.presentation';
+
+// Dashboard presentations
+export {
+  SaasDashboardPresentation,
+  SettingsPanelPresentation,
+} from '../dashboard/dashboard.presentation';
+
+// All presentations collection
+export const SaasBoilerplatePresentations = {
+  // Billing
+  SubscriptionPresentation: undefined,
+  UsageDashboardPresentation: undefined,
+
+  // Project
+  ProjectListPresentation: undefined,
+  ProjectDetailPresentation: undefined,
+
+  // Dashboard
+  SaasDashboardPresentation: undefined,
+  SettingsPanelPresentation: undefined,
+};