@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/components/docs/getting-started/HelloWorldPage.tsx

@@ -0,0 +1,187 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { CodeBlock } from '@contractspec/lib.design-system';
+
+export function HelloWorldPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-2">
+        <h1 className="text-4xl font-bold">Your First Operation</h1>
+        <p className="text-muted-foreground text-lg">
+          Build a payment capture operation with policy enforcement in under 10
+          minutes.
+        </p>
+      </div>
+
+      <div className="space-y-6">
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">What you'll build</h2>
+          <p className="text-muted-foreground">
+            A real-world payment processing operation that validates input,
+            enforces business rules, integrates with Stripe, and audits every
+            transaction. This is production-ready code, not a toy example.
+          </p>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">1. Define the operation spec</h2>
+          <p className="text-muted-foreground">
+            Create <code>lib/specs/billing/capture-payment.ts</code>:
+          </p>
+          <CodeBlock
+            language="typescript"
+            filename="lib/specs/billing/capture-payment.ts"
+            code={`import { defineCommand } from '@contractspec/lib.contracts';
+import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+
+const CapturePaymentInput = new SchemaModel({
+  name: 'CapturePaymentInput',
+  fields: {
+    invoiceId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    amount: { type: ScalarTypeEnum.PositiveNumber(), isOptional: false },
+    currency: { type: ScalarTypeEnum.String(), isOptional: false },
+    paymentMethodId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+  },
+});
+
+const PaymentResult = new SchemaModel({
+  name: 'PaymentResult',
+  fields: {
+    transactionId: { type: ScalarTypeEnum.String(), isOptional: false },
+    status: { type: ScalarTypeEnum.String(), isOptional: false },
+    receiptUrl: { type: ScalarTypeEnum.String(), isOptional: true },
+  },
+});
+
+export const CapturePayment = defineCommand({
+  meta: {
+    key: 'billing.capturePayment',
+    version: '1.0.0',
+    description: 'Process a payment for an invoice',
+    goal: 'Capture funds from customer payment method',
+    context: 'Called when customer confirms purchase',
+    owners: ['team-billing'],
+    tags: ['payments', 'stripe', 'critical'],
+    stability: 'stable',
+  },
+  io: {
+    input: CapturePaymentInput,
+    output: PaymentResult,
+  },
+  policy: {
+    auth: 'user',
+    rules: [
+      { resource: 'invoice', action: 'pay', condition: 'owner' },
+    ],
+  },
+});`}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">2. Implement the handler</h2>
+          <p className="text-muted-foreground">
+            Create <code>lib/handlers/billing/capture-payment.ts</code>:
+          </p>
+          <CodeBlock
+            language="typescript"
+            filename="lib/handlers/billing/capture-payment.ts"
+            code={`import { CapturePayment } from '@/lib/specs/billing/capture-payment';
+import { stripe } from '@/lib/integrations/stripe';
+import { db } from '@/lib/db';
+
+export async function handleCapturePayment(input, ctx) {
+  // 1. Verify invoice exists and belongs to user
+  const invoice = await db.invoice.findUnique({
+    where: { id: input.invoiceId, userId: ctx.userId },
+  });
+
+  if (!invoice) throw new Error('Invoice not found');
+  if (invoice.status === 'paid') throw new Error('Already paid');
+
+  // 2. Create Stripe payment intent
+  const paymentIntent = await stripe.paymentIntents.create({
+    amount: Math.round(input.amount * 100),
+    currency: input.currency,
+    payment_method: input.paymentMethodId,
+    confirm: true,
+    metadata: { invoiceId: input.invoiceId },
+  });
+
+  // 3. Update invoice status
+  await db.invoice.update({
+    where: { id: input.invoiceId },
+    data: {
+      status: 'paid',
+      paidAt: new Date(),
+      transactionId: paymentIntent.id,
+    },
+  });
+
+  return {
+    transactionId: paymentIntent.id,
+    status: paymentIntent.status,
+    receiptUrl: paymentIntent.charges.data[0]?.receipt_url,
+  };
+}`}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">3. Register and serve</h2>
+          <p className="text-muted-foreground">
+            Wire it up in <code>lib/registry.ts</code> and{' '}
+            <code>app/api/ops/[...route]/route.ts</code>:
+          </p>
+          <CodeBlock
+            language="typescript"
+            filename="lib/registry.ts"
+            code={`import { OperationSpecRegistry, installOp } from '@contractspec/lib.contracts';
+import { CapturePayment } from './specs/billing/capture-payment';
+import { handleCapturePayment } from './handlers/billing/capture-payment';
+
+export const registry = new OperationSpecRegistry();
+installOp(registry, CapturePayment, handleCapturePayment);`}
+          />
+          <CodeBlock
+            language="typescript"
+            filename="app/api/ops/[...route]/route.ts"
+            code={`import { makeNextAppHandler } from '@contractspec/lib.contracts/server/rest-next-app';
+import { registry } from '@/lib/registry';
+import { auth } from '@/lib/auth';
+
+const handler = makeNextAppHandler(registry, async (req) => {
+  const session = await auth(req);
+  return { actor: 'user', userId: session.userId, tenantId: session.tenantId };
+});
+
+export { handler as GET, handler as POST };`}
+          />
+        </div>
+
+        <div className="card-subtle space-y-4 p-6">
+          <h3 className="font-bold">What you just built:</h3>
+          <ul className="text-muted-foreground space-y-2 text-sm">
+            <li>
+              Type-safe API endpoint at{' '}
+              <code>/api/ops/billing.capturePayment</code>
+            </li>
+            <li>
+              Automatic input validation (amount must be positive, IDs required)
+            </li>
+            <li>Policy enforcement—only invoice owner can pay</li>
+            <li>Stripe integration with error handling</li>
+            <li>Database transaction with audit trail</li>
+            <li>Same spec works with GraphQL, MCP, or webhooks</li>
+          </ul>
+        </div>
+
+        <div className="flex items-center gap-4 pt-4">
+          <Link href="/docs/getting-started/dataviews" className="btn-primary">
+            Next: Display Data with DataViews <ChevronRight size={16} />
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/getting-started/InstallationPage.tsx

