@wp-typia/project-tools 0.16.2 → 0.16.4

package/README.md

@@ -6,6 +6,9 @@ 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`,
+  plus the emitter-owned built-in structural/code path where built-in
+  templates no longer ship structural or TS/TSX Mustache files.
 - `@wp-typia/block-runtime/*` owns generated-project runtime helpers.
 - `@wp-typia/create` is the deprecated legacy package shell.
 
@@ -24,6 +27,7 @@ Example:
 
 ```ts
 import {
+	BlockGeneratorService,
 	getTemplateById,
 	parseMigrationArgs,
 	projectJsonSchemaDocument,
@@ -35,4 +39,11 @@ import {
 import { normalizeEndpointAuthDefinition } from "@wp-typia/project-tools/schema-core";
 ```
 
+`BlockGeneratorService` is the additive typed orchestration boundary for built-in
+block scaffolds. Built-in templates no longer ship structural or TS/TSX
+Mustache files for built-in `types.ts`, `block.json`, or generated scaffold
+bodies; those files and starter `typia.manifest.json` now come from the emitter
+path, while styles, PHP, and the remaining non-TS scaffold files still come
+from Mustache-backed template copy.
+
 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

@@ -0,0 +1,102 @@
+import type { PackageManagerId } from "./package-managers.js";
+import { type BuiltInTemplateId } from "./template-registry.js";
+import { type InstallDependenciesOptions } from "./scaffold-apply-utils.js";
+import type { DataStorageMode, PersistencePolicy, ScaffoldAnswers, ScaffoldProjectResult, ScaffoldTemplateVariables } from "./scaffold.js";
+export interface BlockSpec {
+    block: {
+        namespace: string;
+        phpPrefix: string;
+        slug: string;
+        textDomain: string;
+    };
+    metadata: {
+        category: string;
+        description: string;
+        icon: string;
+        keyword: string;
+        title: string;
+    };
+    persistence: {
+        enabled: false;
+    } | {
+        dataStorageMode: DataStorageMode;
+        enabled: true;
+        persistencePolicy: PersistencePolicy;
+        scope: "compound-parent" | "single";
+    };
+    project: {
+        author: string;
+    };
+    runtime: {
+        withMigrationUi: boolean;
+        withTestPreset: boolean;
+        withWpEnv: boolean;
+    };
+    template: {
+        description: string;
+        family: BuiltInTemplateId;
+        features: string[];
+    };
+}
+export interface BlockGenerationTarget {
+    allowExistingDir: boolean;
+    cwd: string;
+    noInstall: boolean;
+    packageManager: PackageManagerId;
+    projectDir: string;
+    variant?: string;
+}
+export interface PlanBlockInput {
+    allowExistingDir?: boolean;
+    answers: ScaffoldAnswers;
+    cwd?: string;
+    dataStorageMode?: DataStorageMode;
+    noInstall?: boolean;
+    packageManager: PackageManagerId;
+    persistencePolicy?: PersistencePolicy;
+    projectDir: string;
+    templateId: BuiltInTemplateId;
+    variant?: string;
+    withMigrationUi?: boolean;
+    withTestPreset?: boolean;
+    withWpEnv?: boolean;
+}
+export interface PlanBlockResult {
+    spec: BlockSpec;
+    target: BlockGenerationTarget;
+}
+export interface ValidateBlockInput {
+    plan: PlanBlockResult;
+}
+export interface ValidateBlockResult extends PlanBlockResult {
+}
+export interface RenderBlockInput {
+    validated: ValidateBlockResult;
+}
+export interface RenderBlockResult extends ValidateBlockResult {
+    cleanup?: () => Promise<void>;
+    gitignoreContent: string;
+    postRender: {
+        applyLocalDevPresets: boolean;
+        applyMigrationUiCapability: boolean;
+        seedPersistenceArtifacts: boolean;
+        seedStarterManifestFiles: boolean;
+    };
+    readmeContent: string;
+    selectedVariant: null;
+    templateDir: string;
+    variables: ScaffoldTemplateVariables;
+    warnings: string[];
+}
+export interface ApplyBlockInput {
+    rendered: RenderBlockResult;
+    installDependencies?: ((options: InstallDependenciesOptions) => Promise<void>) | undefined;
+}
+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>;
+    validate({ plan }: ValidateBlockInput): Promise<ValidateBlockResult>;
+    render({ validated }: RenderBlockInput): Promise<RenderBlockResult>;
+    apply({ rendered, installDependencies, }: ApplyBlockInput): Promise<ScaffoldProjectResult>;
+}

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

@@ -0,0 +1,268 @@
+import { getPackageVersions } from "./package-versions.js";
+import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, } from "./template-defaults.js";
+import { getTemplateById, } from "./template-registry.js";
+import { resolveBuiltInTemplateSource } from "./template-builtins.js";
+import { toPascalCase, toSnakeCase, } from "./string-case.js";
+import { applyBuiltInScaffoldProjectFiles, buildGitignore, buildReadme, } from "./scaffold-apply-utils.js";
+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";
+const renderedArtifactCache = new WeakMap();
+function createVariablesFingerprint(variables) {
+    return JSON.stringify(variables);
+}
+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,
+    };
+}
+export function createBuiltInBlockSpec({ 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;
+    return {
+        block: identifiers,
+        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(),
+        },
+        runtime: {
+            withMigrationUi,
+            withTestPreset,
+            withWpEnv,
+        },
+        template: {
+            description: template.description,
+            family: templateId,
+            features: [...template.features],
+        },
+    };
+}
+export function buildTemplateVariablesFromBlockSpec(spec) {
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = 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 compoundChildTitle = `${title} Item`;
+    const cssClassName = buildBlockCssClassName(namespace, slug);
+    const compoundChildCssClassName = buildBlockCssClassName(namespace, `${slug}-item`);
+    const persistenceEnabled = spec.persistence.enabled;
+    const dataStorageMode = persistenceEnabled ? spec.persistence.dataStorageMode : "custom-table";
+    const persistencePolicy = persistenceEnabled
+        ? spec.persistence.persistencePolicy
+        : "authenticated";
+    return {
+        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",
+        projectToolsPackageVersion,
+        cssClassName,
+        dashCase: slug,
+        dataStorageMode,
+        description: spec.metadata.description,
+        frontendCssClassName: buildFrontendCssClassName(cssClassName),
+        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,
+    };
+}
+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, }) {
+        return {
+            spec: createBuiltInBlockSpec({
+                answers,
+                dataStorageMode,
+                persistencePolicy,
+                templateId,
+                withMigrationUi,
+                withTestPreset,
+                withWpEnv,
+            }),
+            target: {
+                allowExistingDir,
+                cwd,
+                noInstall,
+                packageManager,
+                projectDir,
+                variant,
+            },
+        };
+    }
+    async validate({ plan }) {
+        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,
+            persistencePolicy: validated.spec.persistence.enabled &&
+                validated.spec.persistence.persistencePolicy === "public"
+                ? "public"
+                : "authenticated",
+        });
+        const variables = buildTemplateVariablesFromBlockSpec(validated.spec);
+        const persistenceEnabled = validated.spec.persistence.enabled;
+        const rendered = {
+            ...validated,
+            cleanup: templateSource.cleanup,
+            gitignoreContent: buildGitignore(),
+            postRender: {
+                applyLocalDevPresets: true,
+                applyMigrationUiCapability: validated.spec.runtime.withMigrationUi,
+                seedPersistenceArtifacts: validated.spec.template.family === "persistence" ||
+                    (validated.spec.template.family === "compound" && persistenceEnabled),
+                seedStarterManifestFiles: true,
+            },
+            readmeContent: buildReadme(validated.spec.template.family, variables, validated.target.packageManager, {
+                withMigrationUi: validated.spec.runtime.withMigrationUi,
+                withTestPreset: validated.spec.runtime.withTestPreset,
+                withWpEnv: validated.spec.runtime.withWpEnv,
+            }),
+            selectedVariant: null,
+            templateDir: templateSource.templateDir,
+            variables,
+            warnings: templateSource.warnings ?? [],
+        };
+        renderedArtifactCache.set(rendered, {
+            artifacts: buildBuiltInBlockArtifacts({
+                templateId: validated.spec.template.family,
+                variables,
+            }),
+            codeArtifacts: buildBuiltInCodeArtifacts({
+                templateId: validated.spec.template.family,
+                variables,
+            }),
+            variablesFingerprint: createVariablesFingerprint(variables),
+        });
+        return rendered;
+    }
+    async apply({ rendered, installDependencies, }) {
+        const cachedArtifacts = renderedArtifactCache.get(rendered);
+        const currentVariablesFingerprint = createVariablesFingerprint(rendered.variables);
+        const artifacts = cachedArtifacts &&
+            cachedArtifacts.variablesFingerprint === currentVariablesFingerprint
+            ? cachedArtifacts.artifacts
+            : buildBuiltInBlockArtifacts({
+                templateId: rendered.spec.template.family,
+                variables: rendered.variables,
+            });
+        const codeArtifacts = cachedArtifacts &&
+            cachedArtifacts.variablesFingerprint === currentVariablesFingerprint
+            ? cachedArtifacts.codeArtifacts
+            : buildBuiltInCodeArtifacts({
+                templateId: rendered.spec.template.family,
+                variables: rendered.variables,
+            });
+        try {
+            await applyBuiltInScaffoldProjectFiles({
+                allowExistingDir: rendered.target.allowExistingDir,
+                artifacts,
+                codeArtifacts,
+                installDependencies,
+                noInstall: rendered.target.noInstall,
+                packageManager: rendered.target.packageManager,
+                projectDir: rendered.target.projectDir,
+                gitignoreContent: rendered.gitignoreContent,
+                readmeContent: rendered.readmeContent,
+                templateDir: rendered.templateDir,
+                templateId: rendered.spec.template.family,
+                variables: rendered.variables,
+                withMigrationUi: rendered.spec.runtime.withMigrationUi,
+                withTestPreset: rendered.spec.runtime.withTestPreset,
+                withWpEnv: rendered.spec.runtime.withWpEnv,
+            });
+        }
+        finally {
+            await rendered.cleanup?.();
+        }
+        return {
+            packageManager: rendered.target.packageManager,
+            projectDir: rendered.target.projectDir,
+            selectedVariant: rendered.selectedVariant,
+            templateId: rendered.spec.template.family,
+            variables: rendered.variables,
+            warnings: rendered.warnings,
+        };
+    }
+}

package/dist/runtime/built-in-block-artifacts.d.ts

@@ -0,0 +1,37 @@
+import type { ManifestDocument } from "./migration-types.js";
+import type { ScaffoldTemplateVariables } from "./scaffold.js";
+import type { BuiltInTemplateId } from "./template-registry.js";
+export interface BuiltInBlockArtifact {
+    blockJsonDocument: Record<string, unknown>;
+    manifestDocument: ManifestDocument;
+    relativeDir: string;
+    typesSource: string;
+}
+/**
+ * Builds a starter manifest document for a generated compound child block.
+ *
+ * @param childTypeName TypeScript source type name for the child manifest.
+ * @param childTitle Default title used by the child block.
+ * @param bodyPlaceholder Optional placeholder used for the child body field.
+ * @returns Starter manifest metadata for the compound child block.
+ */
+export declare function buildCompoundChildStarterManifestDocument(childTypeName: string, childTitle: string, bodyPlaceholder?: string): ManifestDocument;
+/**
+ * Generates typed structural artifacts for a built-in block scaffold.
+ *
+ * @param options.templateId Built-in template family to emit.
+ * @param options.variables Resolved scaffold template variables.
+ * @returns Structural artifacts for the built-in block, including compound
+ * parent and child outputs when applicable.
+ */
+export declare function buildBuiltInBlockArtifacts({ templateId, variables, }: {
+    templateId: BuiltInTemplateId;
+    variables: ScaffoldTemplateVariables;
+}): BuiltInBlockArtifact[];
+/**
+ * Serializes a generated `block.json` document using scaffold formatting.
+ *
+ * @param document Structured `block.json` document.
+ * @returns Pretty-printed JSON with a trailing newline.
+ */
+export declare function stringifyBuiltInBlockJsonDocument(document: Record<string, unknown>): string;