@wp-typia/project-tools 0.22.7 → 0.22.9

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

@@ -0,0 +1,135 @@
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Environment variable that disables external template cache reads and writes.
+ *
+ * Set to `0`, `false`, `no`, or `off` to bypass the cache.
+ */
+export const EXTERNAL_TEMPLATE_CACHE_ENV = 'WP_TYPIA_EXTERNAL_TEMPLATE_CACHE';
+/**
+ * Environment variable that overrides the external template cache root.
+ */
+export const EXTERNAL_TEMPLATE_CACHE_DIR_ENV = 'WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_DIR';
+/**
+ * Environment variable that enables TTL-based external template cache pruning.
+ *
+ * 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';
+/**
+ * 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;
+/**
+ * Normalized environment values that disable the cache.
+ */
+const DISABLED_CACHE_VALUES = new Set(['0', 'false', 'no', 'off']);
+/**
+ * Checks whether remote external template source caching is enabled.
+ *
+ * Caching is enabled by default. Set `WP_TYPIA_EXTERNAL_TEMPLATE_CACHE` to
+ * `0`, `false`, `no`, or `off` to force uncached resolution.
+ *
+ * @param env Environment object to inspect, defaulting to `process.env`.
+ * @returns Whether external template source cache reads and writes are enabled.
+ */
+export function isExternalTemplateCacheEnabled(env = process.env) {
+    const rawValue = env[EXTERNAL_TEMPLATE_CACHE_ENV];
+    if (rawValue === undefined) {
+        return true;
+    }
+    return !DISABLED_CACHE_VALUES.has(rawValue.trim().toLowerCase());
+}
+/**
+ * Resolves the external template source cache root directory.
+ *
+ * `WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_DIR` overrides the location. Without an
+ * override, wp-typia uses a per-user `wp-typia-template-source-cache-*`
+ * directory inside the operating system temp directory.
+ *
+ * @param env Environment object to inspect, defaulting to `process.env`.
+ * @returns Absolute cache root directory path.
+ */
+export function getExternalTemplateCacheRoot(env = process.env) {
+    const configuredCacheDir = env[EXTERNAL_TEMPLATE_CACHE_DIR_ENV]?.trim();
+    if (configuredCacheDir) {
+        return path.resolve(configuredCacheDir);
+    }
+    return path.join(os.tmpdir(), `wp-typia-template-source-cache-${getCurrentUserCacheSegment()}`);
+}
+function parseExternalTemplateCacheTtlDays(value) {
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        return null;
+    }
+    const ttlDays = typeof value === 'number' ? value : Number(value.trim());
+    if (!Number.isFinite(ttlDays) || ttlDays <= 0) {
+        return null;
+    }
+    return ttlDays;
+}
+export function resolveExternalTemplateCacheTtlMs(options = {}) {
+    const env = options.env ?? process.env;
+    const ttlDays = options.ttlDays === undefined
+        ? parseExternalTemplateCacheTtlDays(env[EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV])
+        : parseExternalTemplateCacheTtlDays(options.ttlDays);
+    if (ttlDays === null) {
+        return null;
+    }
+    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;
+}
+export 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);
+}
+export function getExternalTemplateCacheNowMs(now) {
+    const nowMs = now instanceof Date
+        ? now.getTime()
+        : typeof now === 'number'
+            ? now
+            : Date.now();
+    return Number.isFinite(nowMs) ? nowMs : Date.now();
+}
+function getCurrentUserCacheSegment() {
+    if (typeof process.getuid === 'function') {
+        return String(process.getuid());
+    }
+    try {
+        const safeUsername = os
+            .userInfo()
+            .username.trim()
+            .replace(/[^A-Za-z0-9._-]+/gu, '-');
+        return safeUsername.length > 0 ? safeUsername : 'user';
+    }
+    catch {
+        return 'user';
+    }
+}

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

