@wp-typia/project-tools 0.24.3 → 0.24.5

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

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { patchFile } from "./cli-add-shared.js";
+import { buildNoResourcesGuard, replaceBlockConfigImport, replaceNoResourcesGuard, } from "./cli-add-workspace-rest-sync-script-shared.js";
+function assertSyncRestAnchor(nextSource, target, anchorDescription, hasAnchor, syncRestScriptPath) {
+    if (!nextSource.includes(target) && !hasAnchor) {
+        throw new Error([
+            `ensureRestResourceSyncScriptAnchors could not patch ${path.basename(syncRestScriptPath)}.`,
+            `Missing expected ${anchorDescription} anchor in scripts/sync-rest-contracts.ts.`,
+            "Restore the generated template or add the REST_RESOURCES wiring manually before retrying.",
+        ].join(" "));
+    }
+}
+function replaceRequiredSyncRestSource(nextSource, target, anchor, replacement, anchorDescription, syncRestScriptPath) {
+    if (nextSource.includes(target)) {
+        return nextSource;
+    }
+    const hasAnchor = typeof anchor === "string" ? nextSource.includes(anchor) : anchor.test(nextSource);
+    assertSyncRestAnchor(nextSource, target, anchorDescription, hasAnchor, syncRestScriptPath);
+    return nextSource.replace(anchor, replacement);
+}
+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, buildNoResourcesGuard({
+        subjects: [
+            {
+                condition: "restBlocks.length === 0",
+                include: true,
+                subject: "REST-enabled workspace blocks",
+            },
+            {
+                condition: "standaloneContracts.length === 0",
+                include: hasStandaloneContracts,
+                subject: "standalone contracts",
+            },
+            {
+                condition: "postMetaContracts.length === 0",
+                include: hasPostMeta,
+                subject: "post meta contracts",
+            },
+            {
+                condition: "restResources.length === 0",
+                include: true,
+                subject: "plugin-level REST resources",
+            },
+            {
+                condition: "aiFeatures.length === 0",
+                include: hasAiFeatures,
+                subject: "AI features",
+            },
+        ],
+    }), "ensureRestResourceSyncScriptAnchors", syncRestScriptPath, "REST_RESOURCES");
+}
+/**
+ * Ensure sync-rest can repair and validate plugin-level REST resources.
+ *
+ * @param workspace Workspace project whose sync-rest script should be patched.
+ * @returns A promise that resolves after the sync-rest script is updated.
+ * @throws When the generated sync-rest anchors cannot be found.
+ */
+export async function ensureRestResourceSyncScriptAnchors(workspace) {
+    const syncRestScriptPath = path.join(workspace.projectDir, "scripts", "sync-rest-contracts.ts");
+    await patchFile(syncRestScriptPath, (source) => {
+        let nextSource = replaceBlockConfigImport({
+            functionName: "ensureRestResourceSyncScriptAnchors",
+            nextSource: source,
+            subject: {
+                configTypeName: "WorkspaceRestResourceConfig",
+                constName: "REST_RESOURCES",
+            },
+            syncRestScriptPath,
+        });
+        const helperInsertionAnchor = "async function assertTypeArtifactsCurrent";
+        const restBlocksAnchor = "const restBlocks = BLOCKS.filter( isRestEnabledBlock );";
+        const consoleLogPattern = /\n\tconsole\.log\(\n\t\toptions\.check/u;
+        nextSource = replaceRequiredSyncRestSource(nextSource, "function isWorkspaceRestResource(", helperInsertionAnchor, [
+            "function isWorkspaceRestResource(",
+            "\tresource: WorkspaceRestResourceConfig",
+            "): resource is WorkspaceRestResourceConfig & {",
+            "\tclientFile: string;",
+            "\topenApiFile: string;",
+            "\trestManifest: NonNullable< WorkspaceRestResourceConfig[ 'restManifest' ] >;",
+            "\ttypesFile: string;",
+            "\tvalidatorsFile: string;",
+            "} {",
+            "\treturn (",
+            "\t\ttypeof resource.clientFile === 'string' &&",
+            "\t\ttypeof resource.openApiFile === 'string' &&",
+            "\t\ttypeof resource.typesFile === 'string' &&",
+            "\t\ttypeof resource.validatorsFile === 'string' &&",
+            "\t\ttypeof resource.restManifest === 'object' &&",
+            "\t\tresource.restManifest !== null",
+            "\t);",
+            "}",
+            "",
+            "async function assertTypeArtifactsCurrent",
+        ].join("\n"), "type artifact assertion helper", syncRestScriptPath);
+        nextSource = replaceRequiredSyncRestSource(nextSource, "const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );", restBlocksAnchor, [
+            "const restBlocks = BLOCKS.filter( isRestEnabledBlock );",
+            "const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );",
+        ].join("\n"), "restBlocks filter", syncRestScriptPath);
+        nextSource = insertRestResourceNoResourcesGuard(nextSource, syncRestScriptPath);
+        nextSource = replaceRequiredSyncRestSource(nextSource, "for ( const resource of restResources ) {", consoleLogPattern, [
+            "",
+            "\tfor ( const resource of restResources ) {",
+            "\t\tconst contracts = resource.restManifest.contracts;",
+            "",
+            "\t\tfor ( const [ baseName, contract ] of Object.entries( contracts ) ) {",
+            "\t\t\tawait syncTypeSchemas(",
+            "\t\t\t\t{",
+            "\t\t\t\t\tjsonSchemaFile: path.join(",
+            "\t\t\t\t\t\tpath.dirname( resource.typesFile ),",
+            "\t\t\t\t\t\t'api-schemas',",
+            "\t\t\t\t\t\t`${ baseName }.schema.json`",
+            "\t\t\t\t\t),",
+            "\t\t\t\t\topenApiFile: path.join(",
+            "\t\t\t\t\t\tpath.dirname( resource.typesFile ),",
+            "\t\t\t\t\t\t'api-schemas',",
+            "\t\t\t\t\t\t`${ baseName }.openapi.json`",
+            "\t\t\t\t\t),",
+            "\t\t\t\t\tsourceTypeName: contract.sourceTypeName,",
+            "\t\t\t\t\ttypesFile: resource.typesFile,",
+            "\t\t\t\t},",
+            "\t\t\t\t{",
+            "\t\t\t\t\tcheck: options.check,",
+            "\t\t\t\t}",
+            "\t\t\t);",
+            "\t\t}",
+            "",
+            "\t\tawait syncRestOpenApi(",
+            "\t\t\t{",
+            "\t\t\t\tmanifest: resource.restManifest,",
+            "\t\t\t\topenApiFile: resource.openApiFile,",
+            "\t\t\t\ttypesFile: resource.typesFile,",
+            "\t\t\t},",
+            "\t\t\t{",
+            "\t\t\t\tcheck: options.check,",
+            "\t\t\t}",
+            "\t\t);",
+            "",
+            "\t\tawait syncEndpointClient(",
+            "\t\t\t{",
+            "\t\t\t\tclientFile: resource.clientFile,",
+            "\t\t\t\tmanifest: resource.restManifest,",
+            "\t\t\t\ttypesFile: resource.typesFile,",
+            "\t\t\t\tvalidatorsFile: resource.validatorsFile,",
+            "\t\t\t},",
+            "\t\t\t{",
+            "\t\t\t\tcheck: options.check,",
+            "\t\t\t}",
+            "\t\t);",
+            "\t}",
+            "",
+            "\tconsole.log(",
+            "\t\toptions.check",
+        ].join("\n"), "success log insertion point", syncRestScriptPath);
+        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, portable API clients, and endpoint-aware OpenAPI documents are already up to date for workspace blocks and plugin-level resources!");
+        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents generated from TypeScript types!", "✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents generated for workspace blocks and plugin-level resources!");
+        return nextSource;
+    });
+}

package/dist/runtime/add/cli-add-workspace-rest-schema-helper-php-template.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Build the shared PHP helper loaded by workspace bootstraps for generated REST schemas.
+ *
+ * @param phpPrefix Plugin-scoped PHP function prefix.
+ * @returns PHP source for `inc/rest-schema.php`.
+ */
+export declare function buildWorkspaceRestSchemaHelperPhpSource(phpPrefix: string): string;

package/dist/runtime/add/cli-add-workspace-rest-schema-helper-php-template.js

@@ -0,0 +1,193 @@
+/**
+ * Build the shared PHP helper loaded by workspace bootstraps for generated REST schemas.
+ *
+ * @param phpPrefix Plugin-scoped PHP function prefix.
+ * @returns PHP source for `inc/rest-schema.php`.
+ */
+export function buildWorkspaceRestSchemaHelperPhpSource(phpPrefix) {
+    return `<?php
+if ( ! defined( 'ABSPATH' ) ) {
+\treturn;
+}
+
+if ( ! function_exists( '${phpPrefix}_is_valid_rest_schema_key' ) ) {
+\tfunction ${phpPrefix}_is_valid_rest_schema_key( $value ) {
+\t\treturn is_string( $value ) && 1 === preg_match( '/\\A[A-Za-z0-9_-]+\\z/', $value );
+\t}
+}
+
+if ( ! function_exists( '${phpPrefix}_is_valid_rest_resource_slug' ) ) {
+\tfunction ${phpPrefix}_is_valid_rest_resource_slug( $value ) {
+\t\treturn is_string( $value ) && 1 === preg_match( '/\\A[a-z0-9]+(?:-[a-z0-9]+)*\\z/', $value );
+\t}
+}
+
+if ( ! function_exists( '${phpPrefix}_resolve_rest_schema_paths' ) ) {
+\tfunction ${phpPrefix}_resolve_rest_schema_paths( $schema_name, $options = array() ) {
+\t\tif ( ! ${phpPrefix}_is_valid_rest_schema_key( $schema_name ) ) {
+\t\t\treturn new WP_Error(
+\t\t\t\t'invalid_rest_schema_name',
+\t\t\t\t'Invalid REST schema name.',
+\t\t\t\tarray( 'status' => 500 )
+\t\t\t);
+\t\t}
+
+\t\t$options      = is_array( $options ) ? $options : array();
+\t\t$project_root = dirname( __DIR__ );
+\t\t$paths        = array();
+
+\t\tif ( isset( $options['resource'] ) && '' !== $options['resource'] ) {
+\t\t\tif ( ! ${phpPrefix}_is_valid_rest_resource_slug( $options['resource'] ) ) {
+\t\t\t\treturn new WP_Error(
+\t\t\t\t\t'invalid_rest_schema_resource',
+\t\t\t\t\t'Invalid REST schema resource slug.',
+\t\t\t\t\tarray( 'status' => 500 )
+\t\t\t\t);
+\t\t\t}
+
+\t\t\t$resource_slug = $options['resource'];
+\t\t\t$paths[]       = __DIR__ . '/rest-schemas/rest/' . $resource_slug . '/' . $schema_name . '.schema.json';
+\t\t\t$paths[]       = $project_root . '/src/rest/' . $resource_slug . '/api-schemas/' . $schema_name . '.schema.json';
+\t\t}
+
+\t\tif ( isset( $options['paths'] ) && is_array( $options['paths'] ) ) {
+\t\t\tforeach ( $options['paths'] as $schema_path ) {
+\t\t\t\tif ( is_string( $schema_path ) && '' !== $schema_path && ! in_array( $schema_path, $paths, true ) ) {
+\t\t\t\t\t$paths[] = $schema_path;
+\t\t\t\t}
+\t\t\t}
+\t\t}
+
+\t\treturn $paths;
+\t}
+}
+
+if ( ! function_exists( '${phpPrefix}_load_rest_schema' ) ) {
+\tfunction ${phpPrefix}_load_rest_schema( $schema_name, $options = array() ) {
+\t\t$schema_paths = ${phpPrefix}_resolve_rest_schema_paths( $schema_name, $options );
+\t\tif ( is_wp_error( $schema_paths ) ) {
+\t\t\treturn $schema_paths;
+\t\t}
+
+\t\tforeach ( $schema_paths as $schema_path ) {
+\t\t\tif ( ! is_file( $schema_path ) ) {
+\t\t\t\tcontinue;
+\t\t\t}
+
+\t\t\tif ( ! is_readable( $schema_path ) ) {
+\t\t\t\treturn new WP_Error(
+\t\t\t\t\t'unreadable_rest_schema',
+\t\t\t\t\t'Generated REST schema is not readable.',
+\t\t\t\t\tarray(
+\t\t\t\t\t\t'path'   => $schema_path,
+\t\t\t\t\t\t'status' => 500,
+\t\t\t\t\t)
+\t\t\t\t);
+\t\t\t}
+
+\t\t\t$schema_json = file_get_contents( $schema_path );
+\t\t\tif ( false === $schema_json ) {
+\t\t\t\treturn new WP_Error(
+\t\t\t\t\t'rest_schema_read_failed',
+\t\t\t\t\t'Generated REST schema could not be read.',
+\t\t\t\t\tarray(
+\t\t\t\t\t\t'path'   => $schema_path,
+\t\t\t\t\t\t'status' => 500,
+\t\t\t\t\t)
+\t\t\t\t);
+\t\t\t}
+
+\t\t\t$decoded = json_decode( $schema_json, true );
+\t\t\tif ( ! is_array( $decoded ) ) {
+\t\t\t\treturn new WP_Error(
+\t\t\t\t\t'malformed_rest_schema',
+\t\t\t\t\t'Generated REST schema contains malformed JSON.',
+\t\t\t\t\tarray(
+\t\t\t\t\t\t'json_error' => json_last_error_msg(),
+\t\t\t\t\t\t'path'       => $schema_path,
+\t\t\t\t\t\t'status'     => 500,
+\t\t\t\t\t)
+\t\t\t\t);
+\t\t\t}
+
+\t\t\treturn $decoded;
+\t\t}
+
+\t\treturn new WP_Error(
+\t\t\t'missing_rest_schema',
+\t\t\t'Generated REST schema could not be found.',
+\t\t\tarray(
+\t\t\t\t'paths'  => $schema_paths,
+\t\t\t\t'schema' => $schema_name,
+\t\t\t\t'status' => 500,
+\t\t\t)
+\t\t);
+\t}
+}
+
+if ( ! function_exists( '${phpPrefix}_prepare_rest_schema_for_wordpress' ) ) {
+\tfunction ${phpPrefix}_prepare_rest_schema_for_wordpress( $schema ) {
+\t\tif ( ! is_array( $schema ) ) {
+\t\t\treturn $schema;
+\t\t}
+
+\t\tunset( $schema['$schema'], $schema['title'] );
+
+\t\tforeach ( array( 'properties', 'patternProperties', 'definitions', '$defs' ) as $schema_map_key ) {
+\t\t\tif ( ! isset( $schema[ $schema_map_key ] ) || ! is_array( $schema[ $schema_map_key ] ) ) {
+\t\t\t\tcontinue;
+\t\t\t}
+
+\t\t\tforeach ( $schema[ $schema_map_key ] as $key => $property_schema ) {
+\t\t\t\t$schema[ $schema_map_key ][ $key ] = ${phpPrefix}_prepare_rest_schema_for_wordpress( $property_schema );
+\t\t\t}
+\t\t}
+
+\t\tforeach ( array( 'items', 'additionalProperties', 'contains', 'propertyNames', 'not', 'if', 'then', 'else' ) as $nested_schema_key ) {
+\t\t\tif ( isset( $schema[ $nested_schema_key ] ) && is_array( $schema[ $nested_schema_key ] ) ) {
+\t\t\t\t$schema[ $nested_schema_key ] = ${phpPrefix}_prepare_rest_schema_for_wordpress( $schema[ $nested_schema_key ] );
+\t\t\t}
+\t\t}
+
+\t\tforeach ( array( 'allOf', 'anyOf', 'oneOf' ) as $schema_list_key ) {
+\t\t\tif ( ! isset( $schema[ $schema_list_key ] ) || ! is_array( $schema[ $schema_list_key ] ) ) {
+\t\t\t\tcontinue;
+\t\t\t}
+
+\t\t\tforeach ( $schema[ $schema_list_key ] as $index => $variant_schema ) {
+\t\t\t\t$schema[ $schema_list_key ][ $index ] = ${phpPrefix}_prepare_rest_schema_for_wordpress( $variant_schema );
+\t\t\t}
+\t\t}
+
+\t\treturn $schema;
+\t}
+}
+
+if ( ! function_exists( '${phpPrefix}_get_wordpress_rest_schema' ) ) {
+\tfunction ${phpPrefix}_get_wordpress_rest_schema( $schema_name, $options = array() ) {
+\t\t$schema = ${phpPrefix}_load_rest_schema( $schema_name, $options );
+\t\tif ( is_wp_error( $schema ) ) {
+\t\t\treturn $schema;
+\t\t}
+
+\t\treturn ${phpPrefix}_prepare_rest_schema_for_wordpress( $schema );
+\t}
+}
+
+if ( ! function_exists( '${phpPrefix}_validate_and_sanitize_rest_payload' ) ) {
+\tfunction ${phpPrefix}_validate_and_sanitize_rest_payload( $value, $schema_name, $param_name, $options = array() ) {
+\t\t$rest_schema = ${phpPrefix}_get_wordpress_rest_schema( $schema_name, $options );
+\t\tif ( is_wp_error( $rest_schema ) ) {
+\t\t\treturn $rest_schema;
+\t\t}
+
+\t\t$validation = rest_validate_value_from_schema( $value, $rest_schema, $param_name );
+\t\tif ( is_wp_error( $validation ) ) {
+\t\t\treturn $validation;
+\t\t}
+
+\t\treturn rest_sanitize_value_from_schema( $value, $rest_schema, $param_name );
+\t}
+}
+`;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Compatibility facade for REST workspace source emitters.
+ *
+ * Keep the public runtime import path stable while generated-resource and
+ * manual-contract emitters live in focused modules.
+ */
+export { buildRestResourceApiSource, buildRestResourceConfigEntry, buildRestResourceDataSource, buildRestResourceTypesSource, buildRestResourceValidatorsSource, } from "./cli-add-workspace-rest-generated-source-emitters.js";
+export { buildManualRestContractApiSource, buildManualRestContractConfigEntry, buildManualRestContractTypesSource, buildManualRestContractValidatorsSource, } from "./cli-add-workspace-rest-manual-source-emitters.js";

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

@@ -0,0 +1,8 @@
+/**
+ * Compatibility facade for REST workspace source emitters.
+ *
+ * Keep the public runtime import path stable while generated-resource and
+ * manual-contract emitters live in focused modules.
+ */
+export { buildRestResourceApiSource, buildRestResourceConfigEntry, buildRestResourceDataSource, buildRestResourceTypesSource, buildRestResourceValidatorsSource, } from "./cli-add-workspace-rest-generated-source-emitters.js";
+export { buildManualRestContractApiSource, buildManualRestContractConfigEntry, buildManualRestContractTypesSource, buildManualRestContractValidatorsSource, } from "./cli-add-workspace-rest-manual-source-emitters.js";

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

@@ -0,0 +1,17 @@
+/**
+ * Prefix every line in a multi-line source fragment.
+ *
+ * @param source Source fragment to indent.
+ * @param prefix Prefix to prepend to every line.
+ * @returns The source fragment with each line prefixed.
+ */
+export declare function indentMultiline(source: string, prefix: string): string;
+/**
+ * Render the shared REST nonce helper in the formatting style expected by a
+ * generated source file.
+ *
+ * @param style Compact output is used by manual-contract shims; spaced output
+ * matches generated REST resource shims.
+ * @returns TypeScript source for the embedded `resolveRestNonce()` helper.
+ */
+export declare function formatResolveRestNonceSource(style: "compact" | "spaced"): string;

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

@@ -0,0 +1,50 @@
+/**
+ * Prefix every line in a multi-line source fragment.
+ *
+ * @param source Source fragment to indent.
+ * @param prefix Prefix to prepend to every line.
+ * @returns The source fragment with each line prefixed.
+ */
+export function indentMultiline(source, prefix) {
+    return source
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+const RESOLVE_REST_NONCE_SOURCE = `function resolveRestNonce( fallback?: string ): string | undefined {
+\tif ( typeof fallback === 'string' && fallback.length > 0 ) {
+\t\treturn fallback;
+\t}
+
+\tif ( typeof window === 'undefined' ) {
+\t\treturn undefined;
+\t}
+
+\tconst wpApiSettings = (
+\t\twindow as typeof window & {
+\t\t\twpApiSettings?: { nonce?: string };
+\t\t}
+\t).wpApiSettings;
+
+\treturn typeof wpApiSettings?.nonce === 'string' &&
+\t\twpApiSettings.nonce.length > 0
+\t\t? wpApiSettings.nonce
+\t\t: undefined;
+}`;
+/**
+ * Render the shared REST nonce helper in the formatting style expected by a
+ * generated source file.
+ *
+ * @param style Compact output is used by manual-contract shims; spaced output
+ * matches generated REST resource shims.
+ * @returns TypeScript source for the embedded `resolveRestNonce()` helper.
+ */
+export function formatResolveRestNonceSource(style) {
+    if (style === "spaced") {
+        return RESOLVE_REST_NONCE_SOURCE;
+    }
+    return RESOLVE_REST_NONCE_SOURCE
+        .replace("function resolveRestNonce( fallback?: string ): string | undefined {", "function resolveRestNonce(fallback?: string): string | undefined {")
+        .replace("\tif ( typeof fallback === 'string' && fallback.length > 0 ) {", "\tif (typeof fallback === 'string' && fallback.length > 0) {")
+        .replace("\tif ( typeof window === 'undefined' ) {", "\tif (typeof window === 'undefined') {");
+}

package/dist/runtime/add/cli-add-workspace-rest-sync-script-shared.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Build the standard sync-rest patch failure message for missing anchors.
+ *
+ * @param functionName Name of the patcher that could not complete.
+ * @param syncRestScriptPath Path to the workspace sync-rest script.
+ * @param anchorDescription Human-readable description of the missing anchor.
+ * @param subject Configuration subject the patcher was trying to wire.
+ * @returns A formatted error message with manual recovery guidance.
+ */
+export declare function getSyncRestPatchErrorMessage(functionName: string, syncRestScriptPath: string, anchorDescription: string, subject: string): string;
+/**
+ * Add a required block-config value and type import to sync-rest source.
+ *
+ * @param options Import patching options.
+ * @param options.functionName Name of the calling patcher for error messages.
+ * @param options.nextSource Current sync-rest script source.
+ * @param options.subject Value and type names that must be imported.
+ * @param options.syncRestScriptPath Path to the target sync-rest script.
+ * @returns Source with the block-config import updated or left unchanged.
+ * @throws When the generated block-config import anchor cannot be found.
+ */
+export declare function replaceBlockConfigImport({ functionName, nextSource, subject, syncRestScriptPath, }: {
+    functionName: string;
+    nextSource: string;
+    subject: {
+        configTypeName: string;
+        constName: string;
+    };
+    syncRestScriptPath: string;
+}): string;
+/**
+ * Render a sync-rest guard for the selected empty resource collections.
+ *
+ * @param options Guard rendering options.
+ * @param options.subjects Candidate guard subjects and conditions.
+ * @returns TypeScript source for the no-resources guard block.
+ */
+export declare function buildNoResourcesGuard({ subjects, }: {
+    subjects: readonly {
+        condition: string;
+        include: boolean;
+        subject: string;
+    }[];
+}): string;
+/**
+ * Replace the generated no-resources guard in sync-rest source.
+ *
+ * @param nextSource Current sync-rest script source.
+ * @param replacement New no-resources guard source.
+ * @param functionName Name of the calling patcher for error messages.
+ * @param syncRestScriptPath Path to the target sync-rest script.
+ * @param subject Configuration subject the patcher was trying to wire.
+ * @returns Source with the no-resources guard replaced.
+ * @throws When the generated no-resources guard cannot be found.
+ */
+export declare function replaceNoResourcesGuard(nextSource: string, replacement: string, functionName: string, syncRestScriptPath: string, subject: string): string;

package/dist/runtime/add/cli-add-workspace-rest-sync-script-shared.js

@@ -0,0 +1,122 @@
+import path from "node:path";
+/**
+ * Build the standard sync-rest patch failure message for missing anchors.
+ *
+ * @param functionName Name of the patcher that could not complete.
+ * @param syncRestScriptPath Path to the workspace sync-rest script.
+ * @param anchorDescription Human-readable description of the missing anchor.
+ * @param subject Configuration subject the patcher was trying to wire.
+ * @returns A formatted error message with manual recovery guidance.
+ */
+export 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(" ");
+}
+const BLOCK_CONFIG_IMPORT_PATTERNS = [
+    /^import\s*\{\n(?:\t[^\n]*\n)+\} from ["']\.\/block-config["'];?$/mu,
+    /^import\s*\{[^\n]*\}\s*from\s*["']\.\/block-config["'];?$/mu,
+];
+const BLOCK_CONFIG_VALUE_IMPORT_ORDER = [
+    "AI_FEATURES",
+    "BLOCKS",
+    "CONTRACTS",
+    "POST_META",
+    "REST_RESOURCES",
+];
+const BLOCK_CONFIG_TYPE_IMPORT_ORDER = [
+    "WorkspaceAiFeatureConfig",
+    "WorkspaceBlockConfig",
+    "WorkspaceContractConfig",
+    "WorkspacePostMetaConfig",
+    "WorkspaceRestResourceConfig",
+];
+/**
+ * Add a required block-config value and type import to sync-rest source.
+ *
+ * @param options Import patching options.
+ * @param options.functionName Name of the calling patcher for error messages.
+ * @param options.nextSource Current sync-rest script source.
+ * @param options.subject Value and type names that must be imported.
+ * @param options.syncRestScriptPath Path to the target sync-rest script.
+ * @returns Source with the block-config import updated or left unchanged.
+ * @throws When the generated block-config import anchor cannot be found.
+ */
+export function replaceBlockConfigImport({ functionName, nextSource, subject, syncRestScriptPath, }) {
+    const importMatch = BLOCK_CONFIG_IMPORT_PATTERNS.map((pattern) => pattern.exec(nextSource)).find(Boolean) ?? null;
+    if (!importMatch) {
+        throw new Error(getSyncRestPatchErrorMessage(functionName, syncRestScriptPath, "block-config import", subject.constName));
+    }
+    const importSource = importMatch[0];
+    if (importSource.includes(subject.constName) &&
+        importSource.includes(subject.configTypeName)) {
+        return nextSource;
+    }
+    if (!importSource.includes("BLOCKS") ||
+        !importSource.includes("WorkspaceBlockConfig")) {
+        throw new Error(getSyncRestPatchErrorMessage(functionName, syncRestScriptPath, "BLOCKS import", subject.constName));
+    }
+    const replacement = [
+        "import {",
+        ...BLOCK_CONFIG_VALUE_IMPORT_ORDER.flatMap((constName) => constName === subject.constName || importSource.includes(constName)
+            ? [`\t${constName},`]
+            : []),
+        ...BLOCK_CONFIG_TYPE_IMPORT_ORDER.flatMap((configTypeName) => configTypeName === subject.configTypeName ||
+            importSource.includes(configTypeName)
+            ? [`\ttype ${configTypeName},`]
+            : []),
+        "} from './block-config';",
+    ].join("\n");
+    return nextSource.replace(importSource, 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}`;
+}
+/**
+ * Render a sync-rest guard for the selected empty resource collections.
+ *
+ * @param options Guard rendering options.
+ * @param options.subjects Candidate guard subjects and conditions.
+ * @returns TypeScript source for the no-resources guard block.
+ */
+export function buildNoResourcesGuard({ subjects, }) {
+    const includedSubjects = subjects.filter((subject) => subject.include);
+    const condition = includedSubjects.map(({ condition }, index) => index === includedSubjects.length - 1 ? condition : `${condition} &&`);
+    const noResourcesSubject = formatNoResourcesSubject(includedSubjects.map(({ subject }) => subject));
+    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;
+/**
+ * Replace the generated no-resources guard in sync-rest source.
+ *
+ * @param nextSource Current sync-rest script source.
+ * @param replacement New no-resources guard source.
+ * @param functionName Name of the calling patcher for error messages.
+ * @param syncRestScriptPath Path to the target sync-rest script.
+ * @param subject Configuration subject the patcher was trying to wire.
+ * @returns Source with the no-resources guard replaced.
+ * @throws When the generated no-resources guard cannot be found.
+ */
+export 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);
+}