@wp-typia/project-tools 0.22.7 → 0.22.8

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/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;

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

@@ -0,0 +1,16 @@
+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 function getPropertyNameText(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return null;
+}

package/dist/runtime/workspace-inventory.d.ts

@@ -179,13 +179,25 @@ type WorkspaceInventoryUpdateOptions = {
  */
 export declare function parseWorkspaceInventorySource(source: string): Omit<WorkspaceInventory, "blockConfigPath">;
 /**
- * Read and parse the canonical workspace inventory file.
+ * Synchronously read and parse the canonical workspace inventory file.
+ *
+ * This compatibility helper is intentionally sync-only for callers that expose
+ * synchronous APIs. Prefer `readWorkspaceInventoryAsync()` from async command
+ * paths so workspace reads do not block the event loop.
  *
  * @param projectDir Workspace root directory.
  * @returns Parsed `WorkspaceInventory` including the resolved `blockConfigPath`.
  * @throws {Error} When `scripts/block-config.ts` is missing or invalid.
  */
 export declare function readWorkspaceInventory(projectDir: string): WorkspaceInventory;
+/**
+ * Asynchronously read and parse the canonical workspace inventory file.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Parsed `WorkspaceInventory` including the resolved `blockConfigPath`.
+ * @throws {Error} When `scripts/block-config.ts` is missing or invalid.
+ */
+export declare function readWorkspaceInventoryAsync(projectDir: string): Promise<WorkspaceInventory>;
 /**
  * Return select options for the current workspace block inventory.
  *

package/dist/runtime/workspace-inventory.js

@@ -1,9 +1,10 @@
-import fs from "node:fs";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import ts from "typescript";
 import { REST_RESOURCE_METHOD_IDS } from "./cli-add-shared.js";
 import { escapeRegex } from "./php-utils.js";
+import { getPropertyNameText } from "./ts-property-names.js";
 function defineInventoryEntryParser(descriptor) {
     return descriptor;
 }
@@ -524,12 +525,6 @@ const INVENTORY_SECTIONS = [
         },
     },
 ];
-function getPropertyNameText(name) {
-    if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
-        return name.text;
-    }
-    return null;
-}
 function findExportedArrayLiteral(sourceFile, exportName) {
     for (const statement of sourceFile.statements) {
         if (!ts.isVariableStatement(statement)) {
@@ -705,7 +700,11 @@ export function parseWorkspaceInventorySource(source) {
     return parsedInventory;
 }
 /**
- * Read and parse the canonical workspace inventory file.
+ * Synchronously read and parse the canonical workspace inventory file.
+ *
+ * This compatibility helper is intentionally sync-only for callers that expose
+ * synchronous APIs. Prefer `readWorkspaceInventoryAsync()` from async command
+ * paths so workspace reads do not block the event loop.
  *
  * @param projectDir Workspace root directory.
  * @returns Parsed `WorkspaceInventory` including the resolved `blockConfigPath`.
@@ -715,7 +714,34 @@ export function readWorkspaceInventory(projectDir) {
     const blockConfigPath = path.join(projectDir, "scripts", "block-config.ts");
     let source;
     try {
-        source = fs.readFileSync(blockConfigPath, "utf8");
+        source = readFileSync(blockConfigPath, "utf8");
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            throw new Error(`Workspace inventory file is missing at ${blockConfigPath}. Expected scripts/block-config.ts to exist.`);
+        }
+        throw error;
+    }
+    return {
+        blockConfigPath,
+        ...parseWorkspaceInventorySource(source),
+    };
+}
+/**
+ * Asynchronously read and parse the canonical workspace inventory file.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Parsed `WorkspaceInventory` including the resolved `blockConfigPath`.
+ * @throws {Error} When `scripts/block-config.ts` is missing or invalid.
+ */
+export async function readWorkspaceInventoryAsync(projectDir) {
+    const blockConfigPath = path.join(projectDir, "scripts", "block-config.ts");
+    let source;
+    try {
+        source = await readFile(blockConfigPath, "utf8");
     }
     catch (error) {
         if (typeof error === "object" &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.22.7",
+  "version": "0.22.8",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -47,6 +47,11 @@
       "import": "./dist/runtime/cli-scaffold.js",
       "default": "./dist/runtime/cli-scaffold.js"
     },
+    "./create-template-validation": {
+      "types": "./dist/runtime/create-template-validation.d.ts",
+      "import": "./dist/runtime/create-template-validation.js",
+      "default": "./dist/runtime/create-template-validation.js"
+    },
     "./ai-artifacts": {
       "types": "./dist/runtime/ai-artifacts.d.ts",
       "import": "./dist/runtime/ai-artifacts.js",