@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/application/mcp/index.ts

@@ -0,0 +1,3 @@
+export * from './docsMcp';
+export * from './cliMcp';
+export * from './internalMcp';

package/src/application/mcp/internalMcp.ts

@@ -0,0 +1,227 @@
+import {
+  defineCommand,
+  definePrompt,
+  defineResourceTemplate,
+  installOp,
+  OperationSpecRegistry,
+  PromptRegistry,
+  ResourceRegistry,
+} from '@contractspec/lib.contracts';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import z from 'zod';
+import { createMcpElysiaHandler } from './common';
+import { appLogger } from '../../infrastructure/elysia/logger';
+import {
+  getExample,
+  listExamples,
+  searchExamples,
+} from '@contractspec/module.examples';
+
+const INTERNAL_TAGS = ['internal', 'mcp'];
+const INTERNAL_OWNERS = ['@contractspec'];
+
+const ENDPOINTS = {
+  docs: '/api/mcp/docs',
+  cli: '/api/mcp/cli',
+  internal: '/api/mcp/internal',
+  graphql: '/graphql',
+  health: '/health',
+};
+
+function buildInternalResources() {
+  const resources = new ResourceRegistry();
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'examples://list{?q}',
+        title: 'ContractSpec examples registry',
+        description:
+          'List available examples (templates, integrations, knowledge, scripts). Optional query `q` filters results.',
+        mimeType: 'application/json',
+        tags: ['examples', ...INTERNAL_TAGS],
+      },
+      input: z.object({ q: z.string().optional() }),
+      resolve: async ({ q }) => {
+        const items = q ? searchExamples(q) : [...listExamples()];
+        return {
+          uri: q
+            ? `examples://list?q=${encodeURIComponent(q)}`
+            : 'examples://list',
+          mimeType: 'application/json',
+          data: JSON.stringify(items, null, 2),
+        };
+      },
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'examples://example/{id}',
+        title: 'ContractSpec example (by id)',
+        description: 'Fetch a single example manifest by id.',
+        mimeType: 'application/json',
+        tags: ['examples', ...INTERNAL_TAGS],
+      },
+      input: z.object({ id: z.string().min(1) }),
+      resolve: async ({ id }) => {
+        const example = getExample(id);
+        if (!example) {
+          return {
+            uri: `examples://example/${encodeURIComponent(id)}`,
+            mimeType: 'application/json',
+            data: JSON.stringify(
+              { error: 'not_found', id, message: `Unknown example id: ${id}` },
+              null,
+              2
+            ),
+          };
+        }
+        return {
+          uri: `examples://example/${encodeURIComponent(id)}`,
+          mimeType: 'application/json',
+          data: JSON.stringify(example, null, 2),
+        };
+      },
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'internal://endpoints',
+        title: 'ContractSpec MCP endpoints',
+        description: 'Endpoints for docs, CLI, internal MCP servers.',
+        mimeType: 'application/json',
+        tags: INTERNAL_TAGS,
+      },
+      input: z.object({}),
+      resolve: async () => ({
+        uri: 'internal://endpoints',
+        mimeType: 'application/json',
+        data: JSON.stringify(ENDPOINTS, null, 2),
+      }),
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'internal://playbook',
+        title: 'Internal MCP usage playbook',
+        description:
+          'How internal agents should discover docs, CLI usage, and endpoints.',
+        mimeType: 'text/markdown',
+        tags: INTERNAL_TAGS,
+      },
+      input: z.object({}),
+      resolve: async () => ({
+        uri: 'internal://playbook',
+        mimeType: 'text/markdown',
+        data: [
+          '# Internal MCP playbook',
+          '- Connect to docs MCP first for canonical specs.',
+          '- Use CLI MCP to surface quickstart/reference before running commands.',
+          '- Keep calls read-only unless explicitly approved.',
+          `- Endpoints: ${ENDPOINTS.docs}, ${ENDPOINTS.cli}, ${ENDPOINTS.internal}.`,
+          '- For API work, GraphQL at /graphql; health at /health.',
+        ].join('\n'),
+      }),
+    })
+  );
+
+  return resources;
+}
+
+function buildInternalPrompts() {
+  const prompts = new PromptRegistry();
+
+  prompts.register(
+    definePrompt({
+      meta: {
+        key: 'internal.bootstrap',
+        version: '1.0.0',
+        title: 'Bootstrap internal ContractSpec agent',
+        description:
+          'Points agents to the correct MCP endpoints and guardrails.',
+        tags: INTERNAL_TAGS,
+        owners: INTERNAL_OWNERS,
+        stability: 'beta',
+      },
+      args: [],
+      input: z.object({}),
+      render: async () => [
+        {
+          type: 'text',
+          text: 'Start with internal://endpoints to pick the right MCP. Use docs MCP for specifications and CLI MCP for commands. Keep actions read-only unless explicitly approved.',
+        },
+        {
+          type: 'resource' as const,
+          uri: 'internal://endpoints',
+          title: 'Endpoints',
+        },
+      ],
+    })
+  );
+
+  return prompts;
+}
+
+function buildInternalOps() {
+  const registry = new OperationSpecRegistry();
+
+  const InternalDescribeOutput = defineSchemaModel({
+    name: 'InternalDescribeOutput',
+    fields: {
+      endpoints: {
+        type: ScalarTypeEnum.JSONObject(),
+        isOptional: false,
+      },
+      notes: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    },
+  });
+
+  const describeSpec = defineCommand({
+    meta: {
+      key: 'internal.describe',
+      version: '1.0.0',
+      stability: 'stable',
+      owners: INTERNAL_OWNERS,
+      tags: INTERNAL_TAGS,
+      description:
+        'Return MCP endpoints and guidance for internal ContractSpec agents.',
+      goal: 'Speed up internal development with the correct MCP entrypoints.',
+      context: 'Used by internal MCP surface; read-only.',
+    },
+    io: {
+      input: defineSchemaModel({
+        name: 'InternalDescribeInput',
+        fields: {},
+      }),
+      output: InternalDescribeOutput,
+    },
+    policy: {
+      auth: 'anonymous',
+    },
+  });
+
+  installOp(registry, describeSpec, async () => ({
+    endpoints: ENDPOINTS,
+    notes:
+      'Use docs MCP for canonical specs, CLI MCP for contractspec commands, and keep side-effecting actions gated behind human review.',
+  }));
+
+  return registry;
+}
+
+export function createInternalMcpHandler(path = '/api/mcp/internal') {
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path,
+    serverName: 'contractspec-internal-mcp',
+    ops: buildInternalOps(),
+    resources: buildInternalResources(),
+    prompts: buildInternalPrompts(),
+  });
+}

