@wp-typia/project-tools 0.16.11 → 0.16.13

package/dist/runtime/migration-project-layout-paths.js

@@ -0,0 +1,288 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_FILE, FIXTURES_DIR, GENERATED_DIR, MIGRATION_TODO_PREFIX, ROOT_BLOCK_JSON, ROOT_MANIFEST, RULES_DIR, SNAPSHOT_DIR, } from "./migration-constants.js";
+import { compareMigrationVersionLabels, } from "./migration-utils.js";
+import { ensureRelativePath, normalizeRelativePath, } from "./migration-project-config-source.js";
+function toImportPath(fromDir, targetPath, stripExtension = false) {
+    let relativePath = normalizeRelativePath(path.relative(fromDir, targetPath));
+    if (!relativePath.startsWith(".")) {
+        relativePath = `./${relativePath}`;
+    }
+    if (stripExtension) {
+        relativePath = relativePath.replace(/\.[^.]+$/u, "");
+    }
+    return relativePath;
+}
+/**
+ * Resolves the canonical migration workspace paths for a project directory.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @returns Absolute filesystem paths for config, generated, fixture, rule, and snapshot roots.
+ */
+export function getProjectPaths(projectDir) {
+    return {
+        configFile: path.join(projectDir, CONFIG_FILE),
+        fixturesDir: path.join(projectDir, FIXTURES_DIR),
+        generatedDir: path.join(projectDir, GENERATED_DIR),
+        rulesDir: path.join(projectDir, RULES_DIR),
+        snapshotDir: path.join(projectDir, SNAPSHOT_DIR),
+    };
+}
+/**
+ * Resolves the snapshot root for a block target and migration version.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param version Migration version label.
+ * @returns The absolute snapshot root directory for the requested block/version pair.
+ */
+export function getSnapshotRoot(projectDir, block, version) {
+    if ("layout" in block && block.layout === "legacy") {
+        return path.join(projectDir, SNAPSHOT_DIR, version);
+    }
+    return path.join(projectDir, SNAPSHOT_DIR, version, block.key);
+}
+/**
+ * Resolves the snapshot `block.json` path for a block target and migration version.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param version Migration version label.
+ * @returns The absolute snapshot `block.json` path.
+ */
+export function getSnapshotBlockJsonPath(projectDir, block, version) {
+    return path.join(getSnapshotRoot(projectDir, block, version), ROOT_BLOCK_JSON);
+}
+/**
+ * Resolves the snapshot manifest path for a block target and migration version.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param version Migration version label.
+ * @returns The absolute snapshot manifest path.
+ */
+export function getSnapshotManifestPath(projectDir, block, version) {
+    return path.join(getSnapshotRoot(projectDir, block, version), ROOT_MANIFEST);
+}
+/**
+ * Lists the snapshot versions currently present for a specific block target.
+ *
+ * Returns the sorted subset of supported migration versions that have a manifest on disk
+ * for the provided block, or an empty array when none exist.
+ */
+export function getAvailableSnapshotVersionsForBlock(projectDir, supportedMigrationVersions, block) {
+    return supportedMigrationVersions
+        .filter((version) => fs.existsSync(getSnapshotManifestPath(projectDir, block, version)))
+        .sort(compareMigrationVersionLabels);
+}
+/**
+ * Formats the standard missing-snapshot guidance for a block target.
+ *
+ * Returns a user-facing message that either lists the available snapshot
+ * versions or explains that no snapshots exist yet for the block.
+ */
+export function createMissingBlockSnapshotMessage(blockName, fromVersion, availableSnapshotVersions) {
+    return availableSnapshotVersions.length === 0
+        ? `Snapshot manifest for ${blockName} @ ${fromVersion} does not exist. ` +
+            `No snapshots exist yet for ${blockName}. Run \`wp-typia migrate snapshot --migration-version ${fromVersion}\` first.`
+        : `Snapshot manifest for ${blockName} @ ${fromVersion} does not exist. ` +
+            `Available snapshot versions for ${blockName}: ${availableSnapshotVersions.join(", ")}. ` +
+            `Run \`wp-typia migrate snapshot --migration-version ${fromVersion}\` first if you want to preserve that release.`;
+}
+/**
+ * Resolves the snapshot save source path for a block target and migration version.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param version Migration version label.
+ * @returns The absolute snapshot `save.tsx` path.
+ */
+export function getSnapshotSavePath(projectDir, block, version) {
+    return path.join(getSnapshotRoot(projectDir, block, version), "save.tsx");
+}
+/**
+ * Resolves the generated directory used for a block's migration output.
+ *
+ * @param paths Resolved migration project paths.
+ * @param block Block target or resolved block target.
+ * @returns The absolute generated directory for the block.
+ */
+export function getGeneratedDirForBlock(paths, block) {
+    if ("layout" in block && block.layout === "legacy") {
+        return paths.generatedDir;
+    }
+    return path.join(paths.generatedDir, block.key);
+}
+/**
+ * Resolves the migration rule file path for a block version edge.
+ *
+ * @param paths Resolved migration project paths.
+ * @param block Block target or resolved block target.
+ * @param fromVersion Source migration version.
+ * @param toVersion Destination migration version.
+ * @returns The absolute migration rule file path.
+ */
+export function getRuleFilePath(paths, block, fromVersion, toVersion) {
+    if ("layout" in block && block.layout === "legacy") {
+        return path.join(paths.rulesDir, `${fromVersion}-to-${toVersion}.ts`);
+    }
+    return path.join(paths.rulesDir, block.key, `${fromVersion}-to-${toVersion}.ts`);
+}
+/**
+ * Resolves the migration fixture path for a block version edge.
+ *
+ * @param paths Resolved migration project paths.
+ * @param block Block target or resolved block target.
+ * @param fromVersion Source migration version.
+ * @param toVersion Destination migration version.
+ * @returns The absolute migration fixture file path.
+ */
+export function getFixtureFilePath(paths, block, fromVersion, toVersion) {
+    if ("layout" in block && block.layout === "legacy") {
+        return path.join(paths.fixturesDir, `${fromVersion}-to-${toVersion}.json`);
+    }
+    return path.join(paths.fixturesDir, block.key, `${fromVersion}-to-${toVersion}.json`);
+}
+/**
+ * Resolves the validators import path for generated migration artifacts.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param fromDir Directory that will import the validators module.
+ * @returns A relative module import path without a file extension.
+ */
+export function getValidatorsImportPath(projectDir, block, fromDir) {
+    const validatorPath = path.join(projectDir, block.typesFile.replace(/types\.ts$/u, "validators.ts"));
+    return toImportPath(fromDir, validatorPath, true);
+}
+/**
+ * Ensures the migration fixture, generated, rule, and snapshot directories exist.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param blocks Optional block targets whose scoped rule/fixture directories should be created.
+ * @returns Nothing.
+ */
+export function ensureMigrationDirectories(projectDir, blocks) {
+    const paths = getProjectPaths(projectDir);
+    fs.mkdirSync(paths.fixturesDir, { recursive: true });
+    fs.mkdirSync(paths.generatedDir, { recursive: true });
+    fs.mkdirSync(paths.rulesDir, { recursive: true });
+    fs.mkdirSync(paths.snapshotDir, { recursive: true });
+    if (!Array.isArray(blocks) || blocks.length === 0) {
+        return;
+    }
+    for (const block of blocks) {
+        fs.mkdirSync(path.join(paths.fixturesDir, block.key), { recursive: true });
+        fs.mkdirSync(path.join(paths.generatedDir, block.key), { recursive: true });
+        fs.mkdirSync(path.join(paths.rulesDir, block.key), { recursive: true });
+    }
+}
+/**
+ * Discovers the generated migration registry entries for a loaded project state.
+ *
+ * @param state Loaded migration project state.
+ * @returns Sorted migration registry entries for every available block/version edge.
+ */
+export function discoverMigrationEntries(state) {
+    const entries = [];
+    const currentVersion = state.config.currentMigrationVersion;
+    for (const block of state.blocks) {
+        const generatedDir = getGeneratedDirForBlock(state.paths, block);
+        for (const version of state.config.supportedMigrationVersions) {
+            if (version === currentVersion) {
+                continue;
+            }
+            const manifestPath = getSnapshotManifestPath(state.projectDir, block, version);
+            const blockJsonPath = getSnapshotBlockJsonPath(state.projectDir, block, version);
+            const savePath = getSnapshotSavePath(state.projectDir, block, version);
+            const rulePath = getRuleFilePath(state.paths, block, version, currentVersion);
+            if (!fs.existsSync(manifestPath) ||
+                !fs.existsSync(blockJsonPath) ||
+                !fs.existsSync(savePath) ||
+                !fs.existsSync(rulePath)) {
+                continue;
+            }
+            entries.push({
+                block,
+                blockJsonImport: toImportPath(generatedDir, blockJsonPath),
+                fixtureImport: toImportPath(generatedDir, getFixtureFilePath(state.paths, block, version, currentVersion)),
+                fromVersion: version,
+                generatedDir,
+                manifestImport: toImportPath(generatedDir, manifestPath),
+                ruleImport: toImportPath(generatedDir, rulePath, true),
+                rulePath,
+                saveImport: toImportPath(generatedDir, savePath, true),
+                toVersion: currentVersion,
+                validatorImport: getValidatorsImportPath(state.projectDir, block, generatedDir),
+            });
+        }
+    }
+    return entries.sort((left, right) => {
+        const versionDelta = compareMigrationVersionLabels(right.fromVersion, left.fromVersion);
+        if (versionDelta !== 0) {
+            return versionDelta;
+        }
+        return left.block.key.localeCompare(right.block.key);
+    });
+}
+/**
+ * Verifies that a migration rule file exists and no TODO markers remain in it.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param block Block target or resolved block target.
+ * @param fromMigrationVersion Source migration version.
+ * @param toMigrationVersion Destination migration version.
+ * @returns Nothing.
+ * @throws Error When the rule file is missing or still contains TODO markers.
+ */
+export function assertRuleHasNoTodos(projectDir, block, fromMigrationVersion, toMigrationVersion) {
+    const rulePath = getRuleFilePath(getProjectPaths(projectDir), block, fromMigrationVersion, toMigrationVersion);
+    if (!fs.existsSync(rulePath)) {
+        throw new Error(`Missing migration rule: ${path.relative(projectDir, rulePath)}`);
+    }
+    const source = fs.readFileSync(rulePath, "utf8");
+    if (source.includes(MIGRATION_TODO_PREFIX)) {
+        throw new Error(`Migration rule still contains ${MIGRATION_TODO_PREFIX} markers: ${path.relative(projectDir, rulePath)}`);
+    }
+}
+/**
+ * Reads lightweight metadata from a migration rule source file.
+ *
+ * @param rulePath Absolute path to the migration rule source file.
+ * @returns Parsed unresolved paths, rename mappings, and transform keys.
+ */
+export function readRuleMetadata(rulePath) {
+    const source = fs.readFileSync(rulePath, "utf8");
+    const unresolvedBlock = source.match(/export const unresolved = \[([\s\S]*?)\] as const;/);
+    const renameMapBlock = source.match(/export const renameMap: RenameMap = \{([\s\S]*?)\};/);
+    const transformsBlock = source.match(/export const transforms: TransformMap = \{([\s\S]*?)\};/);
+    const unresolved = unresolvedBlock
+        ? [...unresolvedBlock[1].matchAll(/"([^"]+)"/g)].map((match) => match[1])
+        : [];
+    const renameMap = renameMapBlock
+        ? [...renameMapBlock[1].matchAll(/^\s*"([^"]+)":\s*"([^"]+)"/gm)].map((match) => ({
+            currentPath: match[1],
+            legacyPath: match[2],
+        }))
+        : [];
+    const transforms = transformsBlock
+        ? [...transformsBlock[1].matchAll(/^\s*"([^"]+)":\s*\(/gm)].map((match) => match[1])
+        : [];
+    return { renameMap, transforms, unresolved };
+}
+/**
+ * Normalizes a migration block config against the current working directory.
+ *
+ * @param block Migration block config with project-relative file paths.
+ * @returns A normalized migration block config with ensured relative paths.
+ */
+export function createMigrationBlockConfig(block) {
+    return {
+        blockJsonFile: ensureRelativePath(process.cwd(), block.blockJsonFile),
+        blockName: block.blockName,
+        key: block.key,
+        manifestFile: ensureRelativePath(process.cwd(), block.manifestFile),
+        saveFile: ensureRelativePath(process.cwd(), block.saveFile),
+        typesFile: ensureRelativePath(process.cwd(), block.typesFile),
+    };
+}

