@wp-typia/project-tools 0.15.4 → 0.16.1

package/dist/runtime/cli-help.js

@@ -34,7 +34,7 @@ Package managers: ${PACKAGE_MANAGER_IDS.join(", ")}
 Notes:
   \`wp-typia create\` is the canonical scaffold command.
   \`wp-typia <project-dir>\` remains a backward-compatible alias to \`create\`.
-  Use \`--template @wp-typia/create-workspace-template\` for the official empty workspace scaffold behind \`wp-typia add ...\`.
+  Use \`--template workspace\` as shorthand for \`@wp-typia/create-workspace-template\`, the official empty workspace scaffold behind \`wp-typia add ...\`.
   \`add variation\` uses an existing workspace block from \`scripts/block-config.ts\`.
   \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.

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

@@ -10,6 +10,7 @@ interface GetNextStepsOptions {
     templateId: string;
 }
 interface GetOptionalOnboardingOptions {
+    availableScripts?: string[];
     packageManager: PackageManagerId;
     templateId: string;
     compoundPersistenceEnabled?: boolean;
@@ -60,7 +61,7 @@ export declare function getNextSteps({ projectInput, projectDir, packageManager,
  * @param options Package-manager and template context for optional guidance.
  * @returns Optional onboarding note and step list.
  */
-export declare function getOptionalOnboarding({ packageManager, templateId, compoundPersistenceEnabled, }: GetOptionalOnboardingOptions): OptionalOnboardingGuidance;
+export declare function getOptionalOnboarding({ availableScripts, packageManager, templateId, compoundPersistenceEnabled, }: GetOptionalOnboardingOptions): OptionalOnboardingGuidance;
 /**
  * Resolve scaffold options, prompts, and follow-up steps for one CLI run.
  *

package/dist/runtime/cli-scaffold.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { collectScaffoldAnswers, DATA_STORAGE_MODES, PERSISTENCE_POLICIES, isDataStorageMode, isPersistencePolicy, resolvePackageManagerId, resolveTemplateId, scaffoldProject, } from "./scaffold.js";
 import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
@@ -79,10 +80,14 @@ export function getNextSteps({ projectInput, projectDir, packageManager, noInsta
  * @param options Package-manager and template context for optional guidance.
  * @returns Optional onboarding note and step list.
  */
-export function getOptionalOnboarding({ packageManager, templateId, compoundPersistenceEnabled = false, }) {
+export function getOptionalOnboarding({ availableScripts, packageManager, templateId, compoundPersistenceEnabled = false, }) {
     return {
-        note: getOptionalOnboardingNote(packageManager, templateId),
+        note: getOptionalOnboardingNote(packageManager, templateId, {
+            availableScripts,
+            compoundPersistenceEnabled,
+        }),
         steps: getOptionalOnboardingSteps(packageManager, templateId, {
+            availableScripts,
             compoundPersistenceEnabled,
         }),
     };
@@ -185,8 +190,24 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
         withTestPreset: resolvedWithTestPreset,
         withWpEnv: resolvedWithWpEnv,
     });
+    let availableScripts;
+    try {
+        const parsedPackageJson = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8"));
+        const scripts = parsedPackageJson.scripts &&
+            typeof parsedPackageJson.scripts === "object" &&
+            !Array.isArray(parsedPackageJson.scripts)
+            ? parsedPackageJson.scripts
+            : {};
+        availableScripts = Object.entries(scripts)
+            .filter(([, value]) => typeof value === "string")
+            .map(([scriptName]) => scriptName);
+    }
+    catch {
+        availableScripts = undefined;
+    }
     return {
         optionalOnboarding: getOptionalOnboarding({
+            availableScripts,
             packageManager: resolvedPackageManager,
             templateId: resolvedTemplateId,
             compoundPersistenceEnabled: result.variables.compoundPersistenceEnabled === "true",

package/dist/runtime/scaffold-onboarding.d.ts

@@ -1,5 +1,6 @@
 import type { PackageManagerId } from "./package-managers.js";
 interface SyncOnboardingOptions {
+    availableScripts?: string[];
     compoundPersistenceEnabled?: boolean;
 }
 interface PhpRestExtensionOptions extends SyncOnboardingOptions {
@@ -16,7 +17,7 @@ export declare function getOptionalOnboardingSteps(packageManager: PackageManage
 /**
  * Returns the onboarding note explaining when manual sync is optional.
  */
-export declare function getOptionalOnboardingNote(packageManager: PackageManagerId, templateId?: string): string;
+export declare function getOptionalOnboardingNote(packageManager: PackageManagerId, templateId?: string, options?: SyncOnboardingOptions): string;
 /**
  * Returns source-of-truth guidance for generated artifacts by template mode.
  */

package/dist/runtime/scaffold-onboarding.js

@@ -1,5 +1,6 @@
 import { formatRunScript } from "./package-managers.js";
 import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
 function templateHasPersistenceSync(templateId, { compoundPersistenceEnabled = false } = {}) {
     return templateId === "persistence" || (templateId === "compound" && compoundPersistenceEnabled);
 }
@@ -7,9 +8,19 @@ function templateHasPersistenceSync(templateId, { compoundPersistenceEnabled = f
  * Returns the optional sync script names to suggest for a template.
  */
 export function getOptionalSyncScriptNames(templateId, options = {}) {
-    return templateHasPersistenceSync(templateId, options)
-        ? ["sync-types", "sync-rest"]
-        : ["sync-types"];
+    const availableScripts = new Set(options.availableScripts ?? []);
+    if (availableScripts.has("sync")) {
+        return ["sync"];
+    }
+    const fallbackScripts = ["sync-types", "sync-rest"].filter((scriptName) => availableScripts.has(scriptName));
+    if (fallbackScripts.length > 0) {
+        return fallbackScripts;
+    }
+    if (!isBuiltInTemplateId(templateId) &&
+        templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        return [];
+    }
+    return ["sync"];
 }
 /**
  * Formats optional onboarding sync commands for the selected package manager.
@@ -20,15 +31,33 @@ export function getOptionalOnboardingSteps(packageManager, templateId, options =
 /**
  * Returns the onboarding note explaining when manual sync is optional.
  */
-export function getOptionalOnboardingNote(packageManager, templateId = "basic") {
+export function getOptionalOnboardingNote(packageManager, templateId = "basic", options = {}) {
+    const optionalSyncScripts = getOptionalSyncScriptNames(templateId, options);
+    const hasUnifiedSync = optionalSyncScripts.includes("sync");
+    const syncSteps = optionalSyncScripts.map((scriptName) => formatRunScript(packageManager, scriptName));
     const developmentScript = getPrimaryDevelopmentScript(templateId);
+    const syncCommand = formatRunScript(packageManager, hasUnifiedSync ? "sync" : "sync-types");
+    const syncCheckCommand = formatRunScript(packageManager, hasUnifiedSync ? "sync" : "sync-types", "--check");
     const failOnLossySyncCommand = formatRunScript(packageManager, "sync-types", "--fail-on-lossy");
     const syncTypesCommand = formatRunScript(packageManager, "sync-types");
+    const syncRestCommand = formatRunScript(packageManager, "sync-rest");
     const typecheckCommand = formatRunScript(packageManager, "typecheck");
     const strictSyncCommand = formatRunScript(packageManager, "sync-types", "--strict --report json");
+    const advancedPersistenceNote = templateHasPersistenceSync(templateId, options)
+        ? ` ${syncRestCommand} remains available for advanced REST-only refreshes, but it now fails fast when type-derived artifacts are stale; run \`${syncCommand}\` or \`${syncTypesCommand}\` first.`
+        : "";
+    const fallbackCustomTemplateNote = !hasUnifiedSync &&
+        syncSteps.length > 0 &&
+        !isBuiltInTemplateId(templateId) &&
+        templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        ? `Run ${syncSteps.join(" then ")} manually before build, typecheck, or commit. ${syncCheckCommand} verifies the current type-derived artifacts without rewriting them.${optionalSyncScripts.includes("sync-rest") ? ` ${syncRestCommand} remains available for REST-only refreshes after ${syncTypesCommand}.` : ""}`
+        : null;
+    if (fallbackCustomTemplateNote) {
+        return fallbackCustomTemplateNote;
+    }
     return `${formatRunScript(packageManager, developmentScript)} ${developmentScript === "dev"
         ? "watches the relevant sync scripts during local development."
-        : "remains the primary local entry point."} ${formatRunScript(packageManager, "start")} still runs one-shot syncs before starting, while ${formatRunScript(packageManager, "build")} and ${typecheckCommand} verify that generated metadata/schema artifacts are already current and fail if they are stale. Run the sync scripts manually when you want to refresh generated artifacts before build, typecheck, or commit. ${syncTypesCommand} stays warn-only by default; use \`${failOnLossySyncCommand}\` to fail only on lossy WordPress projections, or \`${strictSyncCommand}\` for a CI-friendly JSON report that fails on all warnings. They do not create migration history.`;
+        : "remains the primary local entry point."} ${formatRunScript(packageManager, "start")} still runs one-shot syncs before starting, while ${formatRunScript(packageManager, "build")} and ${typecheckCommand} verify that generated metadata/schema artifacts are already current through ${syncCheckCommand}. Run ${syncCommand} manually when you want to refresh generated artifacts before build, typecheck, or commit. ${syncTypesCommand} stays warn-only by default; use \`${failOnLossySyncCommand}\` to fail only on lossy WordPress projections, or \`${strictSyncCommand}\` for a CI-friendly JSON report that fails on all warnings.${advancedPersistenceNote} They do not create migration history.`;
 }
 /**
  * Returns source-of-truth guidance for generated artifacts by template mode.
@@ -37,12 +66,12 @@ export function getTemplateSourceOfTruthNote(templateId, { compoundPersistenceEn
     if (templateId === "compound") {
         const compoundBase = "`src/blocks/*/types.ts` files remain the source of truth for each block's `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include starter `typia.manifest.json` files so editor imports resolve before the first sync.";
         if (compoundPersistenceEnabled) {
-            return `${compoundBase} For persistence-enabled parents, \`src/blocks/*/api-types.ts\` files remain the source of truth for \`src/blocks/*/api-schemas/*\` when you run \`sync-rest\`, while \`src/blocks/*/transport.ts\` is the first-class transport seam for editor and frontend requests.`;
+            return `${compoundBase} For persistence-enabled parents, \`src/blocks/*/api-types.ts\` files remain the source of truth for \`src/blocks/*/api-schemas/*\` when you run \`sync\` or \`sync-rest\`, while \`src/blocks/*/transport.ts\` is the first-class transport seam for editor and frontend requests.`;
         }
         return compoundBase;
     }
     if (templateId === "persistence") {
-        return "`src/types.ts` remains the source of truth for `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include a starter `typia.manifest.json` so editor imports resolve before the first sync. `src/api-types.ts` remains the source of truth for `src/api-schemas/*` when you run `sync-rest`, while `src/transport.ts` is the first-class transport seam for editor and frontend requests. This scaffold is intentionally server-rendered: `src/render.php` is the canonical frontend entry, `src/save.tsx` returns `null`, and session-only write data now refreshes through the dedicated `/bootstrap` endpoint after hydration instead of being frozen into markup.";
+        return "`src/types.ts` remains the source of truth for `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include a starter `typia.manifest.json` so editor imports resolve before the first sync. `src/api-types.ts` remains the source of truth for `src/api-schemas/*` when you run `sync` or `sync-rest`, while `src/transport.ts` is the first-class transport seam for editor and frontend requests. This scaffold is intentionally server-rendered: `src/render.php` is the canonical frontend entry, `src/save.tsx` returns `null`, and session-only write data now refreshes through the dedicated `/bootstrap` endpoint after hydration instead of being frozen into markup.";
     }
     return "`src/types.ts` remains the source of truth for `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include a starter `typia.manifest.json` so editor imports resolve before the first sync. The basic scaffold stays static by design: `src/render.php` is only an opt-in server placeholder, `src/save.tsx` remains the canonical frontend output, and the generated webpack config keeps the current `@wordpress/scripts` CommonJS baseline unless you intentionally add `render` to `block.json`.";
 }
