@wp-typia/project-tools 0.16.7 → 0.16.9

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.
@@ -50,4 +51,28 @@ 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.
 
+Generated projects now consume JSON artifacts through typed wrapper modules
+instead of local casts:
+
+- `block-metadata.ts` for `block.json`
+- `manifest-document.ts` for editor and migration consumers of
+  `typia.manifest.json`
+- `manifest-defaults-document.ts` for validator/defaults consumers of
+  `typia.manifest.json`
+
+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 through the canonical built-in CLI flags
+`wp-typia create --external-layer-source ... [--external-layer-id ...]`,
+`wp-typia add block --external-layer-source ... [--external-layer-id ...]`,
+and programmatically through `scaffoldProject(...)`, `BlockGeneratorService`,
+and `inspectBlockGeneration(...)`. The layer contract record 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,9 +41,13 @@ export interface BlockSpec {
 export interface BlockGenerationTarget {
     allowExistingDir: boolean;
     cwd: string;
+    externalLayerId?: string;
+    externalLayerSource?: string;
+    externalLayerSourceLabel?: string;
     noInstall: boolean;
     packageManager: PackageManagerId;
     projectDir: string;
+    repositoryReference?: string;
     variant?: string;
 }
 export interface PlanBlockInput {
@@ -51,10 +55,14 @@ export interface PlanBlockInput {
     answers: ScaffoldAnswers;
     cwd?: string;
     dataStorageMode?: DataStorageMode;
+    externalLayerId?: string;
+    externalLayerSource?: string;
+    externalLayerSourceLabel?: string;
     noInstall?: boolean;
     packageManager: PackageManagerId;
     persistencePolicy?: PersistencePolicy;
     projectDir: string;
+    repositoryReference?: string;
     templateId: BuiltInTemplateId;
     variant?: string;
     withMigrationUi?: boolean;
@@ -95,7 +103,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, externalLayerSourceLabel, noInstall, packageManager, persistencePolicy, projectDir, repositoryReference, 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,9 +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 { stableJsonStringify } from "./object-utils.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);
+    return stableJsonStringify(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") {
@@ -146,7 +199,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, externalLayerSourceLabel, noInstall = false, packageManager, persistencePolicy, projectDir, repositoryReference, templateId, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
         return {
             spec: createBuiltInBlockSpec({
                 answers,
@@ -160,29 +213,102 @@ export class BlockGeneratorService {
             target: {
                 allowExistingDir,
                 cwd,
+                externalLayerId,
+                externalLayerSource,
+                externalLayerSourceLabel,
                 noInstall,
                 packageManager,
                 projectDir,
+                repositoryReference,
                 variant,
             },
         };
     }
     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.externalLayerSourceLabel ?? validated.target.externalLayerSource}".`);
+            }
+            catch (error) {
+                await templateSource.cleanup?.();
+                await layerSeed?.cleanup?.();
+                throw error;
+            }
+        }
         const rendered = {
             ...validated,
             cleanup: templateSource.cleanup,
@@ -202,17 +328,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;
@@ -243,6 +363,7 @@ export class BlockGeneratorService {
                 noInstall: rendered.target.noInstall,
                 packageManager: rendered.target.packageManager,
                 projectDir: rendered.target.projectDir,
+                repositoryReference: rendered.target.repositoryReference,
                 gitignoreContent: rendered.gitignoreContent,
                 readmeContent: rendered.readmeContent,
                 templateDir: rendered.templateDir,

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?.();
+    }
+}