@@ -0,0 +1,94 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+
+export function InstallationPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-2">
+        <h1 className="text-4xl font-bold">Installation</h1>
+        <p className="text-muted-foreground text-lg">
+          Add ContractSpec to your existing Next.js or Bun project, or start
+          fresh.
+        </p>
+      </div>
+
+      <div className="space-y-6">
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Prerequisites</h2>
+          <ul className="text-muted-foreground space-y-2">
+            <li>Node.js 20+ (or Bun 1.0+)</li>
+            <li>Existing Next.js app or Bun HTTP server</li>
+            <li>PostgreSQL database (for persistence)</li>
+          </ul>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Install Core Libraries</h2>
+          <p className="text-muted-foreground">
+            Add the contracts runtime and your choice of adapter:
+          </p>
+          <InstallCommand
+            package={[
+              '@contractspec/lib.contracts',
+              '@contractspec/lib.schema',
+            ]}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">For Next.js projects</h2>
+          <InstallCommand package="@contractspec/lib.contracts" />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">For database models</h2>
+          <InstallCommand
+            package={[
+              '@contractspec/app.cli-database',
+              'prisma',
+              '@prisma/client',
+            ]}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Set up your project</h2>
+          <p className="text-muted-foreground">
+            Initialize a new ContractSpec project structure:
+          </p>
+          <CodeBlock
+            language="bash"
+            filename="installation-init"
+            code={`bunx contractspec init
+# Follow the interactive prompts to configure your project`}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Initialize the database</h2>
+          <p className="text-muted-foreground">
+            If using Prisma, set up your schema and generate the client:
+          </p>
+          <CodeBlock
+            language="bash"
+            filename="installation-prisma"
+            code={`bunx prisma init
+# Edit prisma/schema.prisma with your models
+bunx prisma generate
+bunx prisma migrate dev --name init`}
+          />
+        </div>
+
+        <div className="flex items-center gap-4 pt-4">
+          <Link
+            href="/docs/getting-started/hello-world"
+            className="btn-primary"
+          >
+            Next: First Operation <ChevronRight size={16} />
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/getting-started/StartHerePage.tsx

