@wp-typia/project-tools 0.24.2 → 0.24.3

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

@@ -0,0 +1,124 @@
+import { scaffoldProject } from "./scaffold.js";
+import type { PackageManagerId } from "./package-managers.js";
+import type { ScaffoldProgressEvent } from "./scaffold.js";
+type ScaffoldProjectOptions = Parameters<typeof scaffoldProject>[0];
+/**
+ * Dependency installation hook accepted by scaffold emission.
+ */
+export type ScaffoldInstallDependencies = ScaffoldProjectOptions["installDependencies"];
+/**
+ * Dry-run metadata returned after rendering a scaffold into a preview directory.
+ */
+export interface ScaffoldDryRunPlan {
+    /**
+     * Whether dependency installation would run or is skipped by --no-install.
+     */
+    dependencyInstall: "skipped-by-flag" | "would-install";
+    /**
+     * Sorted project-relative paths that would be written by the scaffold.
+     */
+    files: string[];
+}
+/**
+ * Normalized scaffold emission options shared by real and dry-run flows.
+ */
+export interface ScaffoldEmissionOptions {
+    /**
+     * Whether an existing target directory may be reused.
+     */
+    allowExistingDir: boolean;
+    /**
+     * Optional alternate render target specification for supported templates.
+     */
+    alternateRenderTargets?: ScaffoldProjectOptions["alternateRenderTargets"];
+    /**
+     * Resolved scaffold answers used by template variable generation.
+     */
+    answers: ScaffoldProjectOptions["answers"];
+    /**
+     * Caller working directory used to resolve relative template inputs.
+     */
+    cwd: string;
+    /**
+     * Persistence storage mode for templates that support storage options.
+     */
+    dataStorageMode?: ScaffoldProjectOptions["dataStorageMode"];
+    /**
+     * Optional public root id selected from an external layer package.
+     */
+    externalLayerId?: string;
+    /**
+     * Optional external layer source package, path, or locator.
+     */
+    externalLayerSource?: string;
+    /**
+     * Display label for the external layer source before path resolution.
+     */
+    externalLayerSourceLabel?: string;
+    /**
+     * Optional dependency installer override used by tests and callers.
+     */
+    installDependencies?: ScaffoldProjectOptions["installDependencies"];
+    /**
+     * Whether generated projects should skip dependency installation.
+     */
+    noInstall: boolean;
+    /**
+     * Optional callback for scaffold progress events.
+     */
+    onProgress?: ((event: ScaffoldProgressEvent) => void | Promise<void>) | undefined;
+    /**
+     * Package manager used for generated metadata and follow-up commands.
+     */
+    packageManager: PackageManagerId;
+    /**
+     * Persistence access policy for templates that support server storage.
+     */
+    persistencePolicy?: ScaffoldProjectOptions["persistencePolicy"];
+    /**
+     * Optional create profile that enables preset groups such as plugin QA.
+     */
+    profile?: ScaffoldProjectOptions["profile"];
+    /**
+     * Absolute target directory for the generated project.
+     */
+    projectDir: string;
+    /**
+     * Resolved template id or external template locator to render.
+     */
+    templateId: string;
+    /**
+     * Optional built-in or external template variant id.
+     */
+    variant?: string;
+    /**
+     * Whether migration UI support should be added when supported.
+     */
+    withMigrationUi: boolean;
+    /**
+     * Whether scaffold test presets should be emitted.
+     */
+    withTestPreset: boolean;
+    /**
+     * Whether local wp-env support should be emitted.
+     */
+    withWpEnv: boolean;
+}
+/**
+ * Emit scaffold files into the target project directory.
+ *
+ * @param options Normalized scaffold emission options.
+ * @returns The scaffold result produced by the runtime renderer.
+ */
+export declare function emitScaffoldProject(options: ScaffoldEmissionOptions): Promise<Awaited<ReturnType<typeof scaffoldProject>>>;
+/**
+ * Build a dry-run scaffold plan without mutating the requested target directory.
+ *
+ * @param options Normalized scaffold emission options.
+ * @returns Preview metadata and the scaffold result from the temp render.
+ */
+export declare function buildScaffoldDryRunPlan(options: ScaffoldEmissionOptions): Promise<{
+    plan: ScaffoldDryRunPlan;
+    result: Awaited<ReturnType<typeof scaffoldProject>>;
+}>;
+export {};

