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

package/src/project/project.operations.ts

@@ -0,0 +1,272 @@
+import {
+  defineCommand,
+  defineQuery,
+} from '@contractspec/lib.contracts/operations';
+import {
+  CreateProjectInputModel,
+  DeleteProjectInputModel,
+  DeleteProjectOutputModel,
+  GetProjectInputModel,
+  ListProjectsInputModel,
+  ListProjectsOutputModel,
+  ProjectDeletedPayloadModel,
+  ProjectModel,
+  UpdateProjectInputModel,
+} from './project.schema';
+
+const OWNERS = ['example.saas-boilerplate'] as const;
+
+/**
+ * Create a new project.
+ */
+export const CreateProjectContract = defineCommand({
+  meta: {
+    key: 'saas.project.create',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'create'],
+    description: 'Create a new project in the organization.',
+    goal: 'Allow users to create projects for organizing work.',
+    context: 'Called from project creation UI or API.',
+  },
+  io: {
+    input: CreateProjectInputModel,
+    output: ProjectModel,
+    errors: {
+      SLUG_EXISTS: {
+        description: 'A project with this slug already exists',
+        http: 409,
+        gqlCode: 'SLUG_EXISTS',
+        when: 'Slug is already taken in the organization',
+      },
+      LIMIT_REACHED: {
+        description: 'Project limit reached for this plan',
+        http: 403,
+        gqlCode: 'LIMIT_REACHED',
+        when: 'Organization has reached project limit',
+      },
+    },
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'project.created',
+        version: '1.0.0',
+        when: 'Project is created',
+        payload: ProjectModel,
+      },
+    ],
+    audit: ['project.created'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'create-project-happy-path',
+        given: ['User is authenticated'],
+        when: ['User creates project'],
+        then: ['Project is created', 'ProjectCreated event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'create-basic',
+        input: { name: 'Website Redesign', slug: 'website-redesign' },
+        output: { id: 'proj-123', name: 'Website Redesign', isArchived: false },
+      },
+    ],
+  },
+});
+
+/**
+ * Get project by ID.
+ */
+export const GetProjectContract = defineQuery({
+  meta: {
+    key: 'saas.project.get',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'get'],
+    description: 'Get a project by ID.',
+    goal: 'Retrieve project details.',
+    context: 'Project detail page, API calls.',
+  },
+  io: {
+    input: GetProjectInputModel,
+    output: ProjectModel,
+    errors: {
+      NOT_FOUND: {
+        description: 'Project not found',
+        http: 404,
+        gqlCode: 'NOT_FOUND',
+        when: 'Project ID is invalid or user lacks access',
+      },
+    },
+  },
+  policy: {
+    auth: 'user',
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'get-project-happy-path',
+        given: ['Project exists'],
+        when: ['User requests project'],
+        then: ['Project details are returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'get-existing',
+        input: { projectId: 'proj-123' },
+        output: { id: 'proj-123', name: 'Website Redesign' },
+      },
+    ],
+  },
+});
+
+/**
+ * Update a project.
+ */
+export const UpdateProjectContract = defineCommand({
+  meta: {
+    key: 'saas.project.update',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'update'],
+    description: 'Update project details.',
+    goal: 'Allow project owners/editors to modify project.',
+    context: 'Project settings page.',
+  },
+  io: {
+    input: UpdateProjectInputModel,
+    output: ProjectModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'project.updated',
+        version: '1.0.0',
+        when: 'Project is updated',
+        payload: ProjectModel,
+      },
+    ],
+    audit: ['project.updated'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'update-project-happy-path',
+        given: ['Project exists'],
+        when: ['User updates description'],
+        then: ['Project is updated', 'ProjectUpdated event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'update-desc',
+        input: { projectId: 'proj-123', description: 'New description' },
+        output: { id: 'proj-123', description: 'New description' },
+      },
+    ],
+  },
+});
+
+/**
+ * Delete a project.
+ */
+export const DeleteProjectContract = defineCommand({
+  meta: {
+    key: 'saas.project.delete',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'delete'],
+    description: 'Delete a project (soft delete).',
+    goal: 'Allow project owners to remove projects.',
+    context: 'Project settings page.',
+  },
+  io: {
+    input: DeleteProjectInputModel,
+    output: DeleteProjectOutputModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'project.deleted',
+        version: '1.0.0',
+        when: 'Project is deleted',
+        payload: ProjectDeletedPayloadModel,
+      },
+    ],
+    audit: ['project.deleted'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'delete-project-happy-path',
+        given: ['Project exists'],
+        when: ['User deletes project'],
+        then: ['Project is deleted', 'ProjectDeleted event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'delete-existing',
+        input: { projectId: 'proj-123' },
+        output: { success: true },
+      },
+    ],
+  },
+});
+
+/**
+ * List organization projects.
+ */
+export const ListProjectsContract = defineQuery({
+  meta: {
+    key: 'saas.project.list',
+    version: '1.0.0',
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'list'],
+    description: 'List projects in the organization.',
+    goal: 'Show all projects user has access to.',
+    context: 'Project list page, dashboard.',
+  },
+  io: {
+    input: ListProjectsInputModel,
+    output: ListProjectsOutputModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'list-projects-happy-path',
+        given: ['Projects exist'],
+        when: ['User lists projects'],
+        then: ['List of projects is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'list-all',
+        input: { limit: 10 },
+        output: { items: [], total: 5 },
+      },
+    ],
+  },
+});

