@wp-typia/project-tools 0.22.3 → 0.22.4

package/dist/runtime/cli-add.js

@@ -3,11 +3,11 @@
  *
  * The canonical CLI surface stays stable here while the implementation lives
  * in focused internal modules:
- * - `cli-add-shared` for shared validation/help/rollback helpers
+ * - `cli-add-shared` as a compatibility barrel around focused add helpers
  * - `cli-add-block` for built-in block scaffolding
  * - `cli-add-workspace` for workspace mutation commands
  */
-export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, } from "./cli-add-shared.js";
+export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
 export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
 export { getWorkspaceBlockSelectOptions } from "./workspace-inventory.js";

package/dist/runtime/cli-doctor-workspace-blocks.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
 import { checkExistingFiles, createDoctorCheck, WORKSPACE_FULL_BLOCK_NAME_PATTERN, WORKSPACE_GENERATED_BLOCK_ARTIFACTS, } from "./cli-doctor-workspace-shared.js";
 import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_SET, } from "./hooked-blocks.js";
+import { hasExecutablePattern, hasUncommentedPattern, maskTypeScriptCommentsAndLiterals, } from "./ts-source-masking.js";
 const WORKSPACE_COLLECTION_IMPORT_LINE = "import '../../collection';";
 const WORKSPACE_COLLECTION_IMPORT_PATTERN = /^\s*import\s+["']\.\.\/\.\.\/collection["']\s*;?\s*$/m;
 const WORKSPACE_VARIATIONS_IMPORT_PATTERN = /^\s*import\s*\{\s*registerWorkspaceVariations\s*\}\s*from\s*["']\.\/variations["']\s*;?\s*$/mu;
@@ -40,72 +41,6 @@ const WORKSPACE_BLOCK_LOCAL_STYLE_FILES = [
 ];
 const WORKSPACE_BLOCK_IFRAME_GLOBAL_DOM_PATTERN = /\b(?:document|window)\b|\b(?:parent|top)\b(?!\s*:)/gu;
 const WORKSPACE_BLOCK_PROPS_PATTERN = /\buse(?:Block|InnerBlocks)Props(?:\.save)?\s*\(/u;
-function maskSourceSegment(segment) {
-    return segment.replace(/[^\n\r]/gu, " ");
-}
-function maskTypeScriptComments(source) {
-    return source
-        .replace(/\/\*[\s\S]*?\*\//gu, maskSourceSegment)
-        .replace(/\/\/[^\n\r]*/gu, maskSourceSegment);
-}
-// Preserve offsets while hiding non-executable text from hook checks.
-function maskTypeScriptCommentsAndLiterals(source) {
-    let maskedSource = "";
-    let index = 0;
-    while (index < source.length) {
-        const current = source[index];
-        const next = source[index + 1];
-        if (current === "/" && next === "/") {
-            const start = index;
-            index += 2;
-            while (index < source.length &&
-                source[index] !== "\n" &&
-                source[index] !== "\r") {
-                index += 1;
-            }
-            maskedSource += maskSourceSegment(source.slice(start, index));
-            continue;
-        }
-        if (current === "/" && next === "*") {
-            const start = index;
-            index += 2;
-            while (index < source.length &&
-                !(source[index] === "*" && source[index + 1] === "/")) {
-                index += 1;
-            }
-            index = Math.min(index + 2, source.length);
-            maskedSource += maskSourceSegment(source.slice(start, index));
-            continue;
-        }
-        if (current === "'" || current === '"' || current === "`") {
-            const start = index;
-            const quote = current;
-            index += 1;
-            while (index < source.length) {
-                const char = source[index];
-                if (char === "\\") {
-                    index += 2;
-                    continue;
-                }
-                index += 1;
-                if (char === quote) {
-                    break;
-                }
-            }
-            maskedSource += maskSourceSegment(source.slice(start, index));
-            continue;
-        }
-        maskedSource += current;
-        index += 1;
-    }
-    return maskedSource;
-}
-function hasUncommentedPattern(source, pattern) {
-    return pattern.test(maskTypeScriptComments(source));
-}
-function hasExecutablePattern(source, pattern) {
-    return pattern.test(maskTypeScriptCommentsAndLiterals(source));
-}
 function normalizePathSeparators(relativePath) {
     return relativePath.split(path.sep).join("/");
 }

package/dist/runtime/index.d.ts

@@ -32,6 +32,8 @@ export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, format
 export { clearPackageVersionsCache, getPackageVersions, invalidatePackageVersionsCache, } from "./package-versions.js";
 export type { PackageVersions } from "./package-versions.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
+export { EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, pruneExternalTemplateCache, } from "./template-source-cache.js";
+export type { ExternalTemplateCachePruneOptions, ExternalTemplateCachePruneResult, } from "./template-source-cache.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
 export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
 export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, DoctorCheck, EditorPluginSlotId, HookedBlockPositionId, ReadlinePrompt, } from "./cli-core.js";

package/dist/runtime/index.js

@@ -25,5 +25,6 @@ export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, str
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
 export { clearPackageVersionsCache, getPackageVersions, invalidatePackageVersionsCache, } from "./package-versions.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
+export { EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, pruneExternalTemplateCache, } from "./template-source-cache.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
 export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";

package/dist/runtime/migration-utils.d.ts

@@ -1,3 +1,4 @@
+import { type PackageManagerId } from './package-managers.js';
 import type { JsonValue, ManifestAttribute, JsonObject } from './migration-types.js';
 import { type UnknownRecord } from './object-utils.js';
 export { cloneJsonValue } from './json-utils.js';
@@ -12,7 +13,7 @@ export declare function copyFile(sourcePath: string, targetPath: string): void;
 export declare function sanitizeSaveSnapshotSource(source: string): string;
 export declare function sanitizeSnapshotBlockJson(blockJson: JsonObject): JsonObject;
 export declare function runProjectScriptIfPresent(projectDir: string, scriptName: string): void;
-export declare function detectPackageManagerId(projectDir: string): 'bun' | 'npm' | 'pnpm' | 'yarn';
+export declare function detectPackageManagerId(projectDir: string): PackageManagerId;
 export declare function getLocalTsxBinary(projectDir: string): string;
 /**
  * Returns whether isInteractiveTerminal() is running with both stdin and stdout

package/dist/runtime/migration-utils.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
-import { formatRunScript } from './package-managers.js';
+import { formatRunScript, inferPackageManagerId, parsePackageManagerField, } from './package-managers.js';
 import { isPlainObject } from './object-utils.js';
 export { cloneJsonValue } from './json-utils.js';
 const MIGRATION_VERSION_LABEL_PATTERN = /^v([1-9]\d*)$/;
@@ -141,16 +141,8 @@ export function runProjectScriptIfPresent(projectDir, scriptName) {
 }
 export function detectPackageManagerId(projectDir) {
     const packageJson = readJson(path.join(projectDir, 'package.json'));
-    const field = String(packageJson.packageManager ?? '');
-    if (field.startsWith('bun@'))
-        return 'bun';
-    if (field.startsWith('npm@'))
-        return 'npm';
-    if (field.startsWith('pnpm@'))
-        return 'pnpm';
-    if (field.startsWith('yarn@'))
-        return 'yarn';
-    return 'bun';
+    return (parsePackageManagerField(packageJson.packageManager) ??
+        inferPackageManagerId(projectDir));
 }
 export function getLocalTsxBinary(projectDir) {
     const filename = process.platform === 'win32' ? 'tsx.cmd' : 'tsx';

package/dist/runtime/package-managers.d.ts

@@ -9,6 +9,25 @@ export interface PackageManagerDefinition {
 export declare const PACKAGE_MANAGER_IDS: PackageManagerId[];
 export declare const PACKAGE_MANAGERS: Readonly<Record<PackageManagerId, PackageManagerDefinition>>;
 export declare function getPackageManager(id: string): PackageManagerDefinition;
+/**
+ * Parse a normalized package-manager id from a package.json `packageManager` field.
+ *
+ * @param packageManagerField Raw field value such as `pnpm@8.3.1`.
+ * @returns A supported package manager id, or null when the field is missing or unsupported.
+ */
+export declare function parsePackageManagerField(packageManagerField: string | undefined): PackageManagerId | null;
+/**
+ * Infer the package manager used by a project from package.json and lockfile signals.
+ *
+ * `packageManager` fields take precedence over lockfiles, then lockfile and PnP
+ * markers are checked in Bun, pnpm, Yarn, npm order. npm remains the fallback so
+ * generated projects without explicit metadata keep the historical CLI default.
+ *
+ * @param projectDir Project root to inspect.
+ * @param packageManagerField Optional already-read package.json field.
+ * @returns The inferred package manager id.
+ */
+export declare function inferPackageManagerId(projectDir: string, packageManagerField?: string): PackageManagerId;
 export declare function getPackageManagerSelectOptions(): Array<{
     label: string;
     value: PackageManagerId;

package/dist/runtime/package-managers.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 const PACKAGE_MANAGER_DATA = [
     {
         id: "bun",
@@ -28,6 +30,15 @@ const PACKAGE_MANAGER_DATA = [
         frozenInstallCommand: "yarn install --frozen-lockfile",
     },
 ];
+const PACKAGE_MANAGER_LOCKFILE_SIGNALS = [
+    { id: "bun", filenames: ["bun.lock", "bun.lockb"] },
+    { id: "pnpm", filenames: ["pnpm-lock.yaml"] },
+    {
+        id: "yarn",
+        filenames: ["yarn.lock", ".pnp.cjs", ".pnp.loader.mjs", ".yarnrc.yml"],
+    },
+    { id: "npm", filenames: ["package-lock.json", "npm-shrinkwrap.json"] },
+];
 export const PACKAGE_MANAGER_IDS = PACKAGE_MANAGER_DATA.map((manager) => manager.id);
 export const PACKAGE_MANAGERS = Object.freeze(Object.fromEntries(PACKAGE_MANAGER_DATA.map((manager) => [manager.id, manager])));
 const DEV_INSTALL_FLAGS = {
@@ -44,6 +55,57 @@ export function getPackageManager(id) {
     }
     return manager;
 }
+/**
+ * Parse a normalized package-manager id from a package.json `packageManager` field.
+ *
+ * @param packageManagerField Raw field value such as `pnpm@8.3.1`.
+ * @returns A supported package manager id, or null when the field is missing or unsupported.
+ */
+export function parsePackageManagerField(packageManagerField) {
+    const packageManagerId = packageManagerField?.split("@", 1)[0];
+    return PACKAGE_MANAGER_IDS.includes(packageManagerId)
+        ? packageManagerId
+        : null;
+}
+function readPackageManagerField(projectDir) {
+    try {
+        const packageJsonPath = path.join(projectDir, "package.json");
+        if (!fs.existsSync(packageJsonPath)) {
+            return undefined;
+        }
+        const manifest = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        return typeof manifest.packageManager === "string"
+            ? manifest.packageManager
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Infer the package manager used by a project from package.json and lockfile signals.
+ *
+ * `packageManager` fields take precedence over lockfiles, then lockfile and PnP
+ * markers are checked in Bun, pnpm, Yarn, npm order. npm remains the fallback so
+ * generated projects without explicit metadata keep the historical CLI default.
+ *
+ * @param projectDir Project root to inspect.
+ * @param packageManagerField Optional already-read package.json field.
+ * @returns The inferred package manager id.
+ */
+export function inferPackageManagerId(projectDir, packageManagerField) {
+    const fieldPackageManager = parsePackageManagerField(packageManagerField) ??
+        parsePackageManagerField(readPackageManagerField(projectDir));
+    if (fieldPackageManager) {
+        return fieldPackageManager;
+    }
+    for (const signal of PACKAGE_MANAGER_LOCKFILE_SIGNALS) {
+        if (signal.filenames.some((filename) => fs.existsSync(path.join(projectDir, filename)))) {
+            return signal.id;
+        }
+    }
+    return "npm";
+}
 export function getPackageManagerSelectOptions() {
     return PACKAGE_MANAGER_DATA.map((manager) => ({
         label: manager.label,

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

@@ -8,6 +8,12 @@ export declare const EXTERNAL_TEMPLATE_CACHE_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_C
  * 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";
 /**
  * Serializable metadata recorded in the cache marker for diagnostics.
  */
@@ -58,6 +64,48 @@ export interface ExternalTemplateCacheLookupDescriptor {
      */
     namespace: string;
 }
+/**
+ * Options for best-effort external template cache pruning.
+ */
+export interface ExternalTemplateCachePruneOptions {
+    /**
+     * Environment object to inspect, defaulting to `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Clock override for deterministic tests.
+     */
+    now?: Date | number;
+    /**
+     * TTL override in days. When omitted, the TTL environment variable is used.
+     */
+    ttlDays?: number;
+}
+/**
+ * Summary returned after external template cache pruning.
+ */
+export interface ExternalTemplateCachePruneResult {
+    /**
+     * Absolute cache root inspected by the pruning helper.
+     */
+    cacheRoot: string;
+    /**
+     * Entries removed because their marker timestamp exceeded the TTL.
+     */
+    prunedEntries: number;
+    /**
+     * Candidate cache entry directories inspected.
+     */
+    scannedEntries: number;
+    /**
+     * Candidate directories skipped because they were malformed or unsafe.
+     */
+    skippedEntries: number;
+    /**
+     * Resolved TTL in milliseconds, or `null` when pruning was disabled.
+     */
+    ttlMs: number | null;
+}
 /**
  * Checks whether remote external template source caching is enabled.
  *
@@ -86,6 +134,17 @@ export declare function getExternalTemplateCacheRoot(env?: NodeJS.ProcessEnv): s
  * @returns SHA-256 hex digest of the JSON-serialized key parts.
  */
 export declare function createExternalTemplateCacheKey(keyParts: readonly string[]): string;
+/**
+ * Removes stale external template cache entries when a positive TTL is configured.
+ *
+ * The helper is best-effort: malformed cache directories are skipped, cache
+ * roots must remain private and non-symlinked, and deletes are constrained to
+ * deterministic entry directories under the configured cache root.
+ *
+ * @param options Optional TTL, clock, and environment overrides.
+ * @returns Pruning summary with counts for inspected, skipped, and removed entries.
+ */
+export declare function pruneExternalTemplateCache(options?: ExternalTemplateCachePruneOptions): Promise<ExternalTemplateCachePruneResult>;
 /**
  * Finds a reusable cache entry whose marker metadata includes the expected fields.
  *

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

@@ -13,10 +13,20 @@ 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';
 /**
  * Marker file written after a cache entry is fully populated.
  */
 const CACHE_MARKER_FILE = 'wp-typia-template-cache.json';
+/**
+ * Milliseconds in one TTL day.
+ */
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
 /**
  * Private directory mode used for cache roots and entries on POSIX platforms.
  */
@@ -51,6 +61,10 @@ const URL_LIKE_METADATA_KEY = /(url|uri|registry|tarball)/iu;
  * Cache namespaces must stay within one path segment under the cache root.
  */
 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.
  *
@@ -84,6 +98,27 @@ export function getExternalTemplateCacheRoot(env = process.env) {
     }
     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;
+}
 /**
  * Creates a deterministic cache key from source identity and integrity parts.
  *
@@ -281,6 +316,129 @@ function parseCacheMarkerMetadata(markerText) {
 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 isPathInsideDirectory(directory, candidatePath) {
+    const relativePath = path.relative(directory, candidatePath);
+    return (relativePath.length > 0 &&
+        !relativePath.startsWith('..') &&
+        !path.isAbsolute(relativePath));
+}
+async function removeCacheEntryWithinRoot(cacheRoot, entryDir) {
+    if (!isPathInsideDirectory(cacheRoot, entryDir)) {
+        return false;
+    }
+    try {
+        await fsp.rm(entryDir, { force: true, recursive: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes stale external template cache entries when a positive TTL is configured.
+ *
+ * The helper is best-effort: malformed cache directories are skipped, cache
+ * roots must remain private and non-symlinked, and deletes are constrained to
+ * deterministic entry directories under the configured cache root.
+ *
+ * @param options Optional TTL, clock, and environment overrides.
+ * @returns Pruning summary with counts for inspected, skipped, and removed entries.
+ */
+export async function pruneExternalTemplateCache(options = {}) {
+    const env = options.env ?? process.env;
+    const cacheRoot = getExternalTemplateCacheRoot(env);
+    const ttlMs = resolveExternalTemplateCacheTtlMs({
+        env,
+        ttlDays: options.ttlDays,
+    });
+    const result = {
+        cacheRoot,
+        prunedEntries: 0,
+        scannedEntries: 0,
+        skippedEntries: 0,
+        ttlMs,
+    };
+    if (ttlMs === null || !(await isPrivateCacheDirectory(cacheRoot))) {
+        return result;
+    }
+    let namespaceEntries;
+    try {
+        namespaceEntries = await fsp.readdir(cacheRoot, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    const expiresBeforeMs = getExternalTemplateCacheNowMs(options.now) - ttlMs;
+    for (const namespaceEntry of namespaceEntries) {
+        if (!namespaceEntry.isDirectory()) {
+            continue;
+        }
+        const namespaceDir = resolveCacheNamespaceDir(cacheRoot, namespaceEntry.name);
+        if (!namespaceDir || !(await isPrivateCacheDirectory(namespaceDir))) {
+            result.skippedEntries += 1;
+            continue;
+        }
+        let cacheEntries;
+        try {
+            cacheEntries = await fsp.readdir(namespaceDir, { withFileTypes: true });
+        }
+        catch {
+            result.skippedEntries += 1;
+            continue;
+        }
+        for (const cacheEntry of cacheEntries) {
+            if (!cacheEntry.isDirectory()) {
+                continue;
+            }
+            if (!SAFE_CACHE_ENTRY_SEGMENT.test(cacheEntry.name)) {
+                result.skippedEntries += 1;
+                continue;
+            }
+            const entryDir = path.join(namespaceDir, cacheEntry.name);
+            result.scannedEntries += 1;
+            if (!isPathInsideDirectory(cacheRoot, entryDir)) {
+                result.skippedEntries += 1;
+                continue;
+            }
+            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);
+            if (!marker) {
+                result.skippedEntries += 1;
+                continue;
+            }
+            if (marker.createdAtMs < expiresBeforeMs) {
+                if (await removeCacheEntryWithinRoot(cacheRoot, entryDir)) {
+                    result.prunedEntries += 1;
+                }
+                else {
+                    result.skippedEntries += 1;
+                }
+            }
+        }
+    }
+    return result;
+}
 /**
  * Finds a reusable cache entry whose marker metadata includes the expected fields.
  *
@@ -304,6 +462,7 @@ export async function findReusableExternalTemplateSourceCache(descriptor) {
         !(await isPrivateCacheDirectory(namespaceDir))) {
         return null;
     }
+    await pruneExternalTemplateCache();
     let entries;
     try {
         entries = await fsp.readdir(namespaceDir, { withFileTypes: true });
@@ -371,6 +530,7 @@ export async function resolveExternalTemplateSourceCache(descriptor, populateSou
         !(await ensurePrivateCacheDirectory(namespaceDir))) {
         return null;
     }
+    await pruneExternalTemplateCache();
     if (await isReusableCacheEntry(entryDir, markerPath, sourceDir)) {
         return {
             cacheHit: true,

package/dist/runtime/ts-source-masking.d.ts

@@ -0,0 +1,28 @@
+/** Original-source range returned from a masked-source pattern match. */
+export interface SourceRange {
+    end: number;
+    start: number;
+}
+/**
+ * Masks TypeScript comments with spaces while preserving newlines and offsets.
+ */
+export declare function maskTypeScriptComments(source: string): string;
+/**
+ * Masks TypeScript comments and quoted/template literals with spaces while
+ * preserving source offsets. This is a lightweight lexer for runtime checks,
+ * not a full TypeScript parser, so template interpolation and regex/division
+ * ambiguity are intentionally left to callers that need deeper syntax analysis.
+ */
+export declare function maskTypeScriptCommentsAndLiterals(source: string): string;
+/**
+ * Tests for a pattern after hiding comments and quoted/template literals.
+ */
+export declare function hasExecutablePattern(source: string, pattern: RegExp): boolean;
+/**
+ * Tests for a pattern after hiding comments while leaving literals intact.
+ */
+export declare function hasUncommentedPattern(source: string, pattern: RegExp): boolean;
+/**
+ * Finds the first masked-source match that maps back to the original source.
+ */
+export declare function findExecutablePatternMatch(source: string, patterns: readonly RegExp[]): SourceRange | undefined;