@wp-typia/project-tools 0.17.0 → 0.19.0

package/dist/runtime/cli-scaffold.js

@@ -1,11 +1,83 @@
 import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { collectScaffoldAnswers, DATA_STORAGE_MODES, PERSISTENCE_POLICIES, isDataStorageMode, isPersistencePolicy, resolvePackageManagerId, resolveTemplateId, scaffoldProject, } from "./scaffold.js";
+import { parseAlternateRenderTargets } from "./alternate-render-targets.js";
+import { parseCompoundInnerBlocksPreset } from "./compound-inner-blocks.js";
 import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
 import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
 import { getOptionalOnboardingNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
+import { formatNonEmptyTargetDirectoryError } from "./scaffold-bootstrap.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 (!fs.existsSync(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, projectDir, templateId, variant, withMigrationUi, withTestPreset, withWpEnv, }) {
+    await assertDryRunTargetDirectoryReady(projectDir, allowExistingDir);
+    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "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,
+            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 fsp.rm(tempRoot, { force: true, recursive: true });
+    }
+}
 function validateCreateProjectInput(projectInput) {
     const normalizedProjectInput = projectInput.trim();
     if (normalizedProjectInput.length === 0) {
@@ -41,14 +113,74 @@ function templateUsesPersistenceSettings(templateId, options) {
 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 { dataStorageMode, persistencePolicy, templateId, variant } = 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 (variant && isBuiltInTemplateId(templateId)) {
-        throw new Error(`--variant is only supported for official external template configs. Received variant "${variant}" for built-in template "${templateId}".`);
+    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) {
@@ -135,14 +267,13 @@ export function getOptionalOnboarding({ availableScripts, packageManager, templa
  * project.
  * @returns The scaffold result together with next-step guidance.
  */
-export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templateId, dataStorageMode, externalLayerId, externalLayerSource, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, queryPostType, yes = false, noInstall = false, isInteractive = false, allowExistingDir = false, selectTemplate, selectDataStorage, selectExternalLayerId, selectPersistencePolicy, selectPackageManager, promptText, installDependencies = undefined, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }) {
-    const normalizedExternalLayerId = typeof externalLayerId === "string" && externalLayerId.trim().length > 0
-        ? externalLayerId.trim()
-        : undefined;
-    const normalizedExternalLayerSource = typeof externalLayerSource === "string" &&
-        externalLayerSource.trim().length > 0
-        ? externalLayerSource.trim()
-        : undefined;
+export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templateId, alternateRenderTargets, dataStorageMode, dryRun = false, externalLayerId, externalLayerSource, innerBlocksPreset, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, queryPostType, yes = false, noInstall = false, onProgress, isInteractive = false, allowExistingDir = false, selectTemplate, selectDataStorage, selectExternalLayerId, selectPersistencePolicy, selectPackageManager, promptText, installDependencies = undefined, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }) {
+    const normalizedExternalLayerId = normalizeOptionalCliString(externalLayerId);
+    const normalizedExternalLayerSource = resolveLocalCliPathOption({
+        cwd,
+        label: "--external-layer-source",
+        value: externalLayerSource,
+    });
     validateCreateProjectInput(projectInput);
     const resolvedTemplateId = await resolveTemplateId({
         templateId,
@@ -151,11 +282,14 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
         selectTemplate,
     });
     validateCreateFlagContract({
+        alternateRenderTargets,
         dataStorageMode,
+        innerBlocksPreset,
         persistencePolicy,
         templateId: resolvedTemplateId,
         variant,
     });
+    const resolvedInnerBlocksPreset = parseCompoundInnerBlocksPreset(innerBlocksPreset);
     const resolvedExternalLayerSelection = isBuiltInTemplateId(resolvedTemplateId) && isInteractive
         ? await resolveOptionalInteractiveExternalLayerId({
             callerCwd: cwd,
@@ -234,47 +368,81 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
             yes,
             promptText,
         });
-        const result = await scaffoldProject({
-            answers,
-            allowExistingDir,
-            cwd,
-            dataStorageMode: resolvedDataStorage,
-            externalLayerId: resolvedExternalLayerSelection.externalLayerId,
-            externalLayerSource: resolvedExternalLayerSelection.externalLayerSource,
-            externalLayerSourceLabel: normalizedExternalLayerSource,
-            installDependencies,
-            noInstall,
-            packageManager: resolvedPackageManager,
-            persistencePolicy: resolvedPersistencePolicy,
-            projectDir,
-            templateId: resolvedTemplateId,
-            variant,
-            withMigrationUi: resolvedWithMigrationUi,
-            withTestPreset: resolvedWithTestPreset,
-            withWpEnv: resolvedWithWpEnv,
-        });
-        let availableScripts;
-        try {
-            const parsedPackageJson = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8"));
-            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);
+        if (resolvedTemplateId === "compound" && resolvedInnerBlocksPreset) {
+            answers.compoundInnerBlocksPreset = resolvedInnerBlocksPreset;
         }
-        catch {
-            availableScripts = undefined;
+        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,
+                projectDir,
+                templateId: resolvedTemplateId,
+                variant,
+                withMigrationUi: resolvedWithMigrationUi,
+                withTestPreset: resolvedWithTestPreset,
+                withWpEnv: resolvedWithWpEnv,
+            })
+            : {
+                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,
+                    projectDir,
+                    templateId: resolvedTemplateId,
+                    variant,
+                    withMigrationUi: resolvedWithMigrationUi,
+                    withTestPreset: resolvedWithTestPreset,
+                    withWpEnv: resolvedWithWpEnv,
+                }),
+            };
+        let availableScripts;
+        if (!dryRun) {
+            try {
+                const parsedPackageJson = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8"));
+                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;
+            }
         }
         return {
+            dryRun,
             optionalOnboarding: getOptionalOnboarding({
                 availableScripts,
                 packageManager: resolvedPackageManager,
                 templateId: resolvedTemplateId,
-                compoundPersistenceEnabled: result.variables.compoundPersistenceEnabled === "true",
+                compoundPersistenceEnabled: resolvedResult.result.variables.compoundPersistenceEnabled === "true",
             }),
+            plan: resolvedResult.plan,
             projectDir,
             projectInput,
             packageManager: resolvedPackageManager,
@@ -286,8 +454,16 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
                 templateId: resolvedTemplateId,
             }),
             result: {
-                ...result,
-                warnings: [...result.warnings, ...collectProjectDirectoryWarnings(projectDir)],
+                ...resolvedResult.result,
+                warnings: [
+                    ...resolvedResult.result.warnings,
+                    ...collectTemplateCapabilityWarnings({
+                        queryPostType,
+                        templateId: resolvedTemplateId,
+                        withMigrationUi,
+                    }),
+                    ...collectProjectDirectoryWarnings(projectDir),
+                ],
             },
         };
     }

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

