@wp-typia/project-tools 0.22.9 → 0.23.0

package/dist/runtime/package-versions.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { getOptionalNodeErrorCode } from './fs-async.js';
 import { PROJECT_TOOLS_PACKAGE_ROOT } from './template-registry.js';
 const require = createRequire(import.meta.url);
 const DEFAULT_VERSION_RANGE = '^0.0.0';
@@ -21,11 +22,6 @@ export const DEFAULT_WORDPRESS_DATA_VERSION = '^9.28.0';
 export const DEFAULT_WORDPRESS_DATAVIEWS_VERSION = '^14.1.0';
 export const DEFAULT_WP_TYPIA_DATAVIEWS_VERSION = '^0.1.1';
 let cachedPackageVersions = null;
-function getErrorCode(error) {
-    return typeof error === 'object' && error !== null && 'code' in error
-        ? String(error.code)
-        : undefined;
-}
 function normalizeVersionRange(value) {
     const trimmed = value?.trim();
     if (!trimmed) {
@@ -82,7 +78,7 @@ function resolvePackageManifestLocation(packageJsonPath) {
         };
     }
     catch (error) {
-        if (getErrorCode(error) === 'ENOENT') {
+        if (getOptionalNodeErrorCode(error) === 'ENOENT') {
             return {
                 cacheKey: `missing-file:${packageJsonPath}`,
                 packageJsonPath: null,
@@ -114,7 +110,7 @@ function resolveInstalledPackageManifestLocation(packageName) {
         return resolvePackageManifestLocation(require.resolve(`${packageName}/package.json`));
     }
     catch (error) {
-        if (getErrorCode(error) === 'MODULE_NOT_FOUND') {
+        if (getOptionalNodeErrorCode(error) === 'MODULE_NOT_FOUND') {
             return {
                 cacheKey: `missing-module:${packageName}`,
                 packageJsonPath: null,

package/dist/runtime/rest-resource-artifacts.d.ts

@@ -1,7 +1,8 @@
-import type { RestResourceMethodId } from "./cli-add-shared.js";
+import type { ManualRestContractAuthId, ManualRestContractHttpMethodId, RestResourceMethodId } from "./cli-add-shared.js";
 interface RestResourceTemplateVariablesLike {
     namespace: string;
     pascalCase: string;
+    routePattern?: string;
     slugKebabCase: string;
     title: string;
 }
@@ -14,6 +15,26 @@ interface SyncRestResourceArtifactsOptions {
     validatorsFile: string;
     variables: RestResourceTemplateVariablesLike;
 }
+interface ManualRestContractTemplateVariablesLike {
+    auth: ManualRestContractAuthId;
+    bodyTypeName?: string;
+    method: ManualRestContractHttpMethodId;
+    namespace: string;
+    pascalCase: string;
+    pathPattern: string;
+    queryTypeName: string;
+    responseTypeName: string;
+    slugKebabCase: string;
+    title: string;
+}
+interface SyncManualRestContractArtifactsOptions {
+    clientFile: string;
+    outputDir: string;
+    projectDir: string;
+    typesFile: string;
+    validatorsFile: string;
+    variables: ManualRestContractTemplateVariablesLike;
+}
 /**
  * Build the endpoint manifest for a workspace-level REST resource scaffold.
  *
@@ -24,6 +45,33 @@ interface SyncRestResourceArtifactsOptions {
 export declare function buildRestResourceEndpointManifest(variables: RestResourceTemplateVariablesLike, methods: RestResourceMethodId[]): import("@wp-typia/block-runtime/metadata-core").EndpointManifestDefinition<Record<string, {
     sourceTypeName: string;
 }>, import("@wp-typia/block-runtime/schema-core").EndpointOpenApiEndpointDefinition[]>;
+/**
+ * Build the endpoint manifest for a type-only manual REST contract. Manual
+ * contracts describe routes owned by another integration without generating PHP
+ * route glue in the workspace.
+ *
+ * @param variables Template naming data used for contract names, route path,
+ * and OpenAPI info.
+ * @returns Endpoint manifest consumed by schema, OpenAPI, and client generators.
+ */
+export declare function buildManualRestContractEndpointManifest(variables: ManualRestContractTemplateVariablesLike): import("@wp-typia/block-runtime/metadata-core").EndpointManifestDefinition<Record<string, {
+    sourceTypeName: string;
+}>, readonly [{
+    readonly wordpressAuth?: {
+        mechanism: "rest-nonce";
+    } | {
+        mechanism: "public-signed-token";
+    } | undefined;
+    readonly method: "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+    readonly operationId: `call${string}ManualRestContract`;
+    readonly path: `/${string}${string}`;
+    readonly queryContract: "query";
+    readonly responseContract: "response";
+    readonly summary: `Call external ${string} REST route.`;
+    readonly tags: readonly [string];
+    readonly bodyContract?: string | undefined;
+    readonly auth: "authenticated" | "public" | "public-write-protected";
+}]>;
 /**
  * Synchronize generated schemas, OpenAPI output, and endpoint client code for
  * a workspace-level REST resource scaffold.
@@ -32,4 +80,12 @@ export declare function buildRestResourceEndpointManifest(variables: RestResourc
  * @returns A promise that resolves after every generated REST artifact has been refreshed.
  */
 export declare function syncRestResourceArtifacts({ clientFile, methods, outputDir, projectDir, typesFile, validatorsFile, variables, }: SyncRestResourceArtifactsOptions): Promise<void>;
+/**
+ * Synchronize generated schemas, OpenAPI output, and endpoint client code for a
+ * type-only manual REST contract.
+ *
+ * @param options Contract file paths and naming variables.
+ * @returns A promise that resolves after every generated artifact has refreshed.
+ */
+export declare function syncManualRestContractArtifacts({ clientFile, outputDir, projectDir, typesFile, validatorsFile, variables, }: SyncManualRestContractArtifactsOptions): Promise<void>;
 export {};

package/dist/runtime/rest-resource-artifacts.js

@@ -1,5 +1,18 @@
 import path from "node:path";
 import { defineEndpointManifest, syncEndpointClient, syncRestOpenApi, syncTypeSchemas, } from "@wp-typia/block-runtime/metadata-core";
+function resolveManualRestContractWordPressAuth(auth) {
+    if (auth === "authenticated") {
+        return {
+            mechanism: "rest-nonce",
+        };
+    }
+    if (auth === "public-write-protected") {
+        return {
+            mechanism: "public-signed-token",
+        };
+    }
+    return undefined;
+}
 /**
  * Build the endpoint manifest for a workspace-level REST resource scaffold.
  *
@@ -9,7 +22,12 @@ import { defineEndpointManifest, syncEndpointClient, syncRestOpenApi, syncTypeSc
  */
 export function buildRestResourceEndpointManifest(variables, methods) {
     const basePath = `/${variables.namespace}/${variables.slugKebabCase}`;
-    const itemPath = `${basePath}/item`;
+    const routePattern = variables.routePattern == null
+        ? `/${variables.slugKebabCase}/item`
+        : variables.routePattern.startsWith("/")
+            ? variables.routePattern
+            : `/${variables.routePattern}`;
+    const itemPath = `/${variables.namespace}${routePattern}`;
     const contracts = {};
     const endpoints = [];
     if (methods.includes("list")) {
@@ -124,6 +142,52 @@ export function buildRestResourceEndpointManifest(variables, methods) {
         },
     });
 }
+/**
+ * Build the endpoint manifest for a type-only manual REST contract. Manual
+ * contracts describe routes owned by another integration without generating PHP
+ * route glue in the workspace.
+ *
+ * @param variables Template naming data used for contract names, route path,
+ * and OpenAPI info.
+ * @returns Endpoint manifest consumed by schema, OpenAPI, and client generators.
+ */
+export function buildManualRestContractEndpointManifest(variables) {
+    const contracts = {
+        query: {
+            sourceTypeName: variables.queryTypeName,
+        },
+        response: {
+            sourceTypeName: variables.responseTypeName,
+        },
+    };
+    if (variables.bodyTypeName) {
+        contracts.request = {
+            sourceTypeName: variables.bodyTypeName,
+        };
+    }
+    const wordpressAuth = resolveManualRestContractWordPressAuth(variables.auth);
+    return defineEndpointManifest({
+        contracts,
+        endpoints: [
+            {
+                auth: variables.auth,
+                ...(variables.bodyTypeName ? { bodyContract: "request" } : {}),
+                method: variables.method,
+                operationId: `call${variables.pascalCase}ManualRestContract`,
+                path: `/${variables.namespace}${variables.pathPattern}`,
+                queryContract: "query",
+                responseContract: "response",
+                summary: `Call external ${variables.title} REST route.`,
+                tags: [variables.title],
+                ...(wordpressAuth ? { wordpressAuth } : {}),
+            },
+        ],
+        info: {
+            title: `${variables.title} Manual REST Contract`,
+            version: "1.0.0",
+        },
+    });
+}
 /**
  * Synchronize generated schemas, OpenAPI output, and endpoint client code for
  * a workspace-level REST resource scaffold.
@@ -156,3 +220,35 @@ export async function syncRestResourceArtifacts({ clientFile, methods, outputDir
         validatorsFile,
     });
 }
+/**
+ * Synchronize generated schemas, OpenAPI output, and endpoint client code for a
+ * type-only manual REST contract.
+ *
+ * @param options Contract file paths and naming variables.
+ * @returns A promise that resolves after every generated artifact has refreshed.
+ */
+export async function syncManualRestContractArtifacts({ clientFile, outputDir, projectDir, typesFile, validatorsFile, variables, }) {
+    const manifest = buildManualRestContractEndpointManifest(variables);
+    for (const [baseName, contract] of Object.entries(manifest.contracts)) {
+        await syncTypeSchemas({
+            jsonSchemaFile: path.join(outputDir, "api-schemas", `${baseName}.schema.json`),
+            openApiFile: path.join(outputDir, "api-schemas", `${baseName}.openapi.json`),
+            projectRoot: projectDir,
+            sourceTypeName: contract.sourceTypeName,
+            typesFile,
+        });
+    }
+    await syncRestOpenApi({
+        manifest,
+        openApiFile: path.join(outputDir, "api.openapi.json"),
+        projectRoot: projectDir,
+        typesFile,
+    });
+    await syncEndpointClient({
+        clientFile,
+        manifest,
+        projectRoot: projectDir,
+        typesFile,
+        validatorsFile,
+    });
+}

package/dist/runtime/scaffold-repository-reference.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
+import { getOptionalNodeErrorCode } from "./fs-async.js";
 import { PROJECT_TOOLS_PACKAGE_ROOT } from "./template-registry.js";
 const require = createRequire(import.meta.url);
 /**
@@ -8,17 +9,12 @@ const require = createRequire(import.meta.url);
  * can be resolved from the current runtime package manifests.
  */
 export const DEFAULT_SCAFFOLD_REPOSITORY_REFERENCE = "imjlk/wp-typia";
-function getErrorCode(error) {
-    return typeof error === "object" && error !== null && "code" in error
-        ? String(error.code)
-        : undefined;
-}
 function readRepositoryPackageManifest(packageJsonPath) {
     try {
         return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
     }
     catch (error) {
-        if (getErrorCode(error) === "ENOENT") {
+        if (getOptionalNodeErrorCode(error) === "ENOENT") {
             return null;
         }
         throw error;
@@ -29,7 +25,7 @@ function resolveInstalledPackageManifestPath(packageName) {
         return require.resolve(`${packageName}/package.json`);
     }
     catch (error) {
-        if (getErrorCode(error) === "MODULE_NOT_FOUND") {
+        if (getOptionalNodeErrorCode(error) === "MODULE_NOT_FOUND") {
             return null;
         }
         throw error;

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.
  *