@wp-typia/project-tools 0.22.3 → 0.22.5

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;

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

@@ -0,0 +1,104 @@
+function maskSourceSegment(segment) {
+    return segment.replace(/[^\n\r]/gu, " ");
+}
+function testPattern(source, pattern) {
+    pattern.lastIndex = 0;
+    const matched = pattern.test(source);
+    pattern.lastIndex = 0;
+    return matched;
+}
+/**
+ * Masks TypeScript comments with spaces while preserving newlines and offsets.
+ */
+export function maskTypeScriptComments(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//gu, maskSourceSegment)
+        .replace(/\/\/[^\n\r]*/gu, maskSourceSegment);
+}
+/**
+ * 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 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;
+}
+/**
+ * Tests for a pattern after hiding comments and quoted/template literals.
+ */
+export function hasExecutablePattern(source, pattern) {
+    return testPattern(maskTypeScriptCommentsAndLiterals(source), pattern);
+}
+/**
+ * Tests for a pattern after hiding comments while leaving literals intact.
+ */
+export function hasUncommentedPattern(source, pattern) {
+    return testPattern(maskTypeScriptComments(source), pattern);
+}
+/**
+ * Finds the first masked-source match that maps back to the original source.
+ */
+export function findExecutablePatternMatch(source, patterns) {
+    const maskedSource = maskTypeScriptCommentsAndLiterals(source);
+    for (const pattern of patterns) {
+        pattern.lastIndex = 0;
+        const match = pattern.exec(maskedSource);
+        pattern.lastIndex = 0;
+        if (match && match.index !== undefined) {
+            return {
+                end: match.index + match[0].length,
+                start: match.index,
+            };
+        }
+    }
+    return undefined;
+}

package/dist/runtime/typia-llm.d.ts

@@ -1,6 +1,6 @@
 import type { ArtifactSyncExecutionOptions, EndpointManifestDefinition, EndpointManifestEndpointDefinition } from '@wp-typia/block-runtime/metadata-core';
 import type { ILlmFunction, ILlmSchema, ILlmStructuredOutput } from 'typia';
-import { type EndpointAuthIntent, type EndpointWordPressAuthDefinition, type OpenApiDocument } from './schema-core.js';
+import { type EndpointAuthIntent, type EndpointWordPressAuthDefinition, type JsonSchemaObject, type OpenApiDocument } from './schema-core.js';
 /**
  * Method-level descriptor projected from an endpoint manifest for a generated
  * `typia.llm` controller interface.
@@ -186,6 +186,14 @@ export interface ProjectTypiaLlmStructuredOutputArtifactOptions {
     /** Compiled structured-output value produced by `typia.llm.structuredOutput(...)`. */
     structuredOutput: TypiaLlmStructuredOutputLike;
 }
+/**
+ * Narrow a `typia.llm` artifact field before applying JSON Schema mutations.
+ *
+ * @param value Candidate schema value emitted by `typia.llm`.
+ * @param context Human-readable artifact path for diagnostics.
+ * @returns The value narrowed to the shared JSON Schema object shape.
+ */
+export declare function assertJsonSchemaObject(value: unknown, context: string): JsonSchemaObject;
 /**
  * Builds the generated controller method descriptors that bridge endpoint
  * manifests to `typia.llm` TypeScript interfaces.

package/dist/runtime/typia-llm.js

@@ -105,6 +105,19 @@ function cloneJsonValueIfDefined(value) {
 function isJsonSchemaObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Narrow a `typia.llm` artifact field before applying JSON Schema mutations.
+ *
+ * @param value Candidate schema value emitted by `typia.llm`.
+ * @param context Human-readable artifact path for diagnostics.
+ * @returns The value narrowed to the shared JSON Schema object shape.
+ */
+export function assertJsonSchemaObject(value, context) {
+    if (isJsonSchemaObject(value)) {
+        return value;
+    }
+    throw new Error(`${context} must be a JSON Schema object.`);
+}
 function decodeJsonPointerSegment(segment) {
     return segment.replace(/~1/g, '/').replace(/~0/g, '~');
 }
@@ -551,23 +564,25 @@ export function applyOpenApiConstraintsToTypiaLlmFunctionArtifact({ functionArti
             typeof resolvedParameter.name === 'string');
     });
     const requestBodySchema = resolveOpenApiRequestBodySchema(operation, openApiDocument);
+    const parameterSchema = assertJsonSchemaObject(constrainedArtifact.parameters, `typia.llm parameters for "${constrainedArtifact.name}"`);
     if (requestBodySchema) {
         if (hasQueryParameters) {
-            mergeJsonSchemaConstraintProperties(openApiDocument, getOrCreateObjectProperty(constrainedArtifact.parameters, 'body'), requestBodySchema);
+            mergeJsonSchemaConstraintProperties(openApiDocument, getOrCreateObjectProperty(parameterSchema, 'body'), requestBodySchema);
         }
         else {
-            mergeJsonSchemaConstraintProperties(openApiDocument, constrainedArtifact.parameters, requestBodySchema);
+            mergeJsonSchemaConstraintProperties(openApiDocument, parameterSchema, requestBodySchema);
         }
     }
     if (hasQueryParameters) {
         applyOpenApiQueryParameterConstraints(requestBodySchema
-            ? getOrCreateObjectProperty(constrainedArtifact.parameters, 'query')
-            : constrainedArtifact.parameters, operation, openApiDocument);
+            ? getOrCreateObjectProperty(parameterSchema, 'query')
+            : parameterSchema, operation, openApiDocument);
     }
     if (constrainedArtifact.output) {
+        const outputSchema = assertJsonSchemaObject(constrainedArtifact.output, `typia.llm output for "${constrainedArtifact.name}"`);
         const responseSchema = resolveOpenApiSuccessResponseSchema(operation, openApiDocument);
         if (responseSchema) {
-            mergeJsonSchemaConstraintProperties(openApiDocument, constrainedArtifact.output, responseSchema);
+            mergeJsonSchemaConstraintProperties(openApiDocument, outputSchema, responseSchema);
         }
     }
     return constrainedArtifact;