@contractspec/bundle.library 0.0.0-canary-20260206014742

package/dist/components/docs/guides/GuideImportExistingCodebasesPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideImportExistingCodebasesPage.js","names":[],"sources":["../../../../src/components/docs/guides/GuideImportExistingCodebasesPage.tsx"],"sourcesContent":["import { CodeBlock } from '@contractspec/lib.design-system';\nimport Link from '@contractspec/lib.ui-link';\nimport {\n  ChevronRight,\n  FileCode,\n  Scan,\n  Settings,\n  AlertCircle,\n} from 'lucide-react';\nimport { StudioPrompt } from '../shared/StudioPrompt';\n\nconst supportedFrameworks = [\n  {\n    name: 'NestJS',\n    flag: 'nestjs',\n    description: 'Controllers, decorators, DTOs',\n  },\n  {\n    name: 'Express',\n    flag: 'express',\n    description: 'Router methods, middleware',\n  },\n  {\n    name: 'Fastify',\n    flag: 'fastify',\n    description: 'Route definitions, schemas',\n  },\n  {\n    name: 'Hono',\n    flag: 'hono',\n    description: 'Route handlers, validators',\n  },\n  {\n    name: 'Elysia',\n    flag: 'elysia',\n    description: 'Type-safe routes, schemas',\n  },\n  {\n    name: 'tRPC',\n    flag: 'trpc',\n    description: 'Procedure definitions',\n  },\n  {\n    name: 'Next.js',\n    flag: 'next-api',\n    description: 'API routes (app/api, pages/api)',\n  },\n];\n\nexport function GuideImportExistingCodebasesPage() {\n  return (\n    <div className=\"space-y-8\">\n      <div className=\"space-y-3\">\n        <h1 className=\"text-4xl font-bold\">Import Existing Codebases</h1>\n        <p className=\"text-muted-foreground text-lg\">\n          Convert your existing API endpoints into ContractSpec contracts.\n          Auto-detect frameworks, extract schemas, and generate spec-first\n          definitions from your code.\n        </p>\n      </div>\n\n      <div className=\"card-subtle space-y-4 p-6\">\n        <h2 className=\"text-2xl font-bold\">What you'll learn</h2>\n        <ul className=\"text-muted-foreground space-y-2 text-sm\">\n          <li>\n            How to import existing API endpoints as ContractSpec contracts.\n          </li>\n          <li>Framework-specific patterns and auto-detection.</li>\n          <li>Customizing imports with scopes, dry-run, and output options.</li>\n          <li>Registering imported contracts and adding handlers.</li>\n        </ul>\n      </div>\n\n      <div className=\"space-y-6\">\n        {/* Section 1: Why Import */}\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">Why import existing code?</h2>\n          <p className=\"text-muted-foreground text-sm\">\n            Instead of writing contracts from scratch, the import command\n            extracts endpoint patterns from your existing codebase. This gives\n            you:\n          </p>\n          <ul className=\"text-muted-foreground list-disc space-y-1 pl-5 text-sm\">\n            <li>Instant spec coverage for existing APIs</li>\n            <li>Type-safe schemas derived from your existing types</li>\n            <li>A foundation to iterate and refine contracts</li>\n            <li>Gradual adoption without rewriting code</li>\n          </ul>\n        </div>\n\n        {/* Section 2: Supported Frameworks */}\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">Supported frameworks</h2>\n          <div className=\"grid gap-3 md:grid-cols-2 lg:grid-cols-3\">\n            {supportedFrameworks.map((fw) => (\n              <div\n                key={fw.flag}\n                className=\"flex items-start gap-3 rounded-lg border border-white/10 p-4\"\n              >\n                <FileCode className=\"text-violet-400\" size={18} />\n                <div className=\"space-y-1\">\n                  <h3 className=\"font-semibold\">{fw.name}</h3>\n                  <p className=\"text-muted-foreground text-xs\">\n                    {fw.description}\n                  </p>\n                  <code className=\"text-xs text-violet-400\">\n                    --framework {fw.flag}\n                  </code>\n                </div>\n              </div>\n            ))}\n          </div>\n        </div>\n\n        {/* Section 3: Quick Start */}\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">1) Quick start</h2>\n          <p className=\"text-muted-foreground text-sm\">\n            Run the import command to auto-detect your framework and extract\n            endpoints:\n          </p>\n          <CodeBlock\n            language=\"bash\"\n            filename=\"import-quickstart\"\n            code={`# Auto-detect framework and import all endpoints\ncontractspec import ./src\n\n# Preview what would be imported (dry-run)\ncontractspec import ./src --dry-run\n\n# Force a specific framework\ncontractspec import ./src --framework nestjs`}\n          />\n          <p className=\"text-muted-foreground text-sm\">\n            Expected output: A summary of endpoints found, schemas extracted,\n            and files generated.\n          </p>\n        </div>\n\n        {/* Section 4: Framework Examples */}\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">2) Framework-specific patterns</h2>\n          <p className=\"text-muted-foreground text-sm\">\n            The import command recognizes these patterns in each framework:\n          </p>\n        </div>\n\n        {/* NestJS Example */}\n        <div className=\"space-y-3\">\n          <h3 className=\"flex items-center gap-2 text-xl font-semibold\">\n            <Scan size={18} className=\"text-blue-400\" />\n            NestJS\n          </h3>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\"src/users/users.controller.ts (before)\"\n            code={`@Controller('users')\nexport class UsersController {\n  @Get(':id')\n  async getUser(@Param('id') id: string): Promise<UserDto> {\n    return this.usersService.findOne(id);\n  }\n\n  @Post()\n  @UseGuards(AuthGuard)\n  async createUser(@Body() dto: CreateUserDto): Promise<UserDto> {\n    return this.usersService.create(dto);\n  }\n}`}\n          />\n          <p className=\"text-muted-foreground text-sm\">\n            Detected: <code>@Controller</code>, <code>@Get</code>,{' '}\n            <code>@Post</code>, <code>@Body</code>, <code>@Param</code>,{' '}\n            <code>@UseGuards</code> decorators.\n          </p>\n        </div>\n\n        {/* Express Example */}\n        <div className=\"space-y-3\">\n          <h3 className=\"flex items-center gap-2 text-xl font-semibold\">\n            <Scan size={18} className=\"text-green-400\" />\n            Express\n          </h3>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\"src/routes/users.ts (before)\"\n            code={`const router = express.Router();\n\nrouter.get('/users/:id', async (req, res) => {\n  const user = await getUserById(req.params.id);\n  res.json(user);\n});\n\nrouter.post('/users', validateBody(CreateUserSchema), async (req, res) => {\n  const user = await createUser(req.body);\n  res.status(201).json(user);\n});`}\n          />\n          <p className=\"text-muted-foreground text-sm\">\n            Detected: <code>router.get</code>, <code>router.post</code>,\n            validation middleware, Zod schemas.\n          </p>\n        </div>\n\n        {/* Next.js Example */}\n        <div className=\"space-y-3\">\n          <h3 className=\"flex items-center gap-2 text-xl font-semibold\">\n            <Scan size={18} className=\"text-purple-400\" />\n            Next.js API Routes\n          </h3>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\"app/api/users/[id]/route.ts (before)\"\n            code={`export async function GET(\n  request: Request,\n  { params }: { params: { id: string } }\n) {\n  const user = await getUserById(params.id);\n  return Response.json(user);\n}\n\nexport async function POST(request: Request) {\n  const body = await request.json();\n  const user = await createUser(body);\n  return Response.json(user, { status: 201 });\n}`}\n          />\n          <p className=\"text-muted-foreground text-sm\">\n            Detected: <code>GET</code>, <code>POST</code> exports in{' '}\n            <code>app/api/**/route.ts</code> and <code>pages/api/**/*.ts</code>.\n          </p>\n        </div>\n\n        {/* Section 5: Generated Output */}\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">\n            3) Understanding generated contracts\n          </h2>\n          <p className=\"text-muted-foreground text-sm\">\n            The import command generates ContractSpec operations with TODO\n            placeholders for fields it cannot infer:\n          </p>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\".contractspec/generated/users.operation.ts\"\n            code={`import { defineQuery, defineCommand } from \"@contractspec/lib.contracts\";\nimport { SchemaModel, ScalarTypeEnum } from \"@contractspec/lib.schema\";\n\nexport const GetUserQuery = defineQuery({\n  meta: {\n    key: \"users.get\",\n    version: \"1.0.0\",\n    description: \"TODO: Add description\",\n    stability: \"draft\",\n    owners: [\"TODO\"],\n    tags: [\"users\"],\n  },\n  io: {\n    input: new SchemaModel({\n      name: \"GetUserInput\",\n      fields: {\n        id: { type: ScalarTypeEnum.String(), isOptional: false },\n      },\n    }),\n    output: new SchemaModel({\n      name: \"GetUserOutput\",\n      fields: {\n        // TODO: Add output fields based on your UserDto\n        id: { type: ScalarTypeEnum.String(), isOptional: false },\n      },\n    }),\n  },\n  policy: { auth: \"user\" }, // Inferred from @UseGuards\n  transport: {\n    rest: { method: \"GET\", path: \"/users/:id\" },\n  },\n});\n\nexport const CreateUserCommand = defineCommand({\n  meta: {\n    key: \"users.create\",\n    version: \"1.0.0\",\n    description: \"TODO: Add description\",\n    stability: \"draft\",\n    owners: [\"TODO\"],\n    tags: [\"users\"],\n  },\n  io: {\n    input: new SchemaModel({\n      name: \"CreateUserInput\",\n      fields: {\n        // TODO: Add fields from CreateUserDto\n      },\n    }),\n    output: new SchemaModel({\n      name: \"CreateUserOutput\",\n      fields: {\n        id: { type: ScalarTypeEnum.String(), isOptional: false },\n      },\n    }),\n  },\n  policy: { auth: \"admin\" },\n  transport: {\n    rest: { method: \"POST\", path: \"/users\" },\n  },\n});`}\n          />\n        </div>\n\n        {/* Section 6: Command Options */}\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">4) Customizing imports</h2>\n          <div className=\"flex items-center gap-2\">\n            <Settings size={18} className=\"text-violet-400\" />\n            <h3 className=\"text-lg font-semibold\">Available options</h3>\n          </div>\n          <div className=\"overflow-x-auto\">\n            <table className=\"w-full text-sm\">\n              <thead>\n                <tr className=\"border-b border-white/10\">\n                  <th className=\"py-2 pr-4 text-left\">Option</th>\n                  <th className=\"py-2 pr-4 text-left\">Description</th>\n                  <th className=\"py-2 text-left\">Example</th>\n                </tr>\n              </thead>\n              <tbody className=\"text-muted-foreground\">\n                <tr className=\"border-b border-white/5\">\n                  <td className=\"py-2 pr-4\">\n                    <code>--scope</code>\n                  </td>\n                  <td className=\"py-2 pr-4\">Limit to specific directories</td>\n                  <td className=\"py-2\">\n                    <code>--scope src/users src/auth</code>\n                  </td>\n                </tr>\n                <tr className=\"border-b border-white/5\">\n                  <td className=\"py-2 pr-4\">\n                    <code>--framework</code>\n                  </td>\n                  <td className=\"py-2 pr-4\">Force a specific framework</td>\n                  <td className=\"py-2\">\n                    <code>--framework express</code>\n                  </td>\n                </tr>\n                <tr className=\"border-b border-white/5\">\n                  <td className=\"py-2 pr-4\">\n                    <code>--output</code>\n                  </td>\n                  <td className=\"py-2 pr-4\">Output directory</td>\n                  <td className=\"py-2\">\n                    <code>--output ./contracts</code>\n                  </td>\n                </tr>\n                <tr className=\"border-b border-white/5\">\n                  <td className=\"py-2 pr-4\">\n                    <code>--dry-run</code>\n                  </td>\n                  <td className=\"py-2 pr-4\">Preview without writing files</td>\n                  <td className=\"py-2\">\n                    <code>--dry-run</code>\n                  </td>\n                </tr>\n                <tr className=\"border-b border-white/5\">\n                  <td className=\"py-2 pr-4\">\n                    <code>--analyze</code>\n                  </td>\n                  <td className=\"py-2 pr-4\">\n                    Analysis only, no code generation\n                  </td>\n                  <td className=\"py-2\">\n                    <code>--analyze</code>\n                  </td>\n                </tr>\n                <tr>\n                  <td className=\"py-2 pr-4\">\n                    <code>--json</code>\n                  </td>\n                  <td className=\"py-2 pr-4\">Output as JSON for scripting</td>\n                  <td className=\"py-2\">\n                    <code>--json</code>\n                  </td>\n                </tr>\n              </tbody>\n            </table>\n          </div>\n          <CodeBlock\n            language=\"bash\"\n            filename=\"import-options\"\n            code={`# Import only specific modules\ncontractspec import ./src --scope src/users src/orders\n\n# Preview with analysis\ncontractspec import ./src --dry-run --analyze\n\n# Output to custom directory\ncontractspec import ./src --output ./src/contracts/generated\n\n# Get JSON for CI/scripting\ncontractspec import ./src --json > import-result.json`}\n          />\n        </div>\n\n        {/* Section 7: Registration */}\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">\n            5) Registering imported contracts\n          </h2>\n          <p className=\"text-muted-foreground text-sm\">\n            After import, register contracts and add handlers:\n          </p>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\"src/contracts/registry.ts\"\n            code={`import {\n  OperationSpecRegistry,\n  installOp,\n} from \"@contractspec/lib.contracts/operations\";\nimport {\n  GetUserQuery,\n  CreateUserCommand,\n} from \"./.contractspec/generated/users.operation\";\n\nexport const registry = new OperationSpecRegistry();\n\n// Add handlers to imported operations\ninstallOp(registry, GetUserQuery, async (input) => {\n  const user = await db.user.findUnique({ where: { id: input.id } });\n  return user;\n});\n\ninstallOp(registry, CreateUserCommand, async (input) => {\n  const user = await db.user.create({ data: input });\n  return { id: user.id };\n});`}\n          />\n        </div>\n\n        {/* Section 8: Next Steps */}\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">6) After importing</h2>\n          <ol className=\"text-muted-foreground list-decimal space-y-2 pl-5 text-sm\">\n            <li>\n              <strong>Review generated contracts</strong> — Check the TODO\n              placeholders and fill in descriptions, owners, and tags.\n            </li>\n            <li>\n              <strong>Refine schemas</strong> — Add proper types, validation\n              rules, and error definitions.\n            </li>\n            <li>\n              <strong>Run validation</strong> —{' '}\n              <code>contractspec validate</code> to ensure contracts are valid.\n            </li>\n            <li>\n              <strong>Register and wire handlers</strong> — Connect contracts to\n              your existing business logic.\n            </li>\n            <li>\n              <strong>Iterate</strong> — The imported contracts are a starting\n              point. Refine them as your spec matures.\n            </li>\n          </ol>\n        </div>\n\n        {/* Troubleshooting */}\n        <div className=\"space-y-3\">\n          <h2 className=\"flex items-center gap-2 text-2xl font-bold\">\n            <AlertCircle size={20} className=\"text-yellow-400\" />\n            Troubleshooting\n          </h2>\n          <div className=\"space-y-4\">\n            <div className=\"card-subtle space-y-2 p-4\">\n              <h3 className=\"font-semibold\">Framework not detected</h3>\n              <p className=\"text-muted-foreground text-sm\">\n                Use <code>--framework &lt;name&gt;</code> to force a specific\n                framework. Check that your entry files follow standard patterns.\n              </p>\n            </div>\n            <div className=\"card-subtle space-y-2 p-4\">\n              <h3 className=\"font-semibold\">Missing schemas</h3>\n              <p className=\"text-muted-foreground text-sm\">\n                Schema inference works best with explicit types. If using{' '}\n                <code>any</code> or dynamic types, you'll see TODO placeholders.\n                Fill them in manually.\n              </p>\n            </div>\n            <div className=\"card-subtle space-y-2 p-4\">\n              <h3 className=\"font-semibold\">Partial imports</h3>\n              <p className=\"text-muted-foreground text-sm\">\n                Some endpoints may not be detected if they use unconventional\n                patterns. Use <code>--analyze</code> to see what was found, then\n                add missing contracts manually.\n              </p>\n            </div>\n          </div>\n        </div>\n\n        <StudioPrompt\n          title=\"Want automated contract evolution?\"\n          body=\"Studio monitors your codebase and suggests contract updates when your API changes, keeping specs and code in sync.\"\n        />\n      </div>\n\n      <div className=\"flex items-center gap-4 pt-4\">\n        <Link\n          href=\"/docs/guides/spec-validation-and-typing\"\n          className=\"btn-primary\"\n        >\n          Next: Spec validation + typing <ChevronRight size={16} />\n        </Link>\n        <Link href=\"/docs/guides\" className=\"btn-ghost\">\n          Back to guides\n        </Link>\n      </div>\n    </div>\n  );\n}\n"],"mappings":";;;;;;;AAWA,MAAM,sBAAsB;CAC1B;EACE,MAAM;EACN,MAAM;EACN,aAAa;EACd;CACD;EACE,MAAM;EACN,MAAM;EACN,aAAa;EACd;CACD;EACE,MAAM;EACN,MAAM;EACN,aAAa;EACd;CACD;EACE,MAAM;EACN,MAAM;EACN,aAAa;EACd;CACD;EACE,MAAM;EACN,MAAM;EACN,aAAa;EACd;CACD;EACE,MAAM;EACN,MAAM;EACN,aAAa;EACd;CACD;EACE,MAAM;EACN,MAAM;EACN,aAAa;EACd;CACF;AAED,SAAgB,mCAAmC;AACjD,QACE,qBAAC;EAAI,WAAU;;GACb,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAA8B,EACjE,oBAAC;KAAE,WAAU;eAAgC;MAIzC;KACA;GAEN,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAsB,EACzD,qBAAC;KAAG,WAAU;;MACZ,oBAAC,kBAAG,oEAEC;MACL,oBAAC,kBAAG,oDAAoD;MACxD,oBAAC,kBAAG,kEAAkE;MACtE,oBAAC,kBAAG,wDAAwD;;MACzD;KACD;GAEN,qBAAC;IAAI,WAAU;;KAEb,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAA8B;OACjE,oBAAC;QAAE,WAAU;kBAAgC;SAIzC;OACJ,qBAAC;QAAG,WAAU;;SACZ,oBAAC,kBAAG,4CAA4C;SAChD,oBAAC,kBAAG,uDAAuD;SAC3D,oBAAC,kBAAG,iDAAiD;SACrD,oBAAC,kBAAG,4CAA4C;;SAC7C;;OACD;KAGN,qBAAC;MAAI,WAAU;iBACb,oBAAC;OAAG,WAAU;iBAAqB;QAAyB,EAC5D,oBAAC;OAAI,WAAU;iBACZ,oBAAoB,KAAK,OACxB,qBAAC;QAEC,WAAU;mBAEV,oBAAC;SAAS,WAAU;SAAkB,MAAM;UAAM,EAClD,qBAAC;SAAI,WAAU;;UACb,oBAAC;WAAG,WAAU;qBAAiB,GAAG;YAAU;UAC5C,oBAAC;WAAE,WAAU;qBACV,GAAG;YACF;UACJ,qBAAC;WAAK,WAAU;sBAA0B,gBAC3B,GAAG;YACX;;UACH;UAZD,GAAG,KAaJ,CACN;QACE;OACF;KAGN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAAmB;OACtD,oBAAC;QAAE,WAAU;kBAAgC;SAGzC;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;SAQN;OACF,oBAAC;QAAE,WAAU;kBAAgC;SAGzC;;OACA;KAGN,qBAAC;MAAI,WAAU;iBACb,oBAAC;OAAG,WAAU;iBAAqB;QAAmC,EACtE,oBAAC;OAAE,WAAU;iBAAgC;QAEzC;OACA;KAGN,qBAAC;MAAI,WAAU;;OACb,qBAAC;QAAG,WAAU;mBACZ,oBAAC;SAAK,MAAM;SAAI,WAAU;UAAkB;SAEzC;OACL,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;;;SAaN;OACF,qBAAC;QAAE,WAAU;;SAAgC;SACjC,oBAAC,oBAAK,gBAAkB;;SAAE,oBAAC,oBAAK,SAAW;;SAAE;SACvD,oBAAC,oBAAK,UAAY;;SAAE,oBAAC,oBAAK,UAAY;;SAAE,oBAAC,oBAAK,WAAa;;SAAE;SAC7D,oBAAC,oBAAK,eAAiB;;;SACrB;;OACA;KAGN,qBAAC;MAAI,WAAU;;OACb,qBAAC;QAAG,WAAU;mBACZ,oBAAC;SAAK,MAAM;SAAI,WAAU;UAAmB;SAE1C;OACL,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;SAWN;OACF,qBAAC;QAAE,WAAU;;SAAgC;SACjC,oBAAC,oBAAK,eAAiB;;SAAE,oBAAC,oBAAK,gBAAkB;;;SAEzD;;OACA;KAGN,qBAAC;MAAI,WAAU;;OACb,qBAAC;QAAG,WAAU;mBACZ,oBAAC;SAAK,MAAM;SAAI,WAAU;UAAoB;SAE3C;OACL,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;;;SAaN;OACF,qBAAC;QAAE,WAAU;;SAAgC;SACjC,oBAAC,oBAAK,QAAU;;SAAE,oBAAC,oBAAK,SAAW;;SAAY;SACzD,oBAAC,oBAAK,wBAA0B;;SAAK,oBAAC,oBAAK,sBAAwB;;;SACjE;;OACA;KAGN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAE9B;OACL,oBAAC;QAAE,WAAU;kBAAgC;SAGzC;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SA6DN;;OACE;KAGN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAA2B;OAC9D,qBAAC;QAAI,WAAU;mBACb,oBAAC;SAAS,MAAM;SAAI,WAAU;UAAoB,EAClD,oBAAC;SAAG,WAAU;mBAAwB;UAAsB;SACxD;OACN,oBAAC;QAAI,WAAU;kBACb,qBAAC;SAAM,WAAU;oBACf,oBAAC,qBACC,qBAAC;UAAG,WAAU;;WACZ,oBAAC;YAAG,WAAU;sBAAsB;aAAW;WAC/C,oBAAC;YAAG,WAAU;sBAAsB;aAAgB;WACpD,oBAAC;YAAG,WAAU;sBAAiB;aAAY;;WACxC,GACC,EACR,qBAAC;UAAM,WAAU;;WACf,qBAAC;YAAG,WAAU;;aACZ,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,YAAc;eACjB;aACL,oBAAC;cAAG,WAAU;wBAAY;eAAkC;aAC5D,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,+BAAiC;eACpC;;aACF;WACL,qBAAC;YAAG,WAAU;;aACZ,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,gBAAkB;eACrB;aACL,oBAAC;cAAG,WAAU;wBAAY;eAA+B;aACzD,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,wBAA0B;eAC7B;;aACF;WACL,qBAAC;YAAG,WAAU;;aACZ,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,aAAe;eAClB;aACL,oBAAC;cAAG,WAAU;wBAAY;eAAqB;aAC/C,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,yBAA2B;eAC9B;;aACF;WACL,qBAAC;YAAG,WAAU;;aACZ,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,cAAgB;eACnB;aACL,oBAAC;cAAG,WAAU;wBAAY;eAAkC;aAC5D,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,cAAgB;eACnB;;aACF;WACL,qBAAC;YAAG,WAAU;;aACZ,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,cAAgB;eACnB;aACL,oBAAC;cAAG,WAAU;wBAAY;eAErB;aACL,oBAAC;cAAG,WAAU;wBACZ,oBAAC,oBAAK,cAAgB;eACnB;;aACF;WACL,qBAAC;YACC,oBAAC;aAAG,WAAU;uBACZ,oBAAC,oBAAK,WAAa;cAChB;YACL,oBAAC;aAAG,WAAU;uBAAY;cAAiC;YAC3D,oBAAC;aAAG,WAAU;uBACZ,oBAAC,oBAAK,WAAa;cAChB;eACF;;WACC;UACF;SACJ;OACN,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;SAWN;;OACE;KAGN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAE9B;OACL,oBAAC;QAAE,WAAU;kBAAgC;SAEzC;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;;;;;;;;;;;SAqBN;;OACE;KAGN,qBAAC;MAAI,WAAU;iBACb,oBAAC;OAAG,WAAU;iBAAqB;QAAuB,EAC1D,qBAAC;OAAG,WAAU;;QACZ,qBAAC,mBACC,oBAAC,sBAAO,+BAAmC,kFAExC;QACL,qBAAC,mBACC,oBAAC,sBAAO,mBAAuB,qEAE5B;QACL,qBAAC;SACC,oBAAC,sBAAO,mBAAuB;;SAAG;SAClC,oBAAC,oBAAK,0BAA4B;;YAC/B;QACL,qBAAC,mBACC,oBAAC,sBAAO,+BAAmC,6DAExC;QACL,qBAAC,mBACC,oBAAC,sBAAO,YAAgB,yFAErB;;QACF;OACD;KAGN,qBAAC;MAAI,WAAU;iBACb,qBAAC;OAAG,WAAU;kBACZ,oBAAC;QAAY,MAAM;QAAI,WAAU;SAAoB;QAElD,EACL,qBAAC;OAAI,WAAU;;QACb,qBAAC;SAAI,WAAU;oBACb,oBAAC;UAAG,WAAU;oBAAgB;WAA2B,EACzD,qBAAC;UAAE,WAAU;;WAAgC;WACvC,oBAAC,oBAAK,uBAA+B;;;WAEvC;UACA;QACN,qBAAC;SAAI,WAAU;oBACb,oBAAC;UAAG,WAAU;oBAAgB;WAAoB,EAClD,qBAAC;UAAE,WAAU;;WAAgC;WACe;WAC1D,oBAAC,oBAAK,QAAU;;;WAEd;UACA;QACN,qBAAC;SAAI,WAAU;oBACb,oBAAC;UAAG,WAAU;oBAAgB;WAAoB,EAClD,qBAAC;UAAE,WAAU;;WAAgC;WAE7B,oBAAC,oBAAK,cAAgB;;;WAElC;UACA;;QACF;OACF;KAEN,oBAAC;MACC,OAAM;MACN,MAAK;OACL;;KACE;GAEN,qBAAC;IAAI,WAAU;eACb,qBAAC;KACC,MAAK;KACL,WAAU;gBACX,mCACgC,oBAAC,gBAAa,MAAM,KAAM;MACpD,EACP,oBAAC;KAAK,MAAK;KAAe,WAAU;eAAY;MAEzC;KACH;;GACF"}

