@zonekit/config-publisher

Library-level config build and release workflow for Zonekit.

Use @zonekit/config-publisher when you want to script the config lifecycle in code instead of shelling out to the CLI. It loads authored config from disk, validates it, builds artifacts, computes diffs, publishes outputs, negotiates schema versions, and promotes versions through a lock file.

If you mostly want terminal commands in CI or local workflows, use @zonekit/cli. This package is the lower-level library behind that flow.

Installation

pnpm add -D @zonekit/config-publisher

Quick start

import {
  buildConfig,
  loadConfig,
  publishConfig,
  validateConfig,
} from "@zonekit/config-publisher";

const config = await loadConfig("./zonekit.config.yaml");

const validation = await validateConfig({ configPath: "./zonekit.config.yaml" });
if (!validation.valid) {
  console.error(validation.errors);
  process.exit(1);
}

const result = await buildConfig({ configPath: "./zonekit.config.yaml", outDir: "./dist" });
console.log("Built config hash:", result.hash);

const published = await publishConfig({
  buildDir: "./dist",
  outputDir: "./publish",
});

console.log("Published version:", published.versionFile.current);

void config;

Recommended workflow

1. loadConfig() to parse authored YAML or JSON and expand flow globs.
2. validateConfig() and validateContracts() before merge or publish.
3. buildConfig() to create the exact artifact set you intend to ship.
4. diffConfig() to compare versions and estimate consumer impact.
5. publishConfig() to stage or upload artifacts.
6. promoteConfig() to move a chosen version into the lock file.

Key exports

Loading and validation

• loadConfig(configPath) parses a Zonekit config from YAML or JSON and resolves flows.pattern.
• validateConfig(options) validates an authored config file against schema and semantic rules.
• validateContracts(options) checks the current config surface against *.contract.json files.

Building and diffing

• buildConfig(options) builds versioned artifacts from the authored config.
• diffConfig(options) compares two config versions and returns structural changes plus optional app impact.

Publishing and promotion

• publishConfig(options) copies build artifacts to an output directory and optionally uploads them through a CDN adapter.
• promoteConfig(options) updates a lock file to point at a chosen version hash after schema compatibility checks.
• negotiateSchemaVersion(options) negotiates a compatible schema version across consumers.

Errors

• SchemaVersionMismatchError is thrown when promotion would move the lock file to an incompatible schema version.

Common types

• BuildConfigOptions / BuildResult -- Build input and output
• DiffConfigOptions / DiffResult / StructuralChange / AppImpact -- Diff types
• PublishConfigOptions / PublishResult -- Publish types
• PromoteConfigOptions / PromoteResult -- Promote types
• CdnUploadAdapter / UploadArtifact / UploadResult -- CDN adapter interface
• NegotiateSchemaVersionOptions / NegotiationResult -- Schema negotiation types

Notes

• buildConfig() writes a hash directory plus top-level config.json, config.d.ts, and version.json.
• publishConfig() expects the output of buildConfig() as its buildDir.
• promoteConfig() reads meta.json from the published artifacts directory, not from the raw source config.
• loadConfig() expands flows.pattern relative to the config file location.

License

MIT

Read more:

• @zonekit/config-publisher package docs
• Config plane overview
• CLI docs