@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/components/docs/safety/SafetySecurityTrustPage.tsx

@@ -0,0 +1,100 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function SafetySecurityTrustPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Security & Trust</h1>
+        <p className="text-muted-foreground">
+          ContractSpec focuses on deterministic, auditable software delivery.
+          This page summarizes our security posture and trust commitments so
+          teams can adopt with clarity.
+        </p>
+      </div>
+
+      <div className="card-subtle space-y-4 p-6">
+        <h2 className="text-2xl font-bold">Security policy</h2>
+        <p className="text-muted-foreground text-sm">
+          We publish a dedicated security policy that explains how to report
+          vulnerabilities and how we respond.
+        </p>
+        <Link href="/SECURITY.md" className="btn-primary">
+          Read the security policy <ChevronRight size={16} />
+        </Link>
+      </div>
+
+      <div className="grid gap-4 md:grid-cols-2">
+        <div className="card-subtle space-y-3 p-6">
+          <h3 className="text-lg font-semibold">Release hygiene</h3>
+          <p className="text-muted-foreground text-sm">
+            We ship with deterministic CI, changesets, and contract validation
+            so teams can trust every release.
+          </p>
+          <ul className="text-muted-foreground space-y-2 text-sm">
+            <li>Changesets required for published packages.</li>
+            <li>CI gate for contract validation and drift detection.</li>
+            <li>Rollback-friendly release process.</li>
+          </ul>
+        </div>
+
+        <div className="card-subtle space-y-3 p-6">
+          <h3 className="text-lg font-semibold">Data handling</h3>
+          <p className="text-muted-foreground text-sm">
+            ContractSpec promotes strict data classification and policy-driven
+            access. Specs can tag sensitive fields for enforcement.
+          </p>
+          <ul className="text-muted-foreground space-y-2 text-sm">
+            <li>Schema-level sensitivity tags.</li>
+            <li>Policy Decision Point enforcement.</li>
+            <li>Audit logs for operational traceability.</li>
+          </ul>
+        </div>
+      </div>
+
+      <div className="grid gap-4 md:grid-cols-2">
+        <div className="card-subtle space-y-3 p-6">
+          <h3 className="text-lg font-semibold">Supply chain</h3>
+          <p className="text-muted-foreground text-sm">
+            We track dependency updates and keep the monorepo build
+            reproducible.
+          </p>
+          <ul className="text-muted-foreground space-y-2 text-sm">
+            <li>Dependabot + Renovate-style updates where available.</li>
+            <li>Signed release artifacts planned for Studio release cycles.</li>
+            <li>Transparent changelogs for every package.</li>
+          </ul>
+        </div>
+
+        <div className="card-subtle space-y-3 p-6">
+          <h3 className="text-lg font-semibold">Responsible disclosure</h3>
+          <p className="text-muted-foreground text-sm">
+            We respond quickly to security reports and coordinate fixes before
+            public disclosure.
+          </p>
+          <ul className="text-muted-foreground space-y-2 text-sm">
+            <li>Security response within 5 business days.</li>
+            <li>Private disclosure via security@contractspec.io.</li>
+            <li>Credit for researchers (with permission).</li>
+          </ul>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Next steps</h2>
+        <p className="text-muted-foreground">
+          Explore the broader safety controls or read the roadmap to see
+          upcoming trust investments.
+        </p>
+        <div className="flex flex-wrap gap-4 pt-4">
+          <Link href="/docs/safety" className="btn-ghost">
+            Safety overview <ChevronRight size={16} />
+          </Link>
+          <Link href="/ROADMAP.md" className="btn-ghost">
+            Roadmap <ChevronRight size={16} />
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/safety/SafetySigningPage.tsx