package/src/project/project.presentation.ts

@@ -0,0 +1,58 @@
+import { definePresentation, StabilityEnum } from '@contractspec/lib.contracts';
+import { ProjectModel } from './project.schema';
+
+/**
+ * Presentation for displaying a list of projects.
+ */
+export const ProjectListPresentation = definePresentation({
+  meta: {
+    key: 'saas.project.list',
+    version: '1.0.0',
+    title: 'Project List',
+    description:
+      'List view of projects with status, tags, and last updated info',
+    domain: 'saas-boilerplate',
+    owners: ['@saas-team'],
+    tags: ['project', 'list', 'dashboard'],
+    stability: StabilityEnum.Beta,
+    goal: 'Browse and manage projects',
+    context: 'Project list page',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'ProjectListView',
+    props: ProjectModel,
+  },
+  targets: ['react', 'markdown', 'application/json'],
+  policy: {
+    flags: ['saas.projects.enabled'],
+  },
+});
+
+/**
+ * Presentation for project detail view.
+ */
+export const ProjectDetailPresentation = definePresentation({
+  meta: {
+    key: 'saas.project.detail',
+    version: '1.0.0',
+    title: 'Project Details',
+    description: 'Detailed view of a project with settings and activity',
+    domain: 'saas-boilerplate',
+    owners: ['@saas-team'],
+    tags: ['project', 'detail'],
+    stability: StabilityEnum.Beta,
+    goal: 'View and edit project details',
+    context: 'Project detail page',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'ProjectDetailView',
+  },
+  targets: ['react', 'markdown'],
+  policy: {
+    flags: ['saas.projects.enabled'],
+  },
+});

package/src/project/project.schema.ts

