@wp-typia/project-tools 0.24.3 → 0.24.5

package/dist/runtime/templates/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 "../shared/fs-async.js";
+import { readJsonFile } from "../shared/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/templates/cli-scaffold-output.d.ts

@@ -0,0 +1,79 @@
+import type { PackageManagerId } from "../shared/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/templates/cli-scaffold-output.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { formatInstallCommand, formatRunScript, } from "../shared/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/templates/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/templates/cli-scaffold-validation.js

@@ -0,0 +1,190 @@
+import path from "node:path";
+import { parseAlternateRenderTargets } from "../add/alternate-render-targets.js";
+import { parseCompoundInnerBlocksPreset } from "../add/compound-inner-blocks.js";
+import { assertBuiltInTemplateVariantAllowed } from "../cli/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/templates/cli-scaffold.d.ts

@@ -0,0 +1,70 @@
+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 "../shared/package-managers.js";
+import { type ExternalLayerSelectionOption } from "./external-layer-selection.js";
+import type { TemplateDefinition } from "./template-registry.js";
+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;
+    cwd?: string;
+    dataStorageMode?: string;
+    dryRun?: boolean;
+    externalLayerId?: string;
+    externalLayerSource?: string;
+    installDependencies?: ScaffoldInstallDependencies;
+    innerBlocksPreset?: string;
+    isInteractive?: boolean;
+    namespace?: string;
+    noInstall?: boolean;
+    onProgress?: ScaffoldEmissionOptions["onProgress"];
+    packageManager?: string;
+    phpPrefix?: string;
+    profile?: string;
+    projectInput: string;
+    promptText?: Parameters<typeof collectScaffoldAnswers>[0]["promptText"];
+    queryPostType?: string;
+    selectDataStorage?: () => Promise<DataStorageMode>;
+    selectExternalLayerId?: (options: ExternalLayerSelectionOption[]) => Promise<string>;
+    selectPackageManager?: () => Promise<PackageManagerId>;
+    selectPersistencePolicy?: () => Promise<PersistencePolicy>;
+    selectTemplate?: () => Promise<TemplateDefinition["id"]>;
+    selectWithMigrationUi?: () => Promise<boolean>;
+    selectWithTestPreset?: () => Promise<boolean>;
+    selectWithWpEnv?: () => Promise<boolean>;
+    templateId?: string;
+    textDomain?: string;
+    variant?: string;
+    persistencePolicy?: string;
+    withMigrationUi?: boolean;
+    withTestPreset?: boolean;
+    withWpEnv?: boolean;
+    yes?: boolean;
+}
+/**
+ * Resolve scaffold options, prompts, and follow-up steps for one CLI run.
+ *
+ * @param options CLI/runtime inputs used to collect answers and scaffold a
+ * project.
+ * @returns The scaffold result together with next-step guidance.
+ */
+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: import("./cli-scaffold-output.js").OptionalOnboardingGuidance;
+    plan: import("./cli-scaffold-emission.js").ScaffoldDryRunPlan | undefined;
+    projectDir: string;
+    projectInput: string;
+    packageManager: PackageManagerId;
+    nextSteps: string[];
+    result: {
+        warnings: string[];
+        packageManager: PackageManagerId;
+        projectDir: string;
+        selectedVariant: string | null;
+        templateId: string;
+        variables: import("./scaffold.js").ScaffoldTemplateVariables;
+    };
+}>;