@contractspec/lib.contracts-spec 2.0.0

package/dist/examples/docs/examples.docblock.js

@@ -0,0 +1,307 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/examples/docs/examples.docblock.ts
+var tech_contracts_examples_DocBlocks = [
+  {
+    id: "docs.tech.contracts.examples",
+    title: "Example Specifications",
+    summary: "ExampleSpec defines complete, demonstrable ContractSpec applications.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/contracts/examples",
+    tags: ["tech", "contracts", "examples", "templates"],
+    body: `## Example Specifications
+
+ExampleSpec is a contract for defining complete, demonstrable ContractSpec applications. Examples integrate with AppBlueprintSpec and FeatureModuleSpec to provide a full application specification.
+
+### Overview
+
+An \`ExampleSpec\` captures:
+- **Metadata** (via \`ExampleMeta\` extending \`OwnerShipMeta\`): key, version, title, description, ownership, tags, stability
+- **Example-specific fields**: kind, visibility, summary
+- **Surfaces**: where the example can be used (templates, sandbox, studio, MCP)
+- **Entrypoints**: package exports mapping
+- **Blueprint**: optional AppBlueprintSpec or reference
+- **Features**: optional FeatureModuleSpec array or references
+
+### Usage
+
+\`\`\`typescript
+import type { ExampleSpec } from '@contractspec/lib.contracts-spec';
+import { ExampleRegistry, validateExample } from '@contractspec/lib.contracts-spec';
+
+const example: ExampleSpec = {
+  meta: {
+    key: 'saas-boilerplate',
+    version: '1.0.0',
+    title: 'SaaS Boilerplate',
+    description: 'Multi-tenant SaaS foundation with billing and RBAC.',
+    kind: 'template',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@saas-team'],
+    tags: ['saas', 'multi-tenant', 'billing'],
+    summary: 'Complete SaaS starter.',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['playground', 'specs', 'builder'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.saas-boilerplate',
+    feature: './saas-boilerplate.feature',
+    contracts: './contracts',
+  },
+  features: [SaasBoilerplateFeature],
+};
+\`\`\`
+
+### ExampleRegistry
+
+Use \`ExampleRegistry\` to manage examples:
+
+\`\`\`typescript
+const registry = new ExampleRegistry();
+registry.register(example);
+
+// Query examples
+registry.listByKind('template');
+registry.listByVisibility('public');
+registry.listBySurface('studio');
+registry.listInstallable();
+registry.search('billing');
+\`\`\`
+
+### ExampleMeta
+
+\`ExampleMeta\` extends \`OwnerShipMeta\` with example-specific fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| key | string | Unique identifier |
+| version | number | Spec version |
+| title | string? | Human-readable title |
+| description | string | Technical description |
+| kind | ExampleKind | template, workflow, integration, etc. |
+| visibility | ExampleVisibility | public, internal, experimental |
+| stability | Stability | idea, experimental, beta, stable, deprecated |
+| owners | string[] | Owner identifiers |
+| tags | string[] | Discovery tags |
+| summary | string? | Marketing summary |
+
+### ExampleKind
+
+| Kind | Use Case |
+|------|----------|
+| template | Full application template |
+| workflow | Workflow automation example |
+| integration | Integration showcase |
+| knowledge | Knowledge base example |
+| blueprint | App blueprint example |
+| ui | UI component showcase |
+| script | CLI/script example |
+| library | Library/SDK example |
+
+### Surfaces
+
+| Surface | Purpose |
+|---------|---------|
+| templates | Available as new project template |
+| sandbox | Interactive playground support |
+| studio | ContractSpec Studio support |
+| mcp | Model Context Protocol support |
+
+### Validation
+
+\`\`\`typescript
+import { validateExample, validateExamples } from '@contractspec/lib.contracts-spec';
+
+const result = validateExample(example);
+if (!result.valid) {
+  console.error(result.errors);
+}
+
+// Batch validation with duplicate detection
+const batchResult = validateExamples([example1, example2]);
+\`\`\`
+
+### Integration with Blueprints and Features
+
+Examples can reference or embed blueprints and features:
+
+\`\`\`typescript
+const example: ExampleSpec = {
+  // ... meta, surfaces, entrypoints
+  
+  // Inline blueprint
+  blueprint: myAppBlueprint,
+  
+  // Or reference by pointer
+  blueprint: { key: 'core.app', version: '1.0.0' },
+  
+  // Inline features
+  features: [MyFeature],
+  
+  // Or reference
+  features: [{ key: 'my-feature' }],
+};
+\`\`\`
+
+### Related
+
+- [App Configuration](file:///docs/tech/contracts/app-config) - AppBlueprintSpec
+- [Features](file:///docs/tech/contracts/features) - FeatureModuleSpec
+`
+  }
+];
+registerDocBlocks(tech_contracts_examples_DocBlocks);
+export {
+  tech_contracts_examples_DocBlocks
+};

package/dist/examples/index.d.ts

@@ -0,0 +1,7 @@
+export type { ExampleKind, ExampleVisibility, ExampleSandboxMode, ExampleDocumentation, ExampleSandboxSupport, ExampleStudioSupport, ExampleMcpSupport, ExampleSurfaces, ExampleEntrypoints, ExampleMeta, ExampleSpec, } from './types';
+export { ExampleKindEnum, ExampleVisibilityEnum, ExampleSandboxModeEnum, isSpecPointer, isFeatureRef, isExampleKind, isExampleVisibility, } from './types';
+export { ExampleKindSchema, ExampleVisibilitySchema, ExampleSandboxModeSchema, ExampleDocumentationSchema, ExampleSurfacesSchema, ExampleEntrypointsSchema, ExampleMetaSchema, ExampleSpecSchema, parseExampleSpec, safeParseExampleSpec, parseExampleMeta, parseExampleSurfaces, parseExampleEntrypoints, parseExampleDocumentation, } from './schema';
+export { ExampleRegistry } from './registry';
+export type { ExampleValidationError, ExampleValidationWarning, ValidateExamplesResult, ValidateExampleResult, CrossValidationContext, } from './validation';
+export { validateExample, validateExamples, validateExampleReferences, } from './validation';
+export { defineExample } from './define';