@zvk/tooling-kit

Node-oriented repository tooling helpers for ZVK applications.

Use @zvk/tooling-kit when app templates or validation scripts need the same repository file-system adapter, deterministic source-file listing, JSON source reads, or in-memory validator test harness.

See ../../docs/package-boundary-matrix.md for the package-family runtime boundary matrix. @zvk/tooling-kit is Node-only and should stay out of browser code and application runtime bundles.

import {
  commandOutputText,
  isCommandSuccess,
  runCommand
} from "@zvk/tooling-kit/commands";
import {
  createNodeRepoFileSystem,
  listRepoSourceFiles,
  readJsonFromRepoFileSystem
} from "@zvk/tooling-kit/repo-files";
import {
  collectValidatorFindings,
  collectPackageExportTargets,
  createValidatorContext,
  getPackageScripts,
  getVscodeTaskScripts,
  parseFrontmatter,
  parseToml,
  validatePackageExportContract
} from "@zvk/tooling-kit/validators";
import {
  classifyPackageSource,
  createZvkPackageProvenanceReport,
  renderZvkPackageProvenanceReport
} from "@zvk/tooling-kit/provenance";

Repository Files

createNodeRepoFileSystem creates a synchronous Node-backed repository adapter rooted at a project directory. The adapter exposes exists, read, listDirectories, and listFiles, plus Node-only helpers such as abs, toRel, and existsAbsolute.

createInMemoryRepoFileSystem mirrors the same core contract for tests without touching disk.

listRepoSourceFiles, listRepoTestFiles, and readJsonFromRepoFileSystem cover common repository contract tests without each app recreating recursive file traversal and JSON parsing helpers.

Validator Harness

createValidatorContext, createFindingRecorder, and collectValidatorFindings provide a small synchronous harness for testing repository validators against in-memory files.

parseFrontmatter, parseToml, readJsonFile, getPackageScripts, and getVscodeTaskScripts cover common repository-validator parsing without bringing in YAML, TOML, or JSON helper dependencies. They intentionally support only the simple shapes used by ZVK agent, skill, package, and VS Code task validation.

validatePackageExportContract and collectPackageExportTargets help package-local scripts validate exports maps, build artifacts, package policy, SSR import coverage, and type-fixture coverage without recreating the same checks in every repo.

The package is intended for Node tooling, tests, validation scripts, and scaffolding support. Do not import it from browser code or app runtime bundles.

Provenance Utilities

@zvk/tooling-kit/provenance adds helpers for reusable package-source checks across dependencies, devDependencies, overrides, and pnpm.overrides, plus optional npm visibility checks and package-manager-aware lockfile checks.

import {
  classifyPackageSource,
  createZvkPackageProvenanceReport,
  renderZvkPackageProvenanceReport
} from "@zvk/tooling-kit/provenance";
import { createNodeRepoFileSystem } from "@zvk/tooling-kit/repo-files";

const fileSystem = createNodeRepoFileSystem();
const report = await createZvkPackageProvenanceReport(fileSystem, {
  packageNames: ["@zvk/ui", "@zvk/themes", "@zvk/tooling-kit"],
  docsToCheck: ["README.md", "docs/USAGE.md"],
  npmVisibility: "check"
});

console.log(renderZvkPackageProvenanceReport(report));

for (const finding of report.findings) {
  if (finding.rule.startsWith("provenance.")) {
    console.error(finding.path, finding.message);
  }
}

classifyPackageSource is a small, deterministic normalizer and can help script-level reporting when you already have a dependency value. Use the provenance subpath only in Node tooling; do not import it in app runtime code.

When a repo intentionally carries multiple lockfiles during a migration, pass them explicitly:

await createZvkPackageProvenanceReport(createNodeRepoFileSystem(), {
  packageNames: ["@zvk/ui", "@zvk/themes"],
  lockfiles: ["bun.lock", "package-lock.json"],
  lockfileChecks: "check",
  lockfileMismatchChecks: "skip",
  npmVisibility: "check"
});

The repository canary runner dogfoods this API: real canary runs install local package tarballs into copied consumer fixtures, then call createZvkPackageProvenanceReport against the fixture manifest before running consumer commands. Keep additional canary provenance reporting on this API instead of copying classification logic into scripts/canary.

Migration Notes

Downstream repos that currently maintain local provenance checks should consolidate into this helper and remove duplicated logic:

• Keep one expected package list in the local script.
• Keep package-specific doc paths in docsToCheck.
• Keep report rendering in local code if custom output is needed.
• Reuse commandRunner for tests by passing an injected runner instead of monkey-patching npm.

import {
  classifyPackageSource,
  createZvkPackageProvenanceReport,
  renderZvkPackageProvenanceReport
} from "@zvk/tooling-kit/provenance";

await createZvkPackageProvenanceReport(createNodeRepoFileSystem(), {
  packageNames: ["@zvk/ui", "@zvk/themes"],
  docsToCheck: ["README.md"],
  npmVisibility: "check"
});

Commands

runCommand wraps spawnSync with deterministic defaults and normalized output, isCommandSuccess checks for status 0 with no spawn error, and commandOutputText joins stdout, stderr, and spawn errors for script diagnostics.

Repo Skill

Use .codex/skills/use-zvk-tooling-kit/SKILL.md when maintaining this package.

See ../../docs/package-boundary-matrix.md for the Node-only and test-only subpaths.