@wp-typia/project-tools 0.19.3 → 0.20.0

package/dist/runtime/cli-add-workspace-ai-anchors.d.ts

@@ -0,0 +1,22 @@
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Patch the workspace bootstrap file so it loads generated AI feature PHP modules.
+ */
+export declare function ensureAiFeatureBootstrapAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Patch `package.json` with `sync-ai` plus the project-tools dependency used by generated AI sync scripts.
+ */
+export declare function ensureAiFeaturePackageScripts(workspace: WorkspaceProject): Promise<{
+    /** True when `@wp-typia/project-tools` was newly added to `devDependencies`. */
+    addedProjectToolsDependency: boolean;
+    /** True when the workspace did not already define a `sync-ai` script. */
+    addedSyncAiScript: boolean;
+}>;
+/**
+ * Patch `scripts/sync-project.ts` after package scripts so generated workspaces invoke `sync-ai` when present.
+ */
+export declare function ensureAiFeatureSyncProjectAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Patch `scripts/sync-rest-contracts.ts` after sync-project wiring so AI feature REST artifacts join the split sync flow.
+ */
+export declare function ensureAiFeatureSyncRestAnchors(workspace: WorkspaceProject): Promise<void>;

package/dist/runtime/cli-add-workspace-ai-anchors.js

