@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/components/docs/guides/GuideNextjsOneEndpointPage.tsx

@@ -0,0 +1,179 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { StudioPrompt } from '../shared/StudioPrompt';
+
+export function GuideNextjsOneEndpointPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-3">
+        <h1 className="text-4xl font-bold">Next.js: add one endpoint</h1>
+        <p className="text-muted-foreground text-lg">
+          Add ContractSpec to an existing Next.js App Router project by wiring a
+          single operation end-to-end with validation and types.
+        </p>
+      </div>
+
+      <div className="card-subtle space-y-4 p-6">
+        <h2 className="text-2xl font-bold">What you'll build</h2>
+        <ul className="text-muted-foreground space-y-2 text-sm">
+          <li>One OperationSpec with SchemaModel validation.</li>
+          <li>A registry wiring the operation to its handler.</li>
+          <li>A Next.js route handler that exposes the operation.</li>
+        </ul>
+      </div>
+
+      <div className="space-y-6">
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">1) Install core packages</h2>
+          <CodeBlock
+            language="bash"
+            filename="nextjs-install"
+            code={`bun add -D contractspec
+bun add @contractspec/lib.contracts @contractspec/lib.schema`}
+          />
+          <p className="text-muted-foreground text-sm">
+            Expected output: <code>added 3 packages</code> and a lockfile
+            update.
+          </p>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">2) Define the operation spec</h2>
+          <p className="text-muted-foreground text-sm">
+            Create <code>src/contracts/healthcheck.operation.ts</code>:
+          </p>
+          <CodeBlock
+            language="typescript"
+            filename="src/contracts/healthcheck.operation.ts"
+            code={`import { defineQuery } from "@contractspec/lib.contracts/operations";
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+const HealthcheckOutput = new SchemaModel({
+  name: "HealthcheckOutput",
+  fields: {
+    status: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    checkedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+export const HealthcheckQuery = defineQuery({
+  meta: {
+    key: "healthcheck.get",
+    version: "1.0.0",
+    description: "Return service health status",
+    owners: ["@platform.core"],
+    tags: ["health", "observability"],
+  },
+  io: {
+    input: null,
+    output: HealthcheckOutput,
+  },
+  policy: {
+    auth: "public",
+  },
+  transport: {
+    rest: { method: "GET" },
+    gql: { field: "healthcheck_get" },
+    mcp: { toolName: "healthcheck.get.v1" },
+  },
+});`}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">3) Register the operation</h2>
+          <p className="text-muted-foreground text-sm">
+            Create <code>src/contracts/registry.ts</code>:
+          </p>
+          <CodeBlock
+            language="typescript"
+            filename="src/contracts/registry.ts"
+            code={`import {
+  OperationSpecRegistry,
+  installOp,
+} from "@contractspec/lib.contracts/operations";
+import { HealthcheckQuery } from "./healthcheck.operation";
+
+export const registry = new OperationSpecRegistry();
+
+installOp(registry, HealthcheckQuery, async () => ({
+  status: "ok",
+  checkedAt: new Date().toISOString(),
+}));`}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">4) Add the Next.js handler</h2>
+          <p className="text-muted-foreground text-sm">
+            Create <code>app/api/ops/[...route]/route.ts</code>:
+          </p>
+          <CodeBlock
+            language="typescript"
+            filename="app/api/ops/[...route]/route.ts"
+            code={`import { makeNextAppHandler } from "@contractspec/lib.contracts/server/rest-next-app";
+import { registry } from "@/contracts/registry";
+
+const handler = makeNextAppHandler(registry, async () => ({
+  actor: "public",
+  tenantId: "public",
+}));
+
+export { handler as GET, handler as POST };`}
+          />
+          <p className="text-muted-foreground text-sm">
+            Expected output: the route responds at
+            <code> /api/ops/healthcheck.get</code>.
+          </p>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">5) Validate the spec</h2>
+          <CodeBlock
+            language="bash"
+            filename="nextjs-validate"
+            code={`contractspec validate src/contracts/healthcheck.operation.ts`}
+          />
+          <p className="text-muted-foreground text-sm">
+            Expected output: <code>Validation passed</code>.
+          </p>
+        </div>
+
+        <div className="card-subtle space-y-3 p-6">
+          <h3 className="text-lg font-semibold">Example package</h3>
+          <p className="text-muted-foreground text-sm">
+            Use <code>@contractspec/example.lifecycle-dashboard</code> as a
+            lightweight Next.js snippet reference.
+          </p>
+          <CodeBlock
+            language="bash"
+            filename="nextjs-example"
+            code={`# Inspect the example docs
+contractspec examples show lifecycle-dashboard
+
+# Validate all example manifests in this repo
+contractspec examples validate --repo-root .`}
+          />
+        </div>
+
+        <StudioPrompt
+          title="Need team approvals for new endpoints?"
+          body="Studio adds review gates, shared registries, and audit trails after you ship your first endpoint."
+        />
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link
+          href="/docs/guides/spec-validation-and-typing"
+          className="btn-primary"
+        >
+          Next: Spec validation + typing <ChevronRight size={16} />
+        </Link>
+        <Link href="/docs/guides" className="btn-ghost">
+          Back to guides
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/guides/GuideSpecValidationTypingPage.tsx

