# ContractSpec — LLM Guide (Full) > Aggregated content from all packages. For summary, see /llms Generated: 2026-03-26T14:20:33.978Z Packages: 164 --- ## @contractspec/lib.accessibility Description: WCAG compliance utilities and validators Path: packages/libs/accessibility URL: /llms/lib.accessibility # @contractspec/lib.accessibility Website: https://contractspec.io **WCAG compliance utilities and validators.** ## What It Provides - **Layer**: lib. - **Consumers**: design-system, example apps. - Related ContractSpec packages include `@contractspec/lib.design-system`, `@contractspec/lib.ui-kit`, `@contractspec/lib.ui-kit-web`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.design-system`, `@contractspec/lib.ui-kit`, `@contractspec/lib.ui-kit-web`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.accessibility` or `bun add @contractspec/lib.accessibility` ## Usage Import the root entrypoint from `@contractspec/lib.accessibility`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/AccessibilityPanel.tsx` is part of the package's public or composition surface. - `src/AccessibilityProvider.tsx` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/nativewind-env.d.ts` is part of the package's public or composition surface. - `src/next-route-announcer.tsx` is part of the package's public or composition surface. - `src/preferences.tsx` is part of the package's public or composition surface. - `src/styles.css` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./AccessibilityPanel` resolves through `./src/AccessibilityPanel.tsx`. - Export `./AccessibilityProvider` resolves through `./src/AccessibilityProvider.tsx`. - Export `./nativewind-env.d` resolves through `./src/nativewind-env.d.ts`. - Export `./next-route-announcer` resolves through `./src/next-route-announcer.tsx`. - Export `./preferences` resolves through `./src/preferences.tsx`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - WCAG compliance standards must be preserved; changes affect all UI surfaces. - Do not weaken or remove existing validators without coordinating with design-system consumers. --- ## @contractspec/lib.ai-agent Description: AI agent orchestration with MCP and tool support Path: packages/libs/ai-agent URL: /llms/lib.ai-agent # @contractspec/lib.ai-agent Website: https://contractspec.io **Core AI agent runtime for ContractSpec with tool orchestration, MCP integration, session state, memory, and telemetry.** ## What It Provides - Provides the central agent runtime used by chat, automation, and higher-level orchestration packages. - Supports tools, sessions, memory, approvals, providers, telemetry, and MCP-aware workflows. - Acts as the stable public API for agent execution across multiple runtimes and delivery surfaces. - Consumes agent definitions from `@contractspec/lib.contracts-spec/agent`. - `src/providers/` contains provider integrations and provider-facing adapters. ## Installation `npm install @contractspec/lib.ai-agent` or `bun add @contractspec/lib.ai-agent` ## Usage Define agents in `@contractspec/lib.contracts-spec/agent`, then run or export them with `@contractspec/lib.ai-agent`. ```ts import { defineAgent } from "@contractspec/lib.contracts-spec/agent"; import { createUnifiedAgent } from "@contractspec/lib.ai-agent/agent/unified-agent"; const SupportBot = defineAgent({ meta: { key: "support.bot", version: "1.0.0", description: "Customer support assistant", owners: ["support"], tags: ["support"], stability: "experimental", }, instructions: "Resolve tickets and escalate low-confidence cases.", tools: [{ name: "support.resolve" }], }); const agent = createUnifiedAgent(SupportBot, { backend: "ai-sdk", }); ``` Runtime portability stays adapter-first: - `AgentSpec.runtime` can declare checkpointing, suspend/resume, and approval-gateway capabilities. - `AgentFactory` and `ContractSpecAgent` accept optional runtime adapter bundles for LangGraph/LangChain-style integrations. - Session state now persists workflow, thread, trace, checkpoint, and approval metadata for replay-safe resumes. - Escalation policies can raise approval requests on timeout, tool failure, or confidence thresholds without coupling core contracts to a vendor runtime. ## Architecture - `src/agent/`, `src/session/`, and `src/memory/` contain the runtime core for execution state and persistence hooks. - `src/tools/`, `src.providers/`, and `src.interop/` connect providers, tools, and MCP-aware runtime surfaces. - `src.telemetry/`, `src.approval/`, `src.knowledge/`, and `src.schema/` round out runtime policy and observability surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Large multi-subpath library exporting agent runtime, approval, memory, knowledge, providers, schema, telemetry, tools, and types. - Export `.` resolves through `./src/index.ts`. - Export `./agent` resolves through `./src/agent/index.ts`. - Export `./agent/agent-factory` resolves through `./src/agent/agent-factory.ts`. - Export `./agent/contract-spec-agent` resolves through `./src/agent/contract-spec-agent.ts`. - Export `./agent/json-runner` resolves through `./src/agent/json-runner.ts`. - Export `./agent/unified-agent` resolves through `./src/agent/unified-agent.ts`. - Export `./approval` resolves through `./src/approval/index.ts`. - Export `./approval/workflow` resolves through `./src/approval/workflow.ts`. - Export `./exporters` resolves through `./src/exporters/index.ts`. - Export `./exporters/claude-agent-exporter` resolves through `./src/exporters/claude-agent-exporter.ts`. - Additional runtime subpaths are published through `package.json`; keep docs aligned with the manifest. ## Migration Note `@contractspec/lib.ai-agent` no longer owns the agent-definition contract layer. - Removed: `@contractspec/lib.ai-agent/spec` - Removed: `@contractspec/lib.ai-agent/spec/spec` - Removed: `@contractspec/lib.ai-agent/spec/registry` - Use `@contractspec/lib.contracts-spec/agent` for `AgentSpec`, `AgentToolConfig`, `AgentRegistry`, `createAgentRegistry`, and `defineAgent` ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Missing dependencies (thanks to knip). - Replace eslint+prettier by biomejs to optimize speed. - Agentic workflows — subagents, memory tools, and next steps. - Vnext ai-native. - Backend operations + frontend rendering support. - Add latest models and align defaults. ## Notes - High blast radius — used by multiple bundles and libs. - Agent definitions are owned by `@contractspec/lib.contracts-spec/agent`. - This package is runtime-focused: execution, exporters, MCP/tool bridges, sessions, memory, approvals, providers, and telemetry. - MCP transport adapters must stay runtime-agnostic (no Node/browser-specific globals). --- ## @contractspec/lib.ai-providers Description: Unified AI provider abstraction layer Path: packages/libs/ai-providers URL: /llms/lib.ai-providers # @contractspec/lib.ai-providers Website: https://contractspec.io **Unified AI provider abstraction layer.** ## What It Provides - **Layer**: lib. - **Consumers**: ai-agent, content-gen, image-gen, voice. - Related ContractSpec packages include `@contractspec/lib.provider-ranking`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.provider-ranking`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.ai-providers` or `bun add @contractspec/lib.ai-providers` ## Usage Import the root entrypoint from `@contractspec/lib.ai-providers`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/factory.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/legacy.ts` is part of the package's public or composition surface. - `src/models.test.ts` is part of the package's public or composition surface. - `src/models.ts` is part of the package's public or composition surface. - `src/selector-types.ts` is part of the package's public or composition surface. - `src/selector.ts` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./factory` resolves through `./src/factory.ts`. - Export `./legacy` resolves through `./src/legacy.ts`. - Export `./models` resolves through `./src/models.ts`. - Export `./selector` resolves through `./src/selector.ts`. - Export `./selector-types` resolves through `./src/selector-types.ts`. - Export `./types` resolves through `./src/types.ts`. - Export `./validation` resolves through `./src/validation.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add latest models and align defaults. - Resolve lint, build, and type errors across nine packages. - Add first-class transport, auth, versioning, and BYOK support across all integrations. - Add AI provider ranking system with ranking-driven model selection. - Add first-class mistral provider support. ## Notes - Provider interface is consumed by all AI-powered libs; breaking changes cascade widely. - Adding new providers must not break existing factory signatures. --- ## @contractspec/lib.analytics Description: Product analytics and growth metrics Path: packages/libs/analytics URL: /llms/lib.analytics # @contractspec/lib.analytics Website: https://contractspec.io **Product analytics and growth metrics.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, apps. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.lifecycle`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.lifecycle`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.analytics` or `bun add @contractspec/lib.analytics` ## Usage Import the root entrypoint from `@contractspec/lib.analytics`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/churn` is part of the package's public or composition surface. - `src/cohort` is part of the package's public or composition surface. - `src/funnel` is part of the package's public or composition surface. - `src/growth` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/lifecycle` is part of the package's public or composition surface. - `src/posthog` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./churn` resolves through `./src/churn/index.ts`. - Export `./churn/predictor` resolves through `./src/churn/predictor.ts`. - Export `./cohort` resolves through `./src/cohort/index.ts`. - Export `./cohort/tracker` resolves through `./src/cohort/tracker.ts`. - Export `./funnel` resolves through `./src/funnel/index.ts`. - Export `./funnel/analyzer` resolves through `./src/funnel/analyzer.ts`. - Export `./growth` resolves through `./src/growth/index.ts`. - Export `./growth/hypothesis-generator` resolves through `./src/growth/hypothesis-generator.ts`. - Export `./lifecycle` resolves through `./src/lifecycle/index.ts`. - The package publishes 16 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Event naming conventions must stay consistent with PostHog taxonomy. - Metric calculations affect live dashboards; verify formulas before changing. --- ## @contractspec/lib.bus Description: Event bus and messaging primitives Path: packages/libs/bus URL: /llms/lib.bus # @contractspec/lib.bus Website: https://contractspec.io **Event bus and messaging primitives.** ## What It Provides - **Layer**: lib. - **Consumers**: personalization, bundles. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.bus` or `bun add @contractspec/lib.bus` ## Usage Import the root entrypoint from `@contractspec/lib.bus`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/auditableBus.ts` is part of the package's public or composition surface. - `src/eventBus.ts` is part of the package's public or composition surface. - `src/filtering.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/inMemoryBus.ts` is part of the package's public or composition surface. - `src/metadata.ts` is part of the package's public or composition surface. - `src/subscriber.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./auditableBus` resolves through `./src/auditableBus.ts`. - Export `./eventBus` resolves through `./src/eventBus.ts`. - Export `./filtering` resolves through `./src/filtering.ts`. - Export `./inMemoryBus` resolves through `./src/inMemoryBus.ts`. - Export `./metadata` resolves through `./src/metadata.ts`. - Export `./subscriber` resolves through `./src/subscriber.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - `EventBus` interface is a core contract; changes affect all event-driven communication. - Do not alter the subscriber/publish protocol without coordinating with all consumers. --- ## @contractspec/lib.content-gen Description: AI-powered content generation for blog, email, and social Path: packages/libs/content-gen URL: /llms/lib.content-gen # @contractspec/lib.content-gen Website: https://contractspec.io **AI-powered content generation for blog, email, and social.** ## What It Provides - **Layer**: lib. - **Consumers**: image-gen, voice, video-gen, bundles. - Related ContractSpec packages include `@contractspec/lib.ai-providers`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.ai-providers`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.content-gen` or `bun add @contractspec/lib.content-gen` ## Usage Import the root entrypoint from `@contractspec/lib.content-gen`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/generators` is part of the package's public or composition surface. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/seo` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./generators` resolves through `./src/generators/index.ts`. - Export `./generators/blog` resolves through `./src/generators/blog.ts`. - Export `./generators/email` resolves through `./src/generators/email.ts`. - Export `./generators/landing-page` resolves through `./src/generators/landing-page.ts`. - Export `./generators/social` resolves through `./src/generators/social.ts`. - Export `./i18n` resolves through `./src/i18n/index.ts`. - Export `./i18n/catalogs` resolves through `./src/i18n/catalogs/index.ts`. - Export `./i18n/catalogs/en` resolves through `./src/i18n/catalogs/en.ts`. - Export `./i18n/catalogs/es` resolves through `./src/i18n/catalogs/es.ts`. - The package publishes 17 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and test failures across voice, workspace, library, and composio. - Add first-class transport, auth, versioning, and BYOK support across all integrations. - Add AI provider ranking system with ranking-driven model selection. - Add full i18n support across all 10 packages (en/fr/es, 460 keys). ## Notes - Generator interface is shared across media libs (image-gen, voice, video-gen); keep it stable. - i18n keys must stay in sync with consuming packages. --- ## @contractspec/lib.context-storage Description: Context pack and snapshot storage primitives Path: packages/libs/context-storage URL: /llms/lib.context-storage # @contractspec/lib.context-storage Website: https://contractspec.io **Context pack and snapshot storage primitives.** ## What It Provides - **Layer**: lib. - **Consumers**: module.context-storage. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.context-storage` or `bun add @contractspec/lib.context-storage` ## Usage Import the root entrypoint from `@contractspec/lib.context-storage`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/in-memory-store.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/store.ts` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./in-memory-store` resolves through `./src/in-memory-store.ts`. - Export `./store` resolves through `./src/store.ts`. - Export `./types` resolves through `./src/types.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add AI provider ranking system with ranking-driven model selection. ## Notes - `Store` interface is the contract boundary for persistence adapters; do not change its shape without updating all adapters. --- ## @contractspec/lib.contracts-integrations Description: Integration contract definitions for external services Path: packages/libs/contracts-integrations URL: /llms/lib.contracts-integrations # @contractspec/lib.contracts-integrations **Integration contract definitions for external services.** ## What It Provides - **Layer**: lib. - **Consumers**: content-gen, image-gen, voice, jobs, metering, analytics, observability, support-bot. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.contracts-integrations` or `bun add @contractspec/lib.contracts-integrations` ## Usage Import the root entrypoint from `@contractspec/lib.contracts-integrations`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/integrations` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./integrations` resolves through `./src/integrations/index.ts`. - Export `./integrations/auth` resolves through `./src/integrations/auth.ts`. - Export `./integrations/auth-helpers` resolves through `./src/integrations/auth-helpers.ts`. - Export `./integrations/binding` resolves through `./src/integrations/binding.ts`. - Export `./integrations/byok` resolves through `./src/integrations/byok.ts`. - Export `./integrations/connection` resolves through `./src/integrations/connection.ts`. - Export `./integrations/docs/integrations.docblock` resolves through `./src/integrations/docs/integrations.docblock.ts`. - Export `./integrations/health` resolves through `./src/integrations/health.ts`. - Export `./integrations/health/contracts` resolves through `./src/integrations/health/contracts/index.ts`. - The package publishes 121 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint and build errors in workspace bundle and integrations lib. - Missing contract layers. - Resolve lint, build, and type errors across nine packages. - Normalize formatting across contracts-integrations, composio, and observability. - Add Composio universal fallback, fix provider-ranking types, and expand package exports. ## Notes - High blast radius — integration contracts are consumed by many libs. - Provider and secret catalog schemas must stay backward-compatible. - Adding a new integration must not break existing subpath imports. --- ## @contractspec/lib.contracts-library Description: (none) Path: packages/libs/contracts-library URL: /llms/lib.contracts-library # @contractspec/lib.contracts-library **Contract definitions for library templates and local runtime.** ## What It Provides - **Layer**: lib. - **Consumers**: `bundle.library`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.contracts-library` or `bun add @contractspec/lib.contracts-library` ## Usage Import the root entrypoint from `@contractspec/lib.contracts-library`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/templates` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./templates` resolves through `./src/templates/index.ts`. - Export `./templates/messaging` resolves through `./src/templates/messaging.ts`. - Export `./templates/recipes` resolves through `./src/templates/recipes.ts`. - Export `./templates/todos` resolves through `./src/templates/todos.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Template contracts define the shape consumed by bundle.library — breaking changes cascade to all template renderers. - Keep contract schemas additive; avoid removing or renaming fields without a migration path. --- ## @contractspec/lib.contracts-runtime-client-react Description: React runtime adapters for ContractSpec contracts Path: packages/libs/contracts-runtime-client-react URL: /llms/lib.contracts-runtime-client-react # @contractspec/lib.contracts-runtime-client-react **React runtime adapters for ContractSpec contracts.** ## What It Provides - **Layer**: lib. - **Consumers**: design-system, presentation-runtime-react, bundles. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.contracts-runtime-client-react` or `bun add @contractspec/lib.contracts-runtime-client-react` ## Usage Import the root entrypoint from `@contractspec/lib.contracts-runtime-client-react`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/drivers` is part of the package's public or composition surface. - `src/feature-render.ts` is part of the package's public or composition surface. - `src/form-render.impl.tsx` is part of the package's public or composition surface. - `src/form-render.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./drivers/rn-reusables` resolves through `./src/drivers/rn-reusables.ts`. - Export `./drivers/shadcn` resolves through `./src/drivers/shadcn.ts`. - Export `./feature-render` resolves through `./src/feature-render.ts`. - Export `./form-render` resolves through `./src/form-render.ts`. - Export `./form-render.impl` resolves through `./src/form-render.impl.tsx`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Driver interface must stay compatible with both shadcn and RN Reusables. - Form rendering pipeline is a critical path; test thoroughly before changing. --- ## @contractspec/lib.contracts-runtime-server-graphql Description: GraphQL server runtime adapters for ContractSpec contracts Path: packages/libs/contracts-runtime-server-graphql URL: /llms/lib.contracts-runtime-server-graphql # @contractspec/lib.contracts-runtime-server-graphql **GraphQL server runtime adapters for ContractSpec contracts.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, apps with GraphQL. - Related ContractSpec packages include `@contractspec/lib.contracts-runtime-server-rest`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-runtime-server-rest`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.contracts-runtime-server-graphql` or `bun add @contractspec/lib.contracts-runtime-server-graphql` ## Usage Import the root entrypoint from `@contractspec/lib.contracts-runtime-server-graphql`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/graphql-pothos.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./graphql-pothos` resolves through `./src/graphql-pothos.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Pothos builder integration must stay compatible with graphql-core and graphql-prisma. - Do not introduce direct schema mutations outside the Pothos pipeline. --- ## @contractspec/lib.contracts-runtime-server-mcp Description: MCP server runtime adapters for ContractSpec contracts Path: packages/libs/contracts-runtime-server-mcp URL: /llms/lib.contracts-runtime-server-mcp # @contractspec/lib.contracts-runtime-server-mcp **MCP server runtime adapters for ContractSpec contracts.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, CLI, VS Code extension. - `src/mcp/` contains MCP handlers, tools, prompts, and resources. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.logger`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/mcp/` contains MCP handlers, tools, prompts, and resources. ## Installation `npm install @contractspec/lib.contracts-runtime-server-mcp` or `bun add @contractspec/lib.contracts-runtime-server-mcp` ## Usage Import the root entrypoint from `@contractspec/lib.contracts-runtime-server-mcp`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/mcp/` contains MCP handlers, tools, prompts, and resources. - `src/provider-mcp.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./mcp/createMcpServer` resolves through `./src/mcp/createMcpServer.ts`. - Export `./mcp/mcpTypes` resolves through `./src/mcp/mcpTypes.ts`. - Export `./mcp/registerPresentations` resolves through `./src/mcp/registerPresentations.ts`. - Export `./mcp/registerPrompts` resolves through `./src/mcp/registerPrompts.ts`. - Export `./mcp/registerResources` resolves through `./src/mcp/registerResources.ts`. - Export `./mcp/registerTools` resolves through `./src/mcp/registerTools.ts`. - Export `./provider-mcp` resolves through `./src/provider-mcp.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add changesets and apply pending fixes. ## Notes - MCP protocol compliance is critical; transport layer must stay spec-compliant. - Do not introduce runtime-specific (Node/browser) dependencies in the transport layer. --- ## @contractspec/lib.contracts-runtime-server-rest Description: REST server runtime adapters for ContractSpec contracts Path: packages/libs/contracts-runtime-server-rest URL: /llms/lib.contracts-runtime-server-rest # @contractspec/lib.contracts-runtime-server-rest **REST server runtime adapters for ContractSpec contracts.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, all REST apps. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.contracts-runtime-server-rest` or `bun add @contractspec/lib.contracts-runtime-server-rest` ## Usage Import the root entrypoint from `@contractspec/lib.contracts-runtime-server-rest`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/contracts-adapter-hydration.ts` is part of the package's public or composition surface. - `src/contracts-adapter-input.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/rest-elysia.ts` is part of the package's public or composition surface. - `src/rest-express.ts` is part of the package's public or composition surface. - `src/rest-generic.ts` is part of the package's public or composition surface. - `src/rest-next-app.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./contracts-adapter-hydration` resolves through `./src/contracts-adapter-hydration.ts`. - Export `./contracts-adapter-input` resolves through `./src/contracts-adapter-input.ts`. - Export `./rest-elysia` resolves through `./src/rest-elysia.ts`. - Export `./rest-express` resolves through `./src/rest-express.ts`. - Export `./rest-generic` resolves through `./src/rest-generic.ts`. - Export `./rest-next-app` resolves through `./src/rest-next-app.ts`. - Export `./rest-next-pages` resolves through `./src/rest-next-pages.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - High blast radius — all REST APIs depend on this package. - Framework adapters (Elysia, Express, Next.js) must stay independent of each other. - Do not introduce cross-adapter coupling. --- ## @contractspec/lib.contracts-spec Description: Spec definitions and registries for ContractSpec Path: packages/libs/contracts-spec URL: /llms/lib.contracts-spec # @contractspec/lib.contracts-spec Core contract declarations, registries, and shared execution primitives for ContractSpec. Website: https://contractspec.io/ ## Why this package exists `@contractspec/lib.contracts-spec` is the foundation of the split from `@contractspec/lib.contracts`. It gives you one place to define behavior before implementation: 1. Declare specs (operations, events, forms, resources, policies). 2. Bind handlers. 3. Project the same contracts into REST, GraphQL, MCP, and React runtimes. This spec-first flow improves determinism, regeneration safety, and multi-surface consistency. ## Package boundary (important) Use this package for: - Contract declarations (`defineCommand`, `defineQuery`, `defineEvent`, `defineResourceTemplate`, etc.). - Agent definition contracts (`defineAgent`, `AgentRegistry`, `AgentSpec`, `AgentToolConfig`). - Core registries (`OperationSpecRegistry`, `EventRegistry`, `FormRegistry`, `ResourceRegistry`). - Shared execution/runtime-neutral types (`HandlerCtx`, policy decision types, telemetry trigger types). - Contract installation helpers (`installOp`, `op`, `makeEmit`). Do not use this package for framework adapters: - REST adapters -> `@contractspec/lib.contracts-runtime-server-rest` - GraphQL adapters -> `@contractspec/lib.contracts-runtime-server-graphql` - MCP adapters -> `@contractspec/lib.contracts-runtime-server-mcp` - React runtime rendering -> `@contractspec/lib.contracts-runtime-client-react` - Integration provider/secret catalogs -> `@contractspec/lib.contracts-integrations` ## Installation ```bash npm install @contractspec/lib.contracts-spec @contractspec/lib.schema # or bun add @contractspec/lib.contracts-spec @contractspec/lib.schema ``` ## Core concepts - `defineCommand` / `defineQuery`: typed operation specs with metadata, I/O schema, policy, transport hints, and side effects. - `defineAgent` + `AgentRegistry`: typed agent-definition contracts that runtime packages execute, export, or adapt. - `OperationSpecRegistry`: registers specs, binds handlers, and executes with validation/policy/event guards. - `defineEvent` + `EventRegistry`: typed event contracts and lookup. - `defineResourceTemplate` + `ResourceRegistry`: URI-template-based resource contracts. - `FormRegistry`: contract-first form declarations consumed by UI runtimes. - `installOp`: one-call helper to register + bind operation handlers. - `makeEmit`: typed helper for declared event emission in handlers. ## Agent Definitions Agent declarations now live in `@contractspec/lib.contracts-spec/agent`. ```ts import { AgentRegistry, defineAgent } from "@contractspec/lib.contracts-spec/agent"; const SupportBot = defineAgent({ meta: { key: "support.bot", version: "1.0.0", description: "Customer support assistant", owners: ["support"], tags: ["support"], stability: "experimental", }, instructions: "Resolve tickets and escalate low-confidence cases.", tools: [{ name: "support.resolve" }], }); const registry = new AgentRegistry().register(SupportBot); ``` Runtime execution, exporters, MCP bridges, and provider adapters stay in `@contractspec/lib.ai-agent`. ## Migration Note If you previously imported agent-definition contracts from `@contractspec/lib.ai-agent/spec`, migrate to: - `@contractspec/lib.contracts-spec/agent` - `@contractspec/lib.contracts-spec/agent/spec` - `@contractspec/lib.contracts-spec/agent/registry` ## Bundle requires alignment When using `@contractspec/lib.surface-runtime`, bundle specs declare required features via `ModuleBundleSpec.requires` (e.g. `{ key: 'ai-chat', version: '1.0.0' }`). These entries should match `FeatureModuleSpec.meta` from `defineFeature`. Register features (e.g. `AiChatFeature` from `@contractspec/module.ai-chat`) in a `FeatureRegistry` when validating bundle requirements. The bundle runtime can call `registry.get(key)` to verify each required feature exists before resolution. ## Canonical self-contained examples by contract type Use these example packages when you want one focused, importable reference per contract layer. `knowledge` and `type` are covered through the exported knowledge bindings/source configs and schema models. `agent` definitions now live directly in this package via `@contractspec/lib.contracts-spec/agent`. - `operation`, `feature`, `example`, `type`: [`@contractspec/example.minimal`](../../examples/minimal/README.md) - `event`, `presentation`, `capability`, `test-spec`: [`@contractspec/example.workflow-system`](../../examples/workflow-system/README.md) - `data-view`: [`@contractspec/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md) - `visualization`: [`@contractspec/example.visualization-showcase`](../../examples/visualization-showcase/README.md) - `agent`: [`@contractspec/example.agent-console`](../../examples/agent-console/README.md) - `harness-scenario`, `harness-suite`: focused reference [`@contractspec/example.harness-lab`](../../examples/harness-lab/README.md), product/business proof [`@contractspec/example.agent-console`](../../examples/agent-console/README.md) - `knowledge`, `knowledge-space`, lightweight `app-config`: [`@contractspec/example.knowledge-canon`](../../examples/knowledge-canon/README.md) - `integration`, `workflow`, integration-oriented `app-config`: [`@contractspec/example.integration-stripe`](../../examples/integration-stripe/README.md) - `policy`, `form`, `translation`: [`@contractspec/example.locale-jurisdiction-gate`](../../examples/locale-jurisdiction-gate/README.md) - `product-intent`: [`@contractspec/example.product-intent`](../../examples/product-intent/README.md) - `experiment`, `theme`: [`@contractspec/example.personalization`](../../examples/personalization/README.md) - `job`: [`@contractspec/example.openbanking-powens`](../../examples/openbanking-powens/README.md) - `migration`: [`@contractspec/example.versioned-knowledge-base`](../../examples/versioned-knowledge-base/README.md) - `telemetry`: [`@contractspec/example.pocket-family-office`](../../examples/pocket-family-office/README.md) ## Full contract inventory (explicit map) The package currently exposes **375 subpath exports**. This map is auto-generated for high-context navigation and AI grounding. > Auto-generated by `bun run readme:inventory` (`scripts/update-readme-contract-inventory.ts`). Do not edit this section manually. ### 1) Registry-level contract types (semantic model) From `src/types.ts`, `ContractSpecType` currently includes: - `agent` - `app-config` - `capability` - `data-view` - `event` - `example` - `experiment` - `feature` - `form` - `harness-scenario` - `harness-suite` - `integration` - `job` - `knowledge` - `knowledge-space` - `migration` - `operation` - `policy` - `presentation` - `product-intent` - `telemetry` - `test-spec` - `theme` - `translation` - `type` - `visualization` - `workflow` ### 2) Export/file artifact kinds (suffix-based) These are the concrete contract artifact kinds visible in package exports: - `.capability` (17) - `.feature` (10) - `.command` (28) - `.event` (28) - `.query` (24) - `.form` (5) - `.presentation` (6) - `.dataView` (11) - `.docs` (0) - `.contracts` (1) - `.docblock` (0) ### 3) Category -> kinds matrix - `acp`: `capability(1)`, `feature(1)`, `command(7)`, `plain(5)` - `agent`: `capability(1)`, `feature(1)`, `command(3)`, `event(4)`, `query(2)`, `form(1)`, `presentation(1)`, `dataView(1)`, `plain(12)` - `app-config`: `capability(1)`, `feature(1)`, `contracts(1)`, `plain(9)` - `capabilities`: `plain(7)` - `context`: `capability(1)`, `feature(1)`, `command(1)`, `event(1)`, `query(2)`, `form(1)`, `presentation(1)`, `dataView(1)`, `plain(10)` - `contract-registry`: `plain(3)` - `control-plane`: `capability(5)`, `feature(1)`, `command(9)`, `event(10)`, `query(6)`, `plain(13)` - `data-views`: `plain(8)` - `database`: `capability(1)`, `feature(1)`, `query(4)`, `dataView(1)`, `plain(6)` - `docs`: `capability(1)`, `feature(1)`, `command(2)`, `event(2)`, `query(2)`, `form(1)`, `presentation(2)`, `dataView(3)`, `plain(12)` - `events`: `plain(1)` - `examples`: `plain(6)` - `experiments`: `plain(3)` - `features`: `plain(6)` - `forms`: `plain(2)` - `harness`: `capability(4)`, `feature(1)`, `command(3)`, `event(8)`, `query(5)`, `presentation(1)`, `dataView(3)`, `plain(11)` - `install`: `plain(1)` - `jobs`: `plain(4)` - `jsonschema`: `plain(1)` - `knowledge`: `capability(1)`, `feature(1)`, `plain(12)` - `llm`: `plain(4)` - `markdown`: `plain(1)` - `migrations`: `plain(1)` - `model-registry`: `plain(1)` - `onboarding-base`: `plain(1)` - `openapi`: `plain(1)` - `operations`: `plain(5)` - `ownership`: `plain(1)` - `policy`: `plain(8)` - `presentations`: `plain(4)` - `product-intent`: `plain(16)` - `prompt`: `plain(1)` - `promptRegistry`: `plain(1)` - `provider-ranking`: `capability(1)`, `feature(1)`, `command(3)`, `event(3)`, `query(3)`, `form(2)`, `presentation(1)`, `dataView(2)`, `plain(10)` - `regenerator`: `plain(7)` - `registry`: `plain(1)` - `registry-utils`: `plain(1)` - `resources`: `plain(1)` - `schema-to-markdown`: `plain(1)` - `serialization`: `plain(3)` - `telemetry`: `plain(4)` - `tests`: `plain(3)` - `themes`: `plain(1)` - `translations`: `plain(7)` - `types`: `plain(1)` - `utils`: `plain(1)` - `versioning`: `plain(4)` - `visualizations`: `plain(4)` - `workflow`: `plain(12)` - `workspace-config`: `plain(3)` ### 4) Fully enumerated named contracts by category #### acp - Capabilities (1): - `acp/capabilities/acpTransport.capability` - Features (1): - `acp/acp.feature` - Commands (7): - `acp/commands/acpFsAccess.command` - `acp/commands/acpPromptTurn.command` - `acp/commands/acpSessionInit.command` - `acp/commands/acpSessionResume.command` - `acp/commands/acpSessionStop.command` - `acp/commands/acpTerminalExec.command` - `acp/commands/acpToolCalls.command` - Plain exports (non-suffix artifacts): `5` #### agent - Capabilities (1): - `agent/capabilities/agentExecution.capability` - Features (1): - `agent/agent.feature` - Commands (3): - `agent/commands/agentApprovals.command` - `agent/commands/agentCancel.command` - `agent/commands/agentRun.command` - Events (4): - `agent/events/agentApprovalRequested.event` - `agent/events/agentRunCompleted.event` - `agent/events/agentRunFailed.event` - `agent/events/agentRunStarted.event` - Queries (2): - `agent/queries/agentArtifacts.query` - `agent/queries/agentStatus.query` - Forms (1): - `agent/forms/agentRun.form` - Presentations (1): - `agent/presentations/agentRunAudit.presentation` - Data views (1): - `agent/views/agentRuns.dataView` - Plain exports (non-suffix artifacts): `12` #### app-config - Capabilities (1): - `app-config/app-config.capability` - Features (1): - `app-config/app-config.feature` - Contracts artifacts (1): - `app-config/app-config.contracts` - Plain exports (non-suffix artifacts): `9` #### capabilities - Plain exports (non-suffix artifacts): `13` #### context - Capabilities (1): - `context/capabilities/contextSystem.capability` - Features (1): - `context/context.feature` - Commands (1): - `context/commands/contextPackSnapshot.command` - Events (1): - `context/events/contextSnapshotCreated.event` - Queries (2): - `context/queries/contextPackDescribe.query` - `context/queries/contextPackSearch.query` - Forms (1): - `context/forms/contextPackSearch.form` - Presentations (1): - `context/presentations/contextSnapshot.presentation` - Data views (1): - `context/views/contextSnapshots.dataView` - Plain exports (non-suffix artifacts): `10` #### contract-registry - Plain exports (non-suffix artifacts): `3` #### control-plane - Capabilities (5): - `control-plane/capabilities/controlPlaneApproval.capability` - `control-plane/capabilities/controlPlaneAudit.capability` - `control-plane/capabilities/controlPlaneChannelRuntime.capability` - `control-plane/capabilities/controlPlaneCore.capability` - `control-plane/capabilities/controlPlaneSkillRegistry.capability` - Features (1): - `control-plane/control-plane.feature` - Commands (9): - `control-plane/commands/controlPlaneExecutionApprove.command` - `control-plane/commands/controlPlaneExecutionCancel.command` - `control-plane/commands/controlPlaneExecutionReject.command` - `control-plane/commands/controlPlaneExecutionStart.command` - `control-plane/commands/controlPlaneIntentSubmit.command` - `control-plane/commands/controlPlanePlanCompile.command` - `control-plane/commands/controlPlanePlanVerify.command` - `control-plane/commands/controlPlaneSkillDisable.command` - `control-plane/commands/controlPlaneSkillInstall.command` - Events (10): - `control-plane/events/controlPlaneExecutionCompleted.event` - `control-plane/events/controlPlaneExecutionFailed.event` - `control-plane/events/controlPlaneExecutionStepBlocked.event` - `control-plane/events/controlPlaneExecutionStepCompleted.event` - `control-plane/events/controlPlaneExecutionStepStarted.event` - `control-plane/events/controlPlaneIntentReceived.event` - `control-plane/events/controlPlanePlanCompiled.event` - `control-plane/events/controlPlanePlanRejected.event` - `control-plane/events/controlPlaneSkillInstalled.event` - `control-plane/events/controlPlaneSkillRejected.event` - Queries (6): - `control-plane/queries/controlPlaneExecutionGet.query` - `control-plane/queries/controlPlaneExecutionList.query` - `control-plane/queries/controlPlanePolicyExplain.query` - `control-plane/queries/controlPlaneSkillList.query` - `control-plane/queries/controlPlaneSkillVerify.query` - `control-plane/queries/controlPlaneTraceGet.query` - Plain exports (non-suffix artifacts): `7` #### data-views - Plain exports (non-suffix artifacts): `8` #### database - Capabilities (1): - `database/capabilities/databaseContext.capability` - Features (1): - `database/database.feature` - Queries (4): - `database/queries/databaseDictionaryGet.query` - `database/queries/databaseMigrationsList.query` - `database/queries/databaseQueryReadonly.query` - `database/queries/databaseSchemaDescribe.query` - Data views (1): - `database/views/databaseSchemas.dataView` - Plain exports (non-suffix artifacts): `6` #### docs - Capabilities (1): - `docs/capabilities/documentationSystem.capability` - Features (1): - `docs/docs.feature` - Commands (2): - `docs/commands/docsGenerate.command` - `docs/commands/docsPublish.command` - Events (2): - `docs/events/docsGenerated.event` - `docs/events/docsPublished.event` - Queries (2): - `docs/queries/contractReference.query` - `docs/queries/docsIndex.query` - Forms (1): - `docs/forms/docsSearch.form` - Presentations (2): - `docs/presentations/docsLayout.presentation` - `docs/presentations/docsReferencePage.presentation` - Data views (3): - `docs/views/contractReference.dataView` - `docs/views/docsIndex.dataView` - `docs/views/exampleCatalog.dataView` - Plain exports (non-suffix artifacts): `12` #### events - Plain exports (non-suffix artifacts): `1` #### examples - Plain exports (non-suffix artifacts): `6` #### experiments - Plain exports (non-suffix artifacts): `3` #### features - Plain exports (non-suffix artifacts): `6` #### forms - Plain exports (non-suffix artifacts): `2` #### harness - Capabilities (4): - `harness/capabilities/harnessEvaluation.capability` - `harness/capabilities/harnessEvidence.capability` - `harness/capabilities/harnessExecution.capability` - `harness/capabilities/harnessTargeting.capability` - Features (1): - `harness/harness.feature` - Commands (3): - `harness/commands/harnessEvaluationRun.command` - `harness/commands/harnessRunCancel.command` - `harness/commands/harnessRunStart.command` - Events (8): - `harness/events/harnessEvaluationCompleted.event` - `harness/events/harnessEvidenceCaptured.event` - `harness/events/harnessRunCompleted.event` - `harness/events/harnessRunFailed.event` - `harness/events/harnessRunStarted.event` - `harness/events/harnessStepBlocked.event` - `harness/events/harnessStepCompleted.event` - `harness/events/harnessStepStarted.event` - Queries (5): - `harness/queries/harnessEvaluationGet.query` - `harness/queries/harnessEvidenceGet.query` - `harness/queries/harnessEvidenceList.query` - `harness/queries/harnessRunGet.query` - `harness/queries/harnessTargetResolve.query` - Presentations (1): - `harness/presentations/harnessRunAudit.presentation` - Data views (3): - `harness/views/harnessEvaluations.dataView` - `harness/views/harnessEvidence.dataView` - `harness/views/harnessRuns.dataView` - Plain exports (non-suffix artifacts): `11` #### install - Plain exports (non-suffix artifacts): `1` #### jobs - Plain exports (non-suffix artifacts): `4` #### jsonschema - Plain exports (non-suffix artifacts): `1` #### knowledge - Capabilities (1): - `knowledge/knowledge.capability` - Features (1): - `knowledge/knowledge.feature` - Plain exports (non-suffix artifacts): `12` #### llm - Plain exports (non-suffix artifacts): `4` #### markdown - Plain exports (non-suffix artifacts): `1` #### migrations - Plain exports (non-suffix artifacts): `1` #### model-registry - Plain exports (non-suffix artifacts): `1` #### onboarding-base - Plain exports (non-suffix artifacts): `1` #### openapi - Plain exports (non-suffix artifacts): `1` #### operations - Plain exports (non-suffix artifacts): `5` #### ownership - Plain exports (non-suffix artifacts): `1` #### policy - Plain exports (non-suffix artifacts): `8` #### presentations - Plain exports (non-suffix artifacts): `4` #### product-intent - Plain exports (non-suffix artifacts): `16` #### prompt - Plain exports (non-suffix artifacts): `1` #### promptRegistry - Plain exports (non-suffix artifacts): `1` #### provider-ranking - Capabilities (1): - `provider-ranking/capabilities/providerRanking.capability` - Features (1): - `provider-ranking/provider-ranking.feature` - Commands (3): - `provider-ranking/commands/benchmarkIngest.command` - `provider-ranking/commands/benchmarkRunCustom.command` - `provider-ranking/commands/rankingRefresh.command` - Events (3): - `provider-ranking/events/benchmarkCustomCompleted.event` - `provider-ranking/events/benchmarkIngested.event` - `provider-ranking/events/rankingUpdated.event` - Queries (3): - `provider-ranking/queries/benchmarkResultsList.query` - `provider-ranking/queries/modelProfileGet.query` - `provider-ranking/queries/providerRankingGet.query` - Forms (2): - `provider-ranking/forms/benchmarkIngest.form` - `provider-ranking/forms/benchmarkRunCustom.form` - Presentations (1): - `provider-ranking/presentations/modelComparison.presentation` - Data views (2): - `provider-ranking/views/benchmarkResults.dataView` - `provider-ranking/views/providerRankings.dataView` - Plain exports (non-suffix artifacts): `10` #### regenerator - Plain exports (non-suffix artifacts): `7` #### registry - Plain exports (non-suffix artifacts): `1` #### registry-utils - Plain exports (non-suffix artifacts): `1` #### resources - Plain exports (non-suffix artifacts): `1` #### schema-to-markdown - Plain exports (non-suffix artifacts): `1` #### serialization - Plain exports (non-suffix artifacts): `3` #### telemetry - Plain exports (non-suffix artifacts): `4` #### tests - Plain exports (non-suffix artifacts): `3` #### themes - Plain exports (non-suffix artifacts): `1` #### translations - Plain exports (non-suffix artifacts): `7` #### types - Plain exports (non-suffix artifacts): `1` #### utils - Plain exports (non-suffix artifacts): `1` #### versioning - Plain exports (non-suffix artifacts): `4` #### visualizations - Plain exports (non-suffix artifacts): `4` #### workflow - Plain exports (non-suffix artifacts): `12` #### workspace-config - Plain exports (non-suffix artifacts): `3` ### 5) DocBlock coverage map (for AI context retrieval) DocBlocks are authored as same-file exports in their owner modules and loaded through generated manifests, not standalone `*.docblock` package exports. ## End-to-end quick start ### 1) Define schema models and specs ```ts import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema"; import { defineCommand, defineEvent, defineQuery, } from "@contractspec/lib.contracts-spec"; const WorkspaceInput = new SchemaModel({ name: "WorkspaceInput", fields: { workspaceId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false }, }, }); const WorkspaceOutput = new SchemaModel({ name: "WorkspaceOutput", fields: { workspaceId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false }, name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false }, }, }); const WorkspaceCreatedPayload = new SchemaModel({ name: "WorkspaceCreatedPayload", fields: { workspaceId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false }, }, }); export const WorkspaceCreated = defineEvent({ meta: { key: "workspace.created", version: "1.0.0", title: "Workspace created", description: "Emitted after a workspace is created.", stability: "stable", owners: ["platform.core"], tags: ["workspace", "event"], }, payload: WorkspaceCreatedPayload, }); export const GetWorkspace = defineQuery({ meta: { key: "workspace.get", version: "1.0.0", title: "Get workspace", description: "Returns workspace metadata for the current tenant.", goal: "Expose read-only workspace state to the UI.", context: "Used by dashboard bootstrap.", stability: "stable", owners: ["platform.core"], tags: ["workspace", "query"], }, io: { input: WorkspaceInput, output: WorkspaceOutput }, policy: { auth: "user" }, }); export const CreateWorkspace = defineCommand({ meta: { key: "workspace.create", version: "1.0.0", title: "Create workspace", description: "Creates a new workspace.", goal: "Provision a workspace for a tenant.", context: "Triggered by onboarding flows.", stability: "stable", owners: ["platform.core"], tags: ["workspace", "command"], }, io: { input: WorkspaceInput, output: WorkspaceOutput }, policy: { auth: "admin" }, sideEffects: { emits: [{ ref: WorkspaceCreated.meta, when: "after_create" }] as const, }, }); ``` ### 2) Register specs and bind handlers ```ts import { EventRegistry, installOp, makeEmit, OperationSpecRegistry, } from "@contractspec/lib.contracts-spec"; import { CreateWorkspace, GetWorkspace, WorkspaceCreated, } from "./workspace.spec"; export const events = new EventRegistry().register(WorkspaceCreated); export const operations = new OperationSpecRegistry(); installOp(operations, GetWorkspace, async (input) => ({ workspaceId: input.workspaceId, name: "Acme Workspace", })); installOp(operations, CreateWorkspace, async (input, ctx) => { const result = { workspaceId: input.workspaceId, name: "Acme Workspace", }; const emit = makeEmit(CreateWorkspace, ctx); await emit.ref(WorkspaceCreated, { workspaceId: input.workspaceId }); return result; }); ``` ### 3) Execute from runtime context ```ts import type { HandlerCtx } from "@contractspec/lib.contracts-spec"; import { operations, events } from "./registry"; const ctx: HandlerCtx = { actor: "admin", channel: "web", eventSpecResolver: events, eventPublisher: async (envelope) => { console.log("published", envelope.key, envelope.version); }, }; const output = await operations.execute( "workspace.create", "1.0.0", { workspaceId: "wk_123" }, ctx ); console.log(output); ``` ## Execution behavior (why this is AI-friendly) `OperationSpecRegistry.execute(...)` runs predictable steps: 1. Resolve spec/version. 2. Parse input. 3. Apply policy hooks when provided (`ctx.decide`, `ctx.rateLimit`). 4. Guard event emission against declared side effects. 5. Execute handler. 6. Parse output when output is a schema model. 7. Emit telemetry when configured. This deterministic contract -> runtime flow is a strong base for code generation and AI-driven refactors. ## AI assistant guidance When writing code: - Start here when asked to "add a new operation/event/form/resource contract". - Keep `meta.key` stable and increment versions for behavior changes. - Define spec first, then bind handler, then expose transport. When reading code: - Treat `` as the canonical identity. - Expect one operation contract to project into multiple transports. ## Split migration from deprecated monolith - `@contractspec/lib.contracts` -> `@contractspec/lib.contracts-spec` - `@contractspec/lib.contracts/operations/*` -> `@contractspec/lib.contracts-spec/operations/*` - `@contractspec/lib.contracts/events` -> `@contractspec/lib.contracts-spec/events` - `@contractspec/lib.contracts/resources` -> `@contractspec/lib.contracts-spec/resources` - `@contractspec/lib.contracts/forms/*` -> `@contractspec/lib.contracts-spec/forms/*` Runtime packages moved out: - REST runtime -> `@contractspec/lib.contracts-runtime-server-rest` - GraphQL runtime -> `@contractspec/lib.contracts-runtime-server-graphql` - MCP runtime -> `@contractspec/lib.contracts-runtime-server-mcp` - React runtime -> `@contractspec/lib.contracts-runtime-client-react` - Integration contracts -> `@contractspec/lib.contracts-integrations` --- ## @contractspec/lib.contracts-transformers Description: Contract format transformations: import/export between ContractSpec and external formats (OpenAPI, AsyncAPI, etc.) Path: packages/libs/contracts-transformers URL: /llms/lib.contracts-transformers # @contractspec/lib.contracts-transformers Website: https://contractspec.io **Contract format transformations: import/export between ContractSpec and external formats (OpenAPI, AsyncAPI, etc.).** ## What It Provides - **Layer**: lib. - **Consumers**: `lib.contracts-spec`, bundles, CLI. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.contracts-transformers` or `bun add @contractspec/lib.contracts-transformers` ## Usage Import the root entrypoint from `@contractspec/lib.contracts-transformers`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/common` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/openapi` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./common` resolves through `./src/common/index.ts`. - Export `./openapi` resolves through `./src/openapi/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Core logic must be pure functions with no I/O. - Preserve original transport metadata (path/query/header params) for accurate round-trips. - Track provenance — where specs came from — for sync operations. - `@contractspec/lib.contracts-spec` re-exports this library for existing consumers; avoid breaking that contract. --- ## @contractspec/lib.contracts Description: Deprecated monolith package split into contracts-spec, contracts-integrations, and contracts-runtime-* packages Path: packages/libs/contracts URL: /llms/lib.contracts # @contractspec/lib.contracts Website: https://contractspec.io **DEPRECATED** monolith package. Exists only as a re-export shim for legacy consumers.** ## What It Provides - **Layer**: lib (deprecated) - **Consumers**: legacy code only ## Installation `npm install @contractspec/lib.contracts` or `bun add @contractspec/lib.contracts` ## Local Commands - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Release video edition tools - Refactor contracts libs to split them reducing bundle size and load ## Notes - **Do NOT add new code here.** Migrate consumers to `contracts-spec`, `contracts-integrations`, or `contracts-runtime-*` packages instead. - This package exists solely for backward compatibility. --- ## @contractspec/lib.cost-tracking Description: API cost tracking and budgeting Path: packages/libs/cost-tracking URL: /llms/lib.cost-tracking # @contractspec/lib.cost-tracking Website: https://contractspec.io **API cost tracking and budgeting.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.cost-tracking` or `bun add @contractspec/lib.cost-tracking` ## Usage Import the root entrypoint from `@contractspec/lib.cost-tracking`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/budget-alert-manager.ts` is part of the package's public or composition surface. - `src/cost-model.ts` is part of the package's public or composition surface. - `src/cost-tracker.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/optimization-recommender.ts` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Cost calculation logic must stay deterministic — no side effects or external calls during computation. - Budget threshold types are shared across consumers; changes require coordination. - Do not introduce floating-point arithmetic where precision matters; use integer cents or a decimal library. --- ## @contractspec/lib.design-system Description: Design tokens and theming primitives Path: packages/libs/design-system URL: /llms/lib.design-system # @contractspec/lib.design-system Website: https://contractspec.io **Design tokens and theming primitives.** ## What It Provides - **Layer**: lib. - **Consumers**: accessibility, presentation-runtime-react, video-gen, bundles, apps. - Related ContractSpec packages include `@contractspec/lib.ai-agent`, `@contractspec/lib.contracts-runtime-client-react`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.example-shared-ui`, `@contractspec/lib.presentation-runtime-react`, `@contractspec/lib.ui-kit`, ... ## Installation `npm install @contractspec/lib.design-system` or `bun add @contractspec/lib.design-system` ## Usage Import the root entrypoint from `@contractspec/lib.design-system`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/components/` contains reusable UI components and view composition. - `src/hooks/` contains custom hooks for host applications. - `src/index.ts` is the root public barrel and package entrypoint. - `src/lib/` contains package-local helper utilities and adapters. - `src/platform` is part of the package's public or composition surface. - `src/renderers` is part of the package's public or composition surface. - `src/theme` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit -p tsconfig.build.json - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run registry:build` — bun run scripts/build-registry.ts - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add data visualization capabilities. - Add table capabilities. - Resolve lint, build, and type errors across nine packages. - Add AI provider ranking system with ranking-driven model selection. - Stabilize marketing header interactions. ## Notes - **High blast radius** — all UI surfaces depend on design tokens; treat token names and values as public API. - Component hierarchy must be preserved; do not flatten or restructure without coordinating downstream consumers. - Token removals or renames are breaking changes. --- ## @contractspec/lib.email Description: (none) Path: packages/libs/email URL: /llms/lib.email # @contractspec/lib.email **Email sending via Scaleway SDK. Provides a provider-agnostic client interface for transactional email.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles. - Related ContractSpec packages include `@contractspec/lib.logger`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.logger`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.email` or `bun add @contractspec/lib.email` ## Usage Import the root entrypoint from `@contractspec/lib.email`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/client.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/types.ts` is shared public type definitions. - `src/utils.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./client` resolves through `./src/client.ts`. - Export `./types` resolves through `./src/types.ts`. - Export `./utils` resolves through `./src/utils.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Client interface abstracts the provider; do not leak Scaleway-specific types into the public API. - Keep the adapter boundary clean so the provider can be swapped without consumer changes. --- ## @contractspec/lib.error Description: Structured error handling and HTTP error utilities Path: packages/libs/error URL: /llms/lib.error # @contractspec/lib.error Website: https://contractspec.io **Structured error handling and HTTP error utilities.** ## What It Provides - **Layer**: lib. - **Consumers**: many libs and bundles. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.error` or `bun add @contractspec/lib.error` ## Usage Import the root entrypoint from `@contractspec/lib.error`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/appError.ts` is part of the package's public or composition surface. - `src/codes.ts` is part of the package's public or composition surface. - `src/http.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./appError` resolves through `./src/appError.ts`. - Export `./codes` resolves through `./src/codes.ts`. - Export `./http` resolves through `./src/http.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Error codes are a shared contract — additions are safe, removals or renames are breaking. - `AppError` shape must stay stable; downstream serialization depends on it. - HTTP status mappings affect all API surfaces; changes require cross-package validation. --- ## @contractspec/lib.evolution Description: AI-powered contract evolution engine Path: packages/libs/evolution URL: /llms/lib.evolution # @contractspec/lib.evolution Website: https://contractspec.io **AI-powered contract evolution engine.** ## What It Provides - **Layer**: lib. - **Consumers**: example-shared-ui, bundles. - **Key dependencies**: ai-agent, contracts-spec, lifecycle, observability, schema. - Related ContractSpec packages include `@contractspec/lib.ai-agent`, `@contractspec/lib.ai-providers`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.lifecycle`, `@contractspec/lib.observability`, ... ## Installation `npm install @contractspec/lib.evolution` or `bun add @contractspec/lib.evolution` ## Usage Import the root entrypoint from `@contractspec/lib.evolution`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/analyzer` is part of the package's public or composition surface. - `src/approval` is part of the package's public or composition surface. - `src/generator` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add changesets and apply pending fixes. - Resolve lint, build, and type errors across nine packages. - Add AI provider ranking system with ranking-driven model selection. ## Notes - Evolution strategies affect contract migration paths; changes can break existing migrations. - Depends on multiple core libs — verify compatibility when updating any dependency. - Strategy selection logic must remain deterministic and auditable. --- ## @contractspec/lib.example-shared-ui Description: (none) Path: packages/libs/example-shared-ui URL: /llms/lib.example-shared-ui # @contractspec/lib.example-shared-ui **Shared React components and hooks for ContractSpec example apps. Provides the common layout, editors, and overlays used across all examples.** ## What It Provides - **Layer**: lib. - **Consumers**: example apps. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.surface-runtime`, `@contractspec/lib.ui-kit-web`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.surface-runtime`, `@contractspec/lib.ui-kit-web`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.example-shared-ui` or `bun add @contractspec/lib.example-shared-ui` ## Usage Import the root entrypoint from `@contractspec/lib.example-shared-ui`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/bundles/` contains bundle definitions and composition entrypoints. - `src/EvolutionDashboard.tsx` is part of the package's public or composition surface. - `src/EvolutionSidebar.tsx` is part of the package's public or composition surface. - `src/hooks/` contains custom hooks for host applications. - `src/index.ts` is the root public barrel and package entrypoint. - `src/lib/` contains package-local helper utilities and adapters. - `src/LocalDataIndicator.tsx` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./bundles` resolves through `./src/bundles/index.ts`. - Export `./bundles/ExampleTemplateBundle` resolves through `./src/bundles/ExampleTemplateBundle.ts`. - Export `./EvolutionDashboard` resolves through `./src/EvolutionDashboard.tsx`. - Export `./EvolutionSidebar` resolves through `./src/EvolutionSidebar.tsx`. - Export `./hooks` resolves through `./src/hooks/index.ts`. - Export `./hooks/useBehaviorTracking` resolves through `./src/hooks/useBehaviorTracking.ts`. - Export `./hooks/useEvolution` resolves through `./src/hooks/useEvolution.ts`. - Export `./hooks/useRegistryTemplates` resolves through `./src/hooks/useRegistryTemplates.ts`. - Export `./hooks/useSpecContent` resolves through `./src/hooks/useSpecContent.ts`. - The package publishes 26 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add changesets and apply pending fixes. - Contracts context, bundle exports, surface-runtime docs. ## Notes - Low blast radius — only example apps depend on this package. - `TemplateShell` is the shared layout for all examples; structural changes affect every example app. --- ## @contractspec/lib.exporter Description: Generic CSV and XML exporters usable across web and mobile. Path: packages/libs/exporter URL: /llms/lib.exporter # @contractspec/lib.exporter Website: https://contractspec.io **Generic CSV and XML exporters usable across web and mobile.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.exporter` or `bun add @contractspec/lib.exporter` ## Usage Import the root entrypoint from `@contractspec/lib.exporter`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Export format must stay consistent for downstream consumers; column order and encoding are part of the contract. - Do not introduce platform-specific APIs (Node-only or browser-only) without a universal fallback. --- ## @contractspec/lib.feature-flags Description: Feature flags and experiments module for ContractSpec applications Path: packages/libs/feature-flags URL: /llms/lib.feature-flags # @contractspec/lib.feature-flags Website: https://contractspec.io **Feature flags and experiments module for ContractSpec applications.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, apps. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Installation `npm install @contractspec/lib.feature-flags` or `bun add @contractspec/lib.feature-flags` ## Usage Import the root entrypoint from `@contractspec/lib.feature-flags`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/evaluation` is part of the package's public or composition surface. - `src/events.ts` is package-level event definitions. - `src/feature-flags.capability.ts` defines a capability surface. - `src/feature-flags.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/feature-flags.docblock` resolves through `./src/docs/feature-flags.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./evaluation` resolves through `./src/evaluation/index.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./feature-flags.capability` resolves through `./src/feature-flags.capability.ts`. - Export `./feature-flags.feature` resolves through `./src/feature-flags.feature.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Flag evaluation logic must be deterministic — same input always produces same output. - Capability and feature contracts are public API; changes are breaking. - Follow the PostHog naming conventions defined in workspace rules for new flag names. --- ## @contractspec/lib.files Description: Files, documents and attachments module for ContractSpec applications Path: packages/libs/files URL: /llms/lib.files # @contractspec/lib.files Website: https://contractspec.io **Files, documents and attachments module for ContractSpec applications.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Installation `npm install @contractspec/lib.files` or `bun add @contractspec/lib.files` ## Usage Import the root entrypoint from `@contractspec/lib.files`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/files.capability.ts` defines a capability surface. - `src/files.feature.ts` defines a feature entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/files.docblock` resolves through `./src/docs/files.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./files.capability` resolves through `./src/files.capability.ts`. - Export `./files.feature` resolves through `./src/files.feature.ts`. - Export `./storage` resolves through `./src/storage/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Storage interface is the adapter boundary — do not couple consumers to a specific storage provider. - File entity schema is shared; field changes require migration coordination. - Capability contract is public API. --- ## @contractspec/lib.graphql-core Description: Shared GraphQL core: Pothos builder factory, scalars, tracing & complexity Path: packages/libs/graphql-core URL: /llms/lib.graphql-core # @contractspec/lib.graphql-core Website: https://contractspec.io **Shared GraphQL core: Pothos builder factory, scalars, tracing & complexity.** ## What It Provides - **Layer**: lib. - **Consumers**: graphql-federation, graphql-prisma, contracts-runtime-server-graphql, bundles. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.graphql-core` or `bun add @contractspec/lib.graphql-core` ## Usage Import the root entrypoint from `@contractspec/lib.graphql-core`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run prebuild` — contractspec-bun-build prebuild - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Builder factory is consumed by all GraphQL packages — interface changes have high blast radius. - Scalar definitions must stay aligned with the schema lib. - Tracing and complexity plugins must not introduce runtime overhead in production without opt-in. --- ## @contractspec/lib.graphql-federation Description: Pothos federation helpers and subgraph schema export utilities Path: packages/libs/graphql-federation URL: /llms/lib.graphql-federation # @contractspec/lib.graphql-federation Website: https://contractspec.io **Pothos federation helpers and subgraph schema export utilities.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles with federated GraphQL. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.graphql-federation` or `bun add @contractspec/lib.graphql-federation` ## Usage Import the root entrypoint from `@contractspec/lib.graphql-federation`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run prebuild` — contractspec-bun-build prebuild - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Federation directives must comply with the Apollo Federation spec; non-compliant changes break gateway composition. - Depends on graphql-core — keep builder factory usage aligned. --- ## @contractspec/lib.graphql-prisma Description: Pothos + Prisma builder factory with injectable client/DMMF Path: packages/libs/graphql-prisma URL: /llms/lib.graphql-prisma # @contractspec/lib.graphql-prisma Website: https://contractspec.io **Pothos + Prisma builder factory with injectable client/DMMF.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles with Prisma. - Related ContractSpec packages include `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.graphql-prisma` or `bun add @contractspec/lib.graphql-prisma` ## Usage Import the root entrypoint from `@contractspec/lib.graphql-prisma`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run prebuild` — contractspec-bun-build prebuild - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Prisma client injection must stay lazy — eagerly importing the client breaks tree-shaking and test isolation. - DMMF handling is version-sensitive; Prisma major upgrades require validation here first. - Depends on graphql-core — keep builder factory usage aligned. --- ## @contractspec/lib.harness Description: Harness orchestration, policy, evidence, and evaluation runtime. Path: packages/libs/harness URL: /llms/lib.harness # @contractspec/lib.harness Website: https://contractspec.io **Harness orchestration, policy, evidence normalization, replay bundling, and evaluation runtime for controlled inspection and proof generation.** ## What It Provides - Provides the mode-agnostic harness core used by higher-level runtime adapters and harness-aware workflows. - Exports focused surfaces for assertions, evidence normalization, orchestration, policy classification, replay bundles, and shared types. - Acts as the central execution model for controlled evaluation, proof generation, and inspection flows. - `src/adapters/` contains runtime, provider, or environment-specific adapters. ## Installation `npm install @contractspec/lib.harness` or `bun add @contractspec/lib.harness` ## Usage Import the root entrypoint from `@contractspec/lib.harness`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/assertions/` contains assertion-engine logic. - `src/evidence/` normalizes harness evidence into runtime-friendly shapes. - `src/orchestration/` runs suites and evaluation pipelines. - `src/policy/` classifies and applies harness policies. - `src/replay/` packages replay bundles and reproducible outputs. - `src/types.ts` contains shared public types. ## Public Entry Points - Exports the root harness runtime plus assertion, evidence, orchestration, policy, replay, and type subpaths. - Export `.` resolves through `./src/index.ts`. - Export `./assertions/engine` resolves through `./src/assertions/engine.ts`. - Export `./evidence/normalizer` resolves through `./src/evidence/normalizer.ts`. - Export `./orchestration/evaluation-runner` resolves through `./src/orchestration/evaluation-runner.ts`. - Export `./orchestration/runner` resolves through `./src/orchestration/runner.ts`. - Export `./policy/classifier` resolves through `./src/policy/classifier.ts`. - Export `./replay/bundle` resolves through `./src/replay/bundle.ts`. - Export `./types` resolves through `./src/types.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add a first-class harness system for controlled inspection, testing, evaluation, and proof generation. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/lib.identity-rbac Description: Identity, Organizations, and RBAC module for ContractSpec applications Path: packages/libs/identity-rbac URL: /llms/lib.identity-rbac # @contractspec/lib.identity-rbac Website: https://contractspec.io **Identity, Organizations, and RBAC module for ContractSpec applications.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, apps. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/contracts/` contains contract specs, operations, entities, and registry exports. ## Installation `npm install @contractspec/lib.identity-rbac` or `bun add @contractspec/lib.identity-rbac` ## Usage Import the root entrypoint from `@contractspec/lib.identity-rbac`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/identity-rbac.capability.ts` defines a capability surface. - `src/identity-rbac.feature.ts` defines a feature entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/policies` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./contracts/organization` resolves through `./src/contracts/organization.ts`. - Export `./contracts/rbac` resolves through `./src/contracts/rbac.ts`. - Export `./contracts/user` resolves through `./src/contracts/user.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./entities/organization` resolves through `./src/entities/organization.ts`. - Export `./entities/rbac` resolves through `./src/entities/rbac.ts`. - Export `./entities/user` resolves through `./src/entities/user.ts`. - Export `./events` resolves through `./src/events.ts`. - The package publishes 14 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - **Security-critical** — RBAC policies control access across the platform. - Role and permission schemas must stay backward-compatible; removals are breaking. - Capability contract is public API; policy evaluation must be deterministic. --- ## @contractspec/lib.image-gen Description: AI-powered image generation for hero, social, thumbnail, OG, and illustration Path: packages/libs/image-gen URL: /llms/lib.image-gen # @contractspec/lib.image-gen Website: https://contractspec.io **AI-powered image generation for hero, social, thumbnail, OG, and illustration.** ## What It Provides - **Layer**: lib. - **Consumers**: video-gen, bundles. - `src/docs/` contains docblocks and documentation-facing exports. - Related ContractSpec packages include `@contractspec/lib.content-gen`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/docs/` contains docblocks and documentation-facing exports. ## Installation `npm install @contractspec/lib.image-gen` or `bun add @contractspec/lib.image-gen` ## Usage Import the root entrypoint from `@contractspec/lib.image-gen`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/generators` is part of the package's public or composition surface. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/presets` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs/generators.docblock` resolves through `./src/docs/generators.docblock.ts`. - Export `./docs/image-gen.docblock` resolves through `./src/docs/image-gen.docblock.ts`. - Export `./generators` resolves through `./src/generators/index.ts`. - Export `./generators/image-generator` resolves through `./src/generators/image-generator.ts`. - Export `./generators/prompt-builder` resolves through `./src/generators/prompt-builder.ts`. - Export `./generators/style-resolver` resolves through `./src/generators/style-resolver.ts`. - Export `./i18n` resolves through `./src/i18n/index.ts`. - Export `./i18n/catalogs` resolves through `./src/i18n/catalogs/index.ts`. - Export `./i18n/catalogs/en` resolves through `./src/i18n/catalogs/en.ts`. - The package publishes 20 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add @contractspec/lib.image-gen package with full test suite. ## Notes - Generator interface is shared with the content-gen pattern; keep the adapter shape consistent. - Preset schemas affect all generated images; field changes require validation across consumers. - Do not hardcode locale-specific strings outside the i18n subpath. --- ## @contractspec/lib.jobs Description: Background jobs and scheduler module for ContractSpec applications Path: packages/libs/jobs URL: /llms/lib.jobs # @contractspec/lib.jobs Website: https://contractspec.io **Background jobs and scheduler module for ContractSpec applications.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Installation `npm install @contractspec/lib.jobs` or `bun add @contractspec/lib.jobs` ## Usage Import the root entrypoint from `@contractspec/lib.jobs`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/jobs.capability.ts` defines a capability surface. - `src/jobs.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - Export `./handlers/gmail-sync-handler` resolves through `./src/handlers/gmail-sync-handler.ts`. - Export `./handlers/ping-job` resolves through `./src/handlers/ping-job.ts`. - Export `./handlers/storage-document-handler` resolves through `./src/handlers/storage-document-handler.ts`. - Export `./jobs.capability` resolves through `./src/jobs.capability.ts`. - Export `./jobs.feature` resolves through `./src/jobs.feature.ts`. - The package publishes 18 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Queue and scheduler interfaces are adapter boundaries — do not leak implementation details. - Job entity schema is shared across consumers; changes require migration awareness. - Capability contract (`jobs.capability`) is public API — treat as a breaking-change surface. --- ## @contractspec/lib.knowledge Description: RAG and knowledge base primitives Path: packages/libs/knowledge URL: /llms/lib.knowledge # @contractspec/lib.knowledge Website: https://contractspec.io **RAG and knowledge base primitives.** ## What It Provides - **Layer**: lib. - **Consumers**: ai-agent, personalization, support-bot, jobs, bundles. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.knowledge` or `bun add @contractspec/lib.knowledge` ## Usage Import the root entrypoint from `@contractspec/lib.knowledge`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/access` is part of the package's public or composition surface. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/ingestion` is part of the package's public or composition surface. - `src/query` is part of the package's public or composition surface. - `src/retriever` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./access` resolves through `./src/access/index.ts`. - Export `./access/guard` resolves through `./src/access/guard.ts`. - Export `./i18n` resolves through `./src/i18n/index.ts`. - Export `./i18n/catalogs` resolves through `./src/i18n/catalogs/index.ts`. - Export `./i18n/catalogs/en` resolves through `./src/i18n/catalogs/en.ts`. - Export `./i18n/catalogs/es` resolves through `./src/i18n/catalogs/es.ts`. - Export `./i18n/catalogs/fr` resolves through `./src/i18n/catalogs/fr.ts`. - Export `./i18n/keys` resolves through `./src/i18n/keys.ts`. - Export `./i18n/locale` resolves through `./src/i18n/locale.ts`. - The package publishes 24 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add full i18n support across all 10 packages (en/fr/es, 460 keys). ## Notes - High blast radius — retriever interface is consumed by multiple AI libs. - Ingestion pipeline must stay idempotent; re-ingesting the same document must not create duplicates. - Type changes ripple into ai-agent, personalization, and support-bot. --- ## @contractspec/lib.lifecycle Description: Contract lifecycle management primitives Path: packages/libs/lifecycle URL: /llms/lib.lifecycle # @contractspec/lib.lifecycle Website: https://contractspec.io **Contract lifecycle management primitives.** ## What It Provides - **Layer**: lib. - **Consumers**: analytics, evolution, observability, bundles. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.lifecycle` or `bun add @contractspec/lib.lifecycle` ## Usage Import the root entrypoint from `@contractspec/lib.lifecycle`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/types` is part of the package's public or composition surface. - `src/utils/` contains internal utility functions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Fix small issues. - Add full i18n support across all 10 packages (en/fr/es, 460 keys). ## Notes - Lifecycle stage definitions are shared across the platform — changes are high-impact. - Stage transitions must be deterministic; no side effects in transition logic. - Consumed by analytics and observability — schema changes affect downstream telemetry. --- ## @contractspec/lib.logger Description: Comprehensive logging library optimized for Bun with ElysiaJS integration Path: packages/libs/logger URL: /llms/lib.logger # @contractspec/lib.logger Website: https://contractspec.io **Comprehensive logging library optimized for Bun with ElysiaJS integration.** ## What It Provides - **Layer**: lib. - **Consumers**: email, jobs, contracts-runtime-server-mcp, bundles, apps. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.logger` or `bun add @contractspec/lib.logger` ## Usage Import the root entrypoint from `@contractspec/lib.logger`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/context.browser.ts` is part of the package's public or composition surface. - `src/context.node.ts` is part of the package's public or composition surface. - `src/context.ts` is part of the package's public or composition surface. - `src/elysia-plugin.ts` is part of the package's public or composition surface. - `src/formatters.ts` is part of the package's public or composition surface. - `src/index.browser.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `types`, `browser`, `default`. - Export `./context` resolves through `types`, `browser`, `node`, ... - Export `./context.browser` resolves through `./src/context.browser.ts`. - Export `./context.node` resolves through `./src/context.node.ts`. - Export `./elysia-plugin` resolves through `./src/elysia-plugin.ts`. - Export `./formatters` resolves through `./src/formatters.ts`. - Export `./index.browser` resolves through `./src/index.browser.ts`. - Export `./logger` resolves through `types`, `browser`, `node`, ... - Export `./logger.browser` resolves through `./src/logger.browser.ts`. - Export `./logger.node` resolves through `./src/logger.node.ts`. - The package publishes 15 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Logger interface is used across the entire stack — breaking changes affect everything. - Structured log format must stay JSON-compatible for log aggregation pipelines. - Elysia plugin must not break the middleware chain; preserve `onRequest`/`onAfterHandle` order. --- ## @contractspec/lib.metering Description: Usage metering and billing core module for ContractSpec applications Path: packages/libs/metering URL: /llms/lib.metering # @contractspec/lib.metering Website: https://contractspec.io **Usage metering and billing core module for ContractSpec applications.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Installation `npm install @contractspec/lib.metering` or `bun add @contractspec/lib.metering` ## Usage Import the root entrypoint from `@contractspec/lib.metering`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/aggregation` is part of the package's public or composition surface. - `src/analytics` is part of the package's public or composition surface. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./aggregation` resolves through `./src/aggregation/index.ts`. - Export `./analytics/posthog-metering` resolves through `./src/analytics/posthog-metering.ts`. - Export `./analytics/posthog-metering-reader` resolves through `./src/analytics/posthog-metering-reader.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/metering.docblock` resolves through `./src/docs/metering.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./metering.capability` resolves through `./src/metering.capability.ts`. - The package publishes 11 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Stability. - Resolve lint, build, and type errors across nine packages. - Add AI provider ranking system with ranking-driven model selection. ## Notes - Aggregation logic must stay deterministic — non-determinism causes billing discrepancies. - Billing-related schemas are compliance-sensitive; changes require review. - Capability contract (`metering.capability`) is public API — treat as a breaking-change surface. --- ## @contractspec/lib.observability Description: OpenTelemetry-based observability primitives Path: packages/libs/observability URL: /llms/lib.observability # @contractspec/lib.observability Website: https://contractspec.io **OpenTelemetry-based observability primitives.** ## What It Provides - **Layer**: lib. - **Consumers**: evolution, progressive-delivery, bundles. - `src/pipeline/` contains pipeline stages and orchestration helpers. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.lifecycle`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/pipeline/` contains pipeline stages and orchestration helpers. ## Installation `npm install @contractspec/lib.observability` or `bun add @contractspec/lib.observability` ## Usage Import the root entrypoint from `@contractspec/lib.observability`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/anomaly` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/intent` is part of the package's public or composition surface. - `src/logging` is part of the package's public or composition surface. - `src/metrics` is part of the package's public or composition surface. - `src/pipeline/` contains pipeline stages and orchestration helpers. - `src/telemetry` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./anomaly/alert-manager` resolves through `./src/anomaly/alert-manager.ts`. - Export `./anomaly/anomaly-detector` resolves through `./src/anomaly/anomaly-detector.ts`. - Export `./anomaly/baseline-calculator` resolves through `./src/anomaly/baseline-calculator.ts`. - Export `./anomaly/root-cause-analyzer` resolves through `./src/anomaly/root-cause-analyzer.ts`. - Export `./intent/aggregator` resolves through `./src/intent/aggregator.ts`. - Export `./intent/detector` resolves through `./src/intent/detector.ts`. - Export `./logging` resolves through `./src/logging/index.ts`. - Export `./metrics` resolves through `./src/metrics/index.ts`. - Export `./pipeline/evolution-pipeline` resolves through `./src/pipeline/evolution-pipeline.ts`. - The package publishes 18 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Circular import issue. - Normalize formatting across contracts-integrations, composio, and observability. - Add AI provider ranking system with ranking-driven model selection. ## Notes - OTel span and metric naming conventions must stay consistent across the platform. - Pipeline interfaces are adapter boundaries — do not leak vendor-specific details. - Anomaly detection thresholds affect alerting; changes require validation. --- ## @contractspec/lib.overlay-engine Description: Runtime overlay engine for ContractSpec personalization and adaptive UI rendering. Path: packages/libs/overlay-engine URL: /llms/lib.overlay-engine # @contractspec/lib.overlay-engine Website: https://contractspec.io **Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.** ## What It Provides - **Layer**: lib. - **Consumers**: personalization, example-shared-ui, bundles. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.overlay-engine` or `bun add @contractspec/lib.overlay-engine` ## Usage Import the root entrypoint from `@contractspec/lib.overlay-engine`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/merger.ts` is part of the package's public or composition surface. - `src/react.ts` is part of the package's public or composition surface. - `src/registry.ts` is part of the package's public or composition surface. - `src/runtime.ts` is part of the package's public or composition surface. - `src/signer.ts` is part of the package's public or composition surface. - `src/spec.ts` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./merger` resolves through `./src/merger.ts`. - Export `./react` resolves through `./src/react.ts`. - Export `./registry` resolves through `./src/registry.ts`. - Export `./runtime` resolves through `./src/runtime.ts`. - Export `./signer` resolves through `./src/signer.ts`. - Export `./spec` resolves through `./src/spec.ts`. - Export `./types` resolves through `./src/types.ts`. - Export `./validator` resolves through `./src/validator.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Overlay spec schema is a contract — changes are breaking for all consumers. - Signer must preserve cryptographic integrity; do not alter signing algorithm without migration. - Merger logic must be idempotent — applying the same overlay twice must produce identical results. --- ## @contractspec/lib.personalization Description: Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization. Path: packages/libs/personalization URL: /llms/lib.personalization # @contractspec/lib.personalization Website: https://contractspec.io **Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, example apps. - `src/docs/` contains docblocks and documentation-facing exports. - Related ContractSpec packages include `@contractspec/lib.bus`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.knowledge`, `@contractspec/lib.overlay-engine`, `@contractspec/lib.schema`, `@contractspec/lib.surface-runtime`, ... - `src/docs/` contains docblocks and documentation-facing exports. ## Installation `npm install @contractspec/lib.personalization` or `bun add @contractspec/lib.personalization` ## Usage Import the root entrypoint from `@contractspec/lib.personalization`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/adapter.ts` is part of the package's public or composition surface. - `src/analyzer.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/index.ts` is the root public barrel and package entrypoint. - `src/preference-dimensions.ts` is part of the package's public or composition surface. - `src/store.ts` is part of the package's public or composition surface. - `src/tracker.ts` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./adapter` resolves through `./src/adapter.ts`. - Export `./analyzer` resolves through `./src/analyzer.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/behavior-tracking.docblock` resolves through `./src/docs/behavior-tracking.docblock.ts`. - Export `./docs/overlay-engine.docblock` resolves through `./src/docs/overlay-engine.docblock.ts`. - Export `./docs/workflow-composition.docblock` resolves through `./src/docs/workflow-composition.docblock.ts`. - Export `./preference-dimensions` resolves through `./src/preference-dimensions.ts`. - Export `./store` resolves through `./src/store.ts`. - Export `./tracker` resolves through `./src/tracker.ts`. - The package publishes 11 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Vercel AI SDK parity + surface-runtime i18n and bundle alignment. - Bundle spec alignment, i18n support, PM workbench pilot. - Upgrade dependencies. ## Notes - Tracker interface is the adapter boundary — implementation details must not leak. - Behavior data schema must stay backward-compatible; older events must remain parseable. - Depends on bus, overlay-engine, and knowledge — coordinate cross-lib changes. --- ## @contractspec/lib.plugins Description: Plugin API and registry for ContractSpec extensions Path: packages/libs/plugins URL: /llms/lib.plugins # @contractspec/lib.plugins Website: https://contractspec.io **Plugin API and registry for ContractSpec extensions.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, CLI. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.plugins` or `bun add @contractspec/lib.plugins` ## Usage Import the root entrypoint from `@contractspec/lib.plugins`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/config.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/registry.ts` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./config` resolves through `./src/config.ts`. - Export `./registry` resolves through `./src/registry.ts`. - Export `./types` resolves through `./src/types.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Plugin interface is a public API contract — breaking changes affect all published plugins. - Registry must stay backward-compatible; older plugin manifests must remain loadable. - Config schema changes require a migration path for existing plugin configurations. --- ## @contractspec/lib.presentation-runtime-core Description: Core presentation runtime for contract-driven UIs Path: packages/libs/presentation-runtime-core URL: /llms/lib.presentation-runtime-core # @contractspec/lib.presentation-runtime-core Website: https://contractspec.io **Core presentation runtime for contract-driven UIs.** ## What It Provides - **Layer**: lib. - **Consumers**: presentation-runtime-react, presentation-runtime-react-native. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.presentation-runtime-core` or `bun add @contractspec/lib.presentation-runtime-core` ## Usage Import the root entrypoint from `@contractspec/lib.presentation-runtime-core`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/metro.cjs` is part of the package's public or composition surface. - `src/next.mjs` is part of the package's public or composition surface. - `src/table.ts` is part of the package's public or composition surface. - `src/visualization.echarts.ts` is part of the package's public or composition surface. - `src/visualization.model.builders.ts` is part of the package's public or composition surface. - `src/visualization.model.helpers.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./table` resolves through `./src/table.ts`. - Export `./visualization` resolves through `./src/visualization.ts`. - Export `./visualization.echarts` resolves through `./src/visualization.echarts.ts`. - Export `./visualization.model` resolves through `./src/visualization.model.ts`. - Export `./visualization.model.builders` resolves through `./src/visualization.model.builders.ts`. - Export `./visualization.model.helpers` resolves through `./src/visualization.model.helpers.ts`. - Export `./visualization.types` resolves through `./src/visualization.types.ts`. - Export `./visualization.utils` resolves through `./src/visualization.utils.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit -p tsconfig.json - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add data visualization capabilities. - Add table capabilities. ## Notes - Core runtime interface is consumed by all presentation runtimes — changes here affect both web and mobile. - Must remain platform-agnostic; no React or React Native imports allowed. - API surface changes require coordinated updates in both downstream runtimes. --- ## @contractspec/lib.presentation-runtime-react-native Description: React Native presentation runtime for mobile apps Path: packages/libs/presentation-runtime-react-native URL: /llms/lib.presentation-runtime-react-native # @contractspec/lib.presentation-runtime-react-native Website: https://contractspec.io **React Native presentation runtime for mobile apps.** ## What It Provides - **Layer**: lib. - **Consumers**: mobile apps. - Related ContractSpec packages include `@contractspec/lib.presentation-runtime-core`, `@contractspec/lib.presentation-runtime-react`, `@contractspec/lib.ui-kit`, `@contractspec/tool.bun`. - Related ContractSpec packages include `@contractspec/lib.presentation-runtime-core`, `@contractspec/lib.presentation-runtime-react`, `@contractspec/lib.ui-kit`, `@contractspec/tool.bun`. ## Installation `npm install @contractspec/lib.presentation-runtime-react-native` or `bun add @contractspec/lib.presentation-runtime-react-native` ## Usage Import the root entrypoint from `@contractspec/lib.presentation-runtime-react-native`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/nativewind-env.d.ts` is part of the package's public or composition surface. - `src/useContractTable.ts` is part of the package's public or composition surface. - `src/useDataViewTable.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./nativewind-env.d` resolves through `./src/nativewind-env.d.ts`. - Export `./useContractTable` resolves through `./src/useContractTable.ts`. - Export `./useDataViewTable` resolves through `./src/useDataViewTable.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit -p tsconfig.json - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add table capabilities. ## Notes - Must stay compatible with presentation-runtime-core; do not diverge from the shared interface. - NativeWind integration is platform-specific — changes must be tested on actual devices/simulators. - Avoid web-only APIs; all code must run in React Native's JavaScript environment. --- ## @contractspec/lib.presentation-runtime-react Description: React presentation runtime with workflow components Path: packages/libs/presentation-runtime-react URL: /llms/lib.presentation-runtime-react # @contractspec/lib.presentation-runtime-react Website: https://contractspec.io **React presentation runtime with workflow components.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, apps. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.presentation-runtime-core`, `@contractspec/lib.ui-kit-web`, `@contractspec/tool.bun`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.presentation-runtime-core`, `@contractspec/lib.ui-kit-web`, `@contractspec/tool.bun`. ## Installation `npm install @contractspec/lib.presentation-runtime-react` or `bun add @contractspec/lib.presentation-runtime-react` ## Usage Import the root entrypoint from `@contractspec/lib.presentation-runtime-react`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/nativewind-env.d.ts` is part of the package's public or composition surface. - `src/table.types.ts` is part of the package's public or composition surface. - `src/table.utils.test.ts` is part of the package's public or composition surface. - `src/table.utils.ts` is part of the package's public or composition surface. - `src/useContractTable.models.tsx` is part of the package's public or composition surface. - `src/useContractTable.tsx` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./nativewind-env.d` resolves through `./src/nativewind-env.d.ts`. - Export `./table.types` resolves through `./src/table.types.ts`. - Export `./table.utils` resolves through `./src/table.utils.ts`. - Export `./useContractTable` resolves through `./src/useContractTable.tsx`. - Export `./useContractTable.models` resolves through `./src/useContractTable.models.tsx`. - Export `./useDataViewTable` resolves through `./src/useDataViewTable.tsx`. - Export `./useVisualizationModel` resolves through `./src/useVisualizationModel.ts`. - Export `./useWorkflow` resolves through `./src/useWorkflow.ts`. - Export `./WorkflowStepper` resolves through `./src/WorkflowStepper.tsx`. - The package publishes 11 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit -p tsconfig.json - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add data visualization capabilities. - Add table capabilities. ## Notes - Workflow component API is consumed by bundles — breaking changes require coordinated updates. - Must stay compatible with presentation-runtime-core interface. - Hook signatures (`useWorkflow`) are public API; parameter changes are breaking. --- ## @contractspec/lib.product-intent-utils Description: Prompt builders and validators for product-intent workflows. Path: packages/libs/product-intent-utils URL: /llms/lib.product-intent-utils # @contractspec/lib.product-intent-utils Website: https://contractspec.io **Prompt builders and validators for product-intent workflows.** ## What It Provides - **Layer**: lib. - **Consumers**: module.product-intent-core, bundles. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.product-intent-utils` or `bun add @contractspec/lib.product-intent-utils` ## Usage Import the root entrypoint from `@contractspec/lib.product-intent-utils`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/impact-engine.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/project-management-sync.ts` is part of the package's public or composition surface. - `src/prompts.ts` is part of the package's public or composition surface. - `src/ticket-pipeline-runner.ts` is part of the package's public or composition surface. - `src/ticket-pipeline.ts` is part of the package's public or composition surface. - `src/ticket-prompts.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Prompt templates directly affect AI output quality — test changes against representative inputs. - Validation schemas must match contracts-spec definitions; drift causes silent mismatches. - Changes here propagate to product-intent-core and all dependent bundles. --- ## @contractspec/lib.progressive-delivery Description: (none) Path: packages/libs/progressive-delivery URL: /llms/lib.progressive-delivery # @contractspec/lib.progressive-delivery **Progressive delivery and canary release primitives. Provides strategy definitions and rollout logic for safe, incremental deployments.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles. - Related ContractSpec packages include `@contractspec/lib.observability`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.observability`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.progressive-delivery` or `bun add @contractspec/lib.progressive-delivery` ## Usage Import the root entrypoint from `@contractspec/lib.progressive-delivery`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/canary-analyzer.ts` is part of the package's public or composition surface. - `src/canary-controller.ts` is part of the package's public or composition surface. - `src/deployment-coordinator.ts` is part of the package's public or composition surface. - `src/events.ts` is package-level event definitions. - `src/feature-flags.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/rollback-manager.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Delivery strategies must be deterministic — same input must produce same rollout decision. - Peer dependency on observability; ensure OTel integration stays aligned. - Strategy interface changes affect all deployment pipelines consuming this lib. --- ## @contractspec/lib.provider-ranking Description: AI provider ranking: benchmark ingestion, scoring, and model comparison Path: packages/libs/provider-ranking URL: /llms/lib.provider-ranking # @contractspec/lib.provider-ranking Website: https://contractspec.io **AI provider ranking: benchmark ingestion, scoring, and model comparison.** ## What It Provides - **Layer**: lib. - **Consumers**: module.provider-ranking. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.provider-ranking` or `bun add @contractspec/lib.provider-ranking` ## Usage Import the root entrypoint from `@contractspec/lib.provider-ranking`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/eval` is part of the package's public or composition surface. - `src/in-memory-store.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/ingesters` is part of the package's public or composition surface. - `src/scoring` is part of the package's public or composition surface. - `src/store.ts` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./eval` resolves through `./src/eval/index.ts`. - Export `./eval/runner` resolves through `./src/eval/runner.ts`. - Export `./eval/types` resolves through `./src/eval/types.ts`. - Export `./in-memory-store` resolves through `./src/in-memory-store.ts`. - Export `./ingesters` resolves through `./src/ingesters/index.ts`. - Export `./ingesters/artificial-analysis` resolves through `./src/ingesters/artificial-analysis.ts`. - Export `./ingesters/chatbot-arena` resolves through `./src/ingesters/chatbot-arena.ts`. - Export `./ingesters/fetch-utils` resolves through `./src/ingesters/fetch-utils.ts`. - Export `./ingesters/open-llm-leaderboard` resolves through `./src/ingesters/open-llm-leaderboard.ts`. - The package publishes 19 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and type errors across nine packages. - Add first-class transport, auth, versioning, and BYOK support across all integrations. - Add AI provider ranking system with ranking-driven model selection. ## Notes - Store interface is the adapter boundary — do not leak implementation details. - Scoring algorithms must stay deterministic (no randomness, no side effects). - Benchmark dimension enum is shared across ingesters and scoring — keep in sync. --- ## @contractspec/lib.runtime-sandbox Description: (none) Path: packages/libs/runtime-sandbox URL: /llms/lib.runtime-sandbox # @contractspec/lib.runtime-sandbox **Browser-compatible database abstraction built on PGLite for client-side SQL execution.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, apps. - `src/adapters/` contains runtime, provider, or environment-specific adapters. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/adapters/` contains runtime, provider, or environment-specific adapters. ## Installation `npm install @contractspec/lib.runtime-sandbox` or `bun add @contractspec/lib.runtime-sandbox` ## Usage Import the root entrypoint from `@contractspec/lib.runtime-sandbox`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/adapters/` contains runtime, provider, or environment-specific adapters. - `src/index.ts` is the root public barrel and package entrypoint. - `src/ports` is part of the package's public or composition surface. - `src/types` is part of the package's public or composition surface. - `src/web` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - DatabasePort interface is the adapter boundary — consumers depend on the port, not the implementation. - PGLite adapter must stay browser-compatible (no Node-only APIs). - Migration schema must remain stable — breaking changes require a migration path. --- ## @contractspec/lib.schema Description: Schema utilities for Zod, JSON Schema, and GraphQL Path: packages/libs/schema URL: /llms/lib.schema # @contractspec/lib.schema Website: https://contractspec.io **Schema utilities for Zod, JSON Schema, and GraphQL.** ## What It Provides - **Layer**: lib. - **Consumers**: nearly all libs, bundles, and apps. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.schema` or `bun add @contractspec/lib.schema` ## Usage Import the root entrypoint from `@contractspec/lib.schema`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/entity` is part of the package's public or composition surface. - `src/EnumType.test.ts` is part of the package's public or composition surface. - `src/EnumType.ts` is part of the package's public or composition surface. - `src/FieldType.test.ts` is part of the package's public or composition surface. - `src/FieldType.ts` is part of the package's public or composition surface. - `src/GraphQLSchemaType.test.ts` is part of the package's public or composition surface. - `src/GraphQLSchemaType.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./entity` resolves through `./src/entity/index.ts`. - Export `./entity/defineEntity` resolves through `./src/entity/defineEntity.ts`. - Export `./entity/generator` resolves through `./src/entity/generator.ts`. - Export `./entity/types` resolves through `./src/entity/types.ts`. - Export `./EnumType` resolves through `./src/EnumType.ts`. - Export `./FieldType` resolves through `./src/FieldType.ts`. - Export `./GraphQLSchemaType` resolves through `./src/GraphQLSchemaType.ts`. - Export `./JsonSchemaType` resolves through `./src/JsonSchemaType.ts`. - Export `./ScalarFactoryCache` resolves through `./src/ScalarFactoryCache.ts`. - The package publishes 14 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Preserve multi-surface consistency: Zod, GraphQL, and JSON Schema representations must stay aligned. - Prefer additive changes; avoid silently weakening validation or changing scalar semantics. - Do not edit `dist/`; source of truth is `src/`. --- ## @contractspec/lib.source-extractors Description: Extract contract candidates from TypeScript source code across multiple frameworks (NestJS, Express, Fastify, Hono, Elysia, tRPC, Next.js) Path: packages/libs/source-extractors URL: /llms/lib.source-extractors # @contractspec/lib.source-extractors Website: https://contractspec.io **Extract contract candidates from TypeScript source code across multiple frameworks (NestJS, Express, Fastify, Hono, Elysia, tRPC, Next.js).** ## What It Provides - **Layer**: lib. - **Consumers**: CLI, bundles. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.source-extractors` or `bun add @contractspec/lib.source-extractors` ## Usage Import the root entrypoint from `@contractspec/lib.source-extractors`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/__fixtures__` is part of the package's public or composition surface. - `src/__snapshots__` is part of the package's public or composition surface. - `src/codegen` is part of the package's public or composition surface. - `src/codegen.test.ts` is part of the package's public or composition surface. - `src/detect.test.ts` is part of the package's public or composition surface. - `src/detect.ts` is part of the package's public or composition surface. - `src/edge-cases.test.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./codegen` resolves through `./src/codegen/index.ts`. - Export `./extractors` resolves through `./src/extractors/index.ts`. - Export `./types` resolves through `./src/types.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Extractor interface must support multiple frameworks — keep it generic. - Codegen output must stay deterministic (same input → same output, always). --- ## @contractspec/lib.support-bot Description: AI support bot framework with RAG and ticket management Path: packages/libs/support-bot URL: /llms/lib.support-bot # @contractspec/lib.support-bot Website: https://contractspec.io **AI support bot framework with RAG and ticket management.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.knowledge`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, ... ## Installation `npm install @contractspec/lib.support-bot` or `bun add @contractspec/lib.support-bot` ## Usage Import the root entrypoint from `@contractspec/lib.support-bot`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/bot` is part of the package's public or composition surface. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/rag` is part of the package's public or composition surface. - `src/spec.ts` is part of the package's public or composition surface. - `src/tickets` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./bot` resolves through `./src/bot/index.ts`. - Export `./bot/auto-responder` resolves through `./src/bot/auto-responder.ts`. - Export `./bot/feedback-loop` resolves through `./src/bot/feedback-loop.ts`. - Export `./bot/tools` resolves through `./src/bot/tools.ts`. - Export `./i18n` resolves through `./src/i18n/index.ts`. - Export `./i18n/catalogs` resolves through `./src/i18n/catalogs/index.ts`. - Export `./i18n/catalogs/en` resolves through `./src/i18n/catalogs/en.ts`. - Export `./i18n/catalogs/es` resolves through `./src/i18n/catalogs/es.ts`. - Export `./i18n/catalogs/fr` resolves through `./src/i18n/catalogs/fr.ts`. - The package publishes 19 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint/test regressions after voice capability updates. - Add full i18n support across all 10 packages (en/fr/es, 460 keys). ## Notes - Bot spec interface follows ai-agent patterns — keep aligned with contracts-spec. - Ticket schema is shared — changes affect consumers downstream. - RAG pipeline must stay compatible with the knowledge lib. --- ## @contractspec/lib.surface-runtime Description: AI-native surface specs and web runtime for adaptive ContractSpec surfaces Path: packages/libs/surface-runtime URL: /llms/lib.surface-runtime # @contractspec/lib.surface-runtime Website: https://contractspec.io **Surface runtime for AI-native ContractSpec experiences, including bundle specs, planners, overlays, patching, and React rendering support.** ## What It Provides - Provides the runtime layer behind AI-planned surfaces, widget registries, overrides, and bundle resolution. - Supports React rendering, adapter boundaries, telemetry, evaluation harnesses, and planner tooling. - Recently expanded to better align with AI chat, i18n, workflow tools, and bundle export needs. - `src/adapters/` contains runtime, provider, or environment-specific adapters. ## Installation `npm install @contractspec/lib.surface-runtime` or `bun add @contractspec/lib.surface-runtime` ## Usage Import the root entrypoint from `@contractspec/lib.surface-runtime`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/spec/` defines module-bundle and surface-patch validation surfaces. - `src/runtime/` contains planners, registries, patch application, policy evaluation, and bundle resolution. - `src/react/` exports the React integration layer for bundle rendering and override handling. - `src/adapters/`, `src.telemetry/`, `src.evals/`, and `src.examples/` support integration and verification flows. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Exports runtime, spec, React integration, adapters, telemetry, eval, and example subpaths for AI-native surface composition. - Export `.` resolves through `./src/index.ts`. - Export `./adapters` resolves through `./src/adapters/index.ts`. - Export `./adapters/ai-sdk-stub` resolves through `./src/adapters/ai-sdk-stub.ts`. - Export `./adapters/blocknote-stub` resolves through `./src/adapters/blocknote-stub.tsx`. - Export `./adapters/dnd-kit-adapter` resolves through `./src/adapters/dnd-kit-adapter.tsx`. - Export `./adapters/dnd-kit-stub` resolves through `./src/adapters/dnd-kit-stub.ts`. - Export `./adapters/floating-ui-stub` resolves through `./src/adapters/floating-ui-stub.tsx`. - Export `./adapters/interfaces` resolves through `./src/adapters/interfaces.ts`. - Export `./adapters/motion-stub` resolves through `./src/adapters/motion-stub.ts`. - Export `./adapters/resizable-panels-stub` resolves through `./src/adapters/resizable-panels-stub.tsx`. - The package publishes 53 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile && node scripts/fix-use-client-directive.mjs - `bun run build:types` — contractspec-bun-build types - `bun run lint:adapters` — node scripts/lint-adapters.mjs - `bun run test:evals` — bun test src/evals/ - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Export, sidebar, workflow tools, slotContent. - Vercel AI SDK parity + surface-runtime i18n and bundle alignment. - Bundle spec alignment, i18n support, PM workbench pilot. ## Notes - No direct third-party UI imports outside `src/adapters/` (when adapters are added). - Every surface must have verification.dimensions for all 7 preference dimensions. - Adapter rule: BlockNote, dnd-kit, etc. behind adapter boundaries only. --- ## @contractspec/lib.testing Description: Contract-aware testing utilities and runners Path: packages/libs/testing URL: /llms/lib.testing # @contractspec/lib.testing Website: https://contractspec.io **Contract-aware testing utilities and runners.** ## What It Provides - **Layer**: lib. - **Consumers**: CLI, bundles. - `src/adapters/` contains runtime, provider, or environment-specific adapters. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/adapters/` contains runtime, provider, or environment-specific adapters. ## Installation `npm install @contractspec/lib.testing` or `bun add @contractspec/lib.testing` ## Usage Import the root entrypoint from `@contractspec/lib.testing`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/adapters/` contains runtime, provider, or environment-specific adapters. - `src/generator` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/recorder` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - TrafficRecorder and GoldenTestGenerator interfaces are public API — do not break signatures. - Test output format must stay compatible with Vitest and Jest runners. --- ## @contractspec/lib.ui-kit-core Description: Core UI primitives and utilities Path: packages/libs/ui-kit-core URL: /llms/lib.ui-kit-core # @contractspec/lib.ui-kit-core Website: https://contractspec.io **Core UI primitives and utilities.** ## What It Provides - **Layer**: lib. - **Consumers**: ui-kit, ui-kit-web, ui-link. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.ui-kit-core` or `bun add @contractspec/lib.ui-kit-core` ## Usage Import the root entrypoint from `@contractspec/lib.ui-kit-core`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/utils.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./utils` resolves through `./src/utils.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - `cn()` utility is used by every UI package — changes here affect all UI components. - This is a foundational package — keep it minimal and zero-surprise. - Test thoroughly before changing any export signature. --- ## @contractspec/lib.ui-kit-web Description: Web UI components with Radix primitives Path: packages/libs/ui-kit-web URL: /llms/lib.ui-kit-web # @contractspec/lib.ui-kit-web Website: https://contractspec.io **Web UI components built on Radix primitives with design-system token integration.** ## What It Provides - **Layer**: lib - **Consumers**: design-system, example-shared-ui, presentation-runtime-react, bundles ## Installation `npm install @contractspec/lib.ui-kit-web` or `bun add @contractspec/lib.ui-kit-web` ## Usage Import the root entrypoint from `@contractspec/lib.ui-kit-web`, or use one of the documented subpaths when you want a narrower surface area. ## Public Entry Points - `.` — main entry - `./ui/*` — individual component exports (many components) ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — jest --passWithNoTests - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types ## Recent Updates - Missing dependencies (thanks to knip) - Replace eslint+prettier by biomejs to optimize speed - Add data visualization capabilities ## Notes - Radix primitive wrappers must stay accessible (ARIA, keyboard nav) - Component API must align with design-system tokens - Do not bypass Radix for custom implementations without justification --- ## @contractspec/lib.ui-kit Description: Cross-platform UI components for React Native and web Path: packages/libs/ui-kit URL: /llms/lib.ui-kit # @contractspec/lib.ui-kit Website: https://contractspec.io **Cross-platform UI components for React Native and web surfaces.** ## What It Provides - **Layer**: lib - **Consumers**: accessibility, design-system, presentation-runtime-react-native, bundles ## Installation `npm install @contractspec/lib.ui-kit` or `bun add @contractspec/lib.ui-kit` ## Usage Import the root entrypoint from `@contractspec/lib.ui-kit`, or use one of the documented subpaths when you want a narrower surface area. ## Public Entry Points - `.` — main entry - `./ui/*` — individual component exports (many components) ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Add data visualization capabilities - Add table capabilities ## Notes - Component API must stay cross-platform compatible (React Native + web) - Depends on ui-kit-core — changes there propagate here - Do not introduce web-only or native-only APIs without a platform check --- ## @contractspec/lib.ui-link Description: Deep linking utilities for navigation Path: packages/libs/ui-link URL: /llms/lib.ui-link # @contractspec/lib.ui-link Website: https://contractspec.io **Deep linking utilities for cross-platform navigation.** ## What It Provides - **Layer**: lib - **Consumers**: bundles, apps ## Installation `npm install @contractspec/lib.ui-link` or `bun add @contractspec/lib.ui-link` ## Usage Import the root entrypoint from `@contractspec/lib.ui-link`, or use one of the documented subpaths when you want a narrower surface area. ## Public Entry Points - `.` — `./index.ts` - `./ui/link` — `./ui/link.tsx` ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Package exports - PublishConfig not supported by bun ## Notes - Link component must stay framework-agnostic (no router-specific coupling) - Depends on ui-kit-core — coordinate changes with that package --- ## @contractspec/lib.utils-typescript Description: TypeScript utility types and helpers Path: packages/libs/utils-typescript URL: /llms/lib.utils-typescript # @contractspec/lib.utils-typescript Website: https://contractspec.io **TypeScript utility types and helpers.** ## What It Provides - **Layer**: lib. - **Consumers**: many libs and bundles (wide blast radius). - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.utils-typescript` or `bun add @contractspec/lib.utils-typescript` ## Usage Import the root entrypoint from `@contractspec/lib.utils-typescript`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/lib/` contains package-local helper utilities and adapters. - `src/staticShouldNotHappen.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./lib/AwaitedResult` resolves through `./src/lib/AwaitedResult.ts`. - Export `./lib/BrowserNativeObject` resolves through `./src/lib/BrowserNativeObject.ts`. - Export `./lib/DeepInfiniteArray` resolves through `./src/lib/DeepInfiniteArray.ts`. - Export `./lib/DeepKeepOnly` resolves through `./src/lib/DeepKeepOnly.ts`. - Export `./lib/DeepKey` resolves through `./src/lib/DeepKey.ts`. - Export `./lib/DeepMap` resolves through `./src/lib/DeepMap.ts`. - Export `./lib/DeepNullable` resolves through `./src/lib/DeepNullable.ts`. - Export `./lib/DeepOr` resolves through `./src/lib/DeepOr.ts`. - Export `./lib/DeepPartial` resolves through `./src/lib/DeepPartial.ts`. - The package publishes 31 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Utility types are used across the entire monorepo — changes can break many packages. - Must stay zero-dependency (no runtime deps). - Test any signature change against downstream consumers before merging. --- ## @contractspec/lib.video-gen Description: (none) Path: packages/libs/video-gen URL: /llms/lib.video-gen # @contractspec/lib.video-gen **AI-powered video generation with Remotion: compositions, rendering, and design integration.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles, video-studio app. - `src/docs/` contains docblocks and documentation-facing exports. - Related ContractSpec packages include `@contractspec/lib.ai-providers`, `@contractspec/lib.content-gen`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.image-gen`, ... - `src/docs/` contains docblocks and documentation-facing exports. ## Installation `npm install @contractspec/lib.video-gen` or `bun add @contractspec/lib.video-gen` ## Usage Import the root entrypoint from `@contractspec/lib.video-gen`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/compositions` is part of the package's public or composition surface. - `src/design` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/generators` is part of the package's public or composition surface. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/player` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./compositions` resolves through `./src/compositions/index.ts`. - Export `./compositions/api-overview` resolves through `./src/compositions/api-overview.tsx`. - Export `./compositions/primitives` resolves through `./src/compositions/primitives/index.ts`. - Export `./compositions/primitives/animated-text` resolves through `./src/compositions/primitives/animated-text.tsx`. - Export `./compositions/primitives/brand-frame` resolves through `./src/compositions/primitives/brand-frame.tsx`. - Export `./compositions/primitives/code-block` resolves through `./src/compositions/primitives/code-block.tsx`. - Export `./compositions/primitives/progress-bar` resolves through `./src/compositions/primitives/progress-bar.tsx`. - Export `./compositions/primitives/terminal` resolves through `./src/compositions/primitives/terminal.tsx`. - Export `./compositions/primitives/transition` resolves through `./src/compositions/primitives/transition.tsx`. - The package publishes 42 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and type errors across nine packages. - Add first-class transport, auth, versioning, and BYOK support across all integrations. - Add AI provider ranking system with ranking-driven model selection. - Resolve lint/test regressions after voice capability updates. - Add @contractspec/lib.voice package for TTS, STT, and conversational voice. ## Notes - Remotion composition API is version-sensitive — pin and test upgrades carefully. - Renderer interface is the adapter boundary — do not leak Remotion internals. - Depends on voice, content-gen, image-gen, design-system — coordinate cross-lib changes. --- ## @contractspec/lib.voice Description: Voice capabilities: TTS, STT, and conversational AI Path: packages/libs/voice URL: /llms/lib.voice # @contractspec/lib.voice Website: https://contractspec.io **Voice capabilities: TTS, STT, and conversational AI.** ## What It Provides - **Layer**: lib. - **Consumers**: video-gen, bundles. - `src/docs/` contains docblocks and documentation-facing exports. - Related ContractSpec packages include `@contractspec/lib.ai-providers`, `@contractspec/lib.content-gen`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/docs/` contains docblocks and documentation-facing exports. ## Installation `npm install @contractspec/lib.voice` or `bun add @contractspec/lib.voice` ## Usage Import the root entrypoint from `@contractspec/lib.voice`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/audio` is part of the package's public or composition surface. - `src/conversational` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/stt` is part of the package's public or composition surface. - `src/sync` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./audio` resolves through `./src/audio/index.ts`. - Export `./audio/audio-concatenator` resolves through `./src/audio/audio-concatenator.ts`. - Export `./audio/duration-estimator` resolves through `./src/audio/duration-estimator.ts`. - Export `./audio/format-converter` resolves through `./src/audio/format-converter.ts`. - Export `./audio/silence-generator` resolves through `./src/audio/silence-generator.ts`. - Export `./conversational` resolves through `./src/conversational/index.ts`. - Export `./conversational/response-orchestrator` resolves through `./src/conversational/response-orchestrator.ts`. - Export `./conversational/transcript-builder` resolves through `./src/conversational/transcript-builder.ts`. - Export `./conversational/turn-detector` resolves through `./src/conversational/turn-detector.ts`. - The package publishes 43 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and test failures across voice, workspace, library, and composio. - Add first-class transport, auth, versioning, and BYOK support across all integrations. - Add AI provider ranking system with ranking-driven model selection. - Add @contractspec/lib.voice package for TTS, STT, and conversational voice. ## Notes - TTS/STT interfaces are adapter boundaries — keep them provider-agnostic. - Audio processing must stay streaming-compatible (no full-buffer-only APIs). - Depends on contracts-spec, contracts-integrations, content-gen. --- ## @contractspec/lib.workflow-composer Description: Tenant-aware workflow composition helpers for ContractSpec. Path: packages/libs/workflow-composer URL: /llms/lib.workflow-composer # @contractspec/lib.workflow-composer Website: https://contractspec.io **Tenant-aware workflow composition helpers for ContractSpec.** ## What It Provides - **Layer**: lib. - **Consumers**: bundles. - Related ContractSpec packages include `@contractspec/lib.ai-providers`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.ai-providers`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/lib.workflow-composer` or `bun add @contractspec/lib.workflow-composer` ## Usage Import the root entrypoint from `@contractspec/lib.workflow-composer`, or choose a documented subpath when you only need one part of the package surface. Workflow composition is deterministic by default: - Extensions are applied in stable priority order. - Duplicate injected step ids and invalid anchor combinations are rejected. - Hidden-step overlays are validated so they cannot orphan the remaining graph. - Extension `metadata` and `annotations` are merged into the composed workflow output. ## Architecture - `src/composer.test.ts` is part of the package's public or composition surface. - `src/composer.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/injector.ts` is part of the package's public or composition surface. - `src/merger.ts` is part of the package's public or composition surface. - `src/templates.ts` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add AI provider ranking system with ranking-driven model selection. - Upgrade dependencies. ## Notes - Workflow composition must stay tenant-isolated — no cross-tenant data leakage. - Depends on contracts-spec — keep aligned with contract definitions. --- ## @contractspec/module.ai-chat Description: AI chat interface module Path: packages/modules/ai-chat URL: /llms/module.ai-chat # @contractspec/module.ai-chat Website: https://contractspec.io **AI chat module with context, core runtime, presentation components, hooks, providers, and agent-aware workflows.** ## What It Provides - Provides the packaged chat feature layer used by examples and higher-level applications. - Supports MCP tools, provider integration, presentation rendering, forms, and agent-mode workflows. - Acts as the main composition layer between the low-level agent runtime and user-facing chat UIs. - `src/adapters/` contains runtime, provider, or environment-specific adapters. - `src/docs/` contains docblocks and documentation-facing exports. - `src/presentation/` contains presentation-layer components and renderers. ## Installation `npm install @contractspec/module.ai-chat` or `bun add @contractspec/module.ai-chat` ## Usage Import the root entrypoint from `@contractspec/module.ai-chat`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/context/` contains shared chat providers and contextual runtime state. - `src/core/` contains chat orchestration, workflows, and non-UI runtime logic. - `src/presentation/` exports UI components and React hooks for embedding the chat experience. - `src/providers/` exposes provider bindings and provider-facing integration helpers. - Top-level feature, capability, operation, schema, and event files define the module contract surface. - `src/ai-chat.capability.ts` defines a capability surface. ## Public Entry Points - Exports the root module plus context, core, core/workflow, presentation, presentation/components, presentation/hooks, and providers subpaths. - Export `.` resolves through `./src/index.ts`. - Export `./context` resolves through `./src/context/index.ts`. - Export `./core` resolves through `./src/core/index.ts`. - Export `./core/workflow` resolves through `./src/core/workflow.ts`. - Export `./presentation` resolves through `./src/presentation/index.ts`. - Export `./presentation/components` resolves through `./src/presentation/components/index.ts`. - Export `./presentation/hooks` resolves through `./src/presentation/hooks/index.ts`. - Export `./providers` resolves through `./src/providers/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Agentic workflows — subagents, memory tools, and next steps. - Vnext ai-native. - Backend operations + frontend rendering support. - Use browser-safe MCP client stub in client bundles. - Add changesets and apply pending fixes. ## Notes - Depends on `lib.ai-agent`, `lib.ai-providers`, `lib.contracts-spec`, `lib.schema`, `lib.metering`, `lib.cost-tracking`, `lib.surface-runtime`. - React peer dependency (>=19.2.4); changes here affect all chat surfaces. - Metering and cost-tracking are wired in -- never bypass them. --- ## @contractspec/module.alpic Description: Alpic MCP and ChatGPT App hosting helpers Path: packages/modules/alpic URL: /llms/module.alpic # @contractspec/module.alpic Website: https://contractspec.io **Alpic MCP and ChatGPT App hosting helpers.** ## What It Provides - **Layer**: module. - **Consumers**: apps (alpic-mcp, chatgpt-app). - `src/mcp/` contains MCP handlers, tools, prompts, and resources. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.logger`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/mcp/` contains MCP handlers, tools, prompts, and resources. ## Installation `npm install @contractspec/module.alpic` or `bun add @contractspec/module.alpic` ## Usage Import the root entrypoint from `@contractspec/module.alpic`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/assets` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/mcp/` contains MCP handlers, tools, prompts, and resources. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Standardize tool naming to underscore notation. - Add changesets and apply pending fixes. - Add first-class transport, auth, versioning, and BYOK support across all integrations. - Test runner. ## Notes - Depends on `@modelcontextprotocol/sdk` and `elysia` -- version bumps may break MCP protocol compatibility. - Exposes external-facing endpoints; treat all inputs as untrusted. - Changes affect MCP tool registration and ChatGPT plugin manifests. --- ## @contractspec/module.audit-trail Description: Audit trail module for tracking and querying system events Path: packages/modules/audit-trail URL: /llms/module.audit-trail # @contractspec/module.audit-trail Website: https://contractspec.io **Audit trail module for tracking and querying system events.** ## What It Provides - **Layer**: module. - **Consumers**: bundles (library, contractspec-studio), apps (web-landing). - `src/contracts/` contains contract specs, operations, entities, and registry exports. - Related ContractSpec packages include `@contractspec/lib.bus`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/contracts/` contains contract specs, operations, entities, and registry exports. ## Installation `npm install @contractspec/module.audit-trail` or `bun add @contractspec/module.audit-trail` ## Usage Import the root entrypoint from `@contractspec/module.audit-trail`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/audit-trail.capability.ts` defines a capability surface. - `src/audit-trail.feature.ts` defines a feature entrypoint. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/entities/` contains domain entities and value objects. - `src/index.ts` is the root public barrel and package entrypoint. - `src/storage/` contains persistence adapters and storage implementations. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./audit-trail.capability` resolves through `./src/audit-trail.capability.ts`. - Export `./audit-trail.feature` resolves through `./src/audit-trail.feature.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./storage` resolves through `./src/storage/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Depends on `lib.bus` for event dispatch -- never emit events outside the bus. - Audit records are append-only; mutations or deletions break compliance invariants. - Storage adapters must implement the store interface; do not bypass it. --- ## @contractspec/module.context-storage Description: Context storage module with persistence adapters Path: packages/modules/context-storage URL: /llms/module.context-storage # @contractspec/module.context-storage Website: https://contractspec.io **Context storage module with persistence adapters.** ## What It Provides - **Layer**: module. - **Consumers**: bundles (library), apps (registry-server). - `src/pipeline/` contains pipeline stages and orchestration helpers. - Related ContractSpec packages include `@contractspec/lib.context-storage`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.knowledge`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/pipeline/` contains pipeline stages and orchestration helpers. ## Installation `npm install @contractspec/module.context-storage` or `bun add @contractspec/module.context-storage` ## Usage Import the root entrypoint from `@contractspec/module.context-storage`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/entities/` contains domain entities and value objects. - `src/index.ts` is the root public barrel and package entrypoint. - `src/pipeline/` contains pipeline stages and orchestration helpers. - `src/storage/` contains persistence adapters and storage implementations. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./pipeline/context-snapshot-pipeline` resolves through `./src/pipeline/context-snapshot-pipeline.ts`. - Export `./storage` resolves through `./src/storage/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and type errors across nine packages. - Add AI provider ranking system with ranking-driven model selection. ## Notes - Depends on `lib.context-storage`, `lib.knowledge`, `lib.contracts-integrations`. - Pipeline stages must be idempotent; re-running a snapshot should not duplicate data. - Storage adapters are swappable -- always code against the interface, not the implementation. --- ## @contractspec/module.examples Description: Example contract specifications collection Path: packages/modules/examples URL: /llms/module.examples # @contractspec/module.examples Website: https://contractspec.io **Example contract specifications collection.** ## What It Provides - **Layer**: module. - **Consumers**: apps (web-landing, docs), bundles (contractspec-studio). - Related ContractSpec packages include `@contractspec/example.agent-console`, `@contractspec/example.ai-chat-assistant`, `@contractspec/example.ai-support-bot`, `@contractspec/example.analytics-dashboard`, `@contractspec/example.calendar-google`, `@contractspec/example.content-generation`, ... - `agent-console` is the default autonomous-agent showcase surfaced through `/sandbox`. - `data-grid-showcase` is the focused ContractSpec table showcase surfaced through `/sandbox?template=data-grid-showcase`. ## Installation `npm install @contractspec/module.examples` or `bun add @contractspec/module.examples` ## Usage Import the root entrypoint from `@contractspec/module.examples`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/builtins.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/registry.test.ts` is part of the package's public or composition surface. - `src/registry.ts` is part of the package's public or composition surface. - `src/runtime` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run generate:registry` — bun ../../../scripts/generate-example-registry.ts --write - `bun run prebuild` — bun run generate:registry && contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add table capabilities. - Stability. - Vnext ai-native. ## Notes - This module is a thin aggregator -- business logic belongs in individual example packages under `packages/examples/`. - Adding a new example requires both creating the example package and wiring it as a dependency here. - Depends on ~30 example workspace packages; keep the dependency list in sync with `packages/examples/`. - The meetup-ready autonomous-agent path is the deterministic `agent-console` sandbox plus its replay proof lane. - The shared ContractSpec table stack is demonstrated directly by `data-grid-showcase` and reused in `analytics-dashboard`, `crm-pipeline`, `integration-hub`, and `agent-console`. --- ## @contractspec/module.learning-journey Description: Comprehensive learning journey engine - onboarding, LMS, flashcards, gamification, and AI personalization Path: packages/modules/learning-journey URL: /llms/module.learning-journey # @contractspec/module.learning-journey Website: https://contractspec.io **Comprehensive learning journey engine - onboarding, LMS, flashcards, gamification, and AI personalization.** ## What It Provides - **Layer**: module. - **Consumers**: bundles (library, contractspec-studio), apps (web-landing). - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Installation `npm install @contractspec/module.learning-journey` or `bun add @contractspec/module.learning-journey` ## Usage Import the root entrypoint from `@contractspec/module.learning-journey`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/engines` is part of the package's public or composition surface. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./contracts/models` resolves through `./src/contracts/models.ts`. - Export `./contracts/onboarding` resolves through `./src/contracts/onboarding.ts`. - Export `./contracts/operations` resolves through `./src/contracts/operations.ts`. - Export `./contracts/shared` resolves through `./src/contracts/shared.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/learning-journey.docblock` resolves through `./src/docs/learning-journey.docblock.ts`. - Export `./engines` resolves through `./src/engines/index.ts`. - Export `./engines/srs` resolves through `./src/engines/srs.ts`. - The package publishes 32 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add full i18n support across all 10 packages (en/fr/es, 460 keys). ## Notes - SRS/streak/XP engines are pure functions -- keep them side-effect-free. - i18n catalogs must stay in sync across all supported locales (en, es, fr). - Entity schemas are shared with the UI; breaking changes propagate to all learning surfaces. --- ## @contractspec/module.lifecycle-advisor Description: AI-powered lifecycle recommendations and guidance Path: packages/modules/lifecycle-advisor URL: /llms/module.lifecycle-advisor # @contractspec/module.lifecycle-advisor Website: https://contractspec.io **AI-powered lifecycle recommendations and guidance.** ## What It Provides - **Layer**: module. - **Consumers**: bundles (library, contractspec-studio), apps (web-landing, cli). - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.lifecycle`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.lifecycle`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/module.lifecycle-advisor` or `bun add @contractspec/module.lifecycle-advisor` ## Usage Import the root entrypoint from `@contractspec/module.lifecycle-advisor`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/ceremony` is part of the package's public or composition surface. - `src/data/` contains static content, registries, and package-local datasets. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/recommendations` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Fix small issues. - Add full i18n support across all 10 packages (en/fr/es, 460 keys). ## Notes - Depends on `lib.lifecycle` for stage definitions -- never redefine stages here. - Recommendation data lives in `src/data/`; keep data files declarative and serializable. - Advisory outputs must be deterministic for the same input state. --- ## @contractspec/module.lifecycle-core Description: Core lifecycle stage definitions and transitions Path: packages/modules/lifecycle-core URL: /llms/module.lifecycle-core # @contractspec/module.lifecycle-core Website: https://contractspec.io **Core lifecycle stage definitions and transitions.** ## What It Provides - **Layer**: module. - **Consumers**: modules (lifecycle-advisor), bundles (library, contractspec-studio), apps (web-landing, cli). - `src/adapters/` contains runtime, provider, or environment-specific adapters. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.lifecycle`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/adapters/` contains runtime, provider, or environment-specific adapters. ## Installation `npm install @contractspec/module.lifecycle-core` or `bun add @contractspec/module.lifecycle-core` ## Usage Import the root entrypoint from `@contractspec/module.lifecycle-core`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/adapters/` contains runtime, provider, or environment-specific adapters. - `src/collectors` is part of the package's public or composition surface. - `src/data/` contains static content, registries, and package-local datasets. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/orchestrator` is part of the package's public or composition surface. - `src/planning` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint/test regressions after voice capability updates. - Add full i18n support across all 10 packages (en/fr/es, 460 keys). ## Notes - Depends on `lib.lifecycle` for foundational types -- this module adds orchestration on top. - Stage transition rules are the source of truth; changes here cascade to lifecycle-advisor and all consuming bundles. - Stage data in `src/data/` must remain backward-compatible to avoid breaking persisted project states. --- ## @contractspec/module.notifications Description: Notification center module for ContractSpec applications Path: packages/modules/notifications URL: /llms/module.notifications # @contractspec/module.notifications Website: https://contractspec.io **Notification center module for ContractSpec applications.** ## What It Provides - **Layer**: module. - **Consumers**: bundles (library, contractspec-studio), apps (web-landing). - `src/contracts/` contains contract specs, operations, entities, and registry exports. - Related ContractSpec packages include `@contractspec/lib.bus`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - `src/contracts/` contains contract specs, operations, entities, and registry exports. ## Installation `npm install @contractspec/module.notifications` or `bun add @contractspec/module.notifications` ## Usage Import the root entrypoint from `@contractspec/module.notifications`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/channels` is part of the package's public or composition surface. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/entities/` contains domain entities and value objects. - `src/i18n` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/notifications.capability.ts` defines a capability surface. - `src/notifications.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./channels` resolves through `./src/channels/index.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./i18n` resolves through `./src/i18n/index.ts`. - Export `./i18n/catalogs` resolves through `./src/i18n/catalogs/index.ts`. - Export `./i18n/catalogs/en` resolves through `./src/i18n/catalogs/en.ts`. - Export `./i18n/catalogs/es` resolves through `./src/i18n/catalogs/es.ts`. - Export `./i18n/catalogs/fr` resolves through `./src/i18n/catalogs/fr.ts`. - Export `./i18n/keys` resolves through `./src/i18n/keys.ts`. - The package publishes 15 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Fix small issues. - Add full i18n support across all 10 packages (en/fr/es, 460 keys). ## Notes - Depends on `lib.bus` for event dispatch -- channel adapters must not send directly. - i18n catalogs must stay in sync across all supported locales (en, es, fr). - Templates are the single source for notification content; do not inline message strings. --- ## @contractspec/module.product-intent-core Description: Core product intent orchestration and adapters Path: packages/modules/product-intent-core URL: /llms/module.product-intent-core # @contractspec/module.product-intent-core Website: https://contractspec.io **Core product intent orchestration and adapters.** ## What It Provides - **Layer**: module. - **Consumers**: bundles (contractspec-studio), apps (web-landing). - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.product-intent-utils`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.product-intent-utils`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/module.product-intent-core` or `bun add @contractspec/module.product-intent-core` ## Usage Import the root entrypoint from `@contractspec/module.product-intent-core`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/evidence/` contains evidence ingestion and normalization helpers. - `src/index.ts` is the root public barrel and package entrypoint. - `src/orchestrator` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Depends on `lib.product-intent-utils` for shared utilities -- keep orchestration logic here, primitives in the lib. - Intent resolution must be idempotent; re-processing the same input should yield the same spec output. - Adapter interfaces are the extension point; new integrations go through the adapter pattern. --- ## @contractspec/module.provider-ranking Description: AI provider ranking module with persistence and pipeline orchestration Path: packages/modules/provider-ranking URL: /llms/module.provider-ranking # @contractspec/module.provider-ranking Website: https://contractspec.io **Provider-ranking module that adds persistence adapters and pipeline orchestration on top of lower-level ranking logic.** ## What It Provides - Coordinates ingest, storage, scoring, and ranking refresh flows over provider benchmark data. - Exposes entities, pipelines, and storage interfaces for ranking-aware applications. - Sits between ranking libraries and deployable MCP or application shells. - `src/pipeline/` contains pipeline stages and orchestration helpers. ## Installation `npm install @contractspec/module.provider-ranking` or `bun add @contractspec/module.provider-ranking` ## Usage Import the root entrypoint from `@contractspec/module.provider-ranking`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/entities/` defines ranking-related domain shapes. - `src/pipeline/` contains ingestion and ranking orchestration stages. - `src/storage/` contains persistence-facing interfaces and implementations. - `src/index.ts` exposes the composed module surface. ## Public Entry Points - Exports entities, pipeline helpers, named pipeline entrypoints, and storage surfaces. - Export `.` resolves through `./src/index.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./pipeline` resolves through `./src/pipeline/index.ts`. - Export `./pipeline/ingestion-pipeline` resolves through `./src/pipeline/ingestion-pipeline.ts`. - Export `./pipeline/ranking-pipeline` resolves through `./src/pipeline/ranking-pipeline.ts`. - Export `./storage` resolves through `./src/storage/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and type errors across nine packages. - Add Composio universal fallback, fix provider-ranking types, and expand package exports. - Add first-class transport, auth, versioning, and BYOK support across all integrations. - Add AI provider ranking system with ranking-driven model selection. ## Notes - Depends on `lib.provider-ranking` for scoring logic and ingesters -- this module adds persistence and orchestration. - Pipeline stages must be idempotent; re-ingesting the same benchmark data should not create duplicates. - Storage adapters are swappable -- always code against the interface, not the implementation. --- ## @contractspec/module.workspace Description: Workspace discovery and management module Path: packages/modules/workspace URL: /llms/module.workspace # @contractspec/module.workspace Website: https://contractspec.io **Workspace discovery and management module.** ## What It Provides - **Layer**: module. - **Consumers**: bundles (contractspec-studio), apps (cli-contractspec, vscode-contractspec). - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/module.workspace` or `bun add @contractspec/module.workspace` ## Usage Import the root entrypoint from `@contractspec/module.workspace`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/ai` is part of the package's public or composition surface. - `src/analysis` is part of the package's public or composition surface. - `src/formatter.ts` is part of the package's public or composition surface. - `src/formatters` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/templates` is part of the package's public or composition surface. - `src/types` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Stability. - Add changesets and apply pending fixes. - Add ai-native messaging channel runtime. ## Notes - Uses `ts-morph` for AST analysis and `compare-versions` for semver checks -- version bumps may affect parsing behavior. - Workspace detection is file-system-dependent; always use the provided abstractions, never raw `fs` calls. - Changes here affect CLI, VSCode extension, and studio workspace initialization flows. --- ## @contractspec/bundle.alpic Description: Alpic MCP server and ChatGPT App hosting bundle Path: packages/bundles/alpic URL: /llms/bundle.alpic # @contractspec/bundle.alpic Website: https://contractspec.io **Re-exports the Alpic module to provide MCP server and ChatGPT App hosting helpers as a single bundle entry point.** ## What It Provides - **Layer**: bundle - **Consumers**: `apps/alpic-mcp` ## Installation `npm install @contractspec/bundle.alpic` or `bun add @contractspec/bundle.alpic` ## Usage Import the root entrypoint from `@contractspec/bundle.alpic`, or use one of the documented subpaths when you want a narrower surface area. ## Public Entry Points - `.` — `./src/index.ts` ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Package exports - Make workspace tests pass without local test files ## Notes - No business logic lives here; all implementation is in `module.alpic`. - Changes to exports must stay in sync with the module's public API. --- ## @contractspec/bundle.library Description: (none) Path: packages/bundles/library URL: /llms/bundle.library # @contractspec/bundle.library **Shared library bundle that composes docs, templates, integrations, MCP implementations, and reusable presentation surfaces.** ## What It Provides - Provides the reusable product-facing bundle consumed by API, web, and documentation surfaces. - Aggregates docs pages, integration marketplace UI, templates, and library-side MCP implementations. - Acts as the main composition layer between lower-level libraries and app-specific delivery shells. - `src/presentation/` contains presentation-layer components and renderers. ## Installation `npm install @contractspec/bundle.library` or `bun add @contractspec/bundle.library` ## Usage Import the root entrypoint from `@contractspec/bundle.library`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/application/` contains application services including MCP implementations and cross-surface orchestration. - `src/components/` contains reusable docs, integrations, legal, shell, and template presentation code. - `src/features/`, `src.config/`, `src.infrastructure/`, and `src.libs/` hold bundle-local composition helpers. - `src/presentation/` contains feature-specific UI composition exported to consuming apps. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Large multi-subpath bundle exporting docs, integrations, templates, shell layout, email helpers, and MCP application surfaces. - Export `.` resolves through `./src/index.ts`. - Export `./application` resolves through `./src/application/index.ts`. - Export `./application/context-storage` resolves through `./src/application/context-storage/index.ts`. - Export `./application/mcp` resolves through `./src/application/mcp/index.ts`. - Export `./application/mcp/cliMcp` resolves through `./src/application/mcp/cliMcp.ts`. - Export `./application/mcp/common` resolves through `./src/application/mcp/common.ts`. - Export `./application/mcp/contractsMcp` resolves through `./src/application/mcp/contractsMcp.ts`. - Export `./application/mcp/contractsMcpResources` resolves through `./src/application/mcp/contractsMcpResources.ts`. - Export `./application/mcp/contractsMcpTools` resolves through `./src/application/mcp/contractsMcpTools.ts`. - Export `./application/mcp/contractsMcpTypes` resolves through `./src/application/mcp/contractsMcpTypes.ts`. - The package publishes 297 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Package exports. - Vnext ai-native. - Add latest models and align defaults. - Standardize tool naming to underscore notation. - Add changesets and apply pending fixes. ## Notes - This bundle is consumed by multiple apps — breaking export changes cascade widely. - MCP server implementations must stay transport-agnostic (the app layer wires the transport). - Keep side effects behind explicit adapters; do not perform I/O at import time. --- ## @contractspec/bundle.lifecycle-managed Description: Lifecycle management bundle with analytics and AI advisor Path: packages/bundles/lifecycle-managed URL: /llms/bundle.lifecycle-managed # @contractspec/bundle.lifecycle-managed Website: https://contractspec.io **Lifecycle management bundle with analytics and AI advisor.** ## What It Provides - **Layer**: bundle. - **Consumers**: `examples/lifecycle-cli`. - `src/services/` contains business logic services and workflows. - Related ContractSpec packages include `@contractspec/lib.analytics`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.lifecycle`, `@contractspec/lib.observability`, `@contractspec/module.lifecycle-advisor`, `@contractspec/module.lifecycle-core`, ... - `src/services/` contains business logic services and workflows. ## Installation `npm install @contractspec/bundle.lifecycle-managed` or `bun add @contractspec/bundle.lifecycle-managed` ## Usage Import the root entrypoint from `@contractspec/bundle.lifecycle-managed`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/services/` -- assessment service (lifecycle evaluation logic). - `src/agents/` -- AI lifecycle advisor agent. - `src/events/` -- lifecycle domain events. - `src/api/` -- REST handler adapters. - `src/__tests__/` -- unit tests. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and type errors across nine packages. - Add first-class transport, auth, versioning, and BYOK support across all integrations. ## Notes - Depends on six workspace packages (`lib.analytics`, `lib.contracts-spec`, `lib.lifecycle`, `lib.observability`, `module.lifecycle-advisor`, `module.lifecycle-core`); changes to those APIs propagate here. - Events must remain serializable for cross-service consumption. - Keep REST handlers thin; domain logic belongs in services. --- ## @contractspec/bundle.marketing Description: (none) Path: packages/bundles/marketing URL: /llms/bundle.marketing # @contractspec/bundle.marketing **Marketing composition bundle for the public ContractSpec site: landing narratives, product/pricing/templates pages, support pages, and email-facing marketing helpers.** ## What It Provides - Marketing page bodies consumed by `@contractspec/app.web-landing` - Scenario/template browsing surfaces used on `/templates` - Support and program pages such as contact, contribute, cofounder, and design-partner - Email/contact helpers and marketing-adjacent utilities ## Architecture - `src/components/marketing/` owns the public marketing narratives, section composition, and page-level stories. - `src/components/templates/` owns template browsing, preview, and template-to-CLI/Studio flows. - `src/libs/email/` owns contact/newsletter/waitlist actions and helpers used by marketing surfaces. - `src/index.ts` is the root public entrypoint. The important boundary: - `bundle.marketing` owns the story and page composition - `app.web-landing` owns routing, metadata, OG, shell, and public delivery ## Public Entry Points - Root export `.` through `src/index.ts` - `./components/marketing/*` for landing, product, pricing, contact, contribute, cofounder, and design-partner surfaces - `./components/templates/*` for templates browsing and preview surfaces - `./libs/email/*` for marketing contact/newsletter/waitlist helpers ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Notes - Keep the bundle focused on page storytelling and marketing interaction flows. Do not move shell/routing concerns here. - Public positioning in this package must stay aligned with root docs and `@contractspec/app.web-landing`. - If the page story changes materially, update the package docs and the public LLM-facing docs so human-facing and agent-facing descriptions do not drift. --- ## @contractspec/bundle.product-intent Description: Product intent bundle with AI runner and evidence retriever Path: packages/bundles/product-intent URL: /llms/bundle.product-intent # @contractspec/bundle.product-intent Website: https://contractspec.io **Product intent bundle with AI runner and evidence retriever.** ## What It Provides - **Layer**: bundle. - **Consumers**: not yet wired into an app (standalone bundle). - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/module.product-intent-core`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/module.product-intent-core`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/bundle.product-intent` or `bun add @contractspec/bundle.product-intent` ## Usage Import the root entrypoint from `@contractspec/bundle.product-intent`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/` -- AI runner and product-intent service. - `src/__tests__/` -- unit tests. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Uses the Vercel AI SDK (`ai`) for LLM interactions; keep provider-agnostic patterns. - Depends on `lib.contracts-spec` and `module.product-intent-core`; spec changes upstream affect this bundle. - AI runner prompts and tool definitions should remain deterministic and testable. --- ## @contractspec/bundle.workspace Description: Workspace utilities for monorepo development Path: packages/bundles/workspace URL: /llms/bundle.workspace # @contractspec/bundle.workspace Website: https://contractspec.io **Core workspace bundle that powers ContractSpec CLI, validation, code generation, AI workflows, and repository setup.** ## What It Provides - Provides the service layer behind the CLI, editor integrations, drift detection, diagnostics, and setup flows. - Owns workspace-oriented AI agents, prompts, templates, fixers, and validation/reporting services. - Acts as the main orchestration bundle for repository lifecycle and codegen workflows. - `src/adapters/` contains runtime, provider, or environment-specific adapters. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/services/` contains business logic services and workflows. ## Installation `npm install @contractspec/bundle.workspace` or `bun add @contractspec/bundle.workspace` ## Usage Import the root entrypoint from `@contractspec/bundle.workspace`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/services/` contains the core use-cases for build, validate, doctor, diff, setup, examples, and CI flows. - `src/adapters/` and `src/ports/` isolate filesystem, git, AI, and workspace integration boundaries. - `src/ai/` contains workspace-specific agent definitions, prompts, and model-aware helpers. - `src/templates/`, `src/contracts/`, `src/formatters/`, `src.types/`, and `src.utils/` support generated outputs and reporting. - `src/index.ts` is the root public barrel and package entrypoint. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Root bundle export with namespaced services, adapters, ports, formatters, templates, contracts, AI helpers, and utilities. - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add table capabilities. - Stability. - Package exports. - Add latest models and align defaults. - Standardize tool naming to underscore notation. ## Notes - Largest bundle in the monorepo (~280 source files); prefer editing existing services over adding new top-level directories. - Adapters must implement port interfaces; no direct infrastructure calls from services. - AI agent definitions must stay provider-agnostic via the `ai` SDK abstraction. - Template changes affect generated code across all consumers; test thoroughly. --- ## @contractspec/app.web-landing Description: (none) Path: packages/apps/web-landing URL: /llms/app.web-landing # @contractspec/app.web-landing **Next.js delivery shell for the public ContractSpec website: marketing, docs, registry pages, `/llms*`, and selected operate/sandbox surfaces.** ## What It Does - Owns the app shell, metadata, OG generation, route wrappers, and public site delivery. - Publishes the marketing experience while delegating most page-body composition to `@contractspec/bundle.marketing`. - Serves docs, registry, sandbox, and operate surfaces while keeping their shared shell consistent with the public brand system. - Publishes `/llms`, `/llms.txt`, `/llms-full.txt`, and package-specific `/llms/[slug]` endpoints for agent-friendly repo guidance. ## Architecture - `src/app/` contains route groups for marketing, docs, sandbox, operate, registry, and API endpoints. - `src/components/` contains app-local shell concerns such as header, footer, SEO helpers, and local route UI. - `public/llms*.txt` contains machine-readable monorepo guidance exposed directly from the site. - `scripts/generate-llms-full.mjs` regenerates the public aggregated README corpus used by `/llms-full.txt`. This package should stay thin: - marketing page narratives belong in `@contractspec/bundle.marketing` - docs and library composition belong in `@contractspec/bundle.library` - shared reusable UI primitives belong in lower layers ## Public Entry Points - Web routes under `/`, `/product`, `/pricing`, `/templates`, `/contact`, `/changelog`, `/docs/*`, `/sandbox`, `/operate/*`, and registry surfaces. - Agent-facing discovery surfaces under `/llms`, `/llms.txt`, `/llms-full.txt`, and `/llms/[slug]`. - API endpoints under `src/app/api/*`, including OG and MCP/chat-related surfaces used by the public site. ## Local Commands - `bun run dev` — bun --bun next dev - `bun run start` — bun --bun next start - `bun run build` — bun run llms:generate && bun --bun next build - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run clean` — rimraf .next dist .turbo - `bun run llms:generate` — bun scripts/generate-llms-full.mjs - `bun run build:types` — tsc --noEmit ## Notes - Route changes here affect SEO, external links, and agent-discovery flows; keep URL stability high. - Branding changes in this package must stay aligned with root docs, generated root AGENTS content, and `public/llms.txt`. - When updating the public shell, verify that docs and `/llms*` remain readable; this package serves more than the marketing homepage. --- ## @contractspec/action.drift Description: GitHub Action for ContractSpec drift detection Path: packages/apps/action-drift URL: /llms/action.drift # @contractspec/action.drift Website: https://contractspec.io **GitHub Action that detects contract drift between specs and implementation. Runs in CI to flag when generated code diverges from its source contracts.** ## What It Does - Uses `@contractspec/lib.contracts-spec` for contract definitions - Uses `@contractspec/bundle.workspace` for workspace analysis - Configured via `action.yml`; no `src/` — logic lives in workspace bundle ## Usage ```yaml name: ContractSpec Drift on: pull_request jobs: contractspec: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: lssm-tech/contractspec/packages/apps/action-drift@main with: generate-command: 'bun contractspec generate' ``` ## Inputs - `package-manager` (default: `bun`) — Package manager to use (bun|npm|pnpm|yarn) - `working-directory` (default: `.`) — Working directory for running commands - `generate-command` (default: `bun contractspec generate`) — Command to regenerate artifacts - `on-drift` (default: `fail`) — Behavior when drift is detected (fail|issue|pr) - `drift-paths-allowlist` — Comma-separated glob patterns to check for drift - `token` (default: `${{ github.token }}`) — GitHub token for issues/PRs ## Outputs - `drift-detected` — Whether drift was detected ## Key Files - `action.yml` — GitHub Action definition - `fixtures/` — Test report data for drift scenarios ## Local Commands - `bun run test` — bun test ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Stability - Stability improvements ## Notes - Do not change `action.yml` inputs/outputs without updating downstream workflow consumers - Fixture JSON files are used for CI testing — keep them valid --- ## @contractspec/action.pr Description: GitHub Action for ContractSpec PR checks Path: packages/apps/action-pr URL: /llms/action.pr # @contractspec/action.pr Website: https://contractspec.io **GitHub Action that runs ContractSpec validation checks on pull requests. Posts drift reports, validation results, and product views as PR comments.** ## What It Does - Uses `@contractspec/lib.contracts-spec` for contract definitions - Uses `@contractspec/bundle.workspace` for workspace analysis - Configured via `action.yml`; no `src/` — logic lives in workspace bundle ## Usage ```yaml name: ContractSpec PR on: pull_request jobs: contractspec: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: lssm-tech/contractspec/packages/apps/action-pr@main with: generate-command: 'bun contractspec generate' ``` ## Inputs - `package-manager` (default: `bun`) — Package manager to use (bun|npm|pnpm|yarn) - `working-directory` (default: `.`) — Working directory for running commands - `report-mode` (default: `summary`) — Report output mode (summary|comment|both|off) - `enable-drift` (default: `true`) — Run drift detection after generate - `fail-on` (default: `any`) — Fail on breaking, drift, any, or never - `generate-command` (default: `bun contractspec generate`) — Command to regenerate artifacts (required when enable-drift=true) - `validate-command` — Override validation command - `contracts-dir` — Directory containing contract specs - `contracts-glob` — Glob pattern for contract specs - `token` (default: `${{ github.token }}`) — GitHub token for PR comments ## Outputs - `drift-detected` — Whether drift was detected - `breaking-change-detected` — Whether breaking changes were detected - `validation-failed` — Whether validation failed ## Key Files - `action.yml` — GitHub Action definition - `fixtures/` — Test report data and validation fixtures - `.contractspec-ci/contracts.json` — CI contract configuration ## Local Commands - `bun run test` — bun test ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Stability - Standardize tool naming to underscore notation ## Notes - Do not change `action.yml` inputs/outputs without updating downstream workflow consumers - Fixture files are used for CI testing — keep them valid --- ## @contractspec/action.validation Description: GitHub Action for running ContractSpec CI checks Path: packages/apps/action-validation URL: /llms/action.validation # @contractspec/action.validation Website: https://contractspec.io **ContractSpec GitHub Action for CI/CD integration. Wraps the `contractspec ci` CLI command as a composite action.** ## What It Does - **Layer**: app (GitHub Action) - **Consumers**: external CI/CD pipelines via `lssm/contractspec-action@v1` ## Usage ```yaml name: ContractSpec CI on: pull_request jobs: contractspec: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: lssm-tech/contractspec/packages/apps/action-validation@main ``` ## Inputs - `checks` (default: `all`) — Checks to run (comma-separated: structure,integrity,deps,doctor,handlers,tests) or "all" - `skip` — Checks to skip (comma-separated) - `pattern` — Glob pattern for spec discovery - `fail-on-warnings` (default: `false`) — Fail the action on warnings (not just errors) - `check-handlers` (default: `false`) — Include handler implementation checks - `check-tests` (default: `false`) — Include test coverage checks - `upload-sarif` (default: `true`) — Upload SARIF results to GitHub Code Scanning - `working-directory` (default: `.`) — Working directory for running checks - `bun-version` (default: `latest`) — Bun version to use - `mode` (default: `validate`) — Action mode: "validate" (run checks) or "impact" (detect breaking changes) - `baseline` — Git ref to compare against for impact detection (default: base branch from PR context) - `pr-comment` (default: `true`) — Post impact results as PR comment ## Outputs - `success` — Whether all checks passed - `errors` — Number of errors found - `warnings` — Number of warnings found - `sarif-file` — Path to SARIF output file (if uploaded) - `json-file` — Path to JSON output file - `impact-status` — Impact status: "no-impact" | "non-breaking" | "breaking" - `breaking-count` — Number of breaking changes detected - `non-breaking-count` — Number of non-breaking changes detected ## Key Files - `action.yml` — GitHub Action definition (composite action) - `README.md` — Usage documentation - `package.json` — Package metadata (private, not published to npm) ## Local Commands - `bun run test` — bun test ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Stability - PublishConfig not supported by bun ## Notes - All input/output changes must be reflected in both `action.yml` and `README.md`. - The action is versioned with tags on the repository — breaking input changes require a major version bump. - Test locally using `act` or by referencing the local action: `uses: ./packages/apps/action-validation`. --- ## @contractspec/action.version Description: GitHub Action for ContractSpec version management Path: packages/apps/action-version URL: /llms/action.version # @contractspec/action.version Website: https://contractspec.io **GitHub Action for automated ContractSpec version management and changelog generation. Handles versioning and release workflows in CI.** ## What It Does - Standalone action with no workspace dependencies - Configured entirely via `action.yml`; no TypeScript source ## Usage ```yaml name: ContractSpec Version Manager on: pull_request jobs: contractspec: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: lssm-tech/contractspec/packages/apps/action-version@main ``` ## Inputs - `mode` (default: `analyze`) — Action mode: analyze (check only) or bump (apply changes) - `auto-bump` (default: `false`) — Whether to automatically applying bumps based on impact analysis - `commit-message` (default: `chore(release): bump spec versions [skip ci]`) — Commit message for version bumps - `create-pr` (default: `false`) — Create a Pull Request instead of pushing directly - `pr-title` (default: `chore(release): version packages`) — Title for the Pull Request - `pr-branch` (default: `release/next-versions`) — Branch name for the Pull Request - `github-token` (default: `${{ github.token }}`) — GitHub Token for creating PRs ## Outputs - `has-changes` — Whether changes were detected/applied - `specs-bumped` — Number of specs bumped ## Key Files - `action.yml` — GitHub Action definition (entry point) ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - PublishConfig not supported by bun - Move automation into actions ## Notes - Do not change `action.yml` inputs/outputs without updating downstream workflow consumers - This is a standalone action — avoid adding workspace dependencies unless necessary --- ## @contractspec/app.alpic-mcp Description: (none) Path: packages/apps/alpic-mcp URL: /llms/app.alpic-mcp # @contractspec/app.alpic-mcp Website: https://contractspec.io **MCP (Model Context Protocol) server for Alpic. Exposes ContractSpec documentation and tooling to AI agents via the MCP standard.** ## What It Does - Uses `@contractspec/bundle.alpic` for Alpic business logic. - Uses `@contractspec/lib.logger` for structured logging. - Built with tsdown; runs as a Node.js server. - Related ContractSpec packages include `@contractspec/bundle.alpic`, `@contractspec/lib.logger`, `@contractspec/tool.tsdown`, `@contractspec/tool.typescript`. ## Running Locally From `packages/apps/alpic-mcp`: - `bun run dev` - `bun run start` - `bun run build` ## Usage ```bash bun run dev ``` ## Architecture - Uses `@contractspec/bundle.alpic` for Alpic business logic. - Uses `@contractspec/lib.logger` for structured logging. - Built with tsdown; runs as a Node.js server. - `src/index.ts` is the root public barrel and package entrypoint. - `src/server.ts` is the main server bootstrap entrypoint. ## Public Entry Points - Export `.` resolves through `./dist/index.mjs`. - Export `./server` resolves through `./dist/server.mjs`. - Export `./*` resolves through `./*`. ## Local Commands - `bun run dev` — tsdown --watch - `bun run start` — node dist/server.js - `bun run build` — tsdown && mkdir -p dist && cp -R assets dist/assets - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - MCP protocol compliance is critical — do not break tool/resource schemas. - Keep server startup fast; defer heavy initialization. --- ## @contractspec/app.api-library Description: (none) Path: packages/apps/api-library URL: /llms/app.api-library # @contractspec/app.api-library **Library API server for ContractSpec documentation, templates, and MCP servers. Thin HTTP layer over `bundle.library`.** ## What It Does - This app is a thin HTTP layer — all business logic lives in `bundle.library`. - Elysia server with MCP endpoint integration. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - Internal control-plane endpoints expose approval queues, trace inspection, policy explanation, skill registry actions, and dashboard summaries for operators. - Related ContractSpec packages include `@contractspec/bundle.library`, `@contractspec/bundle.marketing`, `@contractspec/bundle.workspace`, `@contractspec/integration.providers-impls`, `@contractspec/integration.runtime`, `@contractspec/lib.contracts-spec`, ... - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/apps/api-library`: - `bun run dev` - `bun run start` - `bun run build` ## Usage ```bash bun run dev ``` ## Architecture - This app is a thin HTTP layer — all business logic lives in `bundle.library`. - Elysia server with MCP endpoint integration. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - This package is a deployable application rather than a library with published subpath exports. ## Local Commands - `bun run dev` — bun run --watch src/index.ts - `bun run start` — bun run ./dist/index.js - `bun run build` — bun run build:types && bun run build:bundle - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run clean` — rm -rf dist api/dist - `bun run build:bundle` — bun build --target node --packages bundle --outfile dist/index.js src/index.ts && mkdir -p api/dist && cp dist/index.js api/dist/index.js - `bun run build:types` — tsc -p ./tsconfig.json --noEmit - `bun run postinstall` — if [ "$VERCEL" = "1" ]; then bun run build:bundle; fi ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and type errors across nine packages. - Expose contract management via CLI and MCP. - Stabilize lint gate and runtime contract typing. - Add ai-native messaging channel runtime. - Inline server into index.ts and add Vercel configs. ## Notes - Keep this app thin — no business logic here; delegate to `bundle.library`. - MCP handler changes may affect VS Code extension and CLI consumers. - API route changes require coordinating with `app.web-landing` and any external clients. --- ## @contractspec/app.cli-contractspec Description: CLI tool for creating, building, and validating contract specifications Path: packages/apps/cli-contractspec URL: /llms/app.cli-contractspec # @contractspec/app.cli-contractspec Website: https://contractspec.io **CLI tool for creating, building, and validating contract specifications.** ## What It Does - **Commands** (`src/commands/`) - Thin wrappers that call bundle services. - **Prompts** (`src/commands/create/wizards/`) - Interactive UI using `@inquirer/prompts`. - **CLI setup** (`src/index.ts`, `src/cli.ts`) - Commander.js configuration. - **Types** (`src/types.ts`) - CLI-specific types. - **Services** (`@contractspec/bundle.workspace/services/`) - Core use-cases. - `create.ts` - Spec creation logic. - `build.ts` - Code generation from specs. - `openapi.ts` - OpenAPI export. ## Running Locally From `packages/apps/cli-contractspec`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage ```bash bun run dev ``` ## Architecture - **Commands** (`src/commands/`) - Thin wrappers that call bundle services. - **Prompts** (`src/commands/create/wizards/`) - Interactive UI using `@inquirer/prompts`. - **CLI setup** (`src/index.ts`, `src/cli.ts`) - Commander.js configuration. - **Types** (`src/types.ts`) - CLI-specific types. - **Services** (`@contractspec/bundle.workspace/services/`) - Core use-cases. - `create.ts` - Spec creation logic. - `build.ts` - Code generation from specs. - `openapi.ts` - OpenAPI export. - `registry.ts` - Registry client. - `examples.ts` - Examples management. ## Public Entry Points - Export `./run` resolves through `bun`, `node`, `default`. ## Local Commands - `bun run dev` — bun build ./src/cli.ts --outfile ./dist/cli.js --target node --watch - `bun run build` — bun run build:types && bun run build:all - `bun run test` — bun test - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist - `bun run build:bun` — bun build --outdir ./dist/bun/ --target bun --minify --sourcemap ./src/cli.ts - `bun run build:node` — bun build --outdir ./dist/node/ --target node --minify --sourcemap ./src/cli.ts - `bun run build:all` — bun run build:bun && bun run build:node - `bun run build:types` — tsc --noEmit - `bun run dev:bun` — bun build ./src/cli.ts --outfile ./dist/cli.bun.js --target bun --watch - `bun run test:watch` — bun test --watch ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add table capabilities. - Stability. - Vnext ai-native. - Add latest models and align defaults. - Resolve lint and build errors in workspace bundle and integrations lib. ## Notes - Works alongside `@contractspec/bundle.workspace`, `@contractspec/lib.ai-agent`, `@contractspec/lib.ai-providers`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, ... --- ## @contractspec/app.cli-database Description: (none) Path: packages/apps/cli-database URL: /llms/app.cli-database # @contractspec/app.cli-database Website: https://contractspec.io **CLI tool for single-database management: import, generate, migrate, seed, and schema operations. Wraps Prisma with ContractSpec schema conventions.** ## What It Does - Uses `@contractspec/lib.schema` for schema definitions. - Uses Prisma for database operations and migrations. - Commands dispatched via minimist argument parsing. - Related ContractSpec packages include `@contractspec/lib.schema`, `@contractspec/tool.tsdown`, `@contractspec/tool.typescript`. ## Running Locally From `packages/apps/cli-database`: - `bun run dev` - `bun run build` ## Usage ```bash npx database --help # or bunx database --help ``` ## Architecture - Uses `@contractspec/lib.schema` for schema definitions. - Uses Prisma for database operations and migrations. - Commands dispatched via minimist argument parsing. - `src/cli.ts` is the CLI entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Binary `database` points to `dist/cli.js`. - Export `.` resolves through `./dist/index.mjs`. - Export `./cli` resolves through `./dist/cli.mjs`. - Export `./commands/check` resolves through `./dist/commands/check.mjs`. - Export `./commands/generate` resolves through `./dist/commands/generate.mjs`. - Export `./commands/import` resolves through `./dist/commands/import.mjs`. - Export `./commands/migrate` resolves through `./dist/commands/migrate.mjs`. - Export `./commands/schema-compose` resolves through `./dist/commands/schema-compose.mjs`. - Export `./commands/schema-generate` resolves through `./dist/commands/schema-generate.mjs`. - Export `./commands/seed` resolves through `./dist/commands/seed.mjs`. - Export `./lib/config` resolves through `./dist/lib/config.mjs`. - The package publishes 12 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — bun run build --watch - `bun run build` — tsdown - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist - `bun run prisma:format` — prisma format - `bun run prisma:import` — database import - `bun run prisma:check` — database check - `bun run dbs:generate` — database generate - `bun run dbs:migrate` — database migrate:dev - `bun run dbs:deploy` — database migrate:deploy - `bun run dbs:status` — database migrate:status - `bun run dbs:seed` — database seed ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Do not change CLI argument signatures without updating docs and CI scripts. - Prisma schema generation is order-sensitive — test migrations carefully. --- ## @contractspec/app.cli-databases Description: (none) Path: packages/apps/cli-databases URL: /llms/app.cli-databases # @contractspec/app.cli-databases Website: https://contractspec.io **CLI orchestrator for multi-database workflows. Coordinates operations across multiple database profiles defined in a project.** ## What It Does - Lightweight CLI with no workspace bundle dependencies. - Uses minimist for argument parsing, execa for subprocess execution. - Delegates per-database work to `cli-database`. - Related ContractSpec packages include `@contractspec/tool.tsdown`, `@contractspec/tool.typescript`. ## Running Locally From `packages/apps/cli-databases`: - `bun run dev` - `bun run build` ## Usage ```bash npx databases --help # or bunx databases --help ``` ## Architecture - Lightweight CLI with no workspace bundle dependencies. - Uses minimist for argument parsing, execa for subprocess execution. - Delegates per-database work to `cli-database`. - `src/cli.ts` is the CLI entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Binary `databases` points to `dist/cli.js`. - Export `.` resolves through `./dist/index.mjs`. - Export `./cli` resolves through `./dist/cli.mjs`. - Export `./profile` resolves through `./dist/profile.mjs`. - Export `./*` resolves through `./*`. ## Local Commands - `bun run dev` — bun run build --watch - `bun run build` — tsdown - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Keep this as a thin orchestrator — business logic belongs in `cli-database`. - Do not change CLI argument signatures without updating docs and CI scripts. --- ## @contractspec/jetbrains-contractspec-bridge Description: Node.js bridge server for ContractSpec JetBrains Plugin Path: packages/apps/jetbrains-contractspec/bridge URL: /llms/jetbrains-contractspec-bridge # @contractspec/jetbrains-contractspec-bridge Website: https://contractspec.io/ **Node.js bridge server for ContractSpec JetBrains Plugin** JSON-RPC/LSP server over stdio that connects the JetBrains IDE plugin to ContractSpec workspace services. Uses vscode-languageserver, TextDocuments, and BridgeServer handlers. Private package; not published to npm. ## Installation / Running From the monorepo root: ```bash bun install bun run build --filter=@contractspec/jetbrains-contractspec-bridge bun run start --filter=@contractspec/jetbrains-contractspec-bridge ``` Or from this directory: ```bash bun run build bun run start ``` The bridge is typically launched by the JetBrains plugin as a subprocess; it communicates via stdin/stdout. ## Entry Point - `src/server.ts` — Creates LSP connection, TextDocuments manager, and BridgeServer. Handles `onInitialize`, `onInitialized`, and text document open/change/close events. ## Architecture - **BridgeServer** (`src/handlers/BridgeServer.ts`) — Wraps `@contractspec/bundle.workspace` and `@contractspec/module.workspace` for spec validation, scaffolding, and analysis. - **vscode-languageserver** — Provides stdio transport and LSP protocol. - **TextDocuments** — Tracks open documents for the plugin. --- ## @contractspec/app.expo-demo Description: Minimal Expo React Native app - Task List demo for ContractSpec mobile runtime Path: packages/apps/mobile-demo URL: /llms/app.expo-demo # @contractspec/app.expo-demo **Minimal Expo React Native app demonstrating ContractSpec's mobile runtime with a task list workflow.** ## What This Demonstrates - Demonstrates a spec-first mobile flow from contracts to handlers to React Native screens. - Uses the RN-safe subset of the ContractSpec UI kit and presentation runtime. - Ships task list, create-task, and status-update flows backed by an in-memory store. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/apps/mobile-demo`: - `bun run dev` - `bun run start` - `bun run test` - `bun run typecheck` ## Usage ```bash bun run dev ``` ## Architecture - `app/` contains Expo Router routes and screen wiring. - `src/contracts/` defines the task entity and mobile demo operations. - `src/handlers/` registers demo handlers against the operation registry. - `src/screens/` contains screen-level UI composition for list and form flows. ## Public Entry Points - Deployable Expo app with no published library exports. - Primary runtime surfaces are the Expo routes in `app/` and the registered operations in `src/handlers/`. ## Local Commands - `bun run dev` — expo start - `bun run start` — expo start - `bun run test` — bun test - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run android` — expo start --android - `bun run ios` — expo start --ios ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Stability. - Package exports. - Mobile app example. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.presentation-runtime-core`, `@contractspec/lib.presentation-runtime-react-native`, `@contractspec/lib.schema`, `@contractspec/lib.ui-kit`, ... --- ## @contractspec/app.provider-ranking-mcp Description: (none) Path: packages/apps/provider-ranking-mcp URL: /llms/app.provider-ranking-mcp # @contractspec/app.provider-ranking-mcp **MCP server that exposes provider-ranking operations and resources for benchmark ingestion, ranking refreshes, and leaderboard queries.** ## What It Does - Hosts a ContractSpec MCP server over provider-ranking contracts and runtime registries. - Exposes benchmark ingest, custom benchmark run, and ranking refresh operations. - Publishes leaderboard and model-profile resources backed by the ranking store. - Enriches incomplete ranking data with metadata from `@contractspec/lib.ai-providers`. ## Running Locally From `packages/apps/provider-ranking-mcp`: - `bun run dev` - `bun run start` - `bun run build` ## Usage ```bash bun run dev ``` ## Architecture - `src/server.ts` boots the MCP server and transport wiring. - `src/index.ts` exposes the package entrypoints for reuse or embedding. - The server composes provider-ranking contracts, module orchestration, and MCP resource/tool exposure. ## Public Entry Points - Exports `.` and `./server` for embedding or direct server startup. - Primary MCP surfaces are benchmark-ingest tools, ranking refresh tools, leaderboard resources, and model-profile resources. - Export `.` resolves through `./dist/index.mjs`. - Export `./server` resolves through `./dist/server.mjs`. - Export `./*` resolves through `./*`. ## Local Commands - `bun run dev` — tsdown --watch - `bun run start` — node dist/server.js - `bun run build` — tsdown - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run clean` — rm -rf dist ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add latest models and align defaults. - Resolve lint, build, and type errors across nine packages. - Add AI provider ranking system with ranking-driven model selection. ## Notes - The current implementation uses an in-memory store; restart the process to clear rankings and benchmark results. --- ## @contractspec/app.registry-packs Description: (none) Path: packages/apps/registry-packs URL: /llms/app.registry-packs # @contractspec/app.registry-packs Website: https://agentpacks.dev **Agentpacks registry server for pack publishing, discovery, reviews, dependency graphs, and MCP access.** ## What It Does - Hosts the pack registry API, MCP layer, artifact storage, and publishing workflows. - Supports versioning, reviews, organizations, quality scoring, GitHub integration, and webhooks. - Supports both SQLite and PostgreSQL deployment paths with rate-limiting and auth middleware. - `src/mcp/` contains MCP handlers, tools, prompts, and resources. - `src/routes/` contains HTTP or API route definitions. - `src/services/` contains business logic services and workflows. ## Running Locally From `packages/apps/registry-packs`: - `bun run dev` - `bun run start` - `bun run build` - `bun run test` ## Usage ```bash bun run dev ``` ## Architecture - `src/routes/` owns HTTP endpoints for packs, versions, publishing, organizations, dependencies, and GitHub flows. - `src/services/` contains business workflows for registry operations, search, scoring, reviews, and webhooks. - `src/mcp/` exposes registry tools, prompts, and resources over the MCP protocol. - `src/db/`, `src/storage/`, `src/auth/`, and `src/middleware/` hold persistence and platform adapters. - `src/index.ts` is the root public barrel and package entrypoint. - `src/server.ts` is the main server bootstrap entrypoint. ## Public Entry Points - Deployable API app with HTTP routes, MCP tools/prompts/resources, and registry publishing flows. - Primary public surface is the HTTP route tree under `src/routes/`. - This app exposes MCP-facing tools, prompts, resources, or transport handlers. ## Local Commands - `bun run dev` — bun run --watch src/index.ts - `bun run start` — bun run ./dist/index.js - `bun run build` — bun build --minify-whitespace --minify-syntax --target bun --outfile dist/index.js src/index.ts - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run db:generate` — drizzle-kit generate - `bun run db:migrate` — drizzle-kit migrate - `bun run db:studio` — drizzle-kit studio - `bun run clean` — rm -rf dist - `bun run db:generate:pg` — drizzle-kit generate --config=drizzle-pg.config.ts - `bun run db:migrate:pg` — drizzle-kit migrate --config=drizzle-pg.config.ts - `bun run db:seed` — bun run src/db/seed.ts ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint and build errors in workspace bundle and integrations lib. - Test runner. - Resolve lint/test regressions after voice capability updates. - Phase 4 production hardening — rate limiting, security, E2E tests, versioning polish. - Add dependency graph, webhooks, GitHub App, and PostgreSQL support (Phase 3b). ## Notes - REST API routes are consumed by external clients — do not change paths or response shapes without versioning. - MCP tool schemas are a protocol contract — coordinate changes with MCP clients. - Database migrations must be backwards-compatible. --- ## @contractspec/app.registry-server Description: (none) Path: packages/apps/registry-server URL: /llms/app.registry-server # @contractspec/app.registry-server Website: https://contractspec.io **ContractSpec registry server. Serves contract specs and metadata over HTTP for IDE plugins, CLI tools, and other consumers.** ## What It Does - Built with Elysia (Bun HTTP framework). - Uses `@contractspec/lib.contracts-spec` for contract definitions. - Uses `@contractspec/lib.logger` for structured logging. - Separate handlers for ContractSpec and LSSM routes. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/apps/registry-server`: - `bun run dev` - `bun run start` - `bun run build` ## Usage ```bash bun run dev ``` ## Architecture - Built with Elysia (Bun HTTP framework). - Uses `@contractspec/lib.contracts-spec` for contract definitions. - Uses `@contractspec/lib.logger` for structured logging. - Separate handlers for ContractSpec and LSSM routes. - `src/index.ts` is the root public barrel and package entrypoint. - `src/server.ts` is the main server bootstrap entrypoint. ## Public Entry Points - This package is a deployable application rather than a library with published subpath exports. ## Local Commands - `bun run dev` — bun run --watch src/server.ts - `bun run start` — ./server - `bun run build` — bun build --compile --minify-whitespace --minify-syntax --target bun --outfile dist/server src/index.ts - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rm -rf dist server ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - API routes are consumed by IDE plugins and CI — do not change paths or response shapes without versioning. - Filesystem access must use the `src/utils/` helpers for consistent path resolution. --- ## @contractspec/app.video-studio Description: (none) Path: packages/apps/video-studio URL: /llms/app.video-studio # @contractspec/app.video-studio **Thin Remotion Studio wrapper. Re-exports the Remotion entry point from `@contractspec/lib.video-gen`.** ## What It Does - **Layer**: app (Remotion Studio) - **Consumers**: internal — video preview and rendering ## Running Locally From `packages/apps/video-studio`: - `bun run dev` - `bun run build` ## Usage ```bash bun run dev ``` ## Local Commands - `bun run dev` — bunx remotionb studio src/index.ts - `bun run build` — echo 'No build step needed for Remotion Studio' - `bun run clean` — rimraf out .turbo - `bun run render` — bunx remotionb render src/index.ts - `bun run render:all` — bunx remotionb render src/index.ts ApiOverview out/api-overview.mp4 && bunx remotionb render src/index.ts SocialClip out/social-clip.mp4 && bunx remotionb render src/index.ts SocialClipSquare out/social-clip-square.mp4 && bunx remotionb render src/index.ts SocialClipPortrait out/social-clip-portrait.mp4 && bunx remotionb render src/index.ts TerminalDemo out/terminal-demo.mp4 ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Improve agentpacks - Switch Remotion CLI to bunx remotionb for Bun runtime support ## Notes - Do NOT add compositions here. All compositions live in `@contractspec/lib.video-gen`. - This package exists solely to provide a Remotion Studio entry point. - Uses `remotionb` CLI for Bun runtime support. Known caveat: SSR scripts may not auto-quit (see [Remotion Bun docs](https://www.remotion.dev/docs/bun)). --- ## vscode-contractspec Description: ContractSpec: spec-first development for AI-written software. Validate, scaffold, and explore your contract specifications. Path: packages/apps/vscode-contractspec URL: /llms/vscode-contractspec # vscode-contractspec Website: https://contractspec.io **ContractSpec: spec-first development for AI-written software. Validate, scaffold, and explore your contract specifications.** ## What It Does - `@contractspec/module.workspace` for pure analysis + templates. - `@contractspec/bundle.workspace` for workspace services + adapters. - `src/ui/` contains packaged UI exports and embeddable views. - Related ContractSpec packages include `@contractspec/bundle.workspace`, `@contractspec/lib.ai-agent`, `@contractspec/lib.ai-providers`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.contracts-transformers`, `@contractspec/module.ai-chat`, ... - `src/ui/` contains packaged UI exports and embeddable views. ## Running Locally From `packages/apps/vscode-contractspec`: - `bun run dev` - `bun run build` - `bun run test` ## Usage ```bash bun run dev ``` ## Architecture - `@contractspec/module.workspace` for pure analysis + templates. - `@contractspec/bundle.workspace` for workspace services + adapters. ## Public Entry Points - This package is a deployable application rather than a library with published subpath exports. ## Local Commands - `bun run dev` — bun build src/extension.ts --outdir=dist --target=node --format=cjs --external=vscode --sourcemap=external --watch - `bun run build` — bun run build:types && bun run build:bundle - `bun run test` — vscode-test - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run vscode:prepublish` — bun run build - `bun run build:bundle` — bun build src/extension.ts --outdir=dist --target=node --format=cjs --external=vscode --minify - `bun run build:types` — tsc --noEmit - `bun run package` — vsce package --no-dependencies - `bun run publish:off` — vsce publish --no-dependencies ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Standardize tool naming to underscore notation. ## Notes - Works alongside `@contractspec/bundle.workspace`, `@contractspec/lib.ai-agent`, `@contractspec/lib.ai-providers`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.contracts-transformers`, ... --- ## @contractspec/example.agent-console Description: Agent Console example - AI agent orchestration with tools, runs, and logs Path: packages/examples/agent-console URL: /llms/example.agent-console # @contractspec/example.agent-console Website: https://contractspec.io **Agent Console example - AI agent orchestration with tools, runs, and logs.** ## What This Demonstrates - Agent entity with lifecycle (create, configure, execute). - Canonical `agent` example exports plus business-oriented `harness-scenario` and `harness-suite` proof coverage. - Run tracking with status enums and event-driven state transitions. - Tool registry with typed schemas and operation handlers. - Presentation layer with React UI components, hooks, modals, overlays, and a server-mode shared `DataTable` for run history. - Shared table capabilities including sorting, pagination, column visibility toggles, and expandable run diagnostics. - Contract-backed visualization surfaces for run status, activity, and duration-vs-token analysis. - One deterministic demo runtime shared across React hooks, markdown renderers, and the sandbox runtime. - Markdown and React renderers for multi-surface output. - Seeded local data and harness replay proof for offline-safe demo scenarios. ## Canonical Demo Path - Default sandbox route: `/sandbox` - Explicit sandbox route: `/sandbox?template=agent-console` - Proof artifact: `packages/examples/agent-console/proofs/agent-console-meetup.replay.json` The canonical walkthrough is deterministic and local-first: 1. Load the agent-console sandbox. 2. Inspect seeded agents, tools, runs, and metrics. 3. Create an agent. 4. Activate or pause it. 5. Execute a run. 6. Confirm the run and metrics update. 7. Export or inspect the generated replay proof. ## Runtime Boundaries - React hooks and the sandbox use `createAgentConsoleDemoHandlers(...)` for the meetup path. - Markdown renderers prefer runtime-fetched data and fall back to the same deterministic demo handlers. - The demo runtime is intentionally mocked and offline-safe by default. - Database-backed `createAgentHandlers(db)` remains available for non-demo runtime wiring. ## Running Locally From `packages/examples/agent-console`: - `bun run dev` - `bun run build` - `bun run test` - `bun run proof` - `bun run typecheck` - `bun run preflight` From the repository root: - `bun run meetup:agent-console:policy` - `bun run meetup:agent-console:proof` - `bun run meetup:agent-console:preflight` ## Usage Use `@contractspec/example.agent-console` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/agent` is part of the package's public or composition surface. - `src/agent.capability.ts` defines a capability surface. - `src/agent.feature.ts` defines a feature entrypoint. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/proof/` contains the exported meetup proof scenario and suite. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./agent` resolves through `./src/agent/index.ts`. - Export `./agent.capability` resolves through `./src/agent.capability.ts`. - Export `./agent.feature` resolves through `./src/agent.feature.ts`. - Export `./agent/agent.entity` resolves through `./src/agent/agent.entity.ts`. - Export `./agent/agent.enum` resolves through `./src/agent/agent.enum.ts`. - Export `./agent/agent.event` resolves through `./src/agent/agent.event.ts`. - Export `./agent/agent.handler` resolves through `./src/agent/agent.handler.ts`. - Export `./agent/agent.operation` resolves through `./src/agent/agent.operation.ts`. - Export `./agent/agent.presentation` resolves through `./src/agent/agent.presentation.ts`. - Export `./proof` resolves through `./src/proof/index.ts`. - Export `./proof/meetup-proof.scenario` resolves through `./src/proof/meetup-proof.scenario.ts`. - Export `./proof/meetup-proof.suite` resolves through `./src/proof/meetup-proof.suite.ts`. - The package publishes 72 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run proof` — bun ../../../scripts/generate-agent-console-meetup-proof.ts - `bun run preflight` — bun run build && bun run typecheck && bun run test && bun ../../../scripts/check-agent-console-meetup-policy.ts && bun run proof - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Unified the meetup demo around a single seeded runtime. - Added focused handler tests, a sandbox smoke test, and a harness replay proof. - Added a slice-scoped meetup preflight instead of relying on the repo-wide policy backlog. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.example-shared-ui`, `@contractspec/lib.runtime-sandbox`, `@contractspec/lib.schema`, ... --- ## @contractspec/example.ai-chat-assistant Description: Focused AI chat assistant template with MCP tools, reasoning, chain of thought, sources, and suggestions. Path: packages/examples/ai-chat-assistant URL: /llms/example.ai-chat-assistant # @contractspec/example.ai-chat-assistant Website: https://contractspec.io **Focused AI chat assistant example with MCP tools, reasoning, sources, suggestions, and reusable dashboard UI.** ## What This Demonstrates - Demonstrates how `@contractspec/module.ai-chat` can power a focused assistant experience. - Publishes feature, contracts, handlers, docs, example, and dashboard UI entrypoints. - Provides a search-backed, source-aware assistant template for example consumers and docs. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/examples/ai-chat-assistant`: - `bun run dev` - `bun run build` - `bun run test` - `bun run smoke` - `bun run typecheck` ## Usage Use `@contractspec/example.ai-chat-assistant` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/ai-chat-assistant.feature.ts` defines the example feature surface. - `src/contracts/` contains the assistant operation contract exports. - `src/handlers/` contains the demo assistant handlers wired to the example feature. - `src/ui/` contains the packaged dashboard UI for embedding or demonstration. - `src/docs/` and `src/example.ts` provide docblock and runnable example entrypoints. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Exports the feature surface, contract barrels, handlers, docs entrypoints, runnable example, and dashboard UI. - Export `.` resolves through `./src/index.ts`. - Export `./ai-chat-assistant.feature` resolves through `./src/ai-chat-assistant.feature.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./contracts/assistant.operation` resolves through `./src/contracts/assistant.operation.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/ai-chat-assistant.docblock` resolves through `./src/docs/ai-chat-assistant.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - Export `./handlers/assistant.handlers` resolves through `./src/handlers/assistant.handlers.ts`. - Export `./ui` resolves through `./src/ui/index.ts`. - The package publishes 11 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run smoke` — bun test src/example.smoke.test.ts - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Stability. - Vnext ai-native. ## Notes - Works alongside `@contractspec/lib.ai-agent`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/module.ai-chat`, `@contractspec/tool.bun`, ... --- ## @contractspec/example.ai-support-bot Description: AI support bot example: classify and resolve a support ticket using @contractspec/lib.support-bot. Path: packages/examples/ai-support-bot URL: /llms/example.ai-support-bot # @contractspec/example.ai-support-bot Website: https://contractspec.io **AI support bot example: classify and resolve a support ticket using @contractspec/lib.support-bot.** ## What This Demonstrates - Ticket classification pipeline with AI-driven resolution. - Integration of support-bot lib with knowledge base. - DocBlock documentation for in-app help. - Setup and example entry points for quick cloning. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/ai-support-bot`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.ai-support-bot` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/ai-support-bot.feature.ts` defines a feature entrypoint. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/setup.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./ai-support-bot.feature` resolves through `./src/ai-support-bot.feature.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/ai-support-bot.docblock` resolves through `./src/docs/ai-support-bot.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./setup` resolves through `./src/setup.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.knowledge`, `@contractspec/lib.logger`, `@contractspec/lib.support-bot`, `@contractspec/tool.bun`, ... --- ## @contractspec/example.analytics-dashboard Description: Analytics Dashboard example with widgets and query engine for ContractSpec Path: packages/examples/analytics-dashboard URL: /llms/example.analytics-dashboard # @contractspec/example.analytics-dashboard Website: https://contractspec.io **Analytics Dashboard example with widgets and query engine for ContractSpec.** ## What This Demonstrates - Dashboard feature with presentation, schema, enum, and test-spec. - Query engine with typed operations and handlers. - PostHog datasource adapter. - React UI with hooks, renderers, markdown output, and a shared ContractSpec `DataTable` for saved queries. - Client-mode table capabilities including sorting, pagination, column visibility, column resizing, pinning, and expandable row details. - Event definitions for analytics tracking. - Seeders for demo data. ## Running Locally From `packages/examples/analytics-dashboard`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.analytics-dashboard` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/dashboard` is part of the package's public or composition surface. - `src/dashboard.feature.ts` defines a feature entrypoint. - `src/datasource` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/events.ts` is package-level event definitions. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./dashboard` resolves through `./src/dashboard/index.ts`. - Export `./dashboard.feature` resolves through `./src/dashboard.feature.ts`. - Export `./dashboard/dashboard.enum` resolves through `./src/dashboard/dashboard.enum.ts`. - Export `./dashboard/dashboard.operation` resolves through `./src/dashboard/dashboard.operation.ts`. - Export `./dashboard/dashboard.presentation` resolves through `./src/dashboard/dashboard.presentation.ts`. - Export `./dashboard/dashboard.schema` resolves through `./src/dashboard/dashboard.schema.ts`. - Export `./dashboard/dashboard.test-spec` resolves through `./src/dashboard/dashboard.test-spec.ts`. - Export `./datasource/posthog-datasource` resolves through `./src/datasource/posthog-datasource.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - The package publishes 37 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add data visualization capabilities. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.example-shared-ui`, `@contractspec/lib.runtime-sandbox`, ... --- ## @contractspec/example.calendar-google Description: Google Calendar integration example: list and create events. Path: packages/examples/calendar-google URL: /llms/example.calendar-google # @contractspec/example.calendar-google Website: https://contractspec.io **Google Calendar integration example: list and create events.** ## What This Demonstrates - OAuth-based Google Calendar API wiring. - Event listing and creation flows. - Sync logic for calendar data. - Integration provider pattern with ContractSpec contracts. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/calendar-google`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.calendar-google` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/calendar-google.feature.ts` defines a feature entrypoint. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/run.ts` is part of the package's public or composition surface. - `src/sync.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./calendar-google.feature` resolves through `./src/calendar-google.feature.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/calendar-google.docblock` resolves through `./src/docs/calendar-google.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./run` resolves through `./src/run.ts`. - Export `./sync` resolves through `./src/sync.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/integration.providers-impls`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.content-generation Description: Content generation example using @contractspec/lib.content-gen. Path: packages/examples/content-generation URL: /llms/example.content-generation # @contractspec/example.content-generation Website: https://contractspec.io **Content generation example using @contractspec/lib.content-gen.** ## What This Demonstrates - Content generation pipeline with typed contracts. - Integration with the content-gen library. - Structured logging for generation steps. - DocBlock documentation for the generation flow. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/content-generation`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.content-generation` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/content-generation.feature.ts` defines a feature entrypoint. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/generate.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./content-generation.feature` resolves through `./src/content-generation.feature.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/content-generation.docblock` resolves through `./src/docs/content-generation.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./generate` resolves through `./src/generate.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.content-gen`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.logger`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.crm-pipeline Description: CRM Pipeline - Contacts, Companies, Deals, Tasks Path: packages/examples/crm-pipeline URL: /llms/example.crm-pipeline # @contractspec/example.crm-pipeline Website: https://contractspec.io **CRM Pipeline - Contacts, Companies, Deals, Tasks.** ## What This Demonstrates - Multi-entity domain model (Contact, Company, Deal, Task). - Deal pipeline with stage enums, operations, and test-specs. - Event-driven architecture (contact, deal, task events). - Presentation layer with dashboard and pipeline views. - React UI with pipeline board, hooks, modals, overlays, renderers, and a server-mode shared `DataTable` for deals. - Shared table capabilities including sorting, pagination, multi-row selection, column visibility, pinning, resizing, and expandable deal details. - Feature definition and capability pattern. - Seeders and mock data. ## Running Locally From `packages/examples/crm-pipeline`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.crm-pipeline` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/crm-pipeline.feature.ts` defines a feature entrypoint. - `src/deal` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/events` is part of the package's public or composition surface. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./crm-pipeline.feature` resolves through `./src/crm-pipeline.feature.ts`. - Export `./deal` resolves through `./src/deal/index.ts`. - Export `./deal/deal.enum` resolves through `./src/deal/deal.enum.ts`. - Export `./deal/deal.operation` resolves through `./src/deal/deal.operation.ts`. - Export `./deal/deal.schema` resolves through `./src/deal/deal.schema.ts`. - Export `./deal/deal.test-spec` resolves through `./src/deal/deal.test-spec.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/crm-pipeline.docblock` resolves through `./src/docs/crm-pipeline.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - The package publishes 44 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run validate` — contractspec validate "src/**/*" - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.example-shared-ui`, `@contractspec/lib.identity-rbac`, `@contractspec/lib.runtime-sandbox`, ... --- ## @contractspec/example.data-grid-showcase Description: Focused data-grid example for ContractSpec table capabilities Path: packages/examples/data-grid-showcase URL: /llms/example.data-grid-showcase # @contractspec/example.data-grid-showcase Website: https://contractspec.io **Focused data-grid example for ContractSpec table capabilities.** ## What This Demonstrates - ContractSpec-native table composition through `useContractTable`, `useDataViewTable`, and the design-system `DataTable`. - Client-mode and server-mode table controllers with sorting, pagination, selection, column visibility, resizing, pinning, and row expansion. - A declarative `DataViewSpec` table contract that adapts onto the same headless table stack. - Sandbox-friendly UI packaging for a focused example instead of a full app template. ## Running Locally From `packages/examples/data-grid-showcase`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.data-grid-showcase` as a focused reference for ContractSpec table primitives, or import its exported contracts and UI into docs, sandboxes, and internal examples. ## Architecture - `src/contracts/` owns the sample query contract and declarative data view spec. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the example manifest surfaced by `@contractspec/module.examples`. - `src/ui/` contains the table showcase component and demo data/helpers. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./contracts/data-grid-showcase.data-view` resolves through `./src/contracts/data-grid-showcase.data-view.ts`. - Export `./contracts/data-grid-showcase.operation` resolves through `./src/contracts/data-grid-showcase.operation.ts`. - Export `./data-grid-showcase.feature` resolves through `./src/data-grid-showcase.feature.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./ui` resolves through `./src/ui/index.ts`. - Export `./ui/DataGridShowcase` resolves through `./src/ui/DataGridShowcase.tsx`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit ## Notes - This package is intentionally narrow: it exists to showcase the table primitive, not to simulate a full vertical business template. - The same table stack is reused by the larger examples in `analytics-dashboard`, `crm-pipeline`, `integration-hub`, and `agent-console`. --- ## @contractspec/example.email-gmail Description: Gmail integration example: inbound threads and outbound messages. Path: packages/examples/email-gmail URL: /llms/example.email-gmail # @contractspec/example.email-gmail Website: https://contractspec.io **Gmail integration example: inbound threads and outbound messages.** ## What This Demonstrates - OAuth authentication flow for Gmail API. - Inbound email thread processing. - Outbound message composition and sending. - Integration provider pattern with ContractSpec contracts. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/email-gmail`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.email-gmail` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/auth.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/email-gmail.feature.ts` defines a feature entrypoint. - `src/example.ts` is the runnable example entrypoint. - `src/inbound.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/outbound.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./auth` resolves through `./src/auth.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/email-gmail.docblock` resolves through `./src/docs/email-gmail.docblock.ts`. - Export `./email-gmail.feature` resolves through `./src/email-gmail.feature.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./inbound` resolves through `./src/inbound.ts`. - Export `./outbound` resolves through `./src/outbound.ts`. - Export `./run` resolves through `./src/run.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/integration.providers-impls`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.harness-lab Description: Focused harness example for ContractSpec scenarios, suites, orchestration, and runtime adapters. Path: packages/examples/harness-lab URL: /llms/example.harness-lab # @contractspec/example.harness-lab Website: https://contractspec.io **Focused harness example for scenario contracts, suites, orchestration, and real runtime adapters.** ## What This Demonstrates - Contract layer: canonical `harness-scenario` and `harness-suite` exports. - Orchestration layer: `HarnessRunner`, `HarnessEvaluationRunner`, and replay bundle generation. - Runtime layer: `SandboxedCodeExecutionAdapter`, `PlaywrightBrowserHarnessAdapter`, `DefaultHarnessTargetResolver`, and `InMemoryHarnessArtifactStore`. - A deterministic local browser fixture that stays offline and exercises the real Playwright lane. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/harness-lab`: - `bunx playwright install chromium` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.harness-lab` as the focused harness reference package. It pairs with `@contractspec/example.agent-console`, which remains the business-oriented proof example for harness contracts. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/harness-lab.feature.ts` defines the feature entrypoint for docs/discovery. - `src/index.ts` is the root public barrel and package entrypoint. - `src/runtime/` contains the runnable sandbox and browser evaluation helpers plus the local browser fixture. - `src/scenarios/` contains the focused scenario contracts. - `src/suite/` contains the dual-mode harness suite contract. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/harness-lab.docblock` resolves through `./src/docs/harness-lab.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./harness-lab.feature` resolves through `./src/harness-lab.feature.ts`. - Export `./runtime` resolves through `./src/runtime/index.ts`. - Export `./runtime/runBrowserEvaluation` resolves through `./src/runtime/runBrowserEvaluation.ts`. - Export `./runtime/runSandboxEvaluation` resolves through `./src/runtime/runSandboxEvaluation.ts`. - Export `./scenarios` resolves through `./src/scenarios/index.ts`. - Export `./scenarios/harnessLabBrowser.scenario` resolves through `./src/scenarios/harnessLabBrowser.scenario.ts`. - Export `./scenarios/harnessLabSandbox.scenario` resolves through `./src/scenarios/harnessLabSandbox.scenario.ts`. - Export `./suite` resolves through `./src/suite/index.ts`. - The package publishes 12 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Notes - Browser tests use a real local Playwright run against an in-package HTTP fixture. Install Chromium locally before running `bun run test`. --- ## @contractspec/example.in-app-docs Description: Example showing how to use DocBlock for in-app documentation for non-technical users Path: packages/examples/in-app-docs URL: /llms/example.in-app-docs # @contractspec/example.in-app-docs Website: https://contractspec.io **Example showing how to use DocBlock for in-app documentation for non-technical users.** ## What This Demonstrates - DocBlock-driven in-app documentation pattern. - React viewer component for rendering DocBlocks. - User-facing documentation without technical jargon. - `src/docs/` contains docblocks and documentation-facing exports. - `src/ui/` contains packaged UI exports and embeddable views. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/in-app-docs`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.in-app-docs` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/in-app-docs.feature.ts` defines a feature entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/ui/` contains packaged UI exports and embeddable views. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/in-app-docs.docblock` resolves through `./src/docs/in-app-docs.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./in-app-docs.feature` resolves through `./src/in-app-docs.feature.ts`. - Export `./ui` resolves through `./src/ui/index.ts`. - Export `./ui/InAppDocsViewer` resolves through `./src/ui/InAppDocsViewer.tsx`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.example-shared-ui`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.integration-hub Description: Integration Hub example with sync engine and field mappings for ContractSpec Path: packages/examples/integration-hub URL: /llms/example.integration-hub # @contractspec/example.integration-hub Website: https://contractspec.io **Integration Hub example with sync engine and field mappings for ContractSpec.** ## What This Demonstrates - Connection management with typed schemas and enums. - Integration lifecycle (create, configure, sync). - Sync engine with field mapping and status tracking. - MCP server example for tool integration. - Capability and feature definition patterns. - React UI with dashboard, hooks, markdown renderers, and shared ContractSpec tables for connections and sync configs. - Contract-backed visualizations for integration mix, connection health, and sync-state comparison. - Client-mode table capabilities including sorting, pagination, column visibility, pinning, resizing, and expanded operational details. - Event definitions and operation test-specs. ## Running Locally From `packages/examples/integration-hub`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.integration-hub` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/connection` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/events.ts` is package-level event definitions. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/integration` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./connection` resolves through `./src/connection/index.ts`. - Export `./connection/connection.enum` resolves through `./src/connection/connection.enum.ts`. - Export `./connection/connection.operation` resolves through `./src/connection/connection.operation.ts`. - Export `./connection/connection.presentation` resolves through `./src/connection/connection.presentation.ts`. - Export `./connection/connection.schema` resolves through `./src/connection/connection.schema.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/integration-hub.docblock` resolves through `./src/docs/integration-hub.docblock.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./example` resolves through `./src/example.ts`. - The package publishes 36 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run validate` — contractspec validate "src/**/*" - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run run:mcp` — bun tsx src/run-mcp.ts - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Vnext ai-native. - Missing contract layers. - Resolve lint, build, and type errors across nine packages. - Add Composio universal fallback, fix provider-ranking types, and expand package exports. - Add first-class transport, auth, versioning, and BYOK support across all integrations. ## Notes - Works alongside `@contractspec/lib.ai-agent`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.example-shared-ui`, `@contractspec/lib.runtime-sandbox`, ... --- ## @contractspec/example.integration-posthog Description: PostHog analytics integration example: capture events, run HogQL, and manage feature flags. Path: packages/examples/integration-posthog URL: /llms/example.integration-posthog # @contractspec/example.integration-posthog Website: https://contractspec.io **PostHog analytics integration example: capture events, run HogQL, and manage feature flags.** ## What This Demonstrates - PostHog event capture and tracking setup. - HogQL query execution pattern. - Feature flag management via PostHog API. - Integration provider pattern with ContractSpec contracts. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/integration-posthog`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.integration-posthog` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/integration-posthog.feature.ts` defines a feature entrypoint. - `src/posthog.ts` is part of the package's public or composition surface. - `src/run.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/integration-posthog.docblock` resolves through `./src/docs/integration-posthog.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./integration-posthog.feature` resolves through `./src/integration-posthog.feature.ts`. - Export `./posthog` resolves through `./src/posthog.ts`. - Export `./run` resolves through `./src/run.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add changesets and apply pending fixes. - Missing contract layers. ## Notes - Works alongside `@contractspec/integration.providers-impls`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.integration-stripe Description: Integration example – Stripe Payments (blueprint + workflow + tenant config). Path: packages/examples/integration-stripe URL: /llms/example.integration-stripe # @contractspec/example.integration-stripe Website: https://contractspec.io **Integration example – Stripe Payments (blueprint + workflow + tenant config).** ## What This Demonstrates - Canonical `integration` export via `StripePaymentsIntegrationSpec`. - Integration-oriented `app-config` example via `defineAppConfig(...)`. - Canonical `workflow` export via `defineWorkflow(...)`. - Multi-tenant configuration pattern. - Connection sample for credential wiring. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/integration-stripe`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.integration-stripe` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/blueprint.ts` is part of the package's public or composition surface. - `src/connection.sample.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/integration.ts` defines the exported integration spec. - `src/index.ts` is the root public barrel and package entrypoint. - `src/integration-stripe.feature.ts` defines a feature entrypoint. - `src/tenant.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./blueprint` resolves through `./src/blueprint.ts`. - Export `./connection.sample` resolves through `./src/connection.sample.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/integration-stripe.docblock` resolves through `./src/docs/integration-stripe.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./integration` resolves through `./src/integration.ts`. - Export `./integration-stripe.feature` resolves through `./src/integration-stripe.feature.ts`. - Export `./tenant` resolves through `./src/tenant.ts`. - Export `./workflow` resolves through `./src/workflow.ts`. - The package publishes 9 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.integration-supabase Description: Integration example - Supabase vector store + Postgres database wiring. Path: packages/examples/integration-supabase URL: /llms/example.integration-supabase # @contractspec/example.integration-supabase Website: https://contractspec.io **Integration example - Supabase vector store + Postgres database wiring.** ## What This Demonstrates - Integration blueprint for Supabase vector store + Postgres. - Multi-tenant configuration pattern. - Connection sample for credential wiring. - Runtime sample for execution context setup. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/integration-supabase`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.integration-supabase` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/blueprint.ts` is part of the package's public or composition surface. - `src/connection.sample.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/integration-supabase.feature.ts` defines a feature entrypoint. - `src/runtime.sample.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./blueprint` resolves through `./src/blueprint.ts`. - Export `./connection.sample` resolves through `./src/connection.sample.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/integration-supabase.docblock` resolves through `./src/docs/integration-supabase.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./integration-supabase.feature` resolves through `./src/integration-supabase.feature.ts`. - Export `./runtime.sample` resolves through `./src/runtime.sample.ts`. - Export `./tenant` resolves through `./src/tenant.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/integration.providers-impls`, `@contractspec/integration.runtime`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, ... --- ## @contractspec/example.kb-update-pipeline Description: Example: KB update automation pipeline with HITL review and auditability. Path: packages/examples/kb-update-pipeline URL: /llms/example.kb-update-pipeline # @contractspec/example.kb-update-pipeline Website: https://contractspec.io **Example: KB update automation pipeline with HITL review and auditability.** ## What This Demonstrates - HITL (human-in-the-loop) review pipeline pattern. - Entity models for KB articles and update proposals. - Event-driven pipeline with typed operations. - Feature definition with presentations and test-specs. - In-memory handlers for demo scenarios. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/kb-update-pipeline`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.kb-update-pipeline` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/kb-update-pipeline.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/kb-update-pipeline.docblock` resolves through `./src/docs/kb-update-pipeline.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./entities/models` resolves through `./src/entities/models.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - Export `./handlers/memory.handlers` resolves through `./src/handlers/memory.handlers.ts`. - Export `./kb-update-pipeline.feature` resolves through `./src/kb-update-pipeline.feature.ts`. - The package publishes 14 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.knowledge-canon Description: Knowledge example – Product Canon space (blueprint + tenant config + source sample + runtime helper). Path: packages/examples/knowledge-canon URL: /llms/example.knowledge-canon # @contractspec/example.knowledge-canon Website: https://contractspec.io **Knowledge example – Product Canon space (blueprint + tenant config + source sample + runtime helper).** ## What This Demonstrates - Canonical `knowledge-space` export via `ProductCanonKnowledgeSpace`. - Lightweight `app-config` example via `defineAppConfig(...)`. - Multi-tenant configuration for knowledge bases. - Source sample for content ingestion. - Agent helper for knowledge retrieval. - Minimal contract-only example pattern. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/knowledge-canon`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.knowledge-canon` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/agent.ts` is part of the package's public or composition surface. - `src/blueprint.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/knowledge-canon.feature.ts` defines a feature entrypoint. - `src/product-canon.space.ts` defines the exported knowledge-space spec. - `src/source.sample.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./agent` resolves through `./src/agent.ts`. - Export `./blueprint` resolves through `./src/blueprint.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/knowledge-canon.docblock` resolves through `./src/docs/knowledge-canon.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./knowledge-canon.feature` resolves through `./src/knowledge-canon.feature.ts`. - Export `./product-canon.space` resolves through `./src/product-canon.space.ts`. - Export `./source.sample` resolves through `./src/source.sample.ts`. - Export `./tenant` resolves through `./src/tenant.ts`. - The package publishes 9 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.learning-journey-ambient-coach Description: Ambient coach learning journey example with contextual tips and follow-up actions. Path: packages/examples/learning-journey-ambient-coach URL: /llms/example.learning-journey-ambient-coach # @contractspec/example.learning-journey-ambient-coach Website: https://contractspec.io **Ambient coach learning journey example with contextual tips and follow-up actions.** ## What This Demonstrates - Ambient coaching track definition using the learning-journey module. - Contextual tip delivery based on user activity. - Follow-up action triggers. - Lightweight track + example pattern. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/learning-journey-ambient-coach`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-ambient-coach` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-ambient-coach.feature.ts` defines a feature entrypoint. - `src/track.test.ts` is part of the package's public or composition surface. - `src/track.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/ambient-coach.docblock` resolves through `./src/docs/ambient-coach.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./learning-journey-ambient-coach.feature` resolves through `./src/learning-journey-ambient-coach.feature.ts`. - Export `./track` resolves through `./src/track.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/module.learning-journey`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.learning-journey-crm-onboarding Description: Learning journey track that onboards users to the CRM pipeline example. Path: packages/examples/learning-journey-crm-onboarding URL: /llms/example.learning-journey-crm-onboarding # @contractspec/example.learning-journey-crm-onboarding Website: https://contractspec.io **Learning journey track that onboards users to the CRM pipeline example.** ## What This Demonstrates - CRM-specific onboarding track with step-by-step guidance. - Feature definition with operations, presentations, and test-specs. - Demo handlers for simulated onboarding flow. - Cross-example dependency (builds on crm-pipeline). - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/examples/learning-journey-crm-onboarding`: - `bun run dev` - `bun run build` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-crm-onboarding` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-crm-onboarding.feature.ts` defines a feature entrypoint. - `src/operations` is part of the package's public or composition surface. - `src/presentations` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/crm-onboarding.docblock` resolves through `./src/docs/crm-onboarding.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers/demo.handlers` resolves through `./src/handlers/demo.handlers.ts`. - Export `./learning-journey-crm-onboarding.feature` resolves through `./src/learning-journey-crm-onboarding.feature.ts`. - Export `./operations` resolves through `./src/operations/index.ts`. - Export `./presentations` resolves through `./src/presentations/index.ts`. - Export `./tests/operations.test-spec` resolves through `./src/tests/operations.test-spec.ts`. - Export `./track` resolves through `./src/track.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/example.crm-pipeline`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/module.learning-journey`, `@contractspec/tool.bun`, ... --- ## @contractspec/example.learning-journey-duo-drills Description: Drill-based learning journey example with SRS, XP, and streak hooks. Path: packages/examples/learning-journey-duo-drills URL: /llms/example.learning-journey-duo-drills # @contractspec/example.learning-journey-duo-drills Website: https://contractspec.io **Drill-based learning journey example with SRS, XP, and streak hooks.** ## What This Demonstrates - Drill-based learning track with SRS scheduling. - XP and streak gamification hooks. - Lightweight track + example pattern. - Integration with the learning-journey module. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/learning-journey-duo-drills`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-duo-drills` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-duo-drills.feature.ts` defines a feature entrypoint. - `src/track.test.ts` is part of the package's public or composition surface. - `src/track.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/duo-drills.docblock` resolves through `./src/docs/duo-drills.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./learning-journey-duo-drills.feature` resolves through `./src/learning-journey-duo-drills.feature.ts`. - Export `./track` resolves through `./src/track.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/module.learning-journey`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.learning-journey-platform-tour Description: Learning journey track covering ContractSpec platform primitives. Path: packages/examples/learning-journey-platform-tour URL: /llms/example.learning-journey-platform-tour # @contractspec/example.learning-journey-platform-tour Website: https://contractspec.io **Learning journey track covering ContractSpec platform primitives.** ## What This Demonstrates - Platform primitives tour with step-by-step guidance. - Feature definition with operations, presentations, and test-specs. - Demo handlers for simulated tour flow. - Interactive exploration of ContractSpec concepts. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/examples/learning-journey-platform-tour`: - `bun run dev` - `bun run build` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-platform-tour` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-platform-tour.feature.ts` defines a feature entrypoint. - `src/operations` is part of the package's public or composition surface. - `src/presentations` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/platform-tour.docblock` resolves through `./src/docs/platform-tour.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers/demo.handlers` resolves through `./src/handlers/demo.handlers.ts`. - Export `./learning-journey-platform-tour.feature` resolves through `./src/learning-journey-platform-tour.feature.ts`. - Export `./operations` resolves through `./src/operations/index.ts`. - Export `./presentations` resolves through `./src/presentations/index.ts`. - Export `./tests/operations.test-spec` resolves through `./src/tests/operations.test-spec.ts`. - Export `./track` resolves through `./src/track.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/module.learning-journey`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.learning-journey-quest-challenges Description: Time-bound quest/challenge learning journey example. Path: packages/examples/learning-journey-quest-challenges URL: /llms/example.learning-journey-quest-challenges # @contractspec/example.learning-journey-quest-challenges Website: https://contractspec.io **Time-bound quest/challenge learning journey example.** ## What This Demonstrates - Quest/challenge track with time-bound objectives. - Completion tracking and deadline enforcement. - Lightweight track + example pattern. - Integration with the learning-journey module. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/learning-journey-quest-challenges`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-quest-challenges` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-quest-challenges.feature.ts` defines a feature entrypoint. - `src/track.test.ts` is part of the package's public or composition surface. - `src/track.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/quest-challenges.docblock` resolves through `./src/docs/quest-challenges.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./learning-journey-quest-challenges.feature` resolves through `./src/learning-journey-quest-challenges.feature.ts`. - Export `./track` resolves through `./src/track.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/module.learning-journey`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.learning-journey-registry Description: Registry that aggregates learning journey example tracks. Path: packages/examples/learning-journey-registry URL: /llms/example.learning-journey-registry # @contractspec/example.learning-journey-registry Website: https://contractspec.io **Registry that aggregates learning journey example tracks.** ## What This Demonstrates - Track aggregation and discovery via a central registry. - Feature definition pattern (`learning-journey-registry.feature`). - Progress store for cross-track state. - API and API-types separation for typed endpoints. - Presentation layer with LearningMiniApp UI. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/learning-journey-registry`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-registry` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/api-types.ts` is part of the package's public or composition surface. - `src/api.test.ts` is part of the package's public or composition surface. - `src/api.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-registry.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./api` resolves through `./src/api.ts`. - Export `./api-types` resolves through `./src/api-types.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/learning-journey-registry.docblock` resolves through `./src/docs/learning-journey-registry.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./learning-journey-registry.feature` resolves through `./src/learning-journey-registry.feature.ts`. - Export `./presentations` resolves through `./src/presentations/index.ts`. - Export `./progress-store` resolves through `./src/progress-store.ts`. - Export `./tracks` resolves through `./src/tracks.ts`. - The package publishes 12 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/example.learning-journey-ambient-coach`, `@contractspec/example.learning-journey-crm-onboarding`, `@contractspec/example.learning-journey-duo-drills`, `@contractspec/example.learning-journey-platform-tour`, `@contractspec/example.learning-journey-quest-challenges`, ... --- ## @contractspec/example.learning-journey-studio-onboarding Description: Learning journey track for first 30 minutes in ContractSpec Studio. Path: packages/examples/learning-journey-studio-onboarding URL: /llms/example.learning-journey-studio-onboarding # @contractspec/example.learning-journey-studio-onboarding Website: https://contractspec.io **Learning journey track for first 30 minutes in ContractSpec Studio.** ## What This Demonstrates - Studio onboarding track with time-boxed steps. - Feature definition with operations, presentations, and test-specs. - Demo handlers for simulated onboarding flow. - First-run experience pattern for new users. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/examples/learning-journey-studio-onboarding`: - `bun run dev` - `bun run build` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-studio-onboarding` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-studio-onboarding.feature.ts` defines a feature entrypoint. - `src/operations` is part of the package's public or composition surface. - `src/presentations` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/studio-onboarding.docblock` resolves through `./src/docs/studio-onboarding.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers/demo.handlers` resolves through `./src/handlers/demo.handlers.ts`. - Export `./learning-journey-studio-onboarding.feature` resolves through `./src/learning-journey-studio-onboarding.feature.ts`. - Export `./operations` resolves through `./src/operations/index.ts`. - Export `./presentations` resolves through `./src/presentations/index.ts`. - Export `./tests/operations.test-spec` resolves through `./src/tests/operations.test-spec.ts`. - Export `./track` resolves through `./src/track.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/module.learning-journey`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.learning-journey-ui-coaching Description: Contextual coaching UI with tip cards and engagement tracking. Path: packages/examples/learning-journey-ui-coaching URL: /llms/example.learning-journey-ui-coaching # @contractspec/example.learning-journey-ui-coaching Website: https://contractspec.io **Contextual coaching UI with tip cards and engagement tracking.** ## What This Demonstrates - CoachingMiniApp as a self-contained React application. - TipCard, TipFeed, and EngagementMeter components. - Multi-view layout (Overview, Progress, Steps, Timeline). - Integration with ambient-coach and crm-onboarding tracks. - Design system and UI kit usage patterns. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/learning-journey-ui-coaching`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-ui-coaching` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/CoachingMiniApp.tsx` is part of the package's public or composition surface. - `src/components/` contains reusable UI components and view composition. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-ui-coaching.feature.ts` defines a feature entrypoint. - `src/views/` contains view-level composition. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./CoachingMiniApp` resolves through `./src/CoachingMiniApp.tsx`. - Export `./components` resolves through `./src/components/index.ts`. - Export `./components/EngagementMeter` resolves through `./src/components/EngagementMeter.tsx`. - Export `./components/TipCard` resolves through `./src/components/TipCard.tsx`. - Export `./components/TipFeed` resolves through `./src/components/TipFeed.tsx`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/learning-journey-ui-coaching.docblock` resolves through `./src/docs/learning-journey-ui-coaching.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./learning-journey-ui-coaching.feature` resolves through `./src/learning-journey-ui-coaching.feature.ts`. - The package publishes 15 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/example.learning-journey-ambient-coach`, `@contractspec/example.learning-journey-crm-onboarding`, `@contractspec/example.learning-journey-ui-shared`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, ... --- ## @contractspec/example.learning-journey-ui-gamified Description: Duolingo-style gamified learning UI for drills and quests. Path: packages/examples/learning-journey-ui-gamified URL: /llms/example.learning-journey-ui-gamified # @contractspec/example.learning-journey-ui-gamified Website: https://contractspec.io **Duolingo-style gamified learning UI for drills and quests.** ## What This Demonstrates - GamifiedMiniApp as a self-contained React application. - FlashCard, DayCalendar, and MasteryRing components. - Multi-view layout (Overview, Progress, Steps, Timeline). - Integration with duo-drills and quest-challenges tracks. - Design system and UI kit usage patterns. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/learning-journey-ui-gamified`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-ui-gamified` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/components/` contains reusable UI components and view composition. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/GamifiedMiniApp.tsx` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-ui-gamified.feature.ts` defines a feature entrypoint. - `src/views/` contains view-level composition. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./components` resolves through `./src/components/index.ts`. - Export `./components/DayCalendar` resolves through `./src/components/DayCalendar.tsx`. - Export `./components/FlashCard` resolves through `./src/components/FlashCard.tsx`. - Export `./components/MasteryRing` resolves through `./src/components/MasteryRing.tsx`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/learning-journey-ui-gamified.docblock` resolves through `./src/docs/learning-journey-ui-gamified.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./GamifiedMiniApp` resolves through `./src/GamifiedMiniApp.tsx`. - Export `./learning-journey-ui-gamified.feature` resolves through `./src/learning-journey-ui-gamified.feature.ts`. - The package publishes 15 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/example.learning-journey-duo-drills`, `@contractspec/example.learning-journey-quest-challenges`, `@contractspec/example.learning-journey-ui-shared`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, ... --- ## @contractspec/example.learning-journey-ui-onboarding Description: Developer onboarding UI with checklists and journey maps. Path: packages/examples/learning-journey-ui-onboarding URL: /llms/example.learning-journey-ui-onboarding # @contractspec/example.learning-journey-ui-onboarding Website: https://contractspec.io **Developer onboarding UI with checklists and journey maps.** ## What This Demonstrates - React-based onboarding mini-app with checklist and journey map components. - Multi-view layout (Overview, Progress, Steps, Timeline). - Shared UI component reuse across learning journey examples. - DocBlock-driven documentation pattern. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/learning-journey-ui-onboarding`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-ui-onboarding` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/components/` contains reusable UI components and view composition. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-ui-onboarding.feature.ts` defines a feature entrypoint. - `src/OnboardingMiniApp.tsx` is part of the package's public or composition surface. - `src/views/` contains view-level composition. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./components` resolves through `./src/components/index.ts`. - Export `./components/CodeSnippet` resolves through `./src/components/CodeSnippet.tsx`. - Export `./components/JourneyMap` resolves through `./src/components/JourneyMap.tsx`. - Export `./components/StepChecklist` resolves through `./src/components/StepChecklist.tsx`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/learning-journey-ui-onboarding.docblock` resolves through `./src/docs/learning-journey-ui-onboarding.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./learning-journey-ui-onboarding.feature` resolves through `./src/learning-journey-ui-onboarding.feature.ts`. - Export `./OnboardingMiniApp` resolves through `./src/OnboardingMiniApp.tsx`. - The package publishes 15 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/example.learning-journey-platform-tour`, `@contractspec/example.learning-journey-studio-onboarding`, `@contractspec/example.learning-journey-ui-shared`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, ... --- ## @contractspec/example.learning-journey-ui-shared Description: Shared UI components and hooks for learning journey mini-apps. Path: packages/examples/learning-journey-ui-shared URL: /llms/example.learning-journey-ui-shared # @contractspec/example.learning-journey-ui-shared Website: https://contractspec.io **Shared UI components and hooks for learning journey mini-apps.** ## What This Demonstrates - Reusable gamification components (XpBar, StreakCounter, BadgeDisplay, ViewTabs). - Custom hook pattern (`useLearningProgress`) for shared state. - Shared types for cross-mini-app consistency. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/learning-journey-ui-shared`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-journey-ui-shared` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/components/` contains reusable UI components and view composition. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/hooks/` contains custom hooks for host applications. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-journey-ui-shared.feature.ts` defines a feature entrypoint. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./components` resolves through `./src/components/index.ts`. - Export `./components/BadgeDisplay` resolves through `./src/components/BadgeDisplay.tsx`. - Export `./components/StreakCounter` resolves through `./src/components/StreakCounter.tsx`. - Export `./components/ViewTabs` resolves through `./src/components/ViewTabs.tsx`. - Export `./components/XpBar` resolves through `./src/components/XpBar.tsx`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/learning-journey-ui-shared.docblock` resolves through `./src/docs/learning-journey-ui-shared.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./hooks` resolves through `./src/hooks/index.ts`. - The package publishes 13 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.ui-kit-web`, `@contractspec/module.learning-journey`, `@contractspec/tool.bun`, ... --- ## @contractspec/example.learning-patterns Description: Example: drills + ambient coach + quests learning patterns, powered by Learning Journey (event-driven, deterministic). Path: packages/examples/learning-patterns URL: /llms/example.learning-patterns # @contractspec/example.learning-patterns Website: https://contractspec.io **Example: drills + ambient coach + quests learning patterns, powered by Learning Journey (event-driven, deterministic).** ## What This Demonstrates - Three distinct learning track patterns: drills, ambient-coach, quests. - Event-driven track progression. - Deterministic state transitions via the Learning Journey module. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/learning-patterns`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.learning-patterns` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/events.ts` is package-level event definitions. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/learning-patterns.feature.ts` defines a feature entrypoint. - `src/learning-patterns.test.ts` is part of the package's public or composition surface. - `src/tracks` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/learning-patterns.docblock` resolves through `./src/docs/learning-patterns.docblock.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./learning-patterns.feature` resolves through `./src/learning-patterns.feature.ts`. - Export `./tracks` resolves through `./src/tracks/index.ts`. - Export `./tracks/ambient-coach` resolves through `./src/tracks/ambient-coach.ts`. - Export `./tracks/drills` resolves through `./src/tracks/drills.ts`. - Export `./tracks/quests` resolves through `./src/tracks/quests.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/module.learning-journey`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.lifecycle-cli Description: Lifecycle CLI demo (example): run lifecycle assessment without an HTTP server. Path: packages/examples/lifecycle-cli URL: /llms/example.lifecycle-cli # @contractspec/example.lifecycle-cli Website: https://contractspec.io **Lifecycle CLI demo (example): run lifecycle assessment without an HTTP server.** ## What This Demonstrates - Headless lifecycle assessment execution via CLI. - Bundle consumption pattern (lifecycle-managed). - Logger integration for CLI output. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/lifecycle-cli`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.lifecycle-cli` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/demo.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/lifecycle-cli.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./demo` resolves through `./src/demo.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/lifecycle-cli.docblock` resolves through `./src/docs/lifecycle-cli.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./lifecycle-cli.feature` resolves through `./src/lifecycle-cli.feature.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/bundle.lifecycle-managed`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.lifecycle`, `@contractspec/lib.logger`, `@contractspec/tool.bun`, ... --- ## @contractspec/example.lifecycle-dashboard Description: Lifecycle dashboard example (snippet): how to call lifecycle-managed APIs and render a status card. Path: packages/examples/lifecycle-dashboard URL: /llms/example.lifecycle-dashboard # @contractspec/example.lifecycle-dashboard Website: https://contractspec.io **Lifecycle dashboard example (snippet): how to call lifecycle-managed APIs and render a status card.** ## What This Demonstrates - Lifecycle API consumption pattern. - Status card rendering snippet. - Minimal dependency footprint for quick integration. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/lifecycle-dashboard`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.lifecycle-dashboard` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/lifecycle-dashboard.feature.ts` defines a feature entrypoint. - `src/snippets` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/lifecycle-dashboard.docblock` resolves through `./src/docs/lifecycle-dashboard.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./lifecycle-dashboard.feature` resolves through `./src/lifecycle-dashboard.feature.ts`. - Export `./snippets/page` resolves through `./src/snippets/page.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.locale-jurisdiction-gate Description: Example: enforce locale + jurisdiction + kbSnapshotId + allowed scope for assistant calls (fail-closed). Path: packages/examples/locale-jurisdiction-gate URL: /llms/example.locale-jurisdiction-gate # @contractspec/example.locale-jurisdiction-gate Website: https://contractspec.io **Example: enforce locale + jurisdiction + kbSnapshotId + allowed scope for assistant calls (fail-closed).** ## What This Demonstrates - Canonical `policy` export via `AssistantGatePolicy`. - Canonical `form` export via `AssistantContextForm`. - Canonical `translation` exports for `en-US`, `en-GB`, and `fr-FR`. - Fail-closed policy guard pattern for AI assistant calls. - Entity models for locale/jurisdiction gating. - Event-driven policy enforcement. - Handler and operation separation with typed operations. - Feature definition pattern. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/locale-jurisdiction-gate`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.locale-jurisdiction-gate` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/example.ts` is the runnable example entrypoint. - `src/forms/` contains the exported assistant context form spec. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/locale-jurisdiction-gate.feature.ts` defines a feature entrypoint. - `src/translations/` contains the exported locale catalogs. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/locale-jurisdiction-gate.docblock` resolves through `./src/docs/locale-jurisdiction-gate.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./entities/models` resolves through `./src/entities/models.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./forms` resolves through `./src/forms/index.ts`. - Export `./forms/assistant-context.form` resolves through `./src/forms/assistant-context.form.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - Export `./handlers/demo.handlers` resolves through `./src/handlers/demo.handlers.ts`. - Export `./locale-jurisdiction-gate.feature` resolves through `./src/locale-jurisdiction-gate.feature.ts`. - Export `./policy/assistant-gate.policy` resolves through `./src/policy/assistant-gate.policy.ts`. - Export `./translations` resolves through `./src/translations/index.ts`. - Export `./translations/assistant-gate.en-GB.translation` resolves through `./src/translations/assistant-gate.en-GB.translation.ts`. - Export `./translations/assistant-gate.en-US.translation` resolves through `./src/translations/assistant-gate.en-US.translation.ts`. - Export `./translations/assistant-gate.fr-FR.translation` resolves through `./src/translations/assistant-gate.fr-FR.translation.ts`. - The package publishes 21 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.marketplace Description: Marketplace example with orders, payouts, and reviews for ContractSpec Path: packages/examples/marketplace URL: /llms/example.marketplace # @contractspec/example.marketplace Website: https://contractspec.io **Marketplace example with orders, payouts, and reviews for ContractSpec.** ## What This Demonstrates - Multi-entity domain modeling (order, payout, product, review, store). - Per-entity schema/enum/event/operations/presentation pattern. - Capability and feature definition patterns. - React UI with hooks, renderers, and dashboard component. - Contract-backed visualizations for order status, category value comparison, and recent order activity. - Seeder pattern for demo data. - Test-spec for operations validation. ## Running Locally From `packages/examples/marketplace`: - `bun run dev` - `bun run build` - `bun run typecheck` ## Usage Use `@contractspec/example.marketplace` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/marketplace.capability.ts` defines a capability surface. - `src/marketplace.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/marketplace.docblock` resolves through `./src/docs/marketplace.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./entities/order` resolves through `./src/entities/order.ts`. - Export `./entities/payout` resolves through `./src/entities/payout.ts`. - Export `./entities/product` resolves through `./src/entities/product.ts`. - Export `./entities/review` resolves through `./src/entities/review.ts`. - Export `./entities/store` resolves through `./src/entities/store.ts`. - Export `./example` resolves through `./src/example.ts`. - The package publishes 52 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.example-shared-ui`, `@contractspec/lib.runtime-sandbox`, `@contractspec/lib.schema`, ... --- ## @contractspec/example.meeting-recorder-providers Description: Meeting recorder provider example: list meetings, transcripts, and webhooks. Path: packages/examples/meeting-recorder-providers URL: /llms/example.meeting-recorder-providers # @contractspec/example.meeting-recorder-providers Website: https://contractspec.io **Meeting recorder provider example: list meetings, transcripts, and webhooks.** ## What This Demonstrates - Provider integration pattern with connection samples. - Handler-per-action pattern (create-provider, get-transcript, list-meetings, webhook-handler). - Webhook handler for external event ingestion. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/meeting-recorder-providers`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.meeting-recorder-providers` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/connection.sample.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/meeting-recorder-providers.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./connection.sample` resolves through `./src/connection.sample.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/meeting-recorder-providers.docblock` resolves through `./src/docs/meeting-recorder-providers.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers/create-provider` resolves through `./src/handlers/create-provider.ts`. - Export `./handlers/get-transcript` resolves through `./src/handlers/get-transcript.ts`. - Export `./handlers/list-meetings` resolves through `./src/handlers/list-meetings.ts`. - Export `./handlers/webhook-handler` resolves through `./src/handlers/webhook-handler.ts`. - Export `./meeting-recorder-providers.feature` resolves through `./src/meeting-recorder-providers.feature.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/integration.providers-impls`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.messaging-agent-actions Description: Safe messaging agent actions example with fixed intents, allowlisted actions, workflow dispatch, and deterministic replies. Path: packages/examples/messaging-agent-actions URL: /llms/example.messaging-agent-actions # @contractspec/example.messaging-agent-actions Safe messaging agent actions example with fixed intents, allowlisted action execution, workflow dispatch, and deterministic confirmation replies. ## What This Demonstrates - Inbound message normalization for Slack, WhatsApp, Telegram, or any messaging bridge. - Fixed intent parsing: `status`, `run action`, and `dispatch workflow`. - Allowlisted action and workflow routing instead of arbitrary tool execution. - Replayable meetup proof for the canonical status -> action -> workflow walkthrough. ## Running Locally From `packages/examples/messaging-agent-actions`: - `bun run build` - `bun run test` - `bun run typecheck` - `bun run proof` - `bun run preflight` ## Usage Use this package when you need a conservative messaging demo that proves agent actions can stay safe, typed, and reviewable even when messages come from live provider webhooks. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./contracts` resolves through `./src/contracts/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - Export `./messaging-agent-actions.feature` resolves through `./src/messaging-agent-actions.feature.ts`. - Export `./proof/*` resolves through `./src/proof/*.ts`. ## Local Commands - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run typecheck` — tsc --noEmit - `bun run proof` — bun ../../../scripts/generate-messaging-agent-actions-meetup-proof.ts - `bun run preflight` — bun run build && bun run typecheck && bun run test && bun run proof --- ## @contractspec/example.minimal Description: (none) Path: packages/examples/minimal URL: /llms/example.minimal # @contractspec/example.minimal **Minimal ContractSpec example showing the simplest possible contract definition and build.** ## What This Demonstrates - Bare-minimum contract definition (user contract). - `contractspec build` and `contractspec validate` CLI usage. - Maintained example package included in the ContractSpec example registry. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/examples/minimal`: - `bun run build` - `bun run test` - `bun run typecheck` - `bun run smoke` - `bun run preflight` ## Usage Use `@contractspec/example.minimal` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/minimal.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/minimal.docblock` resolves through `./src/docs/minimal.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./minimal.feature` resolves through `./src/minimal.feature.ts`. - Export `./contracts/user` resolves through `./src/contracts/user.ts`. ## Local Commands - `bun run build` — bun ../../apps/cli-contractspec/src/cli.ts build src/contracts/user.ts - `bun run validate` — bun ../../apps/cli-contractspec/src/cli.ts validate src/contracts/user.ts - `bun run typecheck` — tsc --noEmit - `bun run test` — bun test - `bun run smoke` — bun test src/example.smoke.test.ts - `bun run preflight` — bun run build && bun run typecheck && bun run test && bun run validate && bun run smoke ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Stability. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`. --- ## @contractspec/example.openbanking-powens Description: OpenBanking Powens example: OAuth callback + webhook handler patterns (provider + workflows). Path: packages/examples/openbanking-powens URL: /llms/example.openbanking-powens # @contractspec/example.openbanking-powens Website: https://contractspec.io **OpenBanking Powens example: OAuth callback + webhook handler patterns (provider + workflows).** ## What This Demonstrates - OAuth callback handler pattern for open banking. - Webhook handler for asynchronous bank event ingestion. - Canonical `job` export via `PowensSyncDispatchJob`. - Provider integration via contracts-integrations. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/examples/openbanking-powens`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.openbanking-powens` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/jobs/` contains the exported Powens dispatch job spec. - `src/openbanking-powens.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/openbanking-powens.docblock` resolves through `./src/docs/openbanking-powens.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers/oauth-callback` resolves through `./src/handlers/oauth-callback.ts`. - Export `./handlers/webhook-handler` resolves through `./src/handlers/webhook-handler.ts`. - Export `./jobs` resolves through `./src/jobs/index.ts`. - Export `./jobs/powens-sync-dispatch.job` resolves through `./src/jobs/powens-sync-dispatch.job.ts`. - Export `./openbanking-powens.feature` resolves through `./src/openbanking-powens.feature.ts`. - The package publishes 8 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/integration.providers-impls`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.opencode-cli Description: (none) Path: packages/examples/opencode-cli URL: /llms/example.opencode-cli # @contractspec/example.opencode-cli **OpenCode CLI example showing agent-mode contract building and validation.** ## What This Demonstrates - Agent-mode (`--agent-mode opencode`) contract compilation. - Implementation checking via `--check-implementation`. - Maintained example package included in the ContractSpec example registry. - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/examples/opencode-cli`: - `bun run build` - `bun run test` - `bun run typecheck` - `bun run smoke` - `bun run preflight` ## Usage Use `@contractspec/example.opencode-cli` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/contracts/` contains contract specs, operations, entities, and registry exports. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/opencode-cli.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./contracts/opencode` resolves through `./src/contracts/opencode.contracts.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/opencode-cli.docblock` resolves through `./src/docs/opencode-cli.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./opencode-cli.feature` resolves through `./src/opencode-cli.feature.ts`. ## Local Commands - `bun run build` — bun ../../apps/cli-contractspec/src/cli.ts build src/contracts/opencode.contracts.ts --agent-mode opencode - `bun run validate` — bun ../../apps/cli-contractspec/src/cli.ts validate src/contracts/opencode.contracts.ts --check-implementation --agent-mode opencode - `bun run typecheck` — tsc --noEmit - `bun run test` — bun test - `bun run smoke` — bun test src/example.smoke.test.ts - `bun run preflight` — bun run build && bun run typecheck && bun run test && bun run validate && bun run smoke ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Stability. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`. --- ## @contractspec/example.personalization Description: Personalization examples: behavior tracking, overlay customization, workflow extension. Path: packages/examples/personalization URL: /llms/example.personalization # @contractspec/example.personalization Website: https://contractspec.io **Personalization examples: behavior tracking, overlay customization, workflow extension.** ## What This Demonstrates - Behavior tracking integration pattern. - Canonical `experiment` export via `PersonalizationExperiment`. - Overlay customization via overlay-engine. - Canonical `theme` export via `PersonalizationTheme`. - Workflow extension via workflow-composer. - Multi-lib composition in a single example. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/personalization`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.personalization` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/behavior-tracking.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/overlay-customization.ts` is part of the package's public or composition surface. - `src/personalization.experiment.ts` defines the exported experiment spec. - `src/personalization.feature.ts` defines a feature entrypoint. - `src/personalization.theme.ts` defines the exported theme spec. - `src/workflow-extension.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./behavior-tracking` resolves through `./src/behavior-tracking.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/personalization.docblock` resolves through `./src/docs/personalization.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./overlay-customization` resolves through `./src/overlay-customization.ts`. - Export `./personalization.experiment` resolves through `./src/personalization.experiment.ts`. - Export `./personalization.feature` resolves through `./src/personalization.feature.ts`. - Export `./personalization.theme` resolves through `./src/personalization.theme.ts`. - Export `./workflow-extension` resolves through `./src/workflow-extension.ts`. - The package publishes 9 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.logger`, `@contractspec/lib.overlay-engine`, `@contractspec/lib.personalization`, `@contractspec/lib.workflow-composer`, ... --- ## @contractspec/example.pocket-family-office Description: Pocket Family Office example - personal finance automation with open banking Path: packages/examples/pocket-family-office URL: /llms/example.pocket-family-office # @contractspec/example.pocket-family-office Website: https://contractspec.io **Pocket Family Office example - personal finance automation with open banking.** ## What This Demonstrates - Workflow-driven open banking integration (sync accounts, transactions, balances). - Financial summary and overview generation workflows. - Document processing and email thread ingestion. - Capability and feature definition patterns. - Canonical `telemetry` export via `pocketFamilyOfficeTelemetry`. - Sample tenant and connection configuration. ## Running Locally From `packages/examples/pocket-family-office`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.pocket-family-office` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/blueprint.ts` is part of the package's public or composition surface. - `src/connections` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/knowledge` is part of the package's public or composition surface. - `src/operations` is part of the package's public or composition surface. - `src/telemetry.ts` defines the exported telemetry spec. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./blueprint` resolves through `./src/blueprint.ts`. - Export `./connections/samples` resolves through `./src/connections/samples.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/pocket-family-office.docblock` resolves through `./src/docs/pocket-family-office.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./knowledge/sources.sample` resolves through `./src/knowledge/sources.sample.ts`. - Export `./operations` resolves through `./src/operations/index.ts`. - Export `./pocket-family-office.capability` resolves through `./src/pocket-family-office.capability.ts`. - Export `./pocket-family-office.feature` resolves through `./src/pocket-family-office.feature.ts`. - Export `./telemetry` resolves through `./src/telemetry.ts`. - The package publishes 20 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — bun rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. - Resolve lint/test regressions after voice capability updates. - Major change to content generation. ## Notes - Works alongside `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.knowledge`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, ... --- ## @contractspec/example.policy-safe-knowledge-assistant Description: All-in-one template example: policy-safe knowledge assistant with locale/jurisdiction gating, versioned KB snapshots, HITL update pipeline, and learning hub. Path: packages/examples/policy-safe-knowledge-assistant URL: /llms/example.policy-safe-knowledge-assistant # @contractspec/example.policy-safe-knowledge-assistant Website: https://contractspec.io **All-in-one template example: policy-safe knowledge assistant with locale/jurisdiction gating, versioned KB snapshots, HITL update pipeline, and learning hub.** ## What This Demonstrates - Composition of multiple example packages into a full-stack assistant. - Orchestrator pattern (`buildAnswer`) for policy-gated responses. - React dashboard with hooks and UI components. - Seed data and fixture patterns. - Feature definition aggregating sub-features. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/policy-safe-knowledge-assistant`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.policy-safe-knowledge-assistant` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/integration.test.ts` is part of the package's public or composition surface. - `src/orchestrator` is part of the package's public or composition surface. - `src/policy-safe-knowledge-assistant.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/policy-safe-knowledge-assistant.docblock` resolves through `./src/docs/policy-safe-knowledge-assistant.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - Export `./handlers/policy-safe-knowledge-assistant.handlers` resolves through `./src/handlers/policy-safe-knowledge-assistant.handlers.ts`. - Export `./orchestrator/buildAnswer` resolves through `./src/orchestrator/buildAnswer.ts`. - Export `./policy-safe-knowledge-assistant.feature` resolves through `./src/policy-safe-knowledge-assistant.feature.ts`. - Export `./seed` resolves through `./src/seed/index.ts`. - Export `./seed/fixtures` resolves through `./src/seed/fixtures.ts`. - The package publishes 14 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/example.kb-update-pipeline`, `@contractspec/example.learning-patterns`, `@contractspec/example.locale-jurisdiction-gate`, `@contractspec/example.versioned-knowledge-base`, `@contractspec/lib.contracts-spec`, ... --- ## @contractspec/example.product-intent Description: Product intent example: evidence ingestion and prompt-ready outputs. Path: packages/examples/product-intent URL: /llms/example.product-intent # @contractspec/example.product-intent Website: https://contractspec.io **Product intent example: evidence ingestion and prompt-ready outputs.** ## What This Demonstrates - Canonical `product-intent` export via `ProductIntentDiscoverySpec`. - Evidence loading and ingestion pipeline. - PostHog signal extraction for product analytics. - Action synchronization across tools. - Script-based execution pattern. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/product-intent`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.product-intent` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/load-evidence.test.ts` is part of the package's public or composition surface. - `src/load-evidence.ts` is part of the package's public or composition surface. - `src/posthog-signals.ts` is part of the package's public or composition surface. - `src/product-intent.discovery.ts` defines the exported product-intent spec. - `src/product-intent.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/product-intent.docblock` resolves through `./src/docs/product-intent.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./load-evidence` resolves through `./src/load-evidence.ts`. - Export `./posthog-signals` resolves through `./src/posthog-signals.ts`. - Export `./product-intent.discovery` resolves through `./src/product-intent.discovery.ts`. - Export `./product-intent.feature` resolves through `./src/product-intent.feature.ts`. - Export `./script` resolves through `./src/script.ts`. - Export `./sync-actions` resolves through `./src/sync-actions.ts`. - The package publishes 9 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Stability. - Missing contract layers. ## Notes - Works alongside `@contractspec/integration.providers-impls`, `@contractspec/lib.ai-agent`, `@contractspec/lib.analytics`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, ... --- ## @contractspec/example.project-management-sync Description: Project management sync example: Linear, Jira, and Notion work item creation. Path: packages/examples/project-management-sync URL: /llms/example.project-management-sync # @contractspec/example.project-management-sync Website: https://contractspec.io **Project management sync example: Linear, Jira, and Notion work item creation.** ## What This Demonstrates - Multi-provider sync pattern (Linear, Jira, Notion). - Work item creation from contract definitions. - Run script for one-shot execution. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/project-management-sync`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.project-management-sync` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/project-management-sync.feature.ts` defines a feature entrypoint. - `src/run.ts` is part of the package's public or composition surface. - `src/sync.ts` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/project-management-sync.docblock` resolves through `./src/docs/project-management-sync.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./project-management-sync.feature` resolves through `./src/project-management-sync.feature.ts`. - Export `./run` resolves through `./src/run.ts`. - Export `./sync` resolves through `./src/sync.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/integration.providers-impls`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.saas-boilerplate Description: SaaS Boilerplate - Users, Orgs, Projects, Billing, Settings Path: packages/examples/saas-boilerplate URL: /llms/example.saas-boilerplate # @contractspec/example.saas-boilerplate Website: https://contractspec.io **SaaS Boilerplate - Users, Orgs, Projects, Billing, Settings.** ## What This Demonstrates - Multi-domain SaaS architecture (billing, project, settings, dashboard). - Per-domain entity/enum/event/handler/operations/presentation/schema pattern. - React UI with hooks, modals, overlays, renderers, and dashboard. - Contract-backed visualizations for portfolio status, tier mix, usage, and recent project activity. - Feature definition, seeders, and test-spec patterns. - RBAC, audit trail, and notification module integration. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/saas-boilerplate`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.saas-boilerplate` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/billing` is part of the package's public or composition surface. - `src/dashboard` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/presentations` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./billing` resolves through `./src/billing/index.ts`. - Export `./billing/billing.entity` resolves through `./src/billing/billing.entity.ts`. - Export `./billing/billing.enum` resolves through `./src/billing/billing.enum.ts`. - Export `./billing/billing.event` resolves through `./src/billing/billing.event.ts`. - Export `./billing/billing.handler` resolves through `./src/billing/billing.handler.ts`. - Export `./billing/billing.operations` resolves through `./src/billing/billing.operations.ts`. - Export `./billing/billing.presentation` resolves through `./src/billing/billing.presentation.ts`. - Export `./billing/billing.schema` resolves through `./src/billing/billing.schema.ts`. - Export `./dashboard` resolves through `./src/dashboard/index.ts`. - The package publishes 48 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.example-shared-ui`, `@contractspec/lib.identity-rbac`, `@contractspec/lib.jobs`, ... --- ## @contractspec/example.service-business-os Description: Service Business OS example (clients, quotes, jobs, invoices) for ContractSpec Path: packages/examples/service-business-os URL: /llms/example.service-business-os # @contractspec/example.service-business-os Website: https://contractspec.io **Service Business OS example (clients, quotes, jobs, invoices) for ContractSpec.** ## What This Demonstrates - Multi-entity domain modeling (client, quote, job, invoice, payment). - Per-entity schema and operations pattern. - Capability and feature definition patterns. - Presentation layer and event-driven architecture. - Handler aggregation. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/service-business-os`: - `bun run dev` - `bun run build` - `bun run typecheck` ## Usage Use `@contractspec/example.service-business-os` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/client` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./client` resolves through `./src/client/index.ts`. - Export `./client/client.operations` resolves through `./src/client/client.operations.ts`. - Export `./client/client.schema` resolves through `./src/client/client.schema.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/service-business-os.docblock` resolves through `./src/docs/service-business-os.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - The package publishes 26 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.team-hub Description: Team Hub example with spaces, tasks, rituals, and announcements Path: packages/examples/team-hub URL: /llms/example.team-hub # @contractspec/example.team-hub Website: https://contractspec.io **Team Hub example with spaces, tasks, rituals, and announcements.** ## What This Demonstrates - Multi-entity team collaboration domain (space, task, ritual, announcement). - Per-entity schema and operations pattern. - Capability and feature definition patterns. - Presentation layer with team-hub presentation. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/examples/team-hub`: - `bun run dev` - `bun run build` - `bun run typecheck` ## Usage Use `@contractspec/example.team-hub` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/announcement` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./announcement` resolves through `./src/announcement/index.ts`. - Export `./announcement/announcement.operations` resolves through `./src/announcement/announcement.operations.ts`. - Export `./announcement/announcement.schema` resolves through `./src/announcement/announcement.schema.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/team-hub.docblock` resolves through `./src/docs/team-hub.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - The package publishes 23 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.versioned-knowledge-base Description: Example: curated, versioned knowledge base with immutable sources, rule versions, and published snapshots. Path: packages/examples/versioned-knowledge-base URL: /llms/example.versioned-knowledge-base # @contractspec/example.versioned-knowledge-base Website: https://contractspec.io **Example: curated, versioned knowledge base with immutable sources, rule versions, and published snapshots.** ## What This Demonstrates - Immutable source and versioned rule management. - Snapshot publishing pattern. - Canonical `migration` export via `KnowledgeSnapshotPublicationMigration`. - Entity models for KB domain. - Memory-based handler implementation. - Feature definition and event-driven architecture. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/versioned-knowledge-base`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.versioned-knowledge-base` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/knowledge-snapshot-publication.migration.ts` defines the exported migration spec. - `src/operations` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/versioned-knowledge-base.docblock` resolves through `./src/docs/versioned-knowledge-base.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./entities/models` resolves through `./src/entities/models.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - Export `./handlers/memory.handlers` resolves through `./src/handlers/memory.handlers.ts`. - Export `./knowledge-snapshot-publication.migration` resolves through `./src/knowledge-snapshot-publication.migration.ts`. - Export `./operations` resolves through `./src/operations/index.ts`. - Export `./operations/kb` resolves through `./src/operations/kb.ts`. - Export `./versioned-knowledge-base.feature` resolves through `./src/versioned-knowledge-base.feature.ts`. - The package publishes 12 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.video-api-showcase Description: Generate API documentation videos from contract spec definitions using the ApiOverview composition. Path: packages/examples/video-api-showcase URL: /llms/example.video-api-showcase # @contractspec/example.video-api-showcase Website: https://contractspec.io **Generate API documentation videos from contract spec definitions using the ApiOverview composition.** ## What This Demonstrates - Video generation pipeline from contract specs. - ApiOverview composition pattern. - Sample spec definitions for video input. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/video-api-showcase`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.video-api-showcase` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/build-api-video.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/index.ts` is the root public barrel and package entrypoint. - `src/sample-specs.ts` is part of the package's public or composition surface. - `src/video-api-showcase.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./build-api-video` resolves through `./src/build-api-video.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/video-api-showcase.docblock` resolves through `./src/docs/video-api-showcase.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./sample-specs` resolves through `./src/sample-specs.ts`. - Export `./video-api-showcase.feature` resolves through `./src/video-api-showcase.feature.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.video-gen`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.video-docs-terminal Description: Generate terminal demo videos from CLI walkthroughs using the TerminalDemo composition and ScriptGenerator. Path: packages/examples/video-docs-terminal URL: /llms/example.video-docs-terminal # @contractspec/example.video-docs-terminal Website: https://contractspec.io **Generate terminal demo videos from CLI walkthroughs using the TerminalDemo composition and ScriptGenerator.** ## What This Demonstrates - Terminal demo video generation pipeline. - Narration generation from CLI walkthroughs. - Sample tutorial definitions for video input. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/video-docs-terminal`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.video-docs-terminal` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/build-tutorial.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/generate-narration.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/sample-tutorials.ts` is part of the package's public or composition surface. - `src/video-docs-terminal.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./build-tutorial` resolves through `./src/build-tutorial.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/video-docs-terminal.docblock` resolves through `./src/docs/video-docs-terminal.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./generate-narration` resolves through `./src/generate-narration.ts`. - Export `./sample-tutorials` resolves through `./src/sample-tutorials.ts`. - Export `./video-docs-terminal.feature` resolves through `./src/video-docs-terminal.feature.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.content-gen`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.video-gen`, `@contractspec/tool.bun`, ... --- ## @contractspec/example.video-marketing-clip Description: Generate short-form marketing videos from content briefs using the video-gen pipeline. Path: packages/examples/video-marketing-clip URL: /llms/example.video-marketing-clip # @contractspec/example.video-marketing-clip Website: https://contractspec.io **Generate short-form marketing videos from content briefs using the video-gen pipeline.** ## What This Demonstrates - Marketing clip generation from content briefs. - Brief definition pattern for video input. - Video-gen pipeline consumption. - `src/docs/` contains docblocks and documentation-facing exports. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/video-marketing-clip`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.video-marketing-clip` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/briefs.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/generate-clip.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/video-marketing-clip.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./briefs` resolves through `./src/briefs.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/video-marketing-clip.docblock` resolves through `./src/docs/video-marketing-clip.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./generate-clip` resolves through `./src/generate-clip.ts`. - Export `./video-marketing-clip.feature` resolves through `./src/video-marketing-clip.feature.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.content-gen`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.video-gen`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.visualization-showcase Description: Focused visualization showcase for ContractSpec primitives and design-system wrappers Path: packages/examples/visualization-showcase URL: /llms/example.visualization-showcase # Visualization Showcase `@contractspec/example.visualization-showcase` is the focused reference package for ContractSpec's visualization layer. It demonstrates: - Contract-owned `VisualizationSpec` primitives - Shared visualization registries and refs - Design-system wrappers like `VisualizationCard`, `VisualizationGrid`, `ComparisonView`, and `TimelineView` - Markdown summaries for non-React surfaces Use this package when you want a lightweight, deterministic reference for the visualization contract model without the heavier domain logic of `analytics-dashboard`. --- ## @contractspec/example.voice-providers Description: Voice provider example: Gradium and Fal text-to-speech integration patterns. Path: packages/examples/voice-providers URL: /llms/example.voice-providers # @contractspec/example.voice-providers Website: https://contractspec.io **Voice provider example: Gradium and Fal text-to-speech integration patterns.** ## What This Demonstrates - TTS provider integration pattern with connection samples. - Handler-per-action pattern (create-provider, list-voices, synthesize). - Run script for one-shot execution. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/docs/` contains docblocks and documentation-facing exports. ## Running Locally From `packages/examples/voice-providers`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.voice-providers` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/connection.sample.ts` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/run.ts` is part of the package's public or composition surface. - `src/voice-providers.feature.ts` defines a feature entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./connection.sample` resolves through `./src/connection.sample.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/voice-providers.docblock` resolves through `./src/docs/voice-providers.docblock.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers/create-provider` resolves through `./src/handlers/create-provider.ts`. - Export `./handlers/list-voices` resolves through `./src/handlers/list-voices.ts`. - Export `./handlers/synthesize` resolves through `./src/handlers/synthesize.ts`. - Export `./run` resolves through `./src/run.ts`. - Export `./voice-providers.feature` resolves through `./src/voice-providers.feature.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. - Major change to content generation. ## Notes - Works alongside `@contractspec/integration.providers-impls`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/example.wealth-snapshot Description: Wealth Snapshot mini-app for accounts, assets, liabilities, and goals Path: packages/examples/wealth-snapshot URL: /llms/example.wealth-snapshot # @contractspec/example.wealth-snapshot Website: https://contractspec.io **Wealth Snapshot mini-app for accounts, assets, liabilities, and goals.** ## What This Demonstrates - Financial entity modeling (accounts, assets, liabilities, goals). - Capability and feature definition patterns. - Presentation layer and event-driven architecture. - RBAC, audit trail, and notification module integration. - `src/docs/` contains docblocks and documentation-facing exports. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. ## Running Locally From `packages/examples/wealth-snapshot`: - `bun run dev` - `bun run build` - `bun run typecheck` ## Usage Use `@contractspec/example.wealth-snapshot` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/events.ts` is package-level event definitions. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/operations` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/wealth-snapshot.docblock` resolves through `./src/docs/wealth-snapshot.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - Export `./events` resolves through `./src/events.ts`. - Export `./example` resolves through `./src/example.ts`. - Export `./handlers` resolves through `./src/handlers/index.ts`. - Export `./operations` resolves through `./src/operations/index.ts`. - Export `./presentations` resolves through `./src/presentations.ts`. - Export `./wealth-snapshot.capability` resolves through `./src/wealth-snapshot.capability.ts`. - The package publishes 11 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.identity-rbac`, `@contractspec/lib.schema`, `@contractspec/module.audit-trail`, `@contractspec/module.notifications`, ... --- ## @contractspec/example.workflow-system Description: Workflow and approval system example for ContractSpec - State machine with role-based transitions Path: packages/examples/workflow-system URL: /llms/example.workflow-system # @contractspec/example.workflow-system Website: https://contractspec.io **Workflow and approval system example for ContractSpec - State machine with role-based transitions.** ## What This Demonstrates - State machine pattern for workflow transitions. - Approval flow with role-based access. - Multi-entity domain (workflow, instance, approval). - Per-entity schema/enum/event/handler/operations pattern. - React UI with WorkflowDashboard, hooks, and renderers. - Contract-backed visualizations for workflow status, throughput, and workload comparison. - Capability and feature definition patterns. - Seeder and test-spec patterns. ## Running Locally From `packages/examples/workflow-system`: - `bun run dev` - `bun run build` - `bun run test` - `bun run typecheck` ## Usage Use `@contractspec/example.workflow-system` as a reference implementation, or import its exported surfaces into a workspace that composes ContractSpec examples and bundles. ## Architecture - `src/approval` is part of the package's public or composition surface. - `src/docs/` contains docblocks and documentation-facing exports. - `src/entities/` contains domain entities and value objects. - `src/example.ts` is the runnable example entrypoint. - `src/handlers/` contains handlers or demo adapters wired to contract surfaces. - `src/index.ts` is the root public barrel and package entrypoint. - `src/instance` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./approval` resolves through `./src/approval/index.ts`. - Export `./approval/approval.enum` resolves through `./src/approval/approval.enum.ts`. - Export `./approval/approval.event` resolves through `./src/approval/approval.event.ts`. - Export `./approval/approval.handler` resolves through `./src/approval/approval.handler.ts`. - Export `./approval/approval.operations` resolves through `./src/approval/approval.operations.ts`. - Export `./approval/approval.schema` resolves through `./src/approval/approval.schema.ts`. - Export `./docs` resolves through `./src/docs/index.ts`. - Export `./docs/workflow-system.docblock` resolves through `./src/docs/workflow-system.docblock.ts`. - Export `./entities` resolves through `./src/entities/index.ts`. - The package publishes 44 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild - `bun run test` — bun test ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Missing contract layers. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.design-system`, `@contractspec/lib.example-shared-ui`, `@contractspec/lib.runtime-sandbox`, `@contractspec/lib.schema`, ... --- ## agentpacks Description: Composable AI agent configuration manager. Pack-based rules, commands, skills, hooks, and MCP sync across OpenCode, Cursor, Claude Code, Codex, Gemini, Copilot, and more. Path: packages/tools/agentpacks URL: /llms/agentpacks # agentpacks Website: https://github.com/lssm-tech/contractspec/tree/main/packages/tools/agentpacks **Composable AI agent configuration manager that merges packs into target-specific tool configuration, rules, hooks, skills, and AGENTS output.** ## What It Provides - Loads, merges, and resolves agent packs into Cursor, Claude Code, Codex, Copilot, Gemini, OpenCode, registry, and AGENTS targets. - Publishes a CLI plus a broad programmatic API for pack loading, sources, targets, importers, and exporters. - Recently expanded around AI-native flows, model guidance, Cursor plugin output, and compatibility hardening. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install agentpacks` or `bun add agentpacks` ## Usage ```bash npx agentpacks --help # or bunx agentpacks --help ``` ## Architecture - `src/cli/` contains command implementations for init, generate, install, publish, search, and pack subcommands. - `src/core/` handles config loading, dependency resolution, pack loading, lockfiles, and feature merging. - `src/features/`, `src.sources/`, `src.targets/`, `src.importers/`, and `src.exporters/` implement the pack pipeline. - `src.utils/` contains credentials, diffing, markdown, registry, and model-helper utilities. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Exports the CLI binary plus API, core, features, targets, sources, importers, exporters, and utility subpaths. - Binary `agentpacks` points to `./dist/index.js`. - Export `.` resolves through `./src/index.ts`. - Export `./api` resolves through `./src/api.ts`. - Export `./cli/export-cmd` resolves through `./src/cli/export-cmd.ts`. - Export `./cli/generate` resolves through `./src/cli/generate.ts`. - Export `./cli/import-cmd` resolves through `./src/cli/import-cmd.ts`. - Export `./cli/info` resolves through `./src/cli/info.ts`. - Export `./cli/init` resolves through `./src/cli/init.ts`. - Export `./cli/install` resolves through `./src/cli/install.ts`. - Export `./cli/login` resolves through `./src/cli/login.ts`. - Export `./cli/models-explain` resolves through `./src/cli/models-explain.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Use the Biome-only lint and formatting workflow in pack guidance and generated targets. - Vnext ai-native. - Add latest models and align defaults. - Harden AgentSkills compatibility in agentpacks. - Add first-class mistral provider support. - Align cursor plugin export and hooks output. ## Notes - Do not modify target output formats without updating the corresponding target writer. - Pack schema changes must stay backward-compatible (see `schema.json`). - Never hard-code model names; use `utils/model-allowlist` and `utils/model-guidance`. --- ## @contractspec/biome-config Description: Biome presets, Grit plugins, and policy manifest for ContractSpec repositories. Path: packages/tools/biome-config URL: /llms/biome-config # @contractspec/biome-config Website: https://contractspec.io **Typed ContractSpec lint-policy package that generates Biome presets, Grit plugins, and AI-facing rule summaries.** ## What It Provides - Acts as the source of truth for repository and consumer Biome policy artifacts. - Publishes generated presets, Grit plugins, and AI summaries alongside the typed manifest and generation helpers. - Requires artifact synchronization whenever the typed policy manifest changes so committed outputs stay aligned. - Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/biome-config` or `bun add @contractspec/biome-config` ## Usage Import the root entrypoint from `@contractspec/biome-config`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/policies.ts` defines the typed policy manifest. - `src/generate.ts` and `src/sync.ts` generate and synchronize derived artifacts. - `src/types.ts` and `src/index.ts` expose the public API for generation and policy consumption. - `presets/`, `plugins/`, and `ai/` contain committed generated artifacts consumed by downstream tools. ## Public Entry Points - Exports the root library API and ships generated presets, Grit plugins, and AI-facing summaries as committed package artifacts. - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run sync:artifacts` — bun src/sync.ts - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — bun run sync:artifacts && contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - The committed `presets/`, `plugins/`, and `ai/` artifacts are intended for downstream scaffolding without code execution. --- ## @contractspec/tool.bun Description: Shared Bun build presets and CLI for ContractSpec packages Path: packages/tools/bun URL: /llms/tool.bun # @contractspec/tool.bun Website: https://contractspec.io **Shared Bun build presets and CLI for ContractSpec packages. Provides the `contractspec-bun-build` binary used by nearly every package's `build`, `dev`, and `prebuild` scripts.** ## What It Provides - **Layer**: tool - **Consumers**: all monorepo packages (via `contractspec-bun-build` in their scripts) ## Installation `npm install @contractspec/tool.bun` or `bun add @contractspec/tool.bun` ## Usage ```bash npx contractspec-bun-build --help # or bunx contractspec-bun-build --help ``` ## Public Entry Points - `contractspec-bun-build` -> `./bin/contractspec-bun-build.mjs` - `.` — `./index.js` ## Local Commands - `bun run test` — bun test - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Add multi platform support to bun build - Use-client within lib surface-runtime ## Notes - Changes here affect every package's build pipeline -- test broadly before merging - Do not remove or rename CLI sub-commands (`transpile`, `types`, `dev`, `prebuild`) without updating all consumers - Keep the package dependency-light; only `glob` as a dev dependency --- ## @contractspec/tool.create-contractspec-plugin Description: CLI tool for creating ContractSpec plugins from templates Path: packages/tools/create-contractspec-plugin URL: /llms/tool.create-contractspec-plugin # @contractspec/tool.create-contractspec-plugin Website: https://contractspec.io **CLI tool for creating ContractSpec plugins from templates.** ## What It Provides - **Layer**: tool. - **Consumers**: plugin authors (via `create-contractspec-plugin` CLI). - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/tool.create-contractspec-plugin` or `bun add @contractspec/tool.create-contractspec-plugin` ## Usage ```bash npx create-contractspec-plugin --help # or bunx create-contractspec-plugin --help ``` ## Architecture - `src/index.ts` is the root public barrel and package entrypoint. - `src/templates` is part of the package's public or composition surface. - `src/utils.ts` is part of the package's public or composition surface. ## Public Entry Points - Binary `create-contractspec-plugin` points to `./dist/index.js`. - Export `.` resolves through `./src/index.ts`. - Export `./templates/example-generator` resolves through `./src/templates/example-generator.ts`. - Export `./utils` resolves through `./src/utils.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Template files live in `templates/` -- keep them in sync with the current plugin contract. - Do not change interactive prompts without updating the corresponding template variables. - Depends on `@contractspec/lib.contracts-spec` and `@contractspec/lib.schema` -- respect their APIs. --- ## @contractspec/tool.docs-generator Description: CLI tool for generating docs artifacts from ContractSpec specs and DocBlocks Path: packages/tools/docs-generator URL: /llms/tool.docs-generator # @contractspec/tool.docs-generator Website: https://contractspec.io **CLI tool for generating docs artifacts from ContractSpec specs and DocBlocks.** ## What It Provides - **Layer**: tool. - **Consumers**: docs pipeline (`bun run docs:generate`), CI. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/tool.docs-generator` or `bun add @contractspec/tool.docs-generator` ## Usage ```bash npx contractspec-docs --help # or bunx contractspec-docs --help ``` ## Architecture - `src/fs.ts` is part of the package's public or composition surface. - `src/generate.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/markdown.test.ts` is part of the package's public or composition surface. - `src/markdown.ts` is part of the package's public or composition surface. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Binary `contractspec-docs` points to `./dist/index.js`. - Export `.` resolves through `./src/index.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run docs:generate` — bun src/index.ts generate --source "../../../generated/docs" --out "../../../packages/bundles/library/src/components/docs/generated" --content-root "../../../generated/docs" - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Output paths are configured via CLI flags -- do not hard-code destination directories. - Depends on `@contractspec/lib.contracts-spec` for spec parsing -- changes there may require updates here. - The `docs:generate` script references relative paths to `generated/docs` and the library bundle; verify paths if the monorepo structure changes. --- ## @contractspec/tool.tsdown Description: Shared tsdown config presets for LSSM monorepo Path: packages/tools/tsdown URL: /llms/tool.tsdown # @contractspec/tool.tsdown Website: https://contractspec.io **Shared tsdown configuration presets for the ContractSpec monorepo. Packages that use tsdown for bundling import this preset to keep build config consistent.** ## What It Provides - **Layer**: tool - **Consumers**: packages using tsdown (typically libs with `tsdown.config.js`) ## Installation `npm install @contractspec/tool.tsdown` or `bun add @contractspec/tool.tsdown` ## Usage Import the root entrypoint from `@contractspec/tool.tsdown`, or use one of the documented subpaths when you want a narrower surface area. ## Public Entry Points - `.` — `./index.js` ## Local Commands - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - PublishConfig not supported by bun - Add examples of integration ## Notes - Changes affect every tsdown consumer's build output -- test downstream packages before merging - Peer-depends on `tsdown ^0.21` -- keep in sync with the workspace catalog version - Keep the preset minimal; package-specific overrides belong in each consumer's `tsdown.config.js` --- ## @contractspec/tool.typescript Description: (none) Path: packages/tools/typescript URL: /llms/tool.typescript # @contractspec/tool.typescript Website: https://contractspec.io **Shared TypeScript configuration presets (base, nextjs, react-library) extended by every package's `tsconfig.json` in the monorepo.** ## What It Provides - **Layer**: tool - **Consumers**: all monorepo packages (via `"extends": "@contractspec/tool.typescript/..."`) ## Installation `npm install @contractspec/tool.typescript` or `bun add @contractspec/tool.typescript` ## Local Commands - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - PublishConfig not supported by bun - Migrate non-app builds to shared Bun toolchain ## Notes - Compiler option changes propagate to every package -- verify with `bun run typecheck` across the repo - Do not weaken strict-mode settings (`strict`, `noUncheckedIndexedAccess`, etc.) - Adding a new preset file requires documenting which packages should use it --- ## @contractspec/integration.example-generator Description: Example plugin: Markdown documentation generator for ContractSpec specs Path: packages/integrations/example-generator URL: /llms/integration.example-generator # @contractspec/integration.example-generator Website: https://contractspec.io **Example plugin: Markdown documentation generator for ContractSpec specs.** ## What It Provides - **Layer**: integration. - **Consumers**: plugin authors, documentation pipelines. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/integration.example-generator` or `bun add @contractspec/integration.example-generator` ## Usage Import the root entrypoint from `@contractspec/integration.example-generator`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/config.ts` is part of the package's public or composition surface. - `src/generator.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/types.ts` is shared public type definitions. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./config` resolves through `./src/config.ts`. - Export `./generator` resolves through `./src/generator.ts`. - Export `./types` resolves through `./src/types.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run test:watch` — bun test --watch - `bun run test:coverage` — bun test --coverage - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. ## Notes - Do not add business logic; this is a reference plugin. - Keep the export surface minimal -- new exports need a clear use-case. - Peer-depends on `contracts-spec` and `schema`; do not bundle them. --- ## @contractspec/integration.harness-runtime Description: Runtime adapters for the ContractSpec harness system. Path: packages/integrations/harness-runtime URL: /llms/integration.harness-runtime # @contractspec/integration.harness-runtime Website: https://contractspec.io **Runtime adapters that bridge the ContractSpec harness core into browser, sandbox, artifact, and MCP-backed execution targets.** ## What It Provides - Provides concrete adapters for browser automation, visual harnessing, sandboxed execution, and artifact storage. - Exposes MCP helpers and default target resolution on top of the mode-agnostic harness core. - Keeps higher-cost runtime integrations optional so consumers can opt into heavier execution targets deliberately. - `src/adapters/` contains runtime, provider, or environment-specific adapters. - `src/mcp/` contains MCP handlers, tools, prompts, and resources. ## Installation `npm install @contractspec/integration.harness-runtime` or `bun add @contractspec/integration.harness-runtime` ## Usage Import the root entrypoint from `@contractspec/integration.harness-runtime`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/adapters/` contains browser, sandbox, and visual harness adapters. - `src/artifacts/` contains filesystem and in-memory artifact-store implementations. - `src/mcp/` exposes harness execution surfaces to MCP-aware runtimes. - `src/targets/` contains target resolution helpers and target-selection logic. - `src/types.ts` exposes shared runtime-facing harness types. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Exports runtime adapters, artifact stores, MCP exposure helpers, target resolution, and shared types. - Export `.` resolves through `./src/index.ts`. - Export `./adapters/playwrightBrowserHarnessAdapter` resolves through `./src/adapters/playwrightBrowserHarnessAdapter.ts`. - Export `./adapters/sandboxedCodeExecutionAdapter` resolves through `./src/adapters/sandboxedCodeExecutionAdapter.ts`. - Export `./adapters/visualHarnessAdapter` resolves through `./src/adapters/visualHarnessAdapter.ts`. - Export `./artifacts/filesystemArtifactStore` resolves through `./src/artifacts/filesystemArtifactStore.ts`. - Export `./artifacts/inMemoryArtifactStore` resolves through `./src/artifacts/inMemoryArtifactStore.ts`. - Export `./mcp/exposure` resolves through `./src/mcp/exposure.ts`. - Export `./targets/defaultTargetResolver` resolves through `./src/targets/defaultTargetResolver.ts`. - Export `./types` resolves through `./src/types.ts`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun run lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Add a first-class harness system for controlled inspection, testing, evaluation, and proof generation. ## Notes - Works alongside `@contractspec/lib.contracts-spec`, `@contractspec/lib.harness`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. --- ## @contractspec/integration.providers-impls Description: Integration provider implementations for email, payments, storage, and more Path: packages/integrations/providers-impls URL: /llms/integration.providers-impls # @contractspec/integration.providers-impls Website: https://contractspec.io **Integration provider implementations for email, payments, storage, and more.** ## What It Provides - **Layer**: integration. - **Consumers**: bundles, apps, modules that need concrete provider wiring. - Related ContractSpec packages include `@contractspec/integration.runtime`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. - Related ContractSpec packages include `@contractspec/integration.runtime`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/integration.providers-impls` or `bun add @contractspec/integration.providers-impls` ## Usage Import the root entrypoint from `@contractspec/integration.providers-impls`, or choose a documented subpath when you only need one part of the package surface. ## Architecture - `src/analytics.ts` is part of the package's public or composition surface. - `src/calendar.ts` is part of the package's public or composition surface. - `src/database.ts` is part of the package's public or composition surface. - `src/email.ts` is part of the package's public or composition surface. - `src/embedding.ts` is part of the package's public or composition surface. - `src/health.ts` is part of the package's public or composition surface. - `src/impls` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./analytics` resolves through `./src/analytics.ts`. - Export `./calendar` resolves through `./src/calendar.ts`. - Export `./database` resolves through `./src/database.ts`. - Export `./email` resolves through `./src/email.ts`. - Export `./embedding` resolves through `./src/embedding.ts`. - Export `./health` resolves through `./src/health.ts`. - Export `./impls` resolves through `./src/impls/index.ts`. - Export `./impls/async-event-queue` resolves through `./src/impls/async-event-queue.ts`. - Export `./impls/composio-fallback-resolver` resolves through `./src/impls/composio-fallback-resolver.ts`. - The package publishes 76 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Missing dependencies (thanks to knip). - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and type errors across nine packages. - Resolve lint, build, and test failures across voice, workspace, library, and composio. - Composio. - Normalize formatting across contracts-integrations, composio, and observability. ## Notes - Every implementation must satisfy a contract from `contracts-integrations`. - Never import from apps or bundles. - Secrets must flow through `@contractspec/integration.runtime`; never hard-code credentials. - Composio fallback is opt-in; existing code paths are unchanged when config is absent. - Composio proxy adapters must not leak Composio-specific types into domain interfaces. --- ## @contractspec/integration.runtime Description: Runtime integration with secret management Path: packages/integrations/runtime URL: /llms/integration.runtime # @contractspec/integration.runtime Website: https://contractspec.io **Runtime integration with secret management.** ## What It Provides - **Layer**: integration. - **Consumers**: `providers-impls`, bundles, apps that need secrets or channel routing. - Related ContractSpec packages include `@contractspec/lib.contracts-integrations`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.logger`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`. ## Installation `npm install @contractspec/integration.runtime` or `bun add @contractspec/integration.runtime` ## Usage Import the root entrypoint from `@contractspec/integration.runtime`, or choose a documented subpath when you only need one part of the package surface. The channel runtime keeps policy evaluation deterministic and auditable: - Signature-invalid events are rejected before processing. - `MessagingPolicyEngine` can be replaced by a contract-backed policy evaluator through `ChannelRuntimeService`. - `ChannelApprovalService` exposes a generic approval queue for CLI, API, web, or custom operator surfaces via the shared channel store. - `ControlPlaneSkillRegistryService` verifies, installs, lists, and disables signed skill artifacts against an allowlisted trust policy. - Compiled plans now carry deterministic plan and step IDs, DAG dependency metadata, typed step I/O schema refs, actor audit context, and approval timeout fallback state. - Capability grants are intended to be bound by the hosting application, for example through `CHANNEL_RUNTIME_DEFAULT_CAPABILITY_GRANTS`, rather than trusted from inbound event payload metadata. - Hosting applications should also bind a server-side actor via `actorResolver` so runtime approvals and execution are attributed to the authenticated service, operator, or agent principal rather than raw inbound channel claims. - Telemetry now carries `traceId`, `sessionId`, and `workflowId` when callers provide them in inbound metadata. - Trace services now persist stage-level trace events so operators can inspect the full intent -> plan -> policy -> action -> outcome chain. ## Architecture - `src/channel` is part of the package's public or composition surface. - `src/health.ts` is part of the package's public or composition surface. - `src/index.ts` is the root public barrel and package entrypoint. - `src/runtime.health.test.ts` is part of the package's public or composition surface. - `src/runtime.ts` is part of the package's public or composition surface. - `src/secrets` is part of the package's public or composition surface. - `src/transport` is part of the package's public or composition surface. ## Public Entry Points - Export `.` resolves through `./src/index.ts`. - Export `./channel` resolves through `./src/channel/index.ts`. - Export `./channel/approval` resolves through `./src/channel/approval.ts`. - Export `./channel/authorization` resolves through `./src/channel/authorization.ts`. - Export `./channel/base-types` resolves through `./src/channel/base-types.ts`. - Export `./channel/dispatcher` resolves through `./src/channel/dispatcher.ts`. - Export `./channel/github` resolves through `./src/channel/github.ts`. - Export `./channel/memory-store` resolves through `./src/channel/memory-store.ts`. - Export `./channel/plan-types` resolves through `./src/channel/plan-types.ts`. - Export `./channel/plan-utils` resolves through `./src/channel/plan-utils.ts`. - Export `./channel/planner` resolves through `./src/channel/planner.ts`. - Export `./channel/planner-types` resolves through `./src/channel/planner-types.ts`. - Export `./channel/policy` resolves through `./src/channel/policy.ts`. - Export `./channel/postgres-queries` resolves through `./src/channel/postgres-queries.ts`. - Export `./channel/postgres-schema` resolves through `./src/channel/postgres-schema.ts`. - Export `./channel/postgres-store` resolves through `./src/channel/postgres-store.ts`. - Export `./channel/replay-fixtures` resolves through `./src/channel/replay-fixtures.ts`. - Export `./channel/service` resolves through `./src/channel/service.ts`. - Export `./channel/slack` resolves through `./src/channel/slack.ts`. - Export `./channel/store` resolves through `./src/channel/store.ts`. - Export `./channel/telegram` resolves through `./src/channel/telegram.ts`. - Export `./channel/telemetry` resolves through `./src/channel/telemetry.ts`. - Export `./channel/trace` resolves through `./src/channel/trace.ts`. - Export `./channel/types` resolves through `./src/channel/types.ts`. - Export `./channel/whatsapp-meta` resolves through `./src/channel/whatsapp-meta.ts`. - Export `./channel/whatsapp-twilio` resolves through `./src/channel/whatsapp-twilio.ts`. - Export `./health` resolves through `./src/health.ts`. - Export `./runtime` resolves through `./src/runtime.ts`. - Export `./secrets` resolves through `./src/secrets/index.ts`. - Export `./secrets/env-secret-provider` resolves through `./src/secrets/env-secret-provider.ts`. - Export `./secrets/gcp-secret-manager` resolves through `./src/secrets/gcp-secret-manager.ts`. - Export `./secrets/manager` resolves through `./src/secrets/manager.ts`. - Export `./secrets/provider` resolves through `./src/secrets/provider.ts`. - Export `./transport` resolves through `./src/transport/index.ts`. - Export `./transport/auth-resolver` resolves through `./src/transport/auth-resolver.ts`. - Export `./transport/transport-factory` resolves through `./src/transport/transport-factory.ts`. - Export `./transport/version-negotiator` resolves through `./src/transport/version-negotiator.ts`. - The package publishes 41 total export subpaths; keep docs aligned with `package.json`. ## Local Commands - `bun run dev` — contractspec-bun-build dev - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types - `bun run test` — bun test --pass-with-no-tests - `bun run lint` — bun lint:fix - `bun run lint:check` — biome check . - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write . - `bun run typecheck` — tsc --noEmit - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary - `bun run clean` — rimraf dist .turbo - `bun run build:bundle` — contractspec-bun-build transpile - `bun run build:types` — contractspec-bun-build types - `bun run prebuild` — contractspec-bun-build prebuild ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed. - Resolve lint, build, and type errors across nine packages. - Add Composio universal fallback, fix provider-ranking types, and expand package exports. - Add first-class transport, auth, versioning, and BYOK support across all integrations. - Upgrade dependencies. - Stabilize lint gate and runtime contract typing. ## Notes - Secret providers must implement the `provider` interface; never read secrets directly. - Channel stores (memory, postgres) are swappable; do not couple to a specific backend. - Never import from apps or bundles. --- ## @contractspec/integration.workflow-devkit Description: Workflow DevKit compiler and runtime bridges for ContractSpec workflows Path: packages/integrations/workflow-devkit URL: /llms/integration.workflow-devkit # @contractspec/integration.workflow-devkit Workflow DevKit compiler and runtime bridges for ContractSpec `WorkflowSpec`. ## What it provides - Compile a `WorkflowSpec` into a deterministic Workflow DevKit manifest. - Generate Workflow, Next.js, and generic-host scaffolding. - Run a `WorkflowSpec` through injected Workflow DevKit primitives such as `sleep`, hooks, and webhooks. - Create a Workflow-backed `AgentRuntimeAdapterBundle` for `@contractspec/lib.ai-agent`. - Expose chat route helpers and re-export `WorkflowChatTransport` for reconnectable chat UIs. ## Entry points - `@contractspec/integration.workflow-devkit` - `@contractspec/integration.workflow-devkit/compiler` - `@contractspec/integration.workflow-devkit/runtime` - `@contractspec/integration.workflow-devkit/chat-routes` - `@contractspec/integration.workflow-devkit/agent-adapter` - `@contractspec/integration.workflow-devkit/next` ## Next.js example ```ts import { withContractSpecWorkflow } from "@contractspec/integration.workflow-devkit/next"; import { createWorkflowChatRoutes } from "@contractspec/module.ai-chat/core/workflow"; export default withContractSpecWorkflow({ experimental: {}, }); const routes = createWorkflowChatRoutes({ workflow: async (payload) => payload, getFollowUpToken({ runId }) { return `chat:${runId}`; }, }); export const POST = routes.start; ``` ## Generic host example ```ts import { createHook, createWebhook, sleep } from "workflow"; import { runWorkflowSpecWithWorkflowDevkit, type WorkflowDevkitRuntimeBridge, } from "@contractspec/integration.workflow-devkit"; import { onboardingWorkflow } from "./onboarding.workflow"; export async function runOnboarding(input: Record, bridge: WorkflowDevkitRuntimeBridge) { "use workflow"; return runWorkflowSpecWithWorkflowDevkit({ spec: onboardingWorkflow, initialData: input, bridge, primitives: { sleep, createHook, createWebhook, }, }); } ``` --- ## contractspec Description: CLI tool for creating, building, and validating contract specifications Path: packages/apps-registry/contractspec URL: /llms/contractspec # contractspec Website: https://contractspec.io **npm-published CLI entry point for ContractSpec. Thin wrapper that delegates to `@contractspec/app.cli-contractspec` via `bin/contractspec.mjs`.** ## What It Does - **Layer**: apps-registry - **Consumers**: end-users installing `npx contractspec` or `bun x contractspec` ## Installation `npm install contractspec` or `bun add contractspec` ## Usage ```bash npx contractspec --help # or bunx contractspec --help ``` ## Public Entry Points - `contractspec` -> `./bin/contractspec.mjs` ## Local Commands - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Stability - Refactor contracts libs to split them reducing bundle size and load ## Notes - This package is a shim; all logic lives in `@contractspec/app.cli-contractspec` - Do not add dependencies beyond the CLI app workspace reference - Changes to `bin/contractspec.mjs` affect every user -- test locally before publishing --- ## @contractspec/app.cursor-marketplace Description: Cursor marketplace catalog for ContractSpec product and core libraries Path: packages/apps-registry/cursor-marketplace URL: /llms/app.cursor-marketplace # @contractspec/app.cursor-marketplace Website: https://contractspec.io **Cursor marketplace catalog containing plugin definitions (rules, commands, agents, skills, assets) for ContractSpec's Cursor IDE integrations.** ## What It Does - **Layer**: apps-registry - **Consumers**: Cursor IDE users, marketplace publishing pipeline ## Running Locally From `packages/apps-registry/cursor-marketplace`: ## Local Commands - `bun run validate` — node ../../../scripts/validate-contractspec-plugin.mjs ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - Expose contract management via CLI and MCP - Add Cursor marketplace catalog for core ContractSpec libraries ## Notes - Each plugin must have a valid `.cursor-plugin/plugin.json` - Do not add runtime code; this package contains only declarative metadata - Validate changes with `bun run validate` before publishing - Logo assets in `assets/` must remain stable (referenced by marketplace) --- ## spec-driven-development Description: CLI tool for creating, building, and validating contract specifications Path: packages/apps-registry/spec-driven-development URL: /llms/spec-driven-development # spec-driven-development Website: https://contractspec.io **npm-published CLI alias for ContractSpec under the `sdd` / `spec-driven-development` binary names. Thin wrapper that delegates to `@contractspec/app.cli-contractspec`.** ## What It Does - **Layer**: apps-registry - **Consumers**: end-users installing `npx sdd` or `npx spec-driven-development` ## Installation `npm install spec-driven-development` or `bun add spec-driven-development` ## Usage ```bash npx sdd --help # or bunx sdd --help ``` ## Public Entry Points - `sdd` -> `./bin/contractspec.mjs` - `spec-driven-development` -> `./bin/contractspec.mjs` ## Local Commands - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose - `bun run publish:pkg:canary` — bun publish:pkg --tag canary ## Recent Updates - Replace eslint+prettier by biomejs to optimize speed - PublishConfig not supported by bun ## Notes - This package is a shim; all logic lives in `@contractspec/app.cli-contractspec` - Do not add dependencies beyond the CLI app workspace reference - Changes to `bin/contractspec.mjs` affect every user -- test locally before publishing ---