@growth-labs/cms 0.3.0 → 0.3.1

package/README.md

@@ -168,6 +168,49 @@ manual publish with a 409 and leaves the content status unchanged; throwing from
 the hook fails closed with a 503. This keeps media-specific readiness checks in
 the host site while preventing a configured site from bypassing them.
 
+## Consumer D1 migrations
+
+Wrangler accepts one `migrations_dir`, while a site commonly already owns
+numbered analytics, SEO, or product migrations. Vendor the exact SQL from the
+installed CMS package into that existing directory, review it, and commit it:
+
+```bash
+pnpm exec growth-labs-cms-migrations sync --dir migrations --start 10
+pnpm exec growth-labs-cms-migrations verify --dir migrations
+```
+
+`--start` is the first unused site sequence and is mandatory. `sync` reserves a
+contiguous range, copies every package migration without rewriting it, and writes
+`migrations/.growth-labs-cms-migrations.json` with the package version and SHA-256
+receipt. It fails before writing if any site SQL already owns a reserved sequence.
+Existing managed SQL is never overwritten: consumer drift, upstream mutation of
+an already-vendored migration, a changed starting sequence, or a symlink target
+fails closed.
+
+The default receipt path is the only manifest allowed inside `migrations/`.
+When `--manifest` is supplied, it must name a `.json` file outside the migrations
+directory whose parent is an existing non-symlink directory; it can never
+collide with or become Wrangler SQL. Sync stages the full SQL set and receipt
+before linking targets. A later link, verification, or receipt failure removes
+every SQL file created by that attempt. An interrupted process may leave only
+exact-hash linked SQL and/or `*.tmp-<uuid>` staging files, but no valid completed
+receipt; `verify` therefore fails closed until a repeated `sync` reconciles the
+batch. Wrangler ignores the temp files, which are safe to delete after the
+repeated sync and verify succeed. Never run the managed D1 workflow without the
+required verify step.
+
+Both `sync` and `verify` acquire an exclusive adjacent `<receipt>.lock` file,
+so concurrent invocations fail closed instead of racing the manifest update.
+An abruptly terminated process can leave a stale lock; first confirm no vendor
+or verify process is running, then remove only that lock and repeat `sync`
+followed by `verify`.
+
+Run `sync` deliberately after a package upgrade, inspect and commit the new SQL
+and receipt, then require `verify` in pull-request CI before the managed D1
+migration workflow. The command only reads and writes local files; it never opens
+a network connection or applies a database migration. Do not call schema setup
+from a request handler.
+
 ## Bounded publication kernel
 
 `publishOne` is the build-independent publication path for a single content item.

package/dist/cli/migrations.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=migrations.d.ts.map

package/dist/cli/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/cli/migrations.ts"],"names":[],"mappings":""}

