@wp-typia/project-tools 0.22.10 → 0.23.1

package/dist/runtime/scaffold.js

@@ -3,11 +3,12 @@ import path from "node:path";
 import { getPackageManager } from "./package-managers.js";
 import { buildGitignore, buildReadme, mergeTextLines, removeQueryLoopPlaceholderFiles, replaceTextRecursively, } from "./scaffold-apply-utils.js";
 import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, } from "./local-dev-presets.js";
+import { runAddIntegrationEnvCommand } from "./cli-add-workspace-integration-env.js";
 import { applyMigrationUiCapability } from "./migration-ui-capability.js";
 import { applyWorkspaceMigrationCapability, ensureScaffoldDirectory, isWorkspaceProject, seedBuiltInPersistenceArtifacts, writeStarterManifestFiles, } from "./scaffold-bootstrap.js";
 import { defaultInstallDependencies, normalizePackageJson, normalizePackageManagerFiles, removeUnexpectedLockfiles, } from "./scaffold-package-manager-files.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { isBuiltInTemplateId, normalizeTemplateLookupId, } from "./template-registry.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, normalizeTemplateLookupId, } from "./template-registry.js";
 import { resolveTemplateSource } from "./template-source.js";
 import { BlockGeneratorService, } from "./block-generator-service.js";
 import { getTemplateVariables } from "./scaffold-template-variables.js";
@@ -16,6 +17,8 @@ import { assertExternalLayerCompositionOptions, } from "./cli-validation.js";
 import { pathExists } from "./fs-async.js";
 export const DATA_STORAGE_MODES = ["post-meta", "custom-table"];
 export const PERSISTENCE_POLICIES = ["authenticated", "public"];
+/** Supported create profile ids for opt-in workspace scaffold presets. */
+export const CREATE_PROFILE_IDS = ["plugin-qa"];
 export { buildBlockCssClassName } from "./scaffold-identifiers.js";
 export { collectScaffoldAnswers, detectAuthor, getDefaultAnswers, resolvePackageManagerId, resolveTemplateId, } from "./scaffold-answer-resolution.js";
 export { getTemplateVariables } from "./scaffold-template-variables.js";
