@wp-typia/project-tools 0.19.0 → 0.19.1

package/dist/runtime/scaffold-documents.js

@@ -2,6 +2,7 @@ import { getPrimaryDevelopmentScript } from './local-dev-presets.js';
 import { getCompoundExtensionWorkflowSection, getInitialCommitCommands, getInitialCommitNote, getOptionalOnboardingNote, getOptionalOnboardingSteps, getQuickStartWorkflowNote, getPhpRestExtensionPointsSection, getTemplateSourceOfTruthNote, } from './scaffold-onboarding.js';
 import { formatPackageExecCommand, formatInstallCommand, formatRunScript, } from './package-managers.js';
 import { getPackageVersions } from './package-versions.js';
+import { getScaffoldTemplateVariableGroups } from './scaffold-template-variable-groups.js';
 /**
  * Builds the generated README markdown for one scaffolded project.
  *
@@ -12,26 +13,28 @@ import { getPackageVersions } from './package-versions.js';
  * @returns Markdown README content for the generated project root.
  */
 export function buildReadme(templateId, variables, packageManager, { withMigrationUi = false, withTestPreset = false, withWpEnv = false, } = {}) {
+    const variableGroups = getScaffoldTemplateVariableGroups(variables);
+    const compoundPersistenceEnabled = variableGroups.compound.enabled &&
+        variableGroups.compound.persistenceEnabled;
     const optionalOnboardingSteps = getOptionalOnboardingSteps(packageManager, templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === 'true',
+        compoundPersistenceEnabled,
     });
     const initialCommitCommands = getInitialCommitCommands();
     const sourceOfTruthNote = getTemplateSourceOfTruthNote(templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === 'true',
+        compoundPersistenceEnabled,
     });
-    const compoundPersistenceEnabled = variables.compoundPersistenceEnabled === 'true';
-    const publicPersistencePolicyNote = variables.isPublicPersistencePolicy === 'true'
+    const publicPersistencePolicyNote = variableGroups.persistence.enabled && variableGroups.persistence.auth.isPublic
         ? 'Public persistence writes use signed short-lived tokens, per-request ids, and coarse rate limiting by default. Add application-specific abuse controls before using the same pattern for high-value metrics or experiments.'
         : null;
-    const alternateRenderTargetSection = variables.hasAlternateRenderTargets === 'true'
+    const alternateRenderTargetSection = variableGroups.alternateRenderTargets.enabled
         ? `## Alternate Render Targets\n\nThis scaffold keeps \`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render.php` : 'src/render.php'}\` as the default web render boundary and also generates ${[
-            variables.hasAlternateEmailRenderTarget === 'true'
+            variableGroups.alternateRenderTargets.hasEmail
                 ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-email.php` : 'src/render-email.php'}\``
                 : null,
-            variables.hasAlternateMjmlRenderTarget === 'true'
+            variableGroups.alternateRenderTargets.hasMjml
                 ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-mjml.php` : 'src/render-mjml.php'}\``
                 : null,
-            variables.hasAlternatePlainTextRenderTarget === 'true'
+            variableGroups.alternateRenderTargets.hasPlainText
                 ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-text.php` : 'src/render-text.php'}\``
                 : null,
         ]

package/dist/runtime/scaffold-template-variable-groups.d.ts

