@wp-typia/project-tools 0.16.12 → 0.16.14

package/dist/runtime/cli-prompt.js

@@ -18,18 +18,17 @@ export function createReadlinePrompt() {
  * retry behavior without stubbing global stdin/stdout.
  */
 export function createReadlinePromptWithInterface(rl) {
+    const askQuestion = (query) => new Promise((resolve) => {
+        rl.question(query, resolve);
+    });
     return {
         async text(message, defaultValue, validate) {
-            const suffix = defaultValue ? ` (${defaultValue})` : "";
             while (true) {
-                const answer = await new Promise((resolve) => {
-                    rl.question(`${message}${suffix}: `, resolve);
-                });
-                const value = String(answer).trim() || defaultValue;
+                const value = normalizePromptAnswer(await askQuestion(formatTextPrompt(message, defaultValue))) || defaultValue;
                 if (validate) {
                     const result = validate(value);
                     if (result !== true) {
-                        console.error(`❌ ${typeof result === "string" ? result : "Invalid input"}`);
+                        console.error(formatValidationError(message, result, defaultValue));
                         continue;
                     }
                 }
@@ -40,22 +39,22 @@ export function createReadlinePromptWithInterface(rl) {
             if (options.length === 0) {
                 throw new Error(`select() requires at least one option for prompt: ${message}`);
             }
-            console.log(message);
-            options.forEach((option, index) => {
-                const hint = option.hint ? ` - ${option.hint}` : "";
-                console.log(`  ${index + 1}. ${option.label}${hint}`);
-            });
+            const resolvedDefaultIndex = getResolvedDefaultIndex(options, defaultValue);
+            renderSelectPrompt(message, options, resolvedDefaultIndex);
             while (true) {
-                const answer = await this.text("Choice", String(defaultValue));
-                const numericChoice = Number(answer);
-                if (!Number.isNaN(numericChoice) && options[numericChoice - 1]) {
-                    return options[numericChoice - 1].value;
+                const answer = normalizePromptAnswer(await askQuestion(formatChoicePrompt(resolvedDefaultIndex)));
+                if (answer.length === 0) {
+                    return options[resolvedDefaultIndex].value;
+                }
+                const selection = resolvePromptSelection(options, answer);
+                if (selection) {
+                    return selection.value;
                 }
-                const directChoice = options.find((option) => option.value === answer);
-                if (directChoice) {
-                    return directChoice.value;
+                if (isPromptHelpToken(answer)) {
+                    renderSelectPrompt(message, options, resolvedDefaultIndex);
+                    continue;
                 }
-                console.error(`❌ Invalid selection: ${answer}`);
+                console.error(formatInvalidSelectionError(answer, options, resolvedDefaultIndex));
             }
         },
         close() {
@@ -63,3 +62,63 @@ export function createReadlinePromptWithInterface(rl) {
         },
     };
 }
+function normalizePromptAnswer(value) {
+    return String(value).trim();
+}
+function normalizePromptToken(value) {
+    return value.trim().toLowerCase();
+}
+function getResolvedDefaultIndex(options, defaultValue) {
+    const candidateIndex = Number.isInteger(defaultValue) ? defaultValue - 1 : -1;
+    return options[candidateIndex] ? candidateIndex : 0;
+}
+function formatTextPrompt(message, defaultValue) {
+    const suffix = defaultValue.length > 0 ? ` [default: ${defaultValue}]` : "";
+    return `${message}${suffix}: `;
+}
+function formatValidationError(message, result, defaultValue) {
+    const detail = typeof result === "string" ? result : "Invalid input";
+    const retryHint = defaultValue.length > 0 ? ` Press Enter to keep "${defaultValue}".` : "";
+    return `❌ ${message}: ${detail}.${retryHint}`;
+}
+function formatChoicePrompt(defaultIndex) {
+    return `Choice [default: ${defaultIndex + 1}, ? for options]: `;
+}
+function renderSelectPrompt(message, options, defaultIndex) {
+    console.log(message);
+    console.log("  Enter a number, option label, or option value. Press Enter to keep the default, or type ? to list choices again.");
+    options.forEach((option, index) => {
+        const defaultMarker = index === defaultIndex ? " (default)" : "";
+        const valueHint = normalizePromptToken(option.label) === normalizePromptToken(option.value)
+            ? ""
+            : ` [${option.value}]`;
+        console.log(`  ${index + 1}. ${option.label}${valueHint}${defaultMarker}`);
+        if (option.hint) {
+            console.log(`     ${option.hint}`);
+        }
+    });
+}
+function isPromptHelpToken(answer) {
+    const normalized = normalizePromptToken(answer);
+    return normalized === "?" || normalized === "help" || normalized === "list";
+}
+function resolvePromptSelection(options, answer) {
+    const numericChoice = Number(answer);
+    if (!Number.isNaN(numericChoice) && options[numericChoice - 1]) {
+        return options[numericChoice - 1];
+    }
+    const normalizedAnswer = normalizePromptToken(answer);
+    return options.find((option) => {
+        const normalizedLabel = normalizePromptToken(option.label);
+        const normalizedValue = normalizePromptToken(option.value);
+        return normalizedAnswer === normalizedLabel || normalizedAnswer === normalizedValue;
+    });
+}
+function formatInvalidSelectionError(answer, options, defaultIndex) {
+    const optionValues = options.map((option) => option.value).join(", ");
+    return [
+        `❌ Invalid selection: ${answer}.`,
+        `Enter 1-${options.length}, one of: ${optionValues},`,
+        `or press Enter for "${options[defaultIndex].label}".`,
+    ].join(" ");
+}

package/dist/runtime/cli-scaffold.d.ts

@@ -78,7 +78,14 @@ export declare function runScaffoldFlow({ projectInput, cwd, templateId, dataSto
     projectDir: string;
     projectInput: string;
     packageManager: PackageManagerId;
-    result: import("./scaffold.js").ScaffoldProjectResult;
     nextSteps: string[];
+    result: {
+        warnings: string[];
+        packageManager: PackageManagerId;
+        projectDir: string;
+        selectedVariant: string | null;
+        templateId: string;
+        variables: import("./scaffold.js").ScaffoldTemplateVariables;
+    };
 }>;
 export {};

package/dist/runtime/cli-scaffold.js

@@ -6,6 +6,29 @@ import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
 import { getOptionalOnboardingNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
 import { resolveOptionalInteractiveExternalLayerId, } from "./external-layer-selection.js";
+function validateCreateProjectInput(projectInput) {
+    const normalizedProjectInput = projectInput.trim();
+    if (normalizedProjectInput.length === 0) {
+        throw new Error("Project directory is required. Usage: wp-typia create <project-dir> (or wp-typia <project-dir> when <project-dir> is the only positional argument).");
+    }
+    const normalizedProjectPath = path.normalize(normalizedProjectInput).replace(/[\\/]+$/u, "") ||
+        path.normalize(normalizedProjectInput);
+    if (normalizedProjectPath === "." || normalizedProjectPath === "..") {
+        throw new Error("`wp-typia create` requires a new project directory. Use an explicit child directory instead of `.` or `..`.");
+    }
+}
+function collectProjectDirectoryWarnings(projectDir) {
+    const warnings = [];
+    const projectName = path.basename(projectDir);
+    if (/\s/u.test(projectName)) {
+        warnings.push(`Project directory "${projectName}" contains spaces. The generated next-step commands will be quoted, but a simple kebab-case directory name is usually easier to use with shells and downstream tooling.`);
+    }
+    const shellSensitiveCharacters = Array.from(new Set(projectName.match(/[^A-Za-z0-9._ -]/gu) ?? []));
+    if (shellSensitiveCharacters.length > 0) {
+        warnings.push(`Project directory "${projectName}" contains shell-sensitive characters (${shellSensitiveCharacters.join(", ")}). Prefer letters, numbers, ".", "_" and "-" when possible.`);
+    }
+    return warnings;
+}
 function templateUsesPersistenceSettings(templateId, options) {
     if (templateId === "persistence") {
         return true;
@@ -15,6 +38,19 @@ function templateUsesPersistenceSettings(templateId, options) {
     }
     return Boolean(options.dataStorageMode || options.persistencePolicy);
 }
+function templateSupportsPersistenceFlags(templateId) {
+    return templateId === "persistence" || templateId === "compound";
+}
+function validateCreateFlagContract(options) {
+    const { dataStorageMode, persistencePolicy, templateId, variant } = options;
+    if ((dataStorageMode || persistencePolicy) &&
+        !templateSupportsPersistenceFlags(templateId)) {
+        throw new Error("`--data-storage` and `--persistence-policy` are supported only for `wp-typia create --template persistence` or `--template compound`.");
+    }
+    if (variant && isBuiltInTemplateId(templateId)) {
+        throw new Error(`--variant is only supported for official external template configs. Received variant "${variant}" for built-in template "${templateId}".`);
+    }
+}
 function parseSelectableValue(label, value, isValue, allowedValues) {
     if (isValue(value)) {
         return value;
@@ -107,15 +143,19 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
         externalLayerSource.trim().length > 0
         ? externalLayerSource.trim()
         : undefined;
-    if (!projectInput) {
-        throw new Error("Project directory is required. Usage: wp-typia create <project-dir> (or wp-typia <project-dir> when <project-dir> is the only positional argument).");
-    }
+    validateCreateProjectInput(projectInput);
     const resolvedTemplateId = await resolveTemplateId({
         templateId,
         yes,
         isInteractive,
         selectTemplate,
     });
+    validateCreateFlagContract({
+        dataStorageMode,
+        persistencePolicy,
+        templateId: resolvedTemplateId,
+        variant,
+    });
     const resolvedExternalLayerSelection = isBuiltInTemplateId(resolvedTemplateId) && isInteractive
         ? await resolveOptionalInteractiveExternalLayerId({
             callerCwd: cwd,
@@ -237,7 +277,6 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
             projectDir,
             projectInput,
             packageManager: resolvedPackageManager,
-            result,
             nextSteps: getNextSteps({
                 projectInput,
                 projectDir,
@@ -245,6 +284,10 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
                 noInstall,
                 templateId: resolvedTemplateId,
             }),
+            result: {
+                ...result,
+                warnings: [...result.warnings, ...collectProjectDirectoryWarnings(projectDir)],
+            },
         };
     }
     finally {

package/dist/runtime/migration-maintenance-fixtures.d.ts

@@ -0,0 +1,23 @@
+import type { FixturesOptions, FuzzOptions } from './migration-command-surface.js';
+/**
+ * Generate or refresh migration fixtures for one or more legacy edges.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Fixture generation scope and refresh options.
+ * @returns Generated and skipped legacy versions.
+ */
+export declare function fixturesProjectMigrations(projectDir: string, { all, confirmOverwrite, force, fromMigrationVersion, isInteractive, renderLine, toMigrationVersion, }?: FixturesOptions): {
+    generatedVersions: string[];
+    skippedVersions: string[];
+};
+/**
+ * Run seeded migration fuzz verification against generated fuzz artifacts.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Fuzz scope, iteration count, seed, and console rendering options.
+ * @returns Fuzzed legacy versions and the effective seed.
+ */
+export declare function fuzzProjectMigrations(projectDir: string, { all, fromMigrationVersion, iterations, renderLine, seed, }?: FuzzOptions): {
+    fuzzedVersions: string[];
+    seed: number | undefined;
+};

package/dist/runtime/migration-maintenance-fixtures.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createMigrationDiff } from './migration-diff.js';
+import { ensureEdgeFixtureFile, } from './migration-fixtures.js';
+import { collectFixtureTargets, formatScaffoldCommand, getSelectedEntriesByBlock, isLegacySingleBlockProject, resolveLegacyVersions, } from './migration-planning.js';
+import { assertRuleHasNoTodos, getGeneratedDirForBlock, loadMigrationProject, } from './migration-project.js';
+import { getLocalTsxBinary, isInteractiveTerminal, resolveTargetMigrationVersion, } from './migration-utils.js';
+/**
+ * Generate or refresh migration fixtures for one or more legacy edges.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Fixture generation scope and refresh options.
+ * @returns Generated and skipped legacy versions.
+ */
+export function fixturesProjectMigrations(projectDir, { all = false, confirmOverwrite, force = false, fromMigrationVersion, isInteractive = isInteractiveTerminal(), renderLine = console.log, toMigrationVersion = 'current', } = {}) {
+    const state = loadMigrationProject(projectDir);
+    const targetMigrationVersion = resolveTargetMigrationVersion(state.config.currentMigrationVersion, toMigrationVersion);
+    const targetVersions = resolveLegacyVersions(state, { all, fromMigrationVersion });
+    if (targetVersions.length === 0) {
+        renderLine('No legacy migration versions configured for fixture generation.');
+        return { generatedVersions: [], skippedVersions: [] };
+    }
+    const generatedVersions = [];
+    const skippedVersions = [];
+    const fixtureTargets = collectFixtureTargets(state, targetVersions, targetMigrationVersion);
+    if (force) {
+        const overwriteTargets = fixtureTargets.filter(({ fixturePath }) => fs.existsSync(fixturePath));
+        if (isInteractive && overwriteTargets.length > 0) {
+            const confirmed = confirmOverwrite?.(`About to overwrite ${overwriteTargets.length} existing migration fixture file(s). Continue?`) ??
+                promptForConfirmation(`About to overwrite ${overwriteTargets.length} existing migration fixture file(s). Continue?`);
+            if (!confirmed) {
+                renderLine(`Cancelled fixture refresh. Kept ${overwriteTargets.length} existing fixture file(s).`);
+                return {
+                    generatedVersions,
+                    skippedVersions: overwriteTargets.map(({ scopedLabel }) => scopedLabel),
+                };
+            }
+        }
+    }
+    for (const { block, fixturePath, scopedLabel, version } of fixtureTargets) {
+        const existed = fs.existsSync(fixturePath);
+        const diff = createMigrationDiff(state, block, version, targetMigrationVersion);
+        const result = ensureEdgeFixtureFile(projectDir, block, version, targetMigrationVersion, diff, { force });
+        if (result.written) {
+            generatedVersions.push(scopedLabel);
+            renderLine(`${existed ? 'Refreshed' : 'Generated'} fixture ${path.relative(projectDir, fixturePath)}`);
+        }
+        else {
+            skippedVersions.push(scopedLabel);
+            renderLine(`Preserved existing fixture ${path.relative(projectDir, fixturePath)} (use --force to refresh)`);
+        }
+    }
+    return {
+        generatedVersions,
+        skippedVersions,
+    };
+}
+/**
+ * Run seeded migration fuzz verification against generated fuzz artifacts.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Fuzz scope, iteration count, seed, and console rendering options.
+ * @returns Fuzzed legacy versions and the effective seed.
+ */
+export function fuzzProjectMigrations(projectDir, { all = false, fromMigrationVersion, iterations = 25, renderLine = console.log, seed, } = {}) {
+    const state = loadMigrationProject(projectDir);
+    const targetVersions = resolveLegacyVersions(state, { all, fromMigrationVersion });
+    const blockEntries = getSelectedEntriesByBlock(state, targetVersions, 'fuzz');
+    const legacySingleBlock = isLegacySingleBlockProject(state);
+    if (targetVersions.length === 0) {
+        renderLine('No legacy migration versions configured for fuzzing.');
+        return { fuzzedVersions: [], seed };
+    }
+    const tsxBinary = getLocalTsxBinary(projectDir);
+    for (const [blockKey, entries] of Object.entries(blockEntries)) {
+        const block = state.blocks.find((entry) => entry.key === blockKey);
+        if (!block || entries.length === 0) {
+            continue;
+        }
+        for (const entry of entries) {
+            assertRuleHasNoTodos(projectDir, block, entry.fromVersion, state.config.currentMigrationVersion);
+        }
+        const fuzzScriptPath = path.join(getGeneratedDirForBlock(state.paths, block), 'fuzz.ts');
+        if (!fs.existsSync(fuzzScriptPath)) {
+            const selectedVersionsForBlock = entries.map((entry) => entry.fromVersion);
+            throw new Error(`Generated fuzz script is missing for ${block.blockName} (${selectedVersionsForBlock.join(', ')}). ` +
+                `Run \`${formatScaffoldCommand(selectedVersionsForBlock)}\` first, then \`wp-typia migrate doctor --all\` if the workspace should already be scaffolded.`);
+        }
+        const selectedVersionsForBlock = entries.map((entry) => entry.fromVersion);
+        const args = [
+            fuzzScriptPath,
+            ...(all ? ['--all'] : ['--from-migration-version', selectedVersionsForBlock[0]]),
+            '--iterations',
+            String(iterations),
+            ...(seed === undefined ? [] : ['--seed', String(seed)]),
+        ];
+        execFileSync(tsxBinary, args, {
+            cwd: projectDir,
+            shell: process.platform === 'win32',
+            stdio: 'inherit',
+        });
+        renderLine(legacySingleBlock
+            ? `Fuzzed migrations for ${selectedVersionsForBlock.join(', ')}`
+            : `Fuzzed ${block.blockName} migrations for ${selectedVersionsForBlock.join(', ')}`);
+    }
+    return { fuzzedVersions: targetVersions, seed };
+}
+function promptForConfirmation(message) {
+    process.stdout.write(`${message} [y/N]: `);
+    const buffer = Buffer.alloc(1);
+    let answer = '';
+    while (true) {
+        const bytesRead = fs.readSync(process.stdin.fd, buffer, 0, 1, null);
+        if (bytesRead === 0) {
+            break;
+        }
+        const char = buffer.toString('utf8', 0, bytesRead);
+        if (char === '\n' || char === '\r') {
+            break;
+        }
+        answer += char;
+    }
+    const normalized = answer.trim().toLowerCase();
+    return normalized === 'y' || normalized === 'yes';
+}

package/dist/runtime/migration-maintenance-verify.d.ts

@@ -0,0 +1,26 @@
+import type { VerifyOptions } from './migration-command-surface.js';
+/**
+ * Run deterministic migration verification against generated fixtures.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Verification scope and console rendering options.
+ * @returns Verified legacy versions.
+ */
+export declare function verifyProjectMigrations(projectDir: string, { all, fromMigrationVersion, renderLine, }?: VerifyOptions): {
+    verifiedVersions: string[];
+};
+/**
+ * Validate the migration workspace without mutating files.
+ *
+ * @param projectDir Absolute or relative project directory containing the migration workspace.
+ * @param options Doctor scope and console rendering options.
+ * @returns Structured doctor check results for the selected legacy versions.
+ */
+export declare function doctorProjectMigrations(projectDir: string, { all, fromMigrationVersion, renderLine, }?: VerifyOptions): {
+    checkedVersions: string[];
+    checks: {
+        detail: string;
+        label: string;
+        status: "fail" | "pass";
+    }[];
+};