bundle.workspace

@lssm-tech/bundle.workspace

Website: https://contractspec.io

Core workspace bundle for ContractSpec validation, code generation, and repository setup.

What It Provides

• Provides the service layer behind the CLI, editor integrations, drift detection, diagnostics, and setup flows.
• Retains dependency-free AI ports used to inject optional capabilities.
• Acts as the main orchestration bundle for repository lifecycle, graph inspection, drift reporting, regeneration planning, 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.
• Generative Core orchestration is exposed as services.generativeCore for graph artifact persistence, dry-run generation plans, drift reports, and Connect/path policy classification.

Local capability lookup

can-help discovers local package manifests from the root workspaces authority (array or workspaces.packages), including nested foundation/platform/domain groups, explicit bridges, root examples and exclusions. Overlapping patterns are deduplicated; undeclared folders and conflicting package identities are not promoted as reusable workspace packages. Classic projects use their root manifest.

Current manifest capability IDs, constraints and canonical imports/exports remain workspace / workspace-scan evidence. They do not establish registry publication or replace the shipped catalog. Mirrored catalog observations retain their source, degraded warnings and staleness, bound to the exact document including observation dates. Legacy embedded mirrors stay explicitly degraded; verified registry or installed catalog evidence remains distinct from local workspace content. No live authorization decisions are cached.

For a focused machine-readable result, use contractspec can-help "@lssm-tech/lib.contracts-spec-core/features" --scope workspace --limit 1 --json. The separate published catalog may remain unavailable while the current workspace implementation is discoverable.

Release file portability

Release discovery reads Changeset frontmatter with LF or CRLF line endings without rewriting files. Package bump metadata, summaries and capsule fallback packages retain their existing meaning. Lone CR and unrecognized headers remain opaque summaries with no parsed package releases; ignored none or invalid bump rows and filesystem errors preserve their existing behavior. This is local, deterministic parsing and grants no provider or publication authority.

Direct capsule validation and YAML-path repair preserve supplied POSIX absolute paths and Windows drive-absolute, UNC or rooted paths. Relative paths, including Windows drive-relative paths, keep the adapter/workspace resolution behavior. Returned capsule and quarantine paths use the adapter's native spelling. Validation remains read-only; repair writes still require the existing explicit write option. Selected Changeset/capsule paths retain paired owning-workspace slug selection and deduplication; bare repair slugs still select canonical workspace capsules.

Installation

npm install @lssm-tech/bundle.workspace

or

bun add @lssm-tech/bundle.workspace

Concrete AI SDKs are optional peers with development mirrors; installing the workspace bundle alone does not force provider SDKs into a consumer lockfile. Hosts that enable AI behavior must supply compatible implementations through the exported ports.

bun add @lssm-tech/integration.workspace-ai

Utiliser createNodeAiAdapter(config) from the integration and pass it as the ai option to createNodeAdapters. Concrete agents and prompts are imported from the integration package rather than the workspace bundle root.

Usage

Import the root entrypoint from @lssm-tech/bundle.workspace, or choose a documented subpath when you only need one part of the package surface.

Self-maintaining API adapters

@lssm-tech/bundle.workspace/maintenance composes the module lifecycle with production-oriented adapters:

• digest-bound OpenAPI, GraphQL, protobuf, SDK-manifest, and changelog source ingestion;
• signed, declarative, language-scoped migration packs that cannot execute arbitrary provider code; and
• GitHub App installation authentication, bounded repository snapshots, atomic branch commits, fail-closed check observation, draft pull requests, webhook verification/deduplication, and exact-ref rollback.

GitHubGovernedChangeAutomationAdapter supplies the optional V2 ready-for-review and native auto-merge port. It re-reads the PR and check runs, requires the exact head SHA, and delegates merge completion to GitHub branch protection; it never invokes the direct merge endpoint. The existing maintenance adapter continues to create draft-only PRs.