package/dist/cli/migrations.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { syncCmsMigrations, verifyCmsMigrations } from '../migration-vendor.js';
+function usage() {
+    return [
+        'Usage:',
+        '  growth-labs-cms-migrations sync --dir <migrations-dir> --start <positive-integer>',
+        '  growth-labs-cms-migrations verify --dir <migrations-dir>',
+        '',
+        'Optional for both commands: --manifest <receipt-path>',
+    ].join('\n');
+}
+function requireValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--'))
+        throw new Error(`${flag} requires a value`);
+    return value;
+}
+function parseArgs(argv) {
+    const command = argv[0];
+    if (command !== 'sync' && command !== 'verify')
+        throw new Error(usage());
+    let migrationsDir;
+    let startSequence;
+    let manifestPath;
+    for (let index = 1; index < argv.length; index += 1) {
+        const flag = argv[index];
+        if (flag === '--dir') {
+            migrationsDir = requireValue(argv, index, flag);
+            index += 1;
+            continue;
+        }
+        if (flag === '--start') {
+            startSequence = Number(requireValue(argv, index, flag));
+            index += 1;
+            continue;
+        }
+        if (flag === '--manifest') {
+            manifestPath = requireValue(argv, index, flag);
+            index += 1;
+            continue;
+        }
+        throw new Error(`unknown argument: ${flag}\n\n${usage()}`);
+    }
+    if (!migrationsDir)
+        throw new Error(`--dir is required\n\n${usage()}`);
+    if (command === 'sync' && startSequence === undefined) {
+        throw new Error(`--start is required for sync\n\n${usage()}`);
+    }
+    if (command === 'verify' && startSequence !== undefined) {
+        throw new Error('--start is read from the committed manifest during verify');
+    }
+    return { command, migrationsDir, startSequence, manifestPath };
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const result = args.command === 'sync'
+        ? await syncCmsMigrations({
+            migrationsDir: args.migrationsDir,
+            startSequence: args.startSequence,
+            manifestPath: args.manifestPath,
+        })
+        : await verifyCmsMigrations({
+            migrationsDir: args.migrationsDir,
+            manifestPath: args.manifestPath,
+        });
+    process.stdout.write(`${JSON.stringify({ ok: true, command: args.command, ...result })}\n`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`growth-labs-cms-migrations: ${message}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=migrations.js.map

package/dist/cli/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../src/cli/migrations.ts"],"names":[],"mappings":"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"}

package/dist/migration-vendor-files.d.ts

@@ -0,0 +1,17 @@
+export interface StagedMigrationVendorFile {
+    tempPath: string;
+    targetPath: string;
+}
+export interface MigrationVendorFileOperations {
+    link(source: string, target: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+}
+export declare function rollbackNewFiles(paths: string[], operations?: MigrationVendorFileOperations): Promise<void>;
+/**
+ * Link every pre-staged file without replacing an existing directory entry.
+ * A later failure removes all targets linked by this attempt and every temp.
+ */
+export declare function commitNewFilesAtomically(files: StagedMigrationVendorFile[], operations?: MigrationVendorFileOperations): Promise<string[]>;
+/** Commit staged SQL, then run the receipt/final verification boundary. */
+export declare function commitStagedMigrationBatch(files: StagedMigrationVendorFile[], finalize: () => Promise<void>, operations?: MigrationVendorFileOperations): Promise<string[]>;
+//# sourceMappingURL=migration-vendor-files.d.ts.map

package/dist/migration-vendor-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-vendor-files.d.ts","sourceRoot":"","sources":["../src/migration-vendor-files.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,yBAAyB;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,6BAA6B;IAC7C,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAmBD,wBAAsB,gBAAgB,CACrC,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,GAAE,6BAAkD,GAC5D,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC7C,KAAK,EAAE,yBAAyB,EAAE,EAClC,UAAU,GAAE,6BAAkD,GAC5D,OAAO,CAAC,MAAM,EAAE,CAAC,CA8BnB;AAED,2EAA2E;AAC3E,wBAAsB,0BAA0B,CAC/C,KAAK,EAAE,yBAAyB,EAAE,EAClC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAC7B,UAAU,GAAE,6BAAkD,GAC5D,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB"}

package/dist/migration-vendor-files.js

@@ -0,0 +1,67 @@
+import { link, unlink } from 'node:fs/promises';
+const DEFAULT_OPERATIONS = { link, unlink };
+async function removePaths(paths, operations) {
+    const errors = [];
+    for (const path of [...paths].reverse()) {
+        try {
+            await operations.unlink(path);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                errors.push(error);
+        }
+    }
+    return errors;
+}
+export async function rollbackNewFiles(paths, operations = DEFAULT_OPERATIONS) {
+    const errors = await removePaths(paths, operations);
+    if (errors.length > 0) {
+        throw new AggregateError(errors, 'failed to roll back newly linked CMS migration files');
+    }
+}
+/**
+ * Link every pre-staged file without replacing an existing directory entry.
+ * A later failure removes all targets linked by this attempt and every temp.
+ */
+export async function commitNewFilesAtomically(files, operations = DEFAULT_OPERATIONS) {
+    const committed = [];
+    let failure;
+    try {
+        for (const file of files) {
+            await operations.link(file.tempPath, file.targetPath);
+            committed.push(file.targetPath);
+        }
+    }
+    catch (error) {
+        failure = error;
+    }
+    const cleanupErrors = await removePaths(files.map((file) => file.tempPath), operations);
+    if (failure) {
+        const rollbackErrors = await removePaths(committed, operations);
+        const errors = [failure, ...cleanupErrors, ...rollbackErrors].filter((error) => error !== undefined);
+        const primary = failure instanceof Error ? `: ${failure.message}` : '';
+        throw new AggregateError(errors, `CMS migration file commit failed${primary}`);
+    }
+    // A hard-linked target remains valid when unlinking only its staged temp
+    // fails. The caller's outer finally retries temp cleanup; rolling targets
+    // back here would turn a harmless leftover temp into data loss.
+    return committed;
+}
+/** Commit staged SQL, then run the receipt/final verification boundary. */
+export async function commitStagedMigrationBatch(files, finalize, operations = DEFAULT_OPERATIONS) {
+    const committed = await commitNewFilesAtomically(files, operations);
+    try {
+        await finalize();
+        return committed;
+    }
+    catch (error) {
+        try {
+            await rollbackNewFiles(committed, operations);
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], 'CMS migration batch finalization failed and rollback was incomplete');
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=migration-vendor-files.js.map

package/dist/migration-vendor-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-vendor-files.js","sourceRoot":"","sources":["../src/migration-vendor-files.ts"],"names":[],"mappings":"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"}

package/dist/migration-vendor.d.ts

@@ -0,0 +1,26 @@
+declare const PACKAGE_NAME = "@growth-labs/cms";
+export interface SyncCmsMigrationsOptions {
+    /** Existing consumer-owned Wrangler migrations directory. */
+    migrationsDir: string;
+    /** First unused sequence number reserved for the package migrations. */
+    startSequence: number;
+    /** Override only when a consumer keeps the receipt outside migrationsDir. */
+    manifestPath?: string;
+}
+export interface VerifyCmsMigrationsOptions {
+    migrationsDir: string;
+    manifestPath?: string;
+}
+export interface CmsMigrationVendorResult {
+    packageName: typeof PACKAGE_NAME;
+    packageVersion: string;
+    startSequence: number;
+    managedFiles: string[];
+    written: number;
+    verified: number;
+    manifestPath: string;
+}
+export declare function syncCmsMigrations(options: SyncCmsMigrationsOptions): Promise<CmsMigrationVendorResult>;
+export declare function verifyCmsMigrations(options: VerifyCmsMigrationsOptions): Promise<CmsMigrationVendorResult>;
+export {};
+//# sourceMappingURL=migration-vendor.d.ts.map

package/dist/migration-vendor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-vendor.d.ts","sourceRoot":"","sources":["../src/migration-vendor.ts"],"names":[],"mappings":"AAiBA,QAAA,MAAM,YAAY,qBAAqB,CAAA;AAgCvC,MAAM,WAAW,wBAAwB;IACxC,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,0BAA0B;IAC1C,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,wBAAwB;IACxC,WAAW,EAAE,OAAO,YAAY,CAAA;IAChC,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;CACpB;AAgSD,wBAAsB,iBAAiB,CACtC,OAAO,EAAE,wBAAwB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAiDnC;AAED,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,0BAA0B,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAmCnC"}

package/dist/migration-vendor.js

@@ -0,0 +1,321 @@
+import { link, lstat, readdir, readFile, realpath, rename, unlink, writeFile, } from 'node:fs/promises';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { commitStagedMigrationBatch, } from './migration-vendor-files.js';
+const PACKAGE_NAME = '@growth-labs/cms';
+const MANIFEST_NAME = '.growth-labs-cms-migrations.json';
+const MANIFEST_SCHEMA_VERSION = 1;
+const MIGRATION_FILE = /^\d{4}_[a-z0-9][a-z0-9_-]*\.sql$/;
+async function packageContract() {
+    const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+    const packageJsonPath = join(packageRoot, 'package.json');
+    const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+    if (packageJson.name !== PACKAGE_NAME || !packageJson.version) {
+        throw new Error('installed CMS package metadata is invalid');
+    }
+    return {
+        packageVersion: packageJson.version,
+        sourceDir: join(packageRoot, 'migrations'),
+    };
+}
+async function sha256(bytes) {
+    const input = new Uint8Array(bytes.byteLength);
+    input.set(bytes);
+    const digest = await crypto.subtle.digest('SHA-256', input.buffer);
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+async function requireExistingDirectory(path, label = 'migrationsDir') {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch {
+        throw new Error(`${label} must be an existing directory: ${path}`);
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`${label} must be an existing non-symlink directory: ${path}`);
+    }
+    return realpath(path);
+}
+function assertStartSequence(value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error('startSequence must be a positive integer');
+    }
+}
+function sequencePrefix(sequence) {
+    return String(sequence).padStart(4, '0');
+}
+async function planMigrations(sourceDir, startSequence) {
+    assertStartSequence(startSequence);
+    const sourceNames = (await readdir(sourceDir)).filter((name) => MIGRATION_FILE.test(name)).sort();
+    if (sourceNames.length === 0)
+        throw new Error('installed CMS package has no migration SQL');
+    if (startSequence + sourceNames.length - 1 > 9999) {
+        throw new Error('reserved CMS migration sequence exceeds 9999');
+    }
+    return Promise.all(sourceNames.map(async (source, index) => {
+        const sequence = startSequence + index;
+        const suffix = source.replace(/^\d{4}_/, '');
+        const target = `${sequencePrefix(sequence)}_growth_labs_cms_${suffix}`;
+        const bytes = new Uint8Array(await readFile(join(sourceDir, source)));
+        return { source, target, sequence, sha256: await sha256(bytes), bytes };
+    }));
+}
+function manifestFor(packageVersion, startSequence, plan) {
+    return {
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
+        packageName: PACKAGE_NAME,
+        packageVersion,
+        startSequence,
+        files: plan.map(({ source, target, sha256: hash }) => ({ source, target, sha256: hash })),
+    };
+}
+async function readManifest(path) {
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`CMS migration manifest must be a regular file: ${path}`);
+        }
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        if (parsed.schemaVersion !== MANIFEST_SCHEMA_VERSION ||
+            parsed.packageName !== PACKAGE_NAME ||
+            !parsed.packageVersion ||
+            !Number.isSafeInteger(parsed.startSequence) ||
+            parsed.startSequence < 1 ||
+            !Array.isArray(parsed.files)) {
+            throw new Error(`CMS migration manifest is invalid: ${path}`);
+        }
+        for (const entry of parsed.files) {
+            if (!entry ||
+                typeof entry.source !== 'string' ||
+                typeof entry.target !== 'string' ||
+                !MIGRATION_FILE.test(entry.source) ||
+                !MIGRATION_FILE.test(entry.target) ||
+                !/^([a-f0-9]{64})$/.test(entry.sha256)) {
+                throw new Error(`CMS migration manifest contains an invalid file entry: ${path}`);
+            }
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function entriesEqual(left, right) {
+    return (left.source === right.source && left.target === right.target && left.sha256 === right.sha256);
+}
+function assertManifestCanAdvance(current, next) {
+    if (!current)
+        return;
+    if (current.startSequence !== next.startSequence) {
+        throw new Error(`CMS migration manifest reserves startSequence ${current.startSequence}; received ${next.startSequence}`);
+    }
+    if (current.files.length > next.files.length) {
+        throw new Error('installed CMS package removed migrations recorded by the consumer manifest');
+    }
+    for (const [index, entry] of current.files.entries()) {
+        const nextEntry = next.files[index];
+        if (!nextEntry || !entriesEqual(entry, nextEntry)) {
+            throw new Error(`installed CMS migration changed after vendoring: ${entry.source}`);
+        }
+    }
+}
+async function assertNoSequenceCollisions(migrationsDir, plan) {
+    const existing = await readdir(migrationsDir);
+    for (const migration of plan) {
+        const prefix = `${sequencePrefix(migration.sequence)}_`;
+        const collisions = existing.filter((name) => name.endsWith('.sql') && name.startsWith(prefix) && name !== migration.target);
+        if (collisions.length > 0) {
+            throw new Error(`reserved sequence ${sequencePrefix(migration.sequence)} collides with ${collisions.join(', ')}`);
+        }
+    }
+}
+async function verifyTargets(migrationsDir, plan, allowMissing) {
+    let verified = 0;
+    const missing = [];
+    for (const migration of plan) {
+        const targetPath = join(migrationsDir, migration.target);
+        try {
+            const stat = await lstat(targetPath);
+            if (!stat.isFile() || stat.isSymbolicLink()) {
+                throw new Error(`managed CMS migration must be a regular file: ${migration.target}`);
+            }
+            const targetHash = await sha256(new Uint8Array(await readFile(targetPath)));
+            if (targetHash !== migration.sha256) {
+                throw new Error(`CMS migration hash mismatch: ${migration.target}`);
+            }
+            verified += 1;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && allowMissing) {
+                missing.push(migration);
+                continue;
+            }
+            throw error;
+        }
+    }
+    return { verified, missing };
+}
+async function stageNewFile(path, bytes) {
+    const temp = `${path}.tmp-${crypto.randomUUID()}`;
+    await writeFile(temp, bytes, { flag: 'wx' });
+    return temp;
+}
+async function stageManifest(path, manifest) {
+    const temp = `${path}.tmp-${crypto.randomUUID()}`;
+    await writeFile(temp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+    return temp;
+}
+async function commitManifest(tempPath, manifestPath, currentManifest) {
+    if (currentManifest) {
+        const latest = await readManifest(manifestPath);
+        if (!latest || JSON.stringify(latest) !== JSON.stringify(currentManifest)) {
+            throw new Error('CMS migration manifest changed during sync');
+        }
+        await rename(tempPath, manifestPath);
+        return;
+    }
+    await link(tempPath, manifestPath);
+}
+function isInsideDirectory(directory, path) {
+    const fromDirectory = relative(directory, path);
+    return (fromDirectory === '' ||
+        (!fromDirectory.startsWith(`..${sep}`) && fromDirectory !== '..' && !isAbsolute(fromDirectory)));
+}
+async function resolveManifestPath(migrationsDir, override) {
+    if (!override)
+        return join(migrationsDir, MANIFEST_NAME);
+    const requested = resolve(override);
+    if (extname(requested).toLowerCase() !== '.json') {
+        throw new Error('CMS migration manifest override must be a .json file');
+    }
+    if (isInsideDirectory(migrationsDir, requested)) {
+        throw new Error('CMS migration manifest override must be outside migrationsDir');
+    }
+    const parent = await requireExistingDirectory(dirname(requested), 'manifest parent');
+    const resolvedPath = join(parent, basename(requested));
+    if (isInsideDirectory(migrationsDir, resolvedPath)) {
+        throw new Error('CMS migration manifest override must be outside migrationsDir');
+    }
+    return resolvedPath;
+}
+async function withManifestLock(manifestPath, action) {
+    const lockPath = `${manifestPath}.lock`;
+    try {
+        await writeFile(lockPath, `${JSON.stringify({ pid: process.pid, startedAt: Date.now() })}\n`, {
+            flag: 'wx',
+            mode: 0o600,
+        });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new Error(`another CMS migration operation is already active: ${lockPath}`);
+        }
+        throw error;
+    }
+    let result;
+    let operationError;
+    try {
+        result = await action();
+    }
+    catch (error) {
+        operationError = error;
+    }
+    let releaseError;
+    try {
+        await unlink(lockPath);
+    }
+    catch (error) {
+        releaseError = error;
+    }
+    if (operationError && releaseError) {
+        throw new AggregateError([operationError, releaseError], 'CMS migration operation failed and its receipt lock could not be released');
+    }
+    if (operationError)
+        throw operationError;
+    if (releaseError)
+        throw releaseError;
+    return result;
+}
+export async function syncCmsMigrations(options) {
+    assertStartSequence(options.startSequence);
+    const migrationsDir = await requireExistingDirectory(resolve(options.migrationsDir));
+    const manifestPath = await resolveManifestPath(migrationsDir, options.manifestPath);
+    return withManifestLock(manifestPath, async () => {
+        const contract = await packageContract();
+        const plan = await planMigrations(contract.sourceDir, options.startSequence);
+        const nextManifest = manifestFor(contract.packageVersion, options.startSequence, plan);
+        const currentManifest = await readManifest(manifestPath);
+        assertManifestCanAdvance(currentManifest, nextManifest);
+        await assertNoSequenceCollisions(migrationsDir, plan);
+        const preflight = await verifyTargets(migrationsDir, plan, true);
+        const staged = [];
+        let manifestTemp = null;
+        let verified = 0;
+        try {
+            for (const migration of preflight.missing) {
+                const targetPath = join(migrationsDir, migration.target);
+                staged.push({
+                    targetPath,
+                    tempPath: await stageNewFile(targetPath, migration.bytes),
+                });
+            }
+            const stagedManifest = await stageManifest(manifestPath, nextManifest);
+            manifestTemp = stagedManifest;
+            await commitStagedMigrationBatch(staged, async () => {
+                await assertNoSequenceCollisions(migrationsDir, plan);
+                const final = await verifyTargets(migrationsDir, plan, false);
+                verified = final.verified;
+                await commitManifest(stagedManifest, manifestPath, currentManifest);
+            });
+            return {
+                packageName: PACKAGE_NAME,
+                packageVersion: contract.packageVersion,
+                startSequence: options.startSequence,
+                managedFiles: plan.map(({ target }) => target),
+                written: preflight.missing.length,
+                verified,
+                manifestPath,
+            };
+        }
+        finally {
+            await Promise.all([
+                ...staged.map(({ tempPath }) => unlink(tempPath).catch(() => { })),
+                ...(manifestTemp ? [unlink(manifestTemp).catch(() => { })] : []),
+            ]);
+        }
+    });
+}
+export async function verifyCmsMigrations(options) {
+    const migrationsDir = await requireExistingDirectory(resolve(options.migrationsDir));
+    const manifestPath = await resolveManifestPath(migrationsDir, options.manifestPath);
+    return withManifestLock(manifestPath, async () => {
+        const manifest = await readManifest(manifestPath);
+        if (!manifest)
+            throw new Error(`CMS migration manifest is missing: ${manifestPath}`);
+        const contract = await packageContract();
+        if (manifest.packageVersion !== contract.packageVersion) {
+            throw new Error(`CMS migration manifest version ${manifest.packageVersion} does not match installed ${contract.packageVersion}`);
+        }
+        const plan = await planMigrations(contract.sourceDir, manifest.startSequence);
+        const expected = manifestFor(contract.packageVersion, manifest.startSequence, plan);
+        if (expected.files.length !== manifest.files.length ||
+            expected.files.some((entry, index) => !entriesEqual(entry, manifest.files[index]))) {
+            throw new Error('CMS migration manifest does not match the installed package contract');
+        }
+        await assertNoSequenceCollisions(migrationsDir, plan);
+        const result = await verifyTargets(migrationsDir, plan, false);
+        return {
+            packageName: PACKAGE_NAME,
+            packageVersion: contract.packageVersion,
+            startSequence: manifest.startSequence,
+            managedFiles: plan.map(({ target }) => target),
+            written: 0,
+            verified: result.verified,
+            manifestPath,
+        };
+    });
+}
+//# sourceMappingURL=migration-vendor.js.map

package/dist/migration-vendor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-vendor.js","sourceRoot":"","sources":["../src/migration-vendor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@growth-labs/cms",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
+  "bin": {
+    "growth-labs-cms-migrations": "./dist/cli/migrations.js"
+  },
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
@@ -24,6 +27,10 @@
       "types": "./dist/integration/index.d.ts",
       "import": "./dist/integration/index.js"
     },
+    "./migration-vendor": {
+      "types": "./dist/migration-vendor.d.ts",
+      "import": "./dist/migration-vendor.js"
+    },
     "./ui": {
       "types": "./dist/ui/components/CmsApp.d.ts",
       "import": "./dist/ui/components/CmsApp.js"

package/src/cli/migrations.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import { syncCmsMigrations, verifyCmsMigrations } from '../migration-vendor.js'
+
+interface ParsedArgs {
+	command: 'sync' | 'verify'
+	migrationsDir: string
+	startSequence?: number
+	manifestPath?: string
+}
+
+function usage(): string {
+	return [
+		'Usage:',
+		'  growth-labs-cms-migrations sync --dir <migrations-dir> --start <positive-integer>',
+		'  growth-labs-cms-migrations verify --dir <migrations-dir>',
+		'',
+		'Optional for both commands: --manifest <receipt-path>',
+	].join('\n')
+}
+
+function requireValue(argv: string[], index: number, flag: string): string {
+	const value = argv[index + 1]
+	if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`)
+	return value
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+	const command = argv[0]
+	if (command !== 'sync' && command !== 'verify') throw new Error(usage())
+	let migrationsDir: string | undefined
+	let startSequence: number | undefined
+	let manifestPath: string | undefined
+
+	for (let index = 1; index < argv.length; index += 1) {
+		const flag = argv[index]
+		if (flag === '--dir') {
+			migrationsDir = requireValue(argv, index, flag)
+			index += 1
+			continue
+		}
+		if (flag === '--start') {
+			startSequence = Number(requireValue(argv, index, flag))
+			index += 1
+			continue
+		}
+		if (flag === '--manifest') {
+			manifestPath = requireValue(argv, index, flag)
+			index += 1
+			continue
+		}
+		throw new Error(`unknown argument: ${flag}\n\n${usage()}`)
+	}
+
+	if (!migrationsDir) throw new Error(`--dir is required\n\n${usage()}`)
+	if (command === 'sync' && startSequence === undefined) {
+		throw new Error(`--start is required for sync\n\n${usage()}`)
+	}
+	if (command === 'verify' && startSequence !== undefined) {
+		throw new Error('--start is read from the committed manifest during verify')
+	}
+	return { command, migrationsDir, startSequence, manifestPath }
+}
+
+async function main(): Promise<void> {
+	const args = parseArgs(process.argv.slice(2))
+	const result =
+		args.command === 'sync'
+			? await syncCmsMigrations({
+					migrationsDir: args.migrationsDir,
+					startSequence: args.startSequence as number,
+					manifestPath: args.manifestPath,
+				})
+			: await verifyCmsMigrations({
+					migrationsDir: args.migrationsDir,
+					manifestPath: args.manifestPath,
+				})
+	process.stdout.write(`${JSON.stringify({ ok: true, command: args.command, ...result })}\n`)
+}
+
+main().catch((error: unknown) => {
+	const message = error instanceof Error ? error.message : String(error)
+	process.stderr.write(`growth-labs-cms-migrations: ${message}\n`)
+	process.exitCode = 1
+})