@@ -69,7 +98,7 @@ function formatPhpRestExtensionPointsSection({ apiTypesPath, extraNote, mainPhpP
         `- Edit \`${mainPhpPath}\` when you need to ${mainPhpScope}.`,
         "- Edit `inc/rest-auth.php` or `inc/rest-public.php` when you need to customize write permissions or token/request-id/nonce checks for the selected policy.",
         `- Edit \`${transportPath}\` when you need to switch between direct WordPress REST and a contract-compatible proxy or BFF without changing the endpoint contracts.`,
-        `- Keep \`${apiTypesPath}\` as the source of truth for request and response contracts, then regenerate \`${schemaJsonGlob}\`, per-contract \`${perContractOpenApiGlob}\`, and \`${aggregateOpenApiPath}\` with \`sync-rest\`.`,
+        `- Keep \`${apiTypesPath}\` as the source of truth for request and response contracts, then regenerate \`${schemaJsonGlob}\`, per-contract \`${perContractOpenApiGlob}\`, and \`${aggregateOpenApiPath}\` with \`sync\` (or \`sync-rest\` after \`sync-types\` when you only need the REST layer).`,
         "- Avoid hand-editing generated schema and OpenAPI artifacts unless you are debugging generated output; they are meant to be regenerated from TypeScript contracts.",
     ];
     if (typeof extraNote === "string" && extraNote.length > 0) {

package/dist/runtime/scaffold.js

@@ -19,6 +19,7 @@ const BLOCK_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
 const PHP_PREFIX_PATTERN = /^[a-z_][a-z0-9_]*$/;
 const PHP_PREFIX_MAX_LENGTH = 50;
 const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+const WORKSPACE_TEMPLATE_ALIAS = "workspace";
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 const LOCKFILES = {
     bun: ["bun.lock", "bun.lockb"],
@@ -138,15 +139,21 @@ export function getDefaultAnswers(projectName, templateId) {
         title: toTitleCase(slugDefault),
     };
 }
+function normalizeTemplateSelection(templateId) {
+    return templateId === WORKSPACE_TEMPLATE_ALIAS
+        ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        : templateId;
+}
 export async function resolveTemplateId({ templateId, yes = false, isInteractive = false, selectTemplate, }) {
     if (templateId) {
+        const normalizedTemplateId = normalizeTemplateSelection(templateId);
         if (isRemovedBuiltInTemplateId(templateId)) {
             throw new Error(getRemovedBuiltInTemplateMessage(templateId));
         }
-        if (isBuiltInTemplateId(templateId)) {
-            return getTemplateById(templateId).id;
+        if (isBuiltInTemplateId(normalizedTemplateId)) {
+            return getTemplateById(normalizedTemplateId).id;
         }
-        return templateId;
+        return normalizedTemplateId;
     }
     if (yes) {
         return "basic";
@@ -154,7 +161,7 @@ export async function resolveTemplateId({ templateId, yes = false, isInteractive
     if (!isInteractive || !selectTemplate) {
         throw new Error(`Template is required in non-interactive mode. Use --template <${TEMPLATE_IDS.join("|")}|./path|github:owner/repo/path[#ref]|npm-package>.`);
     }
-    return selectTemplate();
+    return normalizeTemplateSelection(await selectTemplate());
 }
 export async function resolvePackageManagerId({ packageManager, yes = false, isInteractive = false, selectPackageManager, }) {
     if (packageManager) {
@@ -317,12 +324,13 @@ function buildReadme(templateId, variables, packageManager, { withMigrationUi =
     const sourceOfTruthNote = getTemplateSourceOfTruthNote(templateId, {
         compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
     });
+    const compoundPersistenceEnabled = variables.compoundPersistenceEnabled === "true";
     const publicPersistencePolicyNote = variables.isPublicPersistencePolicy === "true"
         ? "Public persistence writes use signed short-lived tokens, per-request ids, and coarse rate limiting by default. Add application-specific abuse controls before using the same pattern for high-value metrics or experiments."
         : null;
     const compoundExtensionWorkflowSection = getCompoundExtensionWorkflowSection(packageManager, templateId);
     const phpRestExtensionPointsSection = getPhpRestExtensionPointsSection(templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
+        compoundPersistenceEnabled,
         slug: variables.slug,
     });
     const developmentScript = getPrimaryDevelopmentScript(templateId);
@@ -362,7 +370,9 @@ ${formatRunScript(packageManager, "build")}
 ${optionalOnboardingSteps.join("\n")}
 \`\`\`
 
-${getOptionalOnboardingNote(packageManager, templateId)}
+${getOptionalOnboardingNote(packageManager, templateId, {
+        compoundPersistenceEnabled,
+    })}
 
 ${sourceOfTruthNote}${publicPersistencePolicyNote ? `\n\n${publicPersistencePolicyNote}` : ""}${migrationSection ? `\n\n${migrationSection}` : ""}${compoundExtensionWorkflowSection ? `\n\n${compoundExtensionWorkflowSection}` : ""}${wpEnvSection ? `\n\n${wpEnvSection}` : ""}${testPresetSection ? `\n\n${testPresetSection}` : ""}${phpRestExtensionPointsSection ? `\n\n${phpRestExtensionPointsSection}` : ""}
 `;
@@ -625,14 +635,15 @@ async function applyWorkspaceMigrationCapability(projectDir, packageManager) {
     writeInitialMigrationScaffold(projectDir, "v1", []);
 }
 export async function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+    const resolvedTemplateId = normalizeTemplateSelection(templateId);
     const resolvedPackageManager = getPackageManager(packageManager).id;
-    const isBuiltInTemplate = isBuiltInTemplateId(templateId);
-    const variables = getTemplateVariables(templateId, {
+    const isBuiltInTemplate = isBuiltInTemplateId(resolvedTemplateId);
+    const variables = getTemplateVariables(resolvedTemplateId, {
         ...answers,
         dataStorageMode: dataStorageMode ?? answers.dataStorageMode,
         persistencePolicy: persistencePolicy ?? answers.persistencePolicy,
     });
-    const templateSource = await resolveTemplateSource(templateId, cwd, variables, variant);
+    const templateSource = await resolveTemplateSource(resolvedTemplateId, cwd, variables, variant);
     const supportsMigrationUi = isBuiltInTemplate || templateSource.isOfficialWorkspaceTemplate === true;
     if (withMigrationUi && !supportsMigrationUi) {
         await templateSource.cleanup?.();
@@ -649,8 +660,8 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
     }
     const isOfficialWorkspace = isOfficialWorkspaceProject(projectDir);
     if (isBuiltInTemplate) {
-        await writeStarterManifestFiles(projectDir, templateId, variables);
-        await seedBuiltInPersistenceArtifacts(projectDir, templateId, variables);
+        await writeStarterManifestFiles(projectDir, resolvedTemplateId, variables);
+        await seedBuiltInPersistenceArtifacts(projectDir, resolvedTemplateId, variables);
         await applyLocalDevPresetFiles({
             projectDir,
             variables,
@@ -661,7 +672,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
             await applyMigrationUiCapability({
                 packageManager: resolvedPackageManager,
                 projectDir,
-                templateId,
+                templateId: resolvedTemplateId,
                 variables,
             });
         }
@@ -671,7 +682,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
     }
     const readmePath = path.join(projectDir, "README.md");
     if (!fs.existsSync(readmePath)) {
-        await fsp.writeFile(readmePath, buildReadme(templateId, variables, resolvedPackageManager, {
+        await fsp.writeFile(readmePath, buildReadme(resolvedTemplateId, variables, resolvedPackageManager, {
             withMigrationUi: isBuiltInTemplate || isOfficialWorkspace ? withMigrationUi : false,
             withTestPreset: isBuiltInTemplate ? withTestPreset : false,
             withWpEnv: isBuiltInTemplate ? withWpEnv : false,
@@ -688,7 +699,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
             compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
             packageManager: resolvedPackageManager,
             projectDir,
-            templateId,
+            templateId: resolvedTemplateId,
             withTestPreset,
             withWpEnv,
         });
@@ -706,7 +717,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
     return {
         projectDir,
         selectedVariant: templateSource.selectedVariant ?? null,
-        templateId,
+        templateId: resolvedTemplateId,
         packageManager: resolvedPackageManager,
         variables,
         warnings: templateSource.warnings ?? [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.15.4",
+  "version": "0.16.1",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "@wp-typia/api-client": "^0.4.2",
-    "@wp-typia/block-runtime": "^0.4.3",
+    "@wp-typia/block-runtime": "^0.4.4",
     "@wp-typia/rest": "^0.3.5",
     "@wp-typia/block-types": "^0.2.1",
     "mustache": "^4.2.0",

package/templates/_shared/base/package.json.mustache

@@ -7,15 +7,16 @@
   "license": "GPL-2.0-or-later",
   "main": "build/index.js",
   "scripts": {
+    "sync": "tsx scripts/sync-project.ts",
     "sync-types": "tsx scripts/sync-types-to-block-json.ts",
-    "build": "bun run sync-types --check && wp-scripts build --experimental-modules",
-    "start": "bun run sync-types && wp-scripts start --experimental-modules",
+    "build": "bun run sync --check && wp-scripts build --experimental-modules",
+    "start": "bun run sync && wp-scripts start --experimental-modules",
     "dev": "bun run start",
     "lint:js": "wp-scripts lint-js",
     "lint:css": "wp-scripts lint-style",
     "lint": "bun run lint:js && bun run lint:css",
     "format": "wp-scripts format",
-    "typecheck": "bun run sync-types --check && tsc --noEmit"
+    "typecheck": "bun run sync --check && tsc --noEmit"
   },
   "devDependencies": {
     "@wp-typia/block-runtime": "{{blockRuntimePackageVersion}}",

package/templates/_shared/base/scripts/sync-project.ts.mustache

@@ -0,0 +1,103 @@
+/* eslint-disable no-console */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+interface SyncCliOptions {
+	check: boolean;
+}
+
+function parseCliOptions( argv: string[] ): SyncCliOptions {
+	const options: SyncCliOptions = {
+		check: false,
+	};
+
+	for ( const argument of argv ) {
+		if ( argument === '--check' ) {
+			options.check = true;
+			continue;
+		}
+
+		throw new Error( `Unknown sync flag: ${ argument }` );
+	}
+
+	return options;
+}
+
+function getSyncScriptEnv() {
+	const binaryDirectory = path.join( process.cwd(), 'node_modules', '.bin' );
+	const inheritedPath =
+		process.env.PATH ??
+		process.env.Path ??
+		Object.entries( process.env ).find(
+			( [ key ] ) => key.toLowerCase() === 'path'
+		)?.[ 1 ] ??
+		'';
+	const nextPath = fs.existsSync( binaryDirectory )
+		? `${ binaryDirectory }${ path.delimiter }${ inheritedPath }`
+		: inheritedPath;
+	const env: NodeJS.ProcessEnv = {
+		...process.env,
+	};
+
+	for ( const key of Object.keys( env ) ) {
+		if ( key.toLowerCase() === 'path' ) {
+			delete env[ key ];
+		}
+	}
+
+	env.PATH = nextPath;
+
+	return env;
+}
+
+function runSyncScript( scriptPath: string, options: SyncCliOptions ) {
+	const args = [ scriptPath ];
+	if ( options.check ) {
+		args.push( '--check' );
+	}
+
+	const result = spawnSync( 'tsx', args, {
+		cwd: process.cwd(),
+		env: getSyncScriptEnv(),
+		shell: process.platform === 'win32',
+		stdio: 'inherit',
+	} );
+
+	if ( result.error ) {
+		if ( ( result.error as NodeJS.ErrnoException ).code === 'ENOENT' ) {
+			throw new Error(
+				'Unable to resolve `tsx` for project sync. Install project dependencies or rerun the command through your package manager.'
+			);
+		}
+
+		throw result.error;
+	}
+
+	if ( result.status !== 0 ) {
+		throw new Error( `Sync script failed: ${ scriptPath }` );
+	}
+}
+
+async function main() {
+	const options = parseCliOptions( process.argv.slice( 2 ) );
+	const syncTypesScriptPath = path.join( 'scripts', 'sync-types-to-block-json.ts' );
+	const syncRestScriptPath = path.join( 'scripts', 'sync-rest-contracts.ts' );
+
+	runSyncScript( syncTypesScriptPath, options );
+
+	if ( fs.existsSync( path.resolve( process.cwd(), syncRestScriptPath ) ) ) {
+		runSyncScript( syncRestScriptPath, options );
+	}
+
+	console.log(
+		options.check
+			? '✅ Generated project metadata and REST artifacts are already synchronized.'
+			: '✅ Generated project metadata and REST artifacts were synchronized.'
+	);
+}
+
+main().catch( ( error ) => {
+	console.error( '❌ Project sync failed:', error );
+	process.exit( 1 );
+} );

package/templates/_shared/compound/core/package.json.mustache

@@ -8,11 +8,12 @@
   "main": "build/index.js",
   "scripts": {
     "add-child": "tsx scripts/add-compound-child.ts",
+    "sync": "tsx scripts/sync-project.ts",
     "sync-types": "tsx scripts/sync-types-to-block-json.ts",
-    "build": "bun run sync-types --check && wp-scripts build --experimental-modules",
-    "start": "bun run sync-types && wp-scripts start --experimental-modules",
+    "build": "bun run sync --check && wp-scripts build --experimental-modules",
+    "start": "bun run sync && wp-scripts start --experimental-modules",
     "dev": "bun run start",
-    "typecheck": "bun run sync-types --check && tsc --noEmit",
+    "typecheck": "bun run sync --check && tsc --noEmit",
     "lint:js": "wp-scripts lint-js",
     "lint:css": "wp-scripts lint-style",
     "lint": "bun run lint:js && bun run lint:css",

package/templates/_shared/compound/core/scripts/add-compound-child.ts.mustache

@@ -346,8 +346,15 @@ function renderBlockJson(
 	) }\n`;
 }
 
-function renderTypesFile( childTypeName: string, childTitle: string ): string {
-	return `import { tags } from 'typia';
+function renderTypesFile(
+	childTypeName: string,
+	childInterfaceName: string,
+	childTitle: string
+): string {
+	return `import type { ValidationResult } from '@wp-typia/block-runtime/validation';
+import { tags } from 'typia';
+
+export type { ValidationResult } from '@wp-typia/block-runtime/validation';
 
 export interface ${ childTypeName } {
 \ttitle: string &
@@ -359,6 +366,8 @@ export interface ${ childTypeName } {
 \t\ttags.MaxLength< 280 > &
 \t\ttags.Default< ${ JSON.stringify( CHILD_PLACEHOLDER ) } >;
 }
+
+export type ${ childInterfaceName }ValidationResult = ValidationResult< ${ childTypeName } >;
 `;
 }
 
@@ -407,36 +416,37 @@ function renderValidatorsFile(
 ): string {
 	return `import typia from 'typia';
 import currentManifest from './typia.manifest.json';
-import {
-\ttype ManifestDefaultsDocument,
-} from '@wp-typia/block-runtime/defaults';
-import {
-\tcreateScaffoldValidatorToolkit,
-} from '@wp-typia/block-runtime/validation';
-
-import type { ${ childTypeName } } from './types';
-
-const validate = typia.createValidate< ${ childTypeName } >();
-const assert = typia.createAssert< ${ childTypeName } >();
-const is = typia.createIs< ${ childTypeName } >();
-const random = typia.createRandom< ${ childTypeName } >();
-const clone = typia.misc.createClone< ${ childTypeName } >();
-const prune = typia.misc.createPrune< ${ childTypeName } >();
-const scaffoldValidators = createScaffoldValidatorToolkit< ${ childTypeName } >( {
-\tmanifest: currentManifest as ManifestDefaultsDocument,
-\tvalidate,
-\tassert,
-\tis,
-\trandom,
-\tclone,
-\tprune,
+import type {
+\t${ childTypeName },
+\t${ childInterfaceName }ValidationResult,
+} from './types';
+import { createTemplateValidatorToolkit } from '../../validator-toolkit';
+
+const scaffoldValidators = createTemplateValidatorToolkit< ${ childTypeName } >( {
+\tassert: typia.createAssert< ${ childTypeName } >(),
+\tclone: typia.misc.createClone< ${ childTypeName } >() as (
+\t\tvalue: ${ childTypeName },
+\t) => ${ childTypeName },
+\tis: typia.createIs< ${ childTypeName } >(),
+\tmanifest: currentManifest,
+\tprune: typia.misc.createPrune< ${ childTypeName } >(),
+\trandom: typia.createRandom< ${ childTypeName } >() as (
+\t\t...args: unknown[]
+\t) => ${ childTypeName },
+\tvalidate: typia.createValidate< ${ childTypeName } >(),
 } );
 
-export const validate${ childInterfaceName } = scaffoldValidators.validateAttributes;
+export const validate${ childInterfaceName } =
+\tscaffoldValidators.validateAttributes as (
+\t\tattributes: unknown
+\t) => ${ childInterfaceName }ValidationResult;
 
 export const validators = scaffoldValidators.validators;
 
-export const sanitize${ childInterfaceName } = scaffoldValidators.sanitizeAttributes;
+export const sanitize${ childInterfaceName } =
+\tscaffoldValidators.sanitizeAttributes as (
+\t\tattributes: Partial< ${ childTypeName } >
+\t) => ${ childTypeName };
 
 export const createAttributeUpdater = scaffoldValidators.createAttributeUpdater;
 `;
@@ -605,7 +615,11 @@ function main() {
 		renderBlockJson( childBlockName, childFolderSlug, childTitle ),
 		'utf8'
 	);
-	fs.writeFileSync( path.join( childDir, 'types.ts' ), renderTypesFile( childTypeName, childTitle ), 'utf8' );
+	fs.writeFileSync(
+		path.join( childDir, 'types.ts' ),
+		renderTypesFile( childTypeName, childInterfaceName, childTitle ),
+		'utf8'
+	);
 	fs.writeFileSync(
 		path.join( childDir, 'typia.manifest.json' ),
 		renderStarterManifestFile( childTypeName, childTitle ),