@wp-typia/project-tools 0.16.6 → 0.16.8

package/README.md

@@ -6,7 +6,8 @@ Package roles:
 
 - `wp-typia` owns the CLI, help, TUI, completions, skills, MCP, and bin entry.
 - `@wp-typia/project-tools` owns scaffold, add-block, migrate, template, doctor, and schema project helpers.
-  It also owns the typed generator boundary via `BlockSpec` and `BlockGeneratorService`,
+  It also owns the typed generator boundary via `BlockSpec`, `BlockGeneratorService`,
+  and `inspectBlockGeneration(...)`,
   plus the emitter-owned built-in structural/code path where built-in
   templates no longer ship structural, TS/TSX, style, or block-local `render.php`
   Mustache files.
@@ -23,21 +24,23 @@ Implementation note:
 - `@wp-typia/project-tools/schema-core` remains the preferred project-tooling
   import path.
 - The shared implementation now lives in `@wp-typia/block-runtime/schema-core`.
+- Shared manifest/migration contract types now live in
+  `@wp-typia/block-runtime/migration-types`.
 
 Example:
 
 ```ts
 import {
-	BlockGeneratorService,
-	getTemplateById,
-	parseMigrationArgs,
-	projectJsonSchemaDocument,
-	resolvePackageManagerId,
-} from "@wp-typia/project-tools";
+  BlockGeneratorService,
+  getTemplateById,
+  parseMigrationArgs,
+  projectJsonSchemaDocument,
+  resolvePackageManagerId,
+} from '@wp-typia/project-tools';
 ```
 
 ```ts
-import { normalizeEndpointAuthDefinition } from "@wp-typia/project-tools/schema-core";
+import { normalizeEndpointAuthDefinition } from '@wp-typia/project-tools/schema-core';
 ```
 
 `BlockGeneratorService` is the additive typed orchestration boundary for built-in
@@ -48,4 +51,18 @@ files and starter `typia.manifest.json` now come from the emitter path, while
 project bootstrap/package-manager files, sync scripts, shared REST helpers, and
 the remaining non-block assets still come from Mustache-backed template copy.
 
+The higher-level generator architecture record, including the current phase map
+and the non-mutating `plan -> validate -> render -> apply` tool-facing usage
+model, lives in
+[`docs/block-generator-architecture.md`](../../docs/block-generator-architecture.md).
+The public non-mutating controller/tool contract now lives in
+[`docs/block-generator-tool-contract.md`](../../docs/block-generator-tool-contract.md).
+
+Reusable external layer packages on top of the built-in shared scaffold model
+are now available programmatically through `scaffoldProject(...)`,
+`BlockGeneratorService`, and `inspectBlockGeneration(...)` via
+`externalLayerSource` and optional `externalLayerId`. The RFC/CLI UX record
+still lives in
+[`docs/external-template-layer-composition.md`](../../docs/external-template-layer-composition.md).
+
 If you need metadata sync, editor helpers, validation helpers, or other generated-project runtime utilities, import them directly from `@wp-typia/block-runtime/*`.

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