@@ -0,0 +1,158 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { StudioPrompt } from '../shared/StudioPrompt';
+
+export function GuideSpecValidationTypingPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-3">
+        <h1 className="text-4xl font-bold">Spec-driven validation + typing</h1>
+        <p className="text-muted-foreground text-lg">
+          Define a single operation with SchemaModel, generate validation, and
+          keep your existing handler logic.
+        </p>
+      </div>
+
+      <div className="card-subtle space-y-4 p-6">
+        <h2 className="text-2xl font-bold">What you'll build</h2>
+        <ul className="text-muted-foreground space-y-2 text-sm">
+          <li>One command spec with explicit input/output models.</li>
+          <li>Validation + typing without rewriting your service layer.</li>
+          <li>Clear acceptance scenarios for regression safety.</li>
+        </ul>
+      </div>
+
+      <div className="space-y-6">
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">1) Define the spec</h2>
+          <p className="text-muted-foreground text-sm">
+            Create <code>src/contracts/contact-create.operation.ts</code>:
+          </p>
+          <CodeBlock
+            language="typescript"
+            filename="src/contracts/contact-create.operation.ts"
+            code={`import { defineCommand } from "@contractspec/lib.contracts/operations";
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+const ContactInput = new SchemaModel({
+  name: "ContactInput",
+  fields: {
+    email: { type: ScalarTypeEnum.Email(), isOptional: false },
+    firstName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    lastName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+  },
+});
+
+const ContactOutput = new SchemaModel({
+  name: "ContactOutput",
+  fields: {
+    id: { type: ScalarTypeEnum.String(), isOptional: false },
+    email: { type: ScalarTypeEnum.Email(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+export const ContactCreateCommand = defineCommand({
+  meta: {
+    key: "contact.create",
+    version: "1.0.0",
+    description: "Create a CRM contact",
+    owners: ["@sales"],
+    tags: ["crm", "contacts"],
+  },
+  io: {
+    input: ContactInput,
+    output: ContactOutput,
+  },
+  policy: {
+    auth: "user",
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: "create-contact",
+        given: ["User is authenticated"],
+        when: ["ContactCreateCommand executes"],
+        then: ["Contact is persisted", "Email is validated"],
+      },
+    ],
+  },
+});`}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">2) Wire the handler</h2>
+          <p className="text-muted-foreground text-sm">
+            Keep your existing code. Just ensure the handler returns the output
+            shape defined above.
+          </p>
+          <CodeBlock
+            language="typescript"
+            filename="src/handlers/contact-create.ts"
+            code={`import { ContactCreateCommand } from "@/contracts/contact-create.operation";
+ 
+ export async function handleContactCreate(
+   input: (typeof ContactCreateCommand)["io"]["input"],
+   ctx: { userId: string }
+ ) {
+   // Your existing persistence logic
+   return {
+     id: "contact_123",
+     email: input.email,
+     createdAt: new Date().toISOString(),
+   };
+ }`}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">3) Validate</h2>
+          <CodeBlock
+            language="bash"
+            filename="spec-validation"
+            code={`contractspec validate src/contracts/contact-create.operation.ts`}
+          />
+          <p className="text-muted-foreground text-sm">
+            Expected output: <code>Validation passed</code>.
+          </p>
+        </div>
+
+        <div className="card-subtle space-y-3 p-6">
+          <h3 className="text-lg font-semibold">Example package</h3>
+          <p className="text-muted-foreground text-sm">
+            The CRM Pipeline example includes real specs, handlers, and
+            presentations for contact + deal flows.
+          </p>
+          <CodeBlock
+            language="bash"
+            filename="crm-example"
+            code={`# Build + validate the CRM pipeline example
+cd packages/examples/crm-pipeline
+bun install
+bun run build
+bun run validate`}
+          />
+        </div>
+
+        <StudioPrompt
+          title="Need shared validation policies?"
+          body="Studio lets teams enforce validation policies and review changes before they ship."
+        />
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link
+          href="/docs/guides/generate-docs-clients-schemas"
+          className="btn-primary"
+        >
+          Next: Generate docs + clients <ChevronRight size={16} />
+        </Link>
+        <Link href="/docs/guides" className="btn-ghost">
+          Back to guides
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/guides/GuidesIndexPage.tsx