@@ -0,0 +1,154 @@
+export declare const SCAFFOLD_TEMPLATE_VARIABLE_GROUPS: unique symbol;
+export type ScaffoldTemplateFamily = "basic" | "interactivity" | "persistence" | "compound" | "query-loop" | "external";
+export interface ScaffoldSharedTemplateVariableGroup {
+    author: string;
+    blockMetadataVersion: string;
+    category: string;
+    cssClassName: string;
+    description: string;
+    descriptionJson: string;
+    frontendCssClassName: string;
+    icon: string;
+    keyword: string;
+    namespace: string;
+    pascalCase: string;
+    phpPrefix: string;
+    phpPrefixUpper: string;
+    slug: string;
+    slugCamelCase: string;
+    slugKebabCase: string;
+    slugSnakeCase: string;
+    textDomain: string;
+    title: string;
+    titleCase: string;
+    titleJson: string;
+    versions: {
+        apiClient: string;
+        blockRuntime: string;
+        blockTypes: string;
+        projectTools: string;
+        rest: string;
+    };
+}
+export interface ScaffoldAlternateRenderTargetVariableGroup {
+    csv: string;
+    enabled: boolean;
+    hasEmail: boolean;
+    hasMjml: boolean;
+    hasPlainText: boolean;
+    json: string;
+    targets: readonly string[];
+}
+export interface DisabledScaffoldCompoundVariableGroup {
+    enabled: false;
+    persistenceEnabled: false;
+}
+export interface EnabledScaffoldCompoundVariableGroup {
+    child: {
+        category: string;
+        cssClassName: string;
+        icon: string;
+        title: string;
+        titleJson: string;
+    };
+    enabled: true;
+    innerBlocks: {
+        description: string;
+        directInsert: boolean;
+        label: string;
+        orientation: "" | "horizontal" | "vertical";
+        orientationExpression: string;
+        preset: string;
+        templateLockExpression: string;
+    };
+    persistenceEnabled: boolean;
+}
+export type ScaffoldCompoundVariableGroup = DisabledScaffoldCompoundVariableGroup | EnabledScaffoldCompoundVariableGroup;
+export interface DisabledScaffoldPersistenceVariableGroup {
+    enabled: false;
+    scope: "none";
+}
+export interface EnabledScaffoldPersistenceVariableGroup {
+    auth: {
+        bootstrapCredentialDeclarations: string;
+        descriptionJson: string;
+        intent: "authenticated" | "public-write-protected";
+        isAuthenticated: boolean;
+        isPublic: boolean;
+        mechanism: "public-signed-token" | "rest-nonce";
+        mode: "authenticated-rest-nonce" | "public-signed-token";
+        publicWriteRequestIdDeclaration: string;
+    };
+    dataStorageMode: "custom-table" | "post-meta";
+    enabled: true;
+    policy: "authenticated" | "public";
+    scope: "compound-parent" | "single";
+}
+export type ScaffoldPersistenceVariableGroup = DisabledScaffoldPersistenceVariableGroup | EnabledScaffoldPersistenceVariableGroup;
+export interface DisabledScaffoldQueryLoopVariableGroup {
+    enabled: false;
+}
+export interface EnabledScaffoldQueryLoopVariableGroup {
+    allowedControls: readonly string[];
+    allowedControlsJson: string;
+    enabled: true;
+    postType: string;
+    postTypeJson: string;
+    variationNamespace: string;
+    variationNamespaceJson: string;
+}
+export type ScaffoldQueryLoopVariableGroup = DisabledScaffoldQueryLoopVariableGroup | EnabledScaffoldQueryLoopVariableGroup;
+interface ScaffoldTemplateVariableGroupsBase {
+    alternateRenderTargets: ScaffoldAlternateRenderTargetVariableGroup;
+    shared: ScaffoldSharedTemplateVariableGroup;
+    template: {
+        description: string;
+    };
+}
+type DisabledTemplateFamilyGroups<TFamily extends "basic" | "interactivity" | "external"> = ScaffoldTemplateVariableGroupsBase & {
+    compound: DisabledScaffoldCompoundVariableGroup;
+    persistence: DisabledScaffoldPersistenceVariableGroup;
+    queryLoop: DisabledScaffoldQueryLoopVariableGroup;
+    templateFamily: TFamily;
+};
+export type BasicScaffoldTemplateVariableGroups = DisabledTemplateFamilyGroups<"basic">;
+export type InteractivityScaffoldTemplateVariableGroups = DisabledTemplateFamilyGroups<"interactivity">;
+export interface PersistenceScaffoldTemplateVariableGroups extends ScaffoldTemplateVariableGroupsBase {
+    compound: DisabledScaffoldCompoundVariableGroup;
+    persistence: EnabledScaffoldPersistenceVariableGroup & {
+        scope: "single";
+    };
+    queryLoop: DisabledScaffoldQueryLoopVariableGroup;
+    templateFamily: "persistence";
+}
+export interface CompoundScaffoldTemplateVariableGroups extends ScaffoldTemplateVariableGroupsBase {
+    compound: EnabledScaffoldCompoundVariableGroup;
+    persistence: DisabledScaffoldPersistenceVariableGroup | (EnabledScaffoldPersistenceVariableGroup & {
+        scope: "compound-parent";
+    });
+    queryLoop: DisabledScaffoldQueryLoopVariableGroup;
+    templateFamily: "compound";
+}
+export interface QueryLoopScaffoldTemplateVariableGroups extends ScaffoldTemplateVariableGroupsBase {
+    compound: DisabledScaffoldCompoundVariableGroup;
+    persistence: DisabledScaffoldPersistenceVariableGroup;
+    queryLoop: EnabledScaffoldQueryLoopVariableGroup;
+    templateFamily: "query-loop";
+}
+export type ExternalScaffoldTemplateVariableGroups = DisabledTemplateFamilyGroups<"external">;
+export type ScaffoldTemplateVariableGroups = BasicScaffoldTemplateVariableGroups | InteractivityScaffoldTemplateVariableGroups | PersistenceScaffoldTemplateVariableGroups | CompoundScaffoldTemplateVariableGroups | QueryLoopScaffoldTemplateVariableGroups | ExternalScaffoldTemplateVariableGroups;
+export interface ScaffoldTemplateVariableGroupsCarrier {
+    readonly [SCAFFOLD_TEMPLATE_VARIABLE_GROUPS]: ScaffoldTemplateVariableGroups;
+}
+export type CompoundScaffoldTemplateVariablesLike = ScaffoldTemplateVariableGroupsCarrier & {
+    slugKebabCase: string;
+};
+export type PersistenceScaffoldTemplateVariablesLike = ScaffoldTemplateVariableGroupsCarrier & {
+    namespace: string;
+    pascalCase: string;
+    slugKebabCase: string;
+    title: string;
+};
+export declare function attachScaffoldTemplateVariableGroups<TVariables extends Record<string, string>>(variables: TVariables, groups: ScaffoldTemplateVariableGroups): TVariables & ScaffoldTemplateVariableGroupsCarrier;
+export declare function getScaffoldTemplateVariableGroups(variables: ScaffoldTemplateVariableGroupsCarrier): ScaffoldTemplateVariableGroups;
+export {};