package/src/migration-vendor-files.ts

@@ -0,0 +1,100 @@
+import { link, unlink } from 'node:fs/promises'
+
+export interface StagedMigrationVendorFile {
+	tempPath: string
+	targetPath: string
+}
+
+export interface MigrationVendorFileOperations {
+	link(source: string, target: string): Promise<void>
+	unlink(path: string): Promise<void>
+}
+
+const DEFAULT_OPERATIONS: MigrationVendorFileOperations = { link, unlink }
+
+async function removePaths(
+	paths: string[],
+	operations: MigrationVendorFileOperations,
+): Promise<unknown[]> {
+	const errors: unknown[] = []
+	for (const path of [...paths].reverse()) {
+		try {
+			await operations.unlink(path)
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'ENOENT') errors.push(error)
+		}
+	}
+	return errors
+}
+
+export async function rollbackNewFiles(
+	paths: string[],
+	operations: MigrationVendorFileOperations = DEFAULT_OPERATIONS,
+): Promise<void> {
+	const errors = await removePaths(paths, operations)
+	if (errors.length > 0) {
+		throw new AggregateError(errors, 'failed to roll back newly linked CMS migration files')
+	}
+}
+
+/**
+ * Link every pre-staged file without replacing an existing directory entry.
+ * A later failure removes all targets linked by this attempt and every temp.
+ */
+export async function commitNewFilesAtomically(
+	files: StagedMigrationVendorFile[],
+	operations: MigrationVendorFileOperations = DEFAULT_OPERATIONS,
+): Promise<string[]> {
+	const committed: string[] = []
+	let failure: unknown
+
+	try {
+		for (const file of files) {
+			await operations.link(file.tempPath, file.targetPath)
+			committed.push(file.targetPath)
+		}
+	} catch (error) {
+		failure = error
+	}
+
+	const cleanupErrors = await removePaths(
+		files.map((file) => file.tempPath),
+		operations,
+	)
+	if (failure) {
+		const rollbackErrors = await removePaths(committed, operations)
+		const errors = [failure, ...cleanupErrors, ...rollbackErrors].filter(
+			(error): error is NonNullable<unknown> => error !== undefined,
+		)
+		const primary = failure instanceof Error ? `: ${failure.message}` : ''
+		throw new AggregateError(errors, `CMS migration file commit failed${primary}`)
+	}
+	// A hard-linked target remains valid when unlinking only its staged temp
+	// fails. The caller's outer finally retries temp cleanup; rolling targets
+	// back here would turn a harmless leftover temp into data loss.
+
+	return committed
+}
+
+/** Commit staged SQL, then run the receipt/final verification boundary. */
+export async function commitStagedMigrationBatch(
+	files: StagedMigrationVendorFile[],
+	finalize: () => Promise<void>,
+	operations: MigrationVendorFileOperations = DEFAULT_OPERATIONS,
+): Promise<string[]> {
+	const committed = await commitNewFilesAtomically(files, operations)
+	try {
+		await finalize()
+		return committed
+	} catch (error) {
+		try {
+			await rollbackNewFiles(committed, operations)
+		} catch (rollbackError) {
+			throw new AggregateError(
+				[error, rollbackError],
+				'CMS migration batch finalization failed and rollback was incomplete',
+			)
+		}
+		throw error
+	}
+}

