@wp-typia/project-tools 0.22.5 → 0.22.6

package/dist/runtime/scaffold-compatibility.js

@@ -5,7 +5,7 @@
  * metadata aligned when optional or required AI-capable features are added.
  */
 import { AI_FEATURE_DEFINITIONS, resolveAiFeatureCapabilityPlan, } from './ai-feature-capability.js';
-import { pickHigherVersionFloor } from './version-floor.js';
+import { parseVersionFloorParts, pickHigherVersionFloor, } from './version-floor.js';
 /**
  * Baseline headers used by scaffold output before optional features are added.
  */
@@ -39,7 +39,7 @@ export const REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY = [
 function pickHigherScaffoldVersionFloor(current, candidate) {
     return pickHigherVersionFloor(current, candidate) ?? current;
 }
-function pickHigherHeaderVersionFloor(policyValue, currentValue) {
+function pickHigherHeaderVersionFloor(policyValue, currentValue, { headerName, onWarning, }) {
     const normalizedCurrentValue = currentValue.trim();
     if (!normalizedCurrentValue) {
         return policyValue;
@@ -47,10 +47,35 @@ function pickHigherHeaderVersionFloor(policyValue, currentValue) {
     try {
         return pickHigherScaffoldVersionFloor(policyValue, normalizedCurrentValue);
     }
-    catch {
+    catch (error) {
+        const warning = [
+            `Invalid plugin header version floor for ${headerName}: "${normalizedCurrentValue}".`,
+            'Expected dotted numeric segments such as "6.7" or "8.1.2".',
+            `Replacing it with compatibility policy value "${policyValue}".`,
+        ].join(' ');
+        if (!onWarning) {
+            throw new Error(warning, { cause: error });
+        }
+        onWarning(warning);
         return policyValue;
     }
 }
+function assertPolicyVersionFloor(headerName, value) {
+    try {
+        parseVersionFloorParts(value);
+    }
+    catch (error) {
+        throw new Error([
+            `Invalid scaffold compatibility policy floor for ${headerName}: "${value}".`,
+            'Expected dotted numeric segments such as "6.7" or "8.1.2".',
+        ].join(' '), { cause: error });
+    }
+}
+function assertPluginHeaderPolicyVersionFloors(pluginHeader) {
+    assertPolicyVersionFloor('Requires at least', pluginHeader.requiresAtLeast);
+    assertPolicyVersionFloor('Tested up to', pluginHeader.testedUpTo);
+    assertPolicyVersionFloor('Requires PHP', pluginHeader.requiresPhp);
+}
 function formatRuntimeGate(feature) {
     return (feature.runtimeGates ?? []).map((gate) => `${feature.label}: ${gate.kind} ${gate.value}`);
 }
@@ -108,21 +133,27 @@ export function renderScaffoldCompatibilityConfig(policy, indent = '\t\t') {
         .map((line, index) => (index === 0 ? line : `${indent}${line}`))
         .join('\n');
 }
-function replacePluginHeaderVersionFloor(source, pattern, policyValue) {
+function replacePluginHeaderVersionFloor(source, pattern, policyValue, headerName, options) {
     return source.replace(pattern, (_match, prefix, currentValue, lineEnding) => {
         const versionPrefix = prefix.endsWith(':') ? `${prefix} ` : prefix;
-        return `${versionPrefix}${pickHigherHeaderVersionFloor(policyValue, currentValue)}${lineEnding}`;
+        return `${versionPrefix}${pickHigherHeaderVersionFloor(policyValue, currentValue, {
+            headerName,
+            onWarning: options.onWarning,
+        })}${lineEnding}`;
     });
 }
 /**
  * Patch a generated plugin bootstrap header without lowering custom floors.
  *
- * Preserves the original header line endings while replacing empty or invalid
- * version strings with the policy values.
+ * Preserves the original header line endings while replacing empty version
+ * strings with policy values. Malformed user-authored values are reported
+ * through `options.onWarning`; without a warning handler they throw instead of
+ * falling back silently.
  */
-export function updatePluginHeaderCompatibility(source, policy) {
+export function updatePluginHeaderCompatibility(source, policy, options = {}) {
     const { pluginHeader } = policy;
-    const nextSource = replacePluginHeaderVersionFloor(source, /(\* Requires at least:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.requiresAtLeast);
-    const nextSourceWithTestedUpTo = replacePluginHeaderVersionFloor(nextSource, /(\* Tested up to:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.testedUpTo);
-    return replacePluginHeaderVersionFloor(nextSourceWithTestedUpTo, /(\* Requires PHP:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.requiresPhp);
+    assertPluginHeaderPolicyVersionFloors(pluginHeader);
+    const nextSource = replacePluginHeaderVersionFloor(source, /(\* Requires at least:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.requiresAtLeast, 'Requires at least', options);
+    const nextSourceWithTestedUpTo = replacePluginHeaderVersionFloor(nextSource, /(\* Tested up to:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.testedUpTo, 'Tested up to', options);
+    return replacePluginHeaderVersionFloor(nextSourceWithTestedUpTo, /(\* Requires PHP:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.requiresPhp, 'Requires PHP', options);
 }

package/dist/runtime/scaffold-documents.js

@@ -21,6 +21,17 @@ function formatReadmeTemplateIdentity(templateId) {
     }
     return [`- Template id: ${templateId}`, '- Type: custom or external scaffold'].join('\n');
 }
+function getPackageManagerInstallGuidance(packageManager) {
+    if (packageManager !== 'npm') {
+        return '';
+    }
+    const installCommand = formatInstallCommand(packageManager);
+    return [
+        '',
+        `> npm note: the scaffold uses \`${installCommand}\` for the first install so npm does not spend the initial create flow in the audit resolver. Run \`npm audit\` separately when you want npm vulnerability output.`,
+        '> If npm prints React peer dependency noise from WordPress block-editor packages, validate with `npm run typecheck` and `npm run build` before changing WordPress package ranges.',
+    ].join('\n');
+}
 /**
  * Builds the generated README markdown for one scaffolded project.
  *
@@ -99,6 +110,7 @@ ${formatReadmeTemplateIdentity(templateId)}
 ${formatInstallCommand(packageManager)}
 ${formatRunScript(packageManager, developmentScript)}
 \`\`\`
+${getPackageManagerInstallGuidance(packageManager)}
 
 ${getQuickStartWorkflowNote(packageManager, templateId, {
         compoundPersistenceEnabled,

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

@@ -1,8 +1,8 @@
-import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import { execSync } from "node:child_process";
 import path from "node:path";
 import { formatInstallCommand, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
+import { readOptionalUtf8File } from "./fs-async.js";
 const LOCKFILES = {
     bun: ["bun.lock", "bun.lockb"],
     npm: ["package-lock.json"],
@@ -33,11 +33,12 @@ export async function normalizePackageManagerFiles(targetDir, packageManagerId)
  */
 export async function normalizePackageJson(targetDir, packageManagerId) {
     const packageJsonPath = path.join(targetDir, "package.json");
-    if (!fs.existsSync(packageJsonPath)) {
+    const packageJsonSource = await readOptionalUtf8File(packageJsonPath);
+    if (packageJsonSource === null) {
         return;
     }
     const packageManager = getPackageManager(packageManagerId);
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const packageJson = JSON.parse(packageJsonSource);
     if (packageManagerId === "npm") {
         delete packageJson.packageManager;
     }

package/dist/runtime/string-case.d.ts

@@ -1,5 +1,10 @@
 /**
  * Normalize arbitrary text into a kebab-case identifier.
+ * Common acronym runs stay grouped, with a boundary before the next
+ * capitalized word.
+ * Ambiguous acronym+lowercase inputs like `URLslug` intentionally stay as one
+ * word because there is no PascalCase boundary marker before the lowercase
+ * suffix.
  *
  * @param input Raw text that may contain spaces, punctuation, or camelCase.
  * @returns A lowercase kebab-case string with collapsed separators.

package/dist/runtime/string-case.js

@@ -1,15 +1,65 @@
+const COMMON_ACRONYM_PREFIXES = [
+    'HTML',
+    'HTTP',
+    'JSON',
+    'REST',
+    'UUID',
+    'API',
+    'CSS',
+    'CTA',
+    'DOM',
+    'PHP',
+    'SQL',
+    'SVG',
+    'URL',
+    'XML',
+    'ID',
+    'JS',
+    'UI',
+    'WP',
+];
 function capitalizeSegment(segment) {
     return segment.charAt(0).toUpperCase() + segment.slice(1);
 }
+function findCommonAcronymPrefix(segment) {
+    return COMMON_ACRONYM_PREFIXES.find((prefix) => segment.startsWith(prefix));
+}
+function splitKnownAcronymSegment(segment) {
+    const prefixes = [];
+    let remaining = segment;
+    while (remaining.length > 0) {
+        const prefix = findCommonAcronymPrefix(remaining);
+        if (!prefix) {
+            break;
+        }
+        const suffix = remaining.slice(prefix.length);
+        if (/^[A-Z][a-z]/.test(suffix)) {
+            return [...prefixes, prefix, suffix].join('-');
+        }
+        if (!findCommonAcronymPrefix(suffix)) {
+            break;
+        }
+        prefixes.push(prefix);
+        remaining = suffix;
+    }
+    return segment;
+}
+function splitAcronymBoundary(value) {
+    return value.replace(/[A-Z]{2,}[a-z]+/g, splitKnownAcronymSegment);
+}
 /**
  * Normalize arbitrary text into a kebab-case identifier.
+ * Common acronym runs stay grouped, with a boundary before the next
+ * capitalized word.
+ * Ambiguous acronym+lowercase inputs like `URLslug` intentionally stay as one
+ * word because there is no PascalCase boundary marker before the lowercase
+ * suffix.
  *
  * @param input Raw text that may contain spaces, punctuation, or camelCase.
  * @returns A lowercase kebab-case string with collapsed separators.
  */
 export function toKebabCase(input) {
-    return input
-        .trim()
+    return splitAcronymBoundary(input.trim())
         .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
         .replace(/[^A-Za-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '')

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

@@ -14,6 +14,13 @@ export declare const EXTERNAL_TEMPLATE_CACHE_DIR_ENV = "WP_TYPIA_EXTERNAL_TEMPLA
  * Unset, empty, zero, negative, and non-numeric values keep pruning disabled.
  */
 export declare const EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_TTL_DAYS";
+/**
+ * Environment variable that overrides how often TTL pruning may scan the cache.
+ *
+ * Unset values use the default interval. Zero, negative, and non-numeric values
+ * disable scan throttling.
+ */
+export declare const EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS";
 /**
  * Serializable metadata recorded in the cache marker for diagnostics.
  */
@@ -72,10 +79,18 @@ export interface ExternalTemplateCachePruneOptions {
      * Environment object to inspect, defaulting to `process.env`.
      */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Force a full prune scan even when the last-pruned marker is still fresh.
+     */
+    force?: boolean;
     /**
      * Clock override for deterministic tests.
      */
     now?: Date | number;
+    /**
+     * Minimum interval between full prune scans. Omit for the environment/default.
+     */
+    pruneIntervalMs?: number;
     /**
      * TTL override in days. When omitted, the TTL environment variable is used.
      */
@@ -101,6 +116,10 @@ export interface ExternalTemplateCachePruneResult {
      * Candidate directories skipped because they were malformed or unsafe.
      */
     skippedEntries: number;
+    /**
+     * Whether a recent last-pruned marker skipped the full cache directory scan.
+     */
+    skippedByThrottle: boolean;
     /**
      * Resolved TTL in milliseconds, or `null` when pruning was disabled.
      */

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

@@ -19,14 +19,29 @@ export const EXTERNAL_TEMPLATE_CACHE_DIR_ENV = 'WP_TYPIA_EXTERNAL_TEMPLATE_CACHE
  * Unset, empty, zero, negative, and non-numeric values keep pruning disabled.
  */
 export const EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV = 'WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_TTL_DAYS';
+/**
+ * Environment variable that overrides how often TTL pruning may scan the cache.
+ *
+ * Unset values use the default interval. Zero, negative, and non-numeric values
+ * disable scan throttling.
+ */
+export const EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS_ENV = 'WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS';
 /**
  * Marker file written after a cache entry is fully populated.
  */
 const CACHE_MARKER_FILE = 'wp-typia-template-cache.json';
+/**
+ * Marker file written after a full TTL prune scan completes.
+ */
+const CACHE_PRUNE_MARKER_FILE = 'wp-typia-template-cache-prune.json';
 /**
  * Milliseconds in one TTL day.
  */
 const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Default minimum interval between full external template cache prune scans.
+ */
+const DEFAULT_CACHE_PRUNE_INTERVAL_MS = 60 * 60 * 1000;
 /**
  * Private directory mode used for cache roots and entries on POSIX platforms.
  */
@@ -119,6 +134,27 @@ function resolveExternalTemplateCacheTtlMs(options = {}) {
     const ttlMs = ttlDays * MILLISECONDS_PER_DAY;
     return Number.isFinite(ttlMs) ? ttlMs : null;
 }
+function parseExternalTemplateCachePruneIntervalMs(value) {
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        return null;
+    }
+    const intervalMs = typeof value === 'number' ? value : Number(value.trim());
+    if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+        return null;
+    }
+    return intervalMs;
+}
+function resolveExternalTemplateCachePruneIntervalMs(options = {}) {
+    if (options.pruneIntervalMs !== undefined) {
+        return parseExternalTemplateCachePruneIntervalMs(options.pruneIntervalMs);
+    }
+    const env = options.env ?? process.env;
+    const envValue = env[EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS_ENV];
+    if (envValue === undefined) {
+        return DEFAULT_CACHE_PRUNE_INTERVAL_MS;
+    }
+    return parseExternalTemplateCachePruneIntervalMs(envValue);
+}
 /**
  * Creates a deterministic cache key from source identity and integrity parts.
  *
@@ -313,6 +349,14 @@ function parseCacheMarkerMetadata(markerText) {
         metadata,
     };
 }
+async function readCacheEntryMarker(markerPath) {
+    try {
+        return parseCacheMarkerMetadata(await fsp.readFile(markerPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
 function cacheMetadataMatches(actual, expected) {
     return Object.entries(expected).every(([key, value]) => actual[key] === value);
 }
@@ -324,6 +368,19 @@ function getExternalTemplateCacheNowMs(now) {
             : Date.now();
     return Number.isFinite(nowMs) ? nowMs : Date.now();
 }
+function isCacheEntryFreshForTtl(createdAtMs, nowMs, ttlMs) {
+    return ttlMs === null || createdAtMs >= nowMs - ttlMs;
+}
+async function getReusableCacheEntryMarker(entryDir, markerPath, sourceDir) {
+    if (!(await isReusableCacheEntry(entryDir, markerPath, sourceDir))) {
+        return null;
+    }
+    return readCacheEntryMarker(markerPath);
+}
+async function isReusableFreshCacheEntry(entryDir, markerPath, sourceDir, nowMs, ttlMs) {
+    const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
+    return (marker !== null && isCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs));
+}
 function isPathInsideDirectory(directory, candidatePath) {
     const relativePath = path.relative(directory, candidatePath);
     return (relativePath.length > 0 &&
@@ -342,6 +399,74 @@ async function removeCacheEntryWithinRoot(cacheRoot, entryDir) {
         return false;
     }
 }
+function getCachePruneMarkerPath(cacheRoot) {
+    return path.join(cacheRoot, CACHE_PRUNE_MARKER_FILE);
+}
+function parseCachePruneMarker(markerText) {
+    let marker;
+    try {
+        marker = JSON.parse(markerText);
+    }
+    catch {
+        return null;
+    }
+    if (typeof marker !== 'object' || marker === null || Array.isArray(marker)) {
+        return null;
+    }
+    const rawPrunedAt = marker.prunedAt;
+    const prunedAtMs = typeof rawPrunedAt === 'string' ? Date.parse(rawPrunedAt) : Number.NaN;
+    const rawPruneIntervalMs = marker
+        .pruneIntervalMs;
+    const rawTtlMs = marker.ttlMs;
+    if (typeof rawTtlMs !== 'number' || !Number.isFinite(rawTtlMs)) {
+        return null;
+    }
+    if (!Number.isFinite(prunedAtMs)) {
+        return null;
+    }
+    if (rawPruneIntervalMs !== null &&
+        (typeof rawPruneIntervalMs !== 'number' ||
+            !Number.isFinite(rawPruneIntervalMs))) {
+        return null;
+    }
+    return {
+        prunedAtMs,
+        pruneIntervalMs: rawPruneIntervalMs ?? null,
+        ttlMs: rawTtlMs,
+    };
+}
+async function shouldSkipExternalTemplateCachePrune({ cacheRoot, force, nowMs, pruneIntervalMs, ttlMs, }) {
+    if (force || pruneIntervalMs === null) {
+        return false;
+    }
+    let markerText;
+    try {
+        markerText = await fsp.readFile(getCachePruneMarkerPath(cacheRoot), 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const marker = parseCachePruneMarker(markerText);
+    if (!marker ||
+        marker.ttlMs !== ttlMs ||
+        marker.pruneIntervalMs !== pruneIntervalMs) {
+        return false;
+    }
+    const elapsedMs = nowMs - marker.prunedAtMs;
+    return elapsedMs >= 0 && elapsedMs < pruneIntervalMs;
+}
+async function writeExternalTemplateCachePruneMarker({ cacheRoot, nowMs, pruneIntervalMs, ttlMs, }) {
+    try {
+        await fsp.writeFile(getCachePruneMarkerPath(cacheRoot), `${JSON.stringify({
+            prunedAt: new Date(nowMs).toISOString(),
+            pruneIntervalMs,
+            ttlMs,
+        }, null, 2)}\n`, 'utf8');
+    }
+    catch {
+        // Prune markers are an optimization; failing to write one keeps TTL safe.
+    }
+}
 /**
  * Removes stale external template cache entries when a positive TTL is configured.
  *
@@ -359,16 +484,32 @@ export async function pruneExternalTemplateCache(options = {}) {
         env,
         ttlDays: options.ttlDays,
     });
+    const pruneIntervalMs = resolveExternalTemplateCachePruneIntervalMs({
+        env,
+        pruneIntervalMs: options.pruneIntervalMs,
+    });
     const result = {
         cacheRoot,
         prunedEntries: 0,
         scannedEntries: 0,
         skippedEntries: 0,
+        skippedByThrottle: false,
         ttlMs,
     };
     if (ttlMs === null || !(await isPrivateCacheDirectory(cacheRoot))) {
         return result;
     }
+    const nowMs = getExternalTemplateCacheNowMs(options.now);
+    if (await shouldSkipExternalTemplateCachePrune({
+        cacheRoot,
+        force: options.force,
+        nowMs,
+        pruneIntervalMs,
+        ttlMs,
+    })) {
+        result.skippedByThrottle = true;
+        return result;
+    }
     let namespaceEntries;
     try {
         namespaceEntries = await fsp.readdir(cacheRoot, { withFileTypes: true });
@@ -376,7 +517,7 @@ export async function pruneExternalTemplateCache(options = {}) {
     catch {
         return result;
     }
-    const expiresBeforeMs = getExternalTemplateCacheNowMs(options.now) - ttlMs;
+    const expiresBeforeMs = nowMs - ttlMs;
     for (const namespaceEntry of namespaceEntries) {
         if (!namespaceEntry.isDirectory()) {
             continue;
@@ -410,19 +551,7 @@ export async function pruneExternalTemplateCache(options = {}) {
             }
             const markerPath = path.join(entryDir, CACHE_MARKER_FILE);
             const sourceDir = path.join(entryDir, 'source');
-            if (!(await isReusableCacheEntry(entryDir, markerPath, sourceDir))) {
-                result.skippedEntries += 1;
-                continue;
-            }
-            let markerText;
-            try {
-                markerText = await fsp.readFile(markerPath, 'utf8');
-            }
-            catch {
-                result.skippedEntries += 1;
-                continue;
-            }
-            const marker = parseCacheMarkerMetadata(markerText);
+            const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
             if (!marker) {
                 result.skippedEntries += 1;
                 continue;
@@ -437,6 +566,12 @@ export async function pruneExternalTemplateCache(options = {}) {
             }
         }
     }
+    await writeExternalTemplateCachePruneMarker({
+        cacheRoot,
+        nowMs,
+        pruneIntervalMs,
+        ttlMs,
+    });
     return result;
 }
 /**
@@ -462,6 +597,8 @@ export async function findReusableExternalTemplateSourceCache(descriptor) {
         !(await isPrivateCacheDirectory(namespaceDir))) {
         return null;
     }
+    const ttlMs = resolveExternalTemplateCacheTtlMs();
+    const nowMs = getExternalTemplateCacheNowMs(undefined);
     await pruneExternalTemplateCache();
     let entries;
     try {
@@ -478,18 +615,10 @@ export async function findReusableExternalTemplateSourceCache(descriptor) {
         const entryDir = path.join(namespaceDir, entry.name);
         const markerPath = path.join(entryDir, CACHE_MARKER_FILE);
         const sourceDir = path.join(entryDir, 'source');
-        if (!(await isReusableCacheEntry(entryDir, markerPath, sourceDir))) {
-            continue;
-        }
-        let markerText;
-        try {
-            markerText = await fsp.readFile(markerPath, 'utf8');
-        }
-        catch {
-            continue;
-        }
-        const marker = parseCacheMarkerMetadata(markerText);
-        if (!marker || !cacheMetadataMatches(marker.metadata, descriptor.metadata)) {
+        const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
+        if (!marker ||
+            !isCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs) ||
+            !cacheMetadataMatches(marker.metadata, descriptor.metadata)) {
             continue;
         }
         if (!bestEntry || marker.createdAtMs > bestEntry.createdAtMs) {
@@ -530,13 +659,20 @@ export async function resolveExternalTemplateSourceCache(descriptor, populateSou
         !(await ensurePrivateCacheDirectory(namespaceDir))) {
         return null;
     }
+    const ttlMs = resolveExternalTemplateCacheTtlMs();
+    const nowMs = getExternalTemplateCacheNowMs(undefined);
     await pruneExternalTemplateCache();
-    if (await isReusableCacheEntry(entryDir, markerPath, sourceDir)) {
+    const existingMarker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
+    if (existingMarker &&
+        isCacheEntryFreshForTtl(existingMarker.createdAtMs, nowMs, ttlMs)) {
         return {
             cacheHit: true,
             sourceDir,
         };
     }
+    if (existingMarker) {
+        await removeCacheEntryWithinRoot(cacheRoot, entryDir);
+    }
     const temporaryEntryDir = path.join(namespaceDir, `.tmp-${cacheKey}-${process.pid}-${Date.now()}-${Math.random()
         .toString(16)
         .slice(2)}`);
@@ -579,7 +715,7 @@ export async function resolveExternalTemplateSourceCache(descriptor, populateSou
         }
         const errorCode = getNodeErrorCode(error);
         if (CACHE_PUBLISH_RACE_ERROR_CODES.has(errorCode) &&
-            (await isReusableCacheEntry(entryDir, markerPath, sourceDir))) {
+            (await isReusableFreshCacheEntry(entryDir, markerPath, sourceDir, nowMs, ttlMs))) {
             return {
                 cacheHit: true,
                 sourceDir,

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

@@ -11,6 +11,13 @@ export declare const EXTERNAL_TEMPLATE_TRUST_WARNING = "External template config
  * @returns The first matching entry path, or null when no supported entry exists.
  */
 export declare function getExternalTemplateEntry(sourceDir: string): string | null;
+/**
+ * Search a source directory for a supported external template entry asynchronously.
+ *
+ * @param sourceDir Directory that may contain an external template config entry.
+ * @returns The first matching entry path, or null when no supported entry exists.
+ */
+export declare function findExternalTemplateEntry(sourceDir: string): Promise<string | null>;
 /**
  * Load an official external template config and render its seed.
  *

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

@@ -1,5 +1,6 @@
 /// <reference path="./external-template-modules.d.ts" />
 import fs from 'node:fs';
+import { promises as fsp } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { assertExternalTemplateFileSize, getExternalTemplateConfigMaxBytes, withExternalTemplateTimeout, } from './external-template-guards.js';
@@ -7,6 +8,7 @@ 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';
+import { pathExists } from './fs-async.js';
 /**
  * Candidate filenames for official external template config entrypoints.
  */
@@ -43,8 +45,23 @@ export function getExternalTemplateEntry(sourceDir) {
     }
     return null;
 }
+/**
+ * Search a source directory for a supported external template entry asynchronously.
+ *
+ * @param sourceDir Directory that may contain an external template config entry.
+ * @returns The first matching entry path, or null when no supported entry exists.
+ */
+export async function findExternalTemplateEntry(sourceDir) {
+    for (const filename of EXTERNAL_TEMPLATE_ENTRY_CANDIDATES) {
+        const candidate = path.join(sourceDir, filename);
+        if (await pathExists(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
 async function loadExternalTemplateConfig(sourceDir) {
-    const entryPath = getExternalTemplateEntry(sourceDir);
+    const entryPath = await findExternalTemplateEntry(sourceDir);
     if (!entryPath) {
         throw new Error(`No external template config entry found in ${sourceDir}.`);
     }
@@ -52,7 +69,8 @@ async function loadExternalTemplateConfig(sourceDir) {
         label: `External template config "${entryPath}"`,
         maxBytes: getExternalTemplateConfigMaxBytes(),
     });
-    const moduleUrl = `${pathToFileURL(entryPath).href}?mtime=${fs.statSync(entryPath).mtimeMs}`;
+    const entryStats = await fsp.stat(entryPath);
+    const moduleUrl = `${pathToFileURL(entryPath).href}?mtime=${entryStats.mtimeMs}`;
     const loadedModule = (await withExternalTemplateTimeout(`loading external template config "${entryPath}"`, () => import(moduleUrl)));
     const loadedConfig = loadedModule.default ?? loadedModule;
     if (!isPlainObject(loadedConfig)) {
@@ -200,10 +218,9 @@ export async function renderCreateBlockExternalTemplate(sourceDir, context, requ
         if (typeof assetsPath === 'string' && assetsPath.trim().length > 0) {
             await copyRawDirectory(resolveSourceSubpath(sourceDir, assetsPath), path.join(tempRoot, 'assets'));
         }
+        const assetsDir = path.join(tempRoot, 'assets');
         return {
-            assetsDir: fs.existsSync(path.join(tempRoot, 'assets'))
-                ? path.join(tempRoot, 'assets')
-                : undefined,
+            assetsDir: (await pathExists(assetsDir)) ? assetsDir : undefined,
             blockDir,
             cleanup,
             formatHint,

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

@@ -1,5 +1,5 @@
 export { renderCreateBlockExternalTemplate } from './template-source-external.js';
-export { getTemplateProjectType, getDefaultCategory, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, } from './template-source-remote.js';
+export { getTemplateProjectType, getTemplateProjectTypeAsync, getDefaultCategory, getDefaultCategoryAsync, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, } from './template-source-remote.js';
 import type { TemplateSourceFormat, TemplateVariableContext } from './template-source-contracts.js';
 export declare function getTemplateVariableContext(variables: {
     [key: string]: string;