package/dist/runtime/scaffold-template-variable-groups.js

@@ -0,0 +1,13 @@
+export const SCAFFOLD_TEMPLATE_VARIABLE_GROUPS = Symbol("wp-typia.scaffold-template-variable-groups");
+export function attachScaffoldTemplateVariableGroups(variables, groups) {
+    Object.defineProperty(variables, SCAFFOLD_TEMPLATE_VARIABLE_GROUPS, {
+        configurable: false,
+        enumerable: false,
+        value: groups,
+        writable: false,
+    });
+    return variables;
+}
+export function getScaffoldTemplateVariableGroups(variables) {
+    return variables[SCAFFOLD_TEMPLATE_VARIABLE_GROUPS];
+}

package/dist/runtime/scaffold-template-variables.js

@@ -5,6 +5,7 @@ import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS,
 import { DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID, getCompoundInnerBlocksPresetDefinition, } from './compound-inner-blocks.js';
 import { getTemplateById, isBuiltInTemplateId, } from './template-registry.js';
 import { toPascalCase, toSnakeCase, } from './string-case.js';
+import { attachScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
 /**
  * Build the normalized template variables used by scaffold rendering.
  *
@@ -57,7 +58,7 @@ export function getTemplateVariables(templateId, answers) {
     const persistencePolicy = templateId === 'persistence' || compoundPersistenceEnabled
         ? answers.persistencePolicy ?? 'authenticated'
         : 'authenticated';
-    return {
+    const flatVariables = {
         alternateRenderTargetsCsv: '',
         alternateRenderTargetsJson: '[]',
         apiClientPackageVersion,
@@ -136,4 +137,60 @@ export function getTemplateVariables(templateId, answers) {
         titleCase: pascalCase,
         persistencePolicy,
     };
+    return attachScaffoldTemplateVariableGroups(flatVariables, {
+        alternateRenderTargets: {
+            csv: '',
+            enabled: false,
+            hasEmail: false,
+            hasMjml: false,
+            hasPlainText: false,
+            json: '[]',
+            targets: [],
+        },
+        compound: {
+            enabled: false,
+            persistenceEnabled: false,
+        },
+        persistence: {
+            enabled: false,
+            scope: 'none',
+        },
+        queryLoop: {
+            enabled: false,
+        },
+        shared: {
+            author: answers.author.trim(),
+            blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
+            category: metadataDefaults?.category ?? template?.defaultCategory ?? 'widgets',
+            cssClassName,
+            description,
+            descriptionJson: JSON.stringify(description),
+            frontendCssClassName: buildFrontendCssClassName(cssClassName),
+            icon: metadataDefaults?.icon ?? 'smiley',
+            keyword: slug.replace(/-/g, ' '),
+            namespace,
+            pascalCase,
+            phpPrefix,
+            phpPrefixUpper,
+            slug,
+            slugCamelCase: pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1),
+            slugKebabCase: slug,
+            slugSnakeCase,
+            textDomain,
+            title,
+            titleCase: pascalCase,
+            titleJson: JSON.stringify(title),
+            versions: {
+                apiClient: apiClientPackageVersion,
+                blockRuntime: blockRuntimePackageVersion,
+                blockTypes: blockTypesPackageVersion,
+                projectTools: projectToolsPackageVersion,
+                rest: restPackageVersion,
+            },
+        },
+        template: {
+            description: template?.description ?? 'External scaffold template variables',
+        },
+        templateFamily: 'external',
+    });
 }

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.
  *
@@ -29,7 +30,7 @@ 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;
@@ -94,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.
@@ -176,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, 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,6 +12,7 @@ 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"];
@@ -19,6 +20,7 @@ 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);
 }
@@ -164,8 +166,10 @@ export async function scaffoldProject({ projectDir, templateId, answers, alterna
     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.
  *