@@ -0,0 +1,112 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ArrowRight, BookOpen, CheckCircle2 } from 'lucide-react';
+
+const guides = [
+  {
+    title: 'Contract types overview',
+    description:
+      'Learn about the different contract types and when to use each one.',
+    href: '/docs/guides/contract-types',
+    time: '15 min',
+  },
+  {
+    title: 'Next.js: one endpoint',
+    description:
+      'Add ContractSpec to an existing Next.js app by wiring one operation end-to-end.',
+    href: '/docs/guides/nextjs-one-endpoint',
+    time: '25 min',
+  },
+  {
+    title: 'Import existing codebases',
+    description:
+      'Convert your existing API endpoints into ContractSpec contracts for fast onboarding.',
+    href: '/docs/guides/import-existing-codebases',
+    time: '20 min',
+  },
+  {
+    title: 'Spec-driven validation + typing',
+    description:
+      'Define operations with SchemaModel, generate types, and enforce validation without rewrites.',
+    href: '/docs/guides/spec-validation-and-typing',
+    time: '20 min',
+  },
+  {
+    title: 'Generate docs + client schemas',
+    description:
+      'Export docs and OpenAPI for client SDKs and tooling from your specs.',
+    href: '/docs/guides/generate-docs-clients-schemas',
+    time: '20 min',
+  },
+  {
+    title: 'Docs pipeline',
+    description:
+      'Wire generated docs into a reference site with a chunked index.',
+    href: '/docs/guides/docs-generation-pipeline',
+    time: '20 min',
+  },
+  {
+    title: 'CI gating with deterministic diffs',
+    description:
+      'Add ContractSpec CI checks to gate breaking changes and drift.',
+    href: '/docs/guides/ci-contract-diff-gating',
+    time: '15 min',
+  },
+];
+
+export function GuidesIndexPage() {
+  return (
+    <div className="space-y-10">
+      <div className="space-y-3">
+        <h1 className="text-4xl font-bold">Guides</h1>
+        <p className="text-muted-foreground text-lg">
+          Hands-on guides with commands, expected output, and CI-verified
+          example packages.
+        </p>
+      </div>
+
+      <div className="grid gap-4 md:grid-cols-2">
+        {guides.map((guide) => (
+          <Link
+            key={guide.href}
+            href={guide.href}
+            className="card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50"
+          >
+            <div className="flex items-center justify-between">
+              <h2 className="text-xl font-semibold transition-colors group-hover:text-violet-400">
+                {guide.title}
+              </h2>
+              <ArrowRight className="text-violet-400" size={18} />
+            </div>
+            <p className="text-muted-foreground text-sm">{guide.description}</p>
+            <div className="text-muted-foreground flex items-center gap-2 text-xs">
+              <CheckCircle2 size={14} />
+              <span>Target time: {guide.time}</span>
+            </div>
+          </Link>
+        ))}
+      </div>
+
+      <div className="card-subtle space-y-4 p-6">
+        <div className="flex items-center gap-2 text-sm font-semibold tracking-[0.2em] text-violet-400 uppercase">
+          <BookOpen size={16} />
+          How to use the guides
+        </div>
+        <ul className="text-muted-foreground space-y-2 text-sm">
+          <li>Run each guide in a fresh branch or sandbox workspace.</li>
+          <li>Use the linked example package to validate end-to-end.</li>
+          <li>Keep the commands as written to match CI expectations.</li>
+        </ul>
+        <CodeBlock
+          language="bash"
+          filename="guides-quickstart"
+          code={`# list all examples
+contractspec examples list
+
+# validate example packages in this repo
+contractspec examples validate --repo-root .`}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/docs/guides/guides.docblocks.ts

@@ -0,0 +1,113 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const guideDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.guides.index',
+    title: 'Guides',
+    summary: 'Hands-on guides for adopting ContractSpec in real workflows.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/guides',
+    tags: ['guides', 'adoption'],
+    body: `# Guides
+
+Hands-on, runnable guides that map to real adoption scenarios. Each guide includes commands, expected output, and a CI-verified example package.`,
+  },
+  {
+    id: 'docs.guides.nextjs-one-endpoint',
+    title: 'Next.js one endpoint',
+    summary: 'Add ContractSpec to an existing Next.js app with one endpoint.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/guides/nextjs-one-endpoint',
+    tags: ['guides', 'nextjs', 'operations'],
+    body: `# Add ContractSpec to a Next.js app (one endpoint)
+
+Create a single OperationSpec, register it, and expose it through a Next.js App Router handler.`,
+  },
+  {
+    id: 'docs.guides.spec-validation-typing',
+    title: 'Spec validation and typing',
+    summary: 'Define an operation spec with validation and types, no rewrites.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/guides/spec-validation-and-typing',
+    tags: ['guides', 'validation', 'typing'],
+    body: `# Spec-driven validation and typing
+
+Define command/query specs that enforce validation and generate types without rewriting your app.`,
+  },
+  {
+    id: 'docs.guides.docs-clients-schemas',
+    title: 'Generate docs, clients, schemas',
+    summary: 'Generate docs and OpenAPI for client SDKs from specs.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/guides/generate-docs-clients-schemas',
+    tags: ['guides', 'docs', 'openapi'],
+    body: `# Generate docs and client schemas
+
+Use ContractSpec to generate documentation and OpenAPI exports for client SDKs.
+
+## Generate reference docs
+
+1. Regenerate contract artifacts:
+
+\`\`\`bash
+bun contractspec generate
+\`\`\`
+
+2. Build docs output (index + markdown):
+
+\`\`\`bash
+bun docs:generate
+# or versioned output
+bun docs:generate -- --version v1.0.0
+\`\`\``,
+  },
+  {
+    id: 'docs.guides.docs-generation-pipeline',
+    title: 'Docs generation pipeline',
+    summary: 'Wire generated docs into a reference site with chunked indexes.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/guides/docs-generation-pipeline',
+    tags: ['guides', 'docs', 'pipeline'],
+    body: `# Build the docs pipeline
+
+Use ContractSpec to generate reference markdown, build a chunked index, and wire it into your docs routes.
+
+## Generate contract docs
+
+\`\`\`bash
+contractspec generate
+\`\`\`
+
+## Build the docs index
+
+\`\`\`bash
+bun docs:generate
+# versioned output
+bun docs:generate -- --version v1.0.0
+\`\`\`
+
+## Reference wiring
+
+Use the generated manifest and chunks under \`docs-index.manifest.json\` and \`docs-index.*.json\` to load the index at runtime.`,
+  },
+  {
+    id: 'docs.guides.ci-contract-diff-gating',
+    title: 'CI gating for contract diffs',
+    summary: 'Gate changes with deterministic diffs and CI checks.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/guides/ci-contract-diff-gating',
+    tags: ['guides', 'ci', 'diff'],
+    body: `# CI gating with deterministic diffs
+
+Run ContractSpec CI checks to detect drift and breaking changes before merge.`,
+  },
+];
+
+registerDocBlocks(guideDocBlocks);

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