@@ -1,26 +1,4 @@
-/**
- * Environment variable that disables external template cache reads and writes.
- *
- * Set to `0`, `false`, `no`, or `off` to bypass the cache.
- */
-export declare const EXTERNAL_TEMPLATE_CACHE_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_CACHE";
-/**
- * Environment variable that overrides the external template cache root.
- */
-export declare const EXTERNAL_TEMPLATE_CACHE_DIR_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_DIR";
-/**
- * Environment variable that enables TTL-based external template cache pruning.
- *
- * 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";
+export { EXTERNAL_TEMPLATE_CACHE_DIR_ENV, EXTERNAL_TEMPLATE_CACHE_ENV, EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS_ENV, EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, getExternalTemplateCacheRoot, isExternalTemplateCacheEnabled, } from './template-source-cache-policy.js';
 /**
  * Serializable metadata recorded in the cache marker for diagnostics.
  */
@@ -125,27 +103,6 @@ export interface ExternalTemplateCachePruneResult {
      */
     ttlMs: number | null;
 }
-/**
- * Checks whether remote external template source caching is enabled.
- *
- * Caching is enabled by default. Set `WP_TYPIA_EXTERNAL_TEMPLATE_CACHE` to
- * `0`, `false`, `no`, or `off` to force uncached resolution.
- *
- * @param env Environment object to inspect, defaulting to `process.env`.
- * @returns Whether external template source cache reads and writes are enabled.
- */
-export declare function isExternalTemplateCacheEnabled(env?: NodeJS.ProcessEnv): boolean;
-/**
- * Resolves the external template source cache root directory.
- *
- * `WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_DIR` overrides the location. Without an
- * override, wp-typia uses a per-user `wp-typia-template-source-cache-*`
- * directory inside the operating system temp directory.
- *
- * @param env Environment object to inspect, defaulting to `process.env`.
- * @returns Absolute cache root directory path.
- */
-export declare function getExternalTemplateCacheRoot(env?: NodeJS.ProcessEnv): string;
 /**
  * Creates a deterministic cache key from source identity and integrity parts.
  *
@@ -187,4 +144,3 @@ export declare function findReusableExternalTemplateSourceCache(descriptor: Exte
  * @returns Cache resolution details, or `null` when caching is disabled.
  */
 export declare function resolveExternalTemplateSourceCache(descriptor: ExternalTemplateCacheDescriptor, populateSourceDir: (sourceDir: string) => Promise<void>): Promise<ExternalTemplateCacheResolution | null>;
-export {};

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

@@ -1,31 +1,9 @@
-import { createHash } from 'node:crypto';
-import fs from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
 import { promises as fsp } from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
-/**
- * Environment variable that disables external template cache reads and writes.
- *
- * Set to `0`, `false`, `no`, or `off` to bypass the cache.
- */
-export const EXTERNAL_TEMPLATE_CACHE_ENV = 'WP_TYPIA_EXTERNAL_TEMPLATE_CACHE';
-/**
- * Environment variable that overrides the external template cache root.
- */
-export const EXTERNAL_TEMPLATE_CACHE_DIR_ENV = 'WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_DIR';
-/**
- * Environment variable that enables TTL-based external template cache pruning.
- *
- * 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';
+import { getNodeErrorCode, pathExists } from './fs-async.js';
+import { getExternalTemplateCacheNowMs, getExternalTemplateCacheRoot, isExternalTemplateCacheEnabled, resolveExternalTemplateCachePruneIntervalMs, resolveExternalTemplateCacheTtlMs, } from './template-source-cache-policy.js';
+export { EXTERNAL_TEMPLATE_CACHE_DIR_ENV, EXTERNAL_TEMPLATE_CACHE_ENV, EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS_ENV, EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, getExternalTemplateCacheRoot, isExternalTemplateCacheEnabled, } from './template-source-cache-policy.js';
 /**
  * Marker file written after a cache entry is fully populated.
  */
@@ -34,14 +12,6 @@ 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.
  */
