project-tiny-context-harness 0.2.39

package/dist/lib/init.js

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { CONTEXT_MANIFEST_PATH, defaultContextManifestTemplate } from "./context-manifest.js";
+import { architectureContextTemplate, areaContextTemplate, globalContextTemplate, verificationContextTemplate } from "./context-templates.js";
+import { writeConfigIfMissing } from "./config.js";
+import { createDesignMdIfMissing, DESIGN_MD_PATH } from "./design-md.js";
+import { harnessConfigPath } from "./harness-root.js";
+import { ensureDir, pathExists, writeTextIfChanged } from "./fs.js";
+import { assertSupportedSchema } from "./schema-guard.js";
+import { runSync } from "./sync-engine.js";
+export async function runInit(projectRoot, options) {
+    const report = [];
+    await assertSupportedSchema(projectRoot, "init");
+    const existingEntries = await projectHasExistingFiles(projectRoot);
+    if (existingEntries && !options.adopt && !options.force) {
+        report.push("Project is not empty; continuing with non-destructive init. Use --adopt to mark this as an existing project adoption.");
+    }
+    const configPath = await harnessConfigPath(projectRoot);
+    if (await writeConfigIfMissing(projectRoot)) {
+        report.push(`created ${configPath}`);
+    }
+    else {
+        report.push(`kept existing ${configPath}`);
+    }
+    await createProjectContext(projectRoot, report);
+    await createDesignMd(projectRoot, report);
+    const syncReport = await runSync(projectRoot);
+    report.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
+    report.push(options.adopt ? "adopt mode complete" : "init complete");
+    return report;
+}
+async function createDesignMd(projectRoot, report) {
+    if (await createDesignMdIfMissing(projectRoot)) {
+        report.push(`created ${DESIGN_MD_PATH}`);
+    }
+}
+async function projectHasExistingFiles(projectRoot) {
+    const markers = ["README.md", "src", "pyproject.toml", "go.mod"];
+    for (const marker of markers) {
+        if (await pathExists(path.join(projectRoot, marker))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function createProjectContext(projectRoot, report) {
+    const areasRoot = path.join(projectRoot, "project_context", "areas");
+    await ensureDir(areasRoot);
+    const files = [
+        [CONTEXT_MANIFEST_PATH, defaultContextManifestTemplate()],
+        ["project_context/global.md", globalContextTemplate()],
+        ["project_context/architecture.md", architectureContextTemplate()],
+        ["project_context/areas/main.md", areaContextTemplate("main")],
+        ["project_context/areas/main/verification.md", verificationContextTemplate("main")]
+    ];
+    for (const [relative, content] of files) {
+        const target = path.join(projectRoot, relative);
+        if (await pathExists(target)) {
+            report.push(`kept existing ${relative}`);
+            continue;
+        }
+        if (await writeTextIfChanged(target, content)) {
+            report.push(`created ${relative}`);
+        }
+    }
+}

package/dist/lib/managed-file.d.ts

@@ -0,0 +1,19 @@
+export interface ManagedBlockMarkers {
+    start: string;
+    end: string;
+}
+export declare const MANAGED_BLOCK_START = "<!-- pjsdlc:sdlc-harness:begin -->";
+export declare const MANAGED_BLOCK_END = "<!-- pjsdlc:sdlc-harness:end -->";
+export declare const LEGACY_MANAGED_BLOCK_START = "<!-- sdlc-harness:begin -->";
+export declare const LEGACY_MANAGED_BLOCK_END = "<!-- sdlc-harness:end -->";
+export declare const MAKEFILE_BLOCK_START = "# pjsdlc:sdlc-harness:make:begin";
+export declare const MAKEFILE_BLOCK_END = "# pjsdlc:sdlc-harness:make:end";
+export declare const LEGACY_MAKEFILE_BLOCK_START = "# sdlc-harness:make:begin";
+export declare const LEGACY_MAKEFILE_BLOCK_END = "# sdlc-harness:make:end";
+export declare const GITHUB_WORKFLOW_BLOCK_START = "# pjsdlc:sdlc-harness:github-workflow:begin";
+export declare const GITHUB_WORKFLOW_BLOCK_END = "# pjsdlc:sdlc-harness:github-workflow:end";
+export declare const MANAGED_METADATA_START = "<!-- pjsdlc:sdlc-harness-managed";
+export declare const LEGACY_MANAGED_METADATA_START = "<!-- sdlc-harness-managed";
+export declare const MANAGED_METADATA_END = "-->";
+export declare const AGENTS_BLOCK_MARKERS: ManagedBlockMarkers[];
+export declare const MAKEFILE_BLOCK_MARKERS: ManagedBlockMarkers[];

package/dist/lib/managed-file.js

@@ -0,0 +1,21 @@
+export const MANAGED_BLOCK_START = "<!-- pjsdlc:sdlc-harness:begin -->";
+export const MANAGED_BLOCK_END = "<!-- pjsdlc:sdlc-harness:end -->";
+export const LEGACY_MANAGED_BLOCK_START = "<!-- sdlc-harness:begin -->";
+export const LEGACY_MANAGED_BLOCK_END = "<!-- sdlc-harness:end -->";
+export const MAKEFILE_BLOCK_START = "# pjsdlc:sdlc-harness:make:begin";
+export const MAKEFILE_BLOCK_END = "# pjsdlc:sdlc-harness:make:end";
+export const LEGACY_MAKEFILE_BLOCK_START = "# sdlc-harness:make:begin";
+export const LEGACY_MAKEFILE_BLOCK_END = "# sdlc-harness:make:end";
+export const GITHUB_WORKFLOW_BLOCK_START = "# pjsdlc:sdlc-harness:github-workflow:begin";
+export const GITHUB_WORKFLOW_BLOCK_END = "# pjsdlc:sdlc-harness:github-workflow:end";
+export const MANAGED_METADATA_START = "<!-- pjsdlc:sdlc-harness-managed";
+export const LEGACY_MANAGED_METADATA_START = "<!-- sdlc-harness-managed";
+export const MANAGED_METADATA_END = "-->";
+export const AGENTS_BLOCK_MARKERS = [
+    { start: MANAGED_BLOCK_START, end: MANAGED_BLOCK_END },
+    { start: LEGACY_MANAGED_BLOCK_START, end: LEGACY_MANAGED_BLOCK_END }
+];
+export const MAKEFILE_BLOCK_MARKERS = [
+    { start: MAKEFILE_BLOCK_START, end: MAKEFILE_BLOCK_END },
+    { start: LEGACY_MAKEFILE_BLOCK_START, end: LEGACY_MAKEFILE_BLOCK_END }
+];

package/dist/lib/migrations.d.ts

@@ -0,0 +1,11 @@
+export interface Migration {
+    from: string;
+    to: string;
+    description: string;
+}
+export declare const migrations: Migration[];
+export interface MigrationReport {
+    changed: string[];
+    skipped: string[];
+}
+export declare function runMigrations(projectRoot: string): Promise<MigrationReport>;

package/dist/lib/migrations.js

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { CONTEXT_MANIFEST_PATH, contextManifestFromExistingAreas } from "./context-manifest.js";
+import { architectureContextTemplate, areaContextTemplate, globalContextTemplate, verificationContextTemplate } from "./context-templates.js";
+import { defaultConfig, readConfig } from "./config.js";
+import { createDesignMdIfMissing, DESIGN_MD_PATH } from "./design-md.js";
+import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { harnessConfigPath, harnessRoot } from "./harness-root.js";
+import { stringifyYaml } from "./yaml.js";
+export const migrations = [];
+export async function runMigrations(projectRoot) {
+    const report = { changed: [], skipped: [] };
+    const root = await harnessRoot(projectRoot);
+    await migrateConfig(projectRoot, root, report);
+    await migrateLegacyModulesToAreas(projectRoot, report);
+    await migrateBaseProjectContext(projectRoot, report);
+    await migrateContextManifest(projectRoot, report);
+    await migrateManifestModulePaths(projectRoot, report);
+    await migrateDesignMd(projectRoot, report);
+    return report;
+}
+async function migrateBaseProjectContext(projectRoot, report) {
+    await ensureDir(path.join(projectRoot, "project_context", "areas"));
+    const files = [
+        ["project_context/global.md", globalContextTemplate()],
+        ["project_context/architecture.md", architectureContextTemplate()],
+        ["project_context/areas/main.md", areaContextTemplate("main")],
+        ["project_context/areas/main/verification.md", verificationContextTemplate("main")]
+    ];
+    for (const [relative, content] of files) {
+        const target = path.join(projectRoot, ...relative.split("/"));
+        if (await pathExists(target)) {
+            report.skipped.push(relative);
+            continue;
+        }
+        if (await writeTextIfChanged(target, content)) {
+            report.changed.push(relative);
+        }
+        else {
+            report.skipped.push(relative);
+        }
+    }
+    await migrateGlobalContextSections(projectRoot, report);
+}
+async function migrateGlobalContextSections(projectRoot, report) {
+    const relative = "project_context/global.md";
+    const target = path.join(projectRoot, ...relative.split("/"));
+    if (!(await pathExists(target))) {
+        return;
+    }
+    const original = await readText(target);
+    const rewritten = rewriteLegacyModuleReferences(original);
+    const additions = [];
+    if (!hasHeading(rewritten, "Architecture Context")) {
+        additions.push("## Architecture Context", "", "- See `project_context/architecture.md` for the restrained architecture context.", "");
+    }
+    if (!hasHeading(rewritten, "Context Graph")) {
+        additions.push("## Context Graph", "", "- See `project_context/context.toml` for area/context_unit roles, read policy and boundary metadata.", "");
+    }
+    if (!hasHeading(rewritten, "Context Index")) {
+        additions.push("## Context Index", "", "- See `project_context/context.toml` for the current area and context node list.", "");
+    }
+    if (additions.length === 0 && rewritten === original) {
+        return;
+    }
+    const next = additions.length === 0 ? rewritten : `${rewritten.replace(/\s*$/, "\n\n")}${additions.join("\n")}`;
+    if (await writeTextIfChanged(target, next)) {
+        report.changed.push(`${relative}#schema-v4-sections`);
+    }
+}
+async function migrateContextManifest(projectRoot, report) {
+    const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
+    if (await pathExists(manifestPath)) {
+        report.skipped.push(CONTEXT_MANIFEST_PATH);
+        return;
+    }
+    if (await writeTextIfChanged(manifestPath, await contextManifestFromExistingAreas(projectRoot))) {
+        report.changed.push(CONTEXT_MANIFEST_PATH);
+    }
+    else {
+        report.skipped.push(CONTEXT_MANIFEST_PATH);
+    }
+}
+async function migrateLegacyModulesToAreas(projectRoot, report) {
+    const modulesRoot = path.join(projectRoot, "project_context", "modules");
+    const areasRoot = path.join(projectRoot, "project_context", "areas");
+    const moduleFiles = (await listFiles(modulesRoot)).filter((file) => file.endsWith(".md")).sort();
+    if (moduleFiles.length === 0) {
+        report.skipped.push("project_context/modules");
+        return;
+    }
+    await ensureDir(areasRoot);
+    for (const source of moduleFiles) {
+        const relativeToModules = path.relative(modulesRoot, source);
+        const target = path.join(areasRoot, relativeToModules);
+        const sourceRelative = `project_context/modules/${relativeToModules.split(path.sep).join("/")}`;
+        const targetRelative = `project_context/areas/${relativeToModules.split(path.sep).join("/")}`;
+        if (await pathExists(target)) {
+            report.skipped.push(`${sourceRelative} -> ${targetRelative}`);
+            continue;
+        }
+        await ensureDir(path.dirname(target));
+        await fs.rename(source, target);
+        report.changed.push(`${sourceRelative} -> ${targetRelative}`);
+    }
+    const remainingFiles = await listFiles(modulesRoot);
+    if (remainingFiles.length === 0 && await pathExists(modulesRoot)) {
+        await fs.rm(modulesRoot, { recursive: true, force: true });
+        report.changed.push("removed project_context/modules");
+    }
+}
+async function migrateManifestModulePaths(projectRoot, report) {
+    const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
+    if (!(await pathExists(manifestPath))) {
+        return;
+    }
+    const original = await readText(manifestPath);
+    const next = ensureManifestDefaultArea(rewriteLegacyModuleReferences(original));
+    if (next !== original && await writeTextIfChanged(manifestPath, next)) {
+        report.changed.push(`${CONTEXT_MANIFEST_PATH}#areas-paths`);
+    }
+}
+async function migrateDesignMd(projectRoot, report) {
+    if (await createDesignMdIfMissing(projectRoot)) {
+        report.changed.push(DESIGN_MD_PATH);
+    }
+    else {
+        report.skipped.push(DESIGN_MD_PATH);
+    }
+}
+async function migrateConfig(projectRoot, root, report) {
+    const relativeConfigPath = await harnessConfigPath(projectRoot);
+    const configPath = path.join(projectRoot, relativeConfigPath);
+    if (!(await pathExists(configPath))) {
+        report.skipped.push(relativeConfigPath);
+        return;
+    }
+    const config = await readConfig(projectRoot);
+    const current = defaultConfig(root);
+    config.core = current.core;
+    config.managed_files = current.managed_files;
+    config.never_overwrite = Array.from(new Set([...current.never_overwrite, ...config.never_overwrite]));
+    if (await writeTextIfChanged(configPath, stringifyYaml(config))) {
+        report.changed.push(relativeConfigPath);
+    }
+    else {
+        report.skipped.push(relativeConfigPath);
+    }
+}
+function hasHeading(content, heading) {
+    const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`^##\\s+${escaped}\\s*$`, "im").test(content);
+}
+function rewriteLegacyModuleReferences(content) {
+    return content
+        .replace(/project_context\/modules\//g, "project_context/areas/")
+        .replace(/\(modules\//g, "(areas/");
+}
+function ensureManifestDefaultArea(content) {
+    if (/^\s*default\s*=\s*true\s*$/im.test(content)) {
+        return content;
+    }
+    const lines = content.split(/\r?\n/);
+    const firstAreaIndex = lines.findIndex((line) => line.trim() === "[[areas]]");
+    if (firstAreaIndex === -1) {
+        return content;
+    }
+    let nextTableIndex = lines.findIndex((line, index) => index > firstAreaIndex && /^\s*\[\[/.test(line));
+    if (nextTableIndex === -1) {
+        nextTableIndex = lines.length;
+    }
+    for (let index = firstAreaIndex + 1; index < nextTableIndex; index += 1) {
+        if (/^\s*default\s*=/.test(lines[index])) {
+            lines[index] = "default = true";
+            return lines.join("\n");
+        }
+    }
+    lines.splice(nextTableIndex, 0, "default = true");
+    return lines.join("\n");
+}

package/dist/lib/package-json-config.d.ts

@@ -0,0 +1,2 @@
+export declare function packageHarnessRoot(projectRoot: string): Promise<string | undefined>;
+export declare function writePackageHarnessRoot(projectRoot: string, folderName: string): Promise<boolean>;

package/dist/lib/package-json-config.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { normalizeHarnessFolderName } from "./harness-root.js";
+export async function packageHarnessRoot(projectRoot) {
+    const packagePath = path.join(projectRoot, "package.json");
+    if (!(await pathExists(packagePath))) {
+        return undefined;
+    }
+    const packageJson = parsePackageJson(await readText(packagePath));
+    const config = packageJson.sdlcHarness;
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        return undefined;
+    }
+    const value = config.harnessFolderName;
+    return typeof value === "string" && value.trim() ? normalizeHarnessFolderName(value) : undefined;
+}
+export async function writePackageHarnessRoot(projectRoot, folderName) {
+    const normalized = normalizeHarnessFolderName(folderName);
+    const packagePath = path.join(projectRoot, "package.json");
+    const packageJson = (await pathExists(packagePath)) ? parsePackageJson(await readText(packagePath)) : {};
+    const existingConfig = packageJson.sdlcHarness;
+    const nextConfig = existingConfig && typeof existingConfig === "object" && !Array.isArray(existingConfig)
+        ? { ...existingConfig, harnessFolderName: normalized }
+        : { harnessFolderName: normalized };
+    const next = {
+        ...packageJson,
+        sdlcHarness: nextConfig
+    };
+    return writeTextIfChanged(packagePath, `${JSON.stringify(next, null, 2)}\n`);
+}
+function parsePackageJson(content) {
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("package.json must contain a JSON object");
+    }
+    return parsed;
+}

package/dist/lib/package-source.d.ts

@@ -0,0 +1,8 @@
+export interface PackageSourceSyncReport {
+    changed: string[];
+}
+export interface PackageSourceCheckReport {
+    drift: string[];
+}
+export declare function syncSource(projectRoot: string): Promise<PackageSourceSyncReport>;
+export declare function checkSource(projectRoot: string): Promise<PackageSourceCheckReport>;

package/dist/lib/package-source.js

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { AGENTS_BLOCK_MARKERS } from "./managed-file.js";
+import { SOURCE_MAPPINGS_PATH } from "./paths.js";
+import { parseYaml } from "./yaml.js";
+export async function syncSource(projectRoot) {
+    const report = { changed: [] };
+    for (const mapping of await readSourceMappings(projectRoot)) {
+        const changed = await applyMapping(projectRoot, mapping);
+        report.changed.push(...changed);
+    }
+    return report;
+}
+export async function checkSource(projectRoot) {
+    const drift = [];
+    for (const mapping of await readSourceMappings(projectRoot)) {
+        const expected = await renderMapping(projectRoot, mapping);
+        const target = path.join(projectRoot, mapping.target);
+        if (typeof expected === "string") {
+            const existing = (await pathExists(target)) ? await readText(target) : "";
+            if (normalize(existing) !== normalize(expected)) {
+                drift.push(mapping.target);
+            }
+            continue;
+        }
+        const sourceHashes = new Map();
+        for (const item of expected) {
+            sourceHashes.set(item.relative, hash(item.content));
+            const targetFile = path.join(target, item.relative);
+            const existing = (await pathExists(targetFile)) ? await readText(targetFile) : "";
+            if (hash(existing) !== hash(item.content)) {
+                drift.push(`${mapping.target}/${item.relative}`);
+            }
+        }
+        const targetFiles = await listFiles(target);
+        for (const targetFile of targetFiles) {
+            if (path.basename(targetFile) === ".gitkeep") {
+                continue;
+            }
+            const relative = path.relative(target, targetFile);
+            if (!sourceHashes.has(relative)) {
+                drift.push(`${mapping.target}/${relative}`);
+            }
+        }
+    }
+    return { drift };
+}
+async function readSourceMappings(projectRoot) {
+    const mappingPath = path.join(projectRoot, SOURCE_MAPPINGS_PATH);
+    const parsed = parseYaml(await readText(mappingPath));
+    return parsed.source_mappings ?? [];
+}
+async function applyMapping(projectRoot, mapping) {
+    const target = path.join(projectRoot, mapping.target);
+    const rendered = await renderMapping(projectRoot, mapping);
+    if (typeof rendered === "string") {
+        return (await writeTextIfChanged(target, rendered)) ? [mapping.target] : [];
+    }
+    await fs.rm(target, { recursive: true, force: true });
+    await ensureDir(target);
+    const changed = [];
+    for (const item of rendered) {
+        const targetFile = path.join(target, item.relative);
+        if (await writeTextIfChanged(targetFile, item.content)) {
+            changed.push(`${mapping.target}/${item.relative}`);
+        }
+    }
+    return changed;
+}
+async function renderMapping(projectRoot, mapping) {
+    const source = path.join(projectRoot, mapping.source);
+    if (mapping.mode === "copy-file") {
+        return readText(source);
+    }
+    if (mapping.mode === "copy-tree") {
+        const files = await listFiles(source);
+        const rendered = [];
+        for (const file of files) {
+            if (path.basename(file) === ".gitkeep") {
+                continue;
+            }
+            const relative = path.relative(source, file);
+            if (isExcluded(relative, mapping.exclude ?? [])) {
+                continue;
+            }
+            rendered.push({ relative, content: await readText(file) });
+        }
+        return rendered;
+    }
+    if (mapping.mode === "extract-managed-block") {
+        const content = await readText(source);
+        for (const markers of AGENTS_BLOCK_MARKERS) {
+            const start = content.indexOf(markers.start);
+            const end = content.indexOf(markers.end);
+            if (start >= 0 && end > start) {
+                return `${content.slice(start + markers.start.length, end).trim()}\n`;
+            }
+        }
+        return content;
+    }
+    if (mapping.mode === "extract-harness-targets") {
+        return readText(source);
+    }
+    throw new Error(`Unsupported source mapping mode: ${mapping.mode}`);
+}
+function isExcluded(relativePath, patterns) {
+    const normalized = relativePath.split(path.sep).join("/");
+    return patterns.some((pattern) => {
+        const normalizedPattern = pattern.replace(/\\/g, "/");
+        if (normalizedPattern.endsWith("/**")) {
+            const prefix = normalizedPattern.slice(0, -3);
+            return normalized === prefix || normalized.startsWith(`${prefix}/`);
+        }
+        return normalized === normalizedPattern;
+    });
+}
+function normalize(content) {
+    return content.replace(/\r\n/g, "\n").trimEnd();
+}
+function hash(content) {
+    return createHash("sha256").update(normalize(content)).digest("hex");
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,5 @@
+export declare const SOURCE_MAPPINGS_PATH = "packages/sdlc-harness/source-mappings.yaml";
+export declare const DEFAULT_HARNESS_ROOT = ".agent";
+export declare const HARNESS_JSON_CONFIG_PATH = "sdlc-harness.config.json";
+export declare function packageRoot(): string;
+export declare function packageAssetPath(...segments: string[]): string;

package/dist/lib/paths.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const SOURCE_MAPPINGS_PATH = "packages/sdlc-harness/source-mappings.yaml";
+export const DEFAULT_HARNESS_ROOT = ".agent";
+export const HARNESS_JSON_CONFIG_PATH = "sdlc-harness.config.json";
+export function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+}
+export function packageAssetPath(...segments) {
+    return path.join(packageRoot(), "assets", ...segments);
+}

package/dist/lib/schema-guard.d.ts

@@ -0,0 +1,3 @@
+export declare function assertSupportedSchema(projectRoot: string, commandName: string): Promise<void>;
+export declare function unsupportedSchemaMessage(schemaVersion: string, commandName: string): string | undefined;
+export declare function schemaMajor(schemaVersion: string): number | undefined;

package/dist/lib/schema-guard.js

@@ -0,0 +1,28 @@
+import { readConfig } from "./config.js";
+import { CANONICAL_NPX_COMMAND, CURRENT_SCHEMA_VERSION } from "./constants.js";
+export async function assertSupportedSchema(projectRoot, commandName) {
+    const config = await readConfig(projectRoot);
+    const message = unsupportedSchemaMessage(config.core.schema_version, commandName);
+    if (message) {
+        throw new Error(message);
+    }
+}
+export function unsupportedSchemaMessage(schemaVersion, commandName) {
+    const projectMajor = schemaMajor(schemaVersion);
+    const supportedMajor = schemaMajor(CURRENT_SCHEMA_VERSION);
+    if (projectMajor === undefined || supportedMajor === undefined || projectMajor <= supportedMajor) {
+        return undefined;
+    }
+    return [
+        `unsupported Harness schema version ${schemaVersion}; this CLI supports schema ${CURRENT_SCHEMA_VERSION}`,
+        `Refusing to run ${commandName} because older CLI versions must not rewrite newer projects`,
+        `Use the canonical latest CLI: ${CANONICAL_NPX_COMMAND} ${commandName}`
+    ].join(". ");
+}
+export function schemaMajor(schemaVersion) {
+    const match = /^(\d+)/.exec(String(schemaVersion).trim());
+    if (!match) {
+        return undefined;
+    }
+    return Number.parseInt(match[1], 10);
+}

package/dist/lib/sync-engine.d.ts

@@ -0,0 +1,7 @@
+export interface SyncReport {
+    changed: string[];
+    skipped: string[];
+    blocked: string[];
+}
+export declare function emptySyncReport(): SyncReport;
+export declare function runSync(projectRoot: string): Promise<SyncReport>;