lib.contractspec-catalog

@lssm-tech/lib.contractspec-catalog

Machine-readable package and capability metadata for ContractSpec consumers, including repositories that cannot inspect the ContractSpec source repository. The package has no dependency on the ContractSpec CLI or workspace bundle.

Current coverage

The bundled catalog.json covers the exact repository publishable-package inventory used by the release pipeline. It remains explicit about registry reconciliation: prepared artifacts keep contractSpecCatalogStatus.registryReconciled false; the signed release receipt records subsequent registry inventory parity. Publishable packages use restricted @lssm-tech/* GitHub Packages and public @lssm/* npmjs projections. Public catalog JSON and compiled copies are regenerated together with valid content hashes and legacy indexes during staging. Consumers can inspect sourceEvidence, registry integrity, and this status instead of guessing completeness or treating workspace source as public availability.

Library usage

import {
  contractSpecCatalog,
  getContractSpecCatalog,
} from "@lssm-tech/lib.contractspec-catalog";

console.log(contractSpecCatalog.contentHash);
const mutableCopy = getContractSpecCatalog();

The raw document is also exported as @lssm-tech/lib.contractspec-catalog/catalog.json.

Export command

Print the bundled document to standard output:

bunx --package @lssm-tech/lib.contractspec-catalog contractspec-catalog export

Write it to the conventional consumer path:

bunx --package @lssm-tech/lib.contractspec-catalog contractspec-catalog export \
  --output .contractspec/adoption/catalog.json

Utiliser --compact for a single-line JSON document. Writing to a file creates its parent directory and replaces that explicitly selected file.

The command supports Node and Bun, including executable symlinks. Importing @lssm-tech/lib.contractspec-catalog/bin/export stays silent and exposes runCatalogExport and parseExportArguments for explicit programmatic calls.

Canonical generation

The existing workspace generator normalizes partial capability constraints with canonical schema defaults before calculating catalog identity. Explicit fields remain unchanged; absent constraint metadata retains the existing inferred platform/runtime and TypeScript requirement. Generation continues to validate references and the complete content hash. It does not claim registry availability or grant runtime authority.

Reviewed local build workflow

The Catalog build can use an exact reviewed fixture binding for its existing generator and canonical builder. The binding is derived from current source, workspace manifests, task configuration, parser provenance and complete native supplier identities. Its only self exclusion is contractspec.development.qualityTasks.build; changing other inputs invalidates the saved binding. A private candidate's binding is never a live-source receipt.

Windows x64 and Linux x64 supplier profiles are selected by the actual process platform and architecture. Their immutable source review precedes independent full native supplier and executable resolution checks. Caller options, environment paths and a successful inspection do not grant review authority. Unsupported profiles reject. The Catalog task passes only the already owned TMPDIR resource through Turbo's strict environment; its existing SOURCE_DATE_EPOCH hash input stays unchanged.

Execution requires the existing explicit runtime authorization and an idle serial lane. Writes remain bounded to the Catalog's generated artifacts, manifest, transaction/parser temporary namespace and retained task-local RTK diagnostics. Foreign files, aliases, unexpected transient state and supplier changes reject. This contributor workflow does not claim registry publication, runtime/provider authority or final campaign acceptance. Current live producer, packed consumers, release and resulting-tree checks remain separate gates.

Executable installation locations are task identity, separate from the fixed source-reviewed native tuple, tool hashes and complete supplier payload. Resolve the sole current explicit PATH candidate and require regular literal executable paths with reviewed bytes. A same-byte relocation requires a fresh task binding; the old binding stays invalid. Multiple candidates, selected aliases, broken PATH ancestor aliases, changed bytes and foreign tuples reject. Unused existing PATH directory aliases grant no executable authority and remain compatible. Windows case-only executable candidates resolve through the native filesystem API to their canonical saved paths; POSIX case stays exact. Never use an inspected hash or caller-selected receipt as source authority.