@wp-typia/project-tools 0.23.0 → 0.24.0

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

@@ -0,0 +1,266 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { ensureBlockConfigCanAddRestManifests } from "./cli-add-block-legacy-validator.js";
+import { assertValidManualRestContractAuth, assertValidManualRestContractHttpMethod, assertValidTypeScriptIdentifier, collectRestRouteNamedCaptureNames, resolveOptionalPhpCallbackReference, resolveOptionalPhpClassReference, resolveManualRestContractPathPattern, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ensureRestResourceSyncScriptAnchors, } from "./cli-add-workspace-rest-resource-sync-anchors.js";
+import { buildManualRestContractApiSource, buildManualRestContractConfigEntry, buildManualRestContractTypesSource, buildManualRestContractValidatorsSource, } from "./cli-add-workspace-rest-manual-source-emitters.js";
+import { syncManualRestContractArtifacts } from "./rest-resource-artifacts.js";
+import { toPascalCase, toTitleCase } from "./string-case.js";
+import { appendWorkspaceInventoryEntries } from "./workspace-inventory.js";
+const MANUAL_REST_REQUEST_BODY_FIELD_NAMES = new Set(["payload", "comment"]);
+const MANUAL_REST_RESPONSE_FIELD_NAMES = new Set([
+    "id",
+    "status",
+    "message",
+    "updatedAt",
+]);
+function resolveManualRestSecretPreserveOnEmpty(value) {
+    return value ?? true;
+}
+function resolveManualRestSecretStateFieldCandidate(options) {
+    const candidates = [
+        options.secretStateFieldName,
+        options.secretHasValueFieldName,
+        options.secretMaskedResponseFieldName,
+    ].filter((value) => typeof value === "string");
+    const distinct = Array.from(new Set(candidates));
+    if (distinct.length > 1) {
+        throw new Error("Manual REST contract secret state, has-value, and masked response field flags must match when combined.");
+    }
+    return distinct[0];
+}
+function resolveManualRestRoutePathPattern(options) {
+    const trimmedPathPattern = typeof options.pathPattern === "string"
+        ? options.pathPattern.trim()
+        : undefined;
+    const trimmedRoutePattern = typeof options.routePattern === "string"
+        ? options.routePattern.trim()
+        : undefined;
+    if (trimmedPathPattern &&
+        trimmedRoutePattern &&
+        trimmedPathPattern !== trimmedRoutePattern) {
+        throw new Error("Manual REST contract --path and --route-pattern must match when both are provided. Use one route pattern flag for provider routes.");
+    }
+    return resolveManualRestContractPathPattern(options.restResourceSlug, options.pathPattern ?? options.routePattern);
+}
+/**
+ * Scaffold a type-only external REST contract for workspace consumers.
+ *
+ * @param options Resolved workspace and raw manual-mode command options.
+ * @returns Resolved scaffold metadata for the manual REST contract.
+ */
+export async function scaffoldManualRestContract({ auth, bodyTypeName, controllerClass, controllerExtends, method, namespace, pathPattern, permissionCallback, queryTypeName, responseTypeName, restResourceSlug, routePattern, secretFieldName, secretHasValueFieldName, secretMaskedResponseFieldName, secretPreserveOnEmpty, secretStateFieldName, workspace, }) {
+    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+    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");
+    const pascalCase = toPascalCase(restResourceSlug);
+    const resolvedAuth = assertValidManualRestContractAuth(auth);
+    const resolvedMethod = assertValidManualRestContractHttpMethod(method);
+    const resolvedPathPattern = resolveManualRestRoutePathPattern({
+        pathPattern,
+        restResourceSlug,
+        routePattern,
+    });
+    const pathParameterNames = collectRestRouteNamedCaptureNames(resolvedPathPattern);
+    const resolvedPermissionCallback = resolveOptionalPhpCallbackReference("Manual REST contract permission callback", permissionCallback);
+    const resolvedControllerClass = resolveOptionalPhpClassReference("Manual REST contract controller class", controllerClass);
+    const resolvedControllerExtends = resolveOptionalPhpClassReference("Manual REST contract controller base class", controllerExtends);
+    if (resolvedControllerExtends && !resolvedControllerClass) {
+        throw new Error("Manual REST contract controller base class requires --controller-class.");
+    }
+    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.");
+    }
+    const secretStateFieldCandidate = resolveManualRestSecretStateFieldCandidate({
+        secretHasValueFieldName,
+        secretMaskedResponseFieldName,
+        secretStateFieldName,
+    });
+    if (secretPreserveOnEmpty !== undefined && !secretFieldName) {
+        throw new Error("Manual REST contract --secret-preserve-on-empty requires --secret-field.");
+    }
+    if (secretStateFieldCandidate !== undefined && !secretFieldName) {
+        throw new Error("Manual REST contract secret state, has-value, and masked response field flags require --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 resolvedSecretPreserveOnEmpty = resolvedSecretFieldName
+        ? resolveManualRestSecretPreserveOnEmpty(secretPreserveOnEmpty)
+        : undefined;
+    const resolvedSecretStateFieldName = resolvedSecretFieldName
+        ? assertValidTypeScriptIdentifier("Manual REST contract secret state field", secretStateFieldCandidate ??
+            `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 }
+                : {}),
+            pathParameterNames,
+            queryTypeName: resolvedQueryTypeName,
+            responseTypeName: resolvedResponseTypeName,
+            restResourceSlug,
+            ...(resolvedSecretFieldName
+                ? { secretFieldName: resolvedSecretFieldName }
+                : {}),
+            ...(resolvedSecretPreserveOnEmpty !== undefined
+                ? { secretPreserveOnEmpty: resolvedSecretPreserveOnEmpty }
+                : {}),
+            ...(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,
+                pascalCase,
+                pathPattern: resolvedPathPattern,
+                queryTypeName: resolvedQueryTypeName,
+                responseTypeName: resolvedResponseTypeName,
+                slugKebabCase: restResourceSlug,
+                title: toTitleCase(restResourceSlug),
+            },
+        });
+        await appendWorkspaceInventoryEntries(workspace.projectDir, {
+            restResourceEntries: [
+                buildManualRestContractConfigEntry({
+                    auth: resolvedAuth,
+                    ...(resolvedBodyTypeName
+                        ? { bodyTypeName: resolvedBodyTypeName }
+                        : {}),
+                    ...(resolvedControllerClass
+                        ? { controllerClass: resolvedControllerClass }
+                        : {}),
+                    ...(resolvedControllerExtends
+                        ? { controllerExtends: resolvedControllerExtends }
+                        : {}),
+                    method: resolvedMethod,
+                    namespace,
+                    pathPattern: resolvedPathPattern,
+                    ...(resolvedPermissionCallback
+                        ? { permissionCallback: resolvedPermissionCallback }
+                        : {}),
+                    queryTypeName: resolvedQueryTypeName,
+                    responseTypeName: resolvedResponseTypeName,
+                    restResourceSlug,
+                    ...(resolvedSecretFieldName
+                        ? { secretFieldName: resolvedSecretFieldName }
+                        : {}),
+                    ...(resolvedSecretPreserveOnEmpty !== undefined
+                        ? { secretPreserveOnEmpty: resolvedSecretPreserveOnEmpty }
+                        : {}),
+                    ...(resolvedSecretStateFieldName
+                        ? { secretStateFieldName: resolvedSecretStateFieldName }
+                        : {}),
+                }),
+            ],
+            transformSource: ensureBlockConfigCanAddRestManifests,
+        });
+        return {
+            auth: resolvedAuth,
+            ...(resolvedBodyTypeName
+                ? { bodyTypeName: resolvedBodyTypeName }
+                : {}),
+            ...(resolvedControllerClass
+                ? { controllerClass: resolvedControllerClass }
+                : {}),
+            ...(resolvedControllerExtends
+                ? { controllerExtends: resolvedControllerExtends }
+                : {}),
+            method: resolvedMethod,
+            methods: [],
+            mode: "manual",
+            namespace,
+            pathPattern: resolvedPathPattern,
+            ...(resolvedPermissionCallback
+                ? { permissionCallback: resolvedPermissionCallback }
+                : {}),
+            projectDir: workspace.projectDir,
+            queryTypeName: resolvedQueryTypeName,
+            restResourceSlug,
+            responseTypeName: resolvedResponseTypeName,
+            ...(resolvedSecretFieldName
+                ? { secretFieldName: resolvedSecretFieldName }
+                : {}),
+            ...(resolvedSecretPreserveOnEmpty !== undefined
+                ? { secretPreserveOnEmpty: resolvedSecretPreserveOnEmpty }
+                : {}),
+            ...(resolvedSecretStateFieldName
+                ? { secretStateFieldName: resolvedSecretStateFieldName }
+                : {}),
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}

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

@@ -0,0 +1,18 @@
+import { type RestResourceMethodId } from "./cli-add-shared.js";
+export { buildWorkspaceRestSchemaHelperPhpSource, } from "./cli-add-workspace-rest-schema-helper-php-template.js";
+/**
+ * Build the PHP route/controller glue for generated workspace REST resources.
+ *
+ * @param restResourceSlug Normalized REST resource slug.
+ * @param namespace WordPress REST namespace, such as `vendor/v1`.
+ * @param phpPrefix Plugin PHP function prefix.
+ * @param methods REST operations to expose.
+ * @param options Optional generated route and controller customizations.
+ * @returns A complete PHP source file for the generated REST resource.
+ */
+export declare function buildRestResourcePhpSource(restResourceSlug: string, namespace: string, phpPrefix: string, methods: RestResourceMethodId[], options: {
+    controllerClass?: string;
+    controllerExtends?: string;
+    permissionCallback?: string;
+    routePattern: string;
+}): string;

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

@@ -0,0 +1,359 @@
+import { quotePhpString } from "./php-utils.js";
+import { toTitleCase } from "./string-case.js";
+import { buildRestResourceControllerBootstrapSource, buildRestResourceControllerClassSource, buildRestResourceRouteRegistrations, } from "./cli-add-workspace-rest-resource-php-routing-template.js";
+export { buildWorkspaceRestSchemaHelperPhpSource, } from "./cli-add-workspace-rest-schema-helper-php-template.js";
+/**
+ * Build the PHP route/controller glue for generated workspace REST resources.
+ *
+ * @param restResourceSlug Normalized REST resource slug.
+ * @param namespace WordPress REST namespace, such as `vendor/v1`.
+ * @param phpPrefix Plugin PHP function prefix.
+ * @param methods REST operations to expose.
+ * @param options Optional generated route and controller customizations.
+ * @returns A complete PHP source file for the generated REST resource.
+ */
+export function buildRestResourcePhpSource(restResourceSlug, namespace, phpPrefix, methods, options) {
+    const restResourceTitle = toTitleCase(restResourceSlug);
+    const restResourcePhpId = restResourceSlug.replace(/-/g, "_");
+    const canWriteFunctionName = `${phpPrefix}_${restResourcePhpId}_can_manage_rest_resource`;
+    const getItemsFunctionName = `${phpPrefix}_${restResourcePhpId}_get_rest_resource_items`;
+    const validatePayloadFunctionName = `${phpPrefix}_${restResourcePhpId}_validate_rest_resource_payload`;
+    const normalizeItemFunctionName = `${phpPrefix}_${restResourcePhpId}_normalize_rest_resource_item`;
+    const saveItemsFunctionName = `${phpPrefix}_${restResourcePhpId}_save_rest_resource_items`;
+    const getOptionNameFunctionName = `${phpPrefix}_${restResourcePhpId}_get_rest_resource_option_name`;
+    const listHandlerName = `${phpPrefix}_${restResourcePhpId}_handle_list_rest_resource`;
+    const readHandlerName = `${phpPrefix}_${restResourcePhpId}_handle_read_rest_resource`;
+    const createHandlerName = `${phpPrefix}_${restResourcePhpId}_handle_create_rest_resource`;
+    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,
+        deleteHandlerName,
+        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 = buildRestResourceControllerBootstrapSource(options.controllerClass);
+    return `<?php
+if ( ! defined( 'ABSPATH' ) ) {
+\treturn;
+}
+
+if ( ! function_exists( '${getOptionNameFunctionName}' ) ) {
+\tfunction ${getOptionNameFunctionName}() {
+\t\treturn ${quotePhpString(`${phpPrefix}_${restResourcePhpId}_rest_resource_items`)};
+\t}
+}
+
+if ( ! function_exists( '${normalizeItemFunctionName}' ) ) {
+\tfunction ${normalizeItemFunctionName}( array $item ) {
+\t\treturn array(
+\t\t\t'id'        => isset( $item['id'] ) ? (int) $item['id'] : 0,
+\t\t\t'title'     => isset( $item['title'] ) ? (string) $item['title'] : '',
+\t\t\t'content'   => isset( $item['content'] ) ? (string) $item['content'] : '',
+\t\t\t'status'    => isset( $item['status'] ) && 'published' === $item['status'] ? 'published' : 'draft',
+\t\t\t'updatedAt' => isset( $item['updatedAt'] ) ? (string) $item['updatedAt'] : gmdate( 'c' ),
+\t\t);
+\t}
+}
+
+if ( ! function_exists( '${getItemsFunctionName}' ) ) {
+\tfunction ${getItemsFunctionName}() {
+\t\t$seed_items = array(
+\t\t\tarray(
+\t\t\t\t'id'        => 1,
+\t\t\t\t'title'     => ${quotePhpString(`${restResourceTitle} Starter`)},
+\t\t\t\t'content'   => ${quotePhpString(`Replace this seeded ${restResourceTitle.toLowerCase()} content with your plugin data source.`)},
+\t\t\t\t'status'    => 'draft',
+\t\t\t\t'updatedAt' => '2026-01-01T00:00:00Z',
+\t\t\t),
+\t\t);
+\t\t$items = get_option( ${getOptionNameFunctionName}(), $seed_items );
+
+\t\tif ( ! is_array( $items ) ) {
+\t\t\t$items = $seed_items;
+\t\t}
+
+\t\treturn array_values(
+\t\t\tarray_map(
+\t\t\t\t'${normalizeItemFunctionName}',
+\t\t\t\tarray_filter(
+\t\t\t\t\t$items,
+\t\t\t\t\t'is_array'
+\t\t\t\t)
+\t\t\t)
+\t\t);
+\t}
+}
+
+if ( ! function_exists( '${saveItemsFunctionName}' ) ) {
+\tfunction ${saveItemsFunctionName}( array $items ) {
+\t\tupdate_option(
+\t\t\t${getOptionNameFunctionName}(),
+\t\t\tarray_values(
+\t\t\t\tarray_map(
+\t\t\t\t\t'${normalizeItemFunctionName}',
+\t\t\t\t\t$items
+\t\t\t\t)
+\t\t\t),
+\t\t\tfalse
+\t\t);
+\t}
+}
+
+if ( ! function_exists( '${validatePayloadFunctionName}' ) ) {
+\tfunction ${validatePayloadFunctionName}( $value, $schema_name, $param_name ) {
+\t\tif ( ! function_exists( '${phpPrefix}_validate_and_sanitize_rest_payload' ) ) {
+\t\t\treturn new WP_Error(
+\t\t\t\t'missing_rest_schema_helper',
+\t\t\t\t'Missing REST schema helper. Ensure inc/rest-schema.php is loaded before REST resources.',
+\t\t\t\tarray( 'status' => 500 )
+\t\t\t);
+\t\t}
+
+\t\treturn ${phpPrefix}_validate_and_sanitize_rest_payload(
+\t\t\t$value,
+\t\t\t$schema_name,
+\t\t\t$param_name,
+\t\t\tarray( 'resource' => ${quotePhpString(restResourceSlug)} )
+\t\t);
+\t}
+}
+
+if ( ! function_exists( '${canWriteFunctionName}' ) ) {
+\tfunction ${canWriteFunctionName}() {
+\t\treturn current_user_can( 'edit_posts' );
+\t}
+}
+
+if ( ! function_exists( '${listHandlerName}' ) ) {
+\tfunction ${listHandlerName}( WP_REST_Request $request ) {
+\t\t$payload_input = array();
+\t\t$page          = $request->get_param( 'page' );
+\t\t$per_page      = $request->get_param( 'perPage' );
+\t\t$search        = $request->get_param( 'search' );
+
+\t\tif ( null !== $page ) {
+\t\t\t$payload_input['page'] = $page;
+\t\t}
+\t\tif ( null !== $per_page ) {
+\t\t\t$payload_input['perPage'] = $per_page;
+\t\t}
+\t\tif ( null !== $search ) {
+\t\t\t$payload_input['search'] = $search;
+\t\t}
+
+\t\t$payload = ${validatePayloadFunctionName}(
+\t\t\t$payload_input,
+\t\t\t'list-query',
+\t\t\t'query'
+\t\t);
+
+\t\tif ( is_wp_error( $payload ) ) {
+\t\t\treturn $payload;
+\t\t}
+
+\t\t$page     = isset( $payload['page'] ) ? max( 1, (int) $payload['page'] ) : 1;
+\t\t$per_page = isset( $payload['perPage'] ) ? min( 50, max( 1, (int) $payload['perPage'] ) ) : 10;
+\t\t$search   = isset( $payload['search'] ) ? strtolower( (string) $payload['search'] ) : '';
+\t\t$items    = ${getItemsFunctionName}();
+
+\t\tif ( '' !== $search ) {
+\t\t\t$items = array_values(
+\t\t\t\tarray_filter(
+\t\t\t\t\t$items,
+\t\t\t\t\tstatic function ( $item ) use ( $search ) {
+\t\t\t\t\t\treturn false !== strpos( strtolower( (string) ( $item['title'] ?? '' ) ), $search ) ||
+\t\t\t\t\t\t\tfalse !== strpos( strtolower( (string) ( $item['content'] ?? '' ) ), $search );
+\t\t\t\t\t}
+\t\t\t\t)
+\t\t\t);
+\t\t}
+
+\t\t$total = count( $items );
+\t\t$items = array_slice( $items, ( $page - 1 ) * $per_page, $per_page );
+
+\t\treturn rest_ensure_response(
+\t\t\tarray(
+\t\t\t\t'items'   => $items,
+\t\t\t\t'page'    => $page,
+\t\t\t\t'perPage' => $per_page,
+\t\t\t\t'total'   => $total,
+\t\t\t)
+\t\t);
+\t}
+}
+
+if ( ! function_exists( '${readHandlerName}' ) ) {
+\tfunction ${readHandlerName}( WP_REST_Request $request ) {
+\t\t$payload = ${validatePayloadFunctionName}(
+\t\t\tarray(
+\t\t\t\t'id' => $request->get_param( 'id' ),
+\t\t\t),
+\t\t\t'read-query',
+\t\t\t'query'
+\t\t);
+
+\t\tif ( is_wp_error( $payload ) ) {
+\t\t\treturn $payload;
+\t\t}
+
+\t\tforeach ( ${getItemsFunctionName}() as $item ) {
+\t\t\tif ( (int) $item['id'] === (int) $payload['id'] ) {
+\t\t\t\treturn rest_ensure_response( $item );
+\t\t\t}
+\t\t}
+
+\t\treturn new WP_Error( 'rest_not_found', 'Resource not found.', array( 'status' => 404 ) );
+\t}
+}
+
+if ( ! function_exists( '${createHandlerName}' ) ) {
+\tfunction ${createHandlerName}( WP_REST_Request $request ) {
+\t\t$payload = ${validatePayloadFunctionName}( $request->get_json_params(), 'create-request', 'body' );
+\t\tif ( is_wp_error( $payload ) ) {
+\t\t\treturn $payload;
+\t\t}
+
+\t\t$items   = ${getItemsFunctionName}();
+\t\t$next_id = 1;
+\t\tforeach ( $items as $item ) {
+\t\t\t$next_id = max( $next_id, (int) $item['id'] + 1 );
+\t\t}
+
+\t\t$record = ${normalizeItemFunctionName}(
+\t\t\tarray(
+\t\t\t\t'id'        => $next_id,
+\t\t\t\t'title'     => (string) $payload['title'],
+\t\t\t\t'content'   => isset( $payload['content'] ) ? (string) $payload['content'] : '',
+\t\t\t\t'status'    => isset( $payload['status'] ) ? (string) $payload['status'] : 'draft',
+\t\t\t\t'updatedAt' => gmdate( 'c' ),
+\t\t\t)
+\t\t);
+
+\t\t$items[] = $record;
+\t\t${saveItemsFunctionName}( $items );
+
+\t\treturn rest_ensure_response( $record );
+\t}
+}
+
+if ( ! function_exists( '${updateHandlerName}' ) ) {
+\tfunction ${updateHandlerName}( WP_REST_Request $request ) {
+\t\t$query = ${validatePayloadFunctionName}(
+\t\t\tarray(
+\t\t\t\t'id' => $request->get_param( 'id' ),
+\t\t\t),
+\t\t\t'update-query',
+\t\t\t'query'
+\t\t);
+\t\tif ( is_wp_error( $query ) ) {
+\t\t\treturn $query;
+\t\t}
+
+\t\t$payload = ${validatePayloadFunctionName}( $request->get_json_params(), 'update-request', 'body' );
+\t\tif ( is_wp_error( $payload ) ) {
+\t\t\treturn $payload;
+\t\t}
+
+\t\t$items = ${getItemsFunctionName}();
+\t\tforeach ( $items as $index => $item ) {
+\t\t\tif ( (int) $item['id'] !== (int) $query['id'] ) {
+\t\t\t\tcontinue;
+\t\t\t}
+
+\t\t\t$items[ $index ] = ${normalizeItemFunctionName}(
+\t\t\t\tarray(
+\t\t\t\t\t'id'        => $item['id'],
+\t\t\t\t\t'title'     => isset( $payload['title'] ) ? (string) $payload['title'] : (string) $item['title'],
+\t\t\t\t\t'content'   => array_key_exists( 'content', $payload ) ? (string) $payload['content'] : (string) $item['content'],
+\t\t\t\t\t'status'    => isset( $payload['status'] ) ? (string) $payload['status'] : (string) $item['status'],
+\t\t\t\t\t'updatedAt' => gmdate( 'c' ),
+\t\t\t\t)
+\t\t\t);
+
+\t\t\t${saveItemsFunctionName}( $items );
+\t\t\treturn rest_ensure_response( $items[ $index ] );
+\t\t}
+
+\t\treturn new WP_Error( 'rest_not_found', 'Resource not found.', array( 'status' => 404 ) );
+\t}
+}
+
+if ( ! function_exists( '${deleteHandlerName}' ) ) {
+\tfunction ${deleteHandlerName}( WP_REST_Request $request ) {
+\t\t$query = ${validatePayloadFunctionName}(
+\t\t\tarray(
+\t\t\t\t'id' => $request->get_param( 'id' ),
+\t\t\t),
+\t\t\t'delete-query',
+\t\t\t'query'
+\t\t);
+\t\tif ( is_wp_error( $query ) ) {
+\t\t\treturn $query;
+\t\t}
+
+\t\t$items       = ${getItemsFunctionName}();
+\t\t$filtered    = array_values(
+\t\t\tarray_filter(
+\t\t\t\t$items,
+\t\t\t\tstatic function ( $item ) use ( $query ) {
+\t\t\t\t\treturn (int) $item['id'] !== (int) $query['id'];
+\t\t\t\t}
+\t\t\t)
+\t\t);
+\t\t$was_deleted = count( $filtered ) !== count( $items );
+
+\t\tif ( ! $was_deleted ) {
+\t\t\treturn new WP_Error( 'rest_not_found', 'Resource not found.', array( 'status' => 404 ) );
+\t\t}
+
+\t\t${saveItemsFunctionName}( $filtered );
+
+\t\treturn rest_ensure_response(
+\t\t\tarray(
+\t\t\t\t'deleted' => true,
+\t\t\t\t'id'      => (int) $query['id'],
+\t\t\t)
+\t\t);
+\t}
+}
+
+${controllerClassSource}
+if ( ! function_exists( '${registerRoutesFunctionName}' ) ) {
+\tfunction ${registerRoutesFunctionName}() {
+\t\t$namespace = ${quotePhpString(namespace)};
+
+${controllerBootstrapSource}
+${routeRegistrations}
+\t}
+}
+
+add_action( 'rest_api_init', '${registerRoutesFunctionName}' );
+`;
+}

package/dist/runtime/cli-add-workspace-rest-resource-php-routing-template.d.ts

@@ -0,0 +1,33 @@
+import { type RestResourceMethodId } from "./cli-add-shared.js";
+export interface RestResourcePhpFunctionNames {
+    canWriteFunctionName: string;
+    createHandlerName: string;
+    deleteHandlerName: string;
+    listHandlerName: string;
+    readHandlerName: string;
+    updateHandlerName: string;
+}
+/**
+ * Build the `register_rest_route` calls for generated REST resource PHP files.
+ */
+export declare function buildRestResourceRouteRegistrations(restResourceSlug: string, methods: RestResourceMethodId[], functions: RestResourcePhpFunctionNames, options: {
+    controllerVariableName?: string;
+    permissionCallback?: string;
+    routePattern: string;
+}): string;
+/**
+ * Normalize a configured PHP class name into a global `::class` reference.
+ */
+export declare function toPhpClassConstantReference(classReference: string): string;
+/**
+ * Build an optional controller shim class for generated REST resource handlers.
+ */
+export declare function buildRestResourceControllerClassSource(options: {
+    controllerClass: string;
+    controllerExtends?: string;
+    functions: RestResourcePhpFunctionNames;
+}): string;
+/**
+ * Build the controller instantiation block used inside REST route registration.
+ */
+export declare function buildRestResourceControllerBootstrapSource(controllerClass: string | undefined): string;