@wp-typia/project-tools 0.11.1

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

@@ -0,0 +1,4 @@
+import type { MigrationDiff, MigrationRiskSummary } from "./migration-types.js";
+export declare function createEmptyMigrationRiskSummary(): MigrationRiskSummary;
+export declare function formatMigrationRiskSummary(summary: MigrationRiskSummary): string;
+export declare function createMigrationRiskSummary(diff: MigrationDiff): MigrationRiskSummary;

package/dist/runtime/migration-risk.js

@@ -0,0 +1,52 @@
+function createRiskBucket(items) {
+    return {
+        count: items.length,
+        items,
+    };
+}
+function formatDiffOutcome(item) {
+    return `${item.path}: ${item.kind}${item.detail ? ` (${item.detail})` : ""}`;
+}
+function formatRenameCandidate(candidate) {
+    return `${candidate.currentPath} <- ${candidate.legacyPath} (${candidate.autoApply ? "auto" : "review"}, ${candidate.reason})`;
+}
+function formatTransformSuggestion(suggestion) {
+    return `${suggestion.currentPath}${suggestion.legacyPath ? ` <- ${suggestion.legacyPath}` : ""} (${suggestion.reason})`;
+}
+function unique(items) {
+    return [...new Set(items)];
+}
+export function createEmptyMigrationRiskSummary() {
+    return {
+        additive: createRiskBucket([]),
+        rename: createRiskBucket([]),
+        semanticTransform: createRiskBucket([]),
+        unionBreaking: createRiskBucket([]),
+    };
+}
+export function formatMigrationRiskSummary(summary) {
+    return `additive=${summary.additive.count}, rename=${summary.rename.count}, semanticTransform=${summary.semanticTransform.count}, unionBreaking=${summary.unionBreaking.count}`;
+}
+export function createMigrationRiskSummary(diff) {
+    const additiveKinds = new Set([
+        "add-default",
+        "add-optional",
+        "drop",
+        "hydrate",
+        "union-branch-addition",
+    ]);
+    const additiveItems = unique(diff.summary.autoItems
+        .filter((item) => additiveKinds.has(item.kind))
+        .map(formatDiffOutcome));
+    const renameItems = unique(diff.summary.renameCandidates.map(formatRenameCandidate));
+    const semanticTransformItems = unique(diff.summary.transformSuggestions.map(formatTransformSuggestion));
+    const unionBreakingItems = unique(diff.summary.manualItems
+        .filter((item) => item.kind.startsWith("union-"))
+        .map(formatDiffOutcome));
+    return {
+        additive: createRiskBucket(additiveItems),
+        rename: createRiskBucket(renameItems),
+        semanticTransform: createRiskBucket(semanticTransformItems),
+        unionBreaking: createRiskBucket(unionBreakingItems),
+    };
+}

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