@@ -0,0 +1,56 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Spec Signing: ContractSpec Docs',
+//   description: 'Learn how spec signing ensures security and auditability.',
+// };
+
+export function SafetySigningPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-2">
+        <h1 className="text-4xl font-bold">Spec Signing</h1>
+        <p className="text-muted-foreground text-lg">
+          Signing ensures specs haven't been tampered with and provides an audit
+          trail of all changes.
+        </p>
+      </div>
+
+      <div className="space-y-6">
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">How it works</h2>
+          <p className="text-muted-foreground">
+            Every spec is cryptographically signed before deployment. The
+            signature proves that the spec hasn't been modified since it was
+            signed and creates a permanent record of who deployed it and when.
+          </p>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Signing a spec</h2>
+          <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+            <pre>{`contractspec sign app.spec.ts --key ~/.contractspec/key.pem
+contractspec deploy --signed app.spec.ts.signed`}</pre>
+          </div>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Verifying signatures</h2>
+          <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+            <pre>{`contractspec verify app.spec.ts.signed
+# Output: ✓ Signature valid
+# Signed by: alice@example.com
+# Timestamp: 2024-11-08T10:30:00Z`}</pre>
+          </div>
+        </div>
+
+        <div className="flex items-center gap-4 pt-4">
+          <Link href="/docs/safety/pdp" className="btn-primary">
+            Next: Policy Decision Points <ChevronRight size={16} />
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/safety/SafetyTenantIsolationPage.tsx

@@ -0,0 +1,59 @@
+// export const metadata: Metadata = {
+//   title: 'Tenant Isolation Safety | ContractSpec',
+//   description: 'How to ensure data never leaks between tenants.',
+// };
+
+export function SafetyTenantIsolationPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Tenant Isolation</h1>
+        <p className="text-muted-foreground text-lg">
+          Preventing cross-tenant data leaks is the #1 security priority for any
+          SaaS. ContractSpec employs "Defense in Depth" to ensure safety.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Layer 1: RLS Middleware</h2>
+        <p>
+          The primary defense is the Prisma middleware that rewrites queries to
+          include <code>WHERE tenantId = ?</code>. This protects against
+          developer error (forgetting to filter).
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Layer 2: Isolation Validator</h2>
+        <p>
+          For high-security environments, you can use the{' '}
+          <code>IsolationValidator</code> in your test suite to verify that
+          every query generated by your operations actually includes the tenant
+          ID.
+        </p>
+        <pre className="bg-muted rounded-lg border p-4 text-sm">
+          {`import { IsolationValidator } from '@contractspec/lib.multi-tenancy/isolation';
+
+test('findUser query is isolated', () => {
+  const isValid = IsolationValidator.validateQuery(
+    'User',
+    'findFirst',
+    args,
+    'tenant-123'
+  );
+  expect(isValid).toBe(true);
+});`}
+        </pre>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Layer 3: Policy Engine</h2>
+        <p>
+          The Policy Decision Point (PDP) verifies that the authenticated user
+          actually belongs to the requested tenant before any operation logic
+          runs.
+        </p>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/safety/index.ts

@@ -0,0 +1,7 @@
+export { SafetyOverviewPage } from './SafetyOverviewPage';
+export { SafetySigningPage } from './SafetySigningPage';
+export { SafetyAuditingPage } from './SafetyAuditingPage';
+export { SafetyMigrationsPage } from './SafetyMigrationsPage';
+export { SafetyPDPPage } from './SafetyPDPPage';
+export { SafetyTenantIsolationPage } from './SafetyTenantIsolationPage';
+export { SafetySecurityTrustPage } from './SafetySecurityTrustPage';

package/src/components/docs/shared/StudioPrompt.tsx

@@ -0,0 +1,25 @@
+import Link from '@contractspec/lib.ui-link';
+
+interface StudioPromptProps {
+  title?: string;
+  body?: string;
+  ctaLabel?: string;
+  href?: string;
+}
+
+export function StudioPrompt({
+  title = 'Need managed policy gates and approvals?',
+  body = 'ContractSpec Studio adds policy gates, remote registry workflows, and audit trails when you are ready to scale adoption.',
+  ctaLabel = 'Join Studio waitlist',
+  href = '/contact#waitlist',
+}: StudioPromptProps) {
+  return (
+    <div className="card-subtle space-y-3 p-6">
+      <h3 className="text-lg font-semibold">{title}</h3>
+      <p className="text-muted-foreground text-sm">{body}</p>
+      <Link href={href} className="btn-primary">
+        {ctaLabel}
+      </Link>
+    </div>
+  );
+}

package/src/components/docs/specs/SpecsCapabilitiesPage.tsx