@@ -0,0 +1,10 @@
+import './guides.docblocks';
+
+export { GuidesIndexPage } from './GuidesIndexPage';
+export { GuideContractTypesPage } from './GuideContractTypesPage';
+export { GuideDocsPipelinePage } from './GuideDocsPipelinePage';
+export { GuideNextjsOneEndpointPage } from './GuideNextjsOneEndpointPage';
+export { GuideSpecValidationTypingPage } from './GuideSpecValidationTypingPage';
+export { GuideGenerateDocsClientsSchemasPage } from './GuideGenerateDocsClientsSchemasPage';
+export { GuideCIDiffGatingPage } from './GuideCIDiffGatingPage';
+export { GuideImportExistingCodebasesPage } from './GuideImportExistingCodebasesPage';

package/src/components/docs/index.ts

@@ -0,0 +1,58 @@
+// Documentation pages organized by domain
+
+// Root docs page
+export { DocsIndexPage } from './DocsIndexPage';
+
+// Getting Started
+export * from './getting-started';
+
+// Specs
+export * from './specs';
+
+// Libraries
+export * from './libraries';
+
+// Architecture
+export * from './architecture';
+
+// Advanced
+export * from './advanced';
+
+// Safety
+export * from './safety';
+
+// Integrations
+export * from './integrations';
+
+// Guides
+export * from './guides';
+
+// Examples
+export * from './examples';
+
+// Reference
+export * from './reference';
+
+// Generated reference artifacts
+export * from './generated';
+
+// Intent Pages
+export * from './intent';
+
+// Ecosystem
+export * from './ecosystem';
+
+// Knowledge
+export * from './knowledge';
+
+// Comparison
+export * from './comparison';
+
+// Ops
+export * from './ops';
+
+// Manifesto
+export { ManifestoPage } from './manifesto/ManifestoPage';
+
+// Studio
+export * from './studio';