@@ -0,0 +1,249 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type ManifestTsKind = "string" | "number" | "boolean" | "array" | "object" | "union";
+export interface ManifestConstraints {
+    exclusiveMaximum?: number | null;
+    exclusiveMinimum?: number | null;
+    format?: string | null;
+    maxLength?: number | null;
+    maxItems?: number | null;
+    maximum?: number | null;
+    minLength?: number | null;
+    minItems?: number | null;
+    minimum?: number | null;
+    multipleOf?: number | null;
+    pattern?: string | null;
+    typeTag?: string | null;
+}
+export interface ManifestUnionMetadata {
+    discriminator: string;
+    branches: Record<string, ManifestAttribute>;
+}
+export interface ManifestTsMetadata {
+    items?: ManifestAttribute | null;
+    kind: ManifestTsKind;
+    properties?: Record<string, ManifestAttribute> | null;
+    required?: boolean;
+    union?: ManifestUnionMetadata | null;
+}
+export interface ManifestTypiaMetadata {
+    constraints: ManifestConstraints;
+    defaultValue?: JsonValue | null;
+    hasDefault?: boolean;
+}
+export interface ManifestWpMetadata {
+    defaultValue?: JsonValue | null;
+    enum?: JsonValue[] | null;
+    hasDefault?: boolean;
+    selector?: string | null;
+    source?: "html" | "text" | "rich-text" | null;
+    type?: string | null;
+}
+export interface ManifestAttribute {
+    ts: ManifestTsMetadata;
+    typia: ManifestTypiaMetadata;
+    wp: ManifestWpMetadata;
+}
+export interface ManifestDocument {
+    attributes?: Record<string, ManifestAttribute>;
+    manifestVersion?: number | null;
+    sourceType?: string | null;
+}
+export interface ManifestSummaryAttribute {
+    constraints: ManifestAttribute["typia"]["constraints"];
+    defaultValue: ManifestAttribute["typia"]["defaultValue"] | null;
+    enum: ManifestAttribute["wp"]["enum"] | null;
+    hasDefault: boolean;
+    kind: ManifestAttribute["ts"]["kind"] | null;
+    required: boolean;
+    union: ManifestAttribute["ts"]["union"] | null;
+}
+export interface ManifestSummary {
+    attributes: Record<string, ManifestSummaryAttribute>;
+    manifestVersion: number | null;
+    sourceType: string | null;
+}
+export interface UnionBranchSummary {
+    branches: string[];
+    discriminator: string | null;
+    field: string;
+}
+/**
+ * Declares the migration-lineage labels and block targets used by a project migration workspace.
+ *
+ * These labels describe schema lineage such as `v1`, `v2`, and `v3`; they do
+ * not represent package, plugin, or release versions.
+ */
+export interface MigrationConfig {
+    /** Optional single-block name used by legacy-root retrofit layouts. */
+    blockName?: string;
+    /** Optional explicit block target list for multi-block migration workspaces. */
+    blocks?: MigrationBlockConfig[];
+    /** Current migration-lineage label for newly generated snapshots and rules. */
+    currentMigrationVersion: string;
+    /** Relative directory that stores versioned migration snapshots. */
+    snapshotDir: string;
+    /** Ordered migration-lineage labels configured for this workspace, including the current label. */
+    supportedMigrationVersions: string[];
+}
+/**
+ * Declares one migration-capable block target inside a project workspace.
+ */
+export interface MigrationBlockConfig {
+    /** Relative path to the target block.json metadata file. */
+    blockJsonFile: string;
+    /** Registered block name for this migration target. */
+    blockName: string;
+    /** Stable block key used for generated file naming and registry entries. */
+    key: string;
+    /** Relative path to the generated manifest snapshot input for the block. */
+    manifestFile: string;
+    /** Relative path to the saved-markup source file used for snapshot capture. */
+    saveFile: string;
+    /** Relative path to the canonical types source for the block. */
+    typesFile: string;
+}
+export interface ResolvedMigrationBlockTarget extends MigrationBlockConfig {
+    currentBlockJson: Record<string, unknown>;
+    currentManifest: ManifestDocument;
+    layout: "legacy" | "multi";
+}
+export interface MigrationProjectPaths {
+    configFile: string;
+    fixturesDir: string;
+    generatedDir: string;
+    rulesDir: string;
+    snapshotDir: string;
+}
+export interface MigrationProjectState {
+    blocks: ResolvedMigrationBlockTarget[];
+    config: MigrationConfig;
+    currentBlockJson: Record<string, unknown>;
+    currentManifest: ManifestDocument;
+    paths: MigrationProjectPaths;
+    projectDir: string;
+}
+export interface MigrationEntry {
+    block: MigrationBlockConfig;
+    blockJsonImport: string;
+    fixtureImport: string;
+    fromVersion: string;
+    generatedDir: string;
+    manifestImport: string;
+    ruleImport: string;
+    rulePath: string;
+    saveImport: string;
+    toVersion: string;
+    validatorImport: string;
+}
+export interface RuleMetadata {
+    renameMap: Array<{
+        currentPath: string;
+        legacyPath: string;
+    }>;
+    transforms: string[];
+    unresolved: string[];
+}
+export interface FlattenedAttributeDescriptor {
+    attribute: ManifestAttribute;
+    currentPath: string;
+    rootPath: string;
+    sourcePath: string;
+    unionBranch: string | null;
+    unionDiscriminator: string | null;
+    unionRoot: string | null;
+}
+export interface DiffOutcome {
+    detail?: string;
+    kind: string;
+    path: string;
+    status: "auto" | "manual";
+}
+export interface RenameCandidate {
+    autoApply: boolean;
+    currentPath: string;
+    legacyPath: string;
+    reason: string;
+    score: number;
+}
+export interface TransformSuggestion {
+    attribute: ManifestAttribute | null;
+    bodyLines: string[];
+    currentPath: string;
+    legacyPath: string | null;
+    reason: string;
+}
+export interface MigrationDiffSummary {
+    auto: number;
+    autoItems: DiffOutcome[];
+    manual: number;
+    manualItems: DiffOutcome[];
+    renameCandidates: RenameCandidate[];
+    transformSuggestions: TransformSuggestion[];
+}
+export interface MigrationDiff {
+    currentTypeName: string | null | undefined;
+    fromVersion: string;
+    summary: MigrationDiffSummary;
+    toVersion: string;
+}
+export interface MigrationRiskBucket {
+    count: number;
+    items: string[];
+}
+export interface MigrationRiskSummary {
+    additive: MigrationRiskBucket;
+    rename: MigrationRiskBucket;
+    semanticTransform: MigrationRiskBucket;
+    unionBreaking: MigrationRiskBucket;
+}
+export interface MigrationFuzzMapping {
+    currentPath: string;
+    legacyPath: string;
+}
+export interface MigrationFuzzPlan {
+    blockedPaths: string[];
+    compatibleMappings: MigrationFuzzMapping[];
+}
+export interface GeneratedMigrationEntry {
+    diff: MigrationDiff;
+    entry: MigrationEntry;
+    fuzzPlan: MigrationFuzzPlan;
+    riskSummary: MigrationRiskSummary;
+}
+export interface MigrationRuleFileInput {
+    block: MigrationBlockConfig;
+    currentAttributes: Record<string, ManifestAttribute>;
+    currentTypeName: string | null | undefined;
+    diff: MigrationDiff;
+    fromVersion: string;
+    projectDir: string;
+    rulePath: string;
+    targetVersion: string;
+}
+export interface MigrationFixtureCase {
+    input: JsonObject;
+    name: string;
+}
+export interface MigrationFixtureDocument {
+    cases: MigrationFixtureCase[];
+    fromVersion: string;
+    toVersion: string;
+}
+export interface ParsedMigrationArgs {
+    command?: string;
+    flags: {
+        all: boolean;
+        currentMigrationVersion?: string;
+        force: boolean;
+        fromMigrationVersion?: string;
+        iterations?: string;
+        migrationVersion?: string;
+        seed?: string;
+        toMigrationVersion?: string;
+    };
+}
+export type RenderLine = (line: string) => void;
+export type JsonObject = Record<string, JsonValue>;

