@wp-typia/create-workspace-template 0.17.0 → 0.17.1

package/README.md

@@ -6,20 +6,96 @@ Use it through the canonical CLI:
 
 ```bash
 npx wp-typia create my-plugin --template @wp-typia/create-workspace-template
+npx wp-typia create my-plugin --template workspace --profile plugin-qa
 ```
 
 The generated project starts with an empty `src/blocks/*` workspace shell and is designed to grow through:
 
 ```bash
-wp-typia add block my-block --template basic
-wp-typia add integration-env local-smoke --wp-env --service docker-compose
-wp-typia add style callout-emphasis --block my-block
-wp-typia add transform quote-to-block --from core/quote --to my-block
-wp-typia add binding-source hero-data
-wp-typia add binding-source hero-data --block my-block --attribute headline
-wp-typia add contract external-retrieve-response --type ExternalRetrieveResponse
-wp-typia add post-meta integration-state --post-type post --type IntegrationStateMeta
-wp-typia add editor-plugin review-workflow --slot sidebar
-wp-typia add editor-plugin seo-notes --slot document-setting-panel
-wp-typia add hooked-block my-block --anchor core/post-content --position after
+npm run wp-typia:add -- block my-block --template basic
+npm run wp-typia:add -- integration-env local-smoke --wp-env --release-zip --service docker-compose
+npm run wp-typia:add -- style callout-emphasis --block my-block
+npm run wp-typia:add -- transform quote-to-block --from core/quote --to my-block
+npm run wp-typia:add -- binding-source hero-data
+npm run wp-typia:add -- binding-source hero-data --block my-block --attribute headline
+npm run wp-typia:add -- contract external-retrieve-response --type ExternalRetrieveResponse
+npm run wp-typia:add -- rest-resource external-record --manual --namespace legacy/v1 --route-pattern '/records/(?P<post_id>[\d]+)' --permission-callback legacy_can_read_records --controller-class Legacy\\Records\\Controller
+npm run wp-typia:add -- post-meta integration-state --post-type post --type IntegrationStateMeta
+npm run wp-typia:add -- editor-plugin review-workflow --slot sidebar
+npm run wp-typia:add -- editor-plugin seo-notes --slot document-setting-panel
+npm run wp-typia:add -- hooked-block my-block --anchor core/post-content --position after
 ```
+
+## CLI binary policy
+
+Official workspace projects install `wp-typia` as a local devDependency and
+expose package scripts for the common CLI entrypoints:
+
+```json
+{
+  "scripts": {
+    "sync-rest:package": "tsx scripts/sync-rest-contracts.ts --package",
+    "sync-rest:package:check": "tsx scripts/sync-rest-contracts.ts --package --check",
+    "wp-typia:sync": "wp-typia sync",
+    "wp-typia:doctor": "wp-typia doctor",
+    "wp-typia:doctor:workspace": "wp-typia doctor --workspace-only",
+    "wp-typia:add": "wp-typia add"
+  },
+  "devDependencies": {
+    "wp-typia": "<version>"
+  }
+}
+```
+
+## Minimal Workspace vs Plugin QA Profile
+
+Use the default workspace template when you want the smallest editable shell and
+plan to add QA infrastructure later. Use `--profile plugin-qa` when the plugin
+should start with local WordPress smoke checks, `.wp-env.json`, `.env.example`,
+`scripts/integration-smoke/local-smoke.mjs`, and release zip scripts.
+
+Existing minimal workspaces can adopt the same QA surface later:
+
+```bash
+npm run wp-typia:add -- integration-env local-smoke --wp-env --release-zip
+```
+
+Use the script form from generated workspaces so the executable CLI package is
+clearly separated from support packages such as `@wp-typia/project-tools`.
+
+Workspaces that ship REST resources can run `sync-rest:package` before release
+builds to copy generated runtime schemas into `inc/rest-schemas`. Add
+`sync-rest:package:check` to release CI so stale or missing packaged schemas are
+caught before a zip is built without TypeScript source files.
+
+The generated `inc/rest-schema.php` helper centralizes schema loading and
+WordPress REST sanitization. Generated REST resources use it automatically, and
+custom PHP resources can call
+`<phpPrefix>_get_wordpress_rest_schema( 'settings-response', array( 'resource' => 'settings' ) )`
+or `<phpPrefix>_validate_and_sanitize_rest_payload(...)` to reuse the same
+packaged/source lookup and `WP_Error` handling.
+
+Use generated REST resources when the workspace should own the PHP route glue.
+Use `wp-typia add rest-resource <name> --manual` for provider routes owned by
+another plugin, editor contract, or legacy controller. Manual routes can declare
+custom namespaces, `--path` or `--route-pattern` patterns with named captures,
+and route-owner metadata such as `--permission-callback`,
+`--controller-class`, and `--controller-extends` while still generating typed
+schemas, OpenAPI, clients, and drift checks.
+
+Manual settings contracts can model write-only credentials with
+`--secret-field <field>`. The generated request type marks the field as
+`tags.Secret<"has<Field>">` plus `tags.PreserveOnEmpty<true>`, response types
+expose only the safe has-value field, and generated admin settings screens omit
+blank secrets so existing stored values are preserved by default.
+
+| Package manager | Doctor                     | Sync check                         | Add a block                                               |
+| --------------- | -------------------------- | ---------------------------------- | --------------------------------------------------------- |
+| npm             | `npm run wp-typia:doctor`  | `npm run wp-typia:sync -- --check` | `npm run wp-typia:add -- block my-block --template basic` |
+| pnpm            | `pnpm run wp-typia:doctor` | `pnpm run wp-typia:sync --check`   | `pnpm run wp-typia:add block my-block --template basic`   |
+| bun             | `bun run wp-typia:doctor`  | `bun run wp-typia:sync --check`    | `bun run wp-typia:add block my-block --template basic`    |
+| yarn            | `yarn run wp-typia:doctor` | `yarn run wp-typia:sync --check`   | `yarn run wp-typia:add block my-block --template basic`   |
+
+Existing workspaces can adopt the same scripts without regenerating. Pin
+`wp-typia` to the project version you want CI to run, then use
+`wp-typia:doctor:workspace` when optional local runtimes should be advisory.