package/dist/runtime/migration-project-layout.d.ts

@@ -0,0 +1,3 @@
+export type { DiscoveredMigrationLayout } from "./migration-project-layout-discovery.js";
+export { createImplicitLegacyBlock, discoverMigrationInitLayout, ensureAdvancedMigrationProject, readProjectBlockName, resolveMigrationBlocks, } from "./migration-project-layout-discovery.js";
+export { assertRuleHasNoTodos, createMigrationBlockConfig, createMissingBlockSnapshotMessage, discoverMigrationEntries, ensureMigrationDirectories, getAvailableSnapshotVersionsForBlock, getFixtureFilePath, getGeneratedDirForBlock, getProjectPaths, getRuleFilePath, getSnapshotBlockJsonPath, getSnapshotManifestPath, getSnapshotRoot, getSnapshotSavePath, getValidatorsImportPath, readRuleMetadata, } from "./migration-project-layout-paths.js";

package/dist/runtime/migration-project-layout.js

@@ -0,0 +1,2 @@
+export { createImplicitLegacyBlock, discoverMigrationInitLayout, ensureAdvancedMigrationProject, readProjectBlockName, resolveMigrationBlocks, } from "./migration-project-layout-discovery.js";
+export { assertRuleHasNoTodos, createMigrationBlockConfig, createMissingBlockSnapshotMessage, discoverMigrationEntries, ensureMigrationDirectories, getAvailableSnapshotVersionsForBlock, getFixtureFilePath, getGeneratedDirForBlock, getProjectPaths, getRuleFilePath, getSnapshotBlockJsonPath, getSnapshotManifestPath, getSnapshotRoot, getSnapshotSavePath, getValidatorsImportPath, readRuleMetadata, } from "./migration-project-layout-paths.js";