package/dist/runtime/cli-scaffold-emission.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { assertDryRunTargetDirectoryReady, listRelativeProjectFiles, } from "./cli-scaffold-files.js";
+import { scaffoldProject } from "./scaffold.js";
+import { createManagedTempRoot } from "./temp-roots.js";
+/**
+ * Emit scaffold files into the target project directory.
+ *
+ * @param options Normalized scaffold emission options.
+ * @returns The scaffold result produced by the runtime renderer.
+ */
+export async function emitScaffoldProject(options) {
+    return scaffoldProject(options);
+}
+/**
+ * Build a dry-run scaffold plan without mutating the requested target directory.
+ *
+ * @param options Normalized scaffold emission options.
+ * @returns Preview metadata and the scaffold result from the temp render.
+ */
+export async function buildScaffoldDryRunPlan(options) {
+    await assertDryRunTargetDirectoryReady(options.projectDir, options.allowExistingDir);
+    const { path: tempRoot, cleanup } = await createManagedTempRoot("wp-typia-scaffold-plan-");
+    const previewProjectDir = path.join(tempRoot, "preview-project");
+    try {
+        const result = await emitScaffoldProject({
+            ...options,
+            allowExistingDir: false,
+            noInstall: true,
+            projectDir: previewProjectDir,
+        });
+        const files = await listRelativeProjectFiles(previewProjectDir);
+        return {
+            plan: {
+                dependencyInstall: options.noInstall
+                    ? "skipped-by-flag"
+                    : "would-install",
+                files,
+            },
+            result,
+        };
+    }
+    finally {
+        await cleanup();
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * List every file emitted under a scaffold project using POSIX-style paths.
+ *
+ * @param rootDir Root project directory to scan recursively.
+ * @returns Sorted relative file paths suitable for dry-run preview output.
+ */
+export declare function listRelativeProjectFiles(rootDir: string): Promise<string[]>;
+/**
+ * Ensure a dry-run target would be legal before rendering into a temp preview.
+ *
+ * @param projectDir Real target project directory requested by the user.
+ * @param allowExistingDir Whether existing target directories are allowed.
+ * @throws Error when the target exists, is non-empty, and is not allowed.
+ */
+export declare function assertDryRunTargetDirectoryReady(projectDir: string, allowExistingDir: boolean): Promise<void>;
+/**
+ * Read script names from the package manifest emitted by a scaffold run.
+ *
+ * @param projectDir Generated project directory containing package.json.
+ * @returns Script names, or undefined when the manifest is absent or invalid.
+ */
+export declare function readGeneratedPackageScripts(projectDir: string): Promise<string[] | undefined>;

package/dist/runtime/cli-scaffold-files.js

@@ -0,0 +1,69 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { formatNonEmptyTargetDirectoryError } from "./scaffold-bootstrap.js";
+import { pathExists } from "./fs-async.js";
+import { readJsonFile } from "./json-utils.js";
+/**
+ * List every file emitted under a scaffold project using POSIX-style paths.
+ *
+ * @param rootDir Root project directory to scan recursively.
+ * @returns Sorted relative file paths suitable for dry-run preview output.
+ */
+export async function listRelativeProjectFiles(rootDir) {
+    const relativeFiles = [];
+    async function visit(currentDir) {
+        const entries = await fsp.readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const absolutePath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                await visit(absolutePath);
+                continue;
+            }
+            relativeFiles.push(path
+                .relative(rootDir, absolutePath)
+                .replace(path.sep === "\\" ? /\\/gu : /\//gu, "/"));
+        }
+    }
+    await visit(rootDir);
+    return relativeFiles.sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Ensure a dry-run target would be legal before rendering into a temp preview.
+ *
+ * @param projectDir Real target project directory requested by the user.
+ * @param allowExistingDir Whether existing target directories are allowed.
+ * @throws Error when the target exists, is non-empty, and is not allowed.
+ */
+export async function assertDryRunTargetDirectoryReady(projectDir, allowExistingDir) {
+    if (!(await pathExists(projectDir)) || allowExistingDir) {
+        return;
+    }
+    const entries = await fsp.readdir(projectDir);
+    if (entries.length > 0) {
+        throw new Error(formatNonEmptyTargetDirectoryError(projectDir));
+    }
+}
+/**
+ * Read script names from the package manifest emitted by a scaffold run.
+ *
+ * @param projectDir Generated project directory containing package.json.
+ * @returns Script names, or undefined when the manifest is absent or invalid.
+ */
+export async function readGeneratedPackageScripts(projectDir) {
+    try {
+        const parsedPackageJson = await readJsonFile(path.join(projectDir, "package.json"), {
+            context: "generated package manifest",
+        });
+        const scripts = parsedPackageJson.scripts &&
+            typeof parsedPackageJson.scripts === "object" &&
+            !Array.isArray(parsedPackageJson.scripts)
+            ? parsedPackageJson.scripts
+            : {};
+        return Object.entries(scripts)
+            .filter(([, value]) => typeof value === "string")
+            .map(([scriptName]) => scriptName);
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,79 @@
+import type { PackageManagerId } from "./package-managers.js";
+/**
+ * Inputs used to build CLI next-step commands after scaffolding succeeds.
+ */
+export interface ScaffoldNextStepsOptions {
+    /**
+     * Whether install instructions should be printed because install was skipped.
+     */
+    noInstall: boolean;
+    /**
+     * Package manager used to format install and run commands.
+     */
+    packageManager: PackageManagerId;
+    /**
+     * Absolute scaffold target directory.
+     */
+    projectDir: string;
+    /**
+     * Project path exactly as provided to the CLI.
+     */
+    projectInput: string;
+    /**
+     * Resolved template id used to choose the primary development script.
+     */
+    templateId: string;
+}
+/**
+ * Inputs used to compute optional onboarding guidance after scaffolding.
+ */
+export interface ScaffoldOptionalOnboardingOptions {
+    /**
+     * Script names discovered from the generated package manifest.
+     */
+    availableScripts?: string[];
+    /**
+     * Package manager used to format optional commands.
+     */
+    packageManager: PackageManagerId;
+    /**
+     * Resolved template id used to select template-specific guidance.
+     */
+    templateId: string;
+    /**
+     * Whether compound persistence support is present in generated variables.
+     */
+    compoundPersistenceEnabled?: boolean;
+}
+/**
+ * User-facing optional onboarding copy and command list.
+ */
+export interface OptionalOnboardingGuidance {
+    /**
+     * Full note shown in the detailed completion output.
+     */
+    note: string;
+    /**
+     * Short note shown in compact completion output.
+     */
+    shortNote: string;
+    /**
+     * Optional follow-up commands to show after next steps.
+     */
+    steps: string[];
+}
+/**
+ * Build the printed next-step commands for a scaffolded project.
+ *
+ * @param options Project location and package-manager details used to format
+ * next-step commands.
+ * @returns Ordered shell commands shown after scaffolding succeeds.
+ */
+export declare function getNextSteps({ projectInput, projectDir, packageManager, noInstall, templateId, }: ScaffoldNextStepsOptions): string[];
+/**
+ * Compute optional onboarding guidance shown after scaffolding completes.
+ *
+ * @param options Package-manager and template context for optional guidance.
+ * @returns Optional onboarding note and step list.
+ */
+export declare function getOptionalOnboarding({ availableScripts, packageManager, templateId, compoundPersistenceEnabled, }: ScaffoldOptionalOnboardingOptions): OptionalOnboardingGuidance;

package/dist/runtime/cli-scaffold-output.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
+import { getOptionalOnboardingNote, getOptionalOnboardingShortNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
+import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
+function quoteShellValue(value) {
+    if (!value.startsWith("-") &&
+        /^[A-Za-z0-9._/@:-]+(?:\/[A-Za-z0-9._@:-]+)*$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+/**
+ * Build the printed next-step commands for a scaffolded project.
+ *
+ * @param options Project location and package-manager details used to format
+ * next-step commands.
+ * @returns Ordered shell commands shown after scaffolding succeeds.
+ */
+export function getNextSteps({ projectInput, projectDir, packageManager, noInstall, templateId, }) {
+    const cdTarget = path.isAbsolute(projectInput) ? projectDir : projectInput;
+    const steps = [`cd ${quoteShellValue(cdTarget)}`];
+    if (noInstall) {
+        steps.push(formatInstallCommand(packageManager));
+    }
+    steps.push(formatRunScript(packageManager, getPrimaryDevelopmentScript(templateId)));
+    return steps;
+}
+/**
+ * Compute optional onboarding guidance shown after scaffolding completes.
+ *
+ * @param options Package-manager and template context for optional guidance.
+ * @returns Optional onboarding note and step list.
+ */
+export function getOptionalOnboarding({ availableScripts, packageManager, templateId, compoundPersistenceEnabled = false, }) {
+    return {
+        note: getOptionalOnboardingNote(packageManager, templateId, {
+            availableScripts,
+            compoundPersistenceEnabled,
+        }),
+        shortNote: getOptionalOnboardingShortNote(packageManager, templateId, {
+            availableScripts,
+            compoundPersistenceEnabled,
+        }),
+        steps: getOptionalOnboardingSteps(packageManager, templateId, {
+            availableScripts,
+            compoundPersistenceEnabled,
+        }),
+    };
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Validate the project directory argument before template resolution.
+ *
+ * @param projectInput Raw project directory input from the CLI.
+ * @throws Error when the input is empty or points at the current/parent directory.
+ */
+export declare function validateCreateProjectInput(projectInput: string): void;
+/**
+ * Collect warnings for project directory names that are awkward in shells.
+ *
+ * @param projectDir Absolute target project directory.
+ * @returns User-facing warning messages for non-fatal directory concerns.
+ */
+export declare function collectProjectDirectoryWarnings(projectDir: string): string[];
+/**
+ * Determine whether a template should resolve persistence-related options.
+ *
+ * @param templateId Resolved template id.
+ * @param options Explicit persistence flags provided by the caller.
+ * @returns True when persistence defaults or prompts should be applied.
+ */
+export declare function templateUsesPersistenceSettings(templateId: string, options: {
+    dataStorageMode?: string;
+    persistencePolicy?: string;
+}): boolean;
+/**
+ * Collect warnings for flags that do not apply to the selected template.
+ *
+ * @param options Template id and raw CLI flags that may be ignored.
+ * @returns User-facing warnings for non-fatal capability mismatches.
+ */
+export declare function collectTemplateCapabilityWarnings(options: {
+    queryPostType?: string;
+    templateId: string;
+    withMigrationUi?: boolean;
+}): string[];
+/**
+ * Validate create flags that depend on the selected template capability set.
+ *
+ * @param options Raw create flags plus the resolved template id.
+ * @throws Error when a flag is unsupported for the selected template.
+ */
+export declare function validateCreateFlagContract(options: {
+    alternateRenderTargets?: string;
+    dataStorageMode?: string;
+    innerBlocksPreset?: string;
+    persistencePolicy?: string;
+    templateId: string;
+    variant?: string;
+}): void;
+/**
+ * Resolve an optional string selection from explicit input, prompts, or defaults.
+ *
+ * @param options Selection configuration including allowed values and prompt hooks.
+ * @returns The resolved value, or undefined when resolution is disabled.
+ * @throws Error when an explicit value is not in the allowed set.
+ */
+export declare function resolveOptionalSelection<T extends string>({ defaultValue, explicitValue, isInteractive, isValue, label, allowedValues, select, shouldResolve, yes, }: {
+    defaultValue: T;
+    explicitValue?: string;
+    isInteractive: boolean;
+    isValue: (input: string) => input is T;
+    label: string;
+    allowedValues: readonly T[];
+    select?: () => Promise<T>;
+    shouldResolve?: boolean;
+    yes: boolean;
+}): Promise<T | undefined>;
+/**
+ * Resolve an optional boolean flag from explicit input, prompts, or defaults.
+ *
+ * @param options Boolean selection configuration and optional prompt hook.
+ * @returns The resolved boolean value.
+ */
+export declare function resolveOptionalBooleanFlag({ defaultValue, disabled, explicitValue, isInteractive, select, yes, }: {
+    defaultValue?: boolean;
+    disabled?: boolean;
+    explicitValue?: boolean;
+    isInteractive: boolean;
+    select?: () => Promise<boolean>;
+    yes: boolean;
+}): Promise<boolean>;

package/dist/runtime/cli-scaffold-validation.js

@@ -0,0 +1,190 @@
+import path from "node:path";
+import { parseAlternateRenderTargets } from "./alternate-render-targets.js";
+import { parseCompoundInnerBlocksPreset } from "./compound-inner-blocks.js";
+import { assertBuiltInTemplateVariantAllowed } from "./cli-validation.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
+/**
+ * Validate the project directory argument before template resolution.
+ *
+ * @param projectInput Raw project directory input from the CLI.
+ * @throws Error when the input is empty or points at the current/parent directory.
+ */
+export 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 `..`.");
+    }
+}
+/**
+ * Collect warnings for project directory names that are awkward in shells.
+ *
+ * @param projectDir Absolute target project directory.
+ * @returns User-facing warning messages for non-fatal directory concerns.
+ */
+export 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;
+}
+/**
+ * Determine whether a template should resolve persistence-related options.
+ *
+ * @param templateId Resolved template id.
+ * @param options Explicit persistence flags provided by the caller.
+ * @returns True when persistence defaults or prompts should be applied.
+ */
+export function templateUsesPersistenceSettings(templateId, options) {
+    if (templateId === "persistence") {
+        return true;
+    }
+    if (templateId !== "compound") {
+        return false;
+    }
+    return Boolean(options.dataStorageMode || options.persistencePolicy);
+}
+function templateSupportsPersistenceFlags(templateId) {
+    return templateId === "persistence" || templateId === "compound";
+}
+function templateSupportsCompoundInnerBlocksPreset(templateId) {
+    return templateId === "compound";
+}
+function createTemplateLabel(templateId) {
+    return templateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        ? "`--template workspace`"
+        : `"${templateId}"`;
+}
+/**
+ * Collect warnings for flags that do not apply to the selected template.
+ *
+ * @param options Template id and raw CLI flags that may be ignored.
+ * @returns User-facing warnings for non-fatal capability mismatches.
+ */
+export function collectTemplateCapabilityWarnings(options) {
+    const warnings = [];
+    const trimmedQueryPostType = options.queryPostType?.trim();
+    if (trimmedQueryPostType &&
+        options.templateId !== "query-loop" &&
+        (isBuiltInTemplateId(options.templateId) ||
+            options.templateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE)) {
+        warnings.push(`\`--query-post-type\` only applies to \`wp-typia create --template query-loop\`, which scaffolds a create-time \`core/query\` variation instead of a standalone block. ${createTemplateLabel(options.templateId)} will ignore "${trimmedQueryPostType}".`);
+    }
+    if (options.withMigrationUi === true &&
+        !isBuiltInTemplateId(options.templateId) &&
+        options.templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        warnings.push(`\`--with-migration-ui\` was ignored for ${createTemplateLabel(options.templateId)}. Migration UI currently scaffolds built-in templates and the official \`--template workspace\` flow; external templates still need to opt into that surface explicitly.`);
+    }
+    return warnings;
+}
+function templateSupportsAlternateRenderTargets(options) {
+    if (!options.alternateRenderTargets) {
+        return false;
+    }
+    if (options.templateId === "persistence") {
+        return true;
+    }
+    if (options.templateId !== "compound") {
+        return false;
+    }
+    return templateUsesPersistenceSettings(options.templateId, {
+        dataStorageMode: options.dataStorageMode,
+        persistencePolicy: options.persistencePolicy,
+    });
+}
+/**
+ * Validate create flags that depend on the selected template capability set.
+ *
+ * @param options Raw create flags plus the resolved template id.
+ * @throws Error when a flag is unsupported for the selected template.
+ */
+export function validateCreateFlagContract(options) {
+    const { alternateRenderTargets, dataStorageMode, innerBlocksPreset, 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 (alternateRenderTargets &&
+        !templateSupportsAlternateRenderTargets({
+            alternateRenderTargets,
+            dataStorageMode,
+            persistencePolicy,
+            templateId,
+        })) {
+        if (templateId === "compound") {
+            throw new Error("`--alternate-render-targets` on `wp-typia create --template compound` requires the persistence-enabled server render path. Add `--data-storage <post-meta|custom-table>` or `--persistence-policy <authenticated|public>` first.");
+        }
+        throw new Error("`--alternate-render-targets` is supported only for `wp-typia create --template persistence` or persistence-enabled `--template compound` scaffolds.");
+    }
+    parseAlternateRenderTargets(alternateRenderTargets);
+    if (innerBlocksPreset &&
+        !templateSupportsCompoundInnerBlocksPreset(templateId)) {
+        throw new Error("`--inner-blocks-preset` is supported only for `wp-typia create --template compound`.");
+    }
+    parseCompoundInnerBlocksPreset(innerBlocksPreset);
+    if (isBuiltInTemplateId(templateId)) {
+        assertBuiltInTemplateVariantAllowed({
+            templateId,
+            variant,
+        });
+    }
+}
+function parseSelectableValue(label, value, isValue, allowedValues) {
+    if (isValue(value)) {
+        return value;
+    }
+    throw new Error(`Unsupported ${label} "${value}". Expected one of: ${allowedValues.join(", ")}`);
+}
+/**
+ * Resolve an optional string selection from explicit input, prompts, or defaults.
+ *
+ * @param options Selection configuration including allowed values and prompt hooks.
+ * @returns The resolved value, or undefined when resolution is disabled.
+ * @throws Error when an explicit value is not in the allowed set.
+ */
+export async function resolveOptionalSelection({ defaultValue, explicitValue, isInteractive, isValue, label, allowedValues, select, shouldResolve = true, yes, }) {
+    if (!shouldResolve) {
+        return undefined;
+    }
+    if (explicitValue !== undefined) {
+        return parseSelectableValue(label, explicitValue, isValue, allowedValues);
+    }
+    if (yes) {
+        return defaultValue;
+    }
+    if (isInteractive && select) {
+        return select();
+    }
+    return defaultValue;
+}
+/**
+ * Resolve an optional boolean flag from explicit input, prompts, or defaults.
+ *
+ * @param options Boolean selection configuration and optional prompt hook.
+ * @returns The resolved boolean value.
+ */
+export async function resolveOptionalBooleanFlag({ defaultValue = false, disabled = false, explicitValue, isInteractive, select, yes, }) {
+    if (disabled) {
+        return defaultValue;
+    }
+    if (typeof explicitValue === "boolean") {
+        return explicitValue;
+    }
+    if (yes) {
+        return defaultValue;
+    }
+    if (isInteractive && select) {
+        return select();
+    }
+    return defaultValue;
+}

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

@@ -1,30 +1,12 @@
-import { collectScaffoldAnswers, scaffoldProject } from "./scaffold.js";
-import type { DataStorageMode, PersistencePolicy, ScaffoldProgressEvent } from "./scaffold.js";
+import { collectScaffoldAnswers } from "./scaffold.js";
+import { type ScaffoldEmissionOptions, type ScaffoldInstallDependencies } from "./cli-scaffold-emission.js";
+import type { DataStorageMode, PersistencePolicy } from "./scaffold.js";
 import type { PackageManagerId } from "./package-managers.js";
 import { type ExternalLayerSelectionOption } from "./external-layer-selection.js";
 import type { TemplateDefinition } from "./template-registry.js";
-interface GetNextStepsOptions {
-    noInstall: boolean;
-    packageManager: PackageManagerId;
-    projectDir: string;
-    projectInput: string;
-    templateId: string;
-}
-interface GetOptionalOnboardingOptions {
-    availableScripts?: string[];
-    packageManager: PackageManagerId;
-    templateId: string;
-    compoundPersistenceEnabled?: boolean;
-}
-interface OptionalOnboardingGuidance {
-    note: string;
-    shortNote: string;
-    steps: string[];
-}
-export interface ScaffoldDryRunPlan {
-    dependencyInstall: "skipped-by-flag" | "would-install";
-    files: string[];
-}
+export { getNextSteps, getOptionalOnboarding } from "./cli-scaffold-output.js";
+export type { OptionalOnboardingGuidance, ScaffoldNextStepsOptions, ScaffoldOptionalOnboardingOptions, } from "./cli-scaffold-output.js";
+export type { ScaffoldDryRunPlan } from "./cli-scaffold-emission.js";
 interface RunScaffoldFlowOptions {
     allowExistingDir?: boolean;
     alternateRenderTargets?: string;
@@ -33,12 +15,12 @@ interface RunScaffoldFlowOptions {
     dryRun?: boolean;
     externalLayerId?: string;
     externalLayerSource?: string;
-    installDependencies?: Parameters<typeof scaffoldProject>[0]["installDependencies"];
+    installDependencies?: ScaffoldInstallDependencies;
     innerBlocksPreset?: string;
     isInteractive?: boolean;
     namespace?: string;
     noInstall?: boolean;
-    onProgress?: ((event: ScaffoldProgressEvent) => void | Promise<void>) | undefined;
+    onProgress?: ScaffoldEmissionOptions["onProgress"];
     packageManager?: string;
     phpPrefix?: string;
     profile?: string;
@@ -62,21 +44,6 @@ interface RunScaffoldFlowOptions {
     withWpEnv?: boolean;
     yes?: boolean;
 }
-/**
- * Build the printed next-step commands for a scaffolded project.
- *
- * @param options Project location and package-manager details used to format
- * next-step commands.
- * @returns Ordered shell commands shown after scaffolding succeeds.
- */
-export declare function getNextSteps({ projectInput, projectDir, packageManager, noInstall, templateId, }: GetNextStepsOptions): string[];
-/**
- * Compute optional onboarding guidance shown after scaffolding completes.
- *
- * @param options Package-manager and template context for optional guidance.
- * @returns Optional onboarding note and step list.
- */
-export declare function getOptionalOnboarding({ availableScripts, packageManager, templateId, compoundPersistenceEnabled, }: GetOptionalOnboardingOptions): OptionalOnboardingGuidance;
 /**
  * Resolve scaffold options, prompts, and follow-up steps for one CLI run.
  *
@@ -86,8 +53,8 @@ export declare function getOptionalOnboarding({ availableScripts, packageManager
  */
 export declare function runScaffoldFlow({ projectInput, cwd, templateId, alternateRenderTargets, dataStorageMode, dryRun, externalLayerId, externalLayerSource, innerBlocksPreset, persistencePolicy, packageManager, namespace, profile, textDomain, phpPrefix, queryPostType, yes, noInstall, onProgress, isInteractive, allowExistingDir, selectTemplate, selectDataStorage, selectExternalLayerId, selectPersistencePolicy, selectPackageManager, promptText, installDependencies, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }: RunScaffoldFlowOptions): Promise<{
     dryRun: boolean;
-    optionalOnboarding: OptionalOnboardingGuidance;
-    plan: ScaffoldDryRunPlan | undefined;
+    optionalOnboarding: import("./cli-scaffold-output.js").OptionalOnboardingGuidance;
+    plan: import("./cli-scaffold-emission.js").ScaffoldDryRunPlan | undefined;
     projectDir: string;
     projectInput: string;
     packageManager: PackageManagerId;
@@ -101,4 +68,3 @@ export declare function runScaffoldFlow({ projectInput, cwd, templateId, alterna
         variables: import("./scaffold.js").ScaffoldTemplateVariables;
     };
 }>;
-export {};

package/dist/runtime/cli-scaffold.js

@@ -1,272 +1,15 @@
-import { promises as fsp } from "node:fs";
 import path from "node:path";
-import { collectScaffoldAnswers, DATA_STORAGE_MODES, PERSISTENCE_POLICIES, isDataStorageMode, resolveCreateProfileId, isPersistencePolicy, resolvePackageManagerId, resolveTemplateId, scaffoldProject, } from "./scaffold.js";
-import { parseAlternateRenderTargets } from "./alternate-render-targets.js";
+import { collectScaffoldAnswers, DATA_STORAGE_MODES, PERSISTENCE_POLICIES, isDataStorageMode, resolveCreateProfileId, isPersistencePolicy, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
 import { parseCompoundInnerBlocksPreset } from "./compound-inner-blocks.js";
 import { isCompoundPersistenceEnabled } from "./scaffold-template-variable-groups.js";
-import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
-import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
-import { createManagedTempRoot } from "./temp-roots.js";
-import { getOptionalOnboardingNote, getOptionalOnboardingShortNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
-import { formatNonEmptyTargetDirectoryError } from "./scaffold-bootstrap.js";
-import { pathExists } from "./fs-async.js";
-import { readJsonFile } from "./json-utils.js";
+import { buildScaffoldDryRunPlan, emitScaffoldProject, } from "./cli-scaffold-emission.js";
+import { readGeneratedPackageScripts } from "./cli-scaffold-files.js";
+import { getNextSteps, getOptionalOnboarding, } from "./cli-scaffold-output.js";
+import { collectProjectDirectoryWarnings, collectTemplateCapabilityWarnings, resolveOptionalBooleanFlag, resolveOptionalSelection, templateUsesPersistenceSettings, validateCreateFlagContract, validateCreateProjectInput, } from "./cli-scaffold-validation.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
 import { resolveOptionalInteractiveExternalLayerId, } from "./external-layer-selection.js";
-import { assertBuiltInTemplateVariantAllowed, resolveLocalCliPathOption, normalizeOptionalCliString, } from "./cli-validation.js";
-async function listRelativeProjectFiles(rootDir) {
-    const relativeFiles = [];
-    async function visit(currentDir) {
-        const entries = await fsp.readdir(currentDir, { withFileTypes: true });
-        for (const entry of entries) {
-            const absolutePath = path.join(currentDir, entry.name);
-            if (entry.isDirectory()) {
-                await visit(absolutePath);
-                continue;
-            }
-            relativeFiles.push(path
-                .relative(rootDir, absolutePath)
-                .replace(path.sep === "\\" ? /\\/gu : /\//gu, "/"));
-        }
-    }
-    await visit(rootDir);
-    return relativeFiles.sort((left, right) => left.localeCompare(right));
-}
-async function assertDryRunTargetDirectoryReady(projectDir, allowExistingDir) {
-    if (!(await pathExists(projectDir)) || allowExistingDir) {
-        return;
-    }
-    const entries = await fsp.readdir(projectDir);
-    if (entries.length > 0) {
-        throw new Error(formatNonEmptyTargetDirectoryError(projectDir));
-    }
-}
-async function buildScaffoldDryRunPlan({ allowExistingDir, alternateRenderTargets, answers, cwd, dataStorageMode, externalLayerId, externalLayerSource, externalLayerSourceLabel, installDependencies, noInstall, onProgress, packageManager, persistencePolicy, profile, projectDir, templateId, variant, withMigrationUi, withTestPreset, withWpEnv, }) {
-    await assertDryRunTargetDirectoryReady(projectDir, allowExistingDir);
-    const { path: tempRoot, cleanup } = await createManagedTempRoot("wp-typia-scaffold-plan-");
-    const previewProjectDir = path.join(tempRoot, "preview-project");
-    try {
-        const result = await scaffoldProject({
-            allowExistingDir: false,
-            alternateRenderTargets,
-            answers,
-            cwd,
-            dataStorageMode,
-            externalLayerId,
-            externalLayerSource,
-            externalLayerSourceLabel,
-            installDependencies,
-            noInstall: true,
-            onProgress,
-            packageManager,
-            persistencePolicy,
-            profile,
-            projectDir: previewProjectDir,
-            templateId,
-            variant,
-            withMigrationUi,
-            withTestPreset,
-            withWpEnv,
-        });
-        const files = await listRelativeProjectFiles(previewProjectDir);
-        return {
-            plan: {
-                dependencyInstall: noInstall ? "skipped-by-flag" : "would-install",
-                files,
-            },
-            result,
-        };
-    }
-    finally {
-        await cleanup();
-    }
-}
-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;
-    }
-    if (templateId !== "compound") {
-        return false;
-    }
-    return Boolean(options.dataStorageMode || options.persistencePolicy);
-}
-function templateSupportsPersistenceFlags(templateId) {
-    return templateId === "persistence" || templateId === "compound";
-}
-function templateSupportsCompoundInnerBlocksPreset(templateId) {
-    return templateId === "compound";
-}
-function createTemplateLabel(templateId) {
-    return templateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
-        ? "`--template workspace`"
-        : `"${templateId}"`;
-}
-function collectTemplateCapabilityWarnings(options) {
-    const warnings = [];
-    const trimmedQueryPostType = options.queryPostType?.trim();
-    if (trimmedQueryPostType &&
-        options.templateId !== "query-loop" &&
-        (isBuiltInTemplateId(options.templateId) ||
-            options.templateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE)) {
-        warnings.push(`\`--query-post-type\` only applies to \`wp-typia create --template query-loop\`, which scaffolds a create-time \`core/query\` variation instead of a standalone block. ${createTemplateLabel(options.templateId)} will ignore "${trimmedQueryPostType}".`);
-    }
-    if (options.withMigrationUi === true &&
-        !isBuiltInTemplateId(options.templateId) &&
-        options.templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
-        warnings.push(`\`--with-migration-ui\` was ignored for ${createTemplateLabel(options.templateId)}. Migration UI currently scaffolds built-in templates and the official \`--template workspace\` flow; external templates still need to opt into that surface explicitly.`);
-    }
-    return warnings;
-}
-function templateSupportsAlternateRenderTargets(options) {
-    if (!options.alternateRenderTargets) {
-        return false;
-    }
-    if (options.templateId === "persistence") {
-        return true;
-    }
-    if (options.templateId !== "compound") {
-        return false;
-    }
-    return templateUsesPersistenceSettings(options.templateId, {
-        dataStorageMode: options.dataStorageMode,
-        persistencePolicy: options.persistencePolicy,
-    });
-}
-function validateCreateFlagContract(options) {
-    const { alternateRenderTargets, dataStorageMode, innerBlocksPreset, 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 (alternateRenderTargets &&
-        !templateSupportsAlternateRenderTargets({
-            alternateRenderTargets,
-            dataStorageMode,
-            persistencePolicy,
-            templateId,
-        })) {
-        if (templateId === "compound") {
-            throw new Error("`--alternate-render-targets` on `wp-typia create --template compound` requires the persistence-enabled server render path. Add `--data-storage <post-meta|custom-table>` or `--persistence-policy <authenticated|public>` first.");
-        }
-        throw new Error("`--alternate-render-targets` is supported only for `wp-typia create --template persistence` or persistence-enabled `--template compound` scaffolds.");
-    }
-    parseAlternateRenderTargets(alternateRenderTargets);
-    if (innerBlocksPreset &&
-        !templateSupportsCompoundInnerBlocksPreset(templateId)) {
-        throw new Error("`--inner-blocks-preset` is supported only for `wp-typia create --template compound`.");
-    }
-    parseCompoundInnerBlocksPreset(innerBlocksPreset);
-    if (isBuiltInTemplateId(templateId)) {
-        assertBuiltInTemplateVariantAllowed({
-            templateId,
-            variant,
-        });
-    }
-}
-function parseSelectableValue(label, value, isValue, allowedValues) {
-    if (isValue(value)) {
-        return value;
-    }
-    throw new Error(`Unsupported ${label} "${value}". Expected one of: ${allowedValues.join(", ")}`);
-}
-async function resolveOptionalSelection({ defaultValue, explicitValue, isInteractive, isValue, label, allowedValues, select, shouldResolve = true, yes, }) {
-    if (!shouldResolve) {
-        return undefined;
-    }
-    if (explicitValue) {
-        return parseSelectableValue(label, explicitValue, isValue, allowedValues);
-    }
-    if (yes) {
-        return defaultValue;
-    }
-    if (isInteractive && select) {
-        return select();
-    }
-    return defaultValue;
-}
-async function resolveOptionalBooleanFlag({ defaultValue = false, disabled = false, explicitValue, isInteractive, select, yes, }) {
-    if (disabled) {
-        return defaultValue;
-    }
-    if (typeof explicitValue === "boolean") {
-        return explicitValue;
-    }
-    if (yes) {
-        return defaultValue;
-    }
-    if (isInteractive && select) {
-        return select();
-    }
-    return defaultValue;
-}
-function quoteShellValue(value) {
-    if (!value.startsWith("-") &&
-        /^[A-Za-z0-9._/@:-]+(?:\/[A-Za-z0-9._@:-]+)*$/.test(value)) {
-        return value;
-    }
-    return `'${value.replace(/'/g, `'\"'\"'`)}'`;
-}
-/**
- * Build the printed next-step commands for a scaffolded project.
- *
- * @param options Project location and package-manager details used to format
- * next-step commands.
- * @returns Ordered shell commands shown after scaffolding succeeds.
- */
-export function getNextSteps({ projectInput, projectDir, packageManager, noInstall, templateId, }) {
-    const cdTarget = path.isAbsolute(projectInput) ? projectDir : projectInput;
-    const steps = [`cd ${quoteShellValue(cdTarget)}`];
-    if (noInstall) {
-        steps.push(formatInstallCommand(packageManager));
-    }
-    steps.push(formatRunScript(packageManager, getPrimaryDevelopmentScript(templateId)));
-    return steps;
-}
-/**
- * Compute optional onboarding guidance shown after scaffolding completes.
- *
- * @param options Package-manager and template context for optional guidance.
- * @returns Optional onboarding note and step list.
- */
-export function getOptionalOnboarding({ availableScripts, packageManager, templateId, compoundPersistenceEnabled = false, }) {
-    return {
-        note: getOptionalOnboardingNote(packageManager, templateId, {
-            availableScripts,
-            compoundPersistenceEnabled,
-        }),
-        shortNote: getOptionalOnboardingShortNote(packageManager, templateId, {
-            availableScripts,
-            compoundPersistenceEnabled,
-        }),
-        steps: getOptionalOnboardingSteps(packageManager, templateId, {
-            availableScripts,
-            compoundPersistenceEnabled,
-        }),
-    };
-}
+import { resolveLocalCliPathOption, normalizeOptionalCliString, } from "./cli-validation.js";
+export { getNextSteps, getOptionalOnboarding } from "./cli-scaffold-output.js";
 /**
  * Resolve scaffold options, prompts, and follow-up steps for one CLI run.
  *
@@ -381,73 +124,37 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
         if (resolvedTemplateId === "compound" && resolvedInnerBlocksPreset) {
             answers.compoundInnerBlocksPreset = resolvedInnerBlocksPreset;
         }
+        const emissionOptions = {
+            allowExistingDir,
+            alternateRenderTargets,
+            answers,
+            cwd,
+            dataStorageMode: resolvedDataStorage,
+            externalLayerId: resolvedExternalLayerSelection.externalLayerId,
+            externalLayerSource: resolvedExternalLayerSelection.externalLayerSource,
+            externalLayerSourceLabel: normalizedExternalLayerSource,
+            installDependencies,
+            noInstall,
+            onProgress,
+            packageManager: resolvedPackageManager,
+            persistencePolicy: resolvedPersistencePolicy,
+            profile: resolvedProfile,
+            projectDir,
+            templateId: resolvedTemplateId,
+            variant,
+            withMigrationUi: resolvedWithMigrationUi,
+            withTestPreset: resolvedWithTestPreset,
+            withWpEnv: resolvedWithWpEnv,
+        };
         const resolvedResult = dryRun
-            ? await buildScaffoldDryRunPlan({
-                allowExistingDir,
-                alternateRenderTargets,
-                answers,
-                cwd,
-                dataStorageMode: resolvedDataStorage,
-                externalLayerId: resolvedExternalLayerSelection.externalLayerId,
-                externalLayerSource: resolvedExternalLayerSelection.externalLayerSource,
-                externalLayerSourceLabel: normalizedExternalLayerSource,
-                installDependencies,
-                noInstall,
-                onProgress,
-                packageManager: resolvedPackageManager,
-                persistencePolicy: resolvedPersistencePolicy,
-                profile: resolvedProfile,
-                projectDir,
-                templateId: resolvedTemplateId,
-                variant,
-                withMigrationUi: resolvedWithMigrationUi,
-                withTestPreset: resolvedWithTestPreset,
-                withWpEnv: resolvedWithWpEnv,
-            })
+            ? await buildScaffoldDryRunPlan(emissionOptions)
             : {
                 plan: undefined,
-                result: await scaffoldProject({
-                    alternateRenderTargets,
-                    answers,
-                    allowExistingDir,
-                    cwd,
-                    dataStorageMode: resolvedDataStorage,
-                    externalLayerId: resolvedExternalLayerSelection.externalLayerId,
-                    externalLayerSource: resolvedExternalLayerSelection.externalLayerSource,
-                    externalLayerSourceLabel: normalizedExternalLayerSource,
-                    installDependencies,
-                    noInstall,
-                    onProgress,
-                    packageManager: resolvedPackageManager,
-                    persistencePolicy: resolvedPersistencePolicy,
-                    profile: resolvedProfile,
-                    projectDir,
-                    templateId: resolvedTemplateId,
-                    variant,
-                    withMigrationUi: resolvedWithMigrationUi,
-                    withTestPreset: resolvedWithTestPreset,
-                    withWpEnv: resolvedWithWpEnv,
-                }),
+                result: await emitScaffoldProject(emissionOptions),
             };
-        let availableScripts;
-        if (!dryRun) {
-            try {
-                const parsedPackageJson = await readJsonFile(path.join(projectDir, "package.json"), {
-                    context: "generated package manifest",
-                });
-                const scripts = parsedPackageJson.scripts &&
-                    typeof parsedPackageJson.scripts === "object" &&
-                    !Array.isArray(parsedPackageJson.scripts)
-                    ? parsedPackageJson.scripts
-                    : {};
-                availableScripts = Object.entries(scripts)
-                    .filter(([, value]) => typeof value === "string")
-                    .map(([scriptName]) => scriptName);
-            }
-            catch {
-                availableScripts = undefined;
-            }
-        }
+        const availableScripts = dryRun
+            ? undefined
+            : await readGeneratedPackageScripts(projectDir);
         return {
             dryRun,
             optionalOnboarding: getOptionalOnboarding({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",