@@ -8,18 +8,18 @@ import type { TemplateDefinition } from "./template-registry.js";
  */
 export declare function formatTemplateSummary(template: TemplateDefinition): string;
 /**
- * Format the feature hint line shown under a template summary.
+ * Format the feature and capability hint lines shown under a template summary.
  *
  * @param template Template metadata including the `features` list.
- * @returns Indented feature text for CLI list output.
+ * @returns Indented feature and capability text for CLI list output.
  */
 export declare function formatTemplateFeatures(template: TemplateDefinition): string;
 /**
  * Format the detailed template description for `templates inspect`.
  *
  * This expands special layer combinations for the `persistence` and `compound`
- * templates and returns a multi-line block including category, overlay path,
- * resolved layers, and feature labels.
+ * templates and returns a multi-line block centered on human-facing identity,
+ * capabilities, and logical layer composition.
  *
  * @param template Template metadata including `id`, `defaultCategory`,
  * `templateDir`, and `features`.

package/dist/runtime/cli-templates.js

@@ -1,5 +1,5 @@
-import { getBuiltInTemplateLayerDirs } from "./template-builtins.js";
-import { getTemplateById, getTemplateSelectOptions, isBuiltInTemplateId, listTemplates, } from "./template-registry.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, getTemplateById, getTemplateSelectOptions, isBuiltInTemplateId, listTemplates, } from "./template-registry.js";
+const WORKSPACE_TEMPLATE_ALIAS = "workspace";
 /**
  * Format one line of template list output for a built-in template.
  *
@@ -10,62 +10,127 @@ export function formatTemplateSummary(template) {
     return `${template.id.padEnd(14)} ${template.description}`;
 }
 /**
- * Format the feature hint line shown under a template summary.
+ * Format the feature and capability hint lines shown under a template summary.
  *
  * @param template Template metadata including the `features` list.
- * @returns Indented feature text for CLI list output.
+ * @returns Indented feature and capability text for CLI list output.
  */
 export function formatTemplateFeatures(template) {
-    return `  ${template.features.join(" • ")}`;
+    const lines = [`  Features: ${template.features.join(" • ")}`];
+    const capabilityHints = getTemplateCapabilityHints(template);
+    if (capabilityHints.length > 0) {
+        lines.push(`  Supports: ${capabilityHints.join(" • ")}`);
+    }
+    const specialNotes = getTemplateSpecialNotes(template);
+    if (specialNotes.length > 0) {
+        lines.push(`  Notes: ${specialNotes.join(" • ")}`);
+    }
+    if (template.id === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        lines.push(`  Alias: ${WORKSPACE_TEMPLATE_ALIAS} (\`--template ${WORKSPACE_TEMPLATE_ALIAS}\`)`);
+    }
+    return lines.join("\n");
 }
 /**
  * Format the detailed template description for `templates inspect`.
  *
  * This expands special layer combinations for the `persistence` and `compound`
- * templates and returns a multi-line block including category, overlay path,
- * resolved layers, and feature labels.
+ * templates and returns a multi-line block centered on human-facing identity,
+ * capabilities, and logical layer composition.
  *
  * @param template Template metadata including `id`, `defaultCategory`,
  * `templateDir`, and `features`.
  * @returns Multi-line template details text for CLI output.
  */
 export function formatTemplateDetails(template) {
+    const detailLines = [
+        template.id,
+        `Summary: ${template.description}`,
+        ...getTemplateIdentityLines(template),
+        `Category: ${template.defaultCategory}`,
+    ];
+    const capabilityHints = getTemplateCapabilityHints(template);
+    if (capabilityHints.length > 0) {
+        detailLines.push("Capabilities:");
+        for (const capabilityHint of capabilityHints) {
+            detailLines.push(`  - ${capabilityHint}`);
+        }
+    }
+    const specialNotes = getTemplateSpecialNotes(template);
+    if (specialNotes.length > 0) {
+        detailLines.push("Notes:");
+        for (const specialNote of specialNotes) {
+            detailLines.push(`  - ${specialNote}`);
+        }
+    }
+    detailLines.push("Logical layers:");
+    for (const logicalLayer of getTemplateLogicalLayerSummaries(template)) {
+        detailLines.push(`  - ${logicalLayer}`);
+    }
+    detailLines.push(`Features: ${template.features.join(", ")}`);
+    return detailLines.join("\n");
+}
+function getTemplateCapabilityHints(template) {
+    if (template.id === "persistence" || template.id === "compound") {
+        return [
+            "--alternate-render-targets",
+            "--data-storage",
+            "--persistence-policy",
+            "external layers",
+        ];
+    }
+    if (template.id === "query-loop") {
+        return ["--query-post-type", "external layers"];
+    }
+    if (isBuiltInTemplateId(template.id)) {
+        return ["external layers"];
+    }
+    return [];
+}
+function getTemplateSpecialNotes(template) {
+    if (template.id === "query-loop") {
+        return [
+            "Create-time variation scaffold only; use `wp-typia create <project-dir> --template query-loop` instead of `wp-typia add block`.",
+            "Owns a `core/query` variation, so it does not generate `src/types.ts`, `block.json`, or Typia manifests.",
+        ];
+    }
+    return [];
+}
+function getTemplateIdentityLines(template) {
+    if (template.id === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        return [
+            "Identity:",
+            `  - Official package: ${OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE}`,
+            `  - Alias: ${WORKSPACE_TEMPLATE_ALIAS} (\`--template ${WORKSPACE_TEMPLATE_ALIAS}\`)`,
+            "Type: official workspace scaffold",
+        ];
+    }
+    return [
+        "Identity:",
+        `  - Built-in template id: ${template.id}`,
+        "Type: built-in block scaffold",
+    ];
+}
+function getTemplateLogicalLayerSummaries(template) {
     if (!isBuiltInTemplateId(template.id)) {
+        return ["workspace package scaffold"];
+    }
+    if (template.id === "persistence") {
+        return [
+            "authenticated write policy: shared/base -> rest helpers (shared) -> persistence core -> authenticated write policy -> persistence overlay",
+            "public write policy: shared/base -> rest helpers (shared) -> persistence core -> public write policy -> persistence overlay",
+        ];
+    }
+    if (template.id === "compound") {
         return [
-            template.id,
-            template.description,
-            `Category: ${template.defaultCategory}`,
-            `Overlay path: ${template.templateDir}`,
-            "Layers: workspace package scaffold",
-            `Features: ${template.features.join(", ")}`,
-        ].join("\n");
+            "pure block family: shared/base -> compound core -> compound overlay",
+            "authenticated persistence: shared/base -> compound core -> rest helpers (shared) -> compound persistence core -> authenticated write policy -> compound overlay",
+            "public persistence: shared/base -> compound core -> rest helpers (shared) -> compound persistence core -> public write policy -> compound overlay",
+        ];
     }