package/README.md.mustache

@@ -7,31 +7,84 @@
 This scaffold is the official empty `wp-typia` workspace shell. It starts with
 an empty `src/blocks/*` inventory and grows through `wp-typia add`.
 
+Use the minimal workspace when you want the smallest editable shell and plan to
+add QA infrastructure later. Scaffold with `--profile plugin-qa` when the plugin
+should start with local WordPress smoke checks, `.wp-env.json`, `.env.example`,
+`scripts/integration-smoke/local-smoke.mjs`, and release zip scripts. Existing
+minimal workspaces can adopt the same surface later:
+
+```bash
+bun run wp-typia:add integration-env local-smoke --wp-env --release-zip
+```
+
 ## First Block
 
 ```bash
-wp-typia add block counter-card --template basic
+bun run wp-typia:add block counter-card --template basic
 ```
 
 Persistence-ready blocks and compound parent/child blocks can be added later:
 
 ```bash
-wp-typia add block counter-card --template persistence --data-storage custom-table --persistence-policy authenticated
-wp-typia add block faq-stack --template compound --data-storage custom-table --persistence-policy public
+bun run wp-typia:add block counter-card --template persistence --data-storage custom-table --persistence-policy authenticated
+bun run wp-typia:add block faq-stack --template compound --data-storage custom-table --persistence-policy public
 ```
 
 Variations, block styles, transforms, patterns, REST resources, and post meta
 contracts can also be added after the first block exists:
 
 ```bash
-wp-typia add variation hero-card --block counter-card
-wp-typia add style callout-emphasis --block counter-card
-wp-typia add transform quote-to-counter --from core/quote --to counter-card
-wp-typia add pattern hero-layout
-wp-typia add rest-resource snapshots --namespace {{namespace}}/v1 --methods list,read,create
-wp-typia add post-meta integration-state --post-type post
+bun run wp-typia:add variation hero-card --block counter-card
+bun run wp-typia:add style callout-emphasis --block counter-card
+bun run wp-typia:add transform quote-to-counter --from core/quote --to counter-card
+bun run wp-typia:add pattern hero-layout
+bun run wp-typia:add rest-resource snapshots --namespace {{namespace}}/v1 --methods list,read,create
+bun run wp-typia:add rest-resource external-record --manual --namespace legacy/v1 --route-pattern '/records/(?P<post_id>[\d]+)' --permission-callback legacy_can_read_records --controller-class Legacy\\Records\\Controller
+bun run wp-typia:add post-meta integration-state --post-type post
+```
+
+## CLI Commands
+
+This workspace installs the executable `wp-typia` CLI as a local devDependency
+and exposes stable package scripts so support packages are not confused with the
+binary package:
+
+```bash
+bun run wp-typia:doctor
+bun run wp-typia:doctor:workspace
+bun run wp-typia:sync --check
+bun run sync-rest:package:check
+bun run wp-typia:add block counter-card --template basic
 ```
 
