@phcdevworks/spectre-manifest

Machine-readable contract package for the Spectre ecosystem. It records package roles, layers, ownership boundaries, dependency rules, and AI/tooling guidance in one source of truth.

Issues | Pull requests | Security | Contributing

Capabilities

• Defines the official Spectre package and layer map.
• Requires a root schemaVersion so tools know which manifest contract they validated.
• Models allowed and forbidden dependency relationships.
• Publishes a JSON schema and TypeScript validation utilities.
• Validates schema rules plus semantic concerns such as duplicate layer order and dependency cycles.
• Gives humans, CI, scaffolding, docs, and AI workflows the same architecture contract.

Install

npm install @phcdevworks/spectre-manifest

Quick Start

Validate a manifest object:

import { validateManifest } from '@phcdevworks/spectre-manifest'
import manifest from './spectre.manifest.json' with { type: 'json' }

const result = validateManifest(manifest)

if (!result.valid) {
  console.error(result.issues)
}

Validate a manifest file:

import { formatManifestValidationIssues, validateManifestFile } from '@phcdevworks/spectre-manifest'

const result = await validateManifestFile('spectre.manifest.json')

if (!result.valid) {
  console.error(formatManifestValidationIssues(result.issues))
}

Use the validate CLI:

npx spectre-manifest-validate spectre.manifest.json
npx spectre-manifest-validate spectre.manifest.json --json

Check a downstream package against its manifest entry:

npx spectre-manifest-check spectre.manifest.json ./path/to/your-package
npx spectre-manifest-check spectre.manifest.json ./path/to/your-package --json

The checker validates package metadata before inspecting it; malformed data returns structured issues, including with --json. When exports is present, declared exports must have a non-null target. String, array, and conditional root exports represent .; subpath maps are checked by their declared keys. Conditional targets are checked for declared availability, respecting blocking default targets and nested fallthrough, without selecting runtime conditions or checking files on disk. For example, { "default": null, "import": "./index.js" } has no available target because the default blocks the later import condition. Packages without exports retain the legacy behavior of skipping export checks.

Diff two manifests and classify every change as additive, semantic, or breaking:

npx spectre-manifest-diff old.manifest.json new.manifest.json
npx spectre-manifest-diff old.manifest.json new.manifest.json --json

An absent or empty allowedTargets list imposes no target restriction. Changing it to a non-empty list is breaking; clearing the list is additive. The diff CLI exits with code 1 for breaking changes.

For consumers, only an absent list is unrestricted; [] permits no consumers. Introducing a consumer list or removing a listed consumer is breaking. Removing the restriction entirely or adding to an existing list is additive.

Package and layer registry names are matched as own properties, so names such as constructor are handled as ordinary entries. Metadata edits are reported as semantic changes, including $schema, $id, system package-manager/repository fields, notes throughout the manifest, and rule reasons. Metadata additions, removals, and note ordering changes are visible; reordering otherwise identical rules or entrypoints does not create a metadata change.

Import the published manifest document directly:

import manifest from '@phcdevworks/spectre-manifest/manifest' with { type: 'json' }

API

Runtime exports:

• validateManifest
• validateManifestFile
• formatManifestValidationIssues
• loadManifestSchema
• manifestSchemaPath
• checkPackageAgainstManifest
• formatPackageCheckIssues
• diffManifests
• formatManifestDiff

Published schema export:

• @phcdevworks/spectre-manifest/schema

Published manifest export:

• @phcdevworks/spectre-manifest/manifest

Type exports include SpectreManifest, SpectrePackageDefinition, SpectreLayerDefinition, ManifestRules, ManifestAiGuidance, PackageCheckResult, PackageCheckIssue, ManifestChange, ManifestChangeClassification, and ManifestDiffResult.

Boundaries

This package owns architecture metadata, schema, and validation. It does not own rendering, styling, routing, reactive state, component implementation, or framework adapters.

Development

corepack pnpm install
corepack pnpm --filter @phcdevworks/spectre-manifest build
corepack pnpm --filter @phcdevworks/spectre-manifest test

Release Notes

See the project releases on GitHub.

License

MIT. See LICENSE.