@wp-typia/project-tools 0.24.4 → 0.24.6

package/dist/runtime/templates/template-render.js

@@ -0,0 +1,196 @@
+/// <reference path="./external-template-modules.d.ts" />
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import Mustache from "mustache";
+const BINARY_EXTENSIONS = new Set([
+    ".avif",
+    ".bmp",
+    ".gif",
+    ".ico",
+    ".jpeg",
+    ".jpg",
+    ".otf",
+    ".pdf",
+    ".png",
+    ".svg",
+    ".ttf",
+    ".webp",
+    ".woff",
+    ".woff2",
+]);
+const IDENTITY_MUSTACHE_ESCAPE = (value) => value;
+/**
+ * Render a Mustache template with full Mustache semantics while leaving values
+ * unescaped for scaffold source generation.
+ */
+export function renderMustacheTemplateString(template, view) {
+    const mustacheModule = Mustache;
+    const writer = new mustacheModule.Writer();
+    return writer.render(template, view, undefined, {
+        escape: IDENTITY_MUSTACHE_ESCAPE,
+    });
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Render direct `{{key}}` placeholders without enabling sections, partials, or
+ * any other Mustache features.
+ */
+function renderInterpolatedString(template, view) {
+    const keys = Object.keys(view);
+    if (keys.length === 0) {
+        return template;
+    }
+    const placeholderPattern = new RegExp(keys.map((key) => `({{${escapeRegExp(key)}}})`).join("|"), "g");
+    return template.replace(placeholderPattern, (match) => view[match.slice(2, -2)] ?? match);
+}
+function isBinaryTemplateFile(filePath) {
+    return BINARY_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+function resolveRenderedPath(targetDir, destinationName) {
+    const resolvedTargetDir = path.resolve(targetDir);
+    const resolvedDestinationPath = path.resolve(resolvedTargetDir, destinationName);
+    const relativePath = path.relative(resolvedTargetDir, resolvedDestinationPath);
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        throw new Error(`Rendered template path escapes target directory: ${destinationName}`);
+    }
+    return resolvedDestinationPath;
+}
+function stripTemplateExtension(entryName) {
+    return entryName.endsWith(".mustache")
+        ? entryName.slice(0, -".mustache".length)
+        : entryName;
+}
+function renderTemplateDestinationName(entryName, view, renderString) {
+    return renderString(stripTemplateExtension(entryName), view);
+}
+async function traverseTemplateDirectory({ filter, prepareDirectory, renderString, sourceDir, targetDir, view, visitFile, }) {
+    const entries = await fsp.readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationName = renderTemplateDestinationName(entry.name, view, renderString);
+        const destinationPath = resolveRenderedPath(targetDir, destinationName);
+        if (filter && !(await filter(sourcePath, destinationPath, entry))) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await prepareDirectory?.(destinationPath);
+            await traverseTemplateDirectory({
+                filter,
+                prepareDirectory,
+                renderString,
+                sourceDir: sourcePath,
+                targetDir: destinationPath,
+                view,
+                visitFile,
+            });
+            continue;
+        }
+        await visitFile({
+            destinationPath,
+            sourcePath,
+        });
+    }
+}
+async function copyTemplateDirectory({ filter, renderString, sourceDir, targetDir, view, }) {
+    await fsp.mkdir(targetDir, { recursive: true });
+    await traverseTemplateDirectory({
+        filter,
+        prepareDirectory: async (directoryPath) => {
+            await fsp.mkdir(directoryPath, { recursive: true });
+        },
+        renderString,
+        sourceDir,
+        targetDir,
+        view,
+        visitFile: async ({ destinationPath, sourcePath }) => {
+            await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
+            if (isBinaryTemplateFile(sourcePath)) {
+                await fsp.copyFile(sourcePath, destinationPath);
+                return;
+            }
+            const content = await fsp.readFile(sourcePath, "utf8");
+            await fsp.writeFile(destinationPath, renderString(content, view), "utf8");
+        },
+    });
+}
+/**
+ * Recursively copies a directory tree without rendering template contents.
+ */
+export async function copyRawDirectory(sourceDir, targetDir, options = {}) {
+    await fsp.mkdir(targetDir, { recursive: true });
+    for (const entry of await fsp.readdir(sourceDir, { withFileTypes: true })) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const targetPath = path.join(targetDir, entry.name);
+        if (options.filter && !(await options.filter(sourcePath, targetPath, entry))) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await copyRawDirectory(sourcePath, targetPath, options);
+            continue;
+        }
+        await fsp.mkdir(path.dirname(targetPath), { recursive: true });
+        await fsp.copyFile(sourcePath, targetPath);
+    }
+}
+/**
+ * Copy a template directory using full Mustache semantics for filenames and
+ * text-file contents while leaving rendered values unescaped.
+ */
+export async function copyRenderedDirectory(sourceDir, targetDir, view, options = {}) {
+    await copyTemplateDirectory({
+        filter: options.filter,
+        renderString: renderMustacheTemplateString,
+        sourceDir,
+        targetDir,
+        view,
+    });
+}
+/**
+ * Copy a template directory using direct `{{key}}` replacement only.
+ *
+ * This intentionally preserves literal Mustache sections, partials, and other
+ * advanced constructs so built-in scaffold copy paths keep their historical
+ * interpolation behavior.
+ */
+export async function copyInterpolatedDirectory(sourceDir, targetDir, view) {
+    await copyTemplateDirectory({
+        renderString: renderInterpolatedString,
+        sourceDir,
+        targetDir,
+        view,
+    });
+}
+/**
+ * Lists the output file paths produced by an interpolated template directory
+ * without writing any files to disk.
+ *
+ * This walks the source directory, applies the same filename interpolation and
+ * `.mustache` stripping rules as `copyInterpolatedDirectory(...)`, and returns
+ * normalized output-relative paths under a virtual root.
+ *
+ * @param sourceDir - The template directory to traverse.
+ * @param view - The interpolation map used when resolving file and directory
+ * names.
+ * @returns A sorted array of normalized output paths relative to a virtual
+ * preview root.
+ */
+export async function listInterpolatedDirectoryOutputs(sourceDir, view) {
+    const virtualRoot = path.resolve("/wp-typia-template-preview");
+    const outputs = [];
+    await traverseTemplateDirectory({
+        renderString: renderInterpolatedString,
+        sourceDir,
+        targetDir: virtualRoot,
+        view,
+        visitFile: async ({ destinationPath }) => {
+            outputs.push(path.relative(virtualRoot, destinationPath).replace(/\\/g, "/"));
+        },
+    });
+    return outputs.sort((left, right) => left.localeCompare(right));
+}
+export function pathExistsSync(targetPath) {
+    return fs.existsSync(targetPath);
+}

