@wp-typia/project-tools 0.16.11 → 0.16.13

package/dist/runtime/cli-doctor.js

@@ -1,417 +1,22 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { execFileSync } from "node:child_process";
-import { access, constants as fsConstants, rm, writeFile } from "node:fs/promises";
-import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
-import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, } from "./template-builtins.js";
-import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_SET, } from "./hooked-blocks.js";
-import { isBuiltInTemplateId, listTemplates } from "./template-registry.js";
-import { readWorkspaceInventory } from "./workspace-inventory.js";
-import { getInvalidWorkspaceProjectReason, parseWorkspacePackageJson, WORKSPACE_TEMPLATE_PACKAGE, tryResolveWorkspaceProject, } from "./workspace-project.js";
 import { createCliCommandError, formatDoctorCheckLine, formatDoctorSummaryLine, getDoctorFailureDetailLines, } from "./cli-diagnostics.js";
-const WORKSPACE_COLLECTION_IMPORT_LINE = "import '../../collection';";
-const WORKSPACE_COLLECTION_IMPORT_PATTERN = /^\s*import\s+["']\.\.\/\.\.\/collection["']\s*;?\s*$/m;
-const WORKSPACE_BINDING_SERVER_GLOB = "/src/bindings/*/server.php";
-const WORKSPACE_BINDING_EDITOR_SCRIPT = "build/bindings/index.js";
-const WORKSPACE_BINDING_EDITOR_ASSET = "build/bindings/index.asset.php";
-const WORKSPACE_GENERATED_BLOCK_ARTIFACTS = [
-    "block.json",
-    "typia.manifest.json",
-    "typia.schema.json",
-    "typia-validator.php",
-    "typia.openapi.json",
-];
-function readCommandVersion(command, args = ["--version"]) {
-    try {
-        return execFileSync(command, args, {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-    }
-    catch {
-        return null;
-    }
-}
-function compareMajorVersion(actualVersion, minimumMajor) {
-    const parsed = Number.parseInt(actualVersion.replace(/^v/, "").split(".")[0] ?? "", 10);
-    return Number.isFinite(parsed) && parsed >= minimumMajor;
-}
-async function checkWritableDirectory(directory) {
-    try {
-        await access(directory, fsConstants.W_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function checkTempDirectory() {
-    const tempFile = path.join(os.tmpdir(), `wp-typia-${Date.now()}.tmp`);
-    try {
-        await writeFile(tempFile, "ok", "utf8");
-        await rm(tempFile, { force: true });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function createDoctorCheck(label, status, detail) {
-    return { detail, label, status };
-}
-function getWorkspaceBootstrapRelativePath(packageName) {
-    const packageBaseName = packageName.split("/").pop() ?? packageName;
-    return `${packageBaseName}.php`;
-}
-function checkExistingFiles(projectDir, label, filePaths) {
-    const missing = filePaths
-        .filter((filePath) => typeof filePath === "string")
-        .filter((filePath) => !fs.existsSync(path.join(projectDir, filePath)));
-    return createDoctorCheck(label, missing.length === 0 ? "pass" : "fail", missing.length === 0 ? "All referenced files exist" : `Missing: ${missing.join(", ")}`);
-}
-function checkWorkspacePackageMetadata(workspace, packageJson) {
-    const issues = [];
-    const packageName = packageJson.name;
-    const bootstrapRelativePath = getWorkspaceBootstrapRelativePath(typeof packageName === "string" && packageName.length > 0 ? packageName : workspace.packageName);
-    const wpTypia = packageJson.wpTypia;
-    if (typeof packageName !== "string" || packageName.length === 0) {
-        issues.push("package.json must define a string name for workspace bootstrap resolution");
-    }
-    if (wpTypia?.projectType !== "workspace") {
-        issues.push('wpTypia.projectType must be "workspace"');
-    }
-    if (wpTypia?.templatePackage !== WORKSPACE_TEMPLATE_PACKAGE) {
-        issues.push(`wpTypia.templatePackage must be "${WORKSPACE_TEMPLATE_PACKAGE}"`);
-    }
-    if (wpTypia?.namespace !== workspace.workspace.namespace) {
-        issues.push(`wpTypia.namespace must equal "${workspace.workspace.namespace}"`);
-    }
-    if (wpTypia?.textDomain !== workspace.workspace.textDomain) {
-        issues.push(`wpTypia.textDomain must equal "${workspace.workspace.textDomain}"`);
-    }
-    if (wpTypia?.phpPrefix !== workspace.workspace.phpPrefix) {
-        issues.push(`wpTypia.phpPrefix must equal "${workspace.workspace.phpPrefix}"`);
-    }
-    if (!fs.existsSync(path.join(workspace.projectDir, bootstrapRelativePath))) {
-        issues.push(`Missing bootstrap file ${bootstrapRelativePath}`);
-    }
-    return createDoctorCheck("Workspace package metadata", issues.length === 0 ? "pass" : "fail", issues.length === 0
-        ? `package.json metadata aligns with ${workspace.packageName} and ${bootstrapRelativePath}`
-        : issues.join("; "));
-}
-function getWorkspaceBlockRequiredFiles(block) {
-    const blockDir = path.join("src", "blocks", block.slug);
-    return Array.from(new Set([
-        block.typesFile,
-        block.apiTypesFile,
-        block.openApiFile,
-        path.join(blockDir, "index.tsx"),
-        ...WORKSPACE_GENERATED_BLOCK_ARTIFACTS.map((fileName) => path.join(blockDir, fileName)),
-    ].filter((filePath) => typeof filePath === "string")));
-}
-function checkWorkspaceBlockMetadata(projectDir, workspace, block) {
-    const blockJsonRelativePath = path.join("src", "blocks", block.slug, "block.json");
-    const blockJsonPath = path.join(projectDir, blockJsonRelativePath);
-    if (!fs.existsSync(blockJsonPath)) {
-        return createDoctorCheck(`Block metadata ${block.slug}`, "fail", `Missing ${blockJsonRelativePath}`);
-    }
-    let blockJson;
-    try {
-        blockJson = parseScaffoldBlockMetadata(JSON.parse(fs.readFileSync(blockJsonPath, "utf8")));
-    }
-    catch (error) {
-        return createDoctorCheck(`Block metadata ${block.slug}`, "fail", error instanceof Error ? error.message : String(error));
-    }
-    const expectedName = `${workspace.workspace.namespace}/${block.slug}`;
-    const issues = [];
-    if (blockJson.name !== expectedName) {
-        issues.push(`block.json name must equal "${expectedName}"`);
-    }
-    if (blockJson.textdomain !== workspace.workspace.textDomain) {
-        issues.push(`block.json textdomain must equal "${workspace.workspace.textDomain}"`);
-    }
-    return createDoctorCheck(`Block metadata ${block.slug}`, issues.length === 0 ? "pass" : "fail", issues.length === 0
-        ? `block.json matches ${expectedName} and ${workspace.workspace.textDomain}`
-        : issues.join("; "));
-}
-function checkWorkspaceBlockHooks(projectDir, blockSlug) {
-    const blockJsonRelativePath = path.join("src", "blocks", blockSlug, "block.json");
-    const blockJsonPath = path.join(projectDir, blockJsonRelativePath);
-    if (!fs.existsSync(blockJsonPath)) {
-        return createDoctorCheck(`Block hooks ${blockSlug}`, "fail", `Missing ${blockJsonRelativePath}`);
-    }
-    let blockJson;
-    try {
-        blockJson = parseScaffoldBlockMetadata(JSON.parse(fs.readFileSync(blockJsonPath, "utf8")));
-    }
-    catch (error) {
-        return createDoctorCheck(`Block hooks ${blockSlug}`, "fail", error instanceof Error ? error.message : String(error));
-    }
-    const blockHooks = blockJson.blockHooks;
-    if (blockHooks === undefined) {
-        return createDoctorCheck(`Block hooks ${blockSlug}`, "pass", "No blockHooks metadata configured");
-    }
-    if (!blockHooks || typeof blockHooks !== "object" || Array.isArray(blockHooks)) {
-        return createDoctorCheck(`Block hooks ${blockSlug}`, "fail", `${blockJsonRelativePath} must define blockHooks as an object when present.`);
-    }
-    const blockName = typeof blockJson.name === "string" && blockJson.name.trim().length > 0
-        ? blockJson.name.trim()
-        : null;
-    const invalidEntries = Object.entries(blockHooks).filter(([anchor, position]) => (blockName !== null && anchor.trim() === blockName) ||
-        anchor.trim().length === 0 ||
-        anchor !== anchor.trim() ||
-        !HOOKED_BLOCK_ANCHOR_PATTERN.test(anchor) ||
-        typeof position !== "string" ||
-        !HOOKED_BLOCK_POSITION_SET.has(position));
-    return createDoctorCheck(`Block hooks ${blockSlug}`, invalidEntries.length === 0 ? "pass" : "fail", invalidEntries.length === 0
-        ? `blockHooks metadata is valid${Object.keys(blockHooks).length > 0 ? ` (${Object.keys(blockHooks).join(", ")})` : ""}`
-        : `Invalid blockHooks entries: ${invalidEntries
-            .map(([anchor, position]) => `${anchor || "<empty>"} => ${String(position)}`)
-            .join(", ")}`);
-}
-function checkWorkspaceBlockCollectionImport(projectDir, blockSlug) {
-    const entryRelativePath = path.join("src", "blocks", blockSlug, "index.tsx");
-    const entryPath = path.join(projectDir, entryRelativePath);
-    if (!fs.existsSync(entryPath)) {
-        return createDoctorCheck(`Block collection ${blockSlug}`, "fail", `Missing ${entryRelativePath}`);
-    }
-    const source = fs.readFileSync(entryPath, "utf8");
-    const hasCollectionImport = WORKSPACE_COLLECTION_IMPORT_PATTERN.test(source);
-    return createDoctorCheck(`Block collection ${blockSlug}`, hasCollectionImport ? "pass" : "fail", hasCollectionImport
-        ? "Shared block collection import is present"
-        : `Missing a shared collection import like ${WORKSPACE_COLLECTION_IMPORT_LINE}`);
-}
-function checkWorkspacePatternBootstrap(projectDir, packageName) {
-    const packageBaseName = packageName.split("/").pop() ?? packageName;
-    const bootstrapPath = path.join(projectDir, `${packageBaseName}.php`);
-    if (!fs.existsSync(bootstrapPath)) {
-        return createDoctorCheck("Pattern bootstrap", "fail", `Missing ${path.basename(bootstrapPath)}`);
-    }
-    const source = fs.readFileSync(bootstrapPath, "utf8");
-    const hasCategoryAnchor = source.includes("register_block_pattern_category");
-    const hasPatternGlob = source.includes("/src/patterns/*.php");
-    return createDoctorCheck("Pattern bootstrap", hasCategoryAnchor && hasPatternGlob ? "pass" : "fail", hasCategoryAnchor && hasPatternGlob
-        ? "Pattern category and loader hooks are present"
-        : "Missing pattern category registration or src/patterns loader hook");
-}
-function checkWorkspaceBindingBootstrap(projectDir, packageName) {
-    const packageBaseName = packageName.split("/").pop() ?? packageName;
-    const bootstrapPath = path.join(projectDir, `${packageBaseName}.php`);
-    if (!fs.existsSync(bootstrapPath)) {
-        return createDoctorCheck("Binding bootstrap", "fail", `Missing ${path.basename(bootstrapPath)}`);
-    }
-    const source = fs.readFileSync(bootstrapPath, "utf8");
-    const hasServerGlob = source.includes(WORKSPACE_BINDING_SERVER_GLOB);
-    const hasEditorEnqueueHook = source.includes("enqueue_block_editor_assets");
-    const hasEditorScript = source.includes(WORKSPACE_BINDING_EDITOR_SCRIPT);
-    const hasEditorAsset = source.includes(WORKSPACE_BINDING_EDITOR_ASSET);
-    return createDoctorCheck("Binding bootstrap", hasServerGlob && hasEditorEnqueueHook && hasEditorScript && hasEditorAsset ? "pass" : "fail", hasServerGlob && hasEditorEnqueueHook && hasEditorScript && hasEditorAsset
-        ? "Binding source PHP and editor bootstrap hooks are present"
-        : "Missing binding source PHP require glob or editor enqueue hook");
-}
-function checkWorkspaceBindingSourcesIndex(projectDir, bindingSources) {
-    const indexRelativePath = [path.join("src", "bindings", "index.ts"), path.join("src", "bindings", "index.js")].find((relativePath) => fs.existsSync(path.join(projectDir, relativePath)));
-    if (!indexRelativePath) {
-        return createDoctorCheck("Binding sources index", "fail", "Missing src/bindings/index.ts or src/bindings/index.js");
-    }
-    const indexPath = path.join(projectDir, indexRelativePath);
-    const source = fs.readFileSync(indexPath, "utf8");
-    const missingImports = bindingSources.filter((bindingSource) => !source.includes(`./${bindingSource.slug}/editor`));
-    return createDoctorCheck("Binding sources index", missingImports.length === 0 ? "pass" : "fail", missingImports.length === 0
-        ? "Binding source editor registrations are aggregated"
-        : `Missing editor imports for: ${missingImports.map((entry) => entry.slug).join(", ")}`);
-}
-function checkVariationEntrypoint(projectDir, blockSlug) {
-    const entryPath = path.join(projectDir, "src", "blocks", blockSlug, "index.tsx");
-    if (!fs.existsSync(entryPath)) {
-        return createDoctorCheck(`Variation entrypoint ${blockSlug}`, "fail", `Missing ${path.relative(projectDir, entryPath)}`);
-    }
-    const source = fs.readFileSync(entryPath, "utf8");
-    const hasImport = source.includes("./variations");
-    const hasCall = source.includes("registerWorkspaceVariations()");
-    return createDoctorCheck(`Variation entrypoint ${blockSlug}`, hasImport && hasCall ? "pass" : "fail", hasImport && hasCall
-        ? "Variations registration hook is present"
-        : "Missing ./variations import or registerWorkspaceVariations() call");
-}
-function checkMigrationWorkspaceHint(workspace, packageJson) {
-    const hasMigrationScript = typeof packageJson.scripts?.["migration:doctor"] === "string";
-    const migrationConfigRelativePath = path.join("src", "migrations", "config.ts");
-    const hasMigrationConfig = fs.existsSync(path.join(workspace.projectDir, migrationConfigRelativePath));
-    if (!hasMigrationScript && !hasMigrationConfig) {
-        return null;
-    }
-    return createDoctorCheck("Migration workspace", hasMigrationConfig ? "pass" : "fail", hasMigrationConfig
-        ? "Run `wp-typia migrate doctor --all` for migration target, snapshot, fixture, and generated artifact checks"
-        : `Missing ${migrationConfigRelativePath} for the configured migration workspace`);
-}
+import { getEnvironmentDoctorChecks } from "./cli-doctor-environment.js";
+import { getWorkspaceDoctorChecks } from "./cli-doctor-workspace.js";
 /**
  * Collect all runtime doctor checks for the current environment.
  *
- * The returned array includes command availability checks, directory
- * writability checks, and built-in template asset checks in display order.
+ * The returned array concatenates environment checks (command availability,
+ * directory writability, and built-in template assets) followed by
+ * workspace checks (package metadata, inventory, blocks, variations,
+ * patterns, bindings, and optional migration hints) in display order.
  *
  * @param cwd Working directory to validate for writability.
  * @returns Ordered doctor check rows ready for CLI rendering.
  */
 export async function getDoctorChecks(cwd) {
-    const checks = [];
-    const bunVersion = readCommandVersion("bun");
-    const nodeVersion = readCommandVersion("node");
-    const gitVersion = readCommandVersion("git");
-    const cwdWritable = await checkWritableDirectory(cwd);
-    const tempWritable = await checkTempDirectory();
-    checks.push({
-        status: bunVersion && compareMajorVersion(bunVersion, 1) ? "pass" : "fail",
-        label: "Bun",
-        detail: bunVersion ? `Detected ${bunVersion}` : "Not available",
-    });
-    checks.push({
-        status: nodeVersion && compareMajorVersion(nodeVersion, 20) ? "pass" : "fail",
-        label: "Node",
-        detail: nodeVersion ? `Detected ${nodeVersion}` : "Not available",
-    });
-    checks.push({
-        status: gitVersion ? "pass" : "fail",
-        label: "git",
-        detail: gitVersion ?? "Not available",
-    });
-    checks.push({
-        status: cwdWritable ? "pass" : "fail",
-        label: "Current directory",
-        detail: cwdWritable ? "Writable" : "Not writable",
-    });
-    checks.push({
-        status: tempWritable ? "pass" : "fail",
-        label: "Temp directory",
-        detail: tempWritable ? "Writable" : "Not writable",
-    });
-    for (const template of listTemplates()) {
-        if (!isBuiltInTemplateId(template.id)) {
-            const templateDirExists = fs.existsSync(template.templateDir);
-            const hasAssets = templateDirExists &&
-                fs.existsSync(path.join(template.templateDir, "package.json.mustache"));
-            checks.push({
-                status: !templateDirExists || hasAssets ? "pass" : "fail",
-                label: `Template ${template.id}`,
-                detail: !templateDirExists
-                    ? "External template metadata only; local overlay package is not installed."
-                    : hasAssets
-                        ? template.templateDir
-                        : "Missing core template assets",
-            });
-            continue;
-        }
-        const builtInTemplateId = template.id;
-        const layerDirs = builtInTemplateId === "persistence"
-            ? Array.from(new Set([
-                ...getBuiltInTemplateLayerDirs(builtInTemplateId, { persistencePolicy: "authenticated" }),
-                ...getBuiltInTemplateLayerDirs(builtInTemplateId, { persistencePolicy: "public" }),
-            ]))
-            : builtInTemplateId === "compound"
-                ? Array.from(new Set([
-                    ...getBuiltInTemplateLayerDirs(builtInTemplateId),
-                    ...getBuiltInTemplateLayerDirs(builtInTemplateId, {
-                        persistenceEnabled: true,
-                        persistencePolicy: "authenticated",
-                    }),
-                    ...getBuiltInTemplateLayerDirs(builtInTemplateId, {
-                        persistenceEnabled: true,
-                        persistencePolicy: "public",
-                    }),
-                ]))
-                : getBuiltInTemplateLayerDirs(builtInTemplateId);
-        const missingRequiredLayer = layerDirs.some((layerDir) => !fs.existsSync(layerDir) &&
-            !isOmittableBuiltInTemplateLayerDir(builtInTemplateId, layerDir));
-        const existingLayerDirs = layerDirs.filter((layerDir) => fs.existsSync(layerDir));
-        const hasAssets = !missingRequiredLayer &&
-            existingLayerDirs.some((layerDir) => fs.existsSync(path.join(layerDir, "package.json.mustache"))) &&
-            existingLayerDirs.some((layerDir) => fs.existsSync(path.join(layerDir, "src")));
-        checks.push({
-            status: hasAssets ? "pass" : "fail",
-            label: `Template ${template.id}`,
-            detail: hasAssets
-                ? existingLayerDirs.join(" + ")
-                : "Missing core template assets",
-        });
-    }
-    let workspace = null;
-    let invalidWorkspaceReason = null;
-    try {
-        invalidWorkspaceReason = getInvalidWorkspaceProjectReason(cwd);
-        workspace = tryResolveWorkspaceProject(cwd);
-    }
-    catch (error) {
-        checks.push(createDoctorCheck("Workspace package metadata", "fail", error instanceof Error ? error.message : String(error)));
-        return checks;
-    }
-    if (!workspace) {
-        if (invalidWorkspaceReason) {
-            checks.push(createDoctorCheck("Workspace package metadata", "fail", invalidWorkspaceReason));
-        }
-        return checks;
-    }
-    checks.push(createDoctorCheck("Workspace marker", "pass", `Official workspace detected for ${workspace.workspace.namespace}`));
-    let workspacePackageJson;
-    try {
-        workspacePackageJson = parseWorkspacePackageJson(workspace.projectDir);
-    }
-    catch (error) {
-        checks.push(createDoctorCheck("Workspace package metadata", "fail", error instanceof Error ? error.message : String(error)));
-        return checks;
-    }
-    checks.push(checkWorkspacePackageMetadata(workspace, workspacePackageJson));
-    try {
-        const inventory = readWorkspaceInventory(workspace.projectDir);
-        checks.push(createDoctorCheck("Workspace inventory", "pass", `${inventory.blocks.length} block(s), ${inventory.variations.length} variation(s), ${inventory.patterns.length} pattern(s), ${inventory.bindingSources.length} binding source(s)`));
-        for (const block of inventory.blocks) {
-            checks.push(checkExistingFiles(workspace.projectDir, `Block ${block.slug}`, [
-                ...getWorkspaceBlockRequiredFiles(block),
-            ]));
-            checks.push(checkWorkspaceBlockMetadata(workspace.projectDir, workspace, block));
-            checks.push(checkWorkspaceBlockHooks(workspace.projectDir, block.slug));
-            checks.push(checkWorkspaceBlockCollectionImport(workspace.projectDir, block.slug));
-        }
-        const registeredBlockSlugs = new Set(inventory.blocks.map((block) => block.slug));
-        const variationTargetBlocks = new Set();
-        for (const variation of inventory.variations) {
-            if (!registeredBlockSlugs.has(variation.block)) {
-                checks.push(createDoctorCheck(`Variation ${variation.block}/${variation.slug}`, "fail", `Variation references unknown block "${variation.block}"`));
-                continue;
-            }
-            variationTargetBlocks.add(variation.block);
-            checks.push(checkExistingFiles(workspace.projectDir, `Variation ${variation.block}/${variation.slug}`, [variation.file]));
-        }
-        for (const blockSlug of variationTargetBlocks) {
-            checks.push(checkVariationEntrypoint(workspace.projectDir, blockSlug));
-        }
-        const shouldCheckPatternBootstrap = inventory.patterns.length > 0 ||
-            fs.existsSync(path.join(workspace.projectDir, "src", "patterns"));
-        if (shouldCheckPatternBootstrap) {
-            checks.push(checkWorkspacePatternBootstrap(workspace.projectDir, workspace.packageName));
-        }
-        for (const pattern of inventory.patterns) {
-            checks.push(checkExistingFiles(workspace.projectDir, `Pattern ${pattern.slug}`, [pattern.file]));
-        }
-        if (inventory.bindingSources.length > 0) {
-            checks.push(checkWorkspaceBindingBootstrap(workspace.projectDir, workspace.packageName));
-            checks.push(checkWorkspaceBindingSourcesIndex(workspace.projectDir, inventory.bindingSources));
-        }
-        for (const bindingSource of inventory.bindingSources) {
-            checks.push(checkExistingFiles(workspace.projectDir, `Binding source ${bindingSource.slug}`, [
-                bindingSource.serverFile,
-                bindingSource.editorFile,
-            ]));
-        }
-        const migrationWorkspaceCheck = checkMigrationWorkspaceHint(workspace, workspacePackageJson);
-        if (migrationWorkspaceCheck) {
-            checks.push(migrationWorkspaceCheck);
-        }
-    }
-    catch (error) {
-        checks.push(createDoctorCheck("Workspace inventory", "fail", error instanceof Error ? error.message : String(error)));
-    }
-    return checks;
+    return [
+        ...(await getEnvironmentDoctorChecks(cwd)),
+        ...getWorkspaceDoctorChecks(cwd),
+    ];
 }
 /**
  * Run doctor checks, render each line, and fail when any check does not pass.

package/dist/runtime/cli-help.js

@@ -39,7 +39,7 @@ Notes:
   \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.
   \`add hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.
-  \`wp-typia doctor\` checks environment readiness plus workspace inventory and source-tree drift.
+  \`wp-typia doctor\` always checks environment readiness and reports when it only ran environment-level diagnostics; official workspace roots also get inventory and source-tree drift checks.
   \`wp-typia migrate doctor --all\` checks migration target alignment, snapshots, fixtures, and generated migration artifacts.
   \`migrate\` is the canonical migration command; \`migrations\` is no longer supported.`;
 }

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-command-surface.d.ts

@@ -0,0 +1,67 @@
+import type { ReadlinePrompt } from './cli-prompt.js';
+import type { ParsedMigrationArgs, RenderLine } from './migration-types.js';
+export type CommandRenderOptions = {
+    prompt?: ReadlinePrompt;
+    renderLine?: RenderLine;
+};
+export type DiffLikeOptions = {
+    fromMigrationVersion?: string;
+    renderLine?: RenderLine;
+    toMigrationVersion?: string;
+};
+export type VerifyOptions = {
+    all?: boolean;
+    fromMigrationVersion?: string;
+    renderLine?: RenderLine;
+};
+export type FixturesOptions = {
+    all?: boolean;
+    confirmOverwrite?: ((message: string) => boolean) | undefined;
+    force?: boolean;
+    fromMigrationVersion?: string;
+    isInteractive?: boolean;
+    renderLine?: RenderLine;
+    toMigrationVersion?: string;
+};
+export type FuzzOptions = {
+    all?: boolean;
+    fromMigrationVersion?: string;
+    iterations?: number;
+    renderLine?: RenderLine;
+    seed?: number;
+};
+export type WizardOptions = CommandRenderOptions & {
+    isInteractive?: boolean;
+};
+/**
+ * Returns the formatted help text for migration CLI commands and flags.
+ *
+ * @returns Multi-line usage text for the `wp-typia migrate` command surface.
+ */
+export declare function formatMigrationHelpText(): string;
+/**
+ * Parses migration CLI arguments into a structured command payload.
+ *
+ * @param argv Command-line arguments that follow the `migrate` subcommand.
+ * @returns Parsed migration command and normalized flags for runtime dispatch.
+ * @throws Error When no arguments are provided, an unknown flag is encountered, or legacy semver flags are used.
+ */
+export declare function parseMigrationArgs(argv: string[]): ParsedMigrationArgs;
+/**
+ * Parse an optional positive integer flag value.
+ *
+ * @param value Raw CLI flag value, or `undefined` when the flag was omitted.
+ * @param label Human-readable flag label used in validation error messages.
+ * @returns The parsed integer when provided, otherwise `undefined`.
+ * @throws Error When the value is not a base-10 integer greater than zero.
+ */
+export declare function parsePositiveInteger(value: string | undefined, label: string): number | undefined;
+/**
+ * Parse an optional non-negative integer flag value.
+ *
+ * @param value Raw CLI flag value, or `undefined` when the flag was omitted.
+ * @param label Human-readable flag label used in validation error messages.
+ * @returns The parsed integer when provided, otherwise `undefined`.
+ * @throws Error When the value is not a base-10 integer greater than or equal to zero.
+ */
+export declare function parseNonNegativeInteger(value: string | undefined, label: string): number | undefined;