@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/components/docs/libraries/LibrariesAiAgentPage.tsx

@@ -0,0 +1,92 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+
+export function LibrariesAiAgentPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">@contractspec/lib.ai-agent</h1>
+        <p className="text-muted-foreground text-lg">
+          Define AI agents in TypeScript, run them with deterministic tool
+          calling, capture working memory, and route low-confidence decisions to
+          human reviewers.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand package="@contractspec/lib.ai-agent" />
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">Define & register</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import { defineAgent, AgentRegistry } from '@contractspec/lib.ai-agent';
+
+const SupportBot = defineAgent({
+  meta: { name: 'support.bot', version: '1.0.0' },
+  instructions: 'Resolve tickets. Escalate when confidence < 0.75.',
+  tools: [{ name: 'support_resolve_ticket' }],
+  policy: {
+    confidence: { min: 0.7, default: 0.6 },
+    escalation: { confidenceThreshold: 0.75 },
+  },
+});
+
+const registry = new AgentRegistry().register(SupportBot);`}
+        />
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">Run with approvals</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import { AgentRunner, ToolExecutor, ApprovalWorkflow } from '@contractspec/lib.ai-agent';
+
+const runner = new AgentRunner({
+  registry,
+  llm: mistralProvider,
+  toolExecutor: new ToolExecutor({ tools: supportTools }),
+  approvalWorkflow: new ApprovalWorkflow(),
+});
+
+const result = await runner.run({ agent: 'support.bot', input: ticket.body });
+if (result.approvalRequestId) {
+  // show in ApprovalQueue UI
+}`}
+        />
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">What's inside</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <code>defineAgent</code>, <code>AgentRegistry</code>,{' '}
+            <code>AgentRunner</code>
+          </li>
+          <li>
+            <code>ToolExecutor</code> with schema-enforced tool definitions
+          </li>
+          <li>
+            <code>InMemoryAgentMemory</code> plus interfaces for custom stores
+          </li>
+          <li>
+            <code>ApprovalWorkflow</code> + <code>ApprovalStore</code> for
+            human-in-the-loop reviews
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries" className="btn-ghost">
+          Back to Libraries
+        </Link>
+        <Link href="/docs/libraries/support-bot" className="btn-primary">
+          Next: Support Bot <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/libraries/LibrariesAnalyticsPage.tsx

@@ -0,0 +1,63 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+
+export function LibrariesAnalyticsPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">@contractspec/lib.analytics</h1>
+        <p className="text-muted-foreground text-lg">
+          Work directly with telemetry events to understand conversion,
+          retention, churn, and growth opportunities.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand package="@contractspec/lib.analytics" />
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">Funnels in memory</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import { FunnelAnalyzer } from '@contractspec/lib.analytics/funnel';
+
+const analyzer = new FunnelAnalyzer();
+const report = analyzer.analyze(events, {
+  name: 'signup',
+  steps: [
+    { id: 'view', eventName: 'page.view', match: (e) => e.properties?.slug === '/signup' },
+    { id: 'submit', eventName: 'signup.submit' },
+    { id: 'verified', eventName: 'account.verified' },
+  ],
+});`}
+        />
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">Cohorts & churn</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import { CohortTracker } from '@contractspec/lib.analytics/cohort';
+import { ChurnPredictor } from '@contractspec/lib.analytics/churn';
+
+const cohorts = new CohortTracker().analyze(events, { bucket: 'week', periods: 8 });
+const churn = new ChurnPredictor().score(events);`}
+        />
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">Growth hypotheses</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import { GrowthHypothesisGenerator } from '@contractspec/lib.analytics/growth';
+
+const ideas = new GrowthHypothesisGenerator().generate([
+  { name: 'Activation rate', current: 0.42, previous: 0.55, target: 0.6 },
+  { name: 'Expansion ARPU', current: 1.2, previous: 0.9 },
+]);`}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/docs/libraries/LibrariesContentGenPage.tsx

@@ -0,0 +1,71 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function LibrariesContentGenPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">@contractspec/lib.content-gen</h1>
+        <p className="text-muted-foreground text-lg">
+          Feed a single ContentBrief and produce cohesive marketing assets
+          without touching a CMS.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand package="@contractspec/lib.content-gen" />
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">One brief, many assets</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import {
+  BlogGenerator,
+  LandingPageGenerator,
+  EmailCampaignGenerator,
+  SocialPostGenerator,
+} from '@contractspec/lib.content-gen/generators';
+import { SeoOptimizer } from '@contractspec/lib.content-gen/seo';
+
+const brief = {
+  title: 'AI Ops Copilot',
+  summary: 'Automates support + growth.',
+  problems: ['Support queues pile up', 'Growth teams lack experiments'],
+  solutions: ['AI agents', 'Approval queue', 'Analytics'],
+  audience: { role: 'COO', industry: 'Fintech' },
+};
+
+const blog = await new BlogGenerator().generate(brief);
+const landing = await new LandingPageGenerator().generate(brief);
+const email = await new EmailCampaignGenerator().generate({ brief, variant: 'announcement' });
+const social = await new SocialPostGenerator().generate(brief);
+const seo = new SeoOptimizer().optimize(brief);`}
+        />
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">When to use</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>Ship landing page refreshes whenever specs change.</li>
+          <li>Automate release emails + nurture sequences per vertical.</li>
+          <li>
+            Create social snippets that stay on-message with the same brief.
+          </li>
+          <li>Generate SEO metadata + Schema.org markup alongside content.</li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries" className="btn-ghost">
+          Back to Libraries
+        </Link>
+        <Link href="/docs/libraries/support-bot" className="btn-primary">
+          Next: Support Bot <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/libraries/LibrariesContractsPage.tsx

