@wp-typia/project-tools 0.24.3 → 0.24.5

package/dist/runtime/templates/block-generator-service-spec.js

@@ -0,0 +1,419 @@
+import { getPackageVersions } from "../shared/package-versions.js";
+import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, } from "./template-defaults.js";
+import { formatAlternateRenderTargets, parseAlternateRenderTargets, } from "../add/alternate-render-targets.js";
+import { DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID, getCompoundInnerBlocksPresetDefinition, } from "../add/compound-inner-blocks.js";
+import { getTemplateById, } from "./template-registry.js";
+import { toPascalCase, toSnakeCase, } from "../shared/string-case.js";
+import { buildBlockCssClassName, buildFrontendCssClassName, resolveScaffoldIdentifiers, } from "./scaffold-identifiers.js";
+import { resolveScaffoldCompatibilityPolicy } from "./scaffold-compatibility.js";
+import { attachScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
+function getBuiltInPersistenceSpec({ templateId, dataStorageMode, persistencePolicy, }) {
+    if (templateId === "persistence") {
+        return {
+            dataStorageMode: dataStorageMode ?? "custom-table",
+            enabled: true,
+            persistencePolicy: persistencePolicy ?? "authenticated",
+            scope: "single",
+        };
+    }
+    if (templateId === "compound" && (dataStorageMode || persistencePolicy)) {
+        return {
+            dataStorageMode: dataStorageMode ?? "custom-table",
+            enabled: true,
+            persistencePolicy: persistencePolicy ?? "authenticated",
+            scope: "compound-parent",
+        };
+    }
+    return {
+        enabled: false,
+    };
+}
+const DEFAULT_QUERY_LOOP_ALLOWED_CONTROLS = [
+    "inherit",
+    "postType",
+    "order",
+    "sticky",
+    "taxQuery",
+    "author",
+    "search",
+];
+export function createBuiltInBlockSpec({ alternateRenderTargets, answers, dataStorageMode, persistencePolicy, templateId, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+    const template = getTemplateById(templateId);
+    const metadataDefaults = getBuiltInTemplateMetadataDefaults(templateId);
+    const identifiers = resolveScaffoldIdentifiers({
+        namespace: answers.namespace,
+        phpPrefix: answers.phpPrefix,
+        slug: answers.slug,
+        textDomain: answers.textDomain,
+    });
+    const resolvedDataStorageMode = dataStorageMode ?? answers.dataStorageMode;
+    const resolvedPersistencePolicy = persistencePolicy ?? answers.persistencePolicy;
+    const parsedAlternateRenderTargets = parseAlternateRenderTargets(alternateRenderTargets);
+    const innerBlocksPreset = templateId === "compound"
+        ? (answers.compoundInnerBlocksPreset ??
+            DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID)
+        : DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID;
+    return {
+        alternateRenderTargets: parsedAlternateRenderTargets,
+        block: identifiers,
+        compound: {
+            innerBlocksPreset,
+        },
+        metadata: {
+            category: metadataDefaults.category,
+            description: answers.description.trim(),
+            icon: metadataDefaults.icon,
+            keyword: identifiers.slug.replace(/-/g, " "),
+            title: answers.title.trim(),
+        },
+        persistence: getBuiltInPersistenceSpec({
+            dataStorageMode: resolvedDataStorageMode,
+            persistencePolicy: resolvedPersistencePolicy,
+            templateId,
+        }),
+        project: {
+            author: answers.author.trim(),
+        },
+        queryLoop: templateId === "query-loop"
+            ? {
+                allowedControls: DEFAULT_QUERY_LOOP_ALLOWED_CONTROLS,
+                enabled: true,
+                postType: (answers.queryPostType ?? "post").trim() || "post",
+            }
+            : {
+                allowedControls: [],
+                enabled: false,
+                postType: "post",
+            },
+        runtime: {
+            withMigrationUi,
+            withTestPreset,
+            withWpEnv,
+        },
+        template: {
+            description: template.description,
+            family: templateId,
+            features: [...template.features],
+        },
+    };
+}
+export function buildTemplateVariablesFromBlockSpec(spec) {
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, wpTypiaPackageVersion, } = getPackageVersions();
+    const slug = spec.block.slug;
+    const slugSnakeCase = toSnakeCase(slug);
+    const pascalCase = toPascalCase(slug);
+    const title = spec.metadata.title;
+    const namespace = spec.block.namespace;
+    const textDomain = spec.block.textDomain;
+    const phpPrefix = spec.block.phpPrefix;
+    const phpPrefixUpper = phpPrefix.toUpperCase();
+    const alternateRenderTargets = [...spec.alternateRenderTargets];
+    const hasAlternateEmailRenderTarget = alternateRenderTargets.includes("email");
+    const hasAlternateMjmlRenderTarget = alternateRenderTargets.includes("mjml");
+    const hasAlternatePlainTextRenderTarget = alternateRenderTargets.includes("plain-text");
+    const compoundChildTitle = `${title} Item`;
+    const cssClassName = buildBlockCssClassName(namespace, slug);
+    const compoundChildCssClassName = buildBlockCssClassName(namespace, `${slug}-item`);
+    const compoundInnerBlocksPreset = spec.compound.innerBlocksPreset;
+    const compoundInnerBlocksPresetDefinition = getCompoundInnerBlocksPresetDefinition(compoundInnerBlocksPreset);
+    const compoundInnerBlocksOrientation = compoundInnerBlocksPresetDefinition.orientation ?? "";
+    const persistenceEnabled = spec.persistence.enabled;
+    const dataStorageMode = persistenceEnabled ? spec.persistence.dataStorageMode : "custom-table";
+    const persistencePolicy = persistenceEnabled
+        ? spec.persistence.persistencePolicy
+        : "authenticated";
+    const queryVariationNamespace = `${namespace}/${slug}`;
+    const compatibility = resolveScaffoldCompatibilityPolicy([]);
+    const flatVariables = {
+        alternateRenderTargetsCsv: formatAlternateRenderTargets(alternateRenderTargets),
+        alternateRenderTargetsJson: JSON.stringify(alternateRenderTargets),
+        apiClientPackageVersion,
+        author: spec.project.author,
+        blockRuntimePackageVersion,
+        blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
+        blockTypesPackageVersion,
+        category: spec.metadata.category,
+        icon: spec.metadata.icon,
+        compoundChildTitle,
+        compoundChildCategory: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.category,
+        compoundChildCssClassName,
+        compoundChildIcon: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.icon,
+        compoundChildTitleJson: JSON.stringify(compoundChildTitle),
+        compoundPersistenceEnabled: spec.template.family === "compound" && persistenceEnabled ? "true" : "false",
+        compoundInnerBlocksDirectInsert: compoundInnerBlocksPresetDefinition.directInsert ? "true" : "false",
+        compoundInnerBlocksOrientation: compoundInnerBlocksOrientation,
+        compoundInnerBlocksOrientationExpression: compoundInnerBlocksPresetDefinition.orientation
+            ? `'${compoundInnerBlocksPresetDefinition.orientation}'`
+            : "undefined",
+        compoundInnerBlocksPreset,
+        compoundInnerBlocksPresetDescription: compoundInnerBlocksPresetDefinition.description,
+        compoundInnerBlocksPresetLabel: compoundInnerBlocksPresetDefinition.label,
+        compoundInnerBlocksTemplateLockExpression: compoundInnerBlocksPresetDefinition.templateLock === false
+            ? "false"
+            : `'${compoundInnerBlocksPresetDefinition.templateLock}'`,
+        hasAlternateEmailRenderTarget: hasAlternateEmailRenderTarget
+            ? "true"
+            : "false",
+        hasAlternateMjmlRenderTarget: hasAlternateMjmlRenderTarget
+            ? "true"
+            : "false",
+        hasAlternatePlainTextRenderTarget: hasAlternatePlainTextRenderTarget
+            ? "true"
+            : "false",
+        hasAlternateRenderTargets: alternateRenderTargets.length > 0
+            ? "true"
+            : "false",
+        requiresAtLeast: compatibility.pluginHeader.requiresAtLeast,
+        requiresPhp: compatibility.pluginHeader.requiresPhp,
+        testedUpTo: compatibility.pluginHeader.testedUpTo,
+        projectToolsPackageVersion,
+        wpTypiaPackageVersion,
+        cssClassName,
+        dashCase: slug,
+        dataStorageMode,
+        description: spec.metadata.description,
+        descriptionJson: JSON.stringify(spec.metadata.description),
+        frontendCssClassName: buildFrontendCssClassName(cssClassName),
+        queryAllowedControlsJson: JSON.stringify(spec.queryLoop.enabled ? spec.queryLoop.allowedControls : [], null, 2),
+        queryPostType: spec.queryLoop.enabled ? spec.queryLoop.postType : "post",
+        queryPostTypeJson: JSON.stringify(spec.queryLoop.enabled ? spec.queryLoop.postType : "post"),
+        queryVariationNamespace,
+        queryVariationNamespaceJson: JSON.stringify(queryVariationNamespace),
+        isAuthenticatedPersistencePolicy: persistencePolicy === "authenticated" ? "true" : "false",
+        isPublicPersistencePolicy: persistencePolicy === "public" ? "true" : "false",
+        bootstrapCredentialDeclarations: persistencePolicy === "public"
+            ? "publicWriteExpiresAt?: number & tags.Type< 'uint32' >;\n\tpublicWriteToken?: string & tags.MinLength< 1 > & tags.MaxLength< 512 >;"
+            : "restNonce?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
+        persistencePolicyDescriptionJson: JSON.stringify(persistencePolicy === "authenticated"
+            ? "Writes require a logged-in user and a valid REST nonce."
+            : "Anonymous writes use signed short-lived public tokens, per-request ids, and coarse rate limiting."),
+        keyword: spec.metadata.keyword,
+        namespace,
+        needsMigration: "{{needsMigration}}",
+        pascalCase,
+        phpPrefix,
+        phpPrefixUpper,
+        restPackageVersion,
+        publicWriteRequestIdDeclaration: persistencePolicy === "public"
+            ? "publicWriteRequestId: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;"
+            : "publicWriteRequestId?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
+        restWriteAuthIntent: persistencePolicy === "public"
+            ? "public-write-protected"
+            : "authenticated",
+        restWriteAuthMechanism: persistencePolicy === "public" ? "public-signed-token" : "rest-nonce",
+        restWriteAuthMode: persistencePolicy === "public" ? "public-signed-token" : "authenticated-rest-nonce",
+        slug,
+        slugCamelCase: pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1),
+        slugKebabCase: slug,
+        slugSnakeCase,
+        textDomain,
+        textdomain: textDomain,
+        title,
+        titleJson: JSON.stringify(title),
+        titleCase: pascalCase,
+        persistencePolicy,
+    };
+    const shared = {
+        author: spec.project.author,
+        blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
+        category: spec.metadata.category,
+        compatibility: compatibility.pluginHeader,
+        cssClassName,
+        description: spec.metadata.description,
+        descriptionJson: flatVariables.descriptionJson,
+        frontendCssClassName: flatVariables.frontendCssClassName,
+        icon: spec.metadata.icon,
+        keyword: spec.metadata.keyword,
+        namespace,
+        pascalCase,
+        phpPrefix,
+        phpPrefixUpper,
+        slug,
+        slugCamelCase: flatVariables.slugCamelCase,
+        slugKebabCase: slug,
+        slugSnakeCase,
+        textDomain,
+        title,
+        titleCase: pascalCase,
+        titleJson: flatVariables.titleJson,
+        versions: {
+            apiClient: apiClientPackageVersion,
+            blockRuntime: blockRuntimePackageVersion,
+            blockTypes: blockTypesPackageVersion,
+            projectTools: projectToolsPackageVersion,
+            rest: restPackageVersion,
+        },
+    };
+    const alternateRenderTargetsGroup = {
+        csv: flatVariables.alternateRenderTargetsCsv,
+        enabled: alternateRenderTargets.length > 0,
+        hasEmail: hasAlternateEmailRenderTarget,
+        hasMjml: hasAlternateMjmlRenderTarget,
+        hasPlainText: hasAlternatePlainTextRenderTarget,
+        json: flatVariables.alternateRenderTargetsJson,
+        targets: alternateRenderTargets,
+    };
+    const compoundGroup = {
+        child: {
+            category: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.category,
+            cssClassName: compoundChildCssClassName,
+            icon: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.icon,
+            title: compoundChildTitle,
+            titleJson: JSON.stringify(compoundChildTitle),
+        },
+        enabled: true,
+        innerBlocks: {
+            description: compoundInnerBlocksPresetDefinition.description,
+            directInsert: compoundInnerBlocksPresetDefinition.directInsert,
+            label: compoundInnerBlocksPresetDefinition.label,
+            orientation: compoundInnerBlocksOrientation,
+            orientationExpression: compoundInnerBlocksPresetDefinition.orientation
+                ? `'${compoundInnerBlocksPresetDefinition.orientation}'`
+                : "undefined",
+            preset: compoundInnerBlocksPreset,
+            templateLockExpression: compoundInnerBlocksPresetDefinition.templateLock === false
+                ? "false"
+                : `'${compoundInnerBlocksPresetDefinition.templateLock}'`,
+        },
+        persistenceEnabled: persistenceEnabled,
+    };
+    const persistenceGroup = persistenceEnabled
+        ? {
+            auth: {
+                bootstrapCredentialDeclarations: flatVariables.bootstrapCredentialDeclarations,
+                descriptionJson: flatVariables.persistencePolicyDescriptionJson,
+                intent: flatVariables.restWriteAuthIntent,
+                isAuthenticated: persistencePolicy === "authenticated",
+                isPublic: persistencePolicy === "public",
+                mechanism: flatVariables.restWriteAuthMechanism,
+                mode: flatVariables.restWriteAuthMode,
+                publicWriteRequestIdDeclaration: flatVariables.publicWriteRequestIdDeclaration,
+            },
+            dataStorageMode,
+            enabled: true,
+            policy: persistencePolicy,
+            scope: spec.persistence.scope,
+        }
+        : null;
+    const queryLoopGroup = {
+        allowedControls: spec.queryLoop.allowedControls,
+        allowedControlsJson: flatVariables.queryAllowedControlsJson,
+        enabled: true,
+        postType: spec.queryLoop.postType,
+        postTypeJson: flatVariables.queryPostTypeJson,
+        variationNamespace: queryVariationNamespace,
+        variationNamespaceJson: flatVariables.queryVariationNamespaceJson,
+    };
+    switch (spec.template.family) {
+        case "basic":
+            return attachScaffoldTemplateVariableGroups(flatVariables, {
+                alternateRenderTargets: alternateRenderTargetsGroup,
+                compound: {
+                    enabled: false,
+                    persistenceEnabled: false,
+                },
+                persistence: {
+                    enabled: false,
+                    scope: "none",
+                },
+                queryLoop: {
+                    enabled: false,
+                },
+                shared,
+                template: {
+                    description: spec.template.description,
+                },
+                templateFamily: "basic",
+            });
+        case "interactivity":
+            return attachScaffoldTemplateVariableGroups(flatVariables, {
+                alternateRenderTargets: alternateRenderTargetsGroup,
+                compound: {
+                    enabled: false,
+                    persistenceEnabled: false,
+                },
+                persistence: {
+                    enabled: false,
+                    scope: "none",
+                },
+                queryLoop: {
+                    enabled: false,
+                },
+                shared,
+                template: {
+                    description: spec.template.description,
+                },
+                templateFamily: "interactivity",
+            });
+        case "persistence": {
+            if (persistenceGroup === null) {
+                throw new Error("Persistence scaffolds must provide persistence template variables.");
+            }
+            return attachScaffoldTemplateVariableGroups(flatVariables, {
+                alternateRenderTargets: alternateRenderTargetsGroup,
+                compound: {
+                    enabled: false,
+                    persistenceEnabled: false,
+                },
+                persistence: {
+                    ...persistenceGroup,
+                    scope: "single",
+                },
+                queryLoop: {
+                    enabled: false,
+                },
+                shared,
+                template: {
+                    description: spec.template.description,
+                },
+                templateFamily: "persistence",
+            });
+        }
+        case "compound": {
+            const compoundPersistenceGroup = persistenceGroup === null
+                ? {
+                    enabled: false,
+                    scope: "none",
+                }
+                : {
+                    ...persistenceGroup,
+                    scope: "compound-parent",
+                };
+            return attachScaffoldTemplateVariableGroups(flatVariables, {
+                alternateRenderTargets: alternateRenderTargetsGroup,
+                compound: compoundGroup,
+                persistence: compoundPersistenceGroup,
+                queryLoop: {
+                    enabled: false,
+                },
+                shared,
+                template: {
+                    description: spec.template.description,
+                },
+                templateFamily: "compound",
+            });
+        }
+        case "query-loop":
+            return attachScaffoldTemplateVariableGroups(flatVariables, {
+                alternateRenderTargets: alternateRenderTargetsGroup,
+                compound: {
+                    enabled: false,
+                    persistenceEnabled: false,
+                },
+                persistence: {
+                    enabled: false,
+                    scope: "none",
+                },
+                queryLoop: queryLoopGroup,
+                shared,
+                template: {
+                    description: spec.template.description,
+                },
+                templateFamily: "query-loop",
+            });
+        default: {
+            const unreachableTemplateFamily = spec.template.family;
+            throw new Error(`Unhandled scaffold template family: ${unreachableTemplateFamily}`);
+        }
+    }
+}