package/dist/runtime/templates/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/templates/template-source-cache-markers.js

@@ -0,0 +1,130 @@
+import { safeJsonParse } from '../shared/json-utils.js';
+/**
+ * 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 = safeJsonParse(markerText, {
+            context: 'external template cache entry marker',
+        });
+    }
+    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 = safeJsonParse(markerText, {
+            context: 'external template cache prune marker',
+        });
+    }
+    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/templates/template-source-cache-policy.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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";
+/**
+ * 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;
+export declare function resolveExternalTemplateCacheTtlMs(options?: {
+    env?: NodeJS.ProcessEnv;
+    ttlDays?: number;
+}): number | null;
+export declare function resolveExternalTemplateCachePruneIntervalMs(options?: {
+    env?: NodeJS.ProcessEnv;
+    pruneIntervalMs?: number;
+}): number | null;
+export declare function getExternalTemplateCacheNowMs(now: Date | number | undefined): number;

package/dist/runtime/templates/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/templates/template-source-cache.d.ts

@@ -0,0 +1,143 @@
+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';
+/**
+ * Describes a deterministic external template cache entry.
+ *
+ * `namespace` scopes independent cache families, `keyParts` identify the exact
+ * source/integrity tuple, and `metadata` is persisted to the marker file.
+ */
+export interface ExternalTemplateCacheDescriptor {
+    /**
+     * Ordered values that deterministically identify one cached template source.
+     */
+    keyParts: readonly string[];
+    /**
+     * Diagnostic values persisted to the cache marker after sanitization.
+     */
+    metadata: ExternalTemplateCacheMetadata;
+    /**
+     * Cache family scope, stored as a single safe directory segment.
+     */
+    namespace: string;
+}
+/**
+ * Result returned when a cache entry is reused or populated.
+ */
+export interface ExternalTemplateCacheResolution {
+    /**
+     * Whether the returned source directory came from an existing cache entry.
+     */
+    cacheHit: boolean;
+    /**
+     * Populated or reused template source directory.
+     */
+    sourceDir: string;
+}
+/**
+ * Metadata-only lookup descriptor for finding an existing reusable cache entry.
+ */
+export interface ExternalTemplateCacheLookupDescriptor {
+    /**
+     * Metadata fields that must match the sanitized marker metadata.
+     */
+    metadata: ExternalTemplateCacheMetadata;
+    /**
+     * Cache family scope, stored as a single safe directory segment.
+     */
+    namespace: string;
+}
+/**
+ * Options for best-effort external template cache pruning.
+ */
+export interface ExternalTemplateCachePruneOptions {
+    /**
+     * Environment object to inspect, defaulting to `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Force a full prune scan even when the last-pruned marker is still fresh.
+     */
+    force?: boolean;
+    /**
+     * Clock override for deterministic tests.
+     */
+    now?: Date | number;
+    /**
+     * Minimum interval between full prune scans. Omit for the environment/default.
+     */
+    pruneIntervalMs?: number;
+    /**
+     * TTL override in days. When omitted, the TTL environment variable is used.
+     */
+    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;
+    /**
+     * Whether a recent last-pruned marker skipped the full cache directory scan.
+     */
+    skippedByThrottle: boolean;
+    /**
+     * Resolved TTL in milliseconds, or `null` when pruning was disabled.
+     */
+    ttlMs: number | null;
+}
+/**
+ * Creates a deterministic cache key from source identity and integrity parts.
+ *
+ * @param keyParts Ordered values that identify one cached template source.
+ * @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.
+ *
+ * This lookup is intended for resilient fallbacks where a caller cannot compute
+ * the exact deterministic key but can safely reuse a previously validated local
+ * cache entry for the same source identity.
+ *
+ * @param descriptor Cache namespace and marker metadata fields to match.
+ * @returns Existing cache resolution details, or `null` when no safe entry exists.
+ */
+export declare function findReusableExternalTemplateSourceCache(descriptor: ExternalTemplateCacheLookupDescriptor): Promise<ExternalTemplateCacheResolution | null>;
+/**
+ * Resolves or populates a cached external template source directory.
+ *
+ * Returns `null` when caching is disabled. Cache misses populate a temporary
+ * directory first and then atomically move it into place; concurrent writers
+ * that lose the race reuse the completed marker/source pair.
+ *
+ * @param descriptor Namespace, key parts, and metadata for the cache entry.
+ * @param populateSourceDir Callback that writes the guarded source on a miss.
+ * @returns Cache resolution details, or `null` when caching is disabled.
+ */
+export declare function resolveExternalTemplateSourceCache(descriptor: ExternalTemplateCacheDescriptor, populateSourceDir: (sourceDir: string) => Promise<void>): Promise<ExternalTemplateCacheResolution | null>;