package/dist/runtime/migration-project-workspace.d.ts

@@ -0,0 +1,47 @@
+import type { MigrationBlockConfig, MigrationConfig, MigrationProjectState } from "./migration-types.js";
+/**
+ * Writes the initial migration README scaffolds for a project workspace.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param currentMigrationVersion Current migration version label used in README text.
+ * @param blocks Optional block targets whose scoped READMEs should be scaffolded.
+ * @returns Nothing.
+ */
+export declare function writeInitialMigrationScaffold(projectDir: string, currentMigrationVersion: string, blocks?: MigrationBlockConfig[]): void;
+/**
+ * Guards a project directory against legacy semver-based migration workspaces.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @returns Nothing.
+ * @throws Error When legacy config keys or semver-named migration artifacts are detected.
+ */
+export declare function assertNoLegacySemverMigrationWorkspace(projectDir: string): void;
+/**
+ * Loads the migration workspace state for a project directory.
+ *
+ * By default this loader may run the project's `sync-types` script when the
+ * current manifest files are missing, because later migration commands depend
+ * on those generated artifacts. Pass `allowSyncTypes: false` to keep the call
+ * read-only and fail instead of mutating the workspace.
+ *
+ * When `allowMissingConfig` is enabled and the migration config file does not
+ * exist yet, the loader synthesizes a minimal legacy-root config so bootstrap
+ * flows can continue before the first config write.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Loader flags controlling config fallback and `sync-types` side effects.
+ * @returns The resolved migration project state, including config, block targets, and helper paths.
+ * @throws Error When the project is not migration-capable, required manifests remain missing, or generated files cannot be read.
+ */
+export declare function loadMigrationProject(projectDir: string, { allowMissingConfig, allowSyncTypes, }?: {
+    allowMissingConfig?: boolean;
+    allowSyncTypes?: boolean;
+}): MigrationProjectState;
+/**
+ * Writes the migration config source file for a project workspace.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param config Parsed or synthesized migration config to serialize.
+ * @returns Nothing.
+ */
+export declare function writeMigrationConfig(projectDir: string, config: MigrationConfig): void;

