Skip to content
ContractSpec
Start here

Package manual · examples

·Examples and implementation patterns

module.examples

Example contract specifications collection

examplesmodulev6.1.4stableservernode
@lssm-tech/module.examples
bun add @lssm-tech/module.examples
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Website: https://contractspec.io

Catalog-first ContractSpec example metadata, with optional runtime helpers for rich example surfaces.

What It Provides

  • Layer: module.
  • Consumers: CLIs, editor bridges, apps, docs, and rich sandbox/template surfaces.
  • Related ContractSpec packages include @lssm-tech/example.agent-console, @lssm-tech/example.ai-chat-assistant, @lssm-tech/example.ai-support-bot, @lssm-tech/example.analytics-dashboard, @lssm-tech/example.calendar-google, @lssm-tech/example.content-generation, ...
  • agent-console is the default autonomous-agent showcase surfaced through /sandbox.
  • data-grid-showcase is the canonical ContractSpec table showcase surfaced through /sandbox?template=data-grid-showcase and /docs/examples/data-grid-showcase.

Installation

npm install @lssm-tech/module.examples

or

bun add @lssm-tech/module.examples

Usage

Use the root entrypoint or @lssm-tech/module.examples/catalog for metadata-only discovery. Use @lssm-tech/module.examples/runtime only when rendering rich template previews or sandbox runtime surfaces. The catalog also exposes shared preview-surface helpers so apps can show every discoverable example while loading rich UI only for packages that export ./ui.

ts
import { getExample, listExamples } from '@lssm-tech/module.examples/catalog';
ts
import { ExampleWebPreview, TemplateRuntimeProvider, listTemplates } from '@lssm-tech/module.examples/runtime';

Host ports

Apps and bundles that render a specific example read it through a named host port instead of importing @lssm-tech/example.* packages, which the package-layer boundary check rejects. Each port re-exports only what hosts use and is split by runtime:

EntrypointRuntimeContents
./runtime/native-previewsnative, browser, serverExample contracts, visualization specs and deterministic sample data for native preview panels. No web UI or template providers.
./runtime/feature-hub-referencenative, serverinstallFeatureHubCompositionReference and FEATURE_HUB_REFERENCE_ROUTE_IDS.
./runtime/companyos-ai-solutions-engineer-pocbrowser, serverThe hosted-demo contract: COMPANYOS_ACME_PROFILE, compileCanonicalPreparedProof, the outcome-pack schema and the demo runtime contract.
./runtime/companyos-ai-solutions-engineer-poc/serverNode onlyThe proof runtime: call runtime, preflight probe, proof session authority, browser fixture and approved-proof runner.
./runtime/companyos-ai-solutions-engineer-poc/uiclient componentsRequestToVerifiedProofPreview.
ts
import { CRM_PIPELINE_DEALS } from '@lssm-tech/module.examples/runtime/native-previews';
import { COMPANYOS_ACME_PROFILE } from '@lssm-tech/module.examples/runtime/companyos-ai-solutions-engineer-poc';

The example packages stay optional peers: a host installs the examples whose port it imports.

The catalog contains source metadata for each example. CLI users can fetch a full example only when needed:

sh
contractspec examples download minimal --out-dir ./examples/minimal

Public preview/export workflow

Template, docs, and sandbox previews are generated from package-owned example metadata:

  1. Example packages expose catalog metadata through ./example and docs through ./docs when they should appear in public template/docs surfaces.
  2. Rich inline previews are opt-in public surfaces. A package that adds ./ui must keep that export package-native, deterministic, fixture-backed, and mirrored in publishConfig.exports.
  3. scripts/generate-example-registry.ts is the only writer for generated catalog and preview registry artifacts; run bun run --cwd examples/registry generate:registry after changing example exports.
  4. Preview consumers should use catalog helpers for discoverability and supportsInlineExamplePreview() / getExamplePreviewSurface() before loading runtime UI. Keep docs, sandbox, LLMS, and source fallback links available for examples without inline UI.
  5. Do not introduce live backend calls, provider credentials, or production actions in preview fixtures. Provider-oriented examples must render local replay/fixture data only.

Generation and build preflight

Registry generation is an explicit repository operation. Run the existing root bun run examples:sync-registry command, or the package's generate:registry, after changing example metadata, exports or runtime ports. It manages exactly the CLI catalog's src/example-catalog/builtins.ts, the registry's src/runtime/previews.generated.ts, src/preview-catalog.generated.ts, package.json optional peers and turbo.json dependency edges.

Package prebuild now runs check:registry before the canonical artifact builder. That comparison reports stale managed outputs and does not regenerate them. Output leaves and their ancestors must not be symlinks; generation rejects an unsafe output before evaluating example modules or changing another output.

Both explicit generation and comparison still import eligible declared workspace src/example.ts modules. Those are trusted executable project code, not inert JSON. Comparison's absence of managed writes is not a filesystem or network sandbox and does not replace the task's execution-authority review.

Architecture

  • src/builtins.ts is a generated literal catalog and must not statically import @lssm-tech/example.* packages.
  • src/catalog.ts is the metadata-only public 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 the optional rich runtime surface for consumers that intentionally install example packages.

Public Entry Points

  • Export . resolves through ./src/index.ts and is catalog-only.
  • Export ./catalog resolves through ./src/catalog.ts.
  • Export ./runtime resolves through ./src/runtime/index.ts.
  • Exports ./runtime/native-previews, ./runtime/feature-hub-reference, ./runtime/companyos-ai-solutions-engineer-poc, ./runtime/companyos-ai-solutions-engineer-poc/server and ./runtime/companyos-ai-solutions-engineer-poc/ui are the host ports described under Usage.

Local Commands

  • bun run dev — contractspec-bun-build dev
  • bun run build — contractspec-bun-build build
  • 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 — tsgo --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 check:registry — bun ../../scripts/generate-example-registry.ts --check
  • bun run prebuild — bun run check: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 catalog/runtime bridge -- business logic belongs in individual example packages under examples/.
  • Adding a new example requires creating the example package and regenerating the catalog with bun run generate:registry; do not add it as a direct dependency here.
  • Root/catalog imports must remain metadata-only. Rich runtime consumers should import @lssm-tech/module.examples/runtime (or a host port) and own any required @lssm-tech/example.* dependencies directly.
  • 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.

The registry generator also owns optional example-runtime peers and this package's Turbo task dependencies. Optional peers preserve catalog-only installation while letting declaration builds resolve the installed example declaration surfaces. The generated task edges build those declarations before the runtime bridge; example packages remain responsible for validating their own implementations. Run generate:registry after changing preview exports or runtime example imports. Do not hand-edit the managed example peers or turbo.json.

Relationships

THIS PACKAGEmodule.examples8 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

8 declarations

Declared capabilities

Module Examples

Example contract specifications collection

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../scripts/biome.cjs check --write .
  • lint:checknode ../../scripts/biome.cjs check .
  • testbun test
  • generate:registrybun ../../scripts/generate-example-registry.ts --write
  • check:registrybun ../../scripts/generate-example-registry.ts --check
  • prebuildbun run check:registry && contractspec-bun-build prebuild
  • typechecktsgo --noEmit