The host remains responsible for tenant-to-installation authorization, secret resolution, deployment scheduling, policy, and live qualification.

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/maintenance.ts exposes the self-maintaining API adapter composition.
• AI-facing services depend on workspace ports; concrete provider selection is an optional host concern.
• 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.

Generative Core Responsibilities

• Compose discovery, graph-building, artifact persistence, drift classification, and regeneration-plan services behind ports/adapters.
• Keep graph and drift operations deterministic and JSON-schema-versioned so CLI, CI, Builder, and coding agents can replay evidence.
• Enforce preview-first generation: generated writes require provenance hashes and manual-edit guards; protected/apply paths require Connect verification before mutation.
• Keep Connect impact and drift verification read-only: temporary generation must override every configured docs/runtime output root and must never materialize handlers into the consumer workspace.

Public Entry Points

• Root bundle export with namespaced services, adapters, ports, formatters, templates, contracts, AI helpers, and utilities.
• services.generativeCore exposes guarded JSON-artifact helpers for generated/contractspec/graphs/**, generated/contractspec/generation/**, and generated/contractspec/drift/**; dry-run planning remains the default for mutation workflows.
• Export . resolves through ./src/index.ts.
• Export ./maintenance resolves through ./src/maintenance.ts.
• Environment templates can generate root and app-target .env.example content from the shared logical environment contract while preserving per-framework aliases such as NEXT_PUBLIC_* and EXPO_PUBLIC_*.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test --isolate
• 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 prebuild — contractspec-bun-build prebuild

Recent Updates

• Share one semver-accurate compatibility plan across Update and Doctor, with Expo SDK evidence, registry provenance, sticky prerelease channels, peer widening, and deterministic rollback waves.
• 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.
• Add signed source/codemod and GitHub App adapters for self-maintaining APIs.

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.

Builder delivery draft storage

Loop IDs are portable single components: 1–128 letters, digits, underscores or hyphens, beginning with a letter or digit. Reserved Windows device names and path-like IDs are rejected before I/O. Existing malformed or mismatched records now fail instead of being treated as missing; restore a verified record before retrying. Missing ledgers cannot restart an existing loop at release_ready, and malformed idempotency records cannot silently forget earlier effects.

This filesystem adapter remains workspace-local draft storage. It is not an atomic multi-writer ledger or a tenant isolation boundary against local filesystem writers. Production admission, durable approval/receipt persistence and provider reconciliation require the authoritative runtime composition.

Draft evidence append persists primary and related references in the loop artifact catalog without rewriting its transition ledger. Exact retries reuse stable IDs; restarting the service retains the references. Entries are labeled unverified and do not create acceptance verdicts, approvals or permission grants. Hosts with a custom storage adapter may supply the optional updateLoop method; without it, evidence append fails explicitly. The adapter remains single-writer.

Production mode rejects the local simulated approval, receipt, transition and handoff operations. Authoritative production operations must be composed through Connect and Runtime Nodes before enabling shipping in a host.

Simulation receipt recording persists a loop/key-bound draft record before returning success. Exact retries replay it; changed actor, outcome or payload under the same key is rejected. Draft IDs are explicitly prefixed draft_ and no ledger transition is claimed. These records use single-writer local storage and are not provider execution evidence. Handoff preview remains blocked until a verified receipt/replay resolver is composed; it never invents those references.

The root build targets Node-compatible server execution (including Bun). It requires filesystem, process, or native compiler facilities and does not advertise a browser export condition. Browser applications should use the relevant browser-safe contracts or UI entry points instead of importing this server root.

Tests isolate each file so Connect service mocks cannot replace spec discovery in the contract-first policy checks run by other files.

Exact duplicate workspace identities are blocking conflicts: their package and import-subpath lookup cannot fall back to an older catalog entry. Distinct prefix-suffix package identities remain independent; ./ workspace patterns and exclusions normalize to the same authority as unprefixed patterns.

CLI composition

./cli owns the existing reusable ContractSpec command composition. Delivery hosts retain bootstrap, blueprint and version glue; registry distributions call ./cli with their explicit snapshot bindings. ./cli/run remains an executable entry for hosts that need no optional snapshot supplier. Optional AI, Builder and examples registrations remain lazy and are bound to the exact Commander program through @lssm-tech/lib.cli-runtime. Their handlers are canonical here rather than copied into integrations or imported from a delivery host.

contractspec.cliRuntime.version retains the original CLI version fallback for registry wrappers. Release updates must keep it aligned with the CLI distribution version; the existing explicit CONTRACTSPEC_CLI_VERSION override still wins. The app's original program construction signatures remain compatibility wrappers.

Golden traffic generation accepts an explicit typed synchronous or asynchronous snapshot-client factory. The app host retains its original optional database module lookup, deferred until the production-snapshot action is selected. Registry hosts bind their same original lookup through ./cli/snapshot-client; the shared helper accepts a host loader and never imports a database app itself. The old database CLI lookup requested a factory absent from the current source. No production snapshot adapter is supplied here; without a binding the existing warning and no-output behavior remain. Injecting an adapter does not grant database or production authority.

The bundle prebuild owns offline MCP knowledge regeneration. App prebuild keeps its contract-source schema generation; registry consumers build the same owning bundle rather than relying on a previously generated app artifact.

Connect host hook authority

connect hook ... host hooks (--host claudecode|codex|cursor) run through the dedicated entry src/cli/connect-hook-run.ts. Durable authority for governed host edits comes from an explicit local operator grant: contractspec connect hook authority grant --path <prefix/> [--command <cmd>] [--ttl <minutes>] [--host-session <id>] --confirm-workspace <root> (interactive terminal only), with revoke and status. The grant signs a one-shot Hook Authority V1 decision bound to the workspace root and current HEAD, starts its session in the @lssm-tech/integration.lssm-os-state-sqlite adapter under the gitignored .contractspec/connect/hook-authority/, and keeps only the public key and the session capability there. When that store exists, before-file-edit, after-file-edit and before-shell-execution commit a V1 transition before Connect policy; revoked, expired, other-workspace or other-session grants deny. The grant follows the agent's own commits on its branch while every commit since the grant stays inside its prefixes and leaves hook, autonomy and grant control files alone (--pin-head binds one commit); a HEAD that left the grant denies. Lifecycle authority V1 (@lssm-tech/lib.contractspec-connect/lifecycle-authority) lets the grant establish session-start, stop and handoff without ever ending it; merge is never delegated. Hooks deny agent tool calls that run the grant command or touch the store. Without an active grant the recorded exception connect-hook-authority-port-unwired keeps the ask / Codex warning path.

Connect host hooks and run modes

This bundle owns contractspec connect hook and contractspec connect mode.

• While no operator hook authority grant exists, hooks evaluate Connect policy first; policy deny and rewrite always block. The run mode then decides instead of a blanket ask.
• The run mode follows the host permission_mode: bypassPermissions/dontAsk run autonomous (never asks; critical actions are denied with a reason), auto/acceptEdits run assisted (asks only for high-criticality actions or review verdicts), default stays supervised, and plan is readonly.
• Operators grant bounded autonomy with contractspec connect mode set <level> --for 8h [--scope <paths>], inspect it with connect mode show and remove it with connect mode clear. Grants are bound to the worktree, not a git SHA.
• .contractsrc.json connect.runModes sets default, hostModes, maxLevel and extra highCriticalityPaths. durableAuthorityRequired: true caps every run mode at supervised.
• Agent writes to hook and grant control files and agent-run connect mode set|clear are operator-only, so an agent cannot raise its own autonomy.
• Actions a run mode decides without asking are appended to run-mode-decisions.ndjson in the Connect storage root (.contractspec/connect/ by default) for after-the-fact review.