package/src/components/docs/integrations/IntegrationsCircuitBreakersPage.tsx

@@ -0,0 +1,40 @@
+// export const metadata: Metadata = {
+//   title: 'Circuit Breakers for Integrations | ContractSpec',
+//   description: 'How to wrap external integrations with circuit breakers.',
+// };
+
+export function IntegrationsCircuitBreakersPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Integration Circuit Breakers</h1>
+        <p className="text-muted-foreground text-lg">
+          External APIs are the most common source of instability. Wrap every
+          integration call in a circuit breaker to protect your system.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Pattern</h2>
+        <p>
+          Create a dedicated circuit breaker instance for each external service.
+          This ensures that a failure in Stripe doesn't trigger the circuit
+          breaker for Twilio.
+        </p>
+        <pre className="bg-muted rounded-lg border p-4 text-sm">
+          {`// integrations/stripe.ts
+import { CircuitBreaker } from '@contractspec/lib.resilience/circuit-breaker';
+
+const stripeBreaker = new CircuitBreaker({
+  failureThreshold: 10,
+  resetTimeoutMs: 60000,
+});
+
+export async function createCharge(amount: number) {
+  return stripeBreaker.execute(() => stripe.charges.create({ amount }));
+}`}
+        </pre>
+      </div>
+    </div>
+  );
+}