package/dist/components/docs/guides/GuideNextjsOneEndpointPage.d.ts

@@ -0,0 +1,7 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/docs/guides/GuideNextjsOneEndpointPage.d.ts
+declare function GuideNextjsOneEndpointPage(): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { GuideNextjsOneEndpointPage };
+//# sourceMappingURL=GuideNextjsOneEndpointPage.d.ts.map

package/dist/components/docs/guides/GuideNextjsOneEndpointPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideNextjsOneEndpointPage.d.ts","names":[],"sources":["../../../../src/components/docs/guides/GuideNextjsOneEndpointPage.tsx"],"mappings":";;;iBAKgB,0BAAA,CAAA,GAA0B,kBAAA,CAAA,GAAA,CAAA,OAAA"}

package/dist/components/docs/guides/GuideNextjsOneEndpointPage.js

@@ -0,0 +1,258 @@
+import { StudioPrompt } from "../shared/StudioPrompt.js";
+import { ChevronRight } from "lucide-react";
+import { CodeBlock } from "@contractspec/lib.design-system";
+import { jsx, jsxs } from "react/jsx-runtime";
+import Link from "@contractspec/lib.ui-link";
+
+//#region src/components/docs/guides/GuideNextjsOneEndpointPage.tsx
+function GuideNextjsOneEndpointPage() {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "space-y-8",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-3",
+				children: [/* @__PURE__ */ jsx("h1", {
+					className: "text-4xl font-bold",
+					children: "Next.js: add one endpoint"
+				}), /* @__PURE__ */ jsx("p", {
+					className: "text-muted-foreground text-lg",
+					children: "Add ContractSpec to an existing Next.js App Router project by wiring a single operation end-to-end with validation and types."
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "card-subtle space-y-4 p-6",
+				children: [/* @__PURE__ */ jsx("h2", {
+					className: "text-2xl font-bold",
+					children: "What you'll build"
+				}), /* @__PURE__ */ jsxs("ul", {
+					className: "text-muted-foreground space-y-2 text-sm",
+					children: [
+						/* @__PURE__ */ jsx("li", { children: "One OperationSpec with SchemaModel validation." }),
+						/* @__PURE__ */ jsx("li", { children: "A registry wiring the operation to its handler." }),
+						/* @__PURE__ */ jsx("li", { children: "A Next.js route handler that exposes the operation." })
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-6",
+				children: [
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "1) Install core packages"
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "bash",
+								filename: "nextjs-install",
+								code: `bun add -D contractspec
+bun add @contractspec/lib.contracts @contractspec/lib.schema`
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Expected output: ",
+									/* @__PURE__ */ jsx("code", { children: "added 3 packages" }),
+									" and a lockfile update."
+								]
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "2) Define the operation spec"
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Create ",
+									/* @__PURE__ */ jsx("code", { children: "src/contracts/healthcheck.operation.ts" }),
+									":"
+								]
+							}),
+							/* @__PURE__ */ jsx(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" },
+  },
+});`
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "3) Register the operation"
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Create ",
+									/* @__PURE__ */ jsx("code", { children: "src/contracts/registry.ts" }),
+									":"
+								]
+							}),
+							/* @__PURE__ */ jsx(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(),
+}));`
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "4) Add the Next.js handler"
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Create ",
+									/* @__PURE__ */ jsx("code", { children: "app/api/ops/[...route]/route.ts" }),
+									":"
+								]
+							}),
+							/* @__PURE__ */ jsx(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 };`
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Expected output: the route responds at",
+									/* @__PURE__ */ jsx("code", { children: " /api/ops/healthcheck.get" }),
+									"."
+								]
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "5) Validate the spec"
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "bash",
+								filename: "nextjs-validate",
+								code: `contractspec validate src/contracts/healthcheck.operation.ts`
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Expected output: ",
+									/* @__PURE__ */ jsx("code", { children: "Validation passed" }),
+									"."
+								]
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "card-subtle space-y-3 p-6",
+						children: [
+							/* @__PURE__ */ jsx("h3", {
+								className: "text-lg font-semibold",
+								children: "Example package"
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Use ",
+									/* @__PURE__ */ jsx("code", { children: "@contractspec/example.lifecycle-dashboard" }),
+									" as a lightweight Next.js snippet reference."
+								]
+							}),
+							/* @__PURE__ */ jsx(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 .`
+							})
+						]
+					}),
+					/* @__PURE__ */ jsx(StudioPrompt, {
+						title: "Need team approvals for new endpoints?",
+						body: "Studio adds review gates, shared registries, and audit trails after you ship your first endpoint."
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-4 pt-4",
+				children: [/* @__PURE__ */ jsxs(Link, {
+					href: "/docs/guides/spec-validation-and-typing",
+					className: "btn-primary",
+					children: ["Next: Spec validation + typing ", /* @__PURE__ */ jsx(ChevronRight, { size: 16 })]
+				}), /* @__PURE__ */ jsx(Link, {
+					href: "/docs/guides",
+					className: "btn-ghost",
+					children: "Back to guides"
+				})]
+			})
+		]
+	});
+}
+
+//#endregion
+export { GuideNextjsOneEndpointPage };
+//# sourceMappingURL=GuideNextjsOneEndpointPage.js.map

