@wp-typia/project-tools 0.22.10 → 0.23.1

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

@@ -3,6 +3,47 @@ import { getWorkspaceBootstrapPath, patchFile, } from "./cli-add-shared.js";
 import { appendPhpSnippetBeforeClosingTag, insertPhpSnippetBeforeWorkspaceAnchors, } from "./cli-add-workspace-mutation.js";
 import { hasPhpFunctionDefinition } from "./php-utils.js";
 const REST_RESOURCE_SERVER_GLOB = "/inc/rest/*.php";
+const REST_SCHEMA_HELPER_PATH = "/inc/rest-schema.php";
+/**
+ * Ensure the workspace bootstrap loads the shared REST schema helper file.
+ *
+ * @param workspace Resolved workspace project metadata and PHP prefix.
+ * @returns A promise that resolves after the bootstrap is patched.
+ * @throws When an existing loader does not reference `inc/rest-schema.php`.
+ */
+export async function ensureRestSchemaHelperBootstrapAnchors(workspace) {
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    await patchFile(bootstrapPath, (source) => {
+        let nextSource = source;
+        const loadFunctionName = `${workspace.workspace.phpPrefix}_load_rest_schema_helpers`;
+        const loadCall = `${loadFunctionName}();`;
+        const helperFunction = `
+
+function ${loadFunctionName}() {
+\t$helper_path = __DIR__ . '${REST_SCHEMA_HELPER_PATH}';
+\tif ( is_readable( $helper_path ) ) {
+\t\trequire_once $helper_path;
+\t}
+}
+
+${loadCall}
+`;
+        if (!hasPhpFunctionDefinition(nextSource, loadFunctionName)) {
+            nextSource = insertPhpSnippetBeforeWorkspaceAnchors(nextSource, helperFunction);
+        }
+        else if (!nextSource.includes(REST_SCHEMA_HELPER_PATH)) {
+            throw new Error([
+                `Unable to patch ${path.basename(bootstrapPath)} in ensureRestSchemaHelperBootstrapAnchors.`,
+                `The existing ${loadFunctionName}() definition does not include ${REST_SCHEMA_HELPER_PATH}.`,
+                "Restore the generated bootstrap shape or load inc/rest-schema.php manually before retrying.",
+            ].join(" "));
+        }
+        else if (!nextSource.includes(loadCall)) {
+            nextSource = appendPhpSnippetBeforeClosingTag(nextSource, loadCall);
+        }
+        return nextSource;
+    });
+}
 export async function ensureRestResourceBootstrapAnchors(workspace) {
     const bootstrapPath = getWorkspaceBootstrapPath(workspace);
     await patchFile(bootstrapPath, (source) => {
@@ -50,23 +91,296 @@ function replaceRequiredSyncRestSource(nextSource, target, anchor, replacement,
     assertSyncRestAnchor(nextSource, target, anchorDescription, hasAnchor, syncRestScriptPath);
     return nextSource.replace(anchor, replacement);
 }
+function getSyncRestPatchErrorMessage(functionName, syncRestScriptPath, anchorDescription, subject) {
+    return [
+        `${functionName} could not patch ${path.basename(syncRestScriptPath)}.`,
+        `Missing expected ${anchorDescription} anchor in scripts/sync-rest-contracts.ts.`,
+        `Restore the generated template or add the ${subject} wiring manually before retrying.`,
+    ].join(" ");
+}
+function replaceBlockConfigImportForContracts(nextSource, syncRestScriptPath) {
+    const importPatterns = [
+        /^import\s*\{\n(?:\t[^\n]*\n)+\} from ["']\.\/block-config["'];?$/mu,
+        /^import\s*\{[^\n]*\}\s*from\s*["']\.\/block-config["'];?$/mu,
+    ];
+    const importMatch = importPatterns.map((pattern) => pattern.exec(nextSource)).find(Boolean) ??
+        null;
+    if (!importMatch) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureContractSyncScriptAnchors", syncRestScriptPath, "block-config import", "CONTRACTS"));
+    }
+    const importSource = importMatch[0];
+    if (importSource.includes("CONTRACTS") &&
+        importSource.includes("WorkspaceContractConfig")) {
+        return nextSource;
+    }
+    if (!importSource.includes("BLOCKS") ||
+        !importSource.includes("WorkspaceBlockConfig")) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureContractSyncScriptAnchors", syncRestScriptPath, "BLOCKS import", "CONTRACTS"));
+    }
+    const hasAiFeatures = importSource.includes("AI_FEATURES");
+    const hasAiFeatureConfig = importSource.includes("WorkspaceAiFeatureConfig");
+    const hasRestResources = importSource.includes("REST_RESOURCES");
+    const hasRestResourceConfig = importSource.includes("WorkspaceRestResourceConfig");
+    const hasPostMeta = importSource.includes("POST_META");
+    const hasPostMetaConfig = importSource.includes("WorkspacePostMetaConfig");
+    const replacement = [
+        "import {",
+        ...(hasAiFeatures ? ["\tAI_FEATURES,"] : []),
+        "\tBLOCKS,",
+        "\tCONTRACTS,",
+        ...(hasPostMeta ? ["\tPOST_META,"] : []),
+        ...(hasRestResources ? ["\tREST_RESOURCES,"] : []),
+        ...(hasAiFeatureConfig ? ["\ttype WorkspaceAiFeatureConfig,"] : []),
+        "\ttype WorkspaceBlockConfig,",
+        "\ttype WorkspaceContractConfig,",
+        ...(hasPostMetaConfig ? ["\ttype WorkspacePostMetaConfig,"] : []),
+        ...(hasRestResourceConfig ? ["\ttype WorkspaceRestResourceConfig,"] : []),
+        "} from './block-config';",
+    ].join("\n");
+    return nextSource.replace(importSource, replacement);
+}
+function replaceBlockConfigImportForRestResources(nextSource, syncRestScriptPath) {
+    const importPatterns = [
+        /^import\s*\{\n(?:\t[^\n]*\n)+\} from ["']\.\/block-config["'];?$/mu,
+        /^import\s*\{[^\n]*\}\s*from\s*["']\.\/block-config["'];?$/mu,
+    ];
+    const importMatch = importPatterns.map((pattern) => pattern.exec(nextSource)).find(Boolean) ??
+        null;
+    if (!importMatch) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureRestResourceSyncScriptAnchors", syncRestScriptPath, "block-config import", "REST_RESOURCES"));
+    }
+    const importSource = importMatch[0];
+    if (importSource.includes("REST_RESOURCES") &&
+        importSource.includes("WorkspaceRestResourceConfig")) {
+        return nextSource;
+    }
+    if (!importSource.includes("BLOCKS") ||
+        !importSource.includes("WorkspaceBlockConfig")) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureRestResourceSyncScriptAnchors", syncRestScriptPath, "BLOCKS import", "REST_RESOURCES"));
+    }
+    const hasAiFeatures = importSource.includes("AI_FEATURES");
+    const hasAiFeatureConfig = importSource.includes("WorkspaceAiFeatureConfig");
+    const hasContracts = importSource.includes("CONTRACTS");
+    const hasContractConfig = importSource.includes("WorkspaceContractConfig");
+    const hasPostMeta = importSource.includes("POST_META");
+    const hasPostMetaConfig = importSource.includes("WorkspacePostMetaConfig");
+    const replacement = [
+        "import {",
+        ...(hasAiFeatures ? ["\tAI_FEATURES,"] : []),
+        "\tBLOCKS,",
+        ...(hasContracts ? ["\tCONTRACTS,"] : []),
+        ...(hasPostMeta ? ["\tPOST_META,"] : []),
+        "\tREST_RESOURCES,",
+        ...(hasAiFeatureConfig ? ["\ttype WorkspaceAiFeatureConfig,"] : []),
+        "\ttype WorkspaceBlockConfig,",
+        ...(hasContractConfig ? ["\ttype WorkspaceContractConfig,"] : []),
+        ...(hasPostMetaConfig ? ["\ttype WorkspacePostMetaConfig,"] : []),
+        "\ttype WorkspaceRestResourceConfig,",
+        "} from './block-config';",
+    ].join("\n");
+    return nextSource.replace(importSource, replacement);
+}
+function replaceRequiredContractSyncRestSource(nextSource, target, anchor, replacement, anchorDescription, syncRestScriptPath) {
+    if (nextSource.includes(target)) {
+        return nextSource;
+    }
+    const hasAnchor = typeof anchor === "string" ? nextSource.includes(anchor) : anchor.test(nextSource);
+    if (!hasAnchor) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureContractSyncScriptAnchors", syncRestScriptPath, anchorDescription, "CONTRACTS"));
+    }
+    return nextSource.replace(anchor, replacement);
+}
+function formatNoResourcesSubject(subjects) {
+    if (subjects.length <= 2) {
+        return subjects.join(" or ");
+    }
+    const lastSubject = subjects[subjects.length - 1];
+    return `${subjects.slice(0, -1).join(", ")}, or ${lastSubject}`;
+}
+function buildContractNoResourcesGuard({ hasAiFeatures, hasPostMeta, hasRestResources, }) {
+    const condition = ["restBlocks.length === 0 &&", "standaloneContracts.length === 0"];
+    if (hasPostMeta) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("postMetaContracts.length === 0");
+    }
+    if (hasRestResources) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("restResources.length === 0");
+    }
+    if (hasAiFeatures) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("aiFeatures.length === 0");
+    }
+    const noResourcesSubject = formatNoResourcesSubject([
+        "REST-enabled workspace blocks",
+        "standalone contracts",
+        ...(hasPostMeta ? ["post meta contracts"] : []),
+        ...(hasRestResources ? ["plugin-level REST resources"] : []),
+        ...(hasAiFeatures ? ["AI features"] : []),
+    ]);
+    return [
+        "if (",
+        ...condition.map((line) => `\t\t${line}`),
+        "\t) {",
+        "\t\tconsole.log(",
+        "\t\t\toptions.check",
+        `\t\t\t\t? 'ℹ️ No ${noResourcesSubject} are registered yet. \`sync-rest --check\` is already clean.'`,
+        `\t\t\t\t: 'ℹ️ No ${noResourcesSubject} are registered yet.'`,
+        "\t\t);",
+        "\t\treturn;",
+        "\t}",
+    ].join("\n");
+}
+const NO_RESOURCES_GUARD_PATTERN = /if \(\s*restBlocks\.length === 0(?:\s*&&\s*standaloneContracts\.length === 0)?(?:\s*&&\s*postMetaContracts\.length === 0)?(?:\s*&&\s*restResources\.length === 0)?(?:\s*&&\s*aiFeatures\.length === 0)?\s*\) \{[\s\S]*?\n\t\treturn;\n\t\}/u;
+function replaceNoResourcesGuard(nextSource, replacement, functionName, syncRestScriptPath, subject) {
+    if (!NO_RESOURCES_GUARD_PATTERN.test(nextSource)) {
+        throw new Error(getSyncRestPatchErrorMessage(functionName, syncRestScriptPath, "no-resources guard", subject));
+    }
+    return nextSource.replace(NO_RESOURCES_GUARD_PATTERN, replacement);
+}
+function insertStandaloneContractFilter(nextSource, syncRestScriptPath) {
+    if (nextSource.includes("const standaloneContracts = CONTRACTS.filter")) {
+        return nextSource;
+    }
+    const restResourcesFilter = "const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );";
+    if (nextSource.includes(restResourcesFilter)) {
+        return nextSource.replace(restResourcesFilter, [
+            "const standaloneContracts = CONTRACTS.filter( isWorkspaceStandaloneContract );",
+            restResourcesFilter,
+        ].join("\n\t"));
+    }
+    const restBlocksFilter = "const restBlocks = BLOCKS.filter( isRestEnabledBlock );";
+    return replaceRequiredContractSyncRestSource(nextSource, "const standaloneContracts = CONTRACTS.filter", restBlocksFilter, [
+        restBlocksFilter,
+        "const standaloneContracts = CONTRACTS.filter( isWorkspaceStandaloneContract );",
+    ].join("\n\t"), "restBlocks filter", syncRestScriptPath);
+}
+function insertStandaloneContractNoResourcesGuard(nextSource, syncRestScriptPath) {
+    const hasRestResources = nextSource.includes("const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );");
+    const hasAiFeatures = nextSource.includes("const aiFeatures = AI_FEATURES.filter( isWorkspaceAiFeature );");
+    const hasPostMeta = nextSource.includes("const postMetaContracts = POST_META.filter( isWorkspacePostMetaContract );");
+    return replaceNoResourcesGuard(nextSource, buildContractNoResourcesGuard({
+        hasAiFeatures,
+        hasPostMeta,
+        hasRestResources,
+    }), "ensureContractSyncScriptAnchors", syncRestScriptPath, "CONTRACTS");
+}
+function buildRestResourceNoResourcesGuard({ hasAiFeatures, hasPostMeta, hasStandaloneContracts, }) {
+    const condition = ["restBlocks.length === 0"];
+    if (hasStandaloneContracts) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("standaloneContracts.length === 0");
+    }
+    if (hasPostMeta) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("postMetaContracts.length === 0");
+    }
+    condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+    condition.push("restResources.length === 0");
+    if (hasAiFeatures) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("aiFeatures.length === 0");
+    }
+    const noResourcesSubject = formatNoResourcesSubject([
+        "REST-enabled workspace blocks",
+        ...(hasStandaloneContracts ? ["standalone contracts"] : []),
+        ...(hasPostMeta ? ["post meta contracts"] : []),
+        "plugin-level REST resources",
+        ...(hasAiFeatures ? ["AI features"] : []),
+    ]);
+    return [
+        "if (",
+        ...condition.map((line) => `\t\t${line}`),
+        "\t) {",
+        "\t\tconsole.log(",
+        "\t\t\toptions.check",
+        `\t\t\t\t? 'ℹ️ No ${noResourcesSubject} are registered yet. \`sync-rest --check\` is already clean.'`,
+        `\t\t\t\t: 'ℹ️ No ${noResourcesSubject} are registered yet.'`,
+        "\t\t);",
+        "\t\treturn;",
+        "\t}",
+    ].join("\n");
+}
+function insertRestResourceNoResourcesGuard(nextSource, syncRestScriptPath) {
+    const hasStandaloneContracts = nextSource.includes("const standaloneContracts = CONTRACTS.filter( isWorkspaceStandaloneContract );");
+    const hasAiFeatures = nextSource.includes("const aiFeatures = AI_FEATURES.filter( isWorkspaceAiFeature );");
+    const hasPostMeta = nextSource.includes("const postMetaContracts = POST_META.filter( isWorkspacePostMetaContract );");
+    return replaceNoResourcesGuard(nextSource, buildRestResourceNoResourcesGuard({
+        hasAiFeatures,
+        hasPostMeta,
+        hasStandaloneContracts,
+    }), "ensureRestResourceSyncScriptAnchors", syncRestScriptPath, "REST_RESOURCES");
+}
+function insertStandaloneContractSyncLoop(nextSource, syncRestScriptPath) {
+    if (nextSource.includes("for ( const contract of standaloneContracts )")) {
+        return nextSource;
+    }
+    const loopSource = [
+        "\tfor ( const contract of standaloneContracts ) {",
+        "\t\tawait syncTypeSchemas(",
+        "\t\t\t{",
+        "\t\t\t\tjsonSchemaFile: contract.schemaFile,",
+        "\t\t\t\tsourceTypeName: contract.sourceTypeName,",
+        "\t\t\t\ttypesFile: contract.typesFile,",
+        "\t\t\t},",
+        "\t\t\t{",
+        "\t\t\t\tcheck: options.check,",
+        "\t\t\t}",
+        "\t\t);",
+        "\t}",
+    ].join("\n");
+    const resourceLoopAnchor = "\n\tfor ( const resource of restResources ) {";
+    if (nextSource.includes(resourceLoopAnchor)) {
+        return nextSource.replace(resourceLoopAnchor, `\n${loopSource}\n${resourceLoopAnchor}`);
+    }
+    const consoleLogPattern = /\n\tconsole\.log\(\n\t\toptions\.check/u;
+    return replaceRequiredContractSyncRestSource(nextSource, "for ( const contract of standaloneContracts )", consoleLogPattern, [
+        "",
+        loopSource,
+        "",
+        "\tconsole.log(",
+        "\t\toptions.check",
+    ].join("\n"), "success log insertion point", syncRestScriptPath);
+}
+export async function ensureContractSyncScriptAnchors(workspace) {
+    const syncRestScriptPath = path.join(workspace.projectDir, "scripts", "sync-rest-contracts.ts");
+    await patchFile(syncRestScriptPath, (source) => {
+        let nextSource = replaceBlockConfigImportForContracts(source, syncRestScriptPath);
+        const helperInsertionAnchor = "async function assertTypeArtifactsCurrent";
+        nextSource = replaceRequiredContractSyncRestSource(nextSource, "function isWorkspaceStandaloneContract(", helperInsertionAnchor, [
+            "function isWorkspaceStandaloneContract(",
+            "\tcontract: WorkspaceContractConfig",
+            "): contract is WorkspaceContractConfig & {",
+            "\tschemaFile: string;",
+            "\tsourceTypeName: string;",
+            "\ttypesFile: string;",
+            "} {",
+            "\treturn (",
+            "\t\ttypeof contract.schemaFile === 'string' &&",
+            "\t\ttypeof contract.sourceTypeName === 'string' &&",
+            "\t\ttypeof contract.typesFile === 'string'",
+            "\t);",
+            "}",
+            "",
+            "async function assertTypeArtifactsCurrent",
+        ].join("\n"), "type artifact assertion helper", syncRestScriptPath);
+        nextSource = insertStandaloneContractFilter(nextSource, syncRestScriptPath);
+        nextSource = insertStandaloneContractNoResourcesGuard(nextSource, syncRestScriptPath);
+        nextSource = insertStandaloneContractSyncLoop(nextSource, syncRestScriptPath);
+        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents are already up to date for workspace blocks and plugin-level resources!", "✅ REST contract schemas, standalone schemas, portable API clients, and endpoint-aware OpenAPI documents are already up to date for workspace blocks, standalone contracts, and plugin-level resources!");
+        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents generated for workspace blocks and plugin-level resources!", "✅ REST contract schemas, standalone schemas, portable API clients, and endpoint-aware OpenAPI documents generated for workspace blocks, standalone contracts, and plugin-level resources!");
+        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents are already up to date with the TypeScript types!", "✅ REST contract schemas, standalone schemas, portable API clients, and endpoint-aware OpenAPI documents are already up to date with the TypeScript types!");
+        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents generated from TypeScript types!", "✅ REST contract schemas, standalone schemas, portable API clients, and endpoint-aware OpenAPI documents generated from TypeScript types!");
+        return nextSource;
+    });
+}
 export async function ensureRestResourceSyncScriptAnchors(workspace) {
     const syncRestScriptPath = path.join(workspace.projectDir, "scripts", "sync-rest-contracts.ts");
     await patchFile(syncRestScriptPath, (source) => {
-        let nextSource = source;
-        const importAnchor = "import { BLOCKS, type WorkspaceBlockConfig } from './block-config';";
+        let nextSource = replaceBlockConfigImportForRestResources(source, syncRestScriptPath);
         const helperInsertionAnchor = "async function assertTypeArtifactsCurrent";
         const restBlocksAnchor = "const restBlocks = BLOCKS.filter( isRestEnabledBlock );";
-        const noResourcesPattern = /if \( restBlocks.length === 0 \) \{[\s\S]*?\n\t\treturn;\n\t\}/u;
         const consoleLogPattern = /\n\tconsole\.log\(\n\t\toptions\.check/u;
-        nextSource = replaceRequiredSyncRestSource(nextSource, "REST_RESOURCES", importAnchor, [
-            "import {",
-            "\tBLOCKS,",
-            "\tREST_RESOURCES,",
-            "\ttype WorkspaceBlockConfig,",
-            "\ttype WorkspaceRestResourceConfig,",
-            "} from './block-config';",
-        ].join("\n"), "BLOCKS import", syncRestScriptPath);
         nextSource = replaceRequiredSyncRestSource(nextSource, "function isWorkspaceRestResource(", helperInsertionAnchor, [
             "function isWorkspaceRestResource(",
             "\tresource: WorkspaceRestResourceConfig",
@@ -93,16 +407,7 @@ export async function ensureRestResourceSyncScriptAnchors(workspace) {
             "const restBlocks = BLOCKS.filter( isRestEnabledBlock );",
             "const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );",
         ].join("\n"), "restBlocks filter", syncRestScriptPath);
-        nextSource = replaceRequiredSyncRestSource(nextSource, "restBlocks.length === 0 && restResources.length === 0", noResourcesPattern, [
-            "if ( restBlocks.length === 0 && restResources.length === 0 ) {",
-            "\t\tconsole.log(",
-            "\t\t\toptions.check",
-            "\t\t\t\t? 'ℹ️ No REST-enabled workspace blocks or plugin-level REST resources are registered yet. `sync-rest --check` is already clean.'",
-            "\t\t\t\t: 'ℹ️ No REST-enabled workspace blocks or plugin-level REST resources are registered yet.'",
-            "\t\t);",
-            "\t\treturn;",
-            "\t}",
-        ].join("\n"), "no-resources guard", syncRestScriptPath);
+        nextSource = insertRestResourceNoResourcesGuard(nextSource, syncRestScriptPath);
         nextSource = replaceRequiredSyncRestSource(nextSource, "for ( const resource of restResources ) {", consoleLogPattern, [
             "",
             "\tfor ( const resource of restResources ) {",

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

@@ -0,0 +1,9 @@
+import { type GeneratedRestResourceScaffoldOptions, type RunAddRestResourceCommandResult } from "./cli-add-workspace-rest-types.js";
+/**
+ * Scaffold generated TypeScript, PHP, schema, and inventory files for a
+ * workspace-owned REST resource.
+ *
+ * @param options Resolved workspace and raw generated-mode command options.
+ * @returns Resolved scaffold metadata for the generated REST resource.
+ */
+export declare function scaffoldGeneratedRestResource({ controllerClass, controllerExtends, methods, namespace, permissionCallback, restResourceSlug, routePattern, workspace, }: GeneratedRestResourceScaffoldOptions): Promise<RunAddRestResourceCommandResult>;

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

@@ -0,0 +1,158 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { ensureBlockConfigCanAddRestManifests } from "./cli-add-block-legacy-validator.js";
+import { assertValidRestResourceMethods, getWorkspaceBootstrapPath, resolveGeneratedRestResourceRoutePattern, resolveOptionalPhpCallbackReference, resolveOptionalPhpClassReference, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ensureRestResourceBootstrapAnchors, ensureRestSchemaHelperBootstrapAnchors, ensureRestResourceSyncScriptAnchors, } from "./cli-add-workspace-rest-anchors.js";
+import { buildRestResourcePhpSource, buildWorkspaceRestSchemaHelperPhpSource, } from "./cli-add-workspace-rest-php-templates.js";
+import { buildRestResourceApiSource, buildRestResourceConfigEntry, buildRestResourceDataSource, buildRestResourceTypesSource, buildRestResourceValidatorsSource, } from "./cli-add-workspace-rest-source-emitters.js";
+import { hasPhpFunctionDefinition } from "./php-utils.js";
+import { syncRestResourceArtifacts } from "./rest-resource-artifacts.js";
+import { toPascalCase, toTitleCase } from "./string-case.js";
+import { appendWorkspaceInventoryEntries } from "./workspace-inventory.js";
+async function ensureWorkspaceRestSchemaHelperFile(helperFilePath, phpPrefix) {
+    let currentSource = null;
+    try {
+        currentSource = await fsp.readFile(helperFilePath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    if (currentSource === null) {
+        await fsp.mkdir(path.dirname(helperFilePath), { recursive: true });
+        await fsp.writeFile(helperFilePath, buildWorkspaceRestSchemaHelperPhpSource(phpPrefix), "utf8");
+        return;
+    }
+    const requiredFunctions = [
+        `${phpPrefix}_load_rest_schema`,
+        `${phpPrefix}_prepare_rest_schema_for_wordpress`,
+        `${phpPrefix}_get_wordpress_rest_schema`,
+        `${phpPrefix}_validate_and_sanitize_rest_payload`,
+    ];
+    const missingFunctions = requiredFunctions.filter((functionName) => !hasPhpFunctionDefinition(currentSource, functionName));
+    if (missingFunctions.length > 0) {
+        throw new Error([
+            `Existing ${path.relative(process.cwd(), helperFilePath)} is missing generated REST schema helper functions: ${missingFunctions.join(", ")}.`,
+            "Restore the generated inc/rest-schema.php helper or add these functions manually before retrying.",
+        ].join(" "));
+    }
+}
+/**
+ * Scaffold generated TypeScript, PHP, schema, and inventory files for a
+ * workspace-owned REST resource.
+ *
+ * @param options Resolved workspace and raw generated-mode command options.
+ * @returns Resolved scaffold metadata for the generated REST resource.
+ */
+export async function scaffoldGeneratedRestResource({ controllerClass, controllerExtends, methods, namespace, permissionCallback, restResourceSlug, routePattern, 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 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 restSchemaHelperPath = path.join(workspace.projectDir, "inc", "rest-schema.php");
+    const phpFilePath = path.join(workspace.projectDir, "inc", "rest", `${restResourceSlug}.php`);
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([
+            blockConfigPath,
+            bootstrapPath,
+            restSchemaHelperPath,
+            syncRestScriptPath,
+        ]),
+        snapshotDirs: [],
+        targetPaths: [restResourceDir, restSchemaHelperPath, phpFilePath],
+    };
+    try {
+        await fsp.mkdir(restResourceDir, { recursive: true });
+        await fsp.mkdir(path.dirname(phpFilePath), { recursive: true });
+        await ensureWorkspaceRestSchemaHelperFile(restSchemaHelperPath, workspace.workspace.phpPrefix);
+        await ensureRestSchemaHelperBootstrapAnchors(workspace);
+        await ensureRestResourceBootstrapAnchors(workspace);
+        await ensureRestResourceSyncScriptAnchors(workspace);
+        await fsp.writeFile(typesFilePath, buildRestResourceTypesSource(restResourceSlug, resolvedMethods), "utf8");
+        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, namespace, workspace.workspace.phpPrefix, resolvedMethods, {
+            ...(resolvedControllerClass
+                ? { controllerClass: resolvedControllerClass }
+                : {}),
+            ...(resolvedControllerExtends
+                ? { controllerExtends: resolvedControllerExtends }
+                : {}),
+            ...(resolvedPermissionCallback
+                ? { permissionCallback: resolvedPermissionCallback }
+                : {}),
+            routePattern: resolvedRoutePattern,
+        }), "utf8");
+        await syncRestResourceArtifacts({
+            clientFile: `src/rest/${restResourceSlug}/api-client.ts`,
+            methods: resolvedMethods,
+            outputDir: restResourceDir,
+            projectDir: workspace.projectDir,
+            typesFile: `src/rest/${restResourceSlug}/api-types.ts`,
+            validatorsFile: `src/rest/${restResourceSlug}/api-validators.ts`,
+            variables: {
+                namespace,
+                pascalCase: toPascalCase(restResourceSlug),
+                ...(hasCustomRoutePattern ? { routePattern: resolvedRoutePattern } : {}),
+                slugKebabCase: restResourceSlug,
+                title: toTitleCase(restResourceSlug),
+            },
+        });
+        await appendWorkspaceInventoryEntries(workspace.projectDir, {
+            restResourceEntries: [
+                buildRestResourceConfigEntry({
+                    ...(resolvedControllerClass
+                        ? { controllerClass: resolvedControllerClass }
+                        : {}),
+                    ...(resolvedControllerExtends
+                        ? { controllerExtends: resolvedControllerExtends }
+                        : {}),
+                    methods: resolvedMethods,
+                    namespace,
+                    ...(resolvedPermissionCallback
+                        ? { permissionCallback: resolvedPermissionCallback }
+                        : {}),
+                    restResourceSlug,
+                    ...(hasCustomRoutePattern ? { routePattern: resolvedRoutePattern } : {}),
+                }),
+            ],
+            transformSource: ensureBlockConfigCanAddRestManifests,
+        });
+        return {
+            ...(resolvedControllerClass
+                ? { controllerClass: resolvedControllerClass }
+                : {}),
+            ...(resolvedControllerExtends
+                ? { controllerExtends: resolvedControllerExtends }
+                : {}),
+            methods: resolvedMethods,
+            mode: "generated",
+            namespace,
+            ...(resolvedPermissionCallback
+                ? { permissionCallback: resolvedPermissionCallback }
+                : {}),
+            projectDir: workspace.projectDir,
+            restResourceSlug,
+            ...(hasCustomRoutePattern ? { routePattern: resolvedRoutePattern } : {}),
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}

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

@@ -0,0 +1,8 @@
+import { type ManualRestContractScaffoldOptions, type RunAddRestResourceCommandResult } from "./cli-add-workspace-rest-types.js";
+/**
+ * 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 declare function scaffoldManualRestContract({ auth, bodyTypeName, controllerClass, controllerExtends, method, namespace, pathPattern, permissionCallback, queryTypeName, responseTypeName, restResourceSlug, routePattern, secretFieldName, secretHasValueFieldName, secretMaskedResponseFieldName, secretPreserveOnEmpty, secretStateFieldName, workspace, }: ManualRestContractScaffoldOptions): Promise<RunAddRestResourceCommandResult>;