-    const layers = template.id === "persistence"
-        ? [
-            `authenticated: ${getBuiltInTemplateLayerDirs(template.id, { persistencePolicy: "authenticated" }).join(" -> ")}`,
-            `public: ${getBuiltInTemplateLayerDirs(template.id, { persistencePolicy: "public" }).join(" -> ")}`,
-        ]
-        : template.id === "compound"
-            ? [
-                `pure: ${getBuiltInTemplateLayerDirs(template.id).join(" -> ")}`,
-                `authenticated+persistence: ${getBuiltInTemplateLayerDirs(template.id, {
-                    persistenceEnabled: true,
-                    persistencePolicy: "authenticated",
-                }).join(" -> ")}`,
-                `public+persistence: ${getBuiltInTemplateLayerDirs(template.id, {
-                    persistenceEnabled: true,
-                    persistencePolicy: "public",
-                }).join(" -> ")}`,
-            ]
-            : [getBuiltInTemplateLayerDirs(template.id).join(" -> ")];
+    const overlayName = template.id === "query-loop" ? "query-loop overlay" : `${template.id} overlay`;
     return [
-        template.id,
-        template.description,
-        `Category: ${template.defaultCategory}`,
-        `Overlay path: ${template.templateDir}`,
-        `Layers: ${layers.join("\n")}`,
-        `Features: ${template.features.join(", ")}`,
-    ].join("\n");
+        `shared/base -> ${overlayName}`,
+    ];
 }
 export { getTemplateById, getTemplateSelectOptions, listTemplates };
 export { isBuiltInTemplateId };

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