package/dist/runtime/migration-project-workspace.js

@@ -0,0 +1,212 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FIXTURES_DIR, ROOT_BLOCK_JSON, ROOT_MANIFEST, RULES_DIR, SNAPSHOT_DIR, } from "./migration-constants.js";
+import { isLegacySemverMigrationVersion, readJson, runProjectScriptIfPresent, } from "./migration-utils.js";
+import { createLegacyMigrationWorkspaceResetError, hasLegacyConfigKeys, normalizeRelativePath, parseMigrationConfig, } from "./migration-project-config-source.js";
+import { createImplicitLegacyBlock, ensureAdvancedMigrationProject, getProjectPaths, readProjectBlockName, resolveMigrationBlocks, } from "./migration-project-layout.js";
+const LEGACY_VERSIONED_EDGE_FILE_PATTERN = /^(\d+\.\d+\.\d+)-to-(\d+\.\d+\.\d+)\.(?:ts|json)$/;
+function createEmptyMigrationProjectBlockJson() {
+    return {};
+}
+function createEmptyMigrationProjectManifest() {
+    return {
+        attributes: {},
+        manifestVersion: 2,
+        sourceType: null,
+    };
+}
+/**
+ * Writes the initial migration README scaffolds for a project workspace.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param currentMigrationVersion Current migration version label used in README text.
+ * @param blocks Optional block targets whose scoped READMEs should be scaffolded.
+ * @returns Nothing.
+ */
+export function writeInitialMigrationScaffold(projectDir, currentMigrationVersion, blocks) {
+    const paths = getProjectPaths(projectDir);
+    const readmeFiles = [
+        [path.join(paths.snapshotDir, "README.md"), `# Migration Version Snapshots\n\nSnapshots for ${currentMigrationVersion} and future migration versions live here.\n`],
+        [path.join(paths.rulesDir, "README.md"), "# Migration Rules\n\nScaffold direct legacy-to-current migration rules in this directory.\n"],
+        [path.join(paths.fixturesDir, "README.md"), "# Migration Fixtures\n\nGenerated fixtures are used by verify to assert migrations.\n"],
+    ];
+    for (const [targetPath, content] of readmeFiles) {
+        if (!fs.existsSync(targetPath)) {
+            fs.writeFileSync(targetPath, content, "utf8");
+        }
+    }
+    if (!Array.isArray(blocks) || blocks.length === 0) {
+        return;
+    }
+    for (const block of blocks) {
+        const scopedReadmes = [
+            [path.join(paths.rulesDir, block.key, "README.md"), `# ${block.blockName} Migration Rules\n\nScaffold direct legacy-to-current migration rules for ${block.blockName} in this directory.\n`],
+            [path.join(paths.fixturesDir, block.key, "README.md"), `# ${block.blockName} Migration Fixtures\n\nGenerated fixtures for ${block.blockName} are stored in this directory.\n`],
+        ];
+        for (const [targetPath, content] of scopedReadmes) {
+            if (!fs.existsSync(targetPath)) {
+                fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                fs.writeFileSync(targetPath, content, "utf8");
+            }
+        }
+    }
+}
+function findLegacySemverMigrationArtifacts(projectDir) {
+    const paths = getProjectPaths(projectDir);
+    const matches = [];
+    if (fs.existsSync(paths.snapshotDir)) {
+        for (const entry of fs.readdirSync(paths.snapshotDir, { withFileTypes: true })) {
+            if (entry.isDirectory() && isLegacySemverMigrationVersion(entry.name)) {
+                matches.push(normalizeRelativePath(path.join(SNAPSHOT_DIR, entry.name)));
+            }
+        }
+    }
+    const scanEdgeDir = (directory, relativeRoot) => {
+        if (!fs.existsSync(directory)) {
+            return;
+        }
+        const walk = (currentDir, currentRelativeDir) => {
+            for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    walk(path.join(currentDir, entry.name), path.join(currentRelativeDir, entry.name));
+                    continue;
+                }
+                if (LEGACY_VERSIONED_EDGE_FILE_PATTERN.test(entry.name)) {
+                    matches.push(normalizeRelativePath(path.join(currentRelativeDir, entry.name)));
+                }
+            }
+        };
+        walk(directory, relativeRoot);
+    };
+    scanEdgeDir(paths.rulesDir, RULES_DIR);
+    scanEdgeDir(paths.fixturesDir, FIXTURES_DIR);
+    return matches;
+}
+/**
+ * Guards a project directory against legacy semver-based migration workspaces.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @returns Nothing.
+ * @throws Error When legacy config keys or semver-named migration artifacts are detected.
+ */
+export function assertNoLegacySemverMigrationWorkspace(projectDir) {
+    const paths = getProjectPaths(projectDir);
+    if (fs.existsSync(paths.configFile)) {
+        const source = fs.readFileSync(paths.configFile, "utf8");
+        if (hasLegacyConfigKeys(source)) {
+            throw createLegacyMigrationWorkspaceResetError("Detected legacy config keys `currentVersion` / `supportedVersions` in `src/migrations/config.ts`.");
+        }
+    }
+    const artifactMatches = findLegacySemverMigrationArtifacts(projectDir);
+    if (artifactMatches.length > 0) {
+        throw createLegacyMigrationWorkspaceResetError(`Detected legacy semver-named migration artifacts: ${artifactMatches.join(", ")}.`);
+    }
+}
+/**
+ * Loads the migration workspace state for a project directory.
+ *
+ * By default this loader may run the project's `sync-types` script when the
+ * current manifest files are missing, because later migration commands depend
+ * on those generated artifacts. Pass `allowSyncTypes: false` to keep the call
+ * read-only and fail instead of mutating the workspace.
+ *
+ * When `allowMissingConfig` is enabled and the migration config file does not
+ * exist yet, the loader synthesizes a minimal legacy-root config so bootstrap
+ * flows can continue before the first config write.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Loader flags controlling config fallback and `sync-types` side effects.
+ * @returns The resolved migration project state, including config, block targets, and helper paths.
+ * @throws Error When the project is not migration-capable, required manifests remain missing, or generated files cannot be read.
+ */
+export function loadMigrationProject(projectDir, { allowMissingConfig = false, allowSyncTypes = true, } = {}) {
+    assertNoLegacySemverMigrationWorkspace(projectDir);
+    ensureAdvancedMigrationProject(projectDir);
+    const paths = getProjectPaths(projectDir);
+    const config = allowMissingConfig && !fs.existsSync(paths.configFile)
+        ? {
+            blocks: [createImplicitLegacyBlock(projectDir)],
+            currentMigrationVersion: "v1",
+            snapshotDir: SNAPSHOT_DIR.replace(/\\/g, "/"),
+            supportedMigrationVersions: [],
+        }
+        : parseMigrationConfig(fs.readFileSync(paths.configFile, "utf8"));
+    const configuredBlocks = config.blocks === undefined ? [createImplicitLegacyBlock(projectDir, config.blockName)] : config.blocks;
+    const missingManifestFiles = configuredBlocks
+        .filter((block) => !fs.existsSync(path.join(projectDir, block.manifestFile)))
+        .map((block) => block.manifestFile);
+    if (missingManifestFiles.length > 0) {
+        if (!allowSyncTypes) {
+            throw new Error("Migration planning is read-only and cannot run `sync-types` automatically. " +
+                `Missing current manifest file(s): ${missingManifestFiles.join(", ")}. ` +
+                "Run your project's `sync-types` script in the project root first, then rerun the planning command.");
+        }
+        runProjectScriptIfPresent(projectDir, "sync-types");
+        const remainingManifestFiles = configuredBlocks
+            .filter((block) => !fs.existsSync(path.join(projectDir, block.manifestFile)))
+            .map((block) => block.manifestFile);
+        if (remainingManifestFiles.length > 0) {
+            throw new Error(`Missing current manifest file(s): ${remainingManifestFiles.join(", ")}. ` +
+                "Run your project's `sync-types` script in the project root first, then retry.");
+        }
+    }
+    const blocks = resolveMigrationBlocks(projectDir, config);
+    return {
+        blocks,
+        config,
+        currentBlockJson: blocks[0]?.currentBlockJson ??
+            (config.blocks !== undefined
+                ? createEmptyMigrationProjectBlockJson()
+                : readJson(path.join(projectDir, ROOT_BLOCK_JSON))),
+        currentManifest: blocks[0]?.currentManifest ??
+            (config.blocks !== undefined
+                ? createEmptyMigrationProjectManifest()
+                : readJson(path.join(projectDir, ROOT_MANIFEST))),
+        paths,
+        projectDir,
+    };
+}
+/**
+ * Writes the migration config source file for a project workspace.
+ *
+ * @param projectDir Project directory containing the migration workspace.
+ * @param config Parsed or synthesized migration config to serialize.
+ * @returns Nothing.
+ */
+export function writeMigrationConfig(projectDir, config) {
+    const paths = getProjectPaths(projectDir);
+    fs.mkdirSync(path.dirname(paths.configFile), { recursive: true });
+    if (!Array.isArray(config.blocks)) {
+        fs.writeFileSync(paths.configFile, `export const migrationConfig = {
+\tblockName: '${config.blockName ?? readProjectBlockName(projectDir)}',
+\tcurrentMigrationVersion: '${config.currentMigrationVersion}',
+\tsupportedMigrationVersions: [ ${config.supportedMigrationVersions.map((version) => `'${version}'`).join(", ")} ],
+\tsnapshotDir: '${config.snapshotDir}',
+} as const;
+
+export default migrationConfig;
+`, "utf8");
+        return;
+    }
+    const blocksSource = config.blocks
+        .map((block) => `\t\t{
+\t\t\tkey: '${block.key}',
+\t\t\tblockName: '${block.blockName}',
+\t\t\tblockJsonFile: '${normalizeRelativePath(block.blockJsonFile)}',
+\t\t\tmanifestFile: '${normalizeRelativePath(block.manifestFile)}',
+\t\t\tsaveFile: '${normalizeRelativePath(block.saveFile)}',
+\t\t\ttypesFile: '${normalizeRelativePath(block.typesFile)}',
+\t\t},`)
+        .join("\n");
+    fs.writeFileSync(paths.configFile, `export const migrationConfig = {
+\tcurrentMigrationVersion: '${config.currentMigrationVersion}',
+\tsupportedMigrationVersions: [ ${config.supportedMigrationVersions.map((version) => `'${version}'`).join(", ")} ],
+\tsnapshotDir: '${config.snapshotDir}',
+\tblocks: [
+${blocksSource}
+\t],
+} as const;
+
+export default migrationConfig;
+`, "utf8");
+}