+Use `wp-typia:doctor:workspace` in CI when optional local runtimes are advisory
+but workspace checks must still fail the job.
+
+Run `sync-rest:package` before building release zips when REST resources are
+registered. It copies generated runtime schemas into `inc/rest-schemas` and
+`sync-rest:package:check` fails CI if packaged schemas are missing or stale.
+
+The generated `inc/rest-schema.php` helper centralizes schema loading and
+WordPress REST sanitization. Generated REST resources use it automatically, and
+custom PHP resources can call
+`{{phpPrefix}}_get_wordpress_rest_schema( 'settings-response', array( 'resource' => 'settings' ) )`
+or `{{phpPrefix}}_validate_and_sanitize_rest_payload(...)` to reuse the same
+packaged/source lookup and `WP_Error` handling.
+
+Use generated REST resources when the workspace should own the PHP route glue.
+Use `wp-typia add rest-resource <name> --manual` for provider routes owned by
+another plugin, editor contract, or legacy controller. Manual routes can declare
+custom namespaces, `--path` or `--route-pattern` patterns with named captures,
+and route-owner metadata such as `--permission-callback`,
+`--controller-class`, and `--controller-extends` while still generating typed
+schemas, OpenAPI, clients, and drift checks.
+
+Manual settings contracts can model write-only credentials with
+`--secret-field <field>`. The generated request type marks the field as
+`tags.Secret<"has<Field>">` plus `tags.PreserveOnEmpty<true>`, response types
+expose only the safe has-value field, and generated admin settings screens omit
+blank secrets so existing stored values are preserved by default.
+
 ## Development
 
 ```bash

package/inc/rest-schema.php.mustache

@@ -0,0 +1,184 @@
+<?php
+if ( ! defined( 'ABSPATH' ) ) {
+	return;
+}
+
+if ( ! function_exists( '{{phpPrefix}}_is_valid_rest_schema_key' ) ) {
+	function {{phpPrefix}}_is_valid_rest_schema_key( $value ) {
+		return is_string( $value ) && 1 === preg_match( '/\A[A-Za-z0-9_-]+\z/', $value );
+	}
+}
+
+if ( ! function_exists( '{{phpPrefix}}_is_valid_rest_resource_slug' ) ) {
+	function {{phpPrefix}}_is_valid_rest_resource_slug( $value ) {
+		return is_string( $value ) && 1 === preg_match( '/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/', $value );
+	}
+}
+
+if ( ! function_exists( '{{phpPrefix}}_resolve_rest_schema_paths' ) ) {
+	function {{phpPrefix}}_resolve_rest_schema_paths( $schema_name, $options = array() ) {
+		if ( ! {{phpPrefix}}_is_valid_rest_schema_key( $schema_name ) ) {
+			return new WP_Error(
+				'invalid_rest_schema_name',
+				'Invalid REST schema name.',
+				array( 'status' => 500 )
+			);
+		}
+
+		$options      = is_array( $options ) ? $options : array();
+		$project_root = dirname( __DIR__ );
+		$paths        = array();
+
+		if ( isset( $options['resource'] ) && '' !== $options['resource'] ) {
+			if ( ! {{phpPrefix}}_is_valid_rest_resource_slug( $options['resource'] ) ) {
+				return new WP_Error(
+					'invalid_rest_schema_resource',
+					'Invalid REST schema resource slug.',
+					array( 'status' => 500 )
+				);
+			}
+
+			$resource_slug = $options['resource'];
+			$paths[]       = __DIR__ . '/rest-schemas/rest/' . $resource_slug . '/' . $schema_name . '.schema.json';
+			$paths[]       = $project_root . '/src/rest/' . $resource_slug . '/api-schemas/' . $schema_name . '.schema.json';
+		}
+
+		if ( isset( $options['paths'] ) && is_array( $options['paths'] ) ) {
+			foreach ( $options['paths'] as $schema_path ) {
+				if ( is_string( $schema_path ) && '' !== $schema_path && ! in_array( $schema_path, $paths, true ) ) {
+					$paths[] = $schema_path;
+				}
+			}
+		}
+
+		return $paths;
+	}
+}
+
+if ( ! function_exists( '{{phpPrefix}}_load_rest_schema' ) ) {
+	function {{phpPrefix}}_load_rest_schema( $schema_name, $options = array() ) {
+		$schema_paths = {{phpPrefix}}_resolve_rest_schema_paths( $schema_name, $options );
+		if ( is_wp_error( $schema_paths ) ) {
+			return $schema_paths;
+		}
+
+		foreach ( $schema_paths as $schema_path ) {
+			if ( ! is_file( $schema_path ) ) {
+				continue;
+			}
+
+			if ( ! is_readable( $schema_path ) ) {
+				return new WP_Error(
+					'unreadable_rest_schema',
+					'Generated REST schema is not readable.',
+					array(
+						'path'   => $schema_path,
+						'status' => 500,
+					)
+				);
+			}
+
+			$schema_json = file_get_contents( $schema_path );
+			if ( false === $schema_json ) {
+				return new WP_Error(
+					'rest_schema_read_failed',
+					'Generated REST schema could not be read.',
+					array(
+						'path'   => $schema_path,
+						'status' => 500,
+					)
+				);
+			}
+
+			$decoded = json_decode( $schema_json, true );
+			if ( ! is_array( $decoded ) ) {
+				return new WP_Error(
+					'malformed_rest_schema',
+					'Generated REST schema contains malformed JSON.',
+					array(
+						'json_error' => json_last_error_msg(),
+						'path'       => $schema_path,
+						'status'     => 500,
+					)
+				);
+			}
+
+			return $decoded;
+		}
+
+		return new WP_Error(
+			'missing_rest_schema',
+			'Generated REST schema could not be found.',
+			array(
+				'paths'  => $schema_paths,
+				'schema' => $schema_name,
+				'status' => 500,
+			)
+		);
+	}
+}
+
+if ( ! function_exists( '{{phpPrefix}}_prepare_rest_schema_for_wordpress' ) ) {
+	function {{phpPrefix}}_prepare_rest_schema_for_wordpress( $schema ) {
+		if ( ! is_array( $schema ) ) {
+			return $schema;
+		}
+
+		unset( $schema['$schema'], $schema['title'] );
+
+		foreach ( array( 'properties', 'patternProperties', 'definitions', '$defs' ) as $schema_map_key ) {
+			if ( ! isset( $schema[ $schema_map_key ] ) || ! is_array( $schema[ $schema_map_key ] ) ) {
+				continue;
+			}
+
+			foreach ( $schema[ $schema_map_key ] as $key => $property_schema ) {
+				$schema[ $schema_map_key ][ $key ] = {{phpPrefix}}_prepare_rest_schema_for_wordpress( $property_schema );
+			}
+		}
+
+		foreach ( array( 'items', 'additionalProperties', 'contains', 'propertyNames', 'not', 'if', 'then', 'else' ) as $nested_schema_key ) {
+			if ( isset( $schema[ $nested_schema_key ] ) && is_array( $schema[ $nested_schema_key ] ) ) {
+				$schema[ $nested_schema_key ] = {{phpPrefix}}_prepare_rest_schema_for_wordpress( $schema[ $nested_schema_key ] );
+			}
+		}
+
+		foreach ( array( 'allOf', 'anyOf', 'oneOf' ) as $schema_list_key ) {
+			if ( ! isset( $schema[ $schema_list_key ] ) || ! is_array( $schema[ $schema_list_key ] ) ) {
+				continue;
+			}
+
+			foreach ( $schema[ $schema_list_key ] as $index => $variant_schema ) {
+				$schema[ $schema_list_key ][ $index ] = {{phpPrefix}}_prepare_rest_schema_for_wordpress( $variant_schema );
+			}
+		}
+
+		return $schema;
+	}
+}
+
+if ( ! function_exists( '{{phpPrefix}}_get_wordpress_rest_schema' ) ) {
+	function {{phpPrefix}}_get_wordpress_rest_schema( $schema_name, $options = array() ) {
+		$schema = {{phpPrefix}}_load_rest_schema( $schema_name, $options );
+		if ( is_wp_error( $schema ) ) {
+			return $schema;
+		}
+
+		return {{phpPrefix}}_prepare_rest_schema_for_wordpress( $schema );
+	}
+}
+
+if ( ! function_exists( '{{phpPrefix}}_validate_and_sanitize_rest_payload' ) ) {
+	function {{phpPrefix}}_validate_and_sanitize_rest_payload( $value, $schema_name, $param_name, $options = array() ) {
+		$rest_schema = {{phpPrefix}}_get_wordpress_rest_schema( $schema_name, $options );
+		if ( is_wp_error( $rest_schema ) ) {
+			return $rest_schema;
+		}
+
+		$validation = rest_validate_value_from_schema( $value, $rest_schema, $param_name );
+		if ( is_wp_error( $validation ) ) {
+			return $validation;
+		}
+
+		return rest_sanitize_value_from_schema( $value, $rest_schema, $param_name );
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/create-workspace-template",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Official empty wp-typia workspace template package",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -8,6 +8,7 @@
     "package.json.mustache",
     "tsconfig.json.mustache",
     "webpack.config.js.mustache",
+    "inc/",
     "scripts/",
     "src/",
     "languages/",

package/package.json.mustache

@@ -9,6 +9,12 @@
     "sync": "tsx scripts/sync-project.ts",
     "sync-types": "tsx scripts/sync-types-to-block-json.ts",
     "sync-rest": "tsx scripts/sync-rest-contracts.ts",
+    "sync-rest:package": "tsx scripts/sync-rest-contracts.ts --package",
+    "sync-rest:package:check": "tsx scripts/sync-rest-contracts.ts --package --check",
+    "wp-typia:sync": "wp-typia sync",
+    "wp-typia:doctor": "wp-typia doctor",
+    "wp-typia:doctor:workspace": "wp-typia doctor --workspace-only",
+    "wp-typia:add": "wp-typia add",
     "build": "bun run sync --check && node scripts/build-workspace.mjs build",
     "start": "bun run sync && node scripts/build-workspace.mjs start",
     "dev": "bun run start",
@@ -31,6 +37,7 @@
     "@wp-typia/block-types": "{{blockTypesPackageVersion}}",
     "@wp-typia/project-tools": "{{projectToolsPackageVersion}}",
     "@wp-typia/rest": "{{restPackageVersion}}",
+    "wp-typia": "{{wpTypiaPackageVersion}}",
     "@typia/unplugin": "^12.0.1",
     "@types/node": "^24.5.2",
     "@types/wordpress__block-editor": "^11.5.17",

package/scripts/block-config.ts.mustache

@@ -63,6 +63,7 @@ export interface WorkspaceRestResourceBaseConfig {
 		typeof import( '@wp-typia/block-runtime/metadata-core' ).defineEndpointManifest
 	>;
 	secretFieldName?: string;
+	secretPreserveOnEmpty?: boolean;
 	secretStateFieldName?: string;
 	slug: string;
 	typesFile: string;
@@ -114,6 +115,11 @@ export interface WorkspaceAdminViewConfig {
 	source?: string;
 }
 
+export interface WorkspaceRestSchemaPackageConfig {
+	manifestFile?: string;
+	outputDir: string;
+}
+
 export const BLOCKS: WorkspaceBlockConfig[] = [
 	// wp-typia add block entries
 ];
@@ -157,3 +163,8 @@ export const EDITOR_PLUGINS: WorkspaceEditorPluginConfig[] = [
 export const ADMIN_VIEWS: WorkspaceAdminViewConfig[] = [
 	// wp-typia add admin-view entries
 ];
+
+export const REST_SCHEMA_PACKAGE: WorkspaceRestSchemaPackageConfig = {
+	manifestFile: 'inc/rest-schemas/manifest.json',
+	outputDir: 'inc/rest-schemas',
+};

package/scripts/sync-rest-contracts.ts.mustache

@@ -1,4 +1,5 @@
 /* eslint-disable no-console */
+import { promises as fsp } from 'node:fs';
 import path from 'node:path';
 
 import {
@@ -8,6 +9,7 @@ import {
 	syncTypeSchemas,
 } from '@wp-typia/block-runtime/metadata-core';
 
+import * as workspaceConfig from './block-config';
 import {
 	BLOCKS,
 	CONTRACTS,
@@ -19,9 +21,25 @@ import {
 	type WorkspaceRestResourceConfig,
 } from './block-config';
 
+type WorkspaceRestSchemaPackageConfig = {
+	manifestFile?: string;
+	outputDir: string;
+};
+
+const DEFAULT_REST_SCHEMA_PACKAGE: WorkspaceRestSchemaPackageConfig = {
+	manifestFile: 'inc/rest-schemas/manifest.json',
+	outputDir: 'inc/rest-schemas',
+};
+const workspaceConfigWithPackage = workspaceConfig as {
+	REST_SCHEMA_PACKAGE?: WorkspaceRestSchemaPackageConfig;
+};
+const REST_SCHEMA_PACKAGE =
+	workspaceConfigWithPackage.REST_SCHEMA_PACKAGE ?? DEFAULT_REST_SCHEMA_PACKAGE;
+
 function parseCliOptions( argv: string[] ) {
 	const options = {
 		check: false,
+		packageSchemas: false,
 	};
 
 	for ( const argument of argv ) {
@@ -30,12 +48,110 @@ function parseCliOptions( argv: string[] ) {
 			continue;
 		}
 
+		if ( argument === '--package' ) {
+			options.packageSchemas = true;
+			continue;
+		}
+
 		throw new Error( `Unknown sync-rest flag: ${ argument }` );
 	}
 
 	return options;
 }
 
+type RuntimeRestSchemaPackageEntry = {
+	id: string;
+	kind: 'block' | 'rest-resource';
+	owner: string;
+	path: string;
+	schema: string;
+	source: string;
+};
+
+type RuntimeRestSchemaPackageManifest = {
+	generatedBy: 'wp-typia sync-rest --package';
+	outputDir: string;
+	schemaVersion: 1;
+	schemas: RuntimeRestSchemaPackageEntry[];
+};
+
+function getNodeErrorCode( error: unknown ) {
+	return typeof error === 'object' &&
+		error !== null &&
+		'code' in error &&
+		typeof ( error as { code?: unknown } ).code === 'string'
+		? ( error as { code: string } ).code
+		: undefined;
+}
+
+function normalizeProjectPath( filePath: string, label: string ) {
+	if ( path.isAbsolute( filePath ) ) {
+		throw new Error( `${ label } must be project-relative: ${ filePath }` );
+	}
+
+	const normalized = path.normalize( filePath );
+	if ( normalized === '..' || normalized.startsWith( `..${ path.sep }` ) ) {
+		throw new Error( `${ label } cannot point outside the project: ${ filePath }` );
+	}
+
+	return normalized.split( path.sep ).join( '/' );
+}
+
+function resolveRestSchemaPackageConfig() {
+	const outputDir = normalizeProjectPath(
+		REST_SCHEMA_PACKAGE.outputDir,
+		'REST_SCHEMA_PACKAGE.outputDir'
+	);
+	const manifestFile = normalizeProjectPath(
+		REST_SCHEMA_PACKAGE.manifestFile ?? path.join( outputDir, 'manifest.json' ),
+		'REST_SCHEMA_PACKAGE.manifestFile'
+	);
+
+	if ( outputDir === '.' ) {
+		throw new Error(
+			'REST_SCHEMA_PACKAGE.outputDir must not be the project root; use a dedicated subdirectory such as "inc/rest-schemas".'
+		);
+	}
+
+	if ( manifestFile === outputDir || ! manifestFile.startsWith( `${ outputDir }/` ) ) {
+		throw new Error(
+			`REST_SCHEMA_PACKAGE.manifestFile must stay inside REST_SCHEMA_PACKAGE.outputDir (${ outputDir }): ${ manifestFile }`
+		);
+	}
+
+	return {
+		manifestFile,
+		outputDir,
+	};
+}
+
+function assertSafeSchemaBaseName( baseName: string, owner: string ) {
+	if (
+		! /^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test( baseName ) ||
+		baseName === '.' ||
+		baseName === '..'
+	) {
+		throw new Error(
+			`${ owner }: REST schema contract key must be a file basename containing only letters, numbers, dots, underscores, or hyphens: ${ baseName }`
+		);
+	}
+}
+
+function getPackagePath( outputDir: string, owner: string, ...segments: string[] ) {
+	const packagePath = normalizeProjectPath(
+		path.join( outputDir, ...segments ),
+		'REST schema package path'
+	);
+
+	if ( ! packagePath.startsWith( `${ outputDir }/` ) ) {
+		throw new Error(
+			`${ owner }: REST schema package path must stay inside ${ outputDir }: ${ packagePath }`
+		);
+	}
+
+	return packagePath;
+}
+
 function isRestEnabledBlock(
 	block: WorkspaceBlockConfig
 ): block is WorkspaceBlockConfig & {
@@ -98,6 +214,307 @@ function isWorkspacePostMetaContract(
 	);
 }
 
+function getBlockRestSchemaEntries(
+	block: WorkspaceBlockConfig & {
+		restManifest: NonNullable< WorkspaceBlockConfig[ 'restManifest' ] >;
+	},
+	outputDir: string
+): RuntimeRestSchemaPackageEntry[] {
+	return Object.keys( block.restManifest.contracts ).map( ( baseName ) => {
+		const owner = `Block ${ block.slug }`;
+		assertSafeSchemaBaseName( baseName, owner );
+
+		return {
+			id: `block:${ block.slug }:${ baseName }`,
+			kind: 'block',
+			owner: block.slug,
+			path: getPackagePath(
+				outputDir,
+				owner,
+				'blocks',
+				block.slug,
+				`${ baseName }.schema.json`
+			),
+			schema: baseName,
+			source: normalizeProjectPath(
+				path.join(
+					'src',
+					'blocks',
+					block.slug,
+					'api-schemas',
+					`${ baseName }.schema.json`
+				),
+				'REST schema source path'
+			),
+		};
+	} );
+}
+
+function getRestResourceSchemaEntries(
+	resource: WorkspaceRestResourceConfig & {
+		restManifest: NonNullable< WorkspaceRestResourceConfig[ 'restManifest' ] >;
+		typesFile: string;
+	},
+	outputDir: string
+): RuntimeRestSchemaPackageEntry[] {
+	return Object.keys( resource.restManifest.contracts ).map( ( baseName ) => {
+		const owner = `REST resource ${ resource.slug }`;
+		assertSafeSchemaBaseName( baseName, owner );
+
+		return {
+			id: `rest:${ resource.slug }:${ baseName }`,
+			kind: 'rest-resource',
+			owner: resource.slug,
+			path: getPackagePath(
+				outputDir,
+				owner,
+				'rest',
+				resource.slug,
+				`${ baseName }.schema.json`
+			),
+			schema: baseName,
+			source: normalizeProjectPath(
+				path.join(
+					path.dirname( resource.typesFile ),
+					'api-schemas',
+					`${ baseName }.schema.json`
+				),
+				'REST schema source path'
+			),
+		};
+	} );
+}
+
+function buildRuntimeRestSchemaPackageManifest(
+	restBlocks: Array<
+		WorkspaceBlockConfig & {
+			restManifest: NonNullable< WorkspaceBlockConfig[ 'restManifest' ] >;
+		}
+	>,
+	restResources: Array<
+		WorkspaceRestResourceConfig & {
+			restManifest: NonNullable< WorkspaceRestResourceConfig[ 'restManifest' ] >;
+			typesFile: string;
+		}
+	>
+): RuntimeRestSchemaPackageManifest {
+	const { outputDir } = resolveRestSchemaPackageConfig();
+	const schemas = [
+		...restBlocks.flatMap( ( block ) =>
+			getBlockRestSchemaEntries( block, outputDir )
+		),
+		...restResources.flatMap( ( resource ) =>
+			getRestResourceSchemaEntries( resource, outputDir )
+		),
+	].sort(
+		( left, right ) =>
+			left.path.localeCompare( right.path ) || left.id.localeCompare( right.id )
+	);
+	const seenPaths = new Set< string >();
+	const seenIds = new Set< string >();
+
+	for ( const schema of schemas ) {
+		if ( seenIds.has( schema.id ) ) {
+			throw new Error( `Duplicate runtime REST schema package id: ${ schema.id }` );
+		}
+
+		if ( seenPaths.has( schema.path ) ) {
+			throw new Error(
+				`Duplicate runtime REST schema package path: ${ schema.path }`
+			);
+		}
+
+		seenIds.add( schema.id );
+		seenPaths.add( schema.path );
+	}
+
+	return {
+		generatedBy: 'wp-typia sync-rest --package',
+		outputDir,
+		schemaVersion: 1,
+		schemas,
+	};
+}
+
+async function readUtf8IfExists( filePath: string ) {
+	try {
+		return await fsp.readFile( filePath, 'utf8' );
+	} catch ( error ) {
+		if ( getNodeErrorCode( error ) === 'ENOENT' ) {
+			return undefined;
+		}
+
+		throw error;
+	}
+}
+
+async function writeUtf8IfChanged( filePath: string, content: string ) {
+	const existing = await readUtf8IfExists( filePath );
+	if ( existing === content ) {
+		return;
+	}
+
+	await fsp.mkdir( path.dirname( filePath ), { recursive: true } );
+	await fsp.writeFile( filePath, content, 'utf8' );
+}
+
+async function unlinkIfExists( filePath: string ) {
+	try {
+		await fsp.unlink( filePath );
+	} catch ( error ) {
+		if ( getNodeErrorCode( error ) === 'ENOENT' ) {
+			return;
+		}
+
+		throw error;
+	}
+}
+
+async function collectPackagedSchemaFiles( outputDir: string ) {
+	const schemaFiles: string[] = [];
+
+	async function walk( relativeDir: string ) {
+		const currentDir =
+			relativeDir.length > 0 ? path.join( outputDir, relativeDir ) : outputDir;
+		let directoryEntries: import( 'node:fs' ).Dirent[];
+
+		try {
+			directoryEntries = await fsp.readdir( currentDir, {
+				withFileTypes: true,
+			} );
+		} catch ( error ) {
+			if ( getNodeErrorCode( error ) === 'ENOENT' ) {
+				return;
+			}
+
+			throw error;
+		}
+
+		for ( const directoryEntry of directoryEntries ) {
+			const relativePath = path.join( relativeDir, directoryEntry.name );
+
+			if ( directoryEntry.isDirectory() ) {
+				await walk( relativePath );
+				continue;
+			}
+
+			if (
+				directoryEntry.isFile() &&
+				directoryEntry.name.endsWith( '.schema.json' )
+			) {
+				schemaFiles.push(
+					normalizeProjectPath(
+						path.join( outputDir, relativePath ),
+						'REST schema package file'
+					)
+				);
+			}
+		}
+	}
+
+	await walk( '' );
+	return schemaFiles.sort();
+}
+
+async function syncRuntimeRestSchemaPackage(
+	restBlocks: Array<
+		WorkspaceBlockConfig & {
+			restManifest: NonNullable< WorkspaceBlockConfig[ 'restManifest' ] >;
+		}
+	>,
+	restResources: Array<
+		WorkspaceRestResourceConfig & {
+			restManifest: NonNullable< WorkspaceRestResourceConfig[ 'restManifest' ] >;
+			typesFile: string;
+		}
+	>,
+	options: { check: boolean }
+) {
+	const { manifestFile, outputDir } = resolveRestSchemaPackageConfig();
+	const manifest = buildRuntimeRestSchemaPackageManifest(
+		restBlocks,
+		restResources
+	);
+	const manifestContent = `${ JSON.stringify( manifest, null, 2 ) }\n`;
+	const expectedPackagePaths = new Set(
+		manifest.schemas.map( ( schema ) => schema.path )
+	);
+	const packageFailures: string[] = [];
+
+	for ( const schema of manifest.schemas ) {
+		const sourceContent = await readUtf8IfExists( schema.source );
+
+		if ( sourceContent === undefined ) {
+			if ( ! options.check ) {
+				throw new Error(
+					`Runtime REST schema source is missing: ${ schema.source }\nRun \`sync-rest\` before \`sync-rest --package\` to generate source schemas.`
+				);
+			}
+
+			packageFailures.push( `${ schema.source } (source missing)` );
+			continue;
+		}
+
+		if ( options.check ) {
+			const packagedContent = await readUtf8IfExists( schema.path );
+
+			if ( packagedContent === undefined ) {
+				packageFailures.push( `${ schema.path } (missing)` );
+				continue;
+			}
+
+			if ( packagedContent !== sourceContent ) {
+				packageFailures.push( `${ schema.path } (stale)` );
+			}
+
+			continue;
+		}
+
+		await writeUtf8IfChanged( schema.path, sourceContent );
+	}
+
+	const existingPackagedSchemas = await collectPackagedSchemaFiles( outputDir );
+	for ( const schemaPath of existingPackagedSchemas ) {
+		if ( expectedPackagePaths.has( schemaPath ) ) {
+			continue;
+		}
+
+		if ( options.check ) {
+			packageFailures.push( `${ schemaPath } (unexpected)` );
+			continue;
+		}
+
+		await unlinkIfExists( schemaPath );
+	}
+
+	if ( options.check ) {
+		const existingManifestContent = await readUtf8IfExists( manifestFile );
+
+		if ( existingManifestContent === undefined ) {
+			if ( manifest.schemas.length > 0 ) {
+				packageFailures.push( `${ manifestFile } (missing)` );
+			}
+		} else if ( existingManifestContent !== manifestContent ) {
+			packageFailures.push( `${ manifestFile } (stale)` );
+		}
+
+		if ( packageFailures.length > 0 ) {
+			throw new Error(
+				`Runtime REST schema package is missing or stale:\n${ packageFailures
+					.map( ( failure ) => `- ${ failure }` )
+					.join(
+						'\n'
+					) }\nRun \`sync-rest --package\` to refresh packaged REST schemas before building a release zip.`
+			);
+		}
+
+		return manifest.schemas.length;
+	}
+
+	await writeUtf8IfChanged( manifestFile, manifestContent );
+	return manifest.schemas.length;
+}
+
 async function assertTypeArtifactsCurrent( block: WorkspaceBlockConfig ) {
 	const report = await runSyncBlockMetadata(
 		{
@@ -139,6 +556,22 @@ async function main() {
 		postMetaContracts.length === 0 &&
 		restResources.length === 0
 	) {
+		if ( options.packageSchemas ) {
+			const packagedSchemaCount = await syncRuntimeRestSchemaPackage(
+				restBlocks,
+				restResources,
+				{
+					check: options.check,
+				}
+			);
+
+			console.log(
+				options.check
+					? `✅ Runtime REST schema package is already up to date (${ packagedSchemaCount } schemas).`
+					: `✅ Runtime REST schema package generated (${ packagedSchemaCount } schemas).`
+			);
+		}
+
 		console.log(
 			options.check
 				? 'ℹ️ No REST-enabled workspace blocks, standalone contracts, post meta contracts, or plugin-level REST resources are registered yet. `sync-rest --check` is already clean.'
@@ -281,6 +714,22 @@ async function main() {
 		);
 	}
 
+	if ( options.packageSchemas ) {
+		const packagedSchemaCount = await syncRuntimeRestSchemaPackage(
+			restBlocks,
+			restResources,
+			{
+				check: options.check,
+			}
+		);
+
+		console.log(
+			options.check
+				? `✅ Runtime REST schema package is already up to date (${ packagedSchemaCount } schemas).`
+				: `✅ Runtime REST schema package generated (${ packagedSchemaCount } schemas).`
+		);
+	}
+
 	console.log(
 		options.check
 			? '✅ REST contract schemas, standalone schemas, post meta schemas, portable API clients, and endpoint-aware OpenAPI documents are already up to date for workspace blocks, standalone contracts, post meta contracts, and plugin-level resources!'

package/{{slugKebabCase}}.php.mustache

@@ -17,6 +17,15 @@ if ( ! defined( 'ABSPATH' ) ) {
 	exit;
 }
 
+function {{phpPrefix}}_load_rest_schema_helpers() {
+	$helper_path = __DIR__ . '/inc/rest-schema.php';
+	if ( is_readable( $helper_path ) ) {
+		require_once $helper_path;
+	}
+}
+
+{{phpPrefix}}_load_rest_schema_helpers();
+
 foreach ( glob( __DIR__ . '/src/blocks/*/server.php' ) ?: array() as $server_module ) {
 	require_once $server_module;
 }