package/src/components/docs/DocsIndexPage.tsx

@@ -0,0 +1,255 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { BookOpen, ChevronRight, Shield, Zap } from 'lucide-react';
+
+// export const metadata: Metadata = {
+//   title: 'Documentation – ContractSpec',
+//   description:
+//     'Learn to stabilize your AI-generated code. Define contracts, generate consistent code across all surfaces, regenerate safely.',
+//   keywords: [
+//     'documentation',
+//     'guides',
+//     'API reference',
+//     'spec-first compiler',
+//     'AI code stabilization',
+//     'TypeScript',
+//     'contracts',
+//   ],
+//   openGraph: {
+//     title: 'Documentation – ContractSpec',
+//     description:
+//       'Learn to stabilize your AI-generated code with spec-first development.',
+//     url: 'https://contractspec.io/docs',
+//     type: 'website',
+//   },
+//   alternates: {
+//     canonical: 'https://contractspec.io/docs',
+//   },
+// };
+
+export function DocsIndexPage() {
+  return (
+    <div className="space-y-12">
+      {/* Hero */}
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold md:text-5xl">Documentation</h1>
+        <p className="text-muted-foreground max-w-2xl text-lg">
+          Stabilize your AI-generated code. Define contracts once, generate
+          consistent code across all surfaces, regenerate safely anytime.
+        </p>
+      </div>
+
+      {/* Quick Links */}
+      <div className="grid gap-6 md:grid-cols-3">
+        <Link
+          href="/docs/getting-started/installation"
+          className="card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50"
+        >
+          <div className="flex items-start justify-between">
+            <div>
+              <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+                Get started
+              </h3>
+              <p className="text-muted-foreground mt-1 text-sm">
+                Install ContractSpec and define your first contract in minutes.
+              </p>
+            </div>
+            <Zap size={20} className="shrink-0 text-violet-400" />
+          </div>
+        </Link>
+
+        <Link
+          href="/docs/specs/capabilities"
+          className="card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50"
+        >
+          <div className="flex items-start justify-between">
+            <div>
+              <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+                Core contracts
+              </h3>
+              <p className="text-muted-foreground mt-1 text-sm">
+                Commands, queries, events, and presentations. The building
+                blocks.
+              </p>
+            </div>
+            <BookOpen size={20} className="shrink-0 text-violet-400" />
+          </div>
+        </Link>
+
+        <Link
+          href="/docs/safety/signing"
+          className="card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50"
+        >
+          <div className="flex items-start justify-between">
+            <div>
+              <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+                Safe regeneration
+              </h3>
+              <p className="text-muted-foreground mt-1 text-sm">
+                Golden tests, migrations, signing, and audit trails.
+              </p>
+            </div>
+            <Shield size={20} className="shrink-0 text-violet-400" />
+          </div>
+        </Link>
+
+        <Link
+          href="/studio"
+          className="card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50"
+        >
+          <div className="flex items-start justify-between">
+            <div>
+              <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">
+                Studio (managed)
+              </h3>
+              <p className="text-muted-foreground mt-1 text-sm">
+                Visual builder, deployments, and team collaboration.
+              </p>
+            </div>
+            <Zap size={20} className="shrink-0 text-violet-400" />
+          </div>
+        </Link>
+      </div>
+
+      {/* Quick Start */}
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Quick start</h2>
+        <div className="card-subtle space-y-4 p-6">
+          <p className="text-muted-foreground">
+            Add ContractSpec to your project and define your first contract:
+          </p>
+          <CodeBlock
+            language="bash"
+            filename="docs-quick-start"
+            code={`# Install the CLI and core libraries
+bun add -D contractspec
+bun add @contractspec/lib.contracts @contractspec/lib.schema
+
+# Create your first contract
+bun contractspec create --type operation
+
+# Generate implementation
+bun contractspec build src/contracts/mySpec.ts`}
+          />
+
+          <div className="flex flex-wrap gap-2">
+            <Link
+              href="/docs/getting-started/installation"
+              className="btn-primary text-sm"
+            >
+              Installation guide <ChevronRight size={16} />
+            </Link>
+            <Link
+              href="/docs/getting-started/hello-world"
+              className="btn-ghost text-sm"
+            >
+              First contract tutorial
+            </Link>
+          </div>
+
+          {/*<Link*/}
+          {/*  href="/docs/libraries/ai-agent"*/}
+          {/*  className="card-subtle group space-y-3 p-6 transition-colors hover:border-violet-500/50"*/}
+          {/*>*/}
+          {/*  <div className="flex items-start justify-between">*/}
+          {/*    <div>*/}
+          {/*      <p className="text-xs font-semibold tracking-[0.2em] text-violet-500 uppercase">*/}
+          {/*        Featured*/}
+          {/*      </p>*/}
+          {/*      <h3 className="text-lg font-bold transition-colors group-hover:text-violet-400">*/}
+          {/*        AI Governance*/}
+          {/*      </h3>*/}
+          {/*      <p className="text-muted-foreground mt-1 text-sm">*/}
+          {/*        Constrain what AI agents can change. Enforce contracts they*/}
+          {/*        must respect. Human-in-the-loop guardrails.*/}
+          {/*      </p>*/}
+          {/*    </div>*/}
+          {/*    <Activity size={20} className="shrink-0 text-violet-400" />*/}
+          {/*  </div>*/}
+          {/*</Link>*/}
+        </div>
+      </div>
+
+      {/* Browse All Docs */}
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Browse all documentation</h2>
+        <p className="text-muted-foreground">
+          Use the sidebar or choose a topic to explore spec-first development.
+        </p>
+        <div className="mt-6 grid gap-4 md:grid-cols-2">
+          {[
+            {
+              title: 'Getting Started',
+              description: 'Installation, first contract, and CLI usage',
+              href: '/docs/getting-started/installation',
+            },
+            {
+              title: 'Guides',
+              description: 'Runnable adoption scenarios with examples',
+              href: '/docs/guides',
+            },
+            {
+              title: 'Intent Pages',
+              description: 'SEO-optimized pages for specific developer needs',
+              href: '/docs/intent',
+            },
+            {
+              title: 'Ecosystem',
+              description: 'Plugin API, templates, and integrations',
+              href: '/docs/ecosystem/plugins',
+            },
+            {
+              title: 'Core Contracts',
+              description:
+                'Commands, queries, events, presentations, workflows',
+              href: '/docs/specs/capabilities',
+            },
+            {
+              title: 'Safe Regeneration',
+              description: 'Signing, migrations, golden tests, compliance',
+              href: '/docs/safety/signing',
+            },
+            {
+              title: 'Multi-Surface Output',
+              description: 'REST, GraphQL, Prisma, MCP tools, React',
+              href: '/docs/advanced/renderers',
+            },
+            {
+              title: 'Libraries',
+              description: 'Core runtime libraries and utilities',
+              href: '/docs/libraries',
+            },
+            {
+              title: 'AI Governance',
+              description: 'Agents, contract enforcement, approval workflows',
+              href: '/docs/libraries/ai-agent',
+            },
+            {
+              title: 'Architecture',
+              description: 'Multi-tenancy, integrations, knowledge sources',
+              href: '/docs/architecture',
+            },
+            {
+              title: 'Manifesto',
+              description: 'Our philosophy: compiler not prison',
+              href: '/docs/manifesto',
+            },
+          ].map((topic, i) => (
+            <Link
+              key={i}
+              href={topic.href}
+              className="card-subtle group p-4 transition-colors hover:border-violet-500/50"
+            >
+              <h3 className="font-bold transition-colors group-hover:text-violet-400">
+                {topic.title}
+              </h3>
+              <p className="text-muted-foreground mt-1 text-sm">
+                {topic.description}
+              </p>
+            </Link>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}