@@ -0,0 +1,131 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Capabilities: ContractSpec Docs',
+//   description: 'Learn how to define capabilities in ContractSpec.',
+// };
+
+export function SpecsCapabilitiesPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-2">
+        <h1 className="text-4xl font-bold">Capabilities</h1>
+        <p className="text-muted-foreground text-lg">
+          Capabilities are the core building block of ContractSpec. They define
+          what your app can do.
+        </p>
+      </div>
+
+      <div className="space-y-6">
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Overview</h2>
+          <p className="text-muted-foreground">
+            A ContractSpec (or Capability) is a typed, declarative description
+            of an operation. It defines the operation's name, version, inputs,
+            outputs, policies, and side effects. Runtime adapters automatically
+            serve these as REST/GraphQL/MCP endpoints with full validation and
+            policy enforcement.
+          </p>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Defining a Command (Write)</h2>
+          <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+            <pre>{`import { defineCommand } from '@contractspec/lib.contracts';
+import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+
+const TransferFundsInput = new SchemaModel({
+  name: 'TransferFundsInput',
+  fields: {
+    recipient: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    amount: { type: ScalarTypeEnum.PositiveNumber(), isOptional: false },
+  },
+});
+
+const TransferFundsOutput = new SchemaModel({
+  name: 'TransferFundsOutput',
+  fields: {
+    transactionId: { type: ScalarTypeEnum.String(), isOptional: false },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+export const TransferFunds = defineCommand({
+  meta: {
+    key: 'wallet.transferFunds',
+    version: '1.0.0',
+    description: 'Transfer funds to another user',
+    goal: 'Enable peer-to-peer payments',
+    context: 'Requires sufficient balance',
+    owners: ['team-payments'],
+    tags: ['payments'],
+    stability: 'stable',
+  },
+  io: {
+    input: TransferFundsInput,
+    output: TransferFundsOutput,
+  },
+  policy: {
+    auth: 'user',
+    flags: ['payments_enabled'],
+  },
+});`}</pre>
+          </div>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Schema Types</h2>
+          <p className="text-muted-foreground">
+            ContractSpec uses <code>@contractspec/lib.schema</code> for I/O
+            definitions. This provides Zod validation, GraphQL types, and JSON
+            Schema from a single source.
+          </p>
+          <ul className="text-muted-foreground space-y-2">
+            <li>
+              •{' '}
+              <code className="bg-background/50 rounded px-2 py-1">
+                ScalarTypeEnum.NonEmptyString()
+              </code>{' '}
+              - Non-empty text
+            </li>
+            <li>
+              •{' '}
+              <code className="bg-background/50 rounded px-2 py-1">
+                ScalarTypeEnum.PositiveNumber()
+              </code>{' '}
+              - Positive numbers
+            </li>
+            <li>
+              •{' '}
+              <code className="bg-background/50 rounded px-2 py-1">
+                ScalarTypeEnum.DateTime()
+              </code>{' '}
+              - ISO 8601 timestamps
+            </li>
+            <li>
+              •{' '}
+              <code className="bg-background/50 rounded px-2 py-1">
+                ScalarTypeEnum.Email()
+              </code>{' '}
+              - Valid email addresses
+            </li>
+            <li>
+              •{' '}
+              <code className="bg-background/50 rounded px-2 py-1">
+                defineEnum(...)
+              </code>{' '}
+              - Type-safe enums
+            </li>
+          </ul>
+        </div>
+
+        <div className="flex items-center gap-4 pt-4">
+          <Link href="/docs/specs/dataviews" className="btn-primary">
+            Next: DataViews <ChevronRight size={16} />
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/specs/SpecsDataViewsPage.tsx

