@wp-typia/project-tools 0.23.1 → 0.24.1

package/dist/runtime/typia-llm-render.js

@@ -0,0 +1,252 @@
+import { normalizeEndpointAuthDefinition } from './schema-core.js';
+const TYPESCRIPT_RESERVED_WORDS = new Set([
+    'abstract',
+    'any',
+    'as',
+    'asserts',
+    'async',
+    'await',
+    'bigint',
+    'boolean',
+    'break',
+    'case',
+    'catch',
+    'class',
+    'const',
+    'constructor',
+    'continue',
+    'debugger',
+    'declare',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'enum',
+    'export',
+    'extends',
+    'false',
+    'finally',
+    'for',
+    'from',
+    'function',
+    'get',
+    'global',
+    'if',
+    'implements',
+    'import',
+    'in',
+    'infer',
+    'instanceof',
+    'interface',
+    'is',
+    'keyof',
+    'let',
+    'module',
+    'namespace',
+    'never',
+    'new',
+    'null',
+    'number',
+    'object',
+    'of',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'readonly',
+    'require',
+    'return',
+    'satisfies',
+    'set',
+    'static',
+    'string',
+    'super',
+    'switch',
+    'symbol',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'type',
+    'typeof',
+    'undefined',
+    'unique',
+    'unknown',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+function getContractSourceTypeName(manifest, endpoint, contractName) {
+    const contract = manifest.contracts[contractName];
+    if (!contract) {
+        throw new Error(`Endpoint "${endpoint.operationId}" references missing input contract "${contractName}".`);
+    }
+    return contract.sourceTypeName;
+}
+function getEndpointInputTypeDescriptor(manifest, endpoint) {
+    if (endpoint.bodyContract && endpoint.queryContract) {
+        const bodyTypeName = getContractSourceTypeName(manifest, endpoint, endpoint.bodyContract);
+        const queryTypeName = getContractSourceTypeName(manifest, endpoint, endpoint.queryContract);
+        return {
+            importTypeNames: [bodyTypeName, queryTypeName],
+            signatureTypeName: `{ body: ${bodyTypeName}; query: ${queryTypeName} }`,
+        };
+    }
+    const contractName = endpoint.method === 'GET'
+        ? endpoint.queryContract ?? null
+        : endpoint.bodyContract ?? endpoint.queryContract ?? null;
+    if (!contractName) {
+        return {
+            importTypeNames: [],
+            signatureTypeName: null,
+        };
+    }
+    const sourceTypeName = getContractSourceTypeName(manifest, endpoint, contractName);
+    return {
+        importTypeNames: [sourceTypeName],
+        signatureTypeName: sourceTypeName,
+    };
+}
+function getEndpointOutputTypeName(manifest, endpoint) {
+    const contract = manifest.contracts[endpoint.responseContract];
+    if (!contract) {
+        throw new Error(`Endpoint "${endpoint.operationId}" references missing response contract "${endpoint.responseContract}".`);
+    }
+    return contract.sourceTypeName;
+}
+function escapeJsDocLine(line) {
+    return line.replace(/\*\//g, '* /');
+}
+function renderDescriptionJsDocLines(method) {
+    const description = method.description && method.description.trim().length > 0
+        ? method.description
+        : method.operationId;
+    const descriptionLines = description
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => line.trim().replace(/\s+/g, ' '))
+        .filter(Boolean);
+    return (descriptionLines.length > 0
+        ? descriptionLines
+        : [method.operationId]).map((line) => ` * ${escapeJsDocLine(line)}`);
+}
+function renderMethodJsDoc(method) {
+    const lines = [
+        '/**',
+        ...renderDescriptionJsDocLines(method),
+        ' *',
+        ` * REST path: ${method.method} ${method.path}`,
+        ` * Auth intent: ${method.authIntent}`,
+        ...(method.wordpressAuth
+            ? [
+                ` * WordPress auth: ${method.wordpressAuth.mechanism}${method.wordpressAuth.publicTokenField
+                    ? ` (field: ${method.wordpressAuth.publicTokenField})`
+                    : ''}`,
+            ]
+            : []),
+        ...method.tags.map((tag) => ` * @tag ${escapeJsDocLine(tag)}`),
+        ' */',
+    ];
+    return lines.join('\n');
+}
+function renderMethodSignature(method) {
+    const inputSignature = method.inputTypeName === null ? '' : `input: ${method.inputTypeName}`;
+    const methodName = /^[$A-Z_][$0-9A-Z_]*$/i.test(method.operationId) &&
+        !TYPESCRIPT_RESERVED_WORDS.has(method.operationId)
+        ? method.operationId
+        : JSON.stringify(method.operationId);
+    return `${methodName}(${inputSignature}): ${method.outputTypeName};`;
+}
+export function renderTypiaLlmModuleFromMethodDescriptors({ applicationExportName, interfaceName, structuredOutputExportName, structuredOutputTypeName, typesImportPath, }, methods) {
+    const importedTypeNames = new Set([structuredOutputTypeName]);
+    for (const method of methods) {
+        importedTypeNames.add(method.outputTypeName);
+        if (method.inputTypeImportNames) {
+            for (const inputTypeImportName of method.inputTypeImportNames) {
+                importedTypeNames.add(inputTypeImportName);
+            }
+        }
+        else if (method.inputTypeName) {
+            importedTypeNames.add(method.inputTypeName);
+        }
+    }
+    const imports = Array.from(importedTypeNames).sort().join(',\n\t');
+    const methodBlocks = methods
+        .map((method) => {
+        const jsDoc = renderMethodJsDoc(method)
+            .split('\n')
+            .map((line) => `\t${line}`)
+            .join('\n');
+        return `${jsDoc}\n\t${renderMethodSignature(method)}`;
+    })
+        .join('\n\n');
+    return `import typia from "typia";
+import type {
+\t${imports},
+} from "${typesImportPath}";
+
+export interface ${interfaceName} {
+${methodBlocks}
+}
+
+export const ${applicationExportName} =
+\ttypia.llm.application<${interfaceName}>();
+
+export const ${structuredOutputExportName} =
+\ttypia.llm.structuredOutput<${structuredOutputTypeName}>();
+`;
+}
+/**
+ * Builds the generated controller method descriptors that bridge endpoint
+ * manifests to `typia.llm` TypeScript interfaces.
+ *
+ * @param manifest Endpoint manifest that owns operation and source type names.
+ * @returns Ordered method descriptors matching the manifest endpoints.
+ * @throws When an endpoint has ambiguous query/body input mapping.
+ * @throws When an endpoint references a missing input or output contract.
+ */
+export function buildTypiaLlmEndpointMethodDescriptors(manifest) {
+    return manifest.endpoints.map((endpoint) => {
+        const normalizedAuth = normalizeEndpointAuthDefinition(endpoint);
+        const inputTypeDescriptor = getEndpointInputTypeDescriptor(manifest, endpoint);
+        const inputTypeName = inputTypeDescriptor.signatureTypeName;
+        const shouldUseInlineInputImports = inputTypeName !== null &&
+            inputTypeDescriptor.importTypeNames.length > 0 &&
+            inputTypeDescriptor.importTypeNames[0] !== inputTypeName;
+        return {
+            authIntent: normalizedAuth.auth,
+            ...(normalizedAuth.authMode ? { authMode: normalizedAuth.authMode } : {}),
+            description: endpoint.summary,
+            inputTypeName,
+            ...(shouldUseInlineInputImports
+                ? { inputTypeImportNames: inputTypeDescriptor.importTypeNames }
+                : {}),
+            method: endpoint.method,
+            operationId: endpoint.operationId,
+            outputTypeName: getEndpointOutputTypeName(manifest, endpoint),
+            path: endpoint.path,
+            tags: endpoint.tags ?? [],
+            ...(normalizedAuth.wordpressAuth
+                ? { wordpressAuth: normalizedAuth.wordpressAuth }
+                : {}),
+        };
+    });
+}
+/**
+ * Renders a build-time-only TypeScript module that invokes `typia.llm` against
+ * canonical manifest-owned contracts.
+ *
+ * @param options Render options for the generated adapter module.
+ * @returns The generated TypeScript source.
+ */
+export function renderTypiaLlmModule({ applicationExportName, interfaceName, manifest, structuredOutputExportName, structuredOutputTypeName, typesImportPath, }) {
+    return renderTypiaLlmModuleFromMethodDescriptors({
+        applicationExportName,
+        interfaceName,
+        structuredOutputExportName,
+        structuredOutputTypeName,
+        typesImportPath,
+    }, buildTypiaLlmEndpointMethodDescriptors(manifest));
+}

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

@@ -0,0 +1,10 @@
+import type { SyncTypiaLlmAdapterModuleOptions, SyncTypiaLlmAdapterModuleResult } from './typia-llm-types.js';
+/**
+ * Writes or verifies the generated build-time `typia.llm` adapter module. The
+ * returned TypeScript source still needs to be compiled by the consuming
+ * project's Typia transformer before JSON artifacts can be read from it.
+ *
+ * @param options Generated module destination plus render options.
+ * @returns Rendered source, method descriptors, and the checked/written file path.
+ */
+export declare function syncTypiaLlmAdapterModule({ check, generatedSourceFile, ...renderOptions }: SyncTypiaLlmAdapterModuleOptions): Promise<SyncTypiaLlmAdapterModuleResult>;

package/dist/runtime/typia-llm-sync.js

@@ -0,0 +1,63 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getOptionalNodeErrorCode, isFileNotFoundError, } from './fs-async.js';
+import { buildTypiaLlmEndpointMethodDescriptors, renderTypiaLlmModuleFromMethodDescriptors, } from './typia-llm-render.js';
+function normalizeGeneratedArtifactContent(content) {
+    return content.replace(/\r\n?/g, '\n');
+}
+async function reconcileGeneratedTypiaLlmArtifacts(artifacts, check) {
+    if (!check) {
+        for (const artifact of artifacts) {
+            await mkdir(path.dirname(artifact.filePath), {
+                recursive: true,
+            });
+            await writeFile(artifact.filePath, artifact.content, 'utf8');
+        }
+        return;
+    }
+    const issues = [];
+    for (const artifact of artifacts) {
+        try {
+            const current = normalizeGeneratedArtifactContent(await readFile(artifact.filePath, 'utf8'));
+            const expected = normalizeGeneratedArtifactContent(artifact.content);
+            if (current !== expected) {
+                issues.push(`- ${artifact.filePath} (stale)`);
+            }
+        }
+        catch (error) {
+            if (isFileNotFoundError(error)) {
+                issues.push(`- ${artifact.filePath} (missing)`);
+                continue;
+            }
+            const code = getOptionalNodeErrorCode(error);
+            issues.push(`- ${artifact.filePath} (unreadable: ${error instanceof Error ? error.message : code ?? 'unknown'})`);
+        }
+    }
+    if (issues.length > 0) {
+        throw new Error(`Generated typia.llm artifacts are missing or stale:\n${issues.join('\n')}`);
+    }
+}
+/**
+ * Writes or verifies the generated build-time `typia.llm` adapter module. The
+ * returned TypeScript source still needs to be compiled by the consuming
+ * project's Typia transformer before JSON artifacts can be read from it.
+ *
+ * @param options Generated module destination plus render options.
+ * @returns Rendered source, method descriptors, and the checked/written file path.
+ */
+export async function syncTypiaLlmAdapterModule({ check = false, generatedSourceFile, ...renderOptions }) {
+    const methodDescriptors = buildTypiaLlmEndpointMethodDescriptors(renderOptions.manifest);
+    const source = renderTypiaLlmModuleFromMethodDescriptors(renderOptions, methodDescriptors);
+    await reconcileGeneratedTypiaLlmArtifacts([
+        {
+            content: source,
+            filePath: generatedSourceFile,
+        },
+    ], check);
+    return {
+        check,
+        methodDescriptors,
+        source,
+        sourceFile: generatedSourceFile,
+    };
+}

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

@@ -0,0 +1,197 @@
+import type { ArtifactSyncExecutionOptions, EndpointManifestDefinition, EndpointManifestEndpointDefinition } from '@wp-typia/block-runtime/metadata-core';
+import type { ILlmFunction, ILlmSchema, ILlmStructuredOutput } from 'typia';
+import type { EndpointAuthIntent, EndpointWordPressAuthDefinition, OpenApiDocument } from './schema-core.js';
+/**
+ * Method-level descriptor projected from an endpoint manifest for a generated
+ * `typia.llm` controller interface.
+ */
+export interface TypiaLlmEndpointMethodDescriptor {
+    /** Normalized auth intent derived from the endpoint manifest. */
+    authIntent: EndpointAuthIntent;
+    /** Optional auth mode propagated from legacy manifest metadata. */
+    authMode?: EndpointManifestEndpointDefinition['authMode'];
+    /** Human-readable operation summary. */
+    description?: string;
+    /** Input type used by the generated controller method, or null for no input. */
+    inputTypeName: string | null;
+    /** Type names that must be imported when inputTypeName is an inline composite. */
+    inputTypeImportNames?: readonly string[];
+    /** HTTP method from the source endpoint manifest. */
+    method: EndpointManifestEndpointDefinition['method'];
+    /** Stable operation identifier used as the generated method name. */
+    operationId: string;
+    /** Output type used by the generated controller method. */
+    outputTypeName: string;
+    /** REST path from the source endpoint manifest. */
+    path: string;
+    /** Tags copied from the source endpoint manifest. */
+    tags: readonly string[];
+    /** Optional WordPress auth overlay preserved for downstream adapters. */
+    wordpressAuth?: EndpointWordPressAuthDefinition;
+}
+/**
+ * Configures the generated TypeScript module that asks `typia.llm` to derive
+ * function-calling and structured-output artifacts from canonical contracts.
+ */
+export interface RenderTypiaLlmModuleOptions {
+    /** Export name for the generated `typia.llm.application<...>()` value. */
+    applicationExportName: string;
+    /** Generated controller interface name. */
+    interfaceName: string;
+    /** Endpoint manifest that owns REST operation metadata and source type names. */
+    manifest: EndpointManifestDefinition;
+    /** Export name for the generated `typia.llm.structuredOutput<...>()` value. */
+    structuredOutputExportName: string;
+    /** TypeScript output type used for structured-output projection. */
+    structuredOutputTypeName: string;
+    /** Import path from the generated module to the canonical TypeScript contracts. */
+    typesImportPath: string;
+}
+/**
+ * Configures writing or checking the generated `typia.llm` adapter module.
+ */
+export interface SyncTypiaLlmAdapterModuleOptions extends ArtifactSyncExecutionOptions, RenderTypiaLlmModuleOptions {
+    /** Destination path for the generated TypeScript adapter module. */
+    generatedSourceFile: string;
+}
+/**
+ * Describes the generated adapter module and where it was written or checked.
+ */
+export interface SyncTypiaLlmAdapterModuleResult {
+    /** True when the source file was only verified, false when it was written. */
+    check: boolean;
+    /** Generated endpoint method descriptors used by the module renderer. */
+    methodDescriptors: TypiaLlmEndpointMethodDescriptor[];
+    /** Rendered TypeScript module source. */
+    source: string;
+    /** Destination path for the generated TypeScript adapter module. */
+    sourceFile: string;
+}
+/**
+ * Function schema shape projected from a compiled `typia.llm.application(...)`
+ * result.
+ */
+export interface TypiaLlmFunctionLike extends Pick<ILlmFunction, 'description' | 'name' | 'output' | 'parameters'> {
+    /** Function description generated by `typia.llm`. */
+    description?: string;
+    /** Function name generated by `typia.llm`. */
+    name: string;
+    /** Optional output schema generated by `typia.llm`. */
+    output?: ILlmSchema.IParameters;
+    /** Function parameter schema generated by `typia.llm`. */
+    parameters: ILlmSchema.IParameters;
+    /** Optional tags generated by `typia.llm`. */
+    tags?: readonly string[];
+}
+/**
+ * Application shape projected from a compiled `typia.llm.application(...)`
+ * result.
+ */
+export interface TypiaLlmApplicationLike {
+    /** Function schemas generated by `typia.llm`. */
+    functions: readonly TypiaLlmFunctionLike[];
+}
+/**
+ * Structured-output shape projected from a compiled
+ * `typia.llm.structuredOutput(...)` result.
+ */
+export interface TypiaLlmStructuredOutputLike extends Pick<ILlmStructuredOutput, 'parameters'> {
+    /** Structured output parameters generated by `typia.llm`. */
+    parameters: ILlmStructuredOutput['parameters'];
+}
+/**
+ * JSON-friendly function artifact for downstream adapter consumers.
+ */
+export interface ProjectedTypiaLlmFunctionArtifact {
+    /** Function description generated by `typia.llm`. */
+    description?: string;
+    /** Function name generated by `typia.llm`. */
+    name: string;
+    /** Optional output schema generated by `typia.llm`. */
+    output?: ILlmSchema.IParameters;
+    /** Function parameter schema generated by `typia.llm`. */
+    parameters: ILlmSchema.IParameters;
+    /** Optional tags generated by `typia.llm`. */
+    tags?: string[];
+}
+/**
+ * JSON-friendly application artifact for downstream adapter consumers.
+ */
+export interface ProjectedTypiaLlmApplicationArtifact {
+    /** Function-calling artifacts generated by `typia.llm`. */
+    functions: ProjectedTypiaLlmFunctionArtifact[];
+    /** Source metadata that keeps the artifact tied to canonical contracts. */
+    generatedFrom: {
+        baselineOpenApiPath?: string;
+        blockSlug: string;
+        manifestSource: 'endpoint-manifest+typescript';
+    };
+}
+/**
+ * JSON-friendly structured-output artifact for downstream adapter consumers.
+ */
+export interface ProjectedTypiaLlmStructuredOutputArtifact {
+    /** Source metadata that keeps the artifact tied to canonical contracts. */
+    generatedFrom: {
+        aiSchemaPath?: string;
+        blockSlug: string;
+        outputTypeName: string;
+    };
+    /** Structured output parameters generated by `typia.llm`. */
+    parameters: ILlmStructuredOutput['parameters'];
+}
+/**
+ * Configures optional OpenAPI-backed constraint restoration for projected
+ * `typia.llm` function artifacts.
+ */
+export interface ProjectTypiaLlmOpenApiProjectionOptions {
+    /** Canonical endpoint-aware OpenAPI document for the projected contracts. */
+    openApiDocument: OpenApiDocument;
+    /** Optional override for resolving one function schema to an operation id. */
+    resolveOperationId?: (functionSchema: TypiaLlmFunctionLike, functionArtifact: ProjectedTypiaLlmFunctionArtifact) => string;
+}
+/**
+ * Configures projection of a compiled `typia.llm.application(...)` result into
+ * the JSON-friendly adapter artifact.
+ */
+export interface ProjectTypiaLlmApplicationArtifactOptions {
+    /** Compiled application value produced by `typia.llm.application(...)`. */
+    application: TypiaLlmApplicationLike;
+    /** Source metadata for the generated JSON artifact. */
+    generatedFrom: ProjectedTypiaLlmApplicationArtifact['generatedFrom'];
+    /** Optional OpenAPI projection that restores canonical schema constraints. */
+    openApiProjection?: ProjectTypiaLlmOpenApiProjectionOptions;
+    /** Optional hook for adapter-specific function schema normalization. */
+    transformFunction?: (functionArtifact: ProjectedTypiaLlmFunctionArtifact, functionSchema: TypiaLlmFunctionLike) => ProjectedTypiaLlmFunctionArtifact;
+}
+/**
+ * Configures direct OpenAPI-backed constraint restoration for one projected
+ * function artifact.
+ */
+export interface ApplyOpenApiConstraintsToTypiaLlmFunctionArtifactOptions {
+    /** Projected function artifact to enrich with canonical constraints. */
+    functionArtifact: ProjectedTypiaLlmFunctionArtifact;
+    /** Canonical endpoint-aware OpenAPI document. */
+    openApiDocument: OpenApiDocument;
+    /** Operation id that owns the request/response contract for this function. */
+    operationId: string;
+}
+/**
+ * Configures projection of a compiled `typia.llm.structuredOutput(...)` result
+ * into the JSON-friendly adapter artifact.
+ */
+export interface ProjectTypiaLlmStructuredOutputArtifactOptions {
+    /** Source metadata for the generated JSON artifact. */
+    generatedFrom: ProjectedTypiaLlmStructuredOutputArtifact['generatedFrom'];
+    /** Compiled structured-output value produced by `typia.llm.structuredOutput(...)`. */
+    structuredOutput: TypiaLlmStructuredOutputLike;
+}
+/**
+ * Generated Typia LLM artifact payload and destination.
+ */
+export type GeneratedTypiaLlmArtifactFile = {
+    /** File contents to write or compare. */
+    content: string;
+    /** Destination path for the generated artifact file. */
+    filePath: string;
+};

package/dist/runtime/typia-llm-types.js

@@ -0,0 +1 @@
+export {};