@wp-typia/project-tools 0.22.1 → 0.22.3

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

@@ -0,0 +1,21 @@
+import type { ScaffoldCompatibilityPolicy } from "./scaffold-compatibility.js";
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Inputs required to scaffold a generated AI feature into a workspace.
+ */
+export interface ScaffoldAiFeatureWorkspaceOptions {
+    /** Kebab-case feature slug used for file paths and route ids. */
+    aiFeatureSlug: string;
+    /** Compatibility metadata applied to the generated workspace bootstrap. */
+    compatibilityPolicy: ScaffoldCompatibilityPolicy;
+    /** WordPress REST namespace used for generated feature routes. */
+    namespace: string;
+    /** Resolved workspace metadata and filesystem paths for the target project. */
+    workspace: WorkspaceProject;
+}
+/**
+ * Write generated AI feature sources and patch shared workspace anchors.
+ */
+export declare function scaffoldAiFeatureWorkspace({ aiFeatureSlug, compatibilityPolicy, namespace, workspace, }: ScaffoldAiFeatureWorkspaceOptions): Promise<{
+    warnings: string[];
+}>;

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

@@ -0,0 +1,91 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { ensureBlockConfigCanAddRestManifests } from "./cli-add-block-legacy-validator.js";
+import { buildAiFeatureConfigEntry, buildAiFeatureDataSource, buildAiFeatureSyncScriptSource, buildAiFeatureTypesSource, buildAiFeatureValidatorsSource, buildAiFeatureApiSource, } from "./cli-add-workspace-ai-source-emitters.js";
+import { ensureAiFeatureBootstrapAnchors, ensureAiFeaturePackageScripts, ensureAiFeatureSyncProjectAnchors, ensureAiFeatureSyncRestAnchors, } from "./cli-add-workspace-ai-anchors.js";
+import { buildAiFeaturePhpSource } from "./cli-add-workspace-ai-templates.js";
+import { appendWorkspaceInventoryEntries } from "./workspace-inventory.js";
+import { getWorkspaceBootstrapPath, patchFile, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { updatePluginHeaderCompatibility } from "./scaffold-compatibility.js";
+import { toPascalCase, toTitleCase } from "./string-case.js";
+import { syncAiFeatureRestArtifacts, syncAiFeatureSchemaArtifact, } from "./ai-feature-artifacts.js";
+/**
+ * Write generated AI feature sources and patch shared workspace anchors.
+ */
+export async function scaffoldAiFeatureWorkspace({ aiFeatureSlug, compatibilityPolicy, namespace, workspace, }) {
+    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    const packageJsonPath = path.join(workspace.projectDir, "package.json");
+    const syncAiScriptPath = path.join(workspace.projectDir, "scripts", "sync-ai-features.ts");
+    const syncProjectScriptPath = path.join(workspace.projectDir, "scripts", "sync-project.ts");
+    const syncRestScriptPath = path.join(workspace.projectDir, "scripts", "sync-rest-contracts.ts");
+    const aiFeatureDir = path.join(workspace.projectDir, "src", "ai-features", aiFeatureSlug);
+    const typesFilePath = path.join(aiFeatureDir, "api-types.ts");
+    const validatorsFilePath = path.join(aiFeatureDir, "api-validators.ts");
+    const apiFilePath = path.join(aiFeatureDir, "api.ts");
+    const dataFilePath = path.join(aiFeatureDir, "data.ts");
+    const phpFilePath = path.join(workspace.projectDir, "inc", "ai-features", `${aiFeatureSlug}.php`);
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([
+            blockConfigPath,
+            bootstrapPath,
+            packageJsonPath,
+            syncAiScriptPath,
+            syncProjectScriptPath,
+            syncRestScriptPath,
+        ]),
+        snapshotDirs: [],
+        targetPaths: [aiFeatureDir, phpFilePath, syncAiScriptPath],
+    };
+    try {
+        await fsp.mkdir(aiFeatureDir, { recursive: true });
+        await fsp.mkdir(path.dirname(phpFilePath), { recursive: true });
+        await ensureAiFeatureBootstrapAnchors(workspace);
+        await patchFile(bootstrapPath, (source) => updatePluginHeaderCompatibility(source, compatibilityPolicy));
+        const packageScriptChanges = await ensureAiFeaturePackageScripts(workspace);
+        await ensureAiFeatureSyncProjectAnchors(workspace);
+        await ensureAiFeatureSyncRestAnchors(workspace);
+        await fsp.writeFile(syncAiScriptPath, buildAiFeatureSyncScriptSource(), "utf8");
+        await fsp.writeFile(typesFilePath, buildAiFeatureTypesSource(aiFeatureSlug), "utf8");
+        await fsp.writeFile(validatorsFilePath, buildAiFeatureValidatorsSource(aiFeatureSlug), "utf8");
+        await fsp.writeFile(apiFilePath, buildAiFeatureApiSource(aiFeatureSlug), "utf8");
+        await fsp.writeFile(dataFilePath, buildAiFeatureDataSource(aiFeatureSlug), "utf8");
+        await fsp.writeFile(phpFilePath, buildAiFeaturePhpSource(aiFeatureSlug, namespace, workspace.workspace.phpPrefix, workspace.workspace.textDomain), "utf8");
+        const pascalCase = toPascalCase(aiFeatureSlug);
+        await syncAiFeatureRestArtifacts({
+            clientFile: `src/ai-features/${aiFeatureSlug}/api-client.ts`,
+            outputDir: path.join("src", "ai-features", aiFeatureSlug),
+            projectDir: workspace.projectDir,
+            typesFile: `src/ai-features/${aiFeatureSlug}/api-types.ts`,
+            validatorsFile: `src/ai-features/${aiFeatureSlug}/api-validators.ts`,
+            variables: {
+                namespace,
+                pascalCase,
+                slugKebabCase: aiFeatureSlug,
+                title: toTitleCase(aiFeatureSlug),
+            },
+        });
+        await syncAiFeatureSchemaArtifact({
+            aiSchemaFile: `src/ai-features/${aiFeatureSlug}/ai-schemas/feature-result.ai.schema.json`,
+            outputDir: path.join("src", "ai-features", aiFeatureSlug),
+            projectDir: workspace.projectDir,
+        });
+        await appendWorkspaceInventoryEntries(workspace.projectDir, {
+            aiFeatureEntries: [
+                buildAiFeatureConfigEntry(aiFeatureSlug, namespace),
+            ],
+            transformSource: ensureBlockConfigCanAddRestManifests,
+        });
+        return {
+            warnings: packageScriptChanges.addedProjectToolsDependency
+                ? [
+                    "Added `@wp-typia/project-tools` to devDependencies for `sync-ai`. If this workspace was already installed, rerun your package manager install command before the first `wp-typia sync ai`.",
+                ]
+                : [],
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}

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

@@ -1,6 +1,6 @@
 import { 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 { OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY, createScaffoldCompatibilityConfig, renderScaffoldCompatibilityConfig, resolveScaffoldCompatibilityPolicy, } from "./scaffold-compatibility.js";
 import { toPascalCase, toTitleCase } from "./string-case.js";
 function indentMultiline(source, prefix) {
     return source
@@ -79,6 +79,45 @@ export interface ${pascalCase}AiFeatureResponse {
 \tresult: ${pascalCase}AiFeatureResult;
 \ttelemetry: ${pascalCase}AiFeatureTelemetry;
 }
+
+export type ${pascalCase}AiFeatureSupportProbeMode = 'request-time';
+
+export type ${pascalCase}AiFeatureUnavailableErrorCode =
+\t'ai_client_unavailable';
+
+export type ${pascalCase}AiFeatureUnavailableReasonCode =
+\t| 'missing-wordpress-ai-client'
+\t| 'request-time-support-probe';
+
+export interface ${pascalCase}AiFeatureSupportReason {
+\tcode: ${pascalCase}AiFeatureUnavailableReasonCode;
+\tlabel: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tmessage: string & tags.MinLength< 1 > & tags.MaxLength< 4000 >;
+}
+
+export interface ${pascalCase}AiFeatureSupportMetadata {
+\tfeatureLabel: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tfeatureSlug: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tcompatibility: {
+\t\thardMinimums: {
+\t\t\tphp?: string;
+\t\t\twordpress?: string;
+\t\t};
+\t\tmode: 'baseline' | 'optional' | 'required';
+\t\toptionalFeatureIds: string[];
+\t\toptionalFeatures: string[];
+\t\trequiredFeatureIds: string[];
+\t\trequiredFeatures: string[];
+\t\truntimeGates: string[];
+\t};
+\tsupportProbe: {
+\t\tendpointMethod: 'POST';
+\t\tendpointPath: string & tags.MinLength< 1 > & tags.MaxLength< 200 >;
+\t\tmode: ${pascalCase}AiFeatureSupportProbeMode;
+\t\tunavailableErrorCode: ${pascalCase}AiFeatureUnavailableErrorCode;
+\t};
+\tunavailableReasons: ${pascalCase}AiFeatureSupportReason[];
+}
 `;
 }
 /**
@@ -120,6 +159,8 @@ export const apiValidators = {
  */
 export function buildAiFeatureApiSource(aiFeatureSlug) {
     const pascalCase = toPascalCase(aiFeatureSlug);
+    const compatibility = createScaffoldCompatibilityConfig(resolveScaffoldCompatibilityPolicy(OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY));
+    const title = toTitleCase(aiFeatureSlug);
     return `import {
 \tcallEndpoint,
 \tresolveRestRouteUrl,
@@ -127,6 +168,7 @@ export function buildAiFeatureApiSource(aiFeatureSlug) {
 
 import type {
 \t${pascalCase}AiFeatureRequest,
+\t${pascalCase}AiFeatureSupportMetadata,
 } from './api-types';
 import {
 \trun${pascalCase}AiFeatureEndpoint,
@@ -153,6 +195,14 @@ function resolveRestNonce( fallback?: string ): string | undefined {
 \t\t: undefined;
 }
 
+function isPlainObject( value: unknown ): value is Record< string, unknown > {
+\treturn (
+\t\t!! value &&
+\t\ttypeof value === 'object' &&
+\t\t! Array.isArray( value )
+\t);
+}
+
 export const aiFeatureRunEndpoint = {
 \t...run${pascalCase}AiFeatureEndpoint,
 \tbuildRequestOptions: () => {
@@ -168,6 +218,63 @@ export const aiFeatureRunEndpoint = {
 \t},
 };
 
+export const aiFeatureSupportMetadata = {
+\tcompatibility: ${JSON.stringify(compatibility, null, "\t")},
+\tfeatureLabel: ${quoteTsString(title)},
+\tfeatureSlug: ${quoteTsString(aiFeatureSlug)},
+\tsupportProbe: {
+\t\tendpointMethod: 'POST',
+\t\tendpointPath: aiFeatureRunEndpoint.path,
+\t\tmode: 'request-time',
+\t\tunavailableErrorCode: 'ai_client_unavailable',
+\t},
+\tunavailableReasons: [
+\t\t{
+\t\t\tcode: 'missing-wordpress-ai-client',
+\t\t\tlabel: 'WordPress AI Client unavailable',
+\t\t\tmessage:
+\t\t\t\t'This AI feature stays disabled until the WordPress AI Client is available on the site.',
+\t\t},
+\t\t{
+\t\t\tcode: 'request-time-support-probe',
+\t\t\tlabel: 'Support is checked at request time',
+\t\t\tmessage:
+\t\t\t\t'Support is verified when the feature runs, so editor and admin UIs should degrade gracefully when the site rejects the request.',
+\t\t},
+\t],
+} satisfies ${pascalCase}AiFeatureSupportMetadata;
+
+export function getAiFeatureSupportHintLines() {
+\treturn aiFeatureSupportMetadata.unavailableReasons.map(
+\t\t( reason ) => reason.message
+\t);
+}
+
+export function isAiFeatureSupportUnavailableError( error: unknown ) {
+\tif ( ! isPlainObject( error ) ) {
+\t\treturn false;
+\t}
+
+\tconst data = isPlainObject( error.data ) ? error.data : undefined;
+\treturn (
+\t\terror.code === aiFeatureSupportMetadata.supportProbe.unavailableErrorCode ||
+\t\tdata?.status === 501
+\t);
+}
+
+export function resolveAiFeatureUnavailableMessage( error: unknown ) {
+\tif (
+\t\tisPlainObject( error ) &&
+\t\ttypeof error.message === 'string' &&
+\t\terror.message.length > 0
+\t) {
+\t\treturn error.message;
+\t}
+
+\treturn aiFeatureSupportMetadata.unavailableReasons[ 0 ]?.message ??
+\t\t'This AI feature is currently unavailable.';
+}
+
 export function runAiFeature( request: ${pascalCase}AiFeatureRequest ) {
 \treturn callEndpoint( aiFeatureRunEndpoint, request );
 }
@@ -189,6 +296,10 @@ import type {
 } from './api-types';
 import {
 \taiFeatureRunEndpoint,
+\taiFeatureSupportMetadata,
+\tgetAiFeatureSupportHintLines,
+\tisAiFeatureSupportUnavailableError,
+\tresolveAiFeatureUnavailableMessage,
 } from './api';
 
 export type UseRun${pascalCase}AiFeatureMutationOptions =
@@ -203,6 +314,13 @@ export function useRun${pascalCase}AiFeatureMutation(
 ) {
 \treturn useEndpointMutation( aiFeatureRunEndpoint, options );
 }
+
+export {
+\taiFeatureSupportMetadata,
+\tgetAiFeatureSupportHintLines,
+\tisAiFeatureSupportUnavailableError,
+\tresolveAiFeatureUnavailableMessage,
+};
 `;
 }
 /**

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

@@ -0,0 +1,4 @@
+/**
+ * Build the generated PHP controller and hook surface for a workspace AI feature.
+ */
+export declare function buildAiFeaturePhpSource(aiFeatureSlug: string, namespace: string, phpPrefix: string, textDomain: string): string;