@@ -50,10 +20,6 @@ const PRIVATE_CACHE_DIRECTORY_MODE = 0o700;
  * Marker value used when URL-like metadata cannot be safely normalized.
  */
 const REDACTED_CACHE_METADATA_VALUE = '[redacted]';
-/**
- * Normalized environment values that disable the cache.
- */
-const DISABLED_CACHE_VALUES = new Set(['0', 'false', 'no', 'off']);
 /**
  * Filesystem errors that mean another writer published the same cache entry.
  */
@@ -80,80 +46,10 @@ const SAFE_CACHE_NAMESPACE_SEGMENT = /^[A-Za-z0-9_.-]+$/u;
  * Cache entries are deterministic SHA-256 digest directory names.
  */
 const SAFE_CACHE_ENTRY_SEGMENT = /^[a-f0-9]{64}$/u;
-/**
- * Checks whether remote external template source caching is enabled.
- *
- * Caching is enabled by default. Set `WP_TYPIA_EXTERNAL_TEMPLATE_CACHE` to
- * `0`, `false`, `no`, or `off` to force uncached resolution.
- *
- * @param env Environment object to inspect, defaulting to `process.env`.
- * @returns Whether external template source cache reads and writes are enabled.
- */
-export function isExternalTemplateCacheEnabled(env = process.env) {
-    const rawValue = env[EXTERNAL_TEMPLATE_CACHE_ENV];
-    if (rawValue === undefined) {
-        return true;
-    }
-    return !DISABLED_CACHE_VALUES.has(rawValue.trim().toLowerCase());
-}
-/**
- * Resolves the external template source cache root directory.
- *
- * `WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_DIR` overrides the location. Without an
- * override, wp-typia uses a per-user `wp-typia-template-source-cache-*`
- * directory inside the operating system temp directory.
- *
- * @param env Environment object to inspect, defaulting to `process.env`.
- * @returns Absolute cache root directory path.
- */
-export function getExternalTemplateCacheRoot(env = process.env) {
-    const configuredCacheDir = env[EXTERNAL_TEMPLATE_CACHE_DIR_ENV]?.trim();
-    if (configuredCacheDir) {
-        return path.resolve(configuredCacheDir);
-    }
-    return path.join(os.tmpdir(), `wp-typia-template-source-cache-${getCurrentUserCacheSegment()}`);
-}
-function parseExternalTemplateCacheTtlDays(value) {
-    if (typeof value !== 'string' && typeof value !== 'number') {
-        return null;
-    }
-    const ttlDays = typeof value === 'number' ? value : Number(value.trim());
-    if (!Number.isFinite(ttlDays) || ttlDays <= 0) {
-        return null;
-    }
-    return ttlDays;
-}
-function resolveExternalTemplateCacheTtlMs(options = {}) {
-    const env = options.env ?? process.env;
-    const ttlDays = options.ttlDays === undefined
-        ? parseExternalTemplateCacheTtlDays(env[EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV])
-        : parseExternalTemplateCacheTtlDays(options.ttlDays);
-    if (ttlDays === null) {
-        return null;
-    }
-    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);
+function createTemporaryCacheEntryDirName(cacheKey) {
+    // Crypto randomness keeps concurrent cache populators from colliding on the
+    // staging directory before the final atomic rename publishes the cache entry.
+    return `.tmp-${cacheKey}-${process.pid}-${Date.now()}-${randomUUID()}`;
 }
 /**
  * Creates a deterministic cache key from source identity and integrity parts.
@@ -166,15 +62,6 @@ export function createExternalTemplateCacheKey(keyParts) {
         .update(JSON.stringify(keyParts))
         .digest('hex');
 }
-async function pathExists(filePath) {
-    try {
-        await fsp.access(filePath, fs.constants.F_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 async function isDirectoryPath(directory) {
     try {
         const stats = await fsp.lstat(directory);
@@ -184,11 +71,6 @@ async function isDirectoryPath(directory) {
         return false;
     }
 }
-function getNodeErrorCode(error) {
-    return typeof error === 'object' && error !== null && 'code' in error
-        ? String(error.code)
-        : '';
-}
 async function removeTemporaryCacheEntry(entryDir) {
     try {
         await fsp.rm(entryDir, { force: true, recursive: true });
@@ -197,21 +79,6 @@ async function removeTemporaryCacheEntry(entryDir) {
         // Cache cleanup is best-effort; the caller can still continue uncached.
     }
 }
-function getCurrentUserCacheSegment() {
-    if (typeof process.getuid === 'function') {
-        return String(process.getuid());
-    }
-    try {
-        const safeUsername = os
-            .userInfo()
-            .username.trim()
-            .replace(/[^A-Za-z0-9._-]+/gu, '-');
-        return safeUsername.length > 0 ? safeUsername : 'user';
-    }
-    catch {
-        return 'user';
-    }
-}
 function getCurrentUid() {
     return typeof process.getuid === 'function' ? process.getuid() : null;
 }
@@ -360,14 +227,6 @@ async function readCacheEntryMarker(markerPath) {
 function cacheMetadataMatches(actual, expected) {
     return Object.entries(expected).every(([key, value]) => actual[key] === value);
 }
-function getExternalTemplateCacheNowMs(now) {
-    const nowMs = now instanceof Date
-        ? now.getTime()
-        : typeof now === 'number'
-            ? now
-            : Date.now();
-    return Number.isFinite(nowMs) ? nowMs : Date.now();
-}
 function isCacheEntryFreshForTtl(createdAtMs, nowMs, ttlMs) {
     return ttlMs === null || createdAtMs >= nowMs - ttlMs;
 }
@@ -673,9 +532,7 @@ export async function resolveExternalTemplateSourceCache(descriptor, populateSou
     if (existingMarker) {
         await removeCacheEntryWithinRoot(cacheRoot, entryDir);
     }
-    const temporaryEntryDir = path.join(namespaceDir, `.tmp-${cacheKey}-${process.pid}-${Date.now()}-${Math.random()
-        .toString(16)
-        .slice(2)}`);
+    const temporaryEntryDir = path.join(namespaceDir, createTemporaryCacheEntryDirName(cacheKey));
     const temporarySourceDir = path.join(temporaryEntryDir, 'source');
     let populateFailed = false;
     try {

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

@@ -7,6 +7,9 @@ export declare const EXTERNAL_TEMPLATE_TRUST_WARNING = "External template config
 /**
  * Search a source directory for the first supported external template entry.
  *
+ * @deprecated Use `findExternalTemplateEntry()` from async template-source
+ * paths. This synchronous helper remains only for compatibility callers.
+ *
  * @param sourceDir Directory that may contain an external template config entry.
  * @returns The first matching entry path, or null when no supported entry exists.
  */

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