@@ -0,0 +1,277 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { getPackageVersions } from "./package-versions.js";
+import { getWorkspaceBootstrapPath, patchFile, } from "./cli-add-shared.js";
+const AI_FEATURE_SERVER_GLOB = "/inc/ai-features/*.php";
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+/**
+ * Patch the workspace bootstrap file so it loads generated AI feature PHP modules.
+ */
+export async function ensureAiFeatureBootstrapAnchors(workspace) {
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    await patchFile(bootstrapPath, (source) => {
+        let nextSource = source;
+        const registerFunctionName = `${workspace.workspace.phpPrefix}_register_ai_features`;
+        const registerHook = `add_action( 'init', '${registerFunctionName}', 20 );`;
+        const registerFunction = `
+
+function ${registerFunctionName}() {
+\tforeach ( glob( __DIR__ . '${AI_FEATURE_SERVER_GLOB}' ) ?: array() as $ai_feature_module ) {
+\t\trequire_once $ai_feature_module;
+\t}
+}
+`;
+        const insertionAnchors = [
+            /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
+            /\?>\s*$/u,
+        ];
+        const hasPhpFunctionDefinition = (functionName) => new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\(`, "u").test(nextSource);
+        const insertPhpSnippet = (snippet) => {
+            for (const anchor of insertionAnchors) {
+                const candidate = nextSource.replace(anchor, (match) => `${snippet}\n${match}`);
+                if (candidate !== nextSource) {
+                    nextSource = candidate;
+                    return;
+                }
+            }
+            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
+        };
+        const appendPhpSnippet = (snippet) => {
+            const closingTagPattern = /\?>\s*$/u;
+            if (closingTagPattern.test(nextSource)) {
+                nextSource = nextSource.replace(closingTagPattern, `${snippet}\n?>`);
+                return;
+            }
+            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
+        };
+        if (!hasPhpFunctionDefinition(registerFunctionName)) {
+            insertPhpSnippet(registerFunction);
+        }
+        else if (!nextSource.includes(AI_FEATURE_SERVER_GLOB)) {
+            throw new Error([
+                `Unable to patch ${path.basename(bootstrapPath)} in ensureAiFeatureBootstrapAnchors.`,
+                `The existing ${registerFunctionName}() definition does not include ${AI_FEATURE_SERVER_GLOB}.`,
+                "Restore the generated bootstrap shape or wire the AI feature loader manually before retrying.",
+            ].join(" "));
+        }
+        if (!nextSource.includes(registerHook)) {
+            appendPhpSnippet(registerHook);
+        }
+        return nextSource;
+    });
+}
+/**
+ * Patch `package.json` with `sync-ai` plus the project-tools dependency used by generated AI sync scripts.
+ */
+export async function ensureAiFeaturePackageScripts(workspace) {
+    const packageJsonPath = path.join(workspace.projectDir, "package.json");
+    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const nextScripts = {
+        ...(packageJson.scripts ?? {}),
+        "sync-ai": packageJson.scripts?.["sync-ai"] ?? "tsx scripts/sync-ai-features.ts",
+    };
+    const nextDevDependencies = {
+        ...(packageJson.devDependencies ?? {}),
+        "@wp-typia/project-tools": packageJson.devDependencies?.["@wp-typia/project-tools"] ??
+            getPackageVersions().projectToolsPackageVersion,
+    };
+    const addedSyncAiScript = packageJson.scripts?.["sync-ai"] === undefined;
+    const addedProjectToolsDependency = packageJson.devDependencies?.["@wp-typia/project-tools"] === undefined;
+    if (JSON.stringify(nextScripts) === JSON.stringify(packageJson.scripts ?? {}) &&
+        JSON.stringify(nextDevDependencies) ===
+            JSON.stringify(packageJson.devDependencies ?? {})) {
+        return {
+            addedProjectToolsDependency: false,
+            addedSyncAiScript: false,
+        };
+    }
+    packageJson.scripts = nextScripts;
+    packageJson.devDependencies = nextDevDependencies;
+    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
+    return {
+        addedProjectToolsDependency,
+        addedSyncAiScript,
+    };
+}
+/**
+ * Patch `scripts/sync-project.ts` after package scripts so generated workspaces invoke `sync-ai` when present.
+ */
+export async function ensureAiFeatureSyncProjectAnchors(workspace) {
+    const syncProjectScriptPath = path.join(workspace.projectDir, "scripts", "sync-project.ts");
+    await patchFile(syncProjectScriptPath, (source) => {
+        let nextSource = source;
+        const syncRestConst = "const syncRestScriptPath = path.join( 'scripts', 'sync-rest-contracts.ts' );";
+        const syncAiConst = "const syncAiScriptPath = path.join( 'scripts', 'sync-ai-features.ts' );";
+        const syncRestBlockPattern = /if \( fs\.existsSync\( path\.resolve\( process\.cwd\(\), syncRestScriptPath \) \) \) \{\n\s*runSyncScript\( syncRestScriptPath, options \);\n\s*\}/u;
+        const syncAiBlock = [
+            "if ( fs.existsSync( path.resolve( process.cwd(), syncAiScriptPath ) ) ) {",
+            "\trunSyncScript( syncAiScriptPath, options );",
+            "}",
+        ].join("\n");
+        if (!nextSource.includes(syncAiConst)) {
+            if (!nextSource.includes(syncRestConst)) {
+                throw new Error([
+                    `ensureAiFeatureSyncProjectAnchors could not patch ${path.basename(syncProjectScriptPath)}.`,
+                    "Missing the expected sync-rest script constant in scripts/sync-project.ts.",
+                    "Restore the generated template or wire sync-ai manually before retrying.",
+                ].join(" "));
+            }
+            nextSource = nextSource.replace(syncRestConst, `${syncRestConst}\n${syncAiConst}`);
+        }
+        if (!nextSource.includes("runSyncScript( syncAiScriptPath, options );")) {
+            if (!syncRestBlockPattern.test(nextSource)) {
+                throw new Error([
+                    `ensureAiFeatureSyncProjectAnchors could not patch ${path.basename(syncProjectScriptPath)}.`,
+                    "Missing the expected sync-rest invocation block in scripts/sync-project.ts.",
+                    "Restore the generated template or wire sync-ai manually before retrying.",
+                ].join(" "));
+            }
+            nextSource = nextSource.replace(syncRestBlockPattern, (match) => `${match}\n\n${syncAiBlock}`);
+        }
+        return nextSource;
+    });
+}
+function assertSyncRestAnchor(nextSource, target, anchorDescription, hasAnchor, syncRestScriptPath) {
+    if (!nextSource.includes(target) && !hasAnchor) {
+        throw new Error([
+            `ensureAiFeatureSyncRestAnchors could not patch ${path.basename(syncRestScriptPath)}.`,
+            `Missing expected ${anchorDescription} anchor in scripts/sync-rest-contracts.ts.`,
+            "Restore the generated template or add the AI feature wiring manually before retrying.",
+        ].join(" "));
+    }
+}
+function replaceRequiredSyncRestSource(nextSource, target, anchor, replacement, anchorDescription, syncRestScriptPath) {
+    if (nextSource.includes(target)) {
+        return nextSource;
+    }
+    const hasAnchor = typeof anchor === "string" ? nextSource.includes(anchor) : anchor.test(nextSource);
+    assertSyncRestAnchor(nextSource, target, anchorDescription, hasAnchor, syncRestScriptPath);
+    return nextSource.replace(anchor, replacement);
+}
+/**
+ * Patch `scripts/sync-rest-contracts.ts` after sync-project wiring so AI feature REST artifacts join the split sync flow.
+ */
+export async function ensureAiFeatureSyncRestAnchors(workspace) {
+    const syncRestScriptPath = path.join(workspace.projectDir, "scripts", "sync-rest-contracts.ts");
+    await patchFile(syncRestScriptPath, (source) => {
+        let nextSource = source;
+        const importAnchor = [
+            "import {",
+            "\tBLOCKS,",
+            "\tREST_RESOURCES,",
+            "\ttype WorkspaceBlockConfig,",
+            "\ttype WorkspaceRestResourceConfig,",
+            "} from './block-config';",
+        ].join("\n");
+        const helperInsertionAnchor = "async function assertTypeArtifactsCurrent";
+        const restResourcesAnchor = "const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );";
+        const noResourcesPattern = /if \( restBlocks.length === 0 && restResources.length === 0 \) \{[\s\S]*?\n\t\treturn;\n\t\}/u;
+        const consoleLogPattern = /\n\tconsole\.log\(\n\t\toptions\.check/u;
+        nextSource = replaceRequiredSyncRestSource(nextSource, "AI_FEATURES", importAnchor, [
+            "import {",
+            "\tAI_FEATURES,",
+            "\tBLOCKS,",
+            "\tREST_RESOURCES,",
+            "\ttype WorkspaceAiFeatureConfig,",
+            "\ttype WorkspaceBlockConfig,",
+            "\ttype WorkspaceRestResourceConfig,",
+            "} from './block-config';",
+        ].join("\n"), "workspace inventory import", syncRestScriptPath);
+        nextSource = replaceRequiredSyncRestSource(nextSource, "function isWorkspaceAiFeature(", helperInsertionAnchor, [
+            "function isWorkspaceAiFeature(",
+            "\tfeature: WorkspaceAiFeatureConfig",
+            "): feature is WorkspaceAiFeatureConfig & {",
+            "\taiSchemaFile: string;",
+            "\tclientFile: string;",
+            "\topenApiFile: string;",
+            "\trestManifest: NonNullable< WorkspaceAiFeatureConfig[ 'restManifest' ] >;",
+            "\ttypesFile: string;",
+            "\tvalidatorsFile: string;",
+            "} {",
+            "\treturn (",
+            "\t\ttypeof feature.aiSchemaFile === 'string' &&",
+            "\t\ttypeof feature.clientFile === 'string' &&",
+            "\t\ttypeof feature.openApiFile === 'string' &&",
+            "\t\ttypeof feature.typesFile === 'string' &&",
+            "\t\ttypeof feature.validatorsFile === 'string' &&",
+            "\t\ttypeof feature.restManifest === 'object' &&",
+            "\t\tfeature.restManifest !== null",
+            "\t);",
+            "}",
+            "",
+            "async function assertTypeArtifactsCurrent",
+        ].join("\n"), "type artifact assertion helper", syncRestScriptPath);
+        nextSource = replaceRequiredSyncRestSource(nextSource, "const aiFeatures = AI_FEATURES.filter( isWorkspaceAiFeature );", restResourcesAnchor, [
+            "const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );",
+            "const aiFeatures = AI_FEATURES.filter( isWorkspaceAiFeature );",
+        ].join("\n"), "rest resource filter", syncRestScriptPath);
+        nextSource = replaceRequiredSyncRestSource(nextSource, "restBlocks.length === 0 && restResources.length === 0 && aiFeatures.length === 0", noResourcesPattern, [
+            "if ( restBlocks.length === 0 && restResources.length === 0 && aiFeatures.length === 0 ) {",
+            "\t\tconsole.log(",
+            "\t\t\toptions.check",
+            "\t\t\t\t? 'ℹ️ No REST-enabled workspace blocks, plugin-level REST resources, or AI features are registered yet. `sync-rest --check` is already clean.'",
+            "\t\t\t\t: 'ℹ️ No REST-enabled workspace blocks, plugin-level REST resources, or AI features are registered yet.'",
+            "\t\t);",
+            "\t\treturn;",
+            "\t}",
+        ].join("\n"), "no-resources guard", syncRestScriptPath);
+        nextSource = replaceRequiredSyncRestSource(nextSource, "for ( const feature of aiFeatures ) {", consoleLogPattern, [
+            "",
+            "\tfor ( const feature of aiFeatures ) {",
+            "\t\tconst contracts = feature.restManifest.contracts;",
+            "",
+            "\t\tfor ( const [ baseName, contract ] of Object.entries( contracts ) ) {",
+            "\t\t\tawait syncTypeSchemas(",
+            "\t\t\t\t{",
+            "\t\t\t\t\tjsonSchemaFile: path.join(",
+            "\t\t\t\t\t\tpath.dirname( feature.typesFile ),",
+            "\t\t\t\t\t\t'api-schemas',",
+            "\t\t\t\t\t\t`${ baseName }.schema.json`",
+            "\t\t\t\t\t),",
+            "\t\t\t\t\topenApiFile: path.join(",
+            "\t\t\t\t\t\tpath.dirname( feature.typesFile ),",
+            "\t\t\t\t\t\t'api-schemas',",
+            "\t\t\t\t\t\t`${ baseName }.openapi.json`",
+            "\t\t\t\t\t),",
+            "\t\t\t\t\tsourceTypeName: contract.sourceTypeName,",
+            "\t\t\t\t\ttypesFile: feature.typesFile,",
+            "\t\t\t\t},",
+            "\t\t\t\t{",
+            "\t\t\t\t\tcheck: options.check,",
+            "\t\t\t\t}",
+            "\t\t\t);",
+            "\t\t}",
+            "",
+            "\t\tawait syncRestOpenApi(",
+            "\t\t\t{",
+            "\t\t\t\tmanifest: feature.restManifest,",
+            "\t\t\t\topenApiFile: feature.openApiFile,",
+            "\t\t\t\ttypesFile: feature.typesFile,",
+            "\t\t\t},",
+            "\t\t\t{",
+            "\t\t\t\tcheck: options.check,",
+            "\t\t\t}",
+            "\t\t);",
+            "",
+            "\t\tawait syncEndpointClient(",
+            "\t\t\t{",
+            "\t\t\t\tclientFile: feature.clientFile,",
+            "\t\t\t\tmanifest: feature.restManifest,",
+            "\t\t\t\ttypesFile: feature.typesFile,",
+            "\t\t\t\tvalidatorsFile: feature.validatorsFile,",
+            "\t\t\t},",
+            "\t\t\t{",
+            "\t\t\t\tcheck: options.check,",
+            "\t\t\t}",
+            "\t\t);",
+            "\t}",
+            "",
+            "\tconsole.log(",
+            "\t\toptions.check",
+        ].join("\n"), "final sync summary", syncRestScriptPath);
+        nextSource = replaceRequiredSyncRestSource(nextSource, "workspace blocks, plugin-level resources, and AI features", "workspace blocks and plugin-level resources", "workspace blocks, plugin-level resources, and AI features", "sync summary copy", syncRestScriptPath);
+        return nextSource;
+    });
+}

package/dist/runtime/cli-add-workspace-ai-source-emitters.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Convert an AI feature slug into the PascalCase identifier used by generated types.
+ */
+export declare function toPascalCaseFromAiFeatureSlug(slug: string): string;
+/**
+ * Build the workspace inventory entry written into `scripts/block-config.ts` for one AI feature.
+ */
+export declare function buildAiFeatureConfigEntry(aiFeatureSlug: string, namespace: string): string;
+/**
+ * Generate TypeScript request, response, and telemetry contracts for an AI feature scaffold.
+ */
+export declare function buildAiFeatureTypesSource(aiFeatureSlug: string): string;
+/**
+ * Generate runtime validators for the AI feature request/result/response contracts.
+ */
+export declare function buildAiFeatureValidatorsSource(aiFeatureSlug: string): string;
+/**
+ * Generate the typed client wrapper that calls the scaffolded AI feature endpoint.
+ */
+export declare function buildAiFeatureApiSource(aiFeatureSlug: string): string;
+/**
+ * Generate React endpoint-mutation hooks for the scaffolded AI feature client wrapper.
+ */
+export declare function buildAiFeatureDataSource(aiFeatureSlug: string): string;
+/**
+ * Generate the `scripts/sync-ai-features.ts` source that projects AI-safe schemas for workspace features.
+ */
+export declare function buildAiFeatureSyncScriptSource(): string;

package/dist/runtime/cli-add-workspace-ai-source-emitters.js

@@ -0,0 +1,346 @@
+import { normalizeBlockSlug, quoteTsString, } from "./cli-add-shared.js";
+import { buildAiFeatureEndpointManifest } from "./ai-feature-artifacts.js";
+import { OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY, renderScaffoldCompatibilityConfig, resolveScaffoldCompatibilityPolicy, } from "./scaffold-compatibility.js";
+import { toTitleCase } from "./string-case.js";
+/**
+ * Convert an AI feature slug into the PascalCase identifier used by generated types.
+ */
+export function toPascalCaseFromAiFeatureSlug(slug) {
+    return normalizeBlockSlug(slug)
+        .split("-")
+        .filter(Boolean)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join("");
+}
+function indentMultiline(source, prefix) {
+    return source
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+/**
+ * Build the workspace inventory entry written into `scripts/block-config.ts` for one AI feature.
+ */
+export function buildAiFeatureConfigEntry(aiFeatureSlug, namespace) {
+    const pascalCase = toPascalCaseFromAiFeatureSlug(aiFeatureSlug);
+    const title = toTitleCase(aiFeatureSlug);
+    const compatibilityPolicy = resolveScaffoldCompatibilityPolicy(OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY);
+    const manifest = buildAiFeatureEndpointManifest({
+        namespace,
+        pascalCase,
+        slugKebabCase: aiFeatureSlug,
+        title,
+    });
+    return [
+        "\t{",
+        `\t\taiSchemaFile: ${quoteTsString(`src/ai-features/${aiFeatureSlug}/ai-schemas/feature-result.ai.schema.json`)},`,
+        `\t\tapiFile: ${quoteTsString(`src/ai-features/${aiFeatureSlug}/api.ts`)},`,
+        `\t\tclientFile: ${quoteTsString(`src/ai-features/${aiFeatureSlug}/api-client.ts`)},`,
+        `\t\tcompatibility: ${renderScaffoldCompatibilityConfig(compatibilityPolicy)},`,
+        `\t\tdataFile: ${quoteTsString(`src/ai-features/${aiFeatureSlug}/data.ts`)},`,
+        `\t\tnamespace: ${quoteTsString(namespace)},`,
+        `\t\topenApiFile: ${quoteTsString(`src/ai-features/${aiFeatureSlug}/api.openapi.json`)},`,
+        `\t\tphpFile: ${quoteTsString(`inc/ai-features/${aiFeatureSlug}.php`)},`,
+        "\t\trestManifest: defineEndpointManifest(",
+        indentMultiline(JSON.stringify(manifest, null, "\t"), "\t\t\t"),
+        "\t\t),",
+        `\t\tslug: ${quoteTsString(aiFeatureSlug)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/ai-features/${aiFeatureSlug}/api-types.ts`)},`,
+        `\t\tvalidatorsFile: ${quoteTsString(`src/ai-features/${aiFeatureSlug}/api-validators.ts`)},`,
+        "\t},",
+    ].join("\n");
+}
+/**
+ * Generate TypeScript request, response, and telemetry contracts for an AI feature scaffold.
+ */
+export function buildAiFeatureTypesSource(aiFeatureSlug) {
+    const pascalCase = toPascalCaseFromAiFeatureSlug(aiFeatureSlug);
+    return `import { tags } from 'typia';
+
+export interface ${pascalCase}AiFeatureRequest {
+\tbrief: string & tags.MinLength< 1 > & tags.MaxLength< 4000 >;
+\tcontext?: string & tags.MaxLength< 4000 >;
+}
+
+export interface ${pascalCase}AiFeatureResult {
+\ttitle: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tsummary: string & tags.MinLength< 1 > & tags.MaxLength< 2000 >;
+\tconfidence?: number & tags.Minimum< 0 > & tags.Maximum< 1 >;
+}
+
+export interface ${pascalCase}AiFeatureTokenUsage {
+\tcompletionTokens: number & tags.Type< 'uint32' >;
+\tpromptTokens: number & tags.Type< 'uint32' >;
+\ttotalTokens: number & tags.Type< 'uint32' >;
+\tthoughtTokens?: number & tags.Type< 'uint32' >;
+}
+
+export interface ${pascalCase}AiFeatureTelemetry {
+\tmodelId: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tmodelName: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tproviderId: string & tags.MinLength< 1 > & tags.MaxLength< 80 >;
+\tproviderName: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tproviderType: 'client' | 'cloud' | 'server';
+\tresultId: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\ttokenUsage: ${pascalCase}AiFeatureTokenUsage;
+}
+
+export interface ${pascalCase}AiFeatureResponse {
+\tresult: ${pascalCase}AiFeatureResult;
+\ttelemetry: ${pascalCase}AiFeatureTelemetry;
+}
+`;
+}
+/**
+ * Generate runtime validators for the AI feature request/result/response contracts.
+ */
+export function buildAiFeatureValidatorsSource(aiFeatureSlug) {
+    const pascalCase = toPascalCaseFromAiFeatureSlug(aiFeatureSlug);
+    return `import typia from 'typia';
+
+import { toValidationResult } from '@wp-typia/rest';
+import type {
+\t${pascalCase}AiFeatureRequest,
+\t${pascalCase}AiFeatureResponse,
+\t${pascalCase}AiFeatureResult,
+} from './api-types';
+
+const validateFeatureRequest = typia.createValidate< ${pascalCase}AiFeatureRequest >();
+const validateFeatureResult = typia.createValidate< ${pascalCase}AiFeatureResult >();
+const validateFeatureResponse = typia.createValidate< ${pascalCase}AiFeatureResponse >();
+
+export const apiValidators = {
+\tfeatureRequest: ( input: unknown ) =>
+\t\ttoValidationResult< ${pascalCase}AiFeatureRequest >(
+\t\t\tvalidateFeatureRequest( input )
+\t\t),
+\tfeatureResult: ( input: unknown ) =>
+\t\ttoValidationResult< ${pascalCase}AiFeatureResult >(
+\t\t\tvalidateFeatureResult( input )
+\t\t),
+\tfeatureResponse: ( input: unknown ) =>
+\t\ttoValidationResult< ${pascalCase}AiFeatureResponse >(
+\t\t\tvalidateFeatureResponse( input )
+\t\t),
+};
+`;
+}
+/**
+ * Generate the typed client wrapper that calls the scaffolded AI feature endpoint.
+ */
+export function buildAiFeatureApiSource(aiFeatureSlug) {
+    const pascalCase = toPascalCaseFromAiFeatureSlug(aiFeatureSlug);
+    return `import {
+\tcallEndpoint,
+\tresolveRestRouteUrl,
+} from '@wp-typia/rest';
+
+import type {
+\t${pascalCase}AiFeatureRequest,
+} from './api-types';
+import {
+\trun${pascalCase}AiFeatureEndpoint,
+} from './api-client';
+
+function resolveRestNonce( fallback?: string ): string | undefined {
+\tif ( typeof fallback === 'string' && fallback.length > 0 ) {
+\t\treturn fallback;
+\t}
+
+\tif ( typeof window === 'undefined' ) {
+\t\treturn undefined;
+\t}
+
+\tconst wpApiSettings = (
+\t\twindow as typeof window & {
+\t\t\twpApiSettings?: { nonce?: string };
+\t\t}
+\t).wpApiSettings;
+
+\treturn typeof wpApiSettings?.nonce === 'string' &&
+\t\twpApiSettings.nonce.length > 0
+\t\t? wpApiSettings.nonce
+\t\t: undefined;
+}
+
+export const aiFeatureRunEndpoint = {
+\t...run${pascalCase}AiFeatureEndpoint,
+\tbuildRequestOptions: () => {
+\t\tconst nonce = resolveRestNonce();
+\t\treturn {
+\t\t\theaders: nonce
+\t\t\t\t? {
+\t\t\t\t\t'X-WP-Nonce': nonce,
+\t\t\t\t}
+\t\t\t\t: undefined,
+\t\t\turl: resolveRestRouteUrl( run${pascalCase}AiFeatureEndpoint.path ),
+\t\t};
+\t},
+};
+
+export function runAiFeature( request: ${pascalCase}AiFeatureRequest ) {
+\treturn callEndpoint( aiFeatureRunEndpoint, request );
+}
+`;
+}
+/**
+ * Generate React endpoint-mutation hooks for the scaffolded AI feature client wrapper.
+ */
+export function buildAiFeatureDataSource(aiFeatureSlug) {
+    const pascalCase = toPascalCaseFromAiFeatureSlug(aiFeatureSlug);
+    return `import {
+\tuseEndpointMutation,
+\ttype UseEndpointMutationOptions,
+} from '@wp-typia/rest/react';
+
+import type {
+\t${pascalCase}AiFeatureRequest,
+\t${pascalCase}AiFeatureResponse,
+} from './api-types';
+import {
+\taiFeatureRunEndpoint,
+} from './api';
+
+export type UseRun${pascalCase}AiFeatureMutationOptions =
+\tUseEndpointMutationOptions<
+\t\t${pascalCase}AiFeatureRequest,
+\t\t${pascalCase}AiFeatureResponse,
+\t\tunknown
+\t>;
+
+export function useRun${pascalCase}AiFeatureMutation(
+\toptions: UseRun${pascalCase}AiFeatureMutationOptions = {}
+) {
+\treturn useEndpointMutation( aiFeatureRunEndpoint, options );
+}
+`;
+}
+/**
+ * Generate the `scripts/sync-ai-features.ts` source that projects AI-safe schemas for workspace features.
+ */
+export function buildAiFeatureSyncScriptSource() {
+    return `/* eslint-disable no-console */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { projectWordPressAiSchema } from '@wp-typia/project-tools/ai-artifacts';
+
+import {
+\tAI_FEATURES,
+\ttype WorkspaceAiFeatureConfig,
+} from './block-config';
+
+function parseCliOptions( argv: string[] ) {
+\tconst options = {
+\t\tcheck: false,
+\t};
+
+\tfor ( const argument of argv ) {
+\t\tif ( argument === '--check' ) {
+\t\t\toptions.check = true;
+\t\t\tcontinue;
+\t\t}
+
+\t\tthrow new Error( \`Unknown sync-ai flag: \${ argument }\` );
+\t}
+
+\treturn options;
+}
+
+function isWorkspaceAiFeature(
+\tfeature: WorkspaceAiFeatureConfig
+): feature is WorkspaceAiFeatureConfig & {
+\taiSchemaFile: string;
+\ttypesFile: string;
+} {
+\treturn (
+\t\ttypeof feature.aiSchemaFile === 'string' &&
+\t\ttypeof feature.typesFile === 'string'
+\t);
+}
+
+function normalizeGeneratedArtifactContent( content: string ) {
+\treturn content.replace( /\\r\\n?/g, '\\n' );
+}
+
+async function reconcileGeneratedArtifact( options: {
+\tcheck: boolean;
+\tcontent: string;
+\tfilePath: string;
+\tlabel: string;
+} ) {
+\tif ( ! options.check ) {
+\t\tawait mkdir( path.dirname( options.filePath ), {
+\t\t\trecursive: true,
+\t\t} );
+\t\tawait writeFile( options.filePath, options.content, 'utf8' );
+\t\treturn;
+\t}
+
+\tconst current = normalizeGeneratedArtifactContent(
+\t\tawait readFile( options.filePath, 'utf8' )
+\t);
+\tconst expected = normalizeGeneratedArtifactContent( options.content );
+\tif ( current !== expected ) {
+\t\tthrow new Error(
+\t\t\t\`Generated AI feature artifact is stale: \${ options.label } (\${ options.filePath }).\`
+\t\t);
+\t}
+}
+
+async function loadJsonDocument( filePath: string ) {
+\tconst decoded = JSON.parse( await readFile( filePath, 'utf8' ) ) as unknown;
+\tif ( ! decoded || typeof decoded !== 'object' || Array.isArray( decoded ) ) {
+\t\tthrow new Error( \`Expected \${ filePath } to decode to a JSON object.\` );
+\t}
+
+\treturn decoded as Parameters< typeof projectWordPressAiSchema >[ 0 ];
+}
+
+async function main() {
+\tconst options = parseCliOptions( process.argv.slice( 2 ) );
+\tconst aiFeatures = AI_FEATURES.filter( isWorkspaceAiFeature );
+\tif ( AI_FEATURES.length > 0 && aiFeatures.length === 0 ) {
+\t\tconsole.warn(
+\t\t\t'⚠️ AI_FEATURES entries exist, but none satisfied the generated sync-ai guard. Check for missing aiSchemaFile/typesFile fields in scripts/block-config.ts.'
+\t\t);
+\t}
+
+\tif ( aiFeatures.length === 0 ) {
+\t\tconsole.log(
+\t\t\toptions.check
+\t\t\t\t? 'ℹ️ No workspace AI features are registered yet. \`sync-ai --check\` is already clean.'
+\t\t\t\t: 'ℹ️ No workspace AI features are registered yet.'
+\t\t);
+\t\treturn;
+\t}
+
+\tfor ( const feature of aiFeatures ) {
+\t\tconst sourceSchemaPath = path.join(
+\t\t\tpath.dirname( feature.typesFile ),
+\t\t\t'api-schemas',
+\t\t\t'feature-result.schema.json'
+\t\t);
+\t\tconst sourceSchema = await loadJsonDocument( sourceSchemaPath );
+\t\tconst aiSchema = projectWordPressAiSchema( sourceSchema );
+\t\tawait reconcileGeneratedArtifact( {
+\t\t\tcheck: options.check,
+\t\t\tcontent: \`\${ JSON.stringify( aiSchema, null, 2 ) }\\n\`,
+\t\t\tfilePath: feature.aiSchemaFile,
+\t\t\tlabel: feature.slug,
+\t\t} );
+\t}
+
+\tconsole.log(
+\t\toptions.check
+\t\t\t? '✅ AI feature structured-output schemas are already synchronized.'
+\t\t\t: '✅ AI feature structured-output schemas were synchronized.'
+\t);
+}
+
+main().catch( ( error ) => {
+\tconsole.error( '❌ AI feature sync failed:', error );
+\tprocess.exit( 1 );
+} );
+`;
+}