package/dist/components/docs/guides/GuideNextjsOneEndpointPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideNextjsOneEndpointPage.js","names":[],"sources":["../../../../src/components/docs/guides/GuideNextjsOneEndpointPage.tsx"],"sourcesContent":["import { CodeBlock } from '@contractspec/lib.design-system';\nimport Link from '@contractspec/lib.ui-link';\nimport { ChevronRight } from 'lucide-react';\nimport { StudioPrompt } from '../shared/StudioPrompt';\n\nexport function GuideNextjsOneEndpointPage() {\n  return (\n    <div className=\"space-y-8\">\n      <div className=\"space-y-3\">\n        <h1 className=\"text-4xl font-bold\">Next.js: add one endpoint</h1>\n        <p className=\"text-muted-foreground text-lg\">\n          Add ContractSpec to an existing Next.js App Router project by wiring a\n          single operation end-to-end with validation and types.\n        </p>\n      </div>\n\n      <div className=\"card-subtle space-y-4 p-6\">\n        <h2 className=\"text-2xl font-bold\">What you'll build</h2>\n        <ul className=\"text-muted-foreground space-y-2 text-sm\">\n          <li>One OperationSpec with SchemaModel validation.</li>\n          <li>A registry wiring the operation to its handler.</li>\n          <li>A Next.js route handler that exposes the operation.</li>\n        </ul>\n      </div>\n\n      <div className=\"space-y-6\">\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">1) Install core packages</h2>\n          <CodeBlock\n            language=\"bash\"\n            filename=\"nextjs-install\"\n            code={`bun add -D contractspec\nbun add @contractspec/lib.contracts @contractspec/lib.schema`}\n          />\n          <p className=\"text-muted-foreground text-sm\">\n            Expected output: <code>added 3 packages</code> and a lockfile\n            update.\n          </p>\n        </div>\n\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">2) Define the operation spec</h2>\n          <p className=\"text-muted-foreground text-sm\">\n            Create <code>src/contracts/healthcheck.operation.ts</code>:\n          </p>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\"src/contracts/healthcheck.operation.ts\"\n            code={`import { defineQuery } from \"@contractspec/lib.contracts/operations\";\nimport { SchemaModel, ScalarTypeEnum } from \"@contractspec/lib.schema\";\n\nconst HealthcheckOutput = new SchemaModel({\n  name: \"HealthcheckOutput\",\n  fields: {\n    status: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },\n    checkedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },\n  },\n});\n\nexport const HealthcheckQuery = defineQuery({\n  meta: {\n    key: \"healthcheck.get\",\n    version: \"1.0.0\",\n    description: \"Return service health status\",\n    owners: [\"@platform.core\"],\n    tags: [\"health\", \"observability\"],\n  },\n  io: {\n    input: null,\n    output: HealthcheckOutput,\n  },\n  policy: {\n    auth: \"public\",\n  },\n  transport: {\n    rest: { method: \"GET\" },\n    gql: { field: \"healthcheck_get\" },\n    mcp: { toolName: \"healthcheck.get.v1\" },\n  },\n});`}\n          />\n        </div>\n\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">3) Register the operation</h2>\n          <p className=\"text-muted-foreground text-sm\">\n            Create <code>src/contracts/registry.ts</code>:\n          </p>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\"src/contracts/registry.ts\"\n            code={`import {\n  OperationSpecRegistry,\n  installOp,\n} from \"@contractspec/lib.contracts/operations\";\nimport { HealthcheckQuery } from \"./healthcheck.operation\";\n\nexport const registry = new OperationSpecRegistry();\n\ninstallOp(registry, HealthcheckQuery, async () => ({\n  status: \"ok\",\n  checkedAt: new Date().toISOString(),\n}));`}\n          />\n        </div>\n\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">4) Add the Next.js handler</h2>\n          <p className=\"text-muted-foreground text-sm\">\n            Create <code>app/api/ops/[...route]/route.ts</code>:\n          </p>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\"app/api/ops/[...route]/route.ts\"\n            code={`import { makeNextAppHandler } from \"@contractspec/lib.contracts/server/rest-next-app\";\nimport { registry } from \"@/contracts/registry\";\n\nconst handler = makeNextAppHandler(registry, async () => ({\n  actor: \"public\",\n  tenantId: \"public\",\n}));\n\nexport { handler as GET, handler as POST };`}\n          />\n          <p className=\"text-muted-foreground text-sm\">\n            Expected output: the route responds at\n            <code> /api/ops/healthcheck.get</code>.\n          </p>\n        </div>\n\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">5) Validate the spec</h2>\n          <CodeBlock\n            language=\"bash\"\n            filename=\"nextjs-validate\"\n            code={`contractspec validate src/contracts/healthcheck.operation.ts`}\n          />\n          <p className=\"text-muted-foreground text-sm\">\n            Expected output: <code>Validation passed</code>.\n          </p>\n        </div>\n\n        <div className=\"card-subtle space-y-3 p-6\">\n          <h3 className=\"text-lg font-semibold\">Example package</h3>\n          <p className=\"text-muted-foreground text-sm\">\n            Use <code>@contractspec/example.lifecycle-dashboard</code> as a\n            lightweight Next.js snippet reference.\n          </p>\n          <CodeBlock\n            language=\"bash\"\n            filename=\"nextjs-example\"\n            code={`# Inspect the example docs\ncontractspec examples show lifecycle-dashboard\n\n# Validate all example manifests in this repo\ncontractspec examples validate --repo-root .`}\n          />\n        </div>\n\n        <StudioPrompt\n          title=\"Need team approvals for new endpoints?\"\n          body=\"Studio adds review gates, shared registries, and audit trails after you ship your first endpoint.\"\n        />\n      </div>\n\n      <div className=\"flex items-center gap-4 pt-4\">\n        <Link\n          href=\"/docs/guides/spec-validation-and-typing\"\n          className=\"btn-primary\"\n        >\n          Next: Spec validation + typing <ChevronRight size={16} />\n        </Link>\n        <Link href=\"/docs/guides\" className=\"btn-ghost\">\n          Back to guides\n        </Link>\n      </div>\n    </div>\n  );\n}\n"],"mappings":";;;;;;;AAKA,SAAgB,6BAA6B;AAC3C,QACE,qBAAC;EAAI,WAAU;;GACb,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAA8B,EACjE,oBAAC;KAAE,WAAU;eAAgC;MAGzC;KACA;GAEN,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAsB,EACzD,qBAAC;KAAG,WAAU;;MACZ,oBAAC,kBAAG,mDAAmD;MACvD,oBAAC,kBAAG,oDAAoD;MACxD,oBAAC,kBAAG,wDAAwD;;MACzD;KACD;GAEN,qBAAC;IAAI,WAAU;;KACb,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAA6B;OAChE,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;SAEN;OACF,qBAAC;QAAE,WAAU;;SAAgC;SAC1B,oBAAC,oBAAK,qBAAuB;;;SAE5C;;OACA;KAEN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAAiC;OACpE,qBAAC;QAAE,WAAU;;SAAgC;SACpC,oBAAC,oBAAK,2CAA6C;;;SACxD;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAgCN;;OACE;KAEN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAA8B;OACjE,qBAAC;QAAE,WAAU;;SAAgC;SACpC,oBAAC,oBAAK,8BAAgC;;;SAC3C;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;;SAYN;;OACE;KAEN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAA+B;OAClE,qBAAC;QAAE,WAAU;;SAAgC;SACpC,oBAAC,oBAAK,oCAAsC;;;SACjD;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;SASN;OACF,qBAAC;QAAE,WAAU;;SAAgC;SAE3C,oBAAC,oBAAK,8BAAgC;;;SACpC;;OACA;KAEN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAAyB;OAC5D,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;SACN;OACF,qBAAC;QAAE,WAAU;;SAAgC;SAC1B,oBAAC,oBAAK,sBAAwB;;;SAC7C;;OACA;KAEN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAwB;SAAoB;OAC1D,qBAAC;QAAE,WAAU;;SAAgC;SACvC,oBAAC,oBAAK,8CAAgD;;;SAExD;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;SAKN;;OACE;KAEN,oBAAC;MACC,OAAM;MACN,MAAK;OACL;;KACE;GAEN,qBAAC;IAAI,WAAU;eACb,qBAAC;KACC,MAAK;KACL,WAAU;gBACX,mCACgC,oBAAC,gBAAa,MAAM,KAAM;MACpD,EACP,oBAAC;KAAK,MAAK;KAAe,WAAU;eAAY;MAEzC;KACH;;GACF"}

