` and requiring visible text to sit inside `Text` or approved typography components. Repository app packages are excluded by default and can be opted in with the policy allowlist.
- Related ContractSpec packages include `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
## Installation
`npm install @lssm-tech/biome-config`
or
`bun add @lssm-tech/biome-config`
## Usage
Import the root entrypoint from `@lssm-tech/biome-config`, or choose a documented subpath when you only need one part of the package surface.
### JSX Primitive Fixer
The Biome Grit plugins emit diagnostics only. To apply conservative native HTML replacement fixes, run:
`bun run jsx:fix-primitives`
or from this package:
`bun run fix:jsx-primitives`
By default the fixer scans `packages/bundles`, `packages/examples`, and `packages/modules`. It skips `packages/apps` unless an app is explicitly allowlisted:
`bun run jsx:fix-primitives -- --allow-app web-landing`
Use `--check` for a dry run. The fixer preserves original attributes and className by default, infers safe list props from simple class strings, and wraps raw text with context awareness: block-safe containers keep `
...`, while mixed-content contexts use inline-safe `
...`. Ambiguous form/action primitives remain diagnostic-only, and generic inline `
` elements are still skipped.
## Architecture
- `src/policies.ts` defines the typed policy manifest.
- `src/generate.ts` and `src/sync.ts` generate and synchronize derived artifacts.
- `src/fix-jsx-primitives.ts` provides the conservative companion codemod for deterministic JSX primitive replacements.
- `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 fix:jsx-primitives` — apply conservative JSX primitive replacements.
- `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
- Add cross-platform JSX layout and text guardrails for React and React Native compatibility.
- Add a conservative JSX primitive fixer command for deterministic native HTML replacements.
- Replace eslint+prettier by biomejs to optimize speed.
## Notes
- The committed `presets/`, `plugins/`, and `ai/` artifacts are intended for downstream scaffolding without code execution.
---
## @lssm-tech/tool.bun
Description: Shared Bun build presets and CLI for ContractSpec packages
Path: packages/tools/bun
URL: /llms/tool.bun
# @lssm-tech/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 @lssm-tech/tool.bun`
or
`bun add @lssm-tech/tool.bun`
## Usage
```bash
npx contractspec-bun-build --help
# or
bunx contractspec-bun-build --help
```
## Typed Config
The root package export includes TypeScript declarations for config presets:
```ts
import {
defineConfig,
moduleLibrary,
type BuildConfig,
} from "@lssm-tech/tool.bun";
const config: BuildConfig = {
...moduleLibrary,
styleMode: "copy",
};
export default defineConfig(() => config);
```
## Style Exports
`contractspec-bun-build` scans public CSS style entries separately from TypeScript entries so style files do not affect JavaScript output roots.
Default style entries:
- `styles/**/*.css`
- `src/*.css`
- `!**/*.module.css`
Packages can override or disable style entries from their build config:
```js
export default {
styleEntry: ['styles/**/*.css'],
// or: styles: { entry: ['styles/**/*.css'] },
// or: styleEntry: false,
};
```
By default, style entries are processed with `bun build`. Packages that need to preserve CSS directives for another processor, such as Tailwind `@source`, `@custom-variant`, `@theme`, or `@tailwind`, can copy style files unchanged:
```js
export default {
styleEntry: ['src/styles/**/*.css'],
styleMode: 'copy',
// or: styles: { entry: ['src/styles/**/*.css'], mode: 'copy' },
};
```
Style entries are exported under the `style` and `default` conditions, for example `./styles/globals.css`.
## Type Declaration Emit
`contractspec-bun-build types` emits package declarations with the TypeScript 7
native preview (`tsgo`) by generating a temporary declaration-only tsconfig and
writing `.d.ts` files to `dist`. Apps do not use this package declaration path.
## Platform Variants
`contractspec-bun-build` recognizes platform suffixes in public TypeScript entries and emits conditional exports plus matching build outputs:
| Source suffix | Export condition | Build output |
| --- | --- | --- |
| `.web` | `browser` | `dist/browser/*` plus the Bun default when no base entry exists |
| `.native` | `react-native` | `dist/native/*` |
| `.ios` | `ios` | `dist/native/*` |
| `.android` | `android` | `dist/native/*` |
Exact subpaths such as `./foo.web`, `./foo.native`, `./foo.ios`, and `./foo.android` are exported alongside canonical subpaths such as `./foo`.
## 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
- Add copy mode for public CSS style files that must preserve framework directives
- Add direct CSS style subpath exports for public style files
- 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
---
## @lssm-tech/tool.contracts-mcp-gen
Description: Generator that walks ContractSpec defineCommand/defineQuery specs and produces MCP-compatible tool schemas.
Path: packages/tools/contracts-mcp-gen
URL: /llms/tool.contracts-mcp-gen
(No README.md)
---
## @lssm-tech/tools.contractspec-codemods
Description: Codemods + import-graph scanner that mechanically migrate consumers of the rich-reference legacy surfaces (CodeBlock, DiffBlock, ObjectReferenceHandler, RichContentReference, rich-code-preferences) to the post-S-8 surface (RichBlock, RichRef, RichReference, rich-reference/preferences).
Path: packages/tools/contractspec-codemods
URL: /llms/tools.contractspec-codemods
# `@lssm-tech/tools.contractspec-codemods`
Codemods + import-graph scan that mechanically migrate consumers of the
pre-S-8 rich-reference legacy surface (`CodeBlock`, `DiffBlock`,
`ObjectReferenceHandler/Panel`, `RichContentReference`,
`rich-code-preferences`) to the post-S-8 surface (`RichBlock`, `RichRef`,
`PreviewPanel`, `RichReference`, `rich-reference/preferences`).
See [`MIGRATION.md`](./MIGRATION.md) for the full migration guide,
before/after examples, and human-follow-up cases.
## Quick start
```bash
# Discover legacy call sites (writes discovery-list.json)
bun run scripts/discover.ts --roots packages/ --out discovery-list.json
# Dry-run the codemods
bun run scripts/apply.ts --roots packages/ --dry
# Apply the codemods in place
bun run scripts/apply.ts --roots packages/
```
## Codemods
- `codemod-code-block` — `CodeBlock` → ``.
- `codemod-diff-block` — `DiffBlock` → `` (incl.
`DiffBlock.web` / `DiffBlock.native` platform splits).
- `codemod-object-reference` — `ObjectReferenceHandler` → `` and
`ObjectReferencePanel` → ``.
- `codemod-rich-content-references` — `RichContentReference` /
`RichCodeBlockModel` / `RichDiffBlockModel` / `redactRichCodeBlock` /
`redactRichDiffBlock` → new rich-reference + ui-kit-core equivalents.
- `codemod-personalization-imports` — `rich-code-preferences` subpath →
`rich-reference/preferences`.
Each codemod is pure (string → string) and idempotent. Run them in the
canonical `STANDARD_CODEMODS` pipeline, or call them individually.
## Safety
The codemods are regex/string-based with a brace-balanced JSX attribute
parser. They use a context scanner that:
- skips strings, template literals, and comments (so docs-page example
template strings stay intact);
- newline-terminates string scanning (defends against JSX-text
apostrophes such as "What you'll build" — JS strings cannot contain raw
newlines per spec, so this is correct in addition to defensive);
- inserts new imports after the last REAL top-level import, never inside
a template literal.
## CI gate (AC-17)
- Per-PR: `bun run discover` is informational; growth should be flagged.
- Per-release: the migration regression test
(`__tests__/migration-regression.test.ts`) asserts that every entry in
`discovery-list.json` was migrated. Zero hits required to ship.
## Files
```
src/
legacy-symbols.ts # canonical migration map
parse-helpers.ts # safe-span scanner + JSX tag parser
codemod-runner.ts # CodemodResult + pipeline helper
codemod-code-block.ts
codemod-diff-block.ts
codemod-object-reference.ts
codemod-rich-content-references.ts
codemod-personalization-imports.ts
import-graph-scan.ts # AST-ish + string-literal scanner
index.ts # public surface
scripts/
discover.ts # writes discovery-list.json
apply.ts # writes codemod output in place
__tests__/ # fixture tests + migration regression
```
---
## @lssm-tech/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
# @lssm-tech/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 `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
## Installation
`npm install @lssm-tech/tool.create-contractspec-plugin`
or
`bun add @lssm-tech/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 `@lssm-tech/lib.contracts-spec` and `@lssm-tech/lib.schema` -- respect their APIs.
---
## @lssm-tech/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
# @lssm-tech/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 `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
## Installation
`npm install @lssm-tech/tool.docs-generator`
or
`bun add @lssm-tech/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 `@lssm-tech/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.
---
## @lssm-tech/tools.eslint-plugin-i18n
Description: ESLint rules enforcing i18n hygiene: no module-scope translation calls and no raw Accept-Language reads.
Path: packages/tools/eslint-plugin-i18n
URL: /llms/tools.eslint-plugin-i18n
(No README.md)
---
## @lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields
Description: ESLint rule enforcing that every defineReferenceKind() call declares an explicit sensitiveFields array (closes F-4).
Path: packages/tools/eslint-plugin-no-implicit-sensitivefields
URL: /llms/tools.eslint-plugin-no-implicit-sensitivefields
# @lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields
ESLint plugin that enforces explicit `sensitiveFields` declarations on every `defineReferenceKind()` call from `@lssm-tech/lib.contracts-spec/rich-reference`.
Closes plan slice S-1b (architect NR-2 / F-4 mitigation): the contracts-spec runtime already throws when `sensitiveFields` is missing or non-array, but the runtime cannot enforce the additional repository policy that an empty array (`sensitiveFields: []`) must be accompanied by an inline confirmation comment. This rule catches both issues at lint time.
## Install
```bash
bun add -d @lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields
```
`eslint` (>=8, <11) is a peer dependency.
## Flat config (ESLint 9+)
```js
import noImplicitSensitiveFields from '@lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields';
export default [
{
plugins: { 'no-implicit-sensitivefields': noImplicitSensitiveFields },
rules: { 'no-implicit-sensitivefields/no-implicit-sensitivefields': 'error' },
},
];
```
Or apply the bundled `recommended` flat config in one line:
```js
import { configs } from '@lssm-tech/tools.eslint-plugin-no-implicit-sensitivefields';
export default [configs.recommended];
```
## What the rule does
For every call expression whose callee is `defineReferenceKind` (or `.defineReferenceKind`):
1. If the object literal argument lacks a `sensitiveFields` property → reports `missing`.
2. If `sensitiveFields: []` appears without a nearby comment containing `confirmed: no sensitive fields` → reports `emptyWithoutComment`.
A "nearby" comment is one whose line number is within ±1 line of the `sensitiveFields` property — covering the common authoring shapes: a leading comment, a same-line trailing comment, or an in-block comment immediately after.
### Valid
```ts
defineReferenceKind({
id: 'ticket',
schema,
sensitiveFields: ['title'],
defaultPreview: 'inline-card',
defaultPanel: 'drawer',
icon: 'ticket',
});
defineReferenceKind({
id: 'public-doc',
schema,
// confirmed: no sensitive fields
sensitiveFields: [],
defaultPreview: 'inline-card',
defaultPanel: 'drawer',
icon: 'doc',
});
defineReferenceKind({
id: 'public-doc-2',
schema,
sensitiveFields: [], // confirmed: no sensitive fields
defaultPreview: 'inline-card',
defaultPanel: 'drawer',
icon: 'doc',
});
```
### Invalid
```ts
// Missing sensitiveFields entirely
defineReferenceKind({
id: 'bad-1',
schema,
defaultPreview: 'inline-card',
defaultPanel: 'drawer',
icon: 'bad',
}); // error: missing
// Empty list without the confirmation marker
defineReferenceKind({
id: 'bad-2',
schema,
sensitiveFields: [],
defaultPreview: 'inline-card',
defaultPanel: 'drawer',
icon: 'bad',
}); // error: emptyWithoutComment
```
## Test
```bash
bun test
```
---
## @lssm-tech/tool.test-redaction-rules
Description: Credential-pattern regex corpus for CI telemetry redaction sweeps (T.3).
Path: packages/tools/test-redaction-rules
URL: /llms/tool.test-redaction-rules
(No README.md)
---
## @lssm-tech/tool.tsdown
Description: Shared tsdown config presets for LSSM monorepo
Path: packages/tools/tsdown
URL: /llms/tool.tsdown
# @lssm-tech/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 @lssm-tech/tool.tsdown`
or
`bun add @lssm-tech/tool.tsdown`
## Usage
Import the root entrypoint from `@lssm-tech/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`
---
## @lssm-tech/tool.typescript
Description: (none)
Path: packages/tools/typescript
URL: /llms/tool.typescript
# @lssm-tech/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": "@lssm-tech/tool.typescript/..."`)
## Installation
`npm install @lssm-tech/tool.typescript`
or
`bun add @lssm-tech/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
## TypeScript 7 Native Preview
The monorepo keeps the default `typescript` catalog on TypeScript 6 for apps and
framework tooling. Non-app packages can be checked with the side-by-side
TypeScript 7 native preview (`tsgo`) from the repository root:
```sh
bun run typecheck:tsgo:not-apps
```
This command scans `packages/libs`, `packages/modules`, and `packages/bundles`,
uses each package's existing typecheck project (`tsconfig.build.json` when the
package script selects it), and intentionally skips `packages/apps`. Use
`bun run typecheck:tsgo:not-apps:sample` for a fast representative smoke check.
`contractspec-bun-build types` now emits non-app package declarations with
`tsgo`; apps remain on the TypeScript 6 compiler path and do not use this
package declaration pipeline.
Rollback is intentionally narrow: revert `contractspec-bun-build types` to
`tsc`, remove the root `typecheck:tsgo:not-apps` scripts, and remove
`@typescript/native-preview` where it is only needed for tsgo verification.
Package tsconfig presets and app package configs do not need to change.
## 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
---
## @lssm-tech/integration.authos-better-auth
Description: Better Auth bridge that maps AuthOS contracts to provider configuration, plugins, and redacted events.
Path: packages/integrations/authos-better-auth
URL: /llms/integration.authos-better-auth
# `@lssm-tech/integration.authos-better-auth`
Better Auth bridge for AuthOS Broad V0.
This package turns AuthOS contracts into Better Auth configuration and maps Better Auth-like user/session/events back to AuthOS contracts. Canonical models stay in `@lssm-tech/lib.authos-spec`; pure projections and security gates stay in `@lssm-tech/lib.authos-runtime`.
## Maturity
- Core email/password, organization/team, admin, OAuth/OIDC client, MFA, magic link, email OTP, phone, and one-tap are runtime-backed through Better Auth `1.6.10` surfaces.
- SSO, SCIM, and passkey are represented as declared external plugin capabilities until their production package wiring is separately reviewed.
- LSSM-as-IdP is contract-only unless `securityReviewRef` is present and production enablement is explicitly gated.
## Verification
```bash
bun run lint:check
bun run typecheck
bun run test
bun run build
```
---
## @lssm-tech/integration.builder-telegram
Description: Telegram Builder control-channel integration.
Path: packages/integrations/builder-telegram
URL: /llms/integration.builder-telegram
# @lssm-tech/integration.builder-telegram
Telegram webhook normalization and Builder control-channel envelope mapping.
---
## @lssm-tech/integration.builder-voice
Description: Voice Builder input integration.
Path: packages/integrations/builder-voice
URL: /llms/integration.builder-voice
# @lssm-tech/integration.builder-voice
Browser and uploaded voice helpers for Builder transcription flows.
---
## @lssm-tech/integration.builder-whatsapp
Description: WhatsApp Builder control-channel integration.
Path: packages/integrations/builder-whatsapp
URL: /llms/integration.builder-whatsapp
# @lssm-tech/integration.builder-whatsapp
Meta and Twilio WhatsApp normalization for Builder control-channel workflows.
---
## @lssm-tech/integration.crdt-loro
Description: Isolated Loro-compatible CRDT adapter proof for data transmission collaboration envelopes.
Path: packages/integrations/crdt-loro
URL: /llms/integration.crdt-loro
# @lssm-tech/integration.crdt-loro
Isolated Loro adapter proof for ContractSpec collaboration envelopes.
## Boundary
This is the only V0 package that imports `loro-crdt`. Core data-transmission spec/runtime packages expose ContractSpec envelopes and never expose raw Loro types.
## Convergence proof
The package exports `runLoroConvergenceProof`, which applies independent left/right document updates, exchanges snapshots/updates through adapter-scoped envelopes, and verifies converged snapshots, versions, update counts, and byte counts without leaking Loro document objects to core contracts.
## V0 constraints
The proof covers in-memory update/snapshot/export/import/merge semantics. Production persistence, auth, managed WebSocket hosting, multi-region guarantees, and hosted collaboration backends are future work.
---
## @lssm-tech/integration.example-generator
Description: Example plugin: Markdown documentation generator for ContractSpec specs
Path: packages/integrations/example-generator
URL: /llms/integration.example-generator
# @lssm-tech/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 `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Related ContractSpec packages include `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
## Installation
`npm install @lssm-tech/integration.example-generator`
or
`bun add @lssm-tech/integration.example-generator`
## Usage
Import the root entrypoint from `@lssm-tech/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.
---
## @lssm-tech/integration.fake-outbox-adapter
Description: Fake/sandbox outbox adapter for builder delivery loop testing.
Path: packages/integrations/fake-outbox-adapter
URL: /llms/integration.fake-outbox-adapter
# @lssm-tech/integration.fake-outbox-adapter
Website: https://contractspec.io
**Fake/sandbox outbox adapter for builder delivery loop testing.**
## What It Provides
- Simulated outbox adapter for testing builder delivery loop transitions without real provider SDKs or credentials.
- Supports `fake` and `sandbox` modes only; rejects production mode.
- Implements preflight checks, draft preparation, submission, receipt generation, and rollback.
- Idempotency key tracking and duplicate detection.
- Configurable latency simulation and failure rates for testing.
## When to Use
- Testing builder-delivery-loop transitions in development/staging.
- CI/CD integration tests that don't require real provider sends.
- Local development where real credentials aren't available.
- **Never use in production** - this adapter is explicitly designed to reject production mode.
## Usage
```typescript
import { createFakeOutboxAdapter } from '@lssm-tech/integration.fake-outbox-adapter';
const adapter = createFakeOutboxAdapter({
mode: 'sandbox',
simulateLatencyMs: 100,
failureRate: 0.1, // 10% simulated failure rate
});
// Preflight check
const preflight = await adapter.preflight({
loopId: 'loop-123',
idempotencyKey: 'unique-key-123',
billingOSRefs: ['billing-ref-1'],
companyOSRefs: ['company-ref-1'],
operatorApprovalRef: 'approval-123',
});
if (preflight.canProceed) {
// Prepare draft
const draft = await adapter.prepareDraft(input, preflight);
// Submit
const submission = await adapter.submit(draft, {
draftId: draft.draftId,
loopId: 'loop-123',
idempotencyKey: 'unique-key-123',
approvalStillValid: true,
revisionAtSubmission: 1,
});
// Get receipt
const receipt = await adapter.getReceipt({
submissionId: submission.submissionId,
idempotencyKey: 'unique-key-123',
});
}
```
## Architecture
- Pure TypeScript implementation with no external provider dependencies.
- In-memory storage for drafts, submissions, and receipts.
- Fails closed on production mode detection.
- Supports idempotency for safe retry semantics.
## Safety
- **Always rejects production mode** - set `rejectProductionMode: true` (default).
- Requires idempotency keys for all operations.
- Requires operator approval references.
- Duplicate idempotency keys return existing receipts (idempotent).
## Local Commands
- `bun run dev` — contractspec-bun-build dev
- `bun run build` — bun run build:bundle && bun run build:types
- `bun run test` — bun test
- `bun run lint:check` — biome check .
---
## @lssm-tech/integration.harness-runtime
Description: Runtime adapters for the ContractSpec harness system.
Path: packages/integrations/harness-runtime
URL: /llms/integration.harness-runtime
# @lssm-tech/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 deterministic Playwright browser automation, optional `agent-browser` visual computer-use runs, 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 @lssm-tech/integration.harness-runtime`
or
`bun add @lssm-tech/integration.harness-runtime`
## Usage
Import the root entrypoint from `@lssm-tech/integration.harness-runtime`, or choose a documented subpath when you only need one part of the package surface.
## Architecture
- `src/adapters/` contains Playwright, agent-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/agentBrowserHarnessAdapter` resolves through `./src/adapters/agentBrowserHarnessAdapter.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.
- Add OSS full-app verification adapters for Playwright and `agent-browser`, including auth profile refs, visual diff evidence, and replay-friendly browser artifacts.
## Notes
- Works alongside `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.harness`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
- Authenticated browser runs should use named storage-state, browser-profile, session-name, or headers-env refs. Do not embed raw credentials, cookies, or bearer tokens in scenario specs or replay bundles.
---
## @lssm-tech/integration.provider-analytics
Description: Analytics provider implementations for ContractSpec.
Path: packages/integrations/provider-analytics
URL: /llms/integration.provider-analytics
# @lssm-tech/integration.provider-analytics
Website: https://contractspec.io
Analytics provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the analytics implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-calendar
Description: Calendar provider implementations for ContractSpec.
Path: packages/integrations/provider-calendar
URL: /llms/integration.provider-calendar
# @lssm-tech/integration.provider-calendar
Website: https://contractspec.io
Calendar provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the calendar implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-claude-code
Description: Claude Code provider compatibility wrapper for Builder.
Path: packages/integrations/provider-claude-code
URL: /llms/integration.provider-claude-code
(No README.md)
---
## @lssm-tech/integration.provider-codex
Description: Codex provider compatibility wrapper for Builder.
Path: packages/integrations/provider-codex
URL: /llms/integration.provider-codex
(No README.md)
---
## @lssm-tech/integration.provider-copilot
Description: Copilot provider compatibility wrapper for Builder.
Path: packages/integrations/provider-copilot
URL: /llms/integration.provider-copilot
(No README.md)
---
## @lssm-tech/integration.provider-database
Description: Database provider implementations for ContractSpec.
Path: packages/integrations/provider-database
URL: /llms/integration.provider-database
# @lssm-tech/integration.provider-database
Website: https://contractspec.io
Database provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
Use `./governed-read` when a contracts-spec `DataViewQueryGenerator` emits a `database.query.readonly` descriptor and you need to execute that governed read through a `DatabaseProvider`. The helper builds parameterized SQL from field mappings and keeps SQL construction inside this adapter package.
Use `./governed-mutation` for first-class database writes after the owning domain command has planned a portable `database.mutation.execute@2.0.0` envelope. The helper validates actor, tenant, domain-command authority, policy decision, idempotency key, transaction boundary, expected write set, audit refs, replay ref, and correlation ref before running the provider transaction. Drizzle/PostgreSQL rendering remains in this integration package, not in contracts-spec core.
Managed and BYOK Postgres/Supabase deployments are the production posture. Local/PgLite remains a provider-binding compatibility mode for deterministic tests and demos, not a separate ownership mode.
## Public subpaths
- `.` re-exports the provider surface plus governed read/mutation helpers.
- `./database` re-exports the shared `DatabaseProvider` contracts.
- `./governed-read` executes portable DataView read descriptors through a provider.
- `./governed-mutation` executes governed mutation descriptors with transaction, idempotency, and audit hooks.
- `./impls` and `./impls/supabase-psql` expose concrete PostgreSQL/Supabase implementations.
## Compatibility
This package owns the database implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-email
Description: Email provider implementations for ContractSpec.
Path: packages/integrations/provider-email
URL: /llms/integration.provider-email
# @lssm-tech/integration.provider-email
Website: https://contractspec.io
Email provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Included Providers
- `GmailInboundProvider` for thread and message sync
- `GmailOutboundProvider` for Gmail-based outbound delivery
- `PostmarkEmailProvider` for transactional email delivery
## Compatibility
This package owns the email implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-embedding
Description: Embedding provider implementations for ContractSpec.
Path: packages/integrations/provider-embedding
URL: /llms/integration.provider-embedding
# @lssm-tech/integration.provider-embedding
Website: https://contractspec.io
Embedding provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the embedding implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-gemini
Description: Gemini provider compatibility wrapper for Builder.
Path: packages/integrations/provider-gemini
URL: /llms/integration.provider-gemini
(No README.md)
---
## @lssm-tech/integration.provider-github
Description: GitHub provider implementation for ContractSpec with repository, issue, and pull request management.
Path: packages/integrations/provider-github
URL: /llms/integration.provider-github
(No README.md)
---
## @lssm-tech/integration.provider-health
Description: Health data provider implementations for ContractSpec.
Path: packages/integrations/provider-health
URL: /llms/integration.provider-health
# @lssm-tech/integration.provider-health
Website: https://contractspec.io
Health data provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the health implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-llm
Description: LLM provider implementations for ContractSpec.
Path: packages/integrations/provider-llm
URL: /llms/integration.provider-llm
# @lssm-tech/integration.provider-llm
Website: https://contractspec.io
LLM provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the llm implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-local-model
Description: Local model provider compatibility wrapper for Builder.
Path: packages/integrations/provider-local-model
URL: /llms/integration.provider-local-model
(No README.md)
---
## @lssm-tech/integration.provider-meeting-recorder
Description: Meeting recorder provider implementations for ContractSpec.
Path: packages/integrations/provider-meeting-recorder
URL: /llms/integration.provider-meeting-recorder
# @lssm-tech/integration.provider-meeting-recorder
Website: https://contractspec.io
Meeting recorder provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the meeting-recorder implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-messaging
Description: Messaging provider implementations for ContractSpec.
Path: packages/integrations/provider-messaging
URL: /llms/integration.provider-messaging
# @lssm-tech/integration.provider-messaging
Website: https://contractspec.io
Messaging provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Included Providers
- `SlackMessagingProvider`
- `GithubMessagingProvider`
- `MatrixMessagingProvider`
- `TelegramMessagingProvider`
- `MetaWhatsappMessagingProvider`
- `TwilioWhatsappMessagingProvider`
## Compatibility
This package owns the messaging implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
## Slack
`SlackMessagingProvider` implements Slack message send/update/delete plus conversations, users, reactions, files, and search operations over the Slack Web API. It requires a bot token for standard Web API calls and can optionally use a user token for search endpoints that require user-scoped Slack permissions.
Import it from:
```ts
import { SlackMessagingProvider } from "@lssm-tech/integration.provider-messaging/impls/messaging-slack";
```
```ts
const slack = new SlackMessagingProvider({
botToken: process.env.SLACK_BOT_TOKEN!,
userToken: process.env.SLACK_USER_TOKEN,
defaultChannelId: "C0123456789",
});
await slack.sendMessage({ text: "ContractSpec check passed" });
const search = await slack.searchMessages("ContractSpec", 10);
```
For inbound Slack Event API requests, verify signatures and normalize events through `@lssm-tech/integration.runtime/channel/slack` or the higher-level Slack webhook receiver in `@lssm-tech/integration.runtime/webhooks/slack`. Keep `botToken`, `userToken`, app tokens, and signing secrets in a `SecretProvider` or environment secret store; never commit real Slack credentials, raw webhook URLs, or signed payload logs.
## GitHub
`GithubMessagingProvider` implements the messaging bridge for GitHub issue and pull request comments. Use `recipientId` in the `owner/repo#number` form, or configure `defaultOwner` and `defaultRepo` and pass the issue/PR number as `threadId`.
Import it from:
```ts
import { GithubMessagingProvider } from "@lssm-tech/integration.provider-messaging/impls/messaging-github";
```
```ts
const github = new GithubMessagingProvider({
token: process.env.GITHUB_TOKEN!,
defaultOwner: "lssm-tech",
defaultRepo: "contractspec",
});
await github.sendMessage({
threadId: "42",
text: "ContractSpec automation result",
});
```
For repository, issue, pull request, merge, and code-search operations, use `@lssm-tech/integration.provider-github`. For inbound GitHub webhook requests, verify signatures and normalize channel events through `@lssm-tech/integration.runtime/channel/github` or the webhook receiver in `@lssm-tech/integration.runtime/webhooks/github`. Keep personal access tokens, GitHub App installation tokens, private keys, and webhook secrets in managed secrets; test fixtures should use redacted placeholders and mocked `fetch` responses only.
## Matrix
`MatrixMessagingProvider` is a minimal `matrix-js-sdk` adapter for Matrix room sends and mocked room-event normalization. It expects an existing homeserver URL and access token; it does not provision homeservers, automate hosted signup, install bridges, guarantee production bridge operation, or replace direct Slack/Telegram/WhatsApp providers.
Import it from:
```ts
import { MatrixMessagingProvider } from "@lssm-tech/integration.provider-messaging/impls/messaging-matrix";
```
---
## @lssm-tech/integration.provider-openbanking
Description: Open banking provider implementations for ContractSpec.
Path: packages/integrations/provider-openbanking
URL: /llms/integration.provider-openbanking
# @lssm-tech/integration.provider-openbanking
Website: https://contractspec.io
Open banking provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the openbanking implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-opencode-go
Description: OpenCode Go provider compatibility wrapper for Builder.
Path: packages/integrations/provider-opencode-go
URL: /llms/integration.provider-opencode-go
(No README.md)
---
## @lssm-tech/integration.provider-payments
Description: Payments provider implementations for ContractSpec.
Path: packages/integrations/provider-payments
URL: /llms/integration.provider-payments
# @lssm-tech/integration.provider-payments
Website: https://contractspec.io
Payments provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the payments implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-pioneer-ai
Description: Pioneer AI provider adapter for ContractSpec AI improvement workflows.
Path: packages/integrations/provider-pioneer-ai
URL: /llms/integration.provider-pioneer-ai
# @lssm-tech/integration.provider-pioneer-ai
Targeted Pioneer AI adapter for the vendor-neutral AI improvement contracts.
The adapter is feature-gated and mock-first. It never exports Pioneer-specific domain types into core packages; callers interact through ContractSpec AI-improvement envelopes, provider capability maps, and provider receipts.
## Safety defaults
- `AI_IMPROVEMENT_VENDOR_EXPORT=off` denies raw dataset export.
- `AI_IMPROVEMENT_AUTO_APPLY=off` prevents automatic promotion.
- `AI_IMPROVEMENT_LEARNING=off` prevents memory writes.
- `PIONEER_AI_ADAPTER=off` disables this adapter at the Pioneer integration boundary; the neutral core uses `adapterDisabled`.
---
## @lssm-tech/integration.provider-project-management
Description: Project management provider implementations for ContractSpec.
Path: packages/integrations/provider-project-management
URL: /llms/integration.provider-project-management
# @lssm-tech/integration.provider-project-management
Website: https://contractspec.io
Project management provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the project-management implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-sms
Description: SMS provider implementations for ContractSpec.
Path: packages/integrations/provider-sms
URL: /llms/integration.provider-sms
# @lssm-tech/integration.provider-sms
Website: https://contractspec.io
SMS provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the sms implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-storage
Description: Object storage provider implementations for ContractSpec.
Path: packages/integrations/provider-storage
URL: /llms/integration.provider-storage
# @lssm-tech/integration.provider-storage
Website: https://contractspec.io
Object storage provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the storage implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-stt
Description: Speech-to-text provider compatibility wrapper for Builder.
Path: packages/integrations/provider-stt
URL: /llms/integration.provider-stt
(No README.md)
---
## @lssm-tech/integration.provider-vector-store
Description: Vector store provider implementations for ContractSpec.
Path: packages/integrations/provider-vector-store
URL: /llms/integration.provider-vector-store
# @lssm-tech/integration.provider-vector-store
Website: https://contractspec.io
Vector store provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the vector-store implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
---
## @lssm-tech/integration.provider-voice
Description: Voice, speech, and conversational provider implementations for ContractSpec.
Path: packages/integrations/provider-voice
URL: /llms/integration.provider-voice
# @lssm-tech/integration.provider-voice
Website: https://contractspec.io
Voice, speech, and conversational provider implementations for ContractSpec.
## Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the `./impls/*` subpaths.
## Compatibility
This package owns the voice implementation slice split out of `@lssm-tech/integration.providers-impls`. The legacy package continues to re-export these subpaths for existing consumers.
## Implementations
- `GradiumVoiceProvider`: Gradium SDK-backed TTS implementation for the configured workspace, with contract metadata covering public REST/WebSocket TTS and STT surfaces.
- `FalVoiceProvider`: official `@fal-ai/client`-backed Chatterbox TTS implementation with contract metadata covering broader fal media SDK/API/MCP surfaces.
- `SlngVoiceProvider`: API-key `fetch` implementation for SLNG TTS and STT routes. Route templates are configurable so tenants can target the SLNG provider/model path available to their account.
Secrets are passed explicitly through provider options or secret providers; implementations do not read environment variables directly or serialize secret values.
---
## @lssm-tech/integration.providers-impls
Description: Integration provider implementations for email, payments, storage, and more
Path: packages/integrations/providers-impls
URL: /llms/integration.providers-impls
# @lssm-tech/integration.providers-impls
Website: https://contractspec.io
**Compatibility facade and all-provider factory for ContractSpec provider implementations.**
## What It Provides
- **Layer**: integration.
- **Consumers**: bundles, apps, and modules that still need the broad compatibility surface or the all-provider factory.
- Targeted provider implementation packages now own the concrete domains, such as `@lssm-tech/integration.provider-email`, `@lssm-tech/integration.provider-payments`, `@lssm-tech/integration.provider-voice`, and `@lssm-tech/integration.provider-project-management`.
- Related ContractSpec packages include `@lssm-tech/integration.runtime`, `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/tool.bun`, and `@lssm-tech/tool.typescript`.
## Installation
`npm install @lssm-tech/integration.providers-impls`
or
`bun add @lssm-tech/integration.providers-impls`
## Usage
Prefer a targeted package when you only need one provider domain:
```ts
import { GmailInboundProvider } from '@lssm-tech/integration.provider-email/impls/gmail-inbound';
import { StripePaymentsProvider } from '@lssm-tech/integration.provider-payments/impls/stripe-payments';
```
Existing imports from `@lssm-tech/integration.providers-impls` and its `./impls/*` subpaths remain supported as compatibility re-exports. Keep using this package for `IntegrationProviderFactory` or when you intentionally need the broad composition surface.
### Communication Coverage
`IntegrationProviderFactory` now covers the main OSS communication paths directly:
- `createEmailInboundProvider(...)` for Gmail thread/message sync
- `createEmailOutboundProvider(...)` for Gmail and Postmark delivery
- `createSmsProvider(...)` for Twilio SMS
- `createMessagingProvider(...)` for Telegram, WhatsApp Meta, and WhatsApp Twilio
## Architecture
- `src/analytics.ts`, `src/calendar.ts`, `src/database.ts`, `src/email.ts`, `src/embedding.ts`, and the other domain files are compatibility re-exports to targeted packages.
- `src/impls/provider-factory.ts` owns the all-provider factory and imports targeted packages.
- `src/impls/composio-*` owns the cross-domain Composio fallback/proxy surface.
- `src/impls/*` provider implementation files are compatibility re-exports to targeted packages.
- `src/index.ts` is the root public barrel and package entrypoint.
## Targeted Packages
- `@lssm-tech/integration.provider-analytics`
- `@lssm-tech/integration.provider-calendar`
- `@lssm-tech/integration.provider-database`
- `@lssm-tech/integration.provider-email`
- `@lssm-tech/integration.provider-embedding`
- `@lssm-tech/integration.provider-health`
- `@lssm-tech/integration.provider-llm`
- `@lssm-tech/integration.provider-meeting-recorder`
- `@lssm-tech/integration.provider-messaging`
- `@lssm-tech/integration.provider-openbanking`
- `@lssm-tech/integration.provider-payments`
- `@lssm-tech/integration.provider-project-management`
- `@lssm-tech/integration.provider-sms`
- `@lssm-tech/integration.provider-storage`
- `@lssm-tech/integration.provider-vector-store`
- `@lssm-tech/integration.provider-voice`
## 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/pioneer-ai` resolves through `./src/impls/pioneer-ai.ts`.
- Export `./impls/slng-voice` resolves through `./src/impls/slng-voice.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 81 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 `@lssm-tech/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.
- `@lssm-tech/integration.provider-pioneer-ai` for mock-first Pioneer AI self-improvement job/evaluation integration.
---
## @lssm-tech/integration.runtime-hybrid
Description: Hybrid runtime compatibility wrapper for Builder.
Path: packages/integrations/runtime-hybrid
URL: /llms/integration.runtime-hybrid
(No README.md)
---
## @lssm-tech/integration.runtime-local
Description: Local runtime compatibility wrapper for Builder.
Path: packages/integrations/runtime-local
URL: /llms/integration.runtime-local
(No README.md)
---
## @lssm-tech/integration.runtime-managed
Description: Managed runtime compatibility wrapper for Builder.
Path: packages/integrations/runtime-managed
URL: /llms/integration.runtime-managed
(No README.md)
---
## @lssm-tech/integration.runtime
Description: Runtime integration with secret management
Path: packages/integrations/runtime
URL: /llms/integration.runtime
# @lssm-tech/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 `@lssm-tech/lib.contracts-integrations`, `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.logger`, `@lssm-tech/tool.bun`, `@lssm-tech/tool.typescript`.
## Installation
`npm install @lssm-tech/integration.runtime`
or
`bun add @lssm-tech/integration.runtime`
## Usage
Import the root entrypoint from `@lssm-tech/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.
- Add monorepo-aware environment resolution helpers that materialize framework aliases and redact secret values in reports.
- Upgrade dependencies.
- Stabilize lint gate and runtime contract typing.
## Notes
- Secret providers must implement the `provider` interface; never read secrets directly.
- Environment resolution reports must stay redacted; secret and sensitive values are never serialized into examples, reports, telemetry, or errors.
- Channel stores (memory, postgres) are swappable; do not couple to a specific backend.
- Never import from apps or bundles.
---
## @lssm-tech/integration.voice-input-native
Description: @react-native-voice/voice + expo-av/Deepgram STT integration for M3 voice input
Path: packages/integrations/voice-input-native
URL: /llms/integration.voice-input-native
(No README.md)
---
## @lssm-tech/integration.voice-input-web
Description: Web Speech API + Deepgram Nova-3 STT integration for M3 voice input
Path: packages/integrations/voice-input-web
URL: /llms/integration.voice-input-web
(No README.md)
---
## @lssm-tech/integration.workflow-devkit
Description: Workflow DevKit compiler and runtime bridges for ContractSpec workflows
Path: packages/integrations/workflow-devkit
URL: /llms/integration.workflow-devkit
# @lssm-tech/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 `@lssm-tech/lib.ai-agent`.
- Expose chat route helpers and re-export `WorkflowChatTransport` for reconnectable chat UIs.
## Entry points
- `@lssm-tech/integration.workflow-devkit`
- `@lssm-tech/integration.workflow-devkit/compiler`
- `@lssm-tech/integration.workflow-devkit/runtime`
- `@lssm-tech/integration.workflow-devkit/chat-routes`
- `@lssm-tech/integration.workflow-devkit/agent-adapter`
- `@lssm-tech/integration.workflow-devkit/next`
## Workflow vs step boundary
Workflow DevKit code runs across two different execution contexts:
- Workflow functions (`"use workflow"`) orchestrate control flow and must stay deterministic.
- Step functions (`"use step"`) perform the actual Node.js work.
This matches the Workflow docs: workflow functions do not have full Node.js access, while step functions do. Keep Node.js core modules, SDK clients, database access, and other side effects inside `use step` helpers. The workflow function itself should only compose Workflow primitives and call step helpers.
For `WorkflowSpec` authoring in Workflow-hosted apps, import the safe authoring API from `@lssm-tech/lib.contracts-spec/workflow/spec`, not the broad `@lssm-tech/lib.contracts-spec/workflow` barrel.
## Next.js example
```ts
import { withContractSpecWorkflow } from "@lssm-tech/integration.workflow-devkit/next";
import { createWorkflowChatRoutes } from "@lssm-tech/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 "@lssm-tech/integration.workflow-devkit";
import { onboardingWorkflow } from "./onboarding.workflow";
export async function runOnboarding(input: Record, bridge: WorkflowDevkitRuntimeBridge) {
"use workflow";
// Keep this function deterministic. Node.js work belongs in `use step`
// helpers that your bridge dispatches to.
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 `@lssm-tech/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 `@lssm-tech/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
---
## @lssm-tech/app.cursor-marketplace
Description: Cursor marketplace catalog for ContractSpec product and core libraries
Path: packages/apps-registry/cursor-marketplace
URL: /llms/app.cursor-marketplace
# @lssm-tech/app.cursor-marketplace
Website: https://contractspec.io
**Cursor marketplace catalog containing publishable plugin artifacts for ContractSpec's IDE integrations.**
## What It Does
- **Layer**: apps-registry
- **Consumers**: Cursor IDE users, marketplace publishing pipeline
- Hosts derived plugin artifacts generated from reusable `packs/*` sources of truth
## Running Locally
From `packages/apps-registry/cursor-marketplace`:
## Local Commands
- `bun run validate` — node ../../../scripts/validate-contractspec-plugin.mjs
## Catalog Structure
- Root catalog manifest: `.cursor-plugin/marketplace.json`
- Publishable plugin artifacts: `plugins/*`
- Reusable source packs live outside this package under `packs/*` and are exported here
## 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
- Customer-facing runtime behavior is produced through `agentpacks` generation and hook/MCP configs, not custom code in this package
- 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 `@lssm-tech/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 `@lssm-tech/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
---