package/dist/runtime/templates/block-generator-service.d.ts

@@ -0,0 +1,2 @@
+export * from "./block-generator-service-spec.js";
+export * from "./block-generator-service-core.js";

package/dist/runtime/templates/block-generator-service.js

@@ -0,0 +1,2 @@
+export * from "./block-generator-service-spec.js";
+export * from "./block-generator-service-core.js";

package/dist/runtime/templates/block-generator-tool-contract.d.ts

@@ -0,0 +1,93 @@
+import { BlockGeneratorService, type PlanBlockInput, type PlanBlockResult, type RenderBlockResult, type ValidateBlockResult } from "./block-generator-service.js";
+import type { ManifestDocument } from "../migration/migration-types.js";
+import type { BuiltInTemplateId } from "./template-registry.js";
+/**
+ * Semantic version marker for the public block generation tool contract.
+ *
+ * Increment this number whenever the serialized inspection payload changes in a
+ * breaking way.
+ */
+export declare const BLOCK_GENERATION_TOOL_CONTRACT_VERSION: 1;
+/**
+ * Staged execution points for the non-mutating inspection workflow.
+ *
+ * - `"plan"` returns the normalized `BlockSpec` and target metadata.
+ * - `"validate"` returns the validated generation stage without rendering.
+ * - `"render"` returns the full non-mutating preview, including copied and
+ *   emitted file snapshots.
+ */
+export type BlockGenerationToolStage = "plan" | "validate" | "render";
+/**
+ * Input for the staged, non-mutating block generation inspection entrypoint.
+ *
+ * Extends `PlanBlockInput` with an optional `stopAfter` selector so callers can
+ * stop at `plan`, `validate`, or continue through the full `render` preview.
+ */
+export interface InspectBlockGenerationInput extends PlanBlockInput {
+    stopAfter?: BlockGenerationToolStage;
+}
+export interface BlockGenerationTemplateCopyPreview {
+    owner: "template-copy";
+    relativePath: string;
+}
+export interface BlockGenerationEmittedFilePreview {
+    kind: "generated-source" | "starter-manifest" | "structural";
+    owner: "emitter";
+    relativePath: string;
+    source: string;
+}
+export interface BlockGenerationStarterManifestPreview {
+    document: ManifestDocument;
+    owner: "emitter";
+    relativePath: string;
+    source: string;
+}
+export interface BlockGenerationRenderPreview {
+    copiedTemplateFiles: BlockGenerationTemplateCopyPreview[];
+    emittedFiles: BlockGenerationEmittedFilePreview[];
+    postRender: RenderBlockResult["postRender"] & {
+        installsDependencies: boolean;
+    };
+    selectedVariant: null;
+    starterManifestFiles: BlockGenerationStarterManifestPreview[];
+    template: {
+        description: string;
+        family: BuiltInTemplateId;
+        features: string[];
+        format: "wp-typia";
+    };
+    warnings: string[];
+    readmeContent: string;
+    gitignoreContent: string;
+}
+interface BlockGenerationInspectionBase {
+    contractVersion: typeof BLOCK_GENERATION_TOOL_CONTRACT_VERSION;
+    mutatesWorkspace: false;
+    stage: BlockGenerationToolStage;
+}
+export interface InspectBlockGenerationPlanResult extends BlockGenerationInspectionBase {
+    plan: PlanBlockResult;
+    stage: "plan";
+}
+export interface InspectBlockGenerationValidateResult extends BlockGenerationInspectionBase {
+    plan: PlanBlockResult;
+    stage: "validate";
+    validated: ValidateBlockResult;
+}
+export interface InspectBlockGenerationRenderResult extends BlockGenerationInspectionBase {
+    plan: PlanBlockResult;
+    rendered: BlockGenerationRenderPreview;
+    stage: "render";
+    validated: ValidateBlockResult;
+}
+export type InspectBlockGenerationResult = InspectBlockGenerationPlanResult | InspectBlockGenerationValidateResult | InspectBlockGenerationRenderResult;
+export declare function inspectBlockGeneration(input: InspectBlockGenerationInput & {
+    stopAfter: "plan";
+}, service?: BlockGeneratorService): Promise<InspectBlockGenerationPlanResult>;
+export declare function inspectBlockGeneration(input: InspectBlockGenerationInput & {
+    stopAfter: "validate";
+}, service?: BlockGeneratorService): Promise<InspectBlockGenerationValidateResult>;
+export declare function inspectBlockGeneration(input: InspectBlockGenerationInput & {
+    stopAfter?: "render" | undefined;
+}, service?: BlockGeneratorService): Promise<InspectBlockGenerationRenderResult>;
+export {};