@@ -0,0 +1,76 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+
+export function StartHerePage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-2">
+        <h1 className="text-4xl font-bold">Start here</h1>
+        <p className="text-muted-foreground text-lg">
+          A fast onboarding path from install to your first generated contract.
+        </p>
+      </div>
+
+      <div className="space-y-6">
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Install the CLI</h2>
+          <InstallCommand package="contractspec" dev />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Add core libraries</h2>
+          <InstallCommand
+            package={[
+              '@contractspec/lib.contracts',
+              '@contractspec/lib.schema',
+            ]}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Initialize your project</h2>
+          <CodeBlock
+            language="bash"
+            filename="start-here-init"
+            code={`bunx contractspec init`}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Create your first contract</h2>
+          <CodeBlock
+            language="bash"
+            filename="start-here-create"
+            code={`contractspec create --type operation`}
+          />
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Generate implementation</h2>
+          <CodeBlock
+            language="bash"
+            filename="start-here-build"
+            code={`contractspec build src/contracts/mySpec.ts
+contractspec validate src/contracts/mySpec.ts`}
+          />
+        </div>
+      </div>
+
+      <div className="flex flex-wrap items-center gap-3 pt-2">
+        <Link href="/docs/getting-started/hello-world" className="btn-primary">
+          Next: Hello World <ChevronRight size={16} />
+        </Link>
+        <Link
+          href="/docs/getting-started/troubleshooting"
+          className="btn-ghost"
+        >
+          Troubleshooting
+        </Link>
+        <Link href="/docs/getting-started/compatibility" className="btn-ghost">
+          Compatibility
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/getting-started/TroubleshootingPage.tsx

@@ -0,0 +1,81 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { CodeBlock } from '@contractspec/lib.design-system';
+
+export function TroubleshootingPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-2">
+        <h1 className="text-4xl font-bold">Troubleshooting</h1>
+        <p className="text-muted-foreground text-lg">
+          Common issues and fixes when installing or generating with
+          ContractSpec.
+        </p>
+      </div>
+
+      <div className="space-y-6">
+        <div className="card-subtle space-y-3 p-6">
+          <h2 className="text-2xl font-bold">Command not found</h2>
+          <ul className="text-muted-foreground space-y-2">
+            <li>Reinstall the CLI and ensure it is in your PATH.</li>
+            <li>Confirm Node.js 20+ or Bun 1.0+ is installed.</li>
+          </ul>
+        </div>
+
+        <div className="card-subtle space-y-3 p-6">
+          <h2 className="text-2xl font-bold">Specs not discovered</h2>
+          <ul className="text-muted-foreground space-y-2">
+            <li>
+              Run <code>contractspec list</code> to see discovered specs.
+            </li>
+            <li>Verify your spec path conventions in .contractsrc.json.</li>
+          </ul>
+        </div>
+
+        <div className="card-subtle space-y-3 p-6">
+          <h2 className="text-2xl font-bold">Build or validate fails</h2>
+          <ul className="text-muted-foreground space-y-2">
+            <li>
+              Run <code>contractspec validate</code> to surface schema errors.
+            </li>
+            <li>Check that generated files were not manually edited.</li>
+          </ul>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Diagnostics</h2>
+          <CodeBlock
+            language="bash"
+            filename="troubleshooting-diagnostics"
+            code={`contractspec --version
+contractspec list
+contractspec validate src/contracts/mySpec.ts`}
+          />
+        </div>
+
+        <div className="card-subtle space-y-3 p-6">
+          <h2 className="text-2xl font-bold">Still blocked?</h2>
+          <ul className="text-muted-foreground space-y-2">
+            <li>
+              Confirm compatibility requirements for runtime and framework.
+            </li>
+            <li>Re-run builds on a clean branch to isolate changes.</li>
+            <li>Use a new spec and minimal adapter to validate setup.</li>
+          </ul>
+        </div>
+      </div>
+
+      <div className="flex flex-wrap items-center gap-3 pt-2">
+        <Link href="/docs/getting-started/start-here" className="btn-ghost">
+          Start here
+        </Link>
+        <Link href="/docs/getting-started/compatibility" className="btn-ghost">
+          Compatibility
+        </Link>
+        <Link href="/docs/getting-started/installation" className="btn-primary">
+          Next: Installation <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/getting-started/VSCodeExtensionPage.tsx