@@ -41,6 +41,8 @@ export interface BlockSpec {
 export interface BlockGenerationTarget {
     allowExistingDir: boolean;
     cwd: string;
+    externalLayerId?: string;
+    externalLayerSource?: string;
     noInstall: boolean;
     packageManager: PackageManagerId;
     projectDir: string;
@@ -51,6 +53,8 @@ export interface PlanBlockInput {
     answers: ScaffoldAnswers;
     cwd?: string;
     dataStorageMode?: DataStorageMode;
+    externalLayerId?: string;
+    externalLayerSource?: string;
     noInstall?: boolean;
     packageManager: PackageManagerId;
     persistencePolicy?: PersistencePolicy;
@@ -95,7 +99,7 @@ export interface ApplyBlockInput {
 export declare function createBuiltInBlockSpec({ answers, dataStorageMode, persistencePolicy, templateId, withMigrationUi, withTestPreset, withWpEnv, }: Omit<PlanBlockInput, "allowExistingDir" | "cwd" | "noInstall" | "packageManager" | "projectDir" | "variant">): BlockSpec;
 export declare function buildTemplateVariablesFromBlockSpec(spec: BlockSpec): ScaffoldTemplateVariables;
 export declare class BlockGeneratorService {
-    plan({ allowExistingDir, answers, cwd, dataStorageMode, noInstall, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi, withTestPreset, withWpEnv, }: PlanBlockInput): Promise<PlanBlockResult>;
+    plan({ allowExistingDir, answers, cwd, dataStorageMode, externalLayerId, externalLayerSource, noInstall, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi, withTestPreset, withWpEnv, }: PlanBlockInput): Promise<PlanBlockResult>;
     validate({ plan }: ValidateBlockInput): Promise<ValidateBlockResult>;
     render({ validated }: RenderBlockInput): Promise<RenderBlockResult>;
     apply({ rendered, installDependencies, }: ApplyBlockInput): Promise<ScaffoldProjectResult>;

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

@@ -7,10 +7,62 @@ import { applyBuiltInScaffoldProjectFiles, buildGitignore, buildReadme, } from "
 import { buildBlockCssClassName, buildFrontendCssClassName, resolveScaffoldIdentifiers, } from "./scaffold-identifiers.js";
 import { buildBuiltInBlockArtifacts, } from "./built-in-block-artifacts.js";
 import { buildBuiltInCodeArtifacts, } from "./built-in-block-code-artifacts.js";
+import { getStarterManifestFiles } from "./starter-manifests.js";
+import { resolveTemplateSeed, parseTemplateLocator } from "./template-source.js";
+import { assertExternalTemplateLayersDoNotWriteProtectedOutputs, resolveExternalTemplateLayers, } from "./template-layers.js";
+import { getBuiltInTemplateOverlayDir, getBuiltInTemplateSharedLayerDirs, resolveBuiltInTemplateSourceFromLayerDirs, } from "./template-builtins.js";
 const renderedArtifactCache = new WeakMap();
 function createVariablesFingerprint(variables) {
     return JSON.stringify(variables);
 }
+function buildProtectedTemplateOutputPaths({ codeArtifacts, spec, variables, artifacts, }) {
+    const protectedOutputs = new Set([
+        ".gitignore",
+        "package.json",
+        "scripts/add-compound-child.ts",
+        "scripts/block-config.ts",
+        "scripts/sync-project.ts",
+        "scripts/sync-rest-contracts.ts",
+        "scripts/sync-types-to-block-json.ts",
+        "tsconfig.json",
+        "webpack.config.js",
+        `${variables.slugKebabCase}.php`,
+    ]);
+    for (const artifact of codeArtifacts) {
+        protectedOutputs.add(artifact.relativePath);
+    }
+    for (const artifact of artifacts) {
+        protectedOutputs.add(`${artifact.relativeDir}/block.json`);
+        protectedOutputs.add(`${artifact.relativeDir}/types.ts`);
+    }
+    for (const manifest of getStarterManifestFiles(spec.template.family, variables)) {
+        protectedOutputs.add(manifest.relativePath);
+    }
+    return protectedOutputs;
+}
+function buildCombinedTemplateLayerDirs({ baseLayerDirs, externalEntries, templateId, }) {
+    const orderedLayerDirs = [];
+    const seenLayerDirs = new Set();
+    for (const layerDir of baseLayerDirs) {
+        if (seenLayerDirs.has(layerDir)) {
+            continue;
+        }
+        orderedLayerDirs.push(layerDir);
+        seenLayerDirs.add(layerDir);
+    }
+    for (const entry of externalEntries) {
+        if (seenLayerDirs.has(entry.dir)) {
+            continue;
+        }
+        orderedLayerDirs.push(entry.dir);
+        seenLayerDirs.add(entry.dir);
+    }
+    const overlayDir = getBuiltInTemplateOverlayDir(templateId);
+    if (!seenLayerDirs.has(overlayDir)) {
+        orderedLayerDirs.push(overlayDir);
+    }
+    return orderedLayerDirs;
+}
 function getBuiltInPersistenceSpec({ templateId, dataStorageMode, persistencePolicy, }) {
     if (templateId === "persistence") {
         return {
@@ -146,7 +198,7 @@ export function buildTemplateVariablesFromBlockSpec(spec) {
     };
 }
 export class BlockGeneratorService {
-    async plan({ allowExistingDir = false, answers, cwd = process.cwd(), dataStorageMode, noInstall = false, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+    async plan({ allowExistingDir = false, answers, cwd = process.cwd(), dataStorageMode, externalLayerId, externalLayerSource, noInstall = false, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
         return {
             spec: createBuiltInBlockSpec({
                 answers,
@@ -160,6 +212,8 @@ export class BlockGeneratorService {
             target: {
                 allowExistingDir,
                 cwd,
+                externalLayerId,
+                externalLayerSource,
                 noInstall,
                 packageManager,
                 projectDir,
@@ -168,21 +222,90 @@ export class BlockGeneratorService {
         };
     }
     async validate({ plan }) {
+        if (plan.target.externalLayerId && !plan.target.externalLayerSource) {
+            throw new Error("externalLayerId requires externalLayerSource when composing built-in template layers.");
+        }
         if (plan.target.variant) {
             throw new Error(`--variant is only supported for official external template configs. Received variant "${plan.target.variant}" for built-in template "${plan.spec.template.family}".`);
         }
         return plan;
     }
     async render({ validated }) {
-        const templateSource = await resolveBuiltInTemplateSource(validated.spec.template.family, {
-            persistenceEnabled: validated.spec.persistence.enabled,
+        const variables = buildTemplateVariablesFromBlockSpec(validated.spec);
+        const persistenceEnabled = validated.spec.persistence.enabled;
+        const artifacts = buildBuiltInBlockArtifacts({
+            templateId: validated.spec.template.family,
+            variables,
+        });
+        const codeArtifacts = buildBuiltInCodeArtifacts({
+            templateId: validated.spec.template.family,
+            variables,
+        });
+        const templateVariantOptions = {
+            persistenceEnabled,
             persistencePolicy: validated.spec.persistence.enabled &&
                 validated.spec.persistence.persistencePolicy === "public"
                 ? "public"
                 : "authenticated",
-        });
-        const variables = buildTemplateVariablesFromBlockSpec(validated.spec);
-        const persistenceEnabled = validated.spec.persistence.enabled;
+        };
+        let templateSource = await resolveBuiltInTemplateSource(validated.spec.template.family, templateVariantOptions);
+        const warnings = [...(templateSource.warnings ?? [])];
+        if (validated.target.externalLayerSource) {
+            let layerSeed;
+            try {
+                layerSeed = await resolveTemplateSeed(parseTemplateLocator(validated.target.externalLayerSource), validated.target.cwd);
+                const resolvedLayers = await resolveExternalTemplateLayers({
+                    externalLayerId: validated.target.externalLayerId,
+                    sourceRoot: layerSeed.rootDir,
+                });
+                const baseLayerDirs = getBuiltInTemplateSharedLayerDirs(validated.spec.template.family, templateVariantOptions);
+                await assertExternalTemplateLayersDoNotWriteProtectedOutputs({
+                    externalEntries: resolvedLayers.entries,
+                    protectedOutputPaths: buildProtectedTemplateOutputPaths({
+                        artifacts,
+                        codeArtifacts,
+                        spec: validated.spec,
+                        variables,
+                    }),
+                    view: variables,
+                });
+                await templateSource.cleanup?.();
+                templateSource = await resolveBuiltInTemplateSourceFromLayerDirs(validated.spec.template.family, buildCombinedTemplateLayerDirs({
+                    baseLayerDirs,
+                    externalEntries: resolvedLayers.entries,
+                    templateId: validated.spec.template.family,
+                }));
+                const layerSourceCleanup = layerSeed.cleanup;
+                const templateCleanup = templateSource.cleanup;
+                templateSource.cleanup = async () => {
+                    const cleanupErrors = [];
+                    try {
+                        await templateCleanup?.();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error instanceof Error ? error : new Error(String(error)));
+                    }
+                    try {
+                        await layerSourceCleanup?.();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error instanceof Error ? error : new Error(String(error)));
+                    }
+                    if (cleanupErrors.length > 0) {
+                        throw new Error([
+                            "Failed to cleanup composed template sources.",
+                            ...cleanupErrors.map((error) => `- ${error.message}`),
+                        ].join("\n"));
+                    }
+                };
+                warnings.push(`Applied external layer "${resolvedLayers.selectedLayerId}" from "${validated.target.externalLayerSource}".`);
+            }
+            catch (error) {
+                await templateSource.cleanup?.();
+                await layerSeed?.cleanup?.();
+                throw error;
+            }
+        }
         const rendered = {
             ...validated,
             cleanup: templateSource.cleanup,
@@ -202,17 +325,11 @@ export class BlockGeneratorService {
             selectedVariant: null,
             templateDir: templateSource.templateDir,
             variables,
-            warnings: templateSource.warnings ?? [],
+            warnings,
         };
         renderedArtifactCache.set(rendered, {
-            artifacts: buildBuiltInBlockArtifacts({
-                templateId: validated.spec.template.family,
-                variables,
-            }),
-            codeArtifacts: buildBuiltInCodeArtifacts({
-                templateId: validated.spec.template.family,
-                variables,
-            }),
+            artifacts,
+            codeArtifacts,
             variablesFingerprint: createVariablesFingerprint(variables),
         });
         return rendered;

package/dist/runtime/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-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/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?.();
+    }
+}