@wp-typia/project-tools 0.17.0 → 0.19.0

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

@@ -4,7 +4,7 @@ import path from 'node:path';
 
 const PROJECT_ROOT = process.cwd();
 
-const ALLOWED_CHILD_MARKER = '// add-child: insert new allowed child block names here';
+const CHILD_SPEC_MARKER = '// add-child: insert new child specs here';
 const BLOCK_CONFIG_MARKER = '// add-child: insert new block config entries here';
 const CHILD_PLACEHOLDER = 'Add supporting details for this internal item.';
 const BLOCK_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -16,8 +16,10 @@ type StarterManifestDocument = {
 };
 
 type CompoundParentConfig = {
+	blockJsonPath: string;
 	blockName: string;
 	namespace: string;
+	blocksRoot: string;
 	slug: string;
 	styleImport: string;
 	textDomain: string;
@@ -25,12 +27,47 @@ type CompoundParentConfig = {
 	typeName: string;
 };
 
+type ExistingCompoundChild = {
+	ancestorBlockNames: string[];
+	blockJsonPath: string;
+	blockName: string;
+	container: boolean;
+	directAllowedBlocks: string[];
+	folderSlug: string;
+	key: string;
+	parentBlockNames: string[];
+	placement: 'nested' | 'root';
+	supportsInserter: boolean;
+	title: string;
+};
+
+type ParsedArgs = {
+	ancestorValues: string[];
+	container: boolean;
+	dryRun: boolean;
+	inserter?: 'hidden' | 'visible';
+	slug?: string;
+	title?: string;
+};
+
+type CompoundChildGraphNode = {
+	blockName: string;
+	container: boolean;
+	directParentBlockName: string;
+	isProspective: boolean;
+	key: string;
+	placement: 'nested' | 'root';
+	supportsInserter: boolean;
+	title: string;
+};
+
 function parseArgs() {
 	const args = process.argv.slice( 2 );
-	const parsed: {
-		slug?: string;
-		title?: string;
-	} = {};
+	const parsed: ParsedArgs = {
+		ancestorValues: [],
+		container: false,
+		dryRun: false,
+	};
 
 	for ( let index = 0; index < args.length; index += 1 ) {
 		const arg = args[ index ];
@@ -53,6 +90,40 @@ function parseArgs() {
 			index += 1;
 			continue;
 		}
+
+		if ( arg === '--ancestor' ) {
+			const value = args[ index + 1 ];
+			if ( ! value || value.startsWith( '--' ) ) {
+				throw new Error( '--ancestor requires a value.' );
+			}
+			parsed.ancestorValues.push( value );
+			index += 1;
+			continue;
+		}
+
+		if ( arg === '--container' ) {
+			parsed.container = true;
+			continue;
+		}
+
+		if ( arg === '--dry-run' ) {
+			parsed.dryRun = true;
+			continue;
+		}
+
+		if ( arg === '--inserter' ) {
+			const value = args[ index + 1 ];
+			if ( value !== 'hidden' && value !== 'visible' ) {
+				throw new Error( "--inserter must be either 'hidden' or 'visible'." );
+			}
+			parsed.inserter = value;
+			index += 1;
+			continue;
+		}
+
+		if ( arg.startsWith( '--' ) ) {
+			throw new Error( `Unknown option: ${ arg }.` );
+		}
 	}
 
 	return parsed;
@@ -177,8 +248,10 @@ function resolveCompoundParentConfig(): CompoundParentConfig {
 			: parentSlug;
 
 	return {
+		blockJsonPath,
 		blockName,
 		namespace,
+		blocksRoot,
 		slug: parentSlug,
 		styleImport: `../${ parentSlug }/style.scss`,
 		textDomain,
@@ -188,8 +261,10 @@ function resolveCompoundParentConfig(): CompoundParentConfig {
 }
 
 const {
+	blockJsonPath: PARENT_BLOCK_JSON_PATH,
 	blockName: PARENT_BLOCK_NAME,
 	namespace: PARENT_BLOCK_NAMESPACE,
+	blocksRoot: BLOCKS_ROOT,
 	slug: PARENT_BLOCK_SLUG,
 	styleImport: PARENT_STYLE_IMPORT,
 	textDomain: TEXT_DOMAIN,
@@ -300,50 +375,486 @@ function insertBeforeMarker( filePath: string, marker: string, insertionLines: s
 	);
 }
 
+function readBlockJsonDocument(
+	filePath: string
+): Record< string, unknown > {
+	return readJsonFile( filePath );
+}
+
+function writeBlockJsonDocument(
+	filePath: string,
+	document: Record< string, unknown >
+) {
+	fs.writeFileSync(
+		filePath,
+		`${ JSON.stringify( document, null, '\t' ) }\n`,
+		'utf8'
+	);
+}
+
+function deriveChildKey( folderSlug: string ): string {
+	if ( folderSlug.startsWith( `${ PARENT_BLOCK_SLUG }-` ) ) {
+		return folderSlug.slice( PARENT_BLOCK_SLUG.length + 1 );
+	}
+
+	return resolveValidatedBlockSlug( folderSlug );
+}
+
+function listExistingCompoundChildren(): ExistingCompoundChild[] {
+	if ( ! fs.existsSync( BLOCKS_ROOT ) ) {
+		return [];
+	}
+
+	return fs
+		.readdirSync( BLOCKS_ROOT, { withFileTypes: true } )
+		.filter( ( entry ) => entry.isDirectory() )
+		.map( ( entry ) => entry.name )
+		.filter( ( folderSlug ) => folderSlug !== PARENT_BLOCK_SLUG )
+		.filter( ( folderSlug ) => folderSlug.startsWith( `${ PARENT_BLOCK_SLUG }-` ) )
+		.map( ( folderSlug ) => {
+			const blockJsonPath = path.join( BLOCKS_ROOT, folderSlug, 'block.json' );
+			if ( ! fs.existsSync( blockJsonPath ) ) {
+				return null;
+			}
+
+			const blockJson = readBlockJsonDocument( blockJsonPath );
+			const blockName =
+				typeof blockJson.name === 'string' ? blockJson.name.trim() : '';
+			if ( blockName.length === 0 ) {
+				return null;
+			}
+
+			const ancestorBlockNames = Array.isArray( blockJson.ancestor )
+				? blockJson.ancestor.filter(
+					( value ): value is string => typeof value === 'string'
+				)
+				: [];
+			const parentBlockNames = Array.isArray( blockJson.parent )
+				? blockJson.parent.filter(
+					( value ): value is string => typeof value === 'string'
+				)
+				: [];
+			const directAllowedBlocks = Array.isArray( blockJson.allowedBlocks )
+				? blockJson.allowedBlocks.filter(
+					( value ): value is string => typeof value === 'string'
+				)
+				: [];
+			const supports =
+				typeof blockJson.supports === 'object' &&
+				blockJson.supports &&
+				! Array.isArray( blockJson.supports )
+					? blockJson.supports
+					: null;
+			const supportsInserter =
+				supports && typeof supports.inserter === 'boolean'
+					? supports.inserter
+					: true;
+			const title =
+				typeof blockJson.title === 'string' &&
+				blockJson.title.trim().length > 0
+					? blockJson.title.trim()
+					: toTitleCase( deriveChildKey( folderSlug ) );
+
+			return {
+				ancestorBlockNames,
+				blockJsonPath,
+				blockName,
+				container: Object.prototype.hasOwnProperty.call(
+					blockJson,
+					'allowedBlocks'
+				),
+				directAllowedBlocks,
+				folderSlug,
+				key: deriveChildKey( folderSlug ),
+				parentBlockNames,
+				placement: ancestorBlockNames.length > 0 ? 'nested' : 'root',
+				supportsInserter,
+				title,
+			} satisfies ExistingCompoundChild;
+		} )
+		.filter( ( child ): child is ExistingCompoundChild => child !== null );
+}
+
+function buildCompoundChildGraphMap(
+	existingChildren: ExistingCompoundChild[]
+): Map< string, ExistingCompoundChild > {
+	return new Map(
+		existingChildren.map( ( child ) => [ child.blockName, child ] )
+	);
+}
+
+function resolveDirectParentBlockName( child: ExistingCompoundChild ): string {
+	return (
+		child.ancestorBlockNames[ child.ancestorBlockNames.length - 1 ] ??
+		child.parentBlockNames[ 0 ] ??
+		PARENT_BLOCK_NAME
+	);
+}
+
+function validateExistingCompoundChildGraph(
+	existingChildren: ExistingCompoundChild[]
+) {
+	const seenKeys = new Set< string >();
+	const seenBlockNames = new Set< string >();
+	const childByBlockName = buildCompoundChildGraphMap( existingChildren );
+
+	for ( const child of existingChildren ) {
+		if ( seenKeys.has( child.key ) ) {
+			throw new Error(
+				`Existing compound child graph is invalid: child key "${ child.key }" is declared more than once.`
+			);
+		}
+
+		if ( seenBlockNames.has( child.blockName ) ) {
+			throw new Error(
+				`Existing compound child graph is invalid: ${ child.blockName } is declared more than once.`
+			);
+		}
+
+		seenKeys.add( child.key );
+		seenBlockNames.add( child.blockName );
+
+		if ( child.ancestorBlockNames.length === 0 ) {
+			if ( child.parentBlockNames.length === 0 ) {
+				throw new Error(
+					`Existing compound child graph is invalid: ${ child.blockName } must declare a parent block.`
+				);
+			}
+			continue;
+		}
+
+		for ( let index = 0; index < child.ancestorBlockNames.length; index += 1 ) {
+			const ancestorBlockName = child.ancestorBlockNames[ index ];
+			const ancestorChild = childByBlockName.get( ancestorBlockName );
+
+			if ( ! ancestorChild ) {
+				throw new Error(
+					`Existing compound child graph is invalid: ${ child.blockName } references missing ancestor ${ ancestorBlockName }.`
+				);
+			}
+
+			if ( ! ancestorChild.container ) {
+				throw new Error(
+					`Existing compound child graph is invalid: ${ ancestorChild.blockName } is not declared as a container child but has nested descendants.`
+				);
+			}
+
+			const expectedAncestorRoute = child.ancestorBlockNames.slice( 0, index );
+			const ancestorRouteMatches =
+				ancestorChild.ancestorBlockNames.length === expectedAncestorRoute.length &&
+				expectedAncestorRoute.every(
+					( expectedAncestorBlockName, expectedIndex ) =>
+						ancestorChild.ancestorBlockNames[ expectedIndex ] ===
+						expectedAncestorBlockName
+				);
+
+			if ( ! ancestorRouteMatches ) {
+				throw new Error(
+					`Existing compound child graph is invalid: ${ ancestorChild.blockName } is not on the declared ancestor route for ${ child.blockName }.`
+				);
+			}
+
+			const nextBlockName =
+				child.ancestorBlockNames[ index + 1 ] ?? child.blockName;
+			if ( ancestorChild.directAllowedBlocks.includes( nextBlockName ) ) {
+				continue;
+			}
+
+			throw new Error(
+				`Existing compound child graph is invalid: ${ ancestorChild.blockName } does not currently allow ${ nextBlockName } as a direct child.`
+			);
+		}
+	}
+}
+
+function resolveExistingCompoundChild(
+	value: string,
+	existingChildren: ExistingCompoundChild[]
+): ExistingCompoundChild {
+	const trimmedValue = value.trim();
+	if ( trimmedValue.length === 0 ) {
+		throw new Error( 'Ancestor references must not be empty.' );
+	}
+
+	const normalizedCandidate = resolveValidatedBlockSlug(
+		trimmedValue.includes( '/' )
+			? trimmedValue.slice( trimmedValue.lastIndexOf( '/' ) + 1 )
+			: trimmedValue
+	);
+	const resolved = existingChildren.find(
+		( child ) =>
+			child.blockName === trimmedValue ||
+			child.folderSlug === trimmedValue ||
+			child.key === normalizedCandidate ||
+			child.folderSlug === `${ PARENT_BLOCK_SLUG }-${ normalizedCandidate }`
+	);
+
+	if ( ! resolved ) {
+		throw new Error(
+			`Unable to resolve compound child ancestor "${ value }". Use an existing child key, folder slug, or block name.`
+		);
+	}
+
+	return resolved;
+}
+
+function ensureUniqueAncestorChain(
+	ancestors: ExistingCompoundChild[]
+): ExistingCompoundChild[] {
+	const seenKeys = new Set< string >();
+
+	return ancestors.filter( ( ancestor ) => {
+		if ( seenKeys.has( ancestor.key ) ) {
+			return false;
+		}
+
+		seenKeys.add( ancestor.key );
+		return true;
+	} );
+}
+
+function validateAncestorChain(
+	ancestorChain: ExistingCompoundChild[]
+) {
+	for ( let index = 0; index < ancestorChain.length - 1; index += 1 ) {
+		const currentAncestor = ancestorChain[ index ];
+		const nextAncestor = ancestorChain[ index + 1 ];
+
+		if ( currentAncestor.directAllowedBlocks.includes( nextAncestor.blockName ) ) {
+			continue;
+		}
+
+		throw new Error(
+			`Invalid ancestor chain: ${ currentAncestor.blockName } does not currently allow ${ nextAncestor.blockName } as a direct child.`
+		);
+	}
+}
+
+function validateNestedAncestorTarget( ancestorChain: ExistingCompoundChild[] ) {
+	const directAncestor = ancestorChain[ ancestorChain.length - 1 ];
+
+	if ( ! directAncestor ) {
+		return;
+	}
+
+	if ( directAncestor.container ) {
+		return;
+	}
+
+	throw new Error(
+		`Cannot nest descendants under ${ directAncestor.blockName } because it is not declared as a container child. Re-add that child with --container or target an existing container child.`
+	);
+}
+
+function findCompoundChildSpecSource(
+	childrenRegistrySource: string,
+	childKey: string
+): string | null {
+	const childSpecPattern = /\{[\s\S]*?key:\s*["'][^"']+["'][\s\S]*?\n\s*\},/g;
+
+	for ( const match of childrenRegistrySource.matchAll( childSpecPattern ) ) {
+		const candidate = match[ 0 ];
+		if (
+			candidate.includes( `key: "${ childKey }"` ) ||
+			candidate.includes( `key: '${ childKey }'` )
+		) {
+			return candidate;
+		}
+	}
+
+	return null;
+}
+
+function validateAncestorInstantiability(
+	childrenFile: string,
+	ancestorChain: ExistingCompoundChild[]
+) {
+	if ( ancestorChain.length === 0 ) {
+		return;
+	}
+
+	const childrenRegistrySource = fs.readFileSync( childrenFile, 'utf8' );
+
+	for ( const ancestor of ancestorChain ) {
+		const childSpecSource = findCompoundChildSpecSource(
+			childrenRegistrySource,
+			ancestor.key
+		);
+		if ( ! childSpecSource ) {
+			continue;
+		}
+
+		const supportsInserterMatch = childSpecSource.match(
+			/supportsInserter:\s*(true|false)/
+		);
+		const supportsInserter = supportsInserterMatch?.[ 1 ] === 'true';
+		const hasTemplateInstances = ! /templateInstances:\s*\[\s*\]/.test( childSpecSource );
+
+		if ( supportsInserter || hasTemplateInstances ) {
+			continue;
+		}
+
+		throw new Error(
+			`Cannot nest descendants under ${ ancestor.blockName } because it is hidden and has no seeded template instances. Re-add or promote that child with a visible inserter or a seeded template first.`
+		);
+	}
+}
+
+function formatProjectRelativePath( filePath: string ): string {
+	return path.relative( PROJECT_ROOT, filePath ) || '.';
+}
+
+function buildCompoundChildGraphNodes(
+	existingChildren: ExistingCompoundChild[],
+	prospectiveChild: CompoundChildGraphNode
+): CompoundChildGraphNode[] {
+	return [
+		...existingChildren.map( ( child ) => ( {
+			blockName: child.blockName,
+			container: child.container,
+			directParentBlockName: resolveDirectParentBlockName( child ),
+			isProspective: false,
+			key: child.key,
+			placement: child.placement,
+			supportsInserter: child.supportsInserter,
+			title: child.title,
+		} ) ),
+		prospectiveChild,
+	];
+}
+
+function renderCompoundChildGraphPreview(
+	graphNodes: CompoundChildGraphNode[],
+	plannedWritePaths: string[],
+	options: {
+		dryRun: boolean;
+	}
+): string {
+	const childrenByParent = new Map< string, CompoundChildGraphNode[] >();
+
+	for ( const graphNode of graphNodes ) {
+		const existingChildren = childrenByParent.get( graphNode.directParentBlockName ) ?? [];
+		existingChildren.push( graphNode );
+		childrenByParent.set( graphNode.directParentBlockName, existingChildren );
+	}
+
+	const renderChildLines = (
+		parentBlockName: string,
+		indent: string
+	): string[] => {
+		const directChildren = [ ...( childrenByParent.get( parentBlockName ) ?? [] ) ].sort(
+			( left, right ) => left.key.localeCompare( right.key )
+		);
+
+		return directChildren.flatMap( ( child ) => {
+			const labels = [
+				child.isProspective ? 'new' : 'existing',
+				child.placement === 'root' ? 'root' : 'nested',
+				child.container ? 'container' : 'leaf',
+				child.supportsInserter ? 'visible' : 'hidden',
+			];
+			const line = `${ indent }- ${ child.key } -> ${ child.blockName } [${ labels.join( ', ' ) }]`;
+			return [ line, ...renderChildLines( child.blockName, `${ indent }  ` ) ];
+		} );
+	};
+
+	return [
+		'Compound child graph preview',
+		`Parent block: ${ PARENT_BLOCK_NAME }`,
+		...renderChildLines( PARENT_BLOCK_NAME, '' ),
+		'',
+		'Planned writes',
+		...plannedWritePaths.map( ( plannedWritePath ) => `- ${ plannedWritePath }` ),
+		options.dryRun ? '' : '',
+		options.dryRun
+			? 'Dry run only; no files were written.'
+			: 'Applying these updates now.',
+	]
+		.filter( ( line, index, lines ) => {
+			if ( line.length > 0 ) {
+				return true;
+			}
+
+			return index > 0 && lines[ index - 1 ].length > 0;
+		} )
+		.join( '\n' );
+}
+
+function updateAllowedBlocks(
+	filePath: string,
+	blockName: string
+) {
+	const blockJson = readBlockJsonDocument( filePath );
+	const existingAllowedBlocks = Array.isArray( blockJson.allowedBlocks )
+		? blockJson.allowedBlocks.filter(
+			( value ): value is string => typeof value === 'string'
+		)
+		: [];
+
+	if ( existingAllowedBlocks.includes( blockName ) ) {
+		return;
+	}
+
+	blockJson.allowedBlocks = [ ...existingAllowedBlocks, blockName ];
+	writeBlockJsonDocument( filePath, blockJson );
+}
+
 function renderBlockJson(
 	childBlockName: string,
 	childFolderSlug: string,
-	childTitle: string
+	childTitle: string,
+	options: {
+		allowedBlocks?: string[];
+		ancestorBlockNames: string[];
+		container: boolean;
+		supportsInserter: boolean;
+	}
 ): string {
 	const childCssClassName = buildBlockCssClassName( PARENT_BLOCK_NAMESPACE, childFolderSlug );
-
-	return `${ JSON.stringify(
-		{
-			$schema: 'https://schemas.wp.org/trunk/block.json',
-			apiVersion: 3,
-			name: childBlockName,
-			version: '{{blockMetadataVersion}}',
-			title: childTitle,
-			category: '{{compoundChildCategory}}',
-			icon: '{{compoundChildIcon}}',
-			description: `Internal item block used by ${ PARENT_BLOCK_TITLE }.`,
-			parent: [ PARENT_BLOCK_NAME ],
-			example: {},
-			supports: {
-				html: false,
-				inserter: false,
-				reusable: false,
+	const document: Record< string, unknown > = {
+		$schema: 'https://schemas.wp.org/trunk/block.json',
+		apiVersion: 3,
+		name: childBlockName,
+		version: '{{blockMetadataVersion}}',
+		title: childTitle,
+		category: '{{compoundChildCategory}}',
+		icon: '{{compoundChildIcon}}',
+		description: `Internal item block used by ${ PARENT_BLOCK_TITLE }.`,
+		example: {},
+		supports: {
+			html: false,
+			inserter: options.supportsInserter,
+			reusable: false,
+		},
+		attributes: {
+			title: {
+				type: 'string',
+				source: 'html',
+				selector: `.${ childCssClassName }__title`,
+				default: childTitle,
 			},
-			attributes: {
-				title: {
-					type: 'string',
-					source: 'html',
-					selector: `.${ childCssClassName }__title`,
-					default: childTitle,
-				},
-				body: {
-					type: 'string',
-					source: 'html',
-					selector: `.${ childCssClassName }__body`,
-					default: CHILD_PLACEHOLDER,
-				},
+			body: {
+				type: 'string',
+				source: 'html',
+				selector: `.${ childCssClassName }__body`,
+				default: CHILD_PLACEHOLDER,
 			},
-			textdomain: TEXT_DOMAIN,
-			editorScript: 'file:./index.js',
 		},
-		null,
-		'\t'
-	) }\n`;
+		textdomain: TEXT_DOMAIN,
+		editorScript: 'file:./index.js',
+	};
+
+	if ( options.ancestorBlockNames.length > 0 ) {
+		document.ancestor = options.ancestorBlockNames;
+	} else {
+		document.parent = [ PARENT_BLOCK_NAME ];
+	}
+
+	if ( options.container || ( options.allowedBlocks && options.allowedBlocks.length > 0 ) ) {
+		document.allowedBlocks = options.allowedBlocks ?? [];
+	}
+
+	return `${ JSON.stringify( document, null, '\t' ) }\n`;
 }
 
 function renderTypesFile(
@@ -491,10 +1002,15 @@ function renderEditFile(
 	const childCssClassName = buildBlockCssClassName( PARENT_BLOCK_NAMESPACE, childFolderSlug );
 
 	return `import type { BlockEditProps } from '@wp-typia/block-types/blocks/registration';
-import { RichText, useBlockProps } from '@wordpress/block-editor';
+import { InnerBlocks, RichText, useBlockProps } from '@wordpress/block-editor';
 import { Notice } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 
+import metadata from './block-metadata';
+import {
+\tgetChildInnerBlocksPropsOptions,
+\thasNestedChildBlocks,
+} from '../${ PARENT_BLOCK_SLUG }/children';
 import { useTypiaValidation } from './hooks';
 import type { ${ childTypeName } } from './types';
 import {
@@ -503,6 +1019,14 @@ import {
 } from './validators';
 
 type EditProps = BlockEditProps< ${ childTypeName } >;
+type CompoundInnerBlocksProps = Parameters< typeof InnerBlocks >[ 0 ] & {
+\tdefaultBlock?: [ string, Record< string, unknown > ];
+\tdirectInsert?: boolean;
+};
+
+const TypedInnerBlocks = InnerBlocks as unknown as (
+\tprops: CompoundInnerBlocksProps
+) => ReturnType< typeof InnerBlocks >;
 
 export default function Edit( {
 \tattributes,
@@ -513,6 +1037,10 @@ export default function Edit( {
 \t\tattributes,
 \t\tvalidate${ childInterfaceName }
 \t);
+\tconst nestedInnerBlocksPropsOptions = getChildInnerBlocksPropsOptions(
+\t\tmetadata.name
+\t);
+\tconst showsNestedChildren = hasNestedChildBlocks( metadata.name );
 
 \treturn (
 \t\t<div { ...useBlockProps( { className: '${ childCssClassName }' } ) }>
@@ -539,6 +1067,13 @@ export default function Edit( {
 \t\t\t\t\t</ul>
 \t\t\t\t</Notice>
 \t\t\t) }
+\t\t\t{ showsNestedChildren && (
+\t\t\t\t<div className="${ childCssClassName }__children">
+\t\t\t\t\t<TypedInnerBlocks
+\t\t\t\t\t\t{ ...( nestedInnerBlocksPropsOptions ?? {} ) }
+\t\t\t\t\t/>
+\t\t\t\t</div>
+\t\t\t) }
 \t\t</div>
 \t);
 }
@@ -548,8 +1083,10 @@ export default function Edit( {
 function renderSaveFile( childFolderSlug: string, childTypeName: string ): string {
 	const childCssClassName = buildBlockCssClassName( PARENT_BLOCK_NAMESPACE, childFolderSlug );
 
-	return `import { RichText, useBlockProps } from '@wordpress/block-editor';
+	return `import { InnerBlocks, RichText, useBlockProps } from '@wordpress/block-editor';
 
+import metadata from './block-metadata';
+import { hasNestedChildBlocks } from '../${ PARENT_BLOCK_SLUG }/children';
 import type { ${ childTypeName } } from './types';
 
 export default function Save( {
@@ -557,6 +1094,8 @@ export default function Save( {
 }: {
 \tattributes: ${ childTypeName };
 } ) {
+\tconst showsNestedChildren = hasNestedChildBlocks( metadata.name );
+
 \treturn (
 \t\t<div { ...useBlockProps.save( { className: '${ childCssClassName }' } ) }>
 \t\t\t<RichText.Content
@@ -569,13 +1108,18 @@ export default function Save( {
 \t\t\t\tclassName="${ childCssClassName }__body"
 \t\t\t\tvalue={ attributes.body }
 \t\t\t/>
+\t\t\t{ showsNestedChildren && (
+\t\t\t\t<div className="${ childCssClassName }__children">
+\t\t\t\t\t<InnerBlocks.Content />
+\t\t\t\t</div>
+\t\t\t) }
 \t\t</div>
 \t);
 }
 `;
 }
 
-function renderIndexFile( childTypeName: string, childFolderSlug: string ): string {
+function renderIndexFile( childTypeName: string ): string {
 return `import {
 \tregisterScaffoldBlockType,
 \ttype BlockConfiguration,
@@ -604,14 +1148,70 @@ registerScaffoldBlockType( registration.name, registration.settings );
 `;
 }
 
+function renderChildSpecLines(
+	options: {
+		ancestorKeys: string[];
+		blockName: string;
+		container: boolean;
+		folderSlug: string;
+		key: string;
+		placement: 'nested' | 'root';
+		seedTemplate: boolean;
+		supportsInserter: boolean;
+		title: string;
+	}
+): string[] {
+	const templateLines =
+		options.seedTemplate
+			? [
+				'\ttemplateInstances: [',
+				'\t\t{',
+				`\t\t\tbody: ${ JSON.stringify( CHILD_PLACEHOLDER ) },`,
+				`\t\t\ttitle: ${ JSON.stringify( options.title ) },`,
+				'\t\t},',
+				'\t],',
+			]
+			: [ '\ttemplateInstances: [],' ];
+
+	return [
+		'{',
+		`\tancestorKeys: [ ${ options.ancestorKeys.map( ( value ) => JSON.stringify( value ) ).join( ', ' ) } ],`,
+		`\tblockName: ${ JSON.stringify( options.blockName ) },`,
+		`\tbodyPlaceholder: ${ JSON.stringify( CHILD_PLACEHOLDER ) },`,
+		`\tcontainer: ${ options.container ? 'true' : 'false' },`,
+		`\tfolderSlug: ${ JSON.stringify( options.folderSlug ) },`,
+		`\tkey: ${ JSON.stringify( options.key ) },`,
+		`\tplacement: ${ JSON.stringify( options.placement ) },`,
+		`\tsupportsInserter: ${ options.supportsInserter ? 'true' : 'false' },`,
+		...templateLines,
+		`\ttitle: ${ JSON.stringify( options.title ) },`,
+		'},',
+	];
+}
+
 function main() {
-	const { slug, title } = parseArgs();
+	const {
+		ancestorValues,
+		container,
+		dryRun,
+		inserter,
+		slug,
+		title,
+	} = parseArgs();
 	const normalizedSlug = slug ? resolveValidatedBlockSlug( slug ) : '';
 
 	if ( normalizedSlug.length === 0 ) {
 		throw new Error( 'Use a child slug with lowercase letters, numbers, and hyphens only.' );
 	}
 
+	const existingChildren = listExistingCompoundChildren();
+	validateExistingCompoundChildGraph( existingChildren );
+	const ancestorChain = ensureUniqueAncestorChain(
+		ancestorValues.map( ( value ) =>
+			resolveExistingCompoundChild( value, existingChildren )
+		)
+	);
+	validateAncestorChain( ancestorChain );
 	const childTitle = title?.trim().length ? title.trim() : toTitleCase( normalizedSlug );
 	const childFolderSlug = `${ PARENT_BLOCK_SLUG }-${ normalizedSlug }`;
 	const childBlockName = `${ PARENT_BLOCK_NAME }-${ normalizedSlug }`;
@@ -628,6 +1228,10 @@ function main() {
 	);
 	const blockConfigFile = path.join( PROJECT_ROOT, 'scripts', 'block-config.ts' );
 
+	if ( ancestorChain.some( ( ancestor ) => ancestor.key === normalizedSlug ) ) {
+		throw new Error( 'A child block cannot list itself as an ancestor.' );
+	}
+
 	if ( fs.existsSync( childDir ) ) {
 		throw new Error( `Child block already exists: ${ childFolderSlug }` );
 	}
@@ -638,11 +1242,69 @@ function main() {
 		);
 	}
 
+	validateAncestorInstantiability( childrenFile, ancestorChain );
+	validateNestedAncestorTarget( ancestorChain );
+	const supportsInserter =
+		inserter === 'visible'
+			? true
+			: inserter === 'hidden'
+				? false
+				: container || ancestorChain.length > 0;
+	const placement = ancestorChain.length > 0 ? 'nested' : 'root';
+	const seedTemplate = supportsInserter || container || ancestorChain.length > 0;
+	const directAllowedBlocks: string[] = [];
+	const directAncestor = ancestorChain[ ancestorChain.length - 1 ];
+	const plannedWritePaths = [
+		formatProjectRelativePath( path.join( childDir, 'block.json' ) ),
+		formatProjectRelativePath( path.join( childDir, 'types.ts' ) ),
+		formatProjectRelativePath( path.join( childDir, 'typia.manifest.json' ) ),
+		formatProjectRelativePath( path.join( childDir, 'block-metadata.ts' ) ),
+		formatProjectRelativePath( path.join( childDir, 'manifest-document.ts' ) ),
+		formatProjectRelativePath( path.join( childDir, 'manifest-defaults-document.ts' ) ),
+		formatProjectRelativePath( path.join( childDir, 'hooks.ts' ) ),
+		formatProjectRelativePath( path.join( childDir, 'validators.ts' ) ),
+		formatProjectRelativePath( path.join( childDir, 'edit.tsx' ) ),
+		formatProjectRelativePath( path.join( childDir, 'save.tsx' ) ),
+		formatProjectRelativePath( path.join( childDir, 'index.tsx' ) ),
+		formatProjectRelativePath( childrenFile ),
+		formatProjectRelativePath( blockConfigFile ),
+		formatProjectRelativePath(
+			placement === 'root' ? PARENT_BLOCK_JSON_PATH : directAncestor.blockJsonPath
+		),
+	];
+
+	console.log(
+		renderCompoundChildGraphPreview(
+			buildCompoundChildGraphNodes( existingChildren, {
+				blockName: childBlockName,
+				container,
+				directParentBlockName:
+					directAncestor?.blockName ?? PARENT_BLOCK_NAME,
+				isProspective: true,
+				key: normalizedSlug,
+				placement,
+				supportsInserter,
+				title: childTitle,
+			} ),
+			plannedWritePaths,
+			{ dryRun }
+		)
+	);
+
+	if ( dryRun ) {
+		return;
+	}
+
 	fs.mkdirSync( childDir, { recursive: true } );
 
 	fs.writeFileSync(
 		path.join( childDir, 'block.json' ),
-		renderBlockJson( childBlockName, childFolderSlug, childTitle ),
+		renderBlockJson( childBlockName, childFolderSlug, childTitle, {
+			allowedBlocks: directAllowedBlocks,
+			ancestorBlockNames: ancestorChain.map( ( ancestor ) => ancestor.blockName ),
+			container,
+			supportsInserter,
+		} ),
 		'utf8'
 	);
 	fs.writeFileSync(
@@ -688,14 +1350,24 @@ function main() {
 	);
 	fs.writeFileSync(
 		path.join( childDir, 'index.tsx' ),
-		renderIndexFile( childTypeName, childFolderSlug ),
+		renderIndexFile( childTypeName ),
 		'utf8'
 	);
 
 	insertBeforeMarker(
 		childrenFile,
-		ALLOWED_CHILD_MARKER,
-		[ `'${ childBlockName }',` ]
+		CHILD_SPEC_MARKER,
+		renderChildSpecLines( {
+			ancestorKeys: ancestorChain.map( ( ancestor ) => ancestor.key ),
+			blockName: childBlockName,
+			container,
+			folderSlug: childFolderSlug,
+			key: normalizedSlug,
+			placement,
+			seedTemplate,
+			supportsInserter,
+			title: childTitle,
+		} )
 	);
 	insertBeforeMarker(
 		blockConfigFile,
@@ -709,6 +1381,13 @@ function main() {
 		]
 	);
 
+	if ( placement === 'root' ) {
+		updateAllowedBlocks( PARENT_BLOCK_JSON_PATH, childBlockName );
+	} else {
+		const directAncestor = ancestorChain[ ancestorChain.length - 1 ];
+		updateAllowedBlocks( directAncestor.blockJsonPath, childBlockName );
+	}
+
 	console.log( `✅ Added compound child block ${ childBlockName }` );
 	console.log(
 		'Run `sync-types` next to generate block.json metadata, manifests, schemas, and PHP validators for the new child block.'