package/dist/runtime/migration-types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/migration-ui-capability.d.ts

@@ -0,0 +1,17 @@
+import type { PackageManagerId } from "./package-managers.js";
+import type { ScaffoldTemplateVariables } from "./scaffold.js";
+interface ApplyMigrationUiCapabilityOptions {
+    packageManager: PackageManagerId;
+    projectDir: string;
+    templateId: string;
+    variables: ScaffoldTemplateVariables;
+}
+/**
+ * Layer the migration dashboard capability onto a freshly scaffolded project.
+ *
+ * This copies the shared migration UI files, wires template-specific editor
+ * hooks, and injects pinned migration scripts that shell out to the matching
+ * `wp-typia` CLI version.
+ */
+export declare function applyMigrationUiCapability({ packageManager, projectDir, templateId, variables, }: ApplyMigrationUiCapabilityOptions): Promise<void>;
+export {};

package/dist/runtime/migration-ui-capability.js

@@ -0,0 +1,190 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { getPackageVersions } from "./package-versions.js";
+import { formatPackageExecCommand } from "./package-managers.js";
+import { seedProjectMigrations } from "./migrations.js";
+import { copyInterpolatedDirectory } from "./template-render.js";
+import { SHARED_MIGRATION_UI_TEMPLATE_ROOT, } from "./template-registry.js";
+const INITIAL_MIGRATION_VERSION = "v1";
+async function mutatePackageJson(projectDir, mutate) {
+    const packageJsonPath = path.join(projectDir, "package.json");
+    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    mutate(packageJson);
+    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
+}
+async function patchFile(filePath, transform) {
+    const source = await fsp.readFile(filePath, "utf8");
+    const nextSource = transform(source);
+    if (nextSource === source) {
+        throw new Error(`Unable to apply migration UI patch for ${filePath}`);
+    }
+    await fsp.writeFile(filePath, nextSource, "utf8");
+}
+function injectAfter(source, needle, insertion) {
+    if (source.includes(insertion)) {
+        return source;
+    }
+    if (!source.includes(needle)) {
+        return source;
+    }
+    return source.replace(needle, `${needle}\n${insertion}`);
+}
+function injectBefore(source, needle, insertion) {
+    if (source.includes(insertion)) {
+        return source;
+    }
+    if (!source.includes(needle)) {
+        return source;
+    }
+    return source.replace(needle, `${insertion}\n${needle}`);
+}
+function buildMigrationBlocks(templateId, variables) {
+    if (templateId === "compound") {
+        return [
+            {
+                blockJsonFile: `src/blocks/${variables.slugKebabCase}/block.json`,
+                blockName: `${variables.namespace}/${variables.slugKebabCase}`,
+                key: variables.slugKebabCase,
+                manifestFile: `src/blocks/${variables.slugKebabCase}/typia.manifest.json`,
+                saveFile: `src/blocks/${variables.slugKebabCase}/save.tsx`,
+                typesFile: `src/blocks/${variables.slugKebabCase}/types.ts`,
+            },
+            {
+                blockJsonFile: `src/blocks/${variables.slugKebabCase}-item/block.json`,
+                blockName: `${variables.namespace}/${variables.slugKebabCase}-item`,
+                key: `${variables.slugKebabCase}-item`,
+                manifestFile: `src/blocks/${variables.slugKebabCase}-item/typia.manifest.json`,
+                saveFile: `src/blocks/${variables.slugKebabCase}-item/save.tsx`,
+                typesFile: `src/blocks/${variables.slugKebabCase}-item/types.ts`,
+            },
+        ];
+    }
+    return [
+        {
+            blockJsonFile: "src/block.json",
+            blockName: `${variables.namespace}/${variables.slugKebabCase}`,
+            key: variables.slugKebabCase,
+            manifestFile: "src/typia.manifest.json",
+            saveFile: "src/save.tsx",
+            typesFile: "src/types.ts",
+        },
+    ];
+}
+async function applySingleBlockPatches(projectDir, variables) {
+    const editPath = path.join(projectDir, "src", "edit.tsx");
+    const indexPath = path.join(projectDir, "src", "index.tsx");
+    const deprecatedImport = `import { deprecated } from './migrations/generated/${variables.slugKebabCase}/deprecated';`;
+    const deprecatedLine = `  deprecated: deprecated as NonNullable<BlockConfiguration<${variables.pascalCase}Attributes>['deprecated']>,`;
+    const dashboardImport = `import { MigrationDashboard } from './admin/migration-dashboard';`;
+    const migrationPanel = `\n        <PanelBody title={__('Migration Manager', '${variables.textDomain}')}>\n          <MigrationDashboard />\n        </PanelBody>\n      </InspectorControls>`;
+    await patchFile(indexPath, (source) => {
+        let nextSource = injectAfter(source, "import metadata from './block.json';", deprecatedImport);
+        nextSource = injectBefore(nextSource, "  edit: Edit,", deprecatedLine);
+        return nextSource;
+    });
+    await patchFile(editPath, (source) => {
+        let nextSource = injectAfter(source, "import { useTypiaValidation } from './hooks';", dashboardImport);
+        nextSource = nextSource.replace("</InspectorControls>", migrationPanel);
+        return nextSource;
+    });
+}
+async function applyCompoundPatches(projectDir, variables) {
+    const parentEditPath = path.join(projectDir, "src", "blocks", variables.slugKebabCase, "edit.tsx");
+    const parentIndexPath = path.join(projectDir, "src", "blocks", variables.slugKebabCase, "index.tsx");
+    const childIndexPath = path.join(projectDir, "src", "blocks", `${variables.slugKebabCase}-item`, "index.tsx");
+    const addChildScriptPath = path.join(projectDir, "scripts", "add-compound-child.ts");
+    await patchFile(parentIndexPath, (source) => {
+        let nextSource = injectAfter(source, "import metadata from './block.json';", `import { deprecated } from '../../migrations/generated/${variables.slugKebabCase}/deprecated';`);
+        nextSource = injectBefore(nextSource, "\tedit: Edit,", `\tdeprecated: deprecated as NonNullable<BlockConfiguration< ${variables.pascalCase}Attributes >['deprecated']>,`);
+        return nextSource;
+    });
+    await patchFile(childIndexPath, (source) => {
+        let nextSource = injectAfter(source, "import metadata from './block.json';", `import { deprecated } from '../../migrations/generated/${variables.slugKebabCase}-item/deprecated';`);
+        nextSource = injectBefore(nextSource, "\tedit: Edit,", `\tdeprecated: deprecated as NonNullable<BlockConfiguration< ${variables.pascalCase}ItemAttributes >['deprecated']>,`);
+        return nextSource;
+    });
+    await patchFile(parentEditPath, (source) => {
+        let nextSource = injectAfter(source, "import { useTypiaValidation } from './hooks';", `import { MigrationDashboard } from '../../admin/migration-dashboard';`);
+        nextSource = nextSource.replace("</InspectorControls>", `\n\t\t\t\t<PanelBody title={ __( 'Migration Manager', '${variables.textDomain}' ) }>\n\t\t\t\t\t<MigrationDashboard />\n\t\t\t\t</PanelBody>\n\t\t\t</InspectorControls>`);
+        return nextSource;
+    });
+    await patchFile(addChildScriptPath, (source) => {
+        let nextSource = injectAfter(source, "const PROJECT_ROOT = process.cwd();", "const MIGRATION_CONFIG_FILE = path.join( PROJECT_ROOT, 'src', 'migrations', 'config.ts' );");
+        nextSource = nextSource.replace("import metadata from './block.json';\nimport '${ PARENT_STYLE_IMPORT }';", "import metadata from './block.json';\nimport { deprecated } from '../../migrations/generated/${ childFolderSlug }/deprecated';\nimport '${ PARENT_STYLE_IMPORT }';");
+        nextSource = nextSource.replace("\tedit: Edit,\n\tsave: Save,", "\tdeprecated: deprecated as NonNullable<BlockConfiguration< ${ childTypeName } >['deprecated']>,\n\tedit: Edit,\n\tsave: Save,");
+        nextSource = injectAfter(nextSource, "function insertBeforeMarker( filePath: string, marker: string, insertionLines: string[] ) {", "");
+        if (!nextSource.includes("function appendMigrationBlockConfig")) {
+            const appendMigrationHelper = [
+                "function appendMigrationBlockConfig( filePath: string, childBlockName: string, childFolderSlug: string ) {",
+                "\tif ( ! fs.existsSync( filePath ) ) {",
+                "\t\treturn;",
+                "\t}",
+                "",
+                "\tconst source = fs.readFileSync( filePath, 'utf8' );",
+                "\tconst blockEntry = [",
+                "\t\t`\\t\\t{`,",
+                "\t\t`\\t\\t\\tkey: '${ childFolderSlug }',`,",
+                "\t\t`\\t\\t\\tblockName: '${ childBlockName }',`,",
+                "\t\t`\\t\\t\\tblockJsonFile: 'src/blocks/${ childFolderSlug }/block.json',`,",
+                "\t\t`\\t\\t\\tmanifestFile: 'src/blocks/${ childFolderSlug }/typia.manifest.json',`,",
+                "\t\t`\\t\\t\\tsaveFile: 'src/blocks/${ childFolderSlug }/save.tsx',`,",
+                "\t\t`\\t\\t\\ttypesFile: 'src/blocks/${ childFolderSlug }/types.ts',`,",
+                "\t\t`\\t\\t},`,",
+                "\t].join( '\\n' );",
+                "\tif ( source.includes( `key: '${ childFolderSlug }'` ) ) {",
+                "\t\treturn;",
+                "\t}",
+                "\tconst nextSource = source.replace( /\\tblocks:\\s*\\[([\\s\\S]*?)\\n\\t\\],/m, ( match ) => {",
+                "\t\treturn match.replace( /\\n\\t\\],$/, `\\n${ blockEntry }\\n\\t],` );",
+                "\t} );",
+                "\tfs.writeFileSync( filePath, nextSource, 'utf8' );",
+                "}",
+                "",
+                "function renderBlockJson(",
+            ].join("\n");
+            nextSource = nextSource.replace("function renderBlockJson(", appendMigrationHelper);
+        }
+        nextSource = nextSource.replace("console.log( `✅ Added compound child block ${ childBlockName }` );", "appendMigrationBlockConfig( MIGRATION_CONFIG_FILE, childBlockName, childFolderSlug );\n\n\tconsole.log( `✅ Added compound child block ${ childBlockName }` );");
+        return nextSource;
+    });
+}
+/**
+ * Layer the migration dashboard capability onto a freshly scaffolded project.
+ *
+ * This copies the shared migration UI files, wires template-specific editor
+ * hooks, and injects pinned migration scripts that shell out to the matching
+ * `wp-typia` CLI version.
+ */
+export async function applyMigrationUiCapability({ packageManager, projectDir, templateId, variables, }) {
+    const commonTemplateDir = path.join(SHARED_MIGRATION_UI_TEMPLATE_ROOT, "common");
+    await copyInterpolatedDirectory(commonTemplateDir, projectDir, variables);
+    await mutatePackageJson(projectDir, (packageJson) => {
+        const wpTypiaPackageVersion = getPackageVersions().wpTypiaPackageVersion;
+        const canonicalCliSpecifier = wpTypiaPackageVersion === "^0.0.0"
+            ? "wp-typia"
+            : `wp-typia@${wpTypiaPackageVersion.replace(/^[~^]/u, "")}`;
+        const migrationCli = (args) => formatPackageExecCommand(packageManager, canonicalCliSpecifier, `migrate ${args}`);
+        packageJson.dependencies = {
+            ...(packageJson.dependencies ?? {}),
+            "@wordpress/api-fetch": "^7.42.0",
+        };
+        packageJson.scripts = {
+            ...(packageJson.scripts ?? {}),
+            "migration:init": migrationCli(`init --current-migration-version ${INITIAL_MIGRATION_VERSION}`),
+            "migration:snapshot": migrationCli("snapshot"),
+            "migration:diff": migrationCli("diff"),
+            "migration:scaffold": migrationCli("scaffold"),
+            "migration:doctor": migrationCli("doctor --all"),
+            "migration:fixtures": migrationCli("fixtures --all"),
+            "migration:verify": migrationCli("verify --all"),
+            "migration:fuzz": migrationCli("fuzz --all"),
+        };
+    });
+    if (templateId === "compound") {
+        await applyCompoundPatches(projectDir, variables);
+    }
+    else {
+        await applySingleBlockPatches(projectDir, variables);
+    }
+    await seedProjectMigrations(projectDir, INITIAL_MIGRATION_VERSION, buildMigrationBlocks(templateId, variables));
+}

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