package/dist/runtime/migration-project.d.ts

@@ -1,94 +1,4 @@
-import type { MigrationBlockConfig, MigrationConfig, MigrationEntry, MigrationProjectPaths, MigrationProjectState, ResolvedMigrationBlockTarget, RuleMetadata } from "./migration-types.js";
-/**
- * Describes the migration retrofit layout discovered in a project directory.
- *
- * Multi-block discovery wins when block targets are discovered under
- * `src/blocks/<slug>/block.json`.
- * Otherwise the runtime falls back to a supported single-block layout.
- */
-export type DiscoveredMigrationLayout = {
-    block: MigrationBlockConfig;
-    mode: "single";
-} | {
-    blocks: MigrationBlockConfig[];
-    mode: "multi";
-};
-export declare function ensureAdvancedMigrationProject(projectDir: string, blocks?: MigrationBlockConfig[]): void;
-export declare function getProjectPaths(projectDir: string): MigrationProjectPaths;
-/**
- * Detects the supported migration retrofit layout for `migrate init`.
- *
- * Multi-block targets under `src/blocks/<slug>` take precedence over
- * single-block layouts.
- * Returns the detected layout on success and throws an actionable error when no
- * supported first-party layout can be inferred.
- */
-export declare function discoverMigrationInitLayout(projectDir: string): DiscoveredMigrationLayout;
-export declare function resolveMigrationBlocks(projectDir: string, config: MigrationConfig): ResolvedMigrationBlockTarget[];
-export declare function getSnapshotRoot(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
-export declare function getSnapshotBlockJsonPath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
-export declare function getSnapshotManifestPath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
-/**
- * Lists the snapshot versions currently present for a specific block target.
- *
- * Returns the sorted subset of supported migration versions that have a manifest on disk
- * for the provided block, or an empty array when none exist.
- */
-export declare function getAvailableSnapshotVersionsForBlock(projectDir: string, supportedMigrationVersions: string[], block: MigrationBlockConfig | ResolvedMigrationBlockTarget): string[];
-/**
- * Formats the standard missing-snapshot guidance for a block target.
- *
- * Returns a user-facing message that either lists the available snapshot
- * versions or explains that no snapshots exist yet for the block.
- */
-export declare function createMissingBlockSnapshotMessage(blockName: string, fromVersion: string, availableSnapshotVersions: string[]): string;
-export declare function getSnapshotSavePath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, version: string): string;
-export declare function getGeneratedDirForBlock(paths: MigrationProjectPaths, block: MigrationBlockConfig | ResolvedMigrationBlockTarget): string;
-export declare function getRuleFilePath(paths: MigrationProjectPaths, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromVersion: string, toVersion: string): string;
-export declare function getFixtureFilePath(paths: MigrationProjectPaths, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromVersion: string, toVersion: string): string;
-export declare function getValidatorsImportPath(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromDir: string): string;
-export declare function ensureMigrationDirectories(projectDir: string, blocks?: MigrationBlockConfig[]): void;
-export declare function writeInitialMigrationScaffold(projectDir: string, currentMigrationVersion: string, blocks?: MigrationBlockConfig[]): void;
-/**
- * Guards a project directory against legacy semver-based migration workspaces.
- *
- * @param projectDir Absolute or relative project directory containing the migration workspace.
- * @returns Nothing.
- * @throws Error When legacy config keys or semver-named migration artifacts are detected.
- */
-export declare function assertNoLegacySemverMigrationWorkspace(projectDir: string): void;
-/**
- * Loads the migration workspace state for a project directory.
- *
- * By default this loader may run the project's `sync-types` script when the
- * current manifest files are missing, because later migration commands depend
- * on those generated artifacts. Pass `allowSyncTypes: false` to keep the call
- * read-only and fail instead of mutating the workspace.
- *
- * When `allowMissingConfig` is enabled and the migration config file does not
- * exist yet, the loader synthesizes a minimal legacy-root config so bootstrap
- * flows can continue before the first config write.
- *
- * @param projectDir Absolute or relative project directory containing the migration workspace.
- * @param options Loader flags controlling config fallback and `sync-types` side effects.
- * @returns The resolved migration project state, including config, block targets, and helper paths.
- * @throws Error When the project is not migration-capable, required manifests remain missing, or generated files cannot be read.
- */
-export declare function loadMigrationProject(projectDir: string, { allowMissingConfig, allowSyncTypes, }?: {
-    allowMissingConfig?: boolean;
-    allowSyncTypes?: boolean;
-}): MigrationProjectState;
-export declare function discoverMigrationEntries(state: MigrationProjectState): MigrationEntry[];
-export declare function parseMigrationConfig(source: string): MigrationConfig;
-export declare function writeMigrationConfig(projectDir: string, config: MigrationConfig): void;
-/**
- * Returns the discovered block name for a supported single-block project.
- *
- * Uses `discoverSingleBlockTarget(projectDir)` internally and throws when the
- * project directory does not resolve to a supported single-block migration
- * layout.
- */
-export declare function readProjectBlockName(projectDir: string): string;
-export declare function assertRuleHasNoTodos(projectDir: string, block: MigrationBlockConfig | ResolvedMigrationBlockTarget, fromMigrationVersion: string, toMigrationVersion: string): void;
-export declare function readRuleMetadata(rulePath: string): RuleMetadata;
-export declare function createMigrationBlockConfig(block: MigrationBlockConfig): MigrationBlockConfig;
+export type { DiscoveredMigrationLayout } from "./migration-project-layout.js";
+export { parseMigrationConfig } from "./migration-project-config-source.js";
+export { assertRuleHasNoTodos, createMigrationBlockConfig, createMissingBlockSnapshotMessage, discoverMigrationEntries, discoverMigrationInitLayout, ensureAdvancedMigrationProject, ensureMigrationDirectories, getAvailableSnapshotVersionsForBlock, getFixtureFilePath, getGeneratedDirForBlock, getProjectPaths, getRuleFilePath, getSnapshotBlockJsonPath, getSnapshotManifestPath, getSnapshotRoot, getSnapshotSavePath, getValidatorsImportPath, readProjectBlockName, readRuleMetadata, resolveMigrationBlocks, } from "./migration-project-layout.js";
+export { assertNoLegacySemverMigrationWorkspace, loadMigrationProject, writeInitialMigrationScaffold, writeMigrationConfig, } from "./migration-project-workspace.js";