@@ -26,16 +29,62 @@ export function isDataStorageMode(value) {
 export function isPersistencePolicy(value) {
     return PERSISTENCE_POLICIES.includes(value);
 }
+/**
+ * Return whether a raw string is a supported create profile id.
+ */
+export function isCreateProfileId(value) {
+    return CREATE_PROFILE_IDS.includes(value);
+}
+/**
+ * Resolve an optional create profile flag into a validated profile id.
+ *
+ * Empty input disables profile application; unknown ids throw with the allowed
+ * profile list for CLI diagnostics.
+ */
+export function resolveCreateProfileId(profile) {
+    if (profile === undefined || profile.trim().length === 0) {
+        return undefined;
+    }
+    const normalizedProfile = profile.trim();
+    if (isCreateProfileId(normalizedProfile)) {
+        return normalizedProfile;
+    }
+    throw new Error(`Unknown create profile "${profile}". Expected one of: ${CREATE_PROFILE_IDS.join(", ")}.`);
+}
 function normalizeTemplateSelection(templateId) {
     return normalizeTemplateLookupId(templateId);
 }
+function assertCreateProfileTemplateCompatibility({ profile, templateId, }) {
+    if (!profile) {
+        return;
+    }
+    if (profile === "plugin-qa" && templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        throw new Error("`--profile plugin-qa` currently supports only the official workspace template. Use `--template workspace` or add QA files later with `wp-typia add integration-env <name> --wp-env --release-zip`.");
+    }
+}
+async function applyCreateProfile({ profile, projectDir, }) {
+    if (profile !== "plugin-qa") {
+        return;
+    }
+    await runAddIntegrationEnvCommand({
+        cwd: projectDir,
+        integrationEnvName: "local-smoke",
+        service: "none",
+        withReleaseZip: true,
+        withWpEnv: true,
+    });
+}
 async function reportScaffoldProgress(onProgress, event) {
     await onProgress?.(event);
 }
-export async function scaffoldProject({ projectDir, templateId, answers, alternateRenderTargets, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, onProgress = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+export async function scaffoldProject({ projectDir, templateId, answers, alternateRenderTargets, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, profile, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, onProgress = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
     const resolvedTemplateId = normalizeTemplateSelection(templateId);
     const resolvedPackageManager = getPackageManager(packageManager).id;
     const isBuiltInTemplate = isBuiltInTemplateId(resolvedTemplateId);
+    assertCreateProfileTemplateCompatibility({
+        profile,
+        templateId: resolvedTemplateId,
+    });
     assertExternalLayerCompositionOptions({
         externalLayerId,
         externalLayerSource,
@@ -174,6 +223,10 @@ export async function scaffoldProject({ projectDir, templateId, answers, alterna
             withWpEnv,
         });
     }
+    await applyCreateProfile({
+        profile,
+        projectDir,
+    });
     await normalizePackageManagerFiles(projectDir, resolvedPackageManager);
     await removeUnexpectedLockfiles(projectDir, resolvedPackageManager);
     await replaceTextRecursively(projectDir, resolvedPackageManager, {

package/dist/runtime/temp-roots.js

@@ -23,7 +23,10 @@ function cleanupTrackedTempRootsSync() {
         try {
             fs.rmSync(tempRoot, { force: true, recursive: true });
         }
-        catch { }
+        catch {
+            // Process-exit cleanup is best-effort: shutdown-time rm failures
+            // such as EPERM are intentionally ignored rather than made fatal.
+        }
     }
 }
 function installCleanupHandlers() {

package/dist/runtime/template-layers.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { promises as fsp } from "node:fs";
 import { pathExists } from "./fs-async.js";
+import { readJsonFile } from "./json-utils.js";
 import { isPlainObject } from "./object-utils.js";
 import { getBuiltInSharedTemplateLayerDir, isBuiltInSharedTemplateLayerId, } from "./template-builtins.js";
 import { listInterpolatedDirectoryOutputs } from "./template-render.js";
@@ -59,7 +60,9 @@ export async function loadExternalTemplateLayerManifest(sourceRoot) {
     if (!(await pathExists(manifestPath))) {
         return null;
     }
-    const raw = JSON.parse(await fsp.readFile(manifestPath, "utf8"));
+    const raw = await readJsonFile(manifestPath, {
+        context: "template layer manifest",
+    });
     if (!isPlainObject(raw)) {
         throw new Error(`${TEMPLATE_LAYER_MANIFEST_FILENAME} must export a JSON object.`);
     }

package/dist/runtime/template-registry.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { readJsonFileSync } from "./json-utils.js";
 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";
@@ -11,7 +12,9 @@ function resolveValidProjectToolsPackageRoot(candidateRoot) {
         return undefined;
     }
     try {
-        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        const packageJson = readJsonFileSync(packageJsonPath, {
+            context: "project-tools package manifest override",
+        });
         return packageJson.name === PROJECT_TOOLS_PACKAGE_NAME
             ? candidateRoot
             : undefined;
@@ -42,13 +45,16 @@ export function resolvePackageRoot(startDir) {
         const packageJsonPath = path.join(currentDir, "package.json");
         if (fs.existsSync(packageJsonPath)) {
             try {
-                const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+                const packageJson = readJsonFileSync(packageJsonPath, {
+                    context: "project-tools package root discovery manifest",
+                });
                 if (packageJson.name === PROJECT_TOOLS_PACKAGE_NAME) {
                     return currentDir;
                 }
             }
             catch {
-                // Ignore malformed package.json while walking upward.
+                // Ignore malformed package.json while walking upward; discovery should
+                // keep searching parent directories instead of failing on unrelated files.
             }
         }
         const parentDir = path.dirname(currentDir);

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

@@ -55,4 +55,4 @@ export declare function copyInterpolatedDirectory(sourceDir: string, targetDir:
  * preview root.
  */
 export declare function listInterpolatedDirectoryOutputs(sourceDir: string, view: Record<string, string>): Promise<string[]>;
-export declare function pathExists(targetPath: string): boolean;
+export declare function pathExistsSync(targetPath: string): boolean;

package/dist/runtime/template-render.js

@@ -191,6 +191,6 @@ export async function listInterpolatedDirectoryOutputs(sourceDir, view) {
     });
     return outputs.sort((left, right) => left.localeCompare(right));
 }
-export function pathExists(targetPath) {
+export function pathExistsSync(targetPath) {
     return fs.existsSync(targetPath);
 }

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

@@ -0,0 +1,37 @@
+/**
+ * Marker file written after a cache entry is fully populated.
+ */
+export declare const CACHE_MARKER_FILE = "wp-typia-template-cache.json";
+/**
+ * Marker file written after a full TTL prune scan completes.
+ */
+export declare const CACHE_PRUNE_MARKER_FILE = "wp-typia-template-cache-prune.json";
+/**
+ * Serializable metadata recorded in cache markers for diagnostics.
+ */
+export type ExternalTemplateCacheMetadata = Record<string, string | null>;
+export interface ExternalTemplateCacheEntryMarker {
+    createdAtMs: number;
+    metadata: ExternalTemplateCacheMetadata;
+}
+export interface ExternalTemplateCachePruneMarker {
+    prunedAtMs: number;
+    pruneIntervalMs: number | null;
+    ttlMs: number;
+}
+export declare function sanitizeExternalTemplateCacheMetadata(metadata: ExternalTemplateCacheMetadata): ExternalTemplateCacheMetadata;
+export declare function parseExternalTemplateCacheEntryMarker(markerText: string): ExternalTemplateCacheEntryMarker | null;
+export declare function externalTemplateCacheMetadataMatches(actual: ExternalTemplateCacheMetadata, expected: ExternalTemplateCacheMetadata): boolean;
+export declare function isExternalTemplateCacheEntryFreshForTtl(createdAtMs: number, nowMs: number, ttlMs: number | null): boolean;
+export declare function parseExternalTemplateCachePruneMarker(markerText: string): ExternalTemplateCachePruneMarker | null;
+export declare function formatExternalTemplateCacheEntryMarker({ cacheKey, createdAt, metadata, namespace, }: {
+    cacheKey: string;
+    createdAt: Date;
+    metadata: ExternalTemplateCacheMetadata;
+    namespace: string;
+}): string;
+export declare function formatExternalTemplateCachePruneMarker({ nowMs, pruneIntervalMs, ttlMs, }: {
+    nowMs: number;
+    pruneIntervalMs: number | null;
+    ttlMs: number;
+}): string;

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

@@ -0,0 +1,125 @@
+/**
+ * Marker file written after a cache entry is fully populated.
+ */
+export const CACHE_MARKER_FILE = 'wp-typia-template-cache.json';
+/**
+ * Marker file written after a full TTL prune scan completes.
+ */
+export const CACHE_PRUNE_MARKER_FILE = 'wp-typia-template-cache-prune.json';
+/**
+ * Marker value used when URL-like metadata cannot be safely normalized.
+ */
+const REDACTED_CACHE_METADATA_VALUE = '[redacted]';
+/**
+ * Metadata fields that may contain credentialed or signed URLs.
+ */
+const URL_LIKE_METADATA_KEY = /(url|uri|registry|tarball)/iu;
+function sanitizeExternalTemplateCacheMetadataValue(key, value) {
+    if (!URL_LIKE_METADATA_KEY.test(key)) {
+        return value;
+    }
+    try {
+        const url = new URL(value);
+        url.username = '';
+        url.password = '';
+        url.search = '';
+        url.hash = '';
+        return url.toString();
+    }
+    catch {
+        return REDACTED_CACHE_METADATA_VALUE;
+    }
+}
+export function sanitizeExternalTemplateCacheMetadata(metadata) {
+    return Object.fromEntries(Object.entries(metadata).map(([key, value]) => [
+        key,
+        value === null
+            ? null
+            : sanitizeExternalTemplateCacheMetadataValue(key, value),
+    ]));
+}
+export function parseExternalTemplateCacheEntryMarker(markerText) {
+    let marker;
+    try {
+        marker = JSON.parse(markerText);
+    }
+    catch {
+        return null;
+    }
+    if (typeof marker !== 'object' || marker === null || Array.isArray(marker)) {
+        return null;
+    }
+    const rawMetadata = marker.metadata;
+    if (typeof rawMetadata !== 'object' ||
+        rawMetadata === null ||
+        Array.isArray(rawMetadata)) {
+        return null;
+    }
+    const metadata = {};
+    for (const [key, value] of Object.entries(rawMetadata)) {
+        if (typeof value !== 'string' && value !== null) {
+            return null;
+        }
+        metadata[key] = value;
+    }
+    const rawCreatedAt = marker.createdAt;
+    const createdAtMs = typeof rawCreatedAt === 'string' ? Date.parse(rawCreatedAt) : 0;
+    return {
+        createdAtMs: Number.isFinite(createdAtMs) ? createdAtMs : 0,
+        metadata,
+    };
+}
+export function externalTemplateCacheMetadataMatches(actual, expected) {
+    return Object.entries(expected).every(([key, value]) => actual[key] === value);
+}
+export function isExternalTemplateCacheEntryFreshForTtl(createdAtMs, nowMs, ttlMs) {
+    return ttlMs === null || createdAtMs >= nowMs - ttlMs;
+}
+export function parseExternalTemplateCachePruneMarker(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,
+    };
+}
+export function formatExternalTemplateCacheEntryMarker({ cacheKey, createdAt, metadata, namespace, }) {
+    return `${JSON.stringify({
+        createdAt: createdAt.toISOString(),
+        key: cacheKey,
+        metadata: sanitizeExternalTemplateCacheMetadata(metadata),
+        namespace,
+    }, null, 2)}\n`;
+}
+export function formatExternalTemplateCachePruneMarker({ nowMs, pruneIntervalMs, ttlMs, }) {
+    return `${JSON.stringify({
+        prunedAt: new Date(nowMs).toISOString(),
+        pruneIntervalMs,
+        ttlMs,
+    }, null, 2)}\n`;
+}

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

@@ -1,8 +1,5 @@
+import { type ExternalTemplateCacheMetadata } from './template-source-cache-markers.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';
-/**
- * Serializable metadata recorded in the cache marker for diagnostics.
- */
-type ExternalTemplateCacheMetadata = Record<string, string | null>;
 /**
  * Describes a deterministic external template cache entry.
  *

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

@@ -2,24 +2,13 @@ import { createHash, randomUUID } from 'node:crypto';
 import { promises as fsp } from 'node:fs';
 import path from 'node:path';
 import { getNodeErrorCode, pathExists } from './fs-async.js';
+import { CACHE_MARKER_FILE, CACHE_PRUNE_MARKER_FILE, externalTemplateCacheMetadataMatches, formatExternalTemplateCacheEntryMarker, formatExternalTemplateCachePruneMarker, isExternalTemplateCacheEntryFreshForTtl, parseExternalTemplateCacheEntryMarker, parseExternalTemplateCachePruneMarker, } from './template-source-cache-markers.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.
- */
-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';
 /**
  * Private directory mode used for cache roots and entries on POSIX platforms.
  */
 const PRIVATE_CACHE_DIRECTORY_MODE = 0o700;
-/**
- * Marker value used when URL-like metadata cannot be safely normalized.
- */
-const REDACTED_CACHE_METADATA_VALUE = '[redacted]';
 /**
  * Filesystem errors that mean another writer published the same cache entry.
  */
@@ -34,10 +23,6 @@ const CACHE_UNAVAILABLE_ERROR_CODES = new Set([
     'EPERM',
     'EROFS',
 ]);
-/**
- * Metadata fields that may contain credentialed or signed URLs.
- */
-const URL_LIKE_METADATA_KEY = /(url|uri|registry|tarball)/iu;
 /**
  * Cache namespaces must stay within one path segment under the cache root.
  */
@@ -126,28 +111,6 @@ async function ensurePrivateCacheDirectory(directory) {
         return false;
     }
 }
-function sanitizeCacheMetadataValue(key, value) {
-    if (!URL_LIKE_METADATA_KEY.test(key)) {
-        return value;
-    }
-    try {
-        const url = new URL(value);
-        url.username = '';
-        url.password = '';
-        url.search = '';
-        url.hash = '';
-        return url.toString();
-    }
-    catch {
-        return REDACTED_CACHE_METADATA_VALUE;
-    }
-}
-function sanitizeCacheMetadata(metadata) {
-    return Object.fromEntries(Object.entries(metadata).map(([key, value]) => [
-        key,
-        value === null ? null : sanitizeCacheMetadataValue(key, value),
-    ]));
-}
 function resolveCacheNamespaceDir(cacheRoot, namespace) {
     if (namespace === '.' ||
         namespace === '..' ||
@@ -185,51 +148,14 @@ async function isReusableCacheEntry(entryDir, markerPath, sourceDir) {
         (await pathExists(markerPath)) &&
         (await isDirectoryPath(sourceDir)));
 }
-function parseCacheMarkerMetadata(markerText) {
-    let marker;
-    try {
-        marker = JSON.parse(markerText);
-    }
-    catch {
-        return null;
-    }
-    if (typeof marker !== 'object' || marker === null || Array.isArray(marker)) {
-        return null;
-    }
-    const rawMetadata = marker.metadata;
-    if (typeof rawMetadata !== 'object' ||
-        rawMetadata === null ||
-        Array.isArray(rawMetadata)) {
-        return null;
-    }
-    const metadata = {};
-    for (const [key, value] of Object.entries(rawMetadata)) {
-        if (typeof value !== 'string' && value !== null) {
-            return null;
-        }
-        metadata[key] = value;
-    }
-    const rawCreatedAt = marker.createdAt;
-    const createdAtMs = typeof rawCreatedAt === 'string' ? Date.parse(rawCreatedAt) : 0;
-    return {
-        createdAtMs: Number.isFinite(createdAtMs) ? createdAtMs : 0,
-        metadata,
-    };
-}
 async function readCacheEntryMarker(markerPath) {
     try {
-        return parseCacheMarkerMetadata(await fsp.readFile(markerPath, 'utf8'));
+        return parseExternalTemplateCacheEntryMarker(await fsp.readFile(markerPath, 'utf8'));
     }
     catch {
         return null;
     }
 }
-function cacheMetadataMatches(actual, expected) {
-    return Object.entries(expected).every(([key, value]) => actual[key] === value);
-}
-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;
@@ -238,7 +164,8 @@ async function getReusableCacheEntryMarker(entryDir, markerPath, sourceDir) {
 }
 async function isReusableFreshCacheEntry(entryDir, markerPath, sourceDir, nowMs, ttlMs) {
     const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
-    return (marker !== null && isCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs));
+    return (marker !== null &&
+        isExternalTemplateCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs));
 }
 function isPathInsideDirectory(directory, candidatePath) {
     const relativePath = path.relative(directory, candidatePath);
@@ -261,39 +188,6 @@ async function removeCacheEntryWithinRoot(cacheRoot, entryDir) {
 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;
@@ -305,7 +199,7 @@ async function shouldSkipExternalTemplateCachePrune({ cacheRoot, force, nowMs, p
     catch {
         return false;
     }
-    const marker = parseCachePruneMarker(markerText);
+    const marker = parseExternalTemplateCachePruneMarker(markerText);
     if (!marker ||
         marker.ttlMs !== ttlMs ||
         marker.pruneIntervalMs !== pruneIntervalMs) {
@@ -316,11 +210,11 @@ async function shouldSkipExternalTemplateCachePrune({ cacheRoot, force, nowMs, p
 }
 async function writeExternalTemplateCachePruneMarker({ cacheRoot, nowMs, pruneIntervalMs, ttlMs, }) {
     try {
-        await fsp.writeFile(getCachePruneMarkerPath(cacheRoot), `${JSON.stringify({
-            prunedAt: new Date(nowMs).toISOString(),
+        await fsp.writeFile(getCachePruneMarkerPath(cacheRoot), formatExternalTemplateCachePruneMarker({
+            nowMs,
             pruneIntervalMs,
             ttlMs,
-        }, null, 2)}\n`, 'utf8');
+        }), 'utf8');
     }
     catch {
         // Prune markers are an optimization; failing to write one keeps TTL safe.
@@ -476,8 +370,8 @@ export async function findReusableExternalTemplateSourceCache(descriptor) {
         const sourceDir = path.join(entryDir, 'source');
         const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
         if (!marker ||
-            !isCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs) ||
-            !cacheMetadataMatches(marker.metadata, descriptor.metadata)) {
+            !isExternalTemplateCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs) ||
+            !externalTemplateCacheMetadataMatches(marker.metadata, descriptor.metadata)) {
             continue;
         }
         if (!bestEntry || marker.createdAtMs > bestEntry.createdAtMs) {
@@ -523,7 +417,7 @@ export async function resolveExternalTemplateSourceCache(descriptor, populateSou
     await pruneExternalTemplateCache();
     const existingMarker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
     if (existingMarker &&
-        isCacheEntryFreshForTtl(existingMarker.createdAtMs, nowMs, ttlMs)) {
+        isExternalTemplateCacheEntryFreshForTtl(existingMarker.createdAtMs, nowMs, ttlMs)) {
         return {
             cacheHit: true,
             sourceDir,
@@ -550,12 +444,12 @@ export async function resolveExternalTemplateSourceCache(descriptor, populateSou
             populateFailed = true;
             throw error;
         }
-        await fsp.writeFile(path.join(temporaryEntryDir, CACHE_MARKER_FILE), `${JSON.stringify({
-            createdAt: new Date().toISOString(),
-            key: cacheKey,
-            metadata: sanitizeCacheMetadata(descriptor.metadata),
+        await fsp.writeFile(path.join(temporaryEntryDir, CACHE_MARKER_FILE), formatExternalTemplateCacheEntryMarker({
+            cacheKey,
+            createdAt: new Date(),
+            metadata: descriptor.metadata,
             namespace: descriptor.namespace,
-        }, null, 2)}\n`, 'utf8');
+        }), 'utf8');
         await fsp.rename(temporaryEntryDir, entryDir);
         return {
             cacheHit: false,

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

@@ -11,6 +11,8 @@ export interface TemplateVariableContext extends UnknownRecord {
     blockRuntimePackageVersion: string;
     /** Version string for `@wp-typia/block-types` used in generated dependencies. */
     blockTypesPackageVersion: string;
+    /** Version string for `wp-typia` used when templates include the CLI binary locally. */
+    wpTypiaPackageVersion: string;
     /** PascalCase block type name derived from the scaffold slug. */
     pascalCase: string;
     /** Snake_case PHP symbol prefix used for generated functions, constants, and keys. */

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

@@ -7,8 +7,10 @@ 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.
+ * @deprecated Since 0.22.10. Use `findExternalTemplateEntry()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
  *
  * @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,8 +33,10 @@ 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.
+ * @deprecated Since 0.22.10. Use `findExternalTemplateEntry()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
  *
  * @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-normalization.js

@@ -8,13 +8,14 @@ import { pathExists } from './fs-async.js';
 export { renderCreateBlockExternalTemplate } from './template-source-external.js';
 export { getTemplateProjectType, getTemplateProjectTypeAsync, getDefaultCategory, getDefaultCategoryAsync, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, } from './template-source-remote.js';
 export function getTemplateVariableContext(variables) {
-    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = getPackageVersions();
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, wpTypiaPackageVersion, } = getPackageVersions();
     return {
         ...variables,
         apiClientPackageVersion: variables.apiClientPackageVersion ?? apiClientPackageVersion,
         blockRuntimePackageVersion: variables.blockRuntimePackageVersion ?? blockRuntimePackageVersion,
         blockTypesPackageVersion: variables.blockTypesPackageVersion ?? blockTypesPackageVersion,
         projectToolsPackageVersion: variables.projectToolsPackageVersion ?? projectToolsPackageVersion,
+        wpTypiaPackageVersion: variables.wpTypiaPackageVersion ?? wpTypiaPackageVersion,
         description: variables.description,
         keyword: variables.keyword,
         namespace: variables.namespace,