package/dist/components/docs/guides/GuideSpecValidationTypingPage.d.ts

@@ -0,0 +1,7 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/docs/guides/GuideSpecValidationTypingPage.d.ts
+declare function GuideSpecValidationTypingPage(): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { GuideSpecValidationTypingPage };
+//# sourceMappingURL=GuideSpecValidationTypingPage.d.ts.map

package/dist/components/docs/guides/GuideSpecValidationTypingPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideSpecValidationTypingPage.d.ts","names":[],"sources":["../../../../src/components/docs/guides/GuideSpecValidationTypingPage.tsx"],"mappings":";;;iBAKgB,6BAAA,CAAA,GAA6B,kBAAA,CAAA,GAAA,CAAA,OAAA"}

package/dist/components/docs/guides/GuideSpecValidationTypingPage.js

@@ -0,0 +1,205 @@
+import { StudioPrompt } from "../shared/StudioPrompt.js";
+import { ChevronRight } from "lucide-react";
+import { CodeBlock } from "@contractspec/lib.design-system";
+import { jsx, jsxs } from "react/jsx-runtime";
+import Link from "@contractspec/lib.ui-link";
+
+//#region src/components/docs/guides/GuideSpecValidationTypingPage.tsx
+function GuideSpecValidationTypingPage() {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "space-y-8",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-3",
+				children: [/* @__PURE__ */ jsx("h1", {
+					className: "text-4xl font-bold",
+					children: "Spec-driven validation + typing"
+				}), /* @__PURE__ */ jsx("p", {
+					className: "text-muted-foreground text-lg",
+					children: "Define a single operation with SchemaModel, generate validation, and keep your existing handler logic."
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "card-subtle space-y-4 p-6",
+				children: [/* @__PURE__ */ jsx("h2", {
+					className: "text-2xl font-bold",
+					children: "What you'll build"
+				}), /* @__PURE__ */ jsxs("ul", {
+					className: "text-muted-foreground space-y-2 text-sm",
+					children: [
+						/* @__PURE__ */ jsx("li", { children: "One command spec with explicit input/output models." }),
+						/* @__PURE__ */ jsx("li", { children: "Validation + typing without rewriting your service layer." }),
+						/* @__PURE__ */ jsx("li", { children: "Clear acceptance scenarios for regression safety." })
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-6",
+				children: [
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "1) Define the spec"
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Create ",
+									/* @__PURE__ */ jsx("code", { children: "src/contracts/contact-create.operation.ts" }),
+									":"
+								]
+							}),
+							/* @__PURE__ */ jsx(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"],
+      },
+    ],
+  },
+});`
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "2) Wire the handler"
+							}),
+							/* @__PURE__ */ jsx("p", {
+								className: "text-muted-foreground text-sm",
+								children: "Keep your existing code. Just ensure the handler returns the output shape defined above."
+							}),
+							/* @__PURE__ */ jsx(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(),
+   };
+ }`
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "3) Validate"
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "bash",
+								filename: "spec-validation",
+								code: `contractspec validate src/contracts/contact-create.operation.ts`
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Expected output: ",
+									/* @__PURE__ */ jsx("code", { children: "Validation passed" }),
+									"."
+								]
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "card-subtle space-y-3 p-6",
+						children: [
+							/* @__PURE__ */ jsx("h3", {
+								className: "text-lg font-semibold",
+								children: "Example package"
+							}),
+							/* @__PURE__ */ jsx("p", {
+								className: "text-muted-foreground text-sm",
+								children: "The CRM Pipeline example includes real specs, handlers, and presentations for contact + deal flows."
+							}),
+							/* @__PURE__ */ jsx(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`
+							})
+						]
+					}),
+					/* @__PURE__ */ jsx(StudioPrompt, {
+						title: "Need shared validation policies?",
+						body: "Studio lets teams enforce validation policies and review changes before they ship."
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-4 pt-4",
+				children: [/* @__PURE__ */ jsxs(Link, {
+					href: "/docs/guides/generate-docs-clients-schemas",
+					className: "btn-primary",
+					children: ["Next: Generate docs + clients ", /* @__PURE__ */ jsx(ChevronRight, { size: 16 })]
+				}), /* @__PURE__ */ jsx(Link, {
+					href: "/docs/guides",
+					className: "btn-ghost",
+					children: "Back to guides"
+				})]
+			})
+		]
+	});
+}
+
+//#endregion
+export { GuideSpecValidationTypingPage };
+//# sourceMappingURL=GuideSpecValidationTypingPage.js.map

package/dist/components/docs/guides/GuideSpecValidationTypingPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideSpecValidationTypingPage.js","names":[],"sources":["../../../../src/components/docs/guides/GuideSpecValidationTypingPage.tsx"],"sourcesContent":["import { CodeBlock } from '@contractspec/lib.design-system';\nimport Link from '@contractspec/lib.ui-link';\nimport { ChevronRight } from 'lucide-react';\nimport { StudioPrompt } from '../shared/StudioPrompt';\n\nexport function GuideSpecValidationTypingPage() {\n  return (\n    <div className=\"space-y-8\">\n      <div className=\"space-y-3\">\n        <h1 className=\"text-4xl font-bold\">Spec-driven validation + typing</h1>\n        <p className=\"text-muted-foreground text-lg\">\n          Define a single operation with SchemaModel, generate validation, and\n          keep your existing handler logic.\n        </p>\n      </div>\n\n      <div className=\"card-subtle space-y-4 p-6\">\n        <h2 className=\"text-2xl font-bold\">What you'll build</h2>\n        <ul className=\"text-muted-foreground space-y-2 text-sm\">\n          <li>One command spec with explicit input/output models.</li>\n          <li>Validation + typing without rewriting your service layer.</li>\n          <li>Clear acceptance scenarios for regression safety.</li>\n        </ul>\n      </div>\n\n      <div className=\"space-y-6\">\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">1) Define the spec</h2>\n          <p className=\"text-muted-foreground text-sm\">\n            Create <code>src/contracts/contact-create.operation.ts</code>:\n          </p>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\"src/contracts/contact-create.operation.ts\"\n            code={`import { defineCommand } from \"@contractspec/lib.contracts/operations\";\nimport { SchemaModel, ScalarTypeEnum } from \"@contractspec/lib.schema\";\n\nconst ContactInput = new SchemaModel({\n  name: \"ContactInput\",\n  fields: {\n    email: { type: ScalarTypeEnum.Email(), isOptional: false },\n    firstName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },\n    lastName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },\n  },\n});\n\nconst ContactOutput = new SchemaModel({\n  name: \"ContactOutput\",\n  fields: {\n    id: { type: ScalarTypeEnum.String(), isOptional: false },\n    email: { type: ScalarTypeEnum.Email(), isOptional: false },\n    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },\n  },\n});\n\nexport const ContactCreateCommand = defineCommand({\n  meta: {\n    key: \"contact.create\",\n    version: \"1.0.0\",\n    description: \"Create a CRM contact\",\n    owners: [\"@sales\"],\n    tags: [\"crm\", \"contacts\"],\n  },\n  io: {\n    input: ContactInput,\n    output: ContactOutput,\n  },\n  policy: {\n    auth: \"user\",\n  },\n  acceptance: {\n    scenarios: [\n      {\n        key: \"create-contact\",\n        given: [\"User is authenticated\"],\n        when: [\"ContactCreateCommand executes\"],\n        then: [\"Contact is persisted\", \"Email is validated\"],\n      },\n    ],\n  },\n});`}\n          />\n        </div>\n\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">2) Wire the handler</h2>\n          <p className=\"text-muted-foreground text-sm\">\n            Keep your existing code. Just ensure the handler returns the output\n            shape defined above.\n          </p>\n          <CodeBlock\n            language=\"typescript\"\n            filename=\"src/handlers/contact-create.ts\"\n            code={`import { ContactCreateCommand } from \"@/contracts/contact-create.operation\";\n \n export async function handleContactCreate(\n   input: (typeof ContactCreateCommand)[\"io\"][\"input\"],\n   ctx: { userId: string }\n ) {\n   // Your existing persistence logic\n   return {\n     id: \"contact_123\",\n     email: input.email,\n     createdAt: new Date().toISOString(),\n   };\n }`}\n          />\n        </div>\n\n        <div className=\"space-y-3\">\n          <h2 className=\"text-2xl font-bold\">3) Validate</h2>\n          <CodeBlock\n            language=\"bash\"\n            filename=\"spec-validation\"\n            code={`contractspec validate src/contracts/contact-create.operation.ts`}\n          />\n          <p className=\"text-muted-foreground text-sm\">\n            Expected output: <code>Validation passed</code>.\n          </p>\n        </div>\n\n        <div className=\"card-subtle space-y-3 p-6\">\n          <h3 className=\"text-lg font-semibold\">Example package</h3>\n          <p className=\"text-muted-foreground text-sm\">\n            The CRM Pipeline example includes real specs, handlers, and\n            presentations for contact + deal flows.\n          </p>\n          <CodeBlock\n            language=\"bash\"\n            filename=\"crm-example\"\n            code={`# Build + validate the CRM pipeline example\ncd packages/examples/crm-pipeline\nbun install\nbun run build\nbun run validate`}\n          />\n        </div>\n\n        <StudioPrompt\n          title=\"Need shared validation policies?\"\n          body=\"Studio lets teams enforce validation policies and review changes before they ship.\"\n        />\n      </div>\n\n      <div className=\"flex items-center gap-4 pt-4\">\n        <Link\n          href=\"/docs/guides/generate-docs-clients-schemas\"\n          className=\"btn-primary\"\n        >\n          Next: Generate docs + clients <ChevronRight size={16} />\n        </Link>\n        <Link href=\"/docs/guides\" className=\"btn-ghost\">\n          Back to guides\n        </Link>\n      </div>\n    </div>\n  );\n}\n"],"mappings":";;;;;;;AAKA,SAAgB,gCAAgC;AAC9C,QACE,qBAAC;EAAI,WAAU;;GACb,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAoC,EACvE,oBAAC;KAAE,WAAU;eAAgC;MAGzC;KACA;GAEN,qBAAC;IAAI,WAAU;eACb,oBAAC;KAAG,WAAU;eAAqB;MAAsB,EACzD,qBAAC;KAAG,WAAU;;MACZ,oBAAC,kBAAG,wDAAwD;MAC5D,oBAAC,kBAAG,8DAA8D;MAClE,oBAAC,kBAAG,sDAAsD;;MACvD;KACD;GAEN,qBAAC;IAAI,WAAU;;KACb,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAAuB;OAC1D,qBAAC;QAAE,WAAU;;SAAgC;SACpC,oBAAC,oBAAK,8CAAgD;;;SAC3D;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SA+CN;;OACE;KAEN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAAwB;OAC3D,oBAAC;QAAE,WAAU;kBAAgC;SAGzC;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;;;;;;;;;SAaN;;OACE;KAEN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAqB;SAAgB;OACnD,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;SACN;OACF,qBAAC;QAAE,WAAU;;SAAgC;SAC1B,oBAAC,oBAAK,sBAAwB;;;SAC7C;;OACA;KAEN,qBAAC;MAAI,WAAU;;OACb,oBAAC;QAAG,WAAU;kBAAwB;SAAoB;OAC1D,oBAAC;QAAE,WAAU;kBAAgC;SAGzC;OACJ,oBAAC;QACC,UAAS;QACT,UAAS;QACT,MAAM;;;;;SAKN;;OACE;KAEN,oBAAC;MACC,OAAM;MACN,MAAK;OACL;;KACE;GAEN,qBAAC;IAAI,WAAU;eACb,qBAAC;KACC,MAAK;KACL,WAAU;gBACX,kCAC+B,oBAAC,gBAAa,MAAM,KAAM;MACnD,EACP,oBAAC;KAAK,MAAK;KAAe,WAAU;eAAY;MAEzC;KACH;;GACF"}

package/dist/components/docs/guides/GuidesIndexPage.d.ts

@@ -0,0 +1,7 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/docs/guides/GuidesIndexPage.d.ts
+declare function GuidesIndexPage(): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { GuidesIndexPage };
+//# sourceMappingURL=GuidesIndexPage.d.ts.map

package/dist/components/docs/guides/GuidesIndexPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuidesIndexPage.d.ts","names":[],"sources":["../../../../src/components/docs/guides/GuidesIndexPage.tsx"],"mappings":";;;iBAwDgB,eAAA,CAAA,GAAe,kBAAA,CAAA,GAAA,CAAA,OAAA"}