@@ -0,0 +1,147 @@
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import {
+  ProjectStatusSchemaEnum,
+  ProjectStatusFilterEnum,
+} from './project.enum';
+
+/**
+ * A project within an organization.
+ */
+export const ProjectModel = defineSchemaModel({
+  name: 'Project',
+  description: 'A project within an organization',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    createdBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ProjectStatusSchemaEnum, isOptional: false },
+    isPublic: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: false,
+    },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * Input for creating a project.
+ */
+export const CreateProjectInputModel = defineSchemaModel({
+  name: 'CreateProjectInput',
+  description: 'Input for creating a project',
+  fields: {
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    isPublic: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+  },
+});
+
+/**
+ * Input for updating a project.
+ */
+export const UpdateProjectInputModel = defineSchemaModel({
+  name: 'UpdateProjectInput',
+  description: 'Input for updating a project',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    isPublic: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+    status: { type: ProjectStatusSchemaEnum, isOptional: true },
+  },
+});
+
+/**
+ * Input for getting a project.
+ */
+export const GetProjectInputModel = defineSchemaModel({
+  name: 'GetProjectInput',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Input for deleting a project.
+ */
+export const DeleteProjectInputModel = defineSchemaModel({
+  name: 'DeleteProjectInput',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Output for delete operation.
+ */
+export const DeleteProjectOutputModel = defineSchemaModel({
+  name: 'DeleteProjectOutput',
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+  },
+});
+
+/**
+ * Payload for project deleted event.
+ */
+export const ProjectDeletedPayloadModel = defineSchemaModel({
+  name: 'ProjectDeletedPayload',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Input for listing projects.
+ */
+export const ListProjectsInputModel = defineSchemaModel({
+  name: 'ListProjectsInput',
+  description: 'Input for listing projects',
+  fields: {
+    status: { type: ProjectStatusFilterEnum, isOptional: true },
+    search: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    limit: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+      defaultValue: 20,
+    },
+    offset: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+      defaultValue: 0,
+    },
+  },
+});
+
+/**
+ * Output for listing projects.
+ */
+export const ListProjectsOutputModel = defineSchemaModel({
+  name: 'ListProjectsOutput',
+  description: 'Output for listing projects',
+  fields: {
+    projects: { type: ProjectModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+  },
+});

package/src/saas-boilerplate.feature.ts

@@ -0,0 +1,113 @@
+/**
+ * SaaS Boilerplate Feature Module Specification
+ *
+ * Defines the feature module for the SaaS application foundation.
+ */
+import { defineFeature } from '@contractspec/lib.contracts';
+
+/**
+ * SaaS Boilerplate feature module that bundles project management,
+ * billing, and settings operations into an installable feature.
+ */
+export const SaasBoilerplateFeature = defineFeature({
+  meta: {
+    key: 'saas-boilerplate',
+    title: 'SaaS Boilerplate',
+    description:
+      'SaaS application foundation with projects, billing, and settings',
+    domain: 'saas',
+    owners: ['@saas-team'],
+    tags: ['saas', 'projects', 'billing'],
+    stability: 'experimental',
+    version: '1.0.0',
+  },
+
+  // All contract operations included in this feature
+  operations: [
+    // Project operations
+    { key: 'saas.project.create', version: '1.0.0' },
+    { key: 'saas.project.get', version: '1.0.0' },
+    { key: 'saas.project.update', version: '1.0.0' },
+    { key: 'saas.project.delete', version: '1.0.0' },
+    { key: 'saas.project.list', version: '1.0.0' },
+
+    // Billing operations
+    { key: 'saas.billing.subscription.get', version: '1.0.0' },
+    { key: 'saas.billing.usage.record', version: '1.0.0' },
+    { key: 'saas.billing.usage.summary', version: '1.0.0' },
+    { key: 'saas.billing.feature.check', version: '1.0.0' },
+  ],
+
+  // Events emitted by this feature
+  events: [
+    // Project events
+    { key: 'project.created', version: '1.0.0' },
+    { key: 'project.updated', version: '1.0.0' },
+    { key: 'project.deleted', version: '1.0.0' },
+    { key: 'project.archived', version: '1.0.0' },
+
+    // Billing events
+    { key: 'billing.usage.recorded', version: '1.0.0' },
+    { key: 'billing.subscription.changed', version: '1.0.0' },
+    { key: 'billing.limit.reached', version: '1.0.0' },
+  ],
+
+  // Presentations associated with this feature
+  presentations: [
+    { key: 'saas.dashboard', version: '1.0.0' },
+    { key: 'saas.project.list', version: '1.0.0' },
+    { key: 'saas.project.detail', version: '1.0.0' },
+    { key: 'saas.billing.subscription', version: '1.0.0' },
+    { key: 'saas.billing.usage', version: '1.0.0' },
+    { key: 'saas.settings', version: '1.0.0' },
+  ],
+
+  // Link operations to their primary presentations
+  opToPresentation: [
+    {
+      op: { key: 'saas.project.list', version: '1.0.0' },
+      pres: { key: 'saas.project.list', version: '1.0.0' },
+    },
+    {
+      op: { key: 'saas.project.get', version: '1.0.0' },
+      pres: { key: 'saas.project.detail', version: '1.0.0' },
+    },
+    {
+      op: { key: 'saas.billing.subscription.get', version: '1.0.0' },
+      pres: { key: 'saas.billing.subscription', version: '1.0.0' },
+    },
+    {
+      op: { key: 'saas.billing.usage.summary', version: '1.0.0' },
+      pres: { key: 'saas.billing.usage', version: '1.0.0' },
+    },
+  ],
+
+  // Target requirements for multi-surface rendering
+  presentationsTargets: [
+    { key: 'saas.dashboard', version: '1.0.0', targets: ['react', 'markdown'] },
+    {
+      key: 'saas.project.list',
+      version: '1.0.0',
+      targets: ['react', 'markdown', 'application/json'],
+    },
+    {
+      key: 'saas.billing.subscription',
+      version: '1.0.0',
+      targets: ['react', 'markdown'],
+    },
+    {
+      key: 'saas.billing.usage',
+      version: '1.0.0',
+      targets: ['react', 'markdown'],
+    },
+  ],
+
+  // Capability requirements
+  capabilities: {
+    requires: [
+      { key: 'identity', version: '1.0.0' },
+      { key: 'audit-trail', version: '1.0.0' },
+      { key: 'notifications', version: '1.0.0' },
+    ],
+  },
+});

package/src/seeders/index.ts

@@ -0,0 +1,28 @@
+import type { DatabasePort } from '@contractspec/lib.runtime-sandbox';
+
+export async function seedSaasBoilerplate(params: {
+  projectId: string;
+  db: DatabasePort;
+}) {
+  const { projectId, db } = params;
+
+  const existing = await db.query(
+    `SELECT COUNT(*) as count FROM saas_project WHERE "projectId" = $1`,
+    [projectId]
+  );
+  if ((existing.rows[0]?.count as number) > 0) return;
+
+  await db.execute(
+    `INSERT INTO saas_project (id, "projectId", "organizationId", name, description, status, tier)
+     VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+    [
+      'saas_proj_1',
+      projectId,
+      'org_demo',
+      'Demo Project',
+      'A demo SaaS project',
+      'ACTIVE',
+      'PRO',
+    ]
+  );
+}

package/src/settings/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Settings domain - application, organization, and user settings.
+ */
+
+// Enums
+export { SettingsScopeEnum } from './settings.enum';
+
+// Entities
+export { SettingsEntity, FeatureFlagEntity } from './settings.entity';