@@ -33,6 +33,9 @@ function resolveSourceSubpath(sourceDir, relativePath) {
 /**
  * Search a source directory for the first supported external template entry.
  *
+ * @deprecated Use `findExternalTemplateEntry()` from async template-source
+ * paths. This synchronous helper remains only for compatibility callers.
+ *
  * @param sourceDir Directory that may contain an external template config entry.
  * @returns The first matching entry path, or null when no supported entry exists.
  */
@@ -205,11 +208,11 @@ export async function renderCreateBlockExternalTemplate(sourceDir, context, requ
         const view = await buildExternalTemplateView(context, config, selectedVariant, variantConfig);
         const blockTemplateDir = resolveSourceSubpath(sourceDir, templatePath);
         await copyRenderedDirectory(blockTemplateDir, blockDir, view, {
-            filter: (sourcePath, _destinationPath, entry) => {
+            filter: async (sourcePath, _destinationPath, entry) => {
                 const mustacheVariantPath = path.join(path.dirname(sourcePath), `${entry.name}.mustache`);
                 return !(entry.isFile() &&
                     (entry.name === 'package.json' || entry.name === 'README.md') &&
-                    fs.existsSync(mustacheVariantPath));
+                    (await pathExists(mustacheVariantPath)));
             },
         });
         const assetsPath = typeof variantConfig.assetsPath === 'string'

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

@@ -2,6 +2,9 @@ import type { ResolvedTemplateSource, SeedSource, TemplateVariableContext } from
 /**
  * Read a remote block source and return its default block category.
  *
+ * @deprecated Use `getDefaultCategoryAsync()` from async template-source paths.
+ * This synchronous helper remains only for compatibility callers.
+ *
  * @param sourceDir Block source directory that may contain a block.json file.
  * @returns The declared block category, or "widgets" when detection fails.
  */
@@ -16,6 +19,9 @@ export declare function getDefaultCategoryAsync(sourceDir: string): Promise<stri
 /**
  * Read `wpTypia.projectType` from a rendered or source template package
  * manifest and return it when present.
+ *
+ * @deprecated Use `getTemplateProjectTypeAsync()` from async template-source
+ * paths. This synchronous helper remains only for compatibility callers.
  */
 export declare function getTemplateProjectType(sourceDir: string): string | null;
 /**

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

@@ -59,6 +59,9 @@ async function readRemoteBlockJsonAsync(blockDir) {
 /**
  * Read a remote block source and return its default block category.
  *
+ * @deprecated Use `getDefaultCategoryAsync()` from async template-source paths.
+ * This synchronous helper remains only for compatibility callers.
+ *
  * @param sourceDir Block source directory that may contain a block.json file.
  * @returns The declared block category, or "widgets" when detection fails.
  */
@@ -139,6 +142,9 @@ async function readTemplatePackageJsonAsync(sourceDir) {
 /**
  * Read `wpTypia.projectType` from a rendered or source template package
  * manifest and return it when present.
+ *
+ * @deprecated Use `getTemplateProjectTypeAsync()` from async template-source
+ * paths. This synchronous helper remains only for compatibility callers.
  */
 export function getTemplateProjectType(sourceDir) {
     const packageJsonEntry = readTemplatePackageJson(sourceDir);
@@ -185,11 +191,11 @@ export async function normalizeWpTypiaTemplateSeed(seed) {
     const normalizedDir = path.join(tempRoot, 'template');
     try {
         await copyRawDirectory(seed.blockDir, normalizedDir, {
-            filter: (sourcePath, _targetPath, entry) => {
+            filter: async (sourcePath, _targetPath, entry) => {
                 const mustacheVariantPath = path.join(path.dirname(sourcePath), `${entry.name}.mustache`);
                 return !(entry.isFile() &&
                     (entry.name === 'package.json' || entry.name === 'README.md') &&
-                    fs.existsSync(mustacheVariantPath));
+                    (await pathExists(mustacheVariantPath)));
             },
         });
         if (seed.assetsDir && (await pathExists(seed.assetsDir))) {

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

@@ -1,5 +1,18 @@
 import type { RemoteTemplateLocator, SeedSource } from './template-source-contracts.js';
+/**
+ * Synchronously identify the bundled workspace template seed.
+ *
+ * This remains sync-only for compatibility callers. Async template resolution
+ * paths should use `isOfficialWorkspaceTemplateSeedAsync()`.
+ */
 export declare function isOfficialWorkspaceTemplateSeed(seed: SeedSource): boolean;
+/**
+ * Asynchronously identify the bundled workspace template seed.
+ *
+ * @param seed Seed source to inspect.
+ * @returns Whether the seed resolves to the official workspace template package.
+ */
+export declare function isOfficialWorkspaceTemplateSeedAsync(seed: SeedSource): Promise<boolean>;
 export declare function assertNoSymlinks(sourceDir: string): Promise<void>;
 /**
  * Resolves a template locator into a local seed source directory.

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

@@ -8,6 +8,7 @@ import { x as extractTarball } from 'tar';
 import { createExternalTemplateTimeoutError, fetchWithExternalTemplateTimeout, getExternalTemplateMetadataMaxBytes, getExternalTemplateTarballMaxBytes, getExternalTemplateTimeoutMs, readBufferResponseWithLimit, readJsonResponseWithLimit, } from './external-template-guards.js';
 import { findReusableExternalTemplateSourceCache, isExternalTemplateCacheEnabled, resolveExternalTemplateSourceCache, } from './template-source-cache.js';
 import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from './cli-diagnostics.js';
+import { pathExists } from './fs-async.js';
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, OFFICIAL_WORKSPACE_TEMPLATE_ALIAS, PROJECT_TOOLS_PACKAGE_ROOT, TEMPLATE_IDS, } from './template-registry.js';
 import { isPlainObject } from './object-utils.js';
 import { createManagedTempRoot } from './temp-roots.js';
@@ -184,7 +185,9 @@ async function fetchNpmTemplateSource(locator) {
  * Resolve a locally installed npm template package from the caller workspace.
  *
  * Bare package ids are preferred here so monorepo and offline workflows can
- * use an already-installed template without forcing a registry fetch.
+ * use an already-installed template without forcing a registry fetch. This
+ * path intentionally keeps Node's synchronous `require.resolve` semantics
+ * because the module resolver itself has no async equivalent.
  */
 function resolveInstalledNpmTemplateSource(locator, cwd) {
     if (locator.rawSpec !== '' && locator.rawSpec !== '*') {
@@ -244,6 +247,12 @@ function resolveInstalledNpmTemplateSource(locator, cwd) {
         throw error;
     }
 }
+/**
+ * Synchronously identify the bundled workspace template seed.
+ *
+ * This remains sync-only for compatibility callers. Async template resolution
+ * paths should use `isOfficialWorkspaceTemplateSeedAsync()`.
+ */
 export function isOfficialWorkspaceTemplateSeed(seed) {
     const packageJsonPath = path.join(seed.rootDir, 'package.json');
     if (!fs.existsSync(packageJsonPath)) {
@@ -257,6 +266,25 @@ export function isOfficialWorkspaceTemplateSeed(seed) {
         return false;
     }
 }
+/**
+ * Asynchronously identify the bundled workspace template seed.
+ *
+ * @param seed Seed source to inspect.
+ * @returns Whether the seed resolves to the official workspace template package.
+ */
+export async function isOfficialWorkspaceTemplateSeedAsync(seed) {
+    const packageJsonPath = path.join(seed.rootDir, 'package.json');
+    if (!(await pathExists(packageJsonPath))) {
+        return false;
+    }
+    try {
+        const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, 'utf8'));
+        return packageJson.name === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
+    }
+    catch {
+        return false;
+    }
+}
 export async function assertNoSymlinks(sourceDir) {
     const stats = await fsp.lstat(sourceDir);
     if (stats.isSymbolicLink()) {
@@ -300,13 +328,13 @@ function runGitTemplateCommand(args, label, options = {}) {
 function getGitHubTemplateRepositoryUrl(locator) {
     return `https://github.com/${locator.owner}/${locator.repo}.git`;
 }
-function resolveGitHubTemplateDirectory(checkoutDir, locator) {
+async function resolveGitHubTemplateDirectory(checkoutDir, locator) {
     const sourceDir = path.resolve(checkoutDir, locator.sourcePath);
     const relativeSourceDir = path.relative(checkoutDir, sourceDir);
     if (relativeSourceDir.startsWith('..') || path.isAbsolute(relativeSourceDir)) {
         throw new Error('GitHub template path must stay within the cloned repository.');
     }
-    if (!fs.existsSync(sourceDir)) {
+    if (!(await pathExists(sourceDir))) {
         throw new Error(`GitHub template path does not exist: ${locator.sourcePath}`);
     }
     return sourceDir;
@@ -438,7 +466,7 @@ async function reuseGitHubTemplateCacheByMetadata(locator) {
     if (!cachedSource) {
         return null;
     }
-    const sourceDir = resolveGitHubTemplateDirectory(cachedSource.sourceDir, locator);
+    const sourceDir = await resolveGitHubTemplateDirectory(cachedSource.sourceDir, locator);
     await assertNoSymlinks(sourceDir);
     return {
         blockDir: sourceDir,
@@ -482,12 +510,12 @@ async function resolveGitHubTemplateSource(locator) {
                 namespace: 'github',
             }, async (checkoutDir) => {
                 cloneGitHubTemplateSource(locator, checkoutDir);
-                const sourceDir = resolveGitHubTemplateDirectory(checkoutDir, locator);
+                const sourceDir = await resolveGitHubTemplateDirectory(checkoutDir, locator);
                 await assertNoSymlinks(sourceDir);
                 pinGitHubTemplateCacheRevision(locator, checkoutDir, resolvedCacheRevision);
             });
             if (cachedSource) {
-                const sourceDir = resolveGitHubTemplateDirectory(cachedSource.sourceDir, locator);
+                const sourceDir = await resolveGitHubTemplateDirectory(cachedSource.sourceDir, locator);
                 await assertNoSymlinks(sourceDir);
                 return {
                     blockDir: sourceDir,
@@ -506,7 +534,7 @@ async function resolveGitHubTemplateSource(locator) {
     const checkoutDir = path.join(remoteRoot, 'source');
     try {
         cloneGitHubTemplateSource(locator, checkoutDir);
-        const sourceDir = resolveGitHubTemplateDirectory(checkoutDir, locator);
+        const sourceDir = await resolveGitHubTemplateDirectory(checkoutDir, locator);
         await assertNoSymlinks(sourceDir);
         return {
             blockDir: sourceDir,
@@ -530,7 +558,7 @@ async function resolveGitHubTemplateSource(locator) {
 export async function resolveTemplateSeed(locator, cwd) {
     if (locator.kind === 'path') {
         const sourceDir = path.resolve(cwd, locator.templatePath);
-        if (!fs.existsSync(sourceDir)) {
+        if (!(await pathExists(sourceDir))) {
             throw new Error(`Template path does not exist: ${sourceDir}`);
         }
         await assertNoSymlinks(sourceDir);

package/dist/runtime/template-source.js

@@ -2,7 +2,7 @@ import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from './tem
 import { resolveBuiltInTemplateSource } from './template-builtins.js';
 import { parseTemplateLocator, } from './template-source-locators.js';
 import { detectTemplateSourceFormat, getTemplateProjectTypeAsync, getDefaultCategoryAsync, getTemplateVariableContext, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, renderCreateBlockExternalTemplate, } from './template-source-normalization.js';
-import { isOfficialWorkspaceTemplateSeed, resolveTemplateSeed, } from './template-source-seeds.js';
+import { isOfficialWorkspaceTemplateSeedAsync, 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';
@@ -27,7 +27,7 @@ export async function resolveTemplateSource(templateId, cwd, variables, variant)
     const context = getTemplateVariableContext(variables);
     const seed = await resolveTemplateSeed(locator, cwd);
     const isOfficialWorkspaceTemplate = templateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE ||
-        isOfficialWorkspaceTemplateSeed(seed);
+        (await isOfficialWorkspaceTemplateSeedAsync(seed));
     let normalizedSeed = null;
     try {
         const format = await detectTemplateSourceFormat(seed.blockDir);

package/dist/runtime/ts-property-names.d.ts

@@ -0,0 +1,11 @@
+import ts from "typescript";
+/**
+ * Extract the literal text for TypeScript property names this runtime supports.
+ *
+ * Computed property names are intentionally not resolved because their runtime
+ * values are not statically knowable from the syntax node alone.
+ *
+ * @param name TypeScript property name node.
+ * @returns Identifier, string-literal, or numeric-literal text; otherwise `null`.
+ */
+export declare function getPropertyNameText(name: ts.PropertyName): string | null;