@@ -0,0 +1,66 @@
+/**
+ * Normalize one optional CLI string flag by trimming whitespace and collapsing
+ * empty strings to `undefined`.
+ *
+ * @param value Raw CLI value before normalization.
+ * @returns The trimmed string when present, otherwise `undefined`.
+ */
+export declare function normalizeOptionalCliString(value?: string): string | undefined;
+/**
+ * Resolve one CLI path flag relative to the caller when it is expressed as a
+ * local filesystem path.
+ *
+ * Non-local values such as npm package specs or `github:` locators pass
+ * through unchanged. Local relative and absolute paths are resolved against the
+ * provided `cwd` and must exist on disk.
+ *
+ * @param options Path resolution inputs for one CLI flag.
+ * @param options.cwd Caller working directory used for relative path
+ * resolution.
+ * @param options.label Human-readable option label used in thrown errors.
+ * @param options.value Raw CLI value before trimming and path resolution.
+ * @returns The normalized string, or `undefined` when the option was omitted.
+ * @throws When a local-looking path resolves to a missing filesystem entry.
+ */
+export declare function resolveLocalCliPathOption(options: {
+    cwd: string;
+    label: string;
+    value?: string;
+}): string | undefined;
+/**
+ * Validate the built-in template composition rule for external layers.
+ *
+ * @param options External layer CLI options after normalization.
+ * @param options.externalLayerId Optional selected layer id.
+ * @param options.externalLayerSource Optional layer source locator or path.
+ * @throws When `externalLayerId` is provided without `externalLayerSource`.
+ */
+export declare function assertExternalLayerCompositionOptions(options: {
+    externalLayerId?: string;
+    externalLayerSource?: string;
+}): void;
+/**
+ * Build the shared error message used when a built-in template receives a
+ * `--variant` override.
+ *
+ * @param options Built-in template context.
+ * @param options.templateId Built-in template id that rejected the variant.
+ * @param options.variant User-supplied variant override.
+ * @returns The canonical user-facing error message.
+ */
+export declare function createBuiltInVariantErrorMessage(options: {
+    templateId: string;
+    variant: string;
+}): string;
+/**
+ * Reject unsupported `--variant` usage for built-in templates.
+ *
+ * @param options Built-in template validation context.
+ * @param options.templateId Built-in template id being scaffolded.
+ * @param options.variant Optional variant override from CLI flags.
+ * @throws When a built-in template receives any explicit `--variant` value.
+ */
+export declare function assertBuiltInTemplateVariantAllowed(options: {
+    templateId: string;
+    variant?: string;
+}): void;