package/dist/runtime/templates/block-generator-tool-contract.js

@@ -0,0 +1,157 @@
+import { buildBuiltInBlockArtifacts, stringifyBuiltInBlockJsonDocument, } from "./built-in-block-artifacts.js";
+import { buildBuiltInCodeArtifacts, } from "./built-in-block-code-artifacts.js";
+import { BlockGeneratorService, } from "./block-generator-service.js";
+import { getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
+import { listInterpolatedDirectoryOutputs } from "./template-render.js";
+/**
+ * Semantic version marker for the public block generation tool contract.
+ *
+ * Increment this number whenever the serialized inspection payload changes in a
+ * breaking way.
+ */
+export const BLOCK_GENERATION_TOOL_CONTRACT_VERSION = 1;
+function buildStarterManifestPreviews(templateId, variables, artifacts) {
+    const starterManifests = getStarterManifestFiles(templateId, variables);
+    const artifactManifests = new Map(artifacts.map((artifact) => [
+        `${artifact.relativeDir}/typia.manifest.json`,
+        artifact.manifestDocument,
+    ]));
+    return starterManifests
+        .map((entry) => {
+        const document = artifactManifests.get(entry.relativePath) ?? entry.document;
+        return {
+            document,
+            owner: "emitter",
+            relativePath: entry.relativePath,
+            source: stringifyStarterManifest(document),
+        };
+    })
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function buildStructuralArtifactPreviews(artifacts) {
+    return artifacts
+        .flatMap((artifact) => [
+        {
+            kind: "structural",
+            owner: "emitter",
+            relativePath: `${artifact.relativeDir}/block.json`,
+            source: stringifyBuiltInBlockJsonDocument(artifact.blockJsonDocument),
+        },
+        {
+            kind: "structural",
+            owner: "emitter",
+            relativePath: `${artifact.relativeDir}/types.ts`,
+            source: artifact.typesSource,
+        },
+    ])
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function buildCodeArtifactPreviews(codeArtifacts) {
+    return codeArtifacts
+        .map((artifact) => ({
+        kind: "generated-source",
+        owner: "emitter",
+        relativePath: artifact.relativePath,
+        source: artifact.source,
+    }))
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+async function buildRenderPreview(rendered) {
+    const artifacts = buildBuiltInBlockArtifacts({
+        templateId: rendered.spec.template.family,
+        variables: rendered.variables,
+    });
+    const codeArtifacts = buildBuiltInCodeArtifacts({
+        templateId: rendered.spec.template.family,
+        variables: rendered.variables,
+    });
+    const copiedTemplateFiles = await listInterpolatedDirectoryOutputs(rendered.templateDir, rendered.variables);
+    return {
+        copiedTemplateFiles: copiedTemplateFiles.map((relativePath) => ({
+            owner: "template-copy",
+            relativePath,
+        })),
+        emittedFiles: [
+            ...buildStructuralArtifactPreviews(artifacts),
+            ...buildCodeArtifactPreviews(codeArtifacts),
+        ].sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
+        gitignoreContent: rendered.gitignoreContent,
+        postRender: {
+            ...rendered.postRender,
+            installsDependencies: !rendered.target.noInstall,
+        },
+        readmeContent: rendered.readmeContent,
+        selectedVariant: rendered.selectedVariant,
+        starterManifestFiles: buildStarterManifestPreviews(rendered.spec.template.family, rendered.variables, artifacts),
+        template: {
+            description: rendered.spec.template.description,
+            family: rendered.spec.template.family,
+            features: [...rendered.spec.template.features],
+            format: "wp-typia",
+        },
+        warnings: [...rendered.warnings],
+    };
+}
+/**
+ * Inspects built-in block generation through the staged generator boundary
+ * without mutating the destination workspace.
+ *
+ * Use `stopAfter` to halt after the `plan`, `validate`, or `render` stage.
+ * The render stage includes copied template file paths, emitter-owned source
+ * previews, starter manifest previews, and post-render intent metadata. Any
+ * temporary render state is cleaned up before the promise resolves.
+ *
+ * @example
+ * ```ts
+ * const inspection = await inspectBlockGeneration({
+ * 	answers,
+ * 	noInstall: true,
+ * 	packageManager: "bun",
+ * 	projectDir: "demo-block",
+ * 	templateId: "basic",
+ * 	stopAfter: "render",
+ * });
+ * ```
+ *
+ * @param input - Planning input plus an optional `stopAfter` stage selector.
+ * @param service - Optional generator service instance. Defaults to a new
+ * `BlockGeneratorService`.
+ * @returns The serialized inspection result for the reached stage.
+ * @throws Propagates planning, validation, or render failures from
+ * `BlockGeneratorService`.
+ */
+export async function inspectBlockGeneration({ stopAfter = "render", ...planInput }, service = new BlockGeneratorService()) {
+    const plan = await service.plan(planInput);
+    if (stopAfter === "plan") {
+        return {
+            contractVersion: BLOCK_GENERATION_TOOL_CONTRACT_VERSION,
+            mutatesWorkspace: false,
+            plan,
+            stage: "plan",
+        };
+    }
+    const validated = await service.validate({ plan });
+    if (stopAfter === "validate") {
+        return {
+            contractVersion: BLOCK_GENERATION_TOOL_CONTRACT_VERSION,
+            mutatesWorkspace: false,
+            plan,
+            stage: "validate",
+            validated,
+        };
+    }
+    const rendered = await service.render({ validated });
+    try {
+        return {
+            contractVersion: BLOCK_GENERATION_TOOL_CONTRACT_VERSION,
+            mutatesWorkspace: false,
+            plan,
+            rendered: await buildRenderPreview(rendered),
+            stage: "render",
+            validated,
+        };
+    }
+    finally {
+        await rendered.cleanup?.();
+    }
+}

package/dist/runtime/templates/built-in-block-artifact-documents.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_COMPOUND_CHILD_BODY_PLACEHOLDER, buildBlockJsonAttributes, buildManifestDocument, } from "./built-in-block-attribute-emitters.js";
+export type { AttributeDescription, EmittedAttributeDefinition, } from "./built-in-block-attribute-emitters.js";
+export { buildBasicAttributes, buildCompoundChildAttributes, buildCompoundParentAttributes, buildInteractivityAttributes, buildPersistenceAttributes, } from "./built-in-block-attribute-specs.js";

package/dist/runtime/templates/built-in-block-artifact-documents.js

@@ -0,0 +1,2 @@
+export { DEFAULT_COMPOUND_CHILD_BODY_PLACEHOLDER, buildBlockJsonAttributes, buildManifestDocument, } from "./built-in-block-attribute-emitters.js";
+export { buildBasicAttributes, buildCompoundChildAttributes, buildCompoundParentAttributes, buildInteractivityAttributes, buildPersistenceAttributes, } from "./built-in-block-attribute-specs.js";