package/src/migration-vendor.ts

@@ -0,0 +1,450 @@
+import {
+	link,
+	lstat,
+	readdir,
+	readFile,
+	realpath,
+	rename,
+	unlink,
+	writeFile,
+} from 'node:fs/promises'
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+	commitStagedMigrationBatch,
+	type StagedMigrationVendorFile,
+} from './migration-vendor-files.js'
+
+const PACKAGE_NAME = '@growth-labs/cms'
+const MANIFEST_NAME = '.growth-labs-cms-migrations.json'
+const MANIFEST_SCHEMA_VERSION = 1
+const MIGRATION_FILE = /^\d{4}_[a-z0-9][a-z0-9_-]*\.sql$/
+
+interface PackageJson {
+	name?: string
+	version?: string
+}
+
+interface PlannedMigration {
+	source: string
+	target: string
+	sequence: number
+	sha256: string
+	bytes: Uint8Array
+}
+
+interface CmsMigrationManifestEntry {
+	source: string
+	target: string
+	sha256: string
+}
+
+interface CmsMigrationManifest {
+	schemaVersion: 1
+	packageName: typeof PACKAGE_NAME
+	packageVersion: string
+	startSequence: number
+	files: CmsMigrationManifestEntry[]
+}
+
+export interface SyncCmsMigrationsOptions {
+	/** Existing consumer-owned Wrangler migrations directory. */
+	migrationsDir: string
+	/** First unused sequence number reserved for the package migrations. */
+	startSequence: number
+	/** Override only when a consumer keeps the receipt outside migrationsDir. */
+	manifestPath?: string
+}
+
+export interface VerifyCmsMigrationsOptions {
+	migrationsDir: string
+	manifestPath?: string
+}
+
+export interface CmsMigrationVendorResult {
+	packageName: typeof PACKAGE_NAME
+	packageVersion: string
+	startSequence: number
+	managedFiles: string[]
+	written: number
+	verified: number
+	manifestPath: string
+}
+
+interface PackageContract {
+	packageVersion: string
+	sourceDir: string
+}
+
+async function packageContract(): Promise<PackageContract> {
+	const packageRoot = fileURLToPath(new URL('..', import.meta.url))
+	const packageJsonPath = join(packageRoot, 'package.json')
+	const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8')) as PackageJson
+	if (packageJson.name !== PACKAGE_NAME || !packageJson.version) {
+		throw new Error('installed CMS package metadata is invalid')
+	}
+	return {
+		packageVersion: packageJson.version,
+		sourceDir: join(packageRoot, 'migrations'),
+	}
+}
+
+async function sha256(bytes: Uint8Array): Promise<string> {
+	const input = new Uint8Array(bytes.byteLength)
+	input.set(bytes)
+	const digest = await crypto.subtle.digest('SHA-256', input.buffer)
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+async function requireExistingDirectory(path: string, label = 'migrationsDir'): Promise<string> {
+	let stat: Awaited<ReturnType<typeof lstat>>
+	try {
+		stat = await lstat(path)
+	} catch {
+		throw new Error(`${label} must be an existing directory: ${path}`)
+	}
+	if (!stat.isDirectory() || stat.isSymbolicLink()) {
+		throw new Error(`${label} must be an existing non-symlink directory: ${path}`)
+	}
+	return realpath(path)
+}
+
+function assertStartSequence(value: number): void {
+	if (!Number.isSafeInteger(value) || value < 1) {
+		throw new Error('startSequence must be a positive integer')
+	}
+}
+
+function sequencePrefix(sequence: number): string {
+	return String(sequence).padStart(4, '0')
+}
+
+async function planMigrations(
+	sourceDir: string,
+	startSequence: number,
+): Promise<PlannedMigration[]> {
+	assertStartSequence(startSequence)
+	const sourceNames = (await readdir(sourceDir)).filter((name) => MIGRATION_FILE.test(name)).sort()
+	if (sourceNames.length === 0) throw new Error('installed CMS package has no migration SQL')
+	if (startSequence + sourceNames.length - 1 > 9999) {
+		throw new Error('reserved CMS migration sequence exceeds 9999')
+	}
+
+	return Promise.all(
+		sourceNames.map(async (source, index) => {
+			const sequence = startSequence + index
+			const suffix = source.replace(/^\d{4}_/, '')
+			const target = `${sequencePrefix(sequence)}_growth_labs_cms_${suffix}`
+			const bytes = new Uint8Array(await readFile(join(sourceDir, source)))
+			return { source, target, sequence, sha256: await sha256(bytes), bytes }
+		}),
+	)
+}
+
+function manifestFor(
+	packageVersion: string,
+	startSequence: number,
+	plan: PlannedMigration[],
+): CmsMigrationManifest {
+	return {
+		schemaVersion: MANIFEST_SCHEMA_VERSION,
+		packageName: PACKAGE_NAME,
+		packageVersion,
+		startSequence,
+		files: plan.map(({ source, target, sha256: hash }) => ({ source, target, sha256: hash })),
+	}
+}
+
+async function readManifest(path: string): Promise<CmsMigrationManifest | null> {
+	try {
+		const stat = await lstat(path)
+		if (!stat.isFile() || stat.isSymbolicLink()) {
+			throw new Error(`CMS migration manifest must be a regular file: ${path}`)
+		}
+		const parsed = JSON.parse(await readFile(path, 'utf8')) as Partial<CmsMigrationManifest>
+		if (
+			parsed.schemaVersion !== MANIFEST_SCHEMA_VERSION ||
+			parsed.packageName !== PACKAGE_NAME ||
+			!parsed.packageVersion ||
+			!Number.isSafeInteger(parsed.startSequence) ||
+			(parsed.startSequence as number) < 1 ||
+			!Array.isArray(parsed.files)
+		) {
+			throw new Error(`CMS migration manifest is invalid: ${path}`)
+		}
+		for (const entry of parsed.files) {
+			if (
+				!entry ||
+				typeof entry.source !== 'string' ||
+				typeof entry.target !== 'string' ||
+				!MIGRATION_FILE.test(entry.source) ||
+				!MIGRATION_FILE.test(entry.target) ||
+				!/^([a-f0-9]{64})$/.test(entry.sha256)
+			) {
+				throw new Error(`CMS migration manifest contains an invalid file entry: ${path}`)
+			}
+		}
+		return parsed as CmsMigrationManifest
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+		throw error
+	}
+}
+
+function entriesEqual(left: CmsMigrationManifestEntry, right: CmsMigrationManifestEntry): boolean {
+	return (
+		left.source === right.source && left.target === right.target && left.sha256 === right.sha256
+	)
+}
+
+function assertManifestCanAdvance(
+	current: CmsMigrationManifest | null,
+	next: CmsMigrationManifest,
+): void {
+	if (!current) return
+	if (current.startSequence !== next.startSequence) {
+		throw new Error(
+			`CMS migration manifest reserves startSequence ${current.startSequence}; received ${next.startSequence}`,
+		)
+	}
+	if (current.files.length > next.files.length) {
+		throw new Error('installed CMS package removed migrations recorded by the consumer manifest')
+	}
+	for (const [index, entry] of current.files.entries()) {
+		const nextEntry = next.files[index]
+		if (!nextEntry || !entriesEqual(entry, nextEntry)) {
+			throw new Error(`installed CMS migration changed after vendoring: ${entry.source}`)
+		}
+	}
+}
+
+async function assertNoSequenceCollisions(
+	migrationsDir: string,
+	plan: PlannedMigration[],
+): Promise<void> {
+	const existing = await readdir(migrationsDir)
+	for (const migration of plan) {
+		const prefix = `${sequencePrefix(migration.sequence)}_`
+		const collisions = existing.filter(
+			(name) => name.endsWith('.sql') && name.startsWith(prefix) && name !== migration.target,
+		)
+		if (collisions.length > 0) {
+			throw new Error(
+				`reserved sequence ${sequencePrefix(migration.sequence)} collides with ${collisions.join(', ')}`,
+			)
+		}
+	}
+}
+
+async function verifyTargets(
+	migrationsDir: string,
+	plan: PlannedMigration[],
+	allowMissing: boolean,
+): Promise<{ verified: number; missing: PlannedMigration[] }> {
+	let verified = 0
+	const missing: PlannedMigration[] = []
+	for (const migration of plan) {
+		const targetPath = join(migrationsDir, migration.target)
+		try {
+			const stat = await lstat(targetPath)
+			if (!stat.isFile() || stat.isSymbolicLink()) {
+				throw new Error(`managed CMS migration must be a regular file: ${migration.target}`)
+			}
+			const targetHash = await sha256(new Uint8Array(await readFile(targetPath)))
+			if (targetHash !== migration.sha256) {
+				throw new Error(`CMS migration hash mismatch: ${migration.target}`)
+			}
+			verified += 1
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT' && allowMissing) {
+				missing.push(migration)
+				continue
+			}
+			throw error
+		}
+	}
+	return { verified, missing }
+}
+
+async function stageNewFile(path: string, bytes: Uint8Array): Promise<string> {
+	const temp = `${path}.tmp-${crypto.randomUUID()}`
+	await writeFile(temp, bytes, { flag: 'wx' })
+	return temp
+}
+
+async function stageManifest(path: string, manifest: CmsMigrationManifest): Promise<string> {
+	const temp = `${path}.tmp-${crypto.randomUUID()}`
+	await writeFile(temp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' })
+	return temp
+}
+
+async function commitManifest(
+	tempPath: string,
+	manifestPath: string,
+	currentManifest: CmsMigrationManifest | null,
+): Promise<void> {
+	if (currentManifest) {
+		const latest = await readManifest(manifestPath)
+		if (!latest || JSON.stringify(latest) !== JSON.stringify(currentManifest)) {
+			throw new Error('CMS migration manifest changed during sync')
+		}
+		await rename(tempPath, manifestPath)
+		return
+	}
+	await link(tempPath, manifestPath)
+}
+
+function isInsideDirectory(directory: string, path: string): boolean {
+	const fromDirectory = relative(directory, path)
+	return (
+		fromDirectory === '' ||
+		(!fromDirectory.startsWith(`..${sep}`) && fromDirectory !== '..' && !isAbsolute(fromDirectory))
+	)
+}
+
+async function resolveManifestPath(migrationsDir: string, override?: string): Promise<string> {
+	if (!override) return join(migrationsDir, MANIFEST_NAME)
+	const requested = resolve(override)
+	if (extname(requested).toLowerCase() !== '.json') {
+		throw new Error('CMS migration manifest override must be a .json file')
+	}
+	if (isInsideDirectory(migrationsDir, requested)) {
+		throw new Error('CMS migration manifest override must be outside migrationsDir')
+	}
+	const parent = await requireExistingDirectory(dirname(requested), 'manifest parent')
+	const resolvedPath = join(parent, basename(requested))
+	if (isInsideDirectory(migrationsDir, resolvedPath)) {
+		throw new Error('CMS migration manifest override must be outside migrationsDir')
+	}
+	return resolvedPath
+}
+
+async function withManifestLock<T>(manifestPath: string, action: () => Promise<T>): Promise<T> {
+	const lockPath = `${manifestPath}.lock`
+	try {
+		await writeFile(lockPath, `${JSON.stringify({ pid: process.pid, startedAt: Date.now() })}\n`, {
+			flag: 'wx',
+			mode: 0o600,
+		})
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+			throw new Error(`another CMS migration operation is already active: ${lockPath}`)
+		}
+		throw error
+	}
+
+	let result: T | undefined
+	let operationError: unknown
+	try {
+		result = await action()
+	} catch (error) {
+		operationError = error
+	}
+	let releaseError: unknown
+	try {
+		await unlink(lockPath)
+	} catch (error) {
+		releaseError = error
+	}
+	if (operationError && releaseError) {
+		throw new AggregateError(
+			[operationError, releaseError],
+			'CMS migration operation failed and its receipt lock could not be released',
+		)
+	}
+	if (operationError) throw operationError
+	if (releaseError) throw releaseError
+	return result as T
+}
+
+export async function syncCmsMigrations(
+	options: SyncCmsMigrationsOptions,
+): Promise<CmsMigrationVendorResult> {
+	assertStartSequence(options.startSequence)
+	const migrationsDir = await requireExistingDirectory(resolve(options.migrationsDir))
+	const manifestPath = await resolveManifestPath(migrationsDir, options.manifestPath)
+	return withManifestLock(manifestPath, async () => {
+		const contract = await packageContract()
+		const plan = await planMigrations(contract.sourceDir, options.startSequence)
+		const nextManifest = manifestFor(contract.packageVersion, options.startSequence, plan)
+		const currentManifest = await readManifest(manifestPath)
+		assertManifestCanAdvance(currentManifest, nextManifest)
+		await assertNoSequenceCollisions(migrationsDir, plan)
+		const preflight = await verifyTargets(migrationsDir, plan, true)
+		const staged: StagedMigrationVendorFile[] = []
+		let manifestTemp: string | null = null
+		let verified = 0
+
+		try {
+			for (const migration of preflight.missing) {
+				const targetPath = join(migrationsDir, migration.target)
+				staged.push({
+					targetPath,
+					tempPath: await stageNewFile(targetPath, migration.bytes),
+				})
+			}
+			const stagedManifest = await stageManifest(manifestPath, nextManifest)
+			manifestTemp = stagedManifest
+			await commitStagedMigrationBatch(staged, async () => {
+				await assertNoSequenceCollisions(migrationsDir, plan)
+				const final = await verifyTargets(migrationsDir, plan, false)
+				verified = final.verified
+				await commitManifest(stagedManifest, manifestPath, currentManifest)
+			})
+
+			return {
+				packageName: PACKAGE_NAME,
+				packageVersion: contract.packageVersion,
+				startSequence: options.startSequence,
+				managedFiles: plan.map(({ target }) => target),
+				written: preflight.missing.length,
+				verified,
+				manifestPath,
+			}
+		} finally {
+			await Promise.all([
+				...staged.map(({ tempPath }) => unlink(tempPath).catch(() => {})),
+				...(manifestTemp ? [unlink(manifestTemp).catch(() => {})] : []),
+			])
+		}
+	})
+}
+
+export async function verifyCmsMigrations(
+	options: VerifyCmsMigrationsOptions,
+): Promise<CmsMigrationVendorResult> {
+	const migrationsDir = await requireExistingDirectory(resolve(options.migrationsDir))
+	const manifestPath = await resolveManifestPath(migrationsDir, options.manifestPath)
+	return withManifestLock(manifestPath, async () => {
+		const manifest = await readManifest(manifestPath)
+		if (!manifest) throw new Error(`CMS migration manifest is missing: ${manifestPath}`)
+		const contract = await packageContract()
+		if (manifest.packageVersion !== contract.packageVersion) {
+			throw new Error(
+				`CMS migration manifest version ${manifest.packageVersion} does not match installed ${contract.packageVersion}`,
+			)
+		}
+		const plan = await planMigrations(contract.sourceDir, manifest.startSequence)
+		const expected = manifestFor(contract.packageVersion, manifest.startSequence, plan)
+		if (
+			expected.files.length !== manifest.files.length ||
+			expected.files.some(
+				(entry, index) => !entriesEqual(entry, manifest.files[index] as CmsMigrationManifestEntry),
+			)
+		) {
+			throw new Error('CMS migration manifest does not match the installed package contract')
+		}
+		await assertNoSequenceCollisions(migrationsDir, plan)
+		const result = await verifyTargets(migrationsDir, plan, false)
+
+		return {
+			packageName: PACKAGE_NAME,
+			packageVersion: contract.packageVersion,
+			startSequence: manifest.startSequence,
+			managedFiles: plan.map(({ target }) => target),
+			written: 0,
+			verified: result.verified,
+			manifestPath,
+		}
+	})
+}