@@ -0,0 +1,248 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight, ExternalLink } from 'lucide-react';
+import { CodeBlock } from '@contractspec/lib.design-system';
+
+export function VSCodeExtensionPage() {
+  const features = [
+    {
+      category: 'Core Functionality',
+      items: [
+        'Real-time validation with instant feedback on spec errors',
+        'Build/Scaffold handlers and components from specs',
+        'Interactive spec creation wizard',
+        'Watch mode for auto-rebuild on changes',
+        'Sync all specs in workspace with one command',
+      ],
+    },
+    {
+      category: 'Visual Navigation',
+      items: [
+        'Specs Explorer sidebar with organized tree view',
+        'Dependencies view to visualize spec relationships',
+        'Build Results tracking with history',
+        'Circular dependency detection',
+      ],
+    },
+    {
+      category: 'Comparison & Export',
+      items: [
+        'Semantic and text diff between specs',
+        'Git comparison with baseline branches',
+        'OpenAPI 3.1 specification export',
+      ],
+    },
+  ];
+
+  const commands = [
+    {
+      name: 'Create New Spec',
+      description: 'Interactive wizard to create specs',
+    },
+    {
+      name: 'Validate Current Spec',
+      description: 'Validate the currently open spec',
+    },
+    {
+      name: 'Build/Scaffold from Current Spec',
+      description: 'Generate handler/component',
+    },
+    { name: 'Toggle Watch Mode', description: 'Auto-rebuild on changes' },
+    { name: 'Sync All Specs', description: 'Build all specs in workspace' },
+    {
+      name: 'Analyze Spec Dependencies',
+      description: 'Visualize spec dependencies',
+    },
+    {
+      name: 'Compare Specs',
+      description: 'Semantic or text diff between specs',
+    },
+    {
+      name: 'Export to OpenAPI',
+      description: 'Generate OpenAPI specification',
+    },
+  ];
+
+  return (
+    <div className="space-y-8">
+      <div className="space-y-2">
+        <h1 className="text-4xl font-bold">VS Code Extension</h1>
+        <p className="text-muted-foreground text-lg">
+          Spec-first development directly in VS Code. Validate, scaffold, and
+          explore your contract specifications with real-time feedback.
+        </p>
+      </div>
+
+      <div className="flex flex-wrap gap-3">
+        <a
+          href="https://marketplace.visualstudio.com/items?itemName=lssm.vscode-contractspec"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="btn-primary inline-flex items-center gap-2"
+        >
+          Install Extension <ExternalLink size={16} />
+        </a>
+        <a
+          href="vscode:extension/lssm.vscode-contractspec"
+          className="btn-ghost inline-flex items-center gap-2"
+        >
+          Open in VS Code
+        </a>
+      </div>
+
+      <div className="space-y-6">
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Installation</h2>
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">
+              <strong>Option 1:</strong> Install from VS Code Marketplace
+            </p>
+            <CodeBlock
+              language="bash"
+              code="code --install-extension lssm.vscode-contractspec"
+            />
+            <p className="text-muted-foreground mt-4 text-sm">
+              <strong>Option 2:</strong> Search for &quot;ContractSpec&quot; in
+              VS Code Extensions (Ctrl/Cmd+Shift+X)
+            </p>
+          </div>
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Features</h2>
+          <div className="grid gap-4 md:grid-cols-3">
+            {features.map((section) => (
+              <div key={section.category} className="card-subtle space-y-3 p-4">
+                <h3 className="font-bold text-violet-400">
+                  {section.category}
+                </h3>
+                <ul className="space-y-2">
+                  {section.items.map((item) => (
+                    <li
+                      key={item}
+                      className="text-muted-foreground flex items-start gap-2 text-sm"
+                    >
+                      <span className="mt-1 text-violet-400">-</span>
+                      <span>{item}</span>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+          </div>
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Commands</h2>
+          <p className="text-muted-foreground">
+            Access commands via Command Palette (Ctrl/Cmd+Shift+P) with prefix{' '}
+            <code>ContractSpec:</code>
+          </p>
+          <div className="grid gap-3 md:grid-cols-2">
+            {commands.map((cmd) => (
+              <div
+                key={cmd.name}
+                className="card-subtle flex items-center gap-3 p-3"
+              >
+                <div className="flex-1">
+                  <p className="font-mono text-sm font-medium">{cmd.name}</p>
+                  <p className="text-muted-foreground text-xs">
+                    {cmd.description}
+                  </p>
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Sidebar Views</h2>
+          <p className="text-muted-foreground">
+            The extension adds a ContractSpec activity bar (icon in sidebar)
+            with three views:
+          </p>
+          <div className="grid gap-4 md:grid-cols-3">
+            <div className="card-subtle space-y-2 p-4">
+              <h4 className="font-bold">Specs Explorer</h4>
+              <p className="text-muted-foreground text-sm">
+                Browse all specs organized by type. Shows name, version, and
+                stability. Click to open, right-click for actions.
+              </p>
+            </div>
+            <div className="card-subtle space-y-2 p-4">
+              <h4 className="font-bold">Dependencies</h4>
+              <p className="text-muted-foreground text-sm">
+                Visualize spec relationships. Detect circular dependencies.
+                Navigate to referenced specs.
+              </p>
+            </div>
+            <div className="card-subtle space-y-2 p-4">
+              <h4 className="font-bold">Build Results</h4>
+              <p className="text-muted-foreground text-sm">
+                Track build history (last 20). Success/failure indicators. Click
+                to open generated files.
+              </p>
+            </div>
+          </div>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Getting Started</h2>
+          <ol className="text-muted-foreground list-inside list-decimal space-y-2">
+            <li>Install the extension from VS Code Marketplace</li>
+            <li>Open a workspace with ContractSpec files (or create one)</li>
+            <li>Start the walkthrough: Help - Welcome - ContractSpec</li>
+            <li>
+              Create your first spec: Click <strong>+</strong> in Specs Explorer
+              or run <code>ContractSpec: Create New Spec</code>
+            </li>
+            <li>Build from it: Click the build icon in the editor title bar</li>
+          </ol>
+        </div>
+
+        <div className="card-subtle space-y-4 p-6">
+          <h3 className="font-bold">Configuration</h3>
+          <p className="text-muted-foreground text-sm">
+            Configure the extension in VS Code Settings:
+          </p>
+          <div className="overflow-x-auto">
+            <table className="text-muted-foreground w-full text-sm">
+              <thead>
+                <tr className="border-border border-b">
+                  <th className="p-2 text-left font-medium">Setting</th>
+                  <th className="p-2 text-left font-medium">Description</th>
+                  <th className="p-2 text-left font-medium">Default</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr className="border-border border-b">
+                  <td className="p-2 font-mono text-xs">validation.onSave</td>
+                  <td className="p-2">Run validation on save</td>
+                  <td className="p-2">true</td>
+                </tr>
+                <tr className="border-border border-b">
+                  <td className="p-2 font-mono text-xs">validation.onOpen</td>
+                  <td className="p-2">Run validation on open</td>
+                  <td className="p-2">true</td>
+                </tr>
+                <tr className="border-border border-b">
+                  <td className="p-2 font-mono text-xs">api.baseUrl</td>
+                  <td className="p-2">Base URL for ContractSpec API</td>
+                  <td className="p-2">(empty)</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </div>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/getting-started/tools/cli" className="btn-ghost">
+          Back: CLI
+        </Link>
+        <Link href="/docs/specs" className="btn-primary">
+          Next: Core Concepts <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}