@wp-typia/project-tools 0.18.0 → 0.19.1

package/dist/runtime/scaffold.d.ts

@@ -1,4 +1,5 @@
 import type { PackageManagerId } from "./package-managers.js";
+import type { ScaffoldTemplateVariableGroupsCarrier } from "./scaffold-template-variable-groups.js";
 /**
  * User-facing scaffold answers before template rendering.
  *
@@ -8,6 +9,7 @@ import type { PackageManagerId } from "./package-managers.js";
  */
 export interface ScaffoldAnswers {
     author: string;
+    compoundInnerBlocksPreset?: import("./compound-inner-blocks.js").CompoundInnerBlocksPresetId;
     dataStorageMode?: DataStorageMode;
     description: string;
     /** Block namespace used in generated block names such as `namespace/slug`. */
@@ -28,7 +30,9 @@ export type PersistencePolicy = (typeof PERSISTENCE_POLICIES)[number];
 /**
  * Normalized template variables shared by built-in and remote scaffold flows.
  */
-export interface ScaffoldTemplateVariables extends Record<string, string> {
+export interface FlatScaffoldTemplateVariables extends Record<string, string> {
+    alternateRenderTargetsCsv: string;
+    alternateRenderTargetsJson: string;
     apiClientPackageVersion: string;
     author: string;
     blockRuntimePackageVersion: string;
@@ -42,6 +46,17 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     compoundChildIcon: string;
     compoundChildTitleJson: string;
     compoundPersistenceEnabled: "false" | "true";
+    compoundInnerBlocksDirectInsert: "false" | "true";
+    compoundInnerBlocksOrientation: "" | "horizontal" | "vertical";
+    compoundInnerBlocksOrientationExpression: string;
+    compoundInnerBlocksPreset: string;
+    compoundInnerBlocksPresetDescription: string;
+    compoundInnerBlocksPresetLabel: string;
+    compoundInnerBlocksTemplateLockExpression: string;
+    hasAlternateEmailRenderTarget: "false" | "true";
+    hasAlternateMjmlRenderTarget: "false" | "true";
+    hasAlternatePlainTextRenderTarget: "false" | "true";
+    hasAlternateRenderTargets: "false" | "true";
     projectToolsPackageVersion: string;
     cssClassName: string;
     dashCase: string;
@@ -80,6 +95,8 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     titleCase: string;
     persistencePolicy: PersistencePolicy;
 }
+export interface ScaffoldTemplateVariables extends FlatScaffoldTemplateVariables, ScaffoldTemplateVariableGroupsCarrier {
+}
 /**
  * Resolve scaffold template input from either built-in template ids or custom
  * template identifiers such as local paths, GitHub refs, and npm packages.
@@ -131,6 +148,7 @@ export interface ScaffoldProgressEvent {
 }
 interface ScaffoldProjectOptions {
     allowExistingDir?: boolean;
+    alternateRenderTargets?: string;
     answers: ScaffoldAnswers;
     cwd?: string;
     dataStorageMode?: DataStorageMode;
@@ -161,6 +179,7 @@ export interface ScaffoldProjectResult {
 export { buildBlockCssClassName } from "./scaffold-identifiers.js";
 export { collectScaffoldAnswers, detectAuthor, getDefaultAnswers, resolvePackageManagerId, resolveTemplateId, } from "./scaffold-answer-resolution.js";
 export { getTemplateVariables } from "./scaffold-template-variables.js";
+export { getScaffoldTemplateVariableGroups, type BasicScaffoldTemplateVariableGroups, type CompoundScaffoldTemplateVariableGroups, type ExternalScaffoldTemplateVariableGroups, type InteractivityScaffoldTemplateVariableGroups, type PersistenceScaffoldTemplateVariableGroups, type QueryLoopScaffoldTemplateVariableGroups, type ScaffoldTemplateFamily, type ScaffoldTemplateVariableGroups, type ScaffoldTemplateVariableGroupsCarrier, } from "./scaffold-template-variable-groups.js";
 export declare function isDataStorageMode(value: string): value is DataStorageMode;
 export declare function isPersistencePolicy(value: string): value is PersistencePolicy;
-export declare function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd, allowExistingDir, noInstall, installDependencies, onProgress, variant, withMigrationUi, withTestPreset, withWpEnv, }: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;
+export declare function scaffoldProject({ projectDir, templateId, answers, alternateRenderTargets, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd, allowExistingDir, noInstall, installDependencies, onProgress, variant, withMigrationUi, withTestPreset, withWpEnv, }: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;

package/dist/runtime/scaffold.js

@@ -12,12 +12,15 @@ import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./tem
 import { resolveTemplateSource } from "./template-source.js";
 import { BlockGeneratorService, } from "./block-generator-service.js";
 import { getTemplateVariables } from "./scaffold-template-variables.js";
+import { getScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
+import { assertExternalLayerCompositionOptions, } from "./cli-validation.js";
 const WORKSPACE_TEMPLATE_ALIAS = "workspace";
 export const DATA_STORAGE_MODES = ["post-meta", "custom-table"];
 export const PERSISTENCE_POLICIES = ["authenticated", "public"];
 export { buildBlockCssClassName } from "./scaffold-identifiers.js";
 export { collectScaffoldAnswers, detectAuthor, getDefaultAnswers, resolvePackageManagerId, resolveTemplateId, } from "./scaffold-answer-resolution.js";
 export { getTemplateVariables } from "./scaffold-template-variables.js";
+export { getScaffoldTemplateVariableGroups, } from "./scaffold-template-variable-groups.js";
 export function isDataStorageMode(value) {
     return DATA_STORAGE_MODES.includes(value);
 }
@@ -32,13 +35,14 @@ function normalizeTemplateSelection(templateId) {
 async function reportScaffoldProgress(onProgress, event) {
     await onProgress?.(event);
 }
-export async function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, onProgress = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+export async function scaffoldProject({ projectDir, templateId, answers, alternateRenderTargets, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, onProgress = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
     const resolvedTemplateId = normalizeTemplateSelection(templateId);
     const resolvedPackageManager = getPackageManager(packageManager).id;
     const isBuiltInTemplate = isBuiltInTemplateId(resolvedTemplateId);
-    if (externalLayerId && !externalLayerSource) {
-        throw new Error("externalLayerId requires externalLayerSource when composing built-in template layers.");
-    }
+    assertExternalLayerCompositionOptions({
+        externalLayerId,
+        externalLayerSource,
+    });
     if (isBuiltInTemplate) {
         const blockGeneratorService = new BlockGeneratorService();
         await reportScaffoldProgress(onProgress, {
@@ -48,6 +52,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
         });
         const plan = await blockGeneratorService.plan({
             allowExistingDir,
+            alternateRenderTargets,
             answers,
             cwd,
             dataStorageMode: dataStorageMode ?? answers.dataStorageMode,
@@ -161,8 +166,10 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
     await fsp.writeFile(gitignorePath, mergeTextLines(buildGitignore(), existingGitignore), "utf8");
     await normalizePackageJson(projectDir, resolvedPackageManager);
     if (isBuiltInTemplate) {
+        const variableGroups = getScaffoldTemplateVariableGroups(variables);
         await applyGeneratedProjectDxPackageJson({
-            compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
+            compoundPersistenceEnabled: variableGroups.compound.enabled &&
+                variableGroups.compound.persistenceEnabled,
             packageManager: resolvedPackageManager,
             projectDir,
             templateId: resolvedTemplateId,

package/dist/runtime/temp-roots.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Required prefix for managed wp-typia temporary directories.
+ */
+export declare const WP_TYPIA_TEMP_ROOT_PREFIX = "wp-typia-";
+/**
+ * Default age threshold for pruning stale wp-typia temp roots.
+ */
+export declare const STALE_TEMP_ROOT_MAX_AGE_MS: number;
+type TempRootOptions = {
+    maxAgeMs?: number;
+    now?: number;
+    tmpDir?: string;
+};
+/**
+ * Remove a managed temp root and stop tracking it for process-level cleanup.
+ *
+ * @param tempRoot Absolute temporary directory path to remove.
+ */
+export declare function cleanupManagedTempRoot(tempRoot: string): Promise<void>;
+/**
+ * Remove stale `wp-typia-*` temp directories from the target temp root.
+ *
+ * @param options Optional temp directory, age threshold, and clock override.
+ * @returns Absolute temp-root paths removed during the cleanup pass.
+ */
+export declare function cleanupStaleTempRoots({ maxAgeMs, now, tmpDir, }?: TempRootOptions): Promise<string[]>;
+/**
+ * Create a managed wp-typia temp root and install process cleanup handlers.
+ *
+ * @param prefix Temp directory prefix. Must start with `wp-typia-`.
+ * @param options Optional temp directory override.
+ * @returns The created temp-root path plus an async cleanup helper.
+ */
+export declare function createManagedTempRoot(prefix: string, options?: Pick<TempRootOptions, "tmpDir">): Promise<{
+    cleanup: () => Promise<void>;
+    path: string;
+}>;
+/**
+ * Snapshot the currently tracked temp roots for diagnostics and tests.
+ *
+ * @returns Absolute paths for temp roots currently registered for cleanup.
+ */
+export declare function getTrackedTempRoots(): string[];
+export {};

package/dist/runtime/temp-roots.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Required prefix for managed wp-typia temporary directories.
+ */
+export const WP_TYPIA_TEMP_ROOT_PREFIX = "wp-typia-";
+/**
+ * Default age threshold for pruning stale wp-typia temp roots.
+ */
+export const STALE_TEMP_ROOT_MAX_AGE_MS = 1000 * 60 * 60 * 24;
+const trackedTempRoots = new Set();
+let cleanupHandlersInstalled = false;
+let staleCleanupRan = false;
+let signalCleanupInProgress = false;
+function getTempDir(tmpDir) {
+    return tmpDir ?? os.tmpdir();
+}
+function cleanupTrackedTempRootsSync() {
+    for (const tempRoot of [...trackedTempRoots]) {
+        trackedTempRoots.delete(tempRoot);
+        try {
+            fs.rmSync(tempRoot, { force: true, recursive: true });
+        }
+        catch { }
+    }
+}
+function installCleanupHandlers() {
+    if (cleanupHandlersInstalled) {
+        return;
+    }
+    cleanupHandlersInstalled = true;
+    process.on("exit", cleanupTrackedTempRootsSync);
+    for (const [signal, exitCode] of [
+        ["SIGHUP", 129],
+        ["SIGINT", 130],
+        ["SIGTERM", 143],
+    ]) {
+        process.once(signal, () => {
+            if (signalCleanupInProgress) {
+                return;
+            }
+            signalCleanupInProgress = true;
+            cleanupTrackedTempRootsSync();
+            process.exitCode = exitCode;
+            process.exit();
+        });
+    }
+}
+/**
+ * Remove a managed temp root and stop tracking it for process-level cleanup.
+ *
+ * @param tempRoot Absolute temporary directory path to remove.
+ */
+export async function cleanupManagedTempRoot(tempRoot) {
+    trackedTempRoots.delete(tempRoot);
+    await fsp.rm(tempRoot, { force: true, recursive: true });
+}
+/**
+ * Remove stale `wp-typia-*` temp directories from the target temp root.
+ *
+ * @param options Optional temp directory, age threshold, and clock override.
+ * @returns Absolute temp-root paths removed during the cleanup pass.
+ */
+export async function cleanupStaleTempRoots({ maxAgeMs = STALE_TEMP_ROOT_MAX_AGE_MS, now = Date.now(), tmpDir, } = {}) {
+    const resolvedTmpDir = getTempDir(tmpDir);
+    const removedRoots = [];
+    const entries = await fsp.readdir(resolvedTmpDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory() ||
+            !entry.name.startsWith(WP_TYPIA_TEMP_ROOT_PREFIX)) {
+            continue;
+        }
+        const tempRoot = path.join(resolvedTmpDir, entry.name);
+        if (trackedTempRoots.has(tempRoot)) {
+            continue;
+        }
+        let stats;
+        try {
+            stats = await fsp.stat(tempRoot);
+        }
+        catch {
+            continue;
+        }
+        if (now - stats.mtimeMs < maxAgeMs) {
+            continue;
+        }
+        try {
+            await fsp.rm(tempRoot, { force: true, recursive: true });
+            removedRoots.push(tempRoot);
+        }
+        catch {
+            continue;
+        }
+    }
+    return removedRoots;
+}
+/**
+ * Create a managed wp-typia temp root and install process cleanup handlers.
+ *
+ * @param prefix Temp directory prefix. Must start with `wp-typia-`.
+ * @param options Optional temp directory override.
+ * @returns The created temp-root path plus an async cleanup helper.
+ */
+export async function createManagedTempRoot(prefix, options = {}) {
+    if (!prefix.startsWith(WP_TYPIA_TEMP_ROOT_PREFIX)) {
+        throw new Error(`Managed wp-typia temp roots must use the "${WP_TYPIA_TEMP_ROOT_PREFIX}" prefix.`);
+    }
+    installCleanupHandlers();
+    if (!staleCleanupRan) {
+        staleCleanupRan = true;
+        await cleanupStaleTempRoots({ tmpDir: options.tmpDir });
+    }
+    const tempRoot = await fsp.mkdtemp(path.join(getTempDir(options.tmpDir), prefix));
+    trackedTempRoots.add(tempRoot);
+    return {
+        cleanup: async () => cleanupManagedTempRoot(tempRoot),
+        path: tempRoot,
+    };
+}
+/**
+ * Snapshot the currently tracked temp roots for diagnostics and tests.
+ *
+ * @returns Absolute paths for temp roots currently registered for cleanup.
+ */
+export function getTrackedTempRoots() {
+    return [...trackedTempRoots];
+}

package/dist/runtime/template-builtins.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { promises as fsp } from "node:fs";
+import { createManagedTempRoot } from "./temp-roots.js";
 import { getTemplateById, SHARED_BASE_TEMPLATE_ROOT, SHARED_COMPOUND_TEMPLATE_ROOT, SHARED_MIGRATION_UI_TEMPLATE_ROOT, SHARED_PERSISTENCE_TEMPLATE_ROOT, SHARED_PRESET_TEMPLATE_ROOT, SHARED_REST_HELPER_TEMPLATE_ROOT, SHARED_WORKSPACE_TEMPLATE_ROOT, } from "./template-registry.js";
 const BUILT_IN_SHARED_TEMPLATE_LAYERS = Object.freeze([
     {
@@ -152,7 +152,7 @@ function resolveMaterializedTemplateLayerDirs(templateId, layerDirs) {
 async function materializeBuiltInTemplateSource(templateId, layerDirs) {
     const template = getTemplateById(templateId);
     const materializedLayerDirs = resolveMaterializedTemplateLayerDirs(templateId, layerDirs);
-    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-template-"));
+    const { path: tempRoot, cleanup } = await createManagedTempRoot("wp-typia-template-");
     const templateDir = path.join(tempRoot, templateId);
     try {
         await fsp.mkdir(templateDir, { recursive: true });
@@ -164,7 +164,7 @@ async function materializeBuiltInTemplateSource(templateId, layerDirs) {
         }
     }
     catch (error) {
-        await fsp.rm(tempRoot, { force: true, recursive: true });
+        await cleanup();
         throw error;
     }
     return {
@@ -174,9 +174,7 @@ async function materializeBuiltInTemplateSource(templateId, layerDirs) {
         features: template.features,
         format: "wp-typia",
         templateDir,
-        cleanup: async () => {
-            await fsp.rm(tempRoot, { force: true, recursive: true });
-        },
+        cleanup,
     };
 }
 export async function resolveBuiltInTemplateSourceFromLayerDirs(templateId, layerDirs) {

package/dist/runtime/template-registry.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Resolve the canonical `@wp-typia/project-tools` package root.
+ *
+ * When `WP_TYPIA_PROJECT_TOOLS_PACKAGE_ROOT` is set, the override is only
+ * accepted if it points at a readable package manifest whose `name` matches
+ * `@wp-typia/project-tools`. Invalid or stale overrides are ignored and normal
+ * upward package-root discovery continues.
+ */
 export declare function resolvePackageRoot(startDir: string): string;
 export declare const PROJECT_TOOLS_PACKAGE_ROOT: string;
 export declare const TEMPLATE_ROOT: string;

package/dist/runtime/template-registry.js

@@ -3,14 +3,47 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getBuiltInTemplateMetadataDefaults } from "./template-defaults.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_TOOLS_PACKAGE_ROOT_ENV = "WP_TYPIA_PROJECT_TOOLS_PACKAGE_ROOT";
+const PROJECT_TOOLS_PACKAGE_NAME = "@wp-typia/project-tools";
+function resolveValidProjectToolsPackageRoot(candidateRoot) {
+    const packageJsonPath = path.join(candidateRoot, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return undefined;
+    }
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        return packageJson.name === PROJECT_TOOLS_PACKAGE_NAME
+            ? candidateRoot
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the canonical `@wp-typia/project-tools` package root.
+ *
+ * When `WP_TYPIA_PROJECT_TOOLS_PACKAGE_ROOT` is set, the override is only
+ * accepted if it points at a readable package manifest whose `name` matches
+ * `@wp-typia/project-tools`. Invalid or stale overrides are ignored and normal
+ * upward package-root discovery continues.
+ */
 export function resolvePackageRoot(startDir) {
+    const overriddenPackageRoot = process.env[PROJECT_TOOLS_PACKAGE_ROOT_ENV]?.trim();
+    if (overriddenPackageRoot) {
+        const resolvedOverride = path.resolve(overriddenPackageRoot);
+        const validOverride = resolveValidProjectToolsPackageRoot(resolvedOverride);
+        if (validOverride) {
+            return validOverride;
+        }
+    }
     let currentDir = startDir;
     while (true) {
         const packageJsonPath = path.join(currentDir, "package.json");
         if (fs.existsSync(packageJsonPath)) {
             try {
                 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-                if (packageJson.name === "@wp-typia/project-tools") {
+                if (packageJson.name === PROJECT_TOOLS_PACKAGE_NAME) {
                     return currentDir;
                 }
             }

package/dist/runtime/template-source-external.d.ts

@@ -3,6 +3,7 @@ import type { SeedSource, TemplateVariableContext } from './template-source-cont
  * Candidate filenames for official external template config entrypoints.
  */
 export declare const EXTERNAL_TEMPLATE_ENTRY_CANDIDATES: readonly ["index.js", "index.cjs", "index.mjs"];
+export declare const EXTERNAL_TEMPLATE_TRUST_WARNING = "External template configs execute trusted JavaScript during scaffolding. Review the template source before using local paths, GitHub repos, or npm packages you do not already trust.";
 /**
  * Search a source directory for the first supported external template entry.
  *

package/dist/runtime/template-source-external.js

@@ -1,11 +1,10 @@
 /// <reference path="./external-template-modules.d.ts" />
 import fs from 'node:fs';
-import { promises as fsp } from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isPlainObject } from './object-utils.js';
 import { toSegmentPascalCase } from './string-case.js';
+import { createManagedTempRoot } from './temp-roots.js';
 import { copyRawDirectory, copyRenderedDirectory } from './template-render.js';
 /**
  * Candidate filenames for official external template config entrypoints.
@@ -15,6 +14,7 @@ export const EXTERNAL_TEMPLATE_ENTRY_CANDIDATES = [
     'index.cjs',
     'index.mjs',
 ];
+export const EXTERNAL_TEMPLATE_TRUST_WARNING = 'External template configs execute trusted JavaScript during scaffolding. Review the template source before using local paths, GitHub repos, or npm packages you do not already trust.';
 const TEMPLATE_WARNING_MESSAGE = 'wp-typia owns package/tooling/sync setup for generated projects, so this external template setting is ignored.';
 function getTemplateWarning(key) {
     return `Ignoring external template config key "${key}": ${TEMPLATE_WARNING_MESSAGE}`;
@@ -53,7 +53,7 @@ async function loadExternalTemplateConfig(sourceDir) {
     if (!isPlainObject(loadedConfig)) {
         throw new Error(`External template config must export an object: ${entryPath}`);
     }
-    const warnings = [];
+    const warnings = [EXTERNAL_TEMPLATE_TRUST_WARNING];
     for (const ignoredKey of [
         'wpScripts',
         'wpEnv',
@@ -174,10 +174,7 @@ export async function renderCreateBlockExternalTemplate(sourceDir, context, requ
     const { config, warnings } = await loadExternalTemplateConfig(sourceDir);
     const { selectedVariant, variantConfig } = getVariantConfig(config, requestedVariant);
     const { folderName, formatHint, templatePath } = resolveConfiguredTemplatePath(config, variantConfig);
-    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-create-block-external-'));
-    const cleanup = async () => {
-        await fsp.rm(tempRoot, { force: true, recursive: true });
-    };
+    const { path: tempRoot, cleanup } = await createManagedTempRoot('wp-typia-create-block-external-');
     try {
         const renderedRoot = path.join(tempRoot, 'rendered');
         const blockDir = resolveSourceSubpath(renderedRoot, folderName);

package/dist/runtime/template-source-remote.js

@@ -1,9 +1,27 @@
 import fs from 'node:fs';
 import { promises as fsp } from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, } from './template-builtins.js';
 import { copyRawDirectory } from './template-render.js';
+import { createManagedTempRoot } from './temp-roots.js';
+async function cleanupSeedRootPair(cleanup, seedCleanup) {
+    let cleanupError;
+    try {
+        await cleanup();
+    }
+    catch (error) {
+        cleanupError = error;
+    }
+    try {
+        await seedCleanup?.();
+    }
+    catch (error) {
+        cleanupError ?? (cleanupError = error);
+    }
+    if (cleanupError !== undefined) {
+        throw cleanupError;
+    }
+}
 function getDefaultCategoryFromBlockJson(blockJson) {
     return typeof blockJson.category === 'string' &&
         blockJson.category.trim().length > 0
@@ -48,10 +66,14 @@ function readTemplatePackageJson(sourceDir) {
             continue;
         }
         try {
-            return JSON.parse(fs.readFileSync(candidate, 'utf8'));
+            return {
+                packageJson: JSON.parse(fs.readFileSync(candidate, 'utf8')),
+                sourcePath: candidate,
+            };
         }
-        catch {
-            continue;
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown parse failure';
+            throw new Error(`Failed to parse template metadata file "${candidate}": ${message}`);
         }
     }
     return null;
@@ -61,10 +83,18 @@ function readTemplatePackageJson(sourceDir) {
  * manifest and return it when present.
  */
 export function getTemplateProjectType(sourceDir) {
-    const packageJson = readTemplatePackageJson(sourceDir);
-    return typeof packageJson?.wpTypia?.projectType === 'string'
-        ? packageJson.wpTypia.projectType
-        : null;
+    const packageJsonEntry = readTemplatePackageJson(sourceDir);
+    if (!packageJsonEntry) {
+        return null;
+    }
+    const projectType = packageJsonEntry.packageJson.wpTypia?.projectType;
+    if (projectType === undefined) {
+        return null;
+    }
+    if (typeof projectType !== 'string' || projectType.trim().length === 0) {
+        throw new Error(`Template metadata file "${packageJsonEntry.sourcePath}" defines wpTypia.projectType, but it must be a non-empty string.`);
+    }
+    return projectType;
 }
 /**
  * Copy a wp-typia seed into a normalized temporary template directory.
@@ -73,7 +103,7 @@ export function getTemplateProjectType(sourceDir) {
  * @returns A cloned seed whose cleanup removes the temp root and original seed.
  */
 export async function normalizeWpTypiaTemplateSeed(seed) {
-    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-template-source-'));
+    const { path: tempRoot, cleanup } = await createManagedTempRoot('wp-typia-template-source-');
     const normalizedDir = path.join(tempRoot, 'template');
     try {
         await copyRawDirectory(seed.blockDir, normalizedDir, {
@@ -92,15 +122,12 @@ export async function normalizeWpTypiaTemplateSeed(seed) {
         }
     }
     catch (error) {
-        await fsp.rm(tempRoot, { force: true, recursive: true });
+        await Promise.allSettled([cleanup(), seed.cleanup?.()]);
         throw error;
     }
     return {
         blockDir: normalizedDir,
-        cleanup: async () => {
-            await fsp.rm(tempRoot, { force: true, recursive: true });
-            await seed.cleanup?.();
-        },
+        cleanup: async () => cleanupSeedRootPair(cleanup, seed.cleanup),
         rootDir: normalizedDir,
         selectedVariant: seed.selectedVariant,
         warnings: seed.warnings,
@@ -296,7 +323,7 @@ async function removeSeedEntryConflicts(templateDir) {
  * @returns A normalized template source rooted in a temporary directory.
  */
 export async function normalizeCreateBlockSubset(seed, context) {
-    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-remote-template-'));
+    const { path: tempRoot, cleanup } = await createManagedTempRoot('wp-typia-remote-template-');
     try {
         const templateDir = path.join(tempRoot, 'template');
         const blockJson = readRemoteBlockJson(seed.blockDir);
@@ -353,17 +380,11 @@ export async function normalizeCreateBlockSubset(seed, context) {
             selectedVariant: seed.selectedVariant ?? null,
             templateDir,
             warnings: seed.warnings ?? [],
-            cleanup: async () => {
-                await fsp.rm(tempRoot, { force: true, recursive: true });
-                if (seed.cleanup) {
-                    await seed.cleanup();
-                }
-            },
+            cleanup: async () => cleanupSeedRootPair(cleanup, seed.cleanup),
         };
     }
     catch (error) {
-        await fsp.rm(tempRoot, { force: true, recursive: true });
-        await seed.cleanup?.();
+        await Promise.allSettled([cleanup(), seed.cleanup?.()]);
         throw error;
     }
 }

package/dist/runtime/template-source-seeds.js

@@ -1,13 +1,13 @@
 import fs from 'node:fs';
 import { promises as fsp } from 'node:fs';
 import { createRequire } from 'node:module';
-import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import semver from 'semver';
 import { x as extractTarball } from 'tar';
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, } from './template-registry.js';
 import { isPlainObject } from './object-utils.js';
+import { createManagedTempRoot } from './temp-roots.js';
 function selectRegistryVersion(metadata, locator) {
     const distTags = isPlainObject(metadata['dist-tags'])
         ? metadata['dist-tags']
@@ -58,10 +58,7 @@ async function fetchNpmTemplateSource(locator) {
     if (typeof tarballUrl !== 'string' || tarballUrl.length === 0) {
         throw new Error(`npm template metadata is missing tarball URL for ${locator.raw}@${resolvedVersion}.`);
     }
-    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-template-source-'));
-    const cleanup = async () => {
-        await fsp.rm(tempRoot, { force: true, recursive: true });
-    };
+    const { path: tempRoot, cleanup } = await createManagedTempRoot('wp-typia-template-source-');
     try {
         const tarballResponse = await fetch(tarballUrl);
         if (!tarballResponse.ok) {
@@ -178,10 +175,7 @@ export async function assertNoSymlinks(sourceDir) {
     }
 }
 async function resolveGitHubTemplateSource(locator) {
-    const remoteRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-template-source-'));
-    const cleanup = async () => {
-        await fsp.rm(remoteRoot, { force: true, recursive: true });
-    };
+    const { path: remoteRoot, cleanup } = await createManagedTempRoot('wp-typia-template-source-');
     const checkoutDir = path.join(remoteRoot, 'source');
     try {
         const args = ['clone', '--depth', '1'];

package/dist/runtime/template-source.d.ts

@@ -1,7 +1,6 @@
 import type { ResolvedTemplateSource } from './template-source-contracts.js';
+import type { ScaffoldTemplateVariables } from './scaffold.js';
 export type { GitHubTemplateLocator, NpmTemplateLocator, RemoteTemplateLocator, ResolvedTemplateSource, TemplateSourceFormat, TemplateVariableContext, } from './template-source-contracts.js';
 export { parseGitHubTemplateLocator, parseNpmTemplateLocator, parseTemplateLocator, } from './template-source-locators.js';
 export { resolveTemplateSeed } from './template-source-seeds.js';
-export declare function resolveTemplateSource(templateId: string, cwd: string, variables: {
-    [key: string]: string;
-}, variant?: string): Promise<ResolvedTemplateSource>;
+export declare function resolveTemplateSource(templateId: string, cwd: string, variables: ScaffoldTemplateVariables, variant?: string): Promise<ResolvedTemplateSource>;

package/dist/runtime/template-source.js

@@ -3,16 +3,24 @@ import { resolveBuiltInTemplateSource } from './template-builtins.js';
 import { parseTemplateLocator, } from './template-source-locators.js';
 import { detectTemplateSourceFormat, getTemplateProjectType, getDefaultCategory, getTemplateVariableContext, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, renderCreateBlockExternalTemplate, } from './template-source-normalization.js';
 import { isOfficialWorkspaceTemplateSeed, resolveTemplateSeed, } from './template-source-seeds.js';
+import { assertBuiltInTemplateVariantAllowed, } from './cli-validation.js';
+import { getScaffoldTemplateVariableGroups } from './scaffold-template-variable-groups.js';
 export { parseGitHubTemplateLocator, parseNpmTemplateLocator, parseTemplateLocator, } from './template-source-locators.js';
 export { resolveTemplateSeed } from './template-source-seeds.js';
 export async function resolveTemplateSource(templateId, cwd, variables, variant) {
     if (isBuiltInTemplateId(templateId)) {
-        if (variant) {
-            throw new Error(`--variant is only supported for official external template configs. Received variant "${variant}" for built-in template "${templateId}".`);
-        }
+        const variableGroups = getScaffoldTemplateVariableGroups(variables);
+        assertBuiltInTemplateVariantAllowed({
+            templateId,
+            variant,
+        });
         return resolveBuiltInTemplateSource(templateId, {
-            persistenceEnabled: variables.compoundPersistenceEnabled === 'true',
-            persistencePolicy: variables.persistencePolicy === 'public' ? 'public' : 'authenticated',
+            persistenceEnabled: variableGroups.compound.enabled &&
+                variableGroups.compound.persistenceEnabled,
+            persistencePolicy: variableGroups.persistence.enabled &&
+                variableGroups.persistence.policy === 'public'
+                ? 'public'
+                : 'authenticated',
         });
     }
     const locator = parseTemplateLocator(templateId);

package/dist/runtime/workspace-project.js

@@ -148,5 +148,5 @@ export function resolveWorkspaceProject(startDir) {
     if (workspace) {
         return workspace;
     }
-    throw new Error(`This command must run inside a ${WORKSPACE_TEMPLATE_PACKAGE} project. Create one with \`wp-typia create my-plugin --template ${WORKSPACE_TEMPLATE_PACKAGE}\` first.`);
+    throw new Error(`This command must run inside an official wp-typia workspace. Create one with \`wp-typia create my-plugin --template workspace\` first (the short alias for \`${WORKSPACE_TEMPLATE_PACKAGE}\`).`);
 }