@@ -0,0 +1,163 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+
+export function LibrariesContractsPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">@contractspec/lib.contracts</h1>
+        <p className="text-muted-foreground text-lg">
+          The core library for defining what your application can do. Unified
+          specifications for Operations, Events, Presentations, and Features.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand
+          package={['@contractspec/lib.contracts', '@contractspec/lib.schema']}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">What lives where</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>@contractspec/lib.contracts</strong> (root): The core
+            contracts definitions (OperationSpec, PresentationSpec, Registry).
+          </li>
+          <li>
+            <strong>@contractspec/lib.contracts/client</strong>: Browser-safe
+            helpers (React renderers, client SDK). Import this for web/React
+            Native.
+          </li>
+          <li>
+            <strong>@contractspec/lib.contracts/server</strong>: HTTP/MCP
+            adapters, registries, integrations (Node-only).
+          </li>
+          <li>
+            <strong>@contractspec/lib.schema</strong>: Schema dictionary
+            (SchemaModel, FieldType) for I/O definitions.
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Quick Example</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import { defineCommand } from '@contractspec/lib.contracts';
+import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+
+const CreateUserInput = new SchemaModel({
+  name: 'CreateUserInput',
+  fields: {
+    email: { type: ScalarTypeEnum.Email(), isOptional: false },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+  },
+});
+
+export const CreateUser = defineCommand({
+  meta: {
+    key: 'users.createUser',
+    version: '1.0.0',
+    description: 'Create a new user account',
+  },
+  io: {
+    input: CreateUserInput,
+    output: /* ... */,
+  },
+  policy: { auth: 'admin' },
+});`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Core Concepts</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>OperationSpec</strong>: Immutable description of an
+            operation (Command or Query). Defines I/O, policy, and metadata.
+          </li>
+          <li>
+            <strong>OperationSpecRegistry</strong>: Registry of specs +
+            handlers. Use <code className="font-mono text-xs">installOp</code>{' '}
+            to attach a handler.
+          </li>
+          <li>
+            <strong>CapabilitySpec</strong>: Canonical capability declaration
+            (requires/provides).
+          </li>
+          <li>
+            <strong>PolicySpec</strong>: Declarative policy rules (ABAC/ReBAC,
+            rate limits).
+          </li>
+          <li>
+            <strong>TelemetrySpec</strong>: Analytics definitions and privacy
+            levels.
+          </li>
+          <li>
+            <strong>PresentationSpec (V2)</strong>: Describes how data is
+            rendered (Web Components, Markdown, Data).
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Lifecycle</h2>
+        <ol className="text-muted-foreground list-inside list-decimal space-y-2">
+          <li>
+            <strong>Define</strong> the spec (I/O via SchemaModel or Zod).
+          </li>
+          <li>
+            <strong>Register</strong> it:{' '}
+            <code className="font-mono text-xs">
+              installOp(registry, spec, handler)
+            </code>
+            .
+          </li>
+          <li>
+            <strong>Expose</strong> it via an adapter (REST, GraphQL, MCP).
+          </li>
+          <li>
+            <strong>Validate</strong> at runtime automatically.
+          </li>
+        </ol>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Adapters</h2>
+        <ul className="text-muted-foreground space-y-2">
+          <li>
+            <code className="bg-background/50 rounded px-2 py-1">
+              server/rest-next-app
+            </code>
+            : Next.js App Router adapter
+          </li>
+          <li>
+            <code className="bg-background/50 rounded px-2 py-1">
+              server/provider-mcp
+            </code>
+            : Model Context Protocol (MCP) for AI agents
+          </li>
+          <li>
+            <code className="bg-background/50 rounded px-2 py-1">
+              server/graphql-pothos
+            </code>
+            : GraphQL schema generator
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries/schema" className="btn-primary">
+          Next: Schema <ChevronRight size={16} />
+        </Link>
+        <Link href="/docs/specs/capabilities" className="btn-ghost">
+          Core Concepts
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/libraries/LibrariesCostTrackingPage.tsx

@@ -0,0 +1,71 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function LibrariesCostTrackingPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Cost Tracking Library</h1>
+        <p className="text-muted-foreground text-lg">
+          <code>@contractspec/lib.cost-tracking</code> transforms raw telemetry
+          into dollars: DB/API/compute costs per operation, budget alerts per
+          tenant, and actionable optimization tips.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand package="@contractspec/lib.cost-tracking" />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Record Samples</h2>
+        <CodeBlock
+          language="typescript"
+          code={`const tracker = new CostTracker();
+tracker.recordSample({
+  operation: 'orders.list',
+  tenantId: 'acme',
+  dbReads: 1200,
+  dbWrites: 4,
+  computeMs: 180,
+  externalCalls: [{ provider: 'stripe', cost: 0.02 }],
+});`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Budget Alerts</h2>
+        <CodeBlock
+          language="typescript"
+          code={`const budgets = new BudgetAlertManager({
+  budgets: [{ tenantId: 'acme', monthlyLimit: 150 }],
+  onAlert: ({ tenantId, total }) => notifyFinance(tenantId, total),
+});
+
+tracker.getTotals({ tenantId: 'acme' }).forEach((summary) => budgets.track(summary));`}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Optimization Suggestions</h2>
+        <p className="text-muted-foreground text-sm">
+          Feed summaries into <code>OptimizationRecommender</code> to surface
+          N+1 queries, compute-heavy steps, or expensive external calls. Store
+          the generated suggestions in the new Prisma model to power Ops
+          playbooks.
+        </p>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries" className="btn-ghost">
+          Back to Libraries
+        </Link>
+        <Link href="/docs/libraries/slo" className="btn-primary">
+          Next: SLO <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/libraries/LibrariesDataBackendPage.tsx

@@ -0,0 +1,104 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+import { CodeBlock } from '@contractspec/lib.design-system';
+
+export function LibrariesDataBackendPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Data & Backend</h1>
+        <p className="text-muted-foreground">
+          A collection of robust, platform-agnostic libraries for building the
+          backend infrastructure of your LSSM applications.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Libraries</h2>
+
+        <div className="space-y-6">
+          <div className="card-subtle p-6">
+            <h3 className="text-lg font-bold">
+              @contractspec/app.cli-database
+            </h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              <strong>Prisma Wrapper & CLI</strong>. Provides a unified way to
+              manage database schemas, migrations, and clients. Includes seeders
+              and factory patterns for testing.
+            </p>
+          </div>
+
+          <div className="card-subtle p-6">
+            <h3 className="text-lg font-bold">@contractspec/lib.bus</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              <strong>Type-Safe Event Bus</strong>. Decouple your architecture
+              with typed events. Supports in-memory dispatch for monoliths and
+              can be extended for distributed message queues (Redis, SQS).
+            </p>
+          </div>
+
+          <div className="card-subtle p-6">
+            <h3 className="text-lg font-bold">@contractspec/lib.logger</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              <strong>High-Performance Logging</strong>. Optimized for Bun and
+              structured JSON output. Includes plugins for ElysiaJS to log HTTP
+              requests automatically.
+            </p>
+          </div>
+
+          <div className="card-subtle p-6">
+            <h3 className="text-lg font-bold">@contractspec/lib.error</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              <strong>Standardized Errors</strong>. Use `AppError` with standard
+              codes (NOT_FOUND, UNAUTHORIZED) to ensure consistent HTTP
+              responses and error handling across services.
+            </p>
+          </div>
+
+          <div className="card-subtle p-6">
+            <h3 className="text-lg font-bold">@contractspec/lib.exporter</h3>
+            <p className="text-muted-foreground mt-2 text-sm">
+              <strong>Data Export</strong>. Generate CSV and XML files from your
+              data. Platform-agnostic and streaming-friendly.
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Example: Unified Backend Flow</h2>
+        <CodeBlock
+          language="typescript"
+          code={`import { logger } from '@contractspec/lib.logger';
+import { AppError } from '@contractspec/lib.error';
+import { db } from '@contractspec/app.cli-database';
+import { EventBus } from '@contractspec/lib.bus';
+
+export async function createUser(email: string) {
+  logger.info({ email }, 'Creating user');
+
+  const existing = await db.user.findUnique({ where: { email } });
+  if (existing) {
+    throw new AppError('User already exists', 'CONFLICT');
+  }
+
+  const user = await db.user.create({ data: { email } });
+  
+  await EventBus.publish('user.created', { userId: user.id });
+  
+  return user;
+}`}
+        />
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries/runtime" className="btn-primary">
+          Next: Runtime <ChevronRight size={16} />
+        </Link>
+        <Link href="/docs/libraries" className="btn-ghost">
+          Back to Libraries
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/libraries/LibrariesDataViewsPage.tsx

@@ -0,0 +1,108 @@
+import { CodeBlock, InstallCommand } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function LibrariesDataViewsPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">DataViews Runtime Library</h1>
+        <p className="text-muted-foreground text-lg">
+          The <code>@contractspec/lib.contracts/data-views</code> and{' '}
+          <code>@contractspec/lib.design-system</code> libraries provide the
+          runtime logic and UI components to render DataViews in your
+          application.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Installation</h2>
+        <InstallCommand
+          package={[
+            '@contractspec/lib.contracts',
+            '@contractspec/lib.design-system',
+          ]}
+        />
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">DataViewRenderer</h2>
+        <p className="text-muted-foreground">
+          The primary component for rendering any DataView. It automatically
+          selects the correct layout (List, Table, Grid, Detail) based on the
+          spec.
+        </p>
+
+        <CodeBlock
+          language="tsx"
+          code={`import { DataViewRenderer } from '@contractspec/lib.design-system';
+import { MyUserList } from './specs/users.data-view';
+
+export function UserPage() {
+  return (
+    <DataViewRenderer
+      spec={MyUserList}
+      items={users}
+      pagination={{ page: 1, pageSize: 20, total: 100 }}
+      onPageChange={(page) => fetchPage(page)}
+    />
+  );
+}`}
+        />
+
+        <h3 className="text-xl font-semibold">Props</h3>
+        <ul className="text-muted-foreground list-disc space-y-2 pl-6">
+          <li>
+            <code>spec</code>: The DataViewSpec definition.
+          </li>
+          <li>
+            <code>items</code>: Array of data items to render.
+          </li>
+          <li>
+            <code>filters</code>: Current filter state object.
+          </li>
+          <li>
+            <code>onFilterChange</code>: Callback when filters change.
+          </li>
+          <li>
+            <code>pagination</code>: Object with <code>page</code>,{' '}
+            <code>pageSize</code>, <code>total</code>.
+          </li>
+          <li>
+            <code>onPageChange</code>: Callback when page changes.
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Query Generation</h2>
+        <p className="text-muted-foreground">
+          The <code>DataViewQueryGenerator</code> utility helps translate
+          DataView parameters (filters, sorting, pagination) into query
+          arguments for your backend.
+        </p>
+        <CodeBlock
+          language="typescript"
+          code={`import { DataViewQueryGenerator } from '@contractspec/lib.contracts/data-views/query-generator';
+
+const generator = new DataViewQueryGenerator(MyUserList);
+const query = generator.generate({
+  pagination: { page: 1, pageSize: 20 },
+  filters: { role: 'admin' }
+});
+
+// query.input contains { skip: 0, take: 20, role: 'admin' }`}
+        />
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/libraries" className="btn-ghost">
+          Back to Libraries
+        </Link>
+        <Link href="/docs/libraries/data-backend" className="btn-primary">
+          Next: Data & Backend <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}