@wp-typia/project-tools 0.15.3 → 0.16.0

package/dist/runtime/cli-add.js

@@ -648,6 +648,7 @@ const LEGACY_ASSERT_PATTERN = /assert:\s*typia\.createAssert</u;
 const LEGACY_MANIFEST_PATTERN = /\r?\n[ \t]*manifest:\s*currentManifest,/u;
 const LEGACY_TOOLKIT_CALL_PATTERN = /createTemplateValidatorToolkit<\s*(?<typeName>[A-Za-z0-9_]+)\s*>\s*\(\s*\{/u;
 const LEGACY_VALIDATOR_TOOLKIT_IMPORT_PATTERN = /from\s*["']\.\.\/\.\.\/validator-toolkit["']/u;
+const TYPIA_IMPORT_PATTERN = /^[\uFEFF \t]*import\s+typia\s+from\s*["']typia["'];?/mu;
 const COMPATIBLE_COMPOUND_TOOLKIT_PATTERNS = [
     /interface\s+TemplateValidatorFunctions\s*<\s*T\s+extends\s+object\s*>\s*\{/u,
     /\bassert\s*:\s*ScaffoldValidatorToolkitOptions\s*<\s*T\s*>\s*\[\s*["']assert["']\s*\]/u,
@@ -667,6 +668,9 @@ function isLegacyCompoundValidatorSource(source) {
         LEGACY_VALIDATOR_TOOLKIT_IMPORT_PATTERN.test(source) &&
         !LEGACY_ASSERT_PATTERN.test(source));
 }
+function hasTypiaImport(source) {
+    return TYPIA_IMPORT_PATTERN.test(source.replace(/\/\*[\s\S]*?\*\//gu, ""));
+}
 function upgradeLegacyCompoundValidatorSource(source) {
     const typeNameMatch = source.match(LEGACY_TOOLKIT_CALL_PATTERN);
     const typeName = typeNameMatch?.groups?.typeName;
@@ -674,7 +678,7 @@ function upgradeLegacyCompoundValidatorSource(source) {
         throw new Error("Unable to upgrade a legacy compound validator without a generated type import.");
     }
     let nextSource = source;
-    if (!nextSource.includes("import typia from 'typia';")) {
+    if (!hasTypiaImport(nextSource)) {
         nextSource = `import typia from 'typia';\n${nextSource}`;
     }
     nextSource = nextSource.replace(LEGACY_TOOLKIT_CALL_PATTERN, [

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

@@ -317,12 +317,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 +363,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}` : ""}
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",

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/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/persistence/package.json.mustache

@@ -8,12 +8,13 @@
   "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",
     "sync-rest": "tsx scripts/sync-rest-contracts.ts",
-    "build": "bun run sync-types --check && bun run sync-rest --check && wp-scripts build --experimental-modules",
-    "start": "bun run sync-types && bun run sync-rest && 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 && bun run sync-rest --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/persistence/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/persistence/scripts/sync-rest-contracts.ts.mustache

@@ -2,6 +2,7 @@
 import path from 'node:path';
 
 import {
+	runSyncBlockMetadata,
 	syncEndpointClient,
 	syncRestOpenApi,
 	syncTypeSchemas,
@@ -26,6 +27,31 @@ function parseCliOptions( argv: string[] ) {
 	return options;
 }
 
+async function assertTypeArtifactsCurrent( block: ( typeof BLOCKS )[ number ] ) {
+	const report = await runSyncBlockMetadata( {
+		blockJsonFile: path.join( 'src', 'blocks', block.slug, 'block.json' ),
+		jsonSchemaFile: path.join( 'src', 'blocks', block.slug, 'typia.schema.json' ),
+		manifestFile: path.join( 'src', 'blocks', block.slug, 'typia.manifest.json' ),
+		openApiFile: path.join( 'src', 'blocks', block.slug, 'typia.openapi.json' ),
+		sourceTypeName: block.attributeTypeName,
+		typesFile: block.typesFile,
+	}, {
+		check: true,
+	} );
+
+	if ( report.failure?.code === 'stale-generated-artifact' ) {
+		throw new Error(
+			`${ block.slug }: ${ report.failure.message }\nRun \`sync\` or \`sync-types\` first to refresh type-derived artifacts before rerunning \`sync-rest\`.`
+		);
+	}
+
+	if ( report.failure ) {
+		throw new Error(
+			`${ block.slug }: type-derived artifact preflight failed before sync-rest.\n${ report.failure.message }`
+		);
+	}
+}
+
 async function main() {
 	const options = parseCliOptions( process.argv.slice( 2 ) );
 
@@ -39,6 +65,8 @@ async function main() {
 			continue;
 		}
 
+		await assertTypeArtifactsCurrent( block );
+
 		for ( const [ baseName, contract ] of Object.entries( block.restManifest.contracts ) ) {
 			await syncTypeSchemas( {
 				jsonSchemaFile: path.join(

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

@@ -7,16 +7,17 @@
 	"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",
 		"sync-rest": "tsx scripts/sync-rest-contracts.ts",
-		"build": "bun run sync-types --check && bun run sync-rest --check && wp-scripts build --experimental-modules",
-		"start": "bun run sync-types && bun run sync-rest && 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 && bun run sync-rest --check && tsc --noEmit"
+		"typecheck": "bun run sync --check && tsc --noEmit"
 	},
 	"devDependencies": {
 		"@wp-typia/block-runtime": "{{blockRuntimePackageVersion}}",

package/templates/_shared/persistence/core/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/persistence/core/scripts/sync-rest-contracts.ts.mustache

@@ -1,6 +1,7 @@
 /* eslint-disable no-console */
 import {
 	defineEndpointManifest,
+	runSyncBlockMetadata,
 	syncEndpointClient,
 	syncRestOpenApi,
 	syncTypeSchemas,
@@ -23,6 +24,31 @@ function parseCliOptions( argv: string[] ) {
 	return options;
 }
 
+async function assertTypeArtifactsCurrent() {
+	const report = await runSyncBlockMetadata( {
+		blockJsonFile: 'src/block.json',
+		jsonSchemaFile: 'src/typia.schema.json',
+		manifestFile: 'src/typia.manifest.json',
+		openApiFile: 'src/typia.openapi.json',
+		sourceTypeName: '{{pascalCase}}Attributes',
+		typesFile: 'src/types.ts',
+	}, {
+		check: true,
+	} );
+
+	if ( report.failure?.code === 'stale-generated-artifact' ) {
+		throw new Error(
+			`${ report.failure.message }\nRun \`sync\` or \`sync-types\` first to refresh type-derived artifacts before rerunning \`sync-rest\`.`
+		);
+	}
+
+	if ( report.failure ) {
+		throw new Error(
+			`Type-derived artifact preflight failed before sync-rest.\n${ report.failure.message }`
+		);
+	}
+}
+
 const REST_ENDPOINT_MANIFEST = defineEndpointManifest( {
 	contracts: {
 		'state-query': {
@@ -85,6 +111,8 @@ const REST_ENDPOINT_MANIFEST = defineEndpointManifest( {
 async function main() {
 	const options = parseCliOptions( process.argv.slice( 2 ) );
 
+	await assertTypeArtifactsCurrent();
+
 	for ( const [ baseName, contract ] of Object.entries( REST_ENDPOINT_MANIFEST.contracts ) ) {
 		await syncTypeSchemas( {
 			jsonSchemaFile: `src/api-schemas/${ baseName }.schema.json`,

package/templates/interactivity/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}}",