@wp-typia/project-tools 0.22.9 → 0.23.0

package/dist/runtime/cli-add-workspace-rest.js

@@ -1,50 +1,68 @@
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { ensureBlockConfigCanAddRestManifests } from "./cli-add-block-legacy-validator.js";
-import { assertRestResourceDoesNotExist, assertValidGeneratedSlug, assertValidRestResourceMethods, getWorkspaceBootstrapPath, normalizeBlockSlug, resolveRestResourceNamespace, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { assertValidManualRestContractAuth, assertValidManualRestContractHttpMethod, assertRestResourceDoesNotExist, assertValidGeneratedSlug, assertValidRestResourceMethods, assertValidTypeScriptIdentifier, getWorkspaceBootstrapPath, normalizeBlockSlug, resolveGeneratedRestResourceRoutePattern, resolveManualRestContractPathPattern, resolveOptionalPhpCallbackReference, resolveOptionalPhpClassReference, resolveRestResourceNamespace, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
 import { ensureRestResourceBootstrapAnchors, ensureRestResourceSyncScriptAnchors, } from "./cli-add-workspace-rest-anchors.js";
-import { buildRestResourceApiSource, buildRestResourceConfigEntry, buildRestResourceDataSource, buildRestResourceTypesSource, buildRestResourceValidatorsSource, } from "./cli-add-workspace-rest-source-emitters.js";
+import { buildManualRestContractApiSource, buildManualRestContractConfigEntry, buildManualRestContractTypesSource, buildManualRestContractValidatorsSource, buildRestResourceApiSource, buildRestResourceConfigEntry, buildRestResourceDataSource, buildRestResourceTypesSource, buildRestResourceValidatorsSource, } from "./cli-add-workspace-rest-source-emitters.js";
 import { quotePhpString } from "./php-utils.js";
-import { syncRestResourceArtifacts } from "./rest-resource-artifacts.js";
+import { syncManualRestContractArtifacts, syncRestResourceArtifacts, } from "./rest-resource-artifacts.js";
 import { toPascalCase, toTitleCase } from "./string-case.js";
 import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
 import { resolveWorkspaceProject } from "./workspace-project.js";
-function buildRestResourceRouteRegistrations(restResourceSlug, methods, functions) {
+const MANUAL_REST_REQUEST_BODY_FIELD_NAMES = new Set(["payload", "comment"]);
+const MANUAL_REST_RESPONSE_FIELD_NAMES = new Set([
+    "id",
+    "status",
+    "message",
+    "updatedAt",
+]);
+function buildRestResourceRouteRegistrations(restResourceSlug, methods, functions, options) {
     const collectionRoutes = [];
     const itemRoutes = [];
+    const readPermissionCallback = options.permissionCallback
+        ? quotePhpString(options.permissionCallback)
+        : quotePhpString("__return_true");
+    const writePermissionCallback = options.permissionCallback
+        ? quotePhpString(options.permissionCallback)
+        : options.controllerVariableName
+            ? `array( ${options.controllerVariableName}, 'can_manage_rest_resource' )`
+            : quotePhpString(functions.canWriteFunctionName);
+    const buildRouteCallback = (functionName, methodName) => options.controllerVariableName
+        ? `array( ${options.controllerVariableName}, '${methodName}' )`
+        : quotePhpString(functionName);
     if (methods.includes("list")) {
         collectionRoutes.push(`\t\tarray(
 \t\t\t'methods'             => WP_REST_Server::READABLE,
-\t\t\t'callback'            => '${functions.listHandlerName}',
-\t\t\t'permission_callback' => '__return_true',
+\t\t\t'callback'            => ${buildRouteCallback(functions.listHandlerName, "list_items")},
+\t\t\t'permission_callback' => ${readPermissionCallback},
 \t\t)`);
     }
     if (methods.includes("create")) {
         collectionRoutes.push(`\t\tarray(
 \t\t\t'methods'             => WP_REST_Server::CREATABLE,
-\t\t\t'callback'            => '${functions.createHandlerName}',
-\t\t\t'permission_callback' => '${functions.canWriteFunctionName}',
+\t\t\t'callback'            => ${buildRouteCallback(functions.createHandlerName, "create_item")},
+\t\t\t'permission_callback' => ${writePermissionCallback},
 \t\t)`);
     }
     if (methods.includes("read")) {
         itemRoutes.push(`\t\tarray(
 \t\t\t'methods'             => WP_REST_Server::READABLE,
-\t\t\t'callback'            => '${functions.readHandlerName}',
-\t\t\t'permission_callback' => '__return_true',
+\t\t\t'callback'            => ${buildRouteCallback(functions.readHandlerName, "read_item")},
+\t\t\t'permission_callback' => ${readPermissionCallback},
 \t\t)`);
     }
     if (methods.includes("update")) {
         itemRoutes.push(`\t\tarray(
 \t\t\t'methods'             => WP_REST_Server::EDITABLE,
-\t\t\t'callback'            => '${functions.updateHandlerName}',
-\t\t\t'permission_callback' => '${functions.canWriteFunctionName}',
+\t\t\t'callback'            => ${buildRouteCallback(functions.updateHandlerName, "update_item")},
+\t\t\t'permission_callback' => ${writePermissionCallback},
 \t\t)`);
     }
     if (methods.includes("delete")) {
         itemRoutes.push(`\t\tarray(
 \t\t\t'methods'             => WP_REST_Server::DELETABLE,
-\t\t\t'callback'            => '${functions.deleteHandlerName}',
-\t\t\t'permission_callback' => '${functions.canWriteFunctionName}',
+\t\t\t'callback'            => ${buildRouteCallback(functions.deleteHandlerName, "delete_item")},
+\t\t\t'permission_callback' => ${writePermissionCallback},
 \t\t)`);
     }
     const registrations = [];
@@ -60,7 +78,7 @@ ${collectionRoutes.join(",\n")}
     if (itemRoutes.length > 0) {
         registrations.push(`\tregister_rest_route(
 \t\t$namespace,
-\t\t'/${restResourceSlug}/item',
+\t\t${quotePhpString(options.routePattern)},
 \t\tarray(
 ${itemRoutes.join(",\n")}
 \t\t)
@@ -68,7 +86,57 @@ ${itemRoutes.join(",\n")}
     }
     return registrations.join("\n\n");
 }
-function buildRestResourcePhpSource(restResourceSlug, namespace, phpPrefix, textDomain, methods) {
+function normalizeGlobalPhpClassName(classReference) {
+    const normalized = classReference.startsWith("\\")
+        ? classReference.slice(1)
+        : classReference;
+    return /^[A-Za-z_][A-Za-z0-9_]*$/u.test(normalized) ? normalized : undefined;
+}
+function toPhpClassConstantReference(classReference) {
+    const normalized = classReference.startsWith("\\")
+        ? classReference
+        : `\\${classReference}`;
+    return `${normalized}::class`;
+}
+function buildRestResourceControllerClassSource(options) {
+    const controllerClassName = normalizeGlobalPhpClassName(options.controllerClass);
+    if (!controllerClassName) {
+        return "";
+    }
+    const extendsClause = options.controllerExtends
+        ? ` extends ${options.controllerExtends.startsWith("\\") ? options.controllerExtends : `\\${options.controllerExtends}`}`
+        : "";
+    return `
+if ( ! class_exists( ${quotePhpString(controllerClassName)} ) ) {
+\tclass ${controllerClassName}${extendsClause} {
+\t\tpublic function can_manage_rest_resource() {
+\t\t\treturn ${options.functions.canWriteFunctionName}();
+\t\t}
+
+\t\tpublic function list_items( WP_REST_Request $request ) {
+\t\t\treturn ${options.functions.listHandlerName}( $request );
+\t\t}
+
+\t\tpublic function read_item( WP_REST_Request $request ) {
+\t\t\treturn ${options.functions.readHandlerName}( $request );
+\t\t}
+
+\t\tpublic function create_item( WP_REST_Request $request ) {
+\t\t\treturn ${options.functions.createHandlerName}( $request );
+\t\t}
+
+\t\tpublic function update_item( WP_REST_Request $request ) {
+\t\t\treturn ${options.functions.updateHandlerName}( $request );
+\t\t}
+
+\t\tpublic function delete_item( WP_REST_Request $request ) {
+\t\t\treturn ${options.functions.deleteHandlerName}( $request );
+\t\t}
+\t}
+}
+`;
+}
+function buildRestResourcePhpSource(restResourceSlug, namespace, phpPrefix, textDomain, methods, options) {
     const restResourceTitle = toTitleCase(restResourceSlug);
     const restResourcePhpId = restResourceSlug.replace(/-/g, "_");
     const canWriteFunctionName = `${phpPrefix}_${restResourcePhpId}_can_manage_rest_resource`;
@@ -85,6 +153,7 @@ function buildRestResourcePhpSource(restResourceSlug, namespace, phpPrefix, text
     const updateHandlerName = `${phpPrefix}_${restResourcePhpId}_handle_update_rest_resource`;
     const deleteHandlerName = `${phpPrefix}_${restResourcePhpId}_handle_delete_rest_resource`;
     const registerRoutesFunctionName = `${phpPrefix}_${restResourcePhpId}_register_rest_routes`;
+    const controllerVariableName = options.controllerClass ? "$controller" : undefined;
     const routeRegistrations = buildRestResourceRouteRegistrations(restResourceSlug, methods, {
         canWriteFunctionName,
         createHandlerName,
@@ -92,7 +161,38 @@ function buildRestResourcePhpSource(restResourceSlug, namespace, phpPrefix, text
         listHandlerName,
         readHandlerName,
         updateHandlerName,
+    }, {
+        ...(controllerVariableName ? { controllerVariableName } : {}),
+        ...(options.permissionCallback
+            ? { permissionCallback: options.permissionCallback }
+            : {}),
+        routePattern: options.routePattern,
     });
+    const controllerClassSource = options.controllerClass
+        ? buildRestResourceControllerClassSource({
+            controllerClass: options.controllerClass,
+            ...(options.controllerExtends
+                ? { controllerExtends: options.controllerExtends }
+                : {}),
+            functions: {
+                canWriteFunctionName,
+                createHandlerName,
+                deleteHandlerName,
+                listHandlerName,
+                readHandlerName,
+                updateHandlerName,
+            },
+        })
+        : "";
+    const controllerBootstrapSource = options.controllerClass
+        ? `\t\t$controller_class = ${toPhpClassConstantReference(options.controllerClass)};
+\t\tif ( ! class_exists( $controller_class ) ) {
+\t\t\treturn;
+\t\t}
+\t\t$controller = new $controller_class();
+
+`
+        : "";
     return `<?php
 if ( ! defined( 'ABSPATH' ) ) {
 \treturn;
@@ -411,10 +511,12 @@ if ( ! function_exists( '${deleteHandlerName}' ) ) {
 \t}
 }
 
+${controllerClassSource}
 if ( ! function_exists( '${registerRoutesFunctionName}' ) ) {
 \tfunction ${registerRoutesFunctionName}() {
 \t\t$namespace = ${quotePhpString(namespace)};
 
+${controllerBootstrapSource}
 ${routeRegistrations}
 \t}
 }
@@ -429,20 +531,189 @@ add_action( 'rest_api_init', '${registerRoutesFunctionName}' );
  * @param options Command options for the REST resource scaffold workflow.
  * @returns Resolved scaffold metadata for the created REST resource.
  */
-export async function runAddRestResourceCommand({ cwd = process.cwd(), methods, namespace, restResourceName, }) {
+export async function runAddRestResourceCommand({ auth, bodyTypeName, controllerClass, controllerExtends, cwd = process.cwd(), manual, method, methods, namespace, permissionCallback, pathPattern, queryTypeName, restResourceName, responseTypeName, routePattern, secretFieldName, secretStateFieldName, }) {
     const workspace = resolveWorkspaceProject(cwd);
     const restResourceSlug = assertValidGeneratedSlug("REST resource name", normalizeBlockSlug(restResourceName), "wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <list,read,create>]");
-    const resolvedMethods = assertValidRestResourceMethods(methods);
     const resolvedNamespace = resolveRestResourceNamespace(workspace.workspace.namespace, namespace);
     const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
     assertRestResourceDoesNotExist(workspace.projectDir, restResourceSlug, inventory);
     const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
-    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
     const syncRestScriptPath = path.join(workspace.projectDir, "scripts", "sync-rest-contracts.ts");
     const restResourceDir = path.join(workspace.projectDir, "src", "rest", restResourceSlug);
     const typesFilePath = path.join(restResourceDir, "api-types.ts");
     const validatorsFilePath = path.join(restResourceDir, "api-validators.ts");
     const apiFilePath = path.join(restResourceDir, "api.ts");
+    if (manual) {
+        if (controllerClass || controllerExtends || permissionCallback || routePattern) {
+            throw new Error("Manual REST contracts do not generate PHP route glue. Use generated rest-resource mode for --route-pattern, --permission-callback, --controller-class, or --controller-extends.");
+        }
+        const pascalCase = toPascalCase(restResourceSlug);
+        const resolvedAuth = assertValidManualRestContractAuth(auth);
+        const resolvedMethod = assertValidManualRestContractHttpMethod(method);
+        const resolvedPathPattern = resolveManualRestContractPathPattern(restResourceSlug, pathPattern);
+        const resolvedQueryTypeName = assertValidTypeScriptIdentifier("Manual REST contract query type", queryTypeName ?? `${pascalCase}Query`, "wp-typia add rest-resource <name> --manual [--query-type <ExportedQueryType>]");
+        const resolvedResponseTypeName = assertValidTypeScriptIdentifier("Manual REST contract response type", responseTypeName ?? `${pascalCase}Response`, "wp-typia add rest-resource <name> --manual [--response-type <ExportedResponseType>]");
+        const defaultsToBody = bodyTypeName == null && ["PATCH", "POST", "PUT"].includes(resolvedMethod);
+        const resolvedBodyTypeName = bodyTypeName != null || defaultsToBody
+            ? assertValidTypeScriptIdentifier("Manual REST contract body type", bodyTypeName ?? `${pascalCase}Request`, "wp-typia add rest-resource <name> --manual [--body-type <ExportedBodyType>]")
+            : undefined;
+        if (resolvedMethod === "GET" && resolvedBodyTypeName) {
+            throw new Error("Manual REST contract GET routes cannot define a body type. Remove --body-type or use POST, PUT, or PATCH.");
+        }
+        if (secretStateFieldName && !secretFieldName) {
+            throw new Error("Manual REST contract --secret-state-field requires --secret-field.");
+        }
+        if (secretFieldName && !resolvedBodyTypeName) {
+            throw new Error("Manual REST contract secret fields require a request body. Use POST, PUT, or PATCH so a request body is generated.");
+        }
+        const resolvedSecretFieldName = secretFieldName
+            ? assertValidTypeScriptIdentifier("Manual REST contract secret field", secretFieldName, "wp-typia add rest-resource <name> --manual --method POST --secret-field <field>")
+            : undefined;
+        const resolvedSecretStateFieldName = resolvedSecretFieldName
+            ? assertValidTypeScriptIdentifier("Manual REST contract secret state field", secretStateFieldName ?? `has${toPascalCase(resolvedSecretFieldName)}`, "wp-typia add rest-resource <name> --manual --method POST --secret-state-field <field>")
+            : undefined;
+        if (resolvedSecretFieldName &&
+            MANUAL_REST_REQUEST_BODY_FIELD_NAMES.has(resolvedSecretFieldName)) {
+            throw new Error(`Manual REST contract secret field must not reuse scaffolded request body fields: ${Array.from(MANUAL_REST_REQUEST_BODY_FIELD_NAMES).join(", ")}.`);
+        }
+        if (resolvedSecretStateFieldName &&
+            MANUAL_REST_RESPONSE_FIELD_NAMES.has(resolvedSecretStateFieldName)) {
+            throw new Error(`Manual REST contract secret state field must not reuse scaffolded response fields: ${Array.from(MANUAL_REST_RESPONSE_FIELD_NAMES).join(", ")}.`);
+        }
+        if (resolvedSecretFieldName &&
+            resolvedSecretStateFieldName &&
+            resolvedSecretFieldName === resolvedSecretStateFieldName) {
+            throw new Error("Manual REST contract secret state field must be different from the raw secret field.");
+        }
+        const manualTypeNames = [
+            resolvedQueryTypeName,
+            resolvedResponseTypeName,
+            resolvedBodyTypeName,
+        ].filter((value) => value != null);
+        const duplicateManualTypeNames = manualTypeNames.filter((name, index) => manualTypeNames.indexOf(name) !== index);
+        if (duplicateManualTypeNames.length > 0) {
+            throw new Error(`Manual REST contract type names must be unique: ${Array.from(new Set(duplicateManualTypeNames)).join(", ")}. Use distinct --query-type, --body-type, and --response-type values.`);
+        }
+        const mutationSnapshot = {
+            fileSources: await snapshotWorkspaceFiles([
+                blockConfigPath,
+                syncRestScriptPath,
+            ]),
+            snapshotDirs: [],
+            targetPaths: [restResourceDir],
+        };
+        try {
+            await fsp.mkdir(restResourceDir, { recursive: true });
+            await ensureRestResourceSyncScriptAnchors(workspace);
+            await fsp.writeFile(typesFilePath, buildManualRestContractTypesSource({
+                ...(resolvedBodyTypeName
+                    ? { bodyTypeName: resolvedBodyTypeName }
+                    : {}),
+                queryTypeName: resolvedQueryTypeName,
+                responseTypeName: resolvedResponseTypeName,
+                restResourceSlug,
+                ...(resolvedSecretFieldName
+                    ? { secretFieldName: resolvedSecretFieldName }
+                    : {}),
+                ...(resolvedSecretStateFieldName
+                    ? { secretStateFieldName: resolvedSecretStateFieldName }
+                    : {}),
+            }), "utf8");
+            await fsp.writeFile(validatorsFilePath, buildManualRestContractValidatorsSource({
+                ...(resolvedBodyTypeName
+                    ? { bodyTypeName: resolvedBodyTypeName }
+                    : {}),
+                queryTypeName: resolvedQueryTypeName,
+                responseTypeName: resolvedResponseTypeName,
+            }), "utf8");
+            await fsp.writeFile(apiFilePath, buildManualRestContractApiSource({
+                ...(resolvedBodyTypeName
+                    ? { bodyTypeName: resolvedBodyTypeName }
+                    : {}),
+                queryTypeName: resolvedQueryTypeName,
+                restResourceSlug,
+            }), "utf8");
+            await syncManualRestContractArtifacts({
+                clientFile: `src/rest/${restResourceSlug}/api-client.ts`,
+                outputDir: restResourceDir,
+                projectDir: workspace.projectDir,
+                typesFile: `src/rest/${restResourceSlug}/api-types.ts`,
+                validatorsFile: `src/rest/${restResourceSlug}/api-validators.ts`,
+                variables: {
+                    auth: resolvedAuth,
+                    ...(resolvedBodyTypeName
+                        ? { bodyTypeName: resolvedBodyTypeName }
+                        : {}),
+                    method: resolvedMethod,
+                    namespace: resolvedNamespace,
+                    pascalCase,
+                    pathPattern: resolvedPathPattern,
+                    queryTypeName: resolvedQueryTypeName,
+                    responseTypeName: resolvedResponseTypeName,
+                    slugKebabCase: restResourceSlug,
+                    title: toTitleCase(restResourceSlug),
+                },
+            });
+            await appendWorkspaceInventoryEntries(workspace.projectDir, {
+                restResourceEntries: [
+                    buildManualRestContractConfigEntry({
+                        auth: resolvedAuth,
+                        ...(resolvedBodyTypeName
+                            ? { bodyTypeName: resolvedBodyTypeName }
+                            : {}),
+                        method: resolvedMethod,
+                        namespace: resolvedNamespace,
+                        pathPattern: resolvedPathPattern,
+                        queryTypeName: resolvedQueryTypeName,
+                        responseTypeName: resolvedResponseTypeName,
+                        restResourceSlug,
+                        ...(resolvedSecretFieldName
+                            ? { secretFieldName: resolvedSecretFieldName }
+                            : {}),
+                        ...(resolvedSecretStateFieldName
+                            ? { secretStateFieldName: resolvedSecretStateFieldName }
+                            : {}),
+                    }),
+                ],
+                transformSource: ensureBlockConfigCanAddRestManifests,
+            });
+            return {
+                auth: resolvedAuth,
+                ...(resolvedBodyTypeName
+                    ? { bodyTypeName: resolvedBodyTypeName }
+                    : {}),
+                method: resolvedMethod,
+                methods: [],
+                mode: "manual",
+                namespace: resolvedNamespace,
+                pathPattern: resolvedPathPattern,
+                projectDir: workspace.projectDir,
+                queryTypeName: resolvedQueryTypeName,
+                restResourceSlug,
+                responseTypeName: resolvedResponseTypeName,
+                ...(resolvedSecretFieldName
+                    ? { secretFieldName: resolvedSecretFieldName }
+                    : {}),
+                ...(resolvedSecretStateFieldName
+                    ? { secretStateFieldName: resolvedSecretStateFieldName }
+                    : {}),
+            };
+        }
+        catch (error) {
+            await rollbackWorkspaceMutation(mutationSnapshot);
+            throw error;
+        }
+    }
+    const resolvedMethods = assertValidRestResourceMethods(methods);
+    const resolvedRoutePattern = resolveGeneratedRestResourceRoutePattern(restResourceSlug, routePattern);
+    const hasCustomRoutePattern = typeof routePattern === "string" && routePattern.trim().length > 0;
+    const resolvedPermissionCallback = resolveOptionalPhpCallbackReference("Generated REST resource permission callback", permissionCallback);
+    const resolvedControllerClass = resolveOptionalPhpClassReference("Generated REST resource controller class", controllerClass);
+    const resolvedControllerExtends = resolveOptionalPhpClassReference("Generated REST resource controller base class", controllerExtends);
+    if (resolvedControllerExtends && !resolvedControllerClass) {
+        throw new Error("Generated REST resource controller base class requires --controller-class.");
+    }
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
     const dataFilePath = path.join(restResourceDir, "data.ts");
     const phpFilePath = path.join(workspace.projectDir, "inc", "rest", `${restResourceSlug}.php`);
     const mutationSnapshot = {
@@ -463,7 +734,18 @@ export async function runAddRestResourceCommand({ cwd = process.cwd(), methods,
         await fsp.writeFile(validatorsFilePath, buildRestResourceValidatorsSource(restResourceSlug, resolvedMethods), "utf8");
         await fsp.writeFile(apiFilePath, buildRestResourceApiSource(restResourceSlug, resolvedMethods), "utf8");
         await fsp.writeFile(dataFilePath, buildRestResourceDataSource(restResourceSlug, resolvedMethods), "utf8");
-        await fsp.writeFile(phpFilePath, buildRestResourcePhpSource(restResourceSlug, resolvedNamespace, workspace.workspace.phpPrefix, workspace.workspace.textDomain, resolvedMethods), "utf8");
+        await fsp.writeFile(phpFilePath, buildRestResourcePhpSource(restResourceSlug, resolvedNamespace, workspace.workspace.phpPrefix, workspace.workspace.textDomain, resolvedMethods, {
+            ...(resolvedControllerClass
+                ? { controllerClass: resolvedControllerClass }
+                : {}),
+            ...(resolvedControllerExtends
+                ? { controllerExtends: resolvedControllerExtends }
+                : {}),
+            ...(resolvedPermissionCallback
+                ? { permissionCallback: resolvedPermissionCallback }
+                : {}),
+            routePattern: resolvedRoutePattern,
+        }), "utf8");
         await syncRestResourceArtifacts({
             clientFile: `src/rest/${restResourceSlug}/api-client.ts`,
             methods: resolvedMethods,
@@ -474,21 +756,47 @@ export async function runAddRestResourceCommand({ cwd = process.cwd(), methods,
             variables: {
                 namespace: resolvedNamespace,
                 pascalCase: toPascalCase(restResourceSlug),
+                ...(hasCustomRoutePattern ? { routePattern: resolvedRoutePattern } : {}),
                 slugKebabCase: restResourceSlug,
                 title: toTitleCase(restResourceSlug),
             },
         });
         await appendWorkspaceInventoryEntries(workspace.projectDir, {
             restResourceEntries: [
-                buildRestResourceConfigEntry(restResourceSlug, resolvedNamespace, resolvedMethods),
+                buildRestResourceConfigEntry({
+                    ...(resolvedControllerClass
+                        ? { controllerClass: resolvedControllerClass }
+                        : {}),
+                    ...(resolvedControllerExtends
+                        ? { controllerExtends: resolvedControllerExtends }
+                        : {}),
+                    methods: resolvedMethods,
+                    namespace: resolvedNamespace,
+                    ...(resolvedPermissionCallback
+                        ? { permissionCallback: resolvedPermissionCallback }
+                        : {}),
+                    restResourceSlug,
+                    ...(hasCustomRoutePattern ? { routePattern: resolvedRoutePattern } : {}),
+                }),
             ],
             transformSource: ensureBlockConfigCanAddRestManifests,
         });
         return {
+            ...(resolvedControllerClass
+                ? { controllerClass: resolvedControllerClass }
+                : {}),
+            ...(resolvedControllerExtends
+                ? { controllerExtends: resolvedControllerExtends }
+                : {}),
             methods: resolvedMethods,
+            mode: "generated",
             namespace: resolvedNamespace,
+            ...(resolvedPermissionCallback
+                ? { permissionCallback: resolvedPermissionCallback }
+                : {}),
             projectDir: workspace.projectDir,
             restResourceSlug,
+            ...(hasCustomRoutePattern ? { routePattern: resolvedRoutePattern } : {}),
         };
     }
     catch (error) {

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

@@ -10,11 +10,26 @@ export { runAddAdminViewCommand, } from "./cli-add-workspace-admin-view.js";
  * `cli-add-workspace-assets` module.
  */
 export { runAddEditorPluginCommand, runAddBindingSourceCommand, runAddPatternCommand, } from "./cli-add-workspace-assets.js";
+/**
+ * Re-export the local integration environment scaffold workflow from the
+ * focused integration-env runtime helper module.
+ */
+export { runAddIntegrationEnvCommand } from "./cli-add-workspace-integration-env.js";
 /**
  * Re-export the plugin-level REST resource scaffold workflow from the focused
  * rest-resource runtime helper module.
  */
 export { runAddRestResourceCommand } from "./cli-add-workspace-rest.js";
+/**
+ * Re-export the standalone contract scaffold workflow from the focused
+ * contract runtime helper module.
+ */
+export { runAddContractCommand } from "./cli-add-workspace-contract.js";
+/**
+ * Re-export the typed post-meta contract scaffold workflow from the focused
+ * post-meta runtime helper module.
+ */
+export { runAddPostMetaCommand } from "./cli-add-workspace-post-meta.js";
 /**
  * Re-export the typed workflow ability scaffold workflow from the focused
  * ability runtime helper module.

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

@@ -417,11 +417,26 @@ export { runAddAdminViewCommand, } from "./cli-add-workspace-admin-view.js";
  * `cli-add-workspace-assets` module.
  */
 export { runAddEditorPluginCommand, runAddBindingSourceCommand, runAddPatternCommand, } from "./cli-add-workspace-assets.js";
+/**
+ * Re-export the local integration environment scaffold workflow from the
+ * focused integration-env runtime helper module.
+ */
+export { runAddIntegrationEnvCommand } from "./cli-add-workspace-integration-env.js";
 /**
  * Re-export the plugin-level REST resource scaffold workflow from the focused
  * rest-resource runtime helper module.
  */
 export { runAddRestResourceCommand } from "./cli-add-workspace-rest.js";
+/**
+ * Re-export the standalone contract scaffold workflow from the focused
+ * contract runtime helper module.
+ */
+export { runAddContractCommand } from "./cli-add-workspace-contract.js";
+/**
+ * Re-export the typed post-meta contract scaffold workflow from the focused
+ * post-meta runtime helper module.
+ */
+export { runAddPostMetaCommand } from "./cli-add-workspace-post-meta.js";
 /**
  * Re-export the typed workflow ability scaffold workflow from the focused
  * ability runtime helper module.

package/dist/runtime/cli-add.d.ts

@@ -10,6 +10,6 @@
 export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
 export type { AddBlockTemplateId, AddKindId, EditorPluginSlotId, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
-export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
+export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddIntegrationEnvCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
 export { getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, } from "./workspace-inventory.js";
 export type { WorkspaceBlockSelectOption } from "./workspace-inventory.js";

package/dist/runtime/cli-add.js

@@ -9,5 +9,5 @@
  */
 export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
-export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
+export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddIntegrationEnvCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
 export { getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, } from "./workspace-inventory.js";

package/dist/runtime/cli-core.d.ts

@@ -15,6 +15,7 @@
  * `seedWorkspaceMigrationProject` for
  * explicit `wp-typia add` flows,
  * `runAddAiFeatureCommand` for server-owned WordPress AI feature scaffolds,
+ * `runAddContractCommand` for standalone TypeScript schema artifacts,
  * `runAddRestResourceCommand` for plugin-level REST resource scaffolds,
  * `getDoctorChecks`, `runDoctor`, and `DoctorCheck` for diagnostics,
  * `createCliCommandError`, `createCliDiagnosticCodeError`,
@@ -32,7 +33,7 @@
 export { getDoctorChecks, runDoctor, type DoctorCheck } from "./cli-doctor.js";
 export { createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODE_METADATA, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getCliDiagnosticCodeMetadata, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
 export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, } from "./cli-diagnostics.js";
-export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
+export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
 export { COMPOUND_INNER_BLOCKS_PRESET_IDS, getCompoundInnerBlocksPresetDefinition, } from "./compound-inner-blocks.js";
 export type { CompoundInnerBlocksPresetId } from "./compound-inner-blocks.js";
 export { HOOKED_BLOCK_POSITION_IDS } from "./hooked-blocks.js";

package/dist/runtime/cli-core.js

@@ -15,6 +15,7 @@
  * `seedWorkspaceMigrationProject` for
  * explicit `wp-typia add` flows,
  * `runAddAiFeatureCommand` for server-owned WordPress AI feature scaffolds,
+ * `runAddContractCommand` for standalone TypeScript schema artifacts,
  * `runAddRestResourceCommand` for plugin-level REST resource scaffolds,
  * `getDoctorChecks`, `runDoctor`, and `DoctorCheck` for diagnostics,
  * `createCliCommandError`, `createCliDiagnosticCodeError`,
@@ -31,7 +32,7 @@
  */
 export { getDoctorChecks, runDoctor } from "./cli-doctor.js";
 export { createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODE_METADATA, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getCliDiagnosticCodeMetadata, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
-export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
+export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
 export { COMPOUND_INNER_BLOCKS_PRESET_IDS, getCompoundInnerBlocksPresetDefinition, } from "./compound-inner-blocks.js";
 export { HOOKED_BLOCK_POSITION_IDS } from "./hooked-blocks.js";
 export { formatHelpText } from "./cli-help.js";

package/dist/runtime/cli-doctor-environment.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, } from "./template-builtins.js";
+import { createDoctorCheck } from "./cli-doctor-workspace-shared.js";
 import { isBuiltInTemplateId, listTemplates } from "./template-registry.js";
 function readCommandVersion(command, args = ["--version"]) {
     try {
@@ -40,9 +41,6 @@ async function checkTempDirectory() {
         return false;
     }
 }
-function createDoctorCheck(label, status, detail) {
-    return { detail, label, status };
-}
 function getTemplateDoctorChecks() {
     const checks = [];
     for (const template of listTemplates()) {