@@ -0,0 +1,199 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'DataViews: ContractSpec Docs',
+//   description:
+//     'Learn how to define data views for querying, filtering, and presenting data in ContractSpec.',
+// };
+
+export function SpecsDataViewsPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">DataViews</h1>
+        <p className="text-muted-foreground">
+          A <strong>DataViewSpec</strong> describes how data should be queried,
+          filtered, sorted, and presented to users. Runtime adapters execute
+          optimized database queries and serve list views, detail views, and
+          search interfaces while respecting policy constraints.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Core concepts</h2>
+        <div className="space-y-3">
+          <div>
+            <h3 className="text-lg font-semibold">Data sources</h3>
+            <p className="text-muted-foreground">
+              A DataView connects to one or more data sources—databases, APIs,
+              or other capabilities. You specify the source and the fields you
+              want to expose.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Filtering</h3>
+            <p className="text-muted-foreground">
+              Define filters that users can apply to narrow down results.
+              Filters can be simple (e.g., "status equals 'active'") or complex
+              (e.g., "created within the last 30 days AND assigned to current
+              user").
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Sorting</h3>
+            <p className="text-muted-foreground">
+              Specify which fields can be sorted and the default sort order.
+              ContractSpec generates efficient database queries with proper
+              indexes.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Pagination</h3>
+            <p className="text-muted-foreground">
+              DataViews automatically support pagination to handle large
+              datasets. You can configure page size limits and cursor-based or
+              offset-based pagination.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Aggregations</h3>
+            <p className="text-muted-foreground">
+              Compute aggregates like counts, sums, averages, and group-by
+              operations. These are useful for dashboards and summary views.
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Example DataViewSpec</h2>
+        <p className="text-muted-foreground">
+          Here's a DataView for listing orders in TypeScript:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`import { defineDataView } from '@contractspec/lib.contracts';
+import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+
+export const OrderList = defineDataView({
+  meta: {
+    key: 'order.list',
+    version: '1.0.0',
+    description: 'List of recent orders',
+  },
+  source: {
+    type: 'database',
+    table: 'orders',
+  },
+  fields: [
+    { name: 'orderId', type: 'uuid', sortable: true },
+    { name: 'customerName', type: 'string', searchable: true },
+    { name: 'total', type: 'number', sortable: true },
+    { 
+      name: 'status', 
+      type: 'enum', 
+      values: ['pending', 'processing', 'shipped'],
+      filterable: true 
+    },
+    { 
+      name: 'createdAt', 
+      type: 'timestamp', 
+      sortable: true, 
+      defaultSort: 'desc' 
+    },
+  ],
+  filters: [
+    { name: 'status', field: 'status', operator: 'in' },
+    { name: 'dateRange', field: 'createdAt', operator: 'between' },
+    { name: 'minTotal', field: 'total', operator: 'gte' },
+  ],
+  pagination: {
+    type: 'cursor',
+    defaultPageSize: 50,
+    maxPageSize: 200,
+  },
+});`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Policy integration</h2>
+        <p className="text-muted-foreground">
+          DataViews automatically enforce{' '}
+          <Link
+            href="/docs/specs/policy"
+            className="text-violet-400 hover:text-violet-300"
+          >
+            PolicySpecs
+          </Link>
+          . If a user doesn't have permission to see certain fields, those
+          fields are automatically filtered out or redacted. If a user can only
+          see their own data, the query is automatically scoped.
+        </p>
+        <p className="text-muted-foreground">
+          This means you define the data view once, and it works correctly for
+          all users based on their permissions—no need to write separate queries
+          for different roles.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Served outputs</h2>
+        <p className="text-muted-foreground">
+          From a DataViewSpec, ContractSpec serves:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>Database queries</strong> – Optimized SQL or NoSQL queries
+            executed at runtime
+          </li>
+          <li>
+            <strong>API endpoints</strong> – RESTful or GraphQL endpoints for
+            fetching data
+          </li>
+          <li>
+            <strong>UI components</strong> – List views, tables, cards, and
+            detail views
+          </li>
+          <li>
+            <strong>Search interfaces</strong> – Full-text search with
+            autocomplete
+          </li>
+          <li>
+            <strong>Export functions</strong> – CSV, JSON, or Excel exports
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Best practices</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Only expose fields that users actually need—this improves
+            performance and security.
+          </li>
+          <li>Use appropriate indexes for sortable and filterable fields.</li>
+          <li>
+            Set reasonable pagination limits to prevent performance issues.
+          </li>
+          <li>
+            Use aggregations sparingly—they can be expensive on large datasets.
+          </li>
+          <li>
+            Test DataViews with realistic data volumes to ensure they perform
+            well.
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/specs/capabilities" className="btn-ghost">
+          Previous: Capabilities
+        </Link>
+        <Link href="/docs/specs/workflows" className="btn-primary">
+          Next: Workflows <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}