@@ -0,0 +1,69 @@
+import type { JsonValue, ManifestAttribute, JsonObject } from "./migration-types.js";
+export { cloneJsonValue } from "./json-utils.js";
+export declare function getValueAtPath(input: Record<string, unknown>, pathLabel: string): unknown;
+export declare function setValueAtPath(input: Record<string, unknown>, pathLabel: string, value: unknown): void;
+export declare function deleteValueAtPath(input: Record<string, unknown>, pathLabel: string): void;
+export declare function createFixtureScalarValue(pathLabel: string): JsonValue;
+export declare function createTransformFixtureValue(attribute: ManifestAttribute | null | undefined, pathLabel: string): JsonValue;
+export declare function readJson<T = unknown>(filePath: string): T;
+export declare function renderPhpValue(value: unknown, indentLevel: number): string;
+export declare function copyFile(sourcePath: string, targetPath: string): void;
+export declare function sanitizeSaveSnapshotSource(source: string): string;
+export declare function sanitizeSnapshotBlockJson(blockJson: JsonObject): JsonObject;
+export declare function runProjectScriptIfPresent(projectDir: string, scriptName: string): void;
+export declare function detectPackageManagerId(projectDir: string): "bun" | "npm" | "pnpm" | "yarn";
+export declare function getLocalTsxBinary(projectDir: string): string;
+/**
+ * Returns whether isInteractiveTerminal() is running with both stdin and stdout
+ * attached to a TTY so CLI and migration flows can safely prompt the user.
+ */
+export declare function isInteractiveTerminal(): boolean;
+/**
+ * Resolves the `current` sentinel to the current migration version label.
+ *
+ * @param currentMigrationVersion Current migration version label for the workspace.
+ * @param value Requested target value, which may be `current`.
+ * @returns The concrete migration version label that should be used.
+ */
+export declare function resolveTargetMigrationVersion(currentMigrationVersion: string, value: string): string;
+/**
+ * Returns whether a value matches the canonical `vN` migration label format.
+ *
+ * @param value Candidate migration version label.
+ * @returns `true` when the value is a valid `vN` label with `N >= 1`.
+ */
+export declare function isMigrationVersionLabel(value: string): boolean;
+/**
+ * Returns whether a value looks like a legacy semver-based migration label.
+ *
+ * @param value Candidate migration version label.
+ * @returns `true` when the value matches the legacy `x.y.z` semver pattern.
+ */
+export declare function isLegacySemverMigrationVersion(value: string): boolean;
+/**
+ * Throws when a migration version label does not match the canonical `vN` format.
+ *
+ * @param value Candidate migration version label.
+ * @param label Human-readable label used in the thrown error message.
+ * @returns Nothing.
+ * @throws Error When the provided value is not a valid `vN` migration label.
+ */
+export declare function assertMigrationVersionLabel(value: string, label: string): void;
+/**
+ * Compares two migration version labels by their numeric suffix.
+ *
+ * @param left Left migration version label.
+ * @param right Right migration version label.
+ * @returns A negative number when `left < right`, zero when equal, and a positive number when `left > right`.
+ */
+export declare function compareMigrationVersionLabels(left: string, right: string): number;
+/**
+ * Formats the reset guidance shown when a legacy semver migration workspace is detected.
+ *
+ * @param reason Optional leading reason that explains what legacy pattern was found.
+ * @returns A user-facing guidance string that explains how to reset to `v1` labels.
+ */
+export declare function formatLegacyMigrationWorkspaceResetGuidance(reason?: string): string;
+export declare function escapeForCode(value: unknown): string;
+export declare function renderObjectKey(key: string): string;
+export declare function isNumber(value: unknown): value is number;