@wp-typia/project-tools 0.11.1

package/dist/runtime/template-defaults.js

@@ -0,0 +1,65 @@
+/**
+ * Internal built-in template metadata defaults used by scaffold rendering.
+ */
+export const BUILTIN_BLOCK_METADATA_VERSION = "0.1.0";
+/**
+ * Built-in parent block metadata defaults keyed by template id.
+ */
+export const BUILTIN_TEMPLATE_METADATA_DEFAULTS = Object.freeze({
+    basic: Object.freeze({
+        category: "text",
+        icon: "smiley",
+    }),
+    interactivity: Object.freeze({
+        category: "widgets",
+        icon: "smiley",
+    }),
+    persistence: Object.freeze({
+        category: "widgets",
+        icon: "database",
+    }),
+    compound: Object.freeze({
+        category: "widgets",
+        icon: "screenoptions",
+    }),
+});
+/**
+ * Shared hidden child block metadata defaults for compound scaffolds.
+ */
+export const COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS = Object.freeze({
+    category: "widgets",
+    icon: "excerpt-view",
+});
+/**
+ * Legacy built-in template ids that were removed in favor of persistence modes.
+ */
+export const REMOVED_BUILTIN_TEMPLATE_IDS = ["data", "persisted"];
+/**
+ * Returns the metadata defaults for a built-in scaffold template id.
+ *
+ * @param templateId Built-in template id whose metadata defaults should be read.
+ * @returns The stable category/icon defaults used by scaffold rendering.
+ */
+export function getBuiltInTemplateMetadataDefaults(templateId) {
+    return BUILTIN_TEMPLATE_METADATA_DEFAULTS[templateId];
+}
+/**
+ * Checks whether a template id points at a removed built-in scaffold.
+ *
+ * @param templateId Template id supplied to scaffold resolution.
+ * @returns True when the template id is one of the removed legacy built-ins.
+ */
+export function isRemovedBuiltInTemplateId(templateId) {
+    return REMOVED_BUILTIN_TEMPLATE_IDS.includes(templateId);
+}
+/**
+ * Builds the stable recovery guidance shown for removed built-in template ids.
+ *
+ * @param templateId Removed template id, where `data` maps to the public policy and
+ * `persisted` maps to the authenticated policy.
+ * @returns A user-facing error string in the form
+ * `Built-in template "<id>" was removed. Use --template persistence --persistence-policy <policy> instead.`
+ */
+export function getRemovedBuiltInTemplateMessage(templateId) {
+    return `Built-in template "${templateId}" was removed. Use --template persistence --persistence-policy ${templateId === "data" ? "public" : "authenticated"} instead.`;
+}

package/dist/runtime/template-registry.d.ts

@@ -0,0 +1,36 @@
+export declare function resolvePackageRoot(startDir: string): string;
+export declare const PROJECT_TOOLS_PACKAGE_ROOT: string;
+export declare const TEMPLATE_ROOT: string;
+export declare const SHARED_TEMPLATE_ROOT: string;
+export declare const SHARED_BASE_TEMPLATE_ROOT: string;
+export declare const SHARED_COMPOUND_TEMPLATE_ROOT: string;
+export declare const SHARED_PERSISTENCE_TEMPLATE_ROOT: string;
+export declare const SHARED_PRESET_TEMPLATE_ROOT: string;
+export declare const SHARED_REST_HELPER_TEMPLATE_ROOT: string;
+export declare const SHARED_MIGRATION_UI_TEMPLATE_ROOT: string;
+/**
+ * Shared workspace template overlay root used by workspace scaffolding flows.
+ */
+export declare const SHARED_WORKSPACE_TEMPLATE_ROOT: string;
+export declare const SHARED_TEST_PRESET_TEMPLATE_ROOT: string;
+export declare const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT: string;
+export declare const BUILTIN_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound"];
+export type BuiltInTemplateId = (typeof BUILTIN_TEMPLATE_IDS)[number];
+export type PersistencePolicy = "authenticated" | "public";
+export interface TemplateDefinition {
+    id: BuiltInTemplateId;
+    description: string;
+    defaultCategory: string;
+    features: string[];
+    templateDir: string;
+}
+export declare const TEMPLATE_REGISTRY: readonly TemplateDefinition[];
+export declare const TEMPLATE_IDS: BuiltInTemplateId[];
+export declare function isBuiltInTemplateId(templateId: string): templateId is BuiltInTemplateId;
+export declare function listTemplates(): readonly TemplateDefinition[];
+export declare function getTemplateById(templateId: string): TemplateDefinition;
+export declare function getTemplateSelectOptions(): Array<{
+    label: string;
+    value: TemplateDefinition["id"];
+    hint: string;
+}>;

package/dist/runtime/template-registry.js

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getBuiltInTemplateMetadataDefaults } from "./template-defaults.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export function resolvePackageRoot(startDir) {
+    let currentDir = startDir;
+    while (true) {
+        const packageJsonPath = path.join(currentDir, "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+            try {
+                const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+                if (packageJson.name === "@wp-typia/project-tools") {
+                    return currentDir;
+                }
+            }
+            catch {
+                // Ignore malformed package.json while walking upward.
+            }
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            throw new Error("Unable to resolve the @wp-typia/project-tools package root.");
+        }
+        currentDir = parentDir;
+    }
+}
+export const PROJECT_TOOLS_PACKAGE_ROOT = resolvePackageRoot(__dirname);
+export const TEMPLATE_ROOT = path.join(PROJECT_TOOLS_PACKAGE_ROOT, "templates");
+export const SHARED_TEMPLATE_ROOT = path.join(TEMPLATE_ROOT, "_shared");
+export const SHARED_BASE_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "base");
+export const SHARED_COMPOUND_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "compound");
+export const SHARED_PERSISTENCE_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "persistence");
+export const SHARED_PRESET_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "presets");
+export const SHARED_REST_HELPER_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "rest-helpers");
+export const SHARED_MIGRATION_UI_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "migration-ui");
+/**
+ * Shared workspace template overlay root used by workspace scaffolding flows.
+ */
+export const SHARED_WORKSPACE_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "workspace");
+export const SHARED_TEST_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "test-preset");
+export const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "wp-env");
+export const BUILTIN_TEMPLATE_IDS = ["basic", "interactivity", "persistence", "compound"];
+export const TEMPLATE_REGISTRY = Object.freeze([
+    {
+        id: "basic",
+        description: "A lightweight WordPress block with Typia validation",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("basic").category,
+        features: ["Type-safe attributes", "Runtime validation", "Minimal setup"],
+        templateDir: path.join(TEMPLATE_ROOT, "basic"),
+    },
+    {
+        id: "interactivity",
+        description: "An interactive WordPress block with Typia validation and Interactivity API",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("interactivity").category,
+        features: ["Interactivity API", "Client-side state", "Event handling"],
+        templateDir: path.join(TEMPLATE_ROOT, "interactivity"),
+    },
+    {
+        id: "persistence",
+        description: "A persistence-aware WordPress block with Typia validation, typed REST contracts, and selectable public or authenticated write policies",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("persistence").category,
+        features: ["Interactivity API", "Typed REST client", "Schema sync", "Persistence policies"],
+        templateDir: path.join(TEMPLATE_ROOT, "persistence"),
+    },
+    {
+        id: "compound",
+        description: "A parent-and-child WordPress block scaffold with InnerBlocks, optional persistence wiring, and hidden implementation child blocks",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("compound").category,
+        features: ["InnerBlocks", "Hidden child blocks", "Optional persistence layer"],
+        templateDir: path.join(TEMPLATE_ROOT, "compound"),
+    },
+]);
+export const TEMPLATE_IDS = TEMPLATE_REGISTRY.map((template) => template.id);
+export function isBuiltInTemplateId(templateId) {
+    return BUILTIN_TEMPLATE_IDS.includes(templateId);
+}
+export function listTemplates() {
+    return TEMPLATE_REGISTRY;
+}
+export function getTemplateById(templateId) {
+    const template = TEMPLATE_REGISTRY.find((entry) => entry.id === templateId);
+    if (!template) {
+        throw new Error(`Unknown template "${templateId}". Expected one of: ${TEMPLATE_IDS.join(", ")}`);
+    }
+    return template;
+}
+export function getTemplateSelectOptions() {
+    return TEMPLATE_REGISTRY.map((template) => ({
+        label: template.id,
+        value: template.id,
+        hint: template.features.join(", "),
+    }));
+}

package/dist/runtime/template-render.d.ts

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+export type TemplateRenderView = Record<string, unknown>;
+/**
+ * Optional controls for raw directory copies.
+ *
+ * The filter runs for each discovered entry before copying. Returning `false`
+ * skips only that entry; when the skipped entry is a directory, the subtree is
+ * skipped as well.
+ */
+export interface CopyRawDirectoryOptions {
+    /**
+     * Predicate that decides whether a discovered entry should be copied.
+     *
+     * Throwing or rejecting aborts the copy and bubbles to the caller.
+     */
+    filter?: (sourcePath: string, targetPath: string, entry: fs.Dirent) => boolean | Promise<boolean>;
+}
+/**
+ * Recursively copies a directory tree without rendering template contents.
+ */
+export declare function copyRawDirectory(sourceDir: string, targetDir: string, options?: CopyRawDirectoryOptions): Promise<void>;
+export declare function copyRenderedDirectory(sourceDir: string, targetDir: string, view: TemplateRenderView): Promise<void>;
+export declare function copyInterpolatedDirectory(sourceDir: string, targetDir: string, view: Record<string, string>): Promise<void>;
+export declare function pathExists(targetPath: string): boolean;

package/dist/runtime/template-render.js

@@ -0,0 +1,113 @@
+/// <reference path="./external-template-modules.d.ts" />
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import Mustache from "mustache";
+const BINARY_EXTENSIONS = new Set([
+    ".avif",
+    ".bmp",
+    ".gif",
+    ".ico",
+    ".jpeg",
+    ".jpg",
+    ".otf",
+    ".pdf",
+    ".png",
+    ".svg",
+    ".ttf",
+    ".webp",
+    ".woff",
+    ".woff2",
+]);
+Mustache.escape = (value) => value;
+function renderMustacheTemplateString(template, view) {
+    return Mustache.render(template, view);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function renderInterpolatedString(template, view) {
+    return Object.entries(view).reduce((output, [key, value]) => output.replace(new RegExp(`{{${escapeRegExp(key)}}}`, "g"), value), template);
+}
+function isBinaryTemplateFile(filePath) {
+    return BINARY_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+function resolveRenderedPath(targetDir, destinationName) {
+    const resolvedTargetDir = path.resolve(targetDir);
+    const resolvedDestinationPath = path.resolve(resolvedTargetDir, destinationName);
+    const relativePath = path.relative(resolvedTargetDir, resolvedDestinationPath);
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        throw new Error(`Rendered template path escapes target directory: ${destinationName}`);
+    }
+    return resolvedDestinationPath;
+}
+/**
+ * Recursively copies a directory tree without rendering template contents.
+ */
+export async function copyRawDirectory(sourceDir, targetDir, options = {}) {
+    await fsp.mkdir(targetDir, { recursive: true });
+    for (const entry of await fsp.readdir(sourceDir, { withFileTypes: true })) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const targetPath = path.join(targetDir, entry.name);
+        if (options.filter && !(await options.filter(sourcePath, targetPath, entry))) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await copyRawDirectory(sourcePath, targetPath, options);
+            continue;
+        }
+        await fsp.mkdir(path.dirname(targetPath), { recursive: true });
+        await fsp.copyFile(sourcePath, targetPath);
+    }
+}
+export async function copyRenderedDirectory(sourceDir, targetDir, view) {
+    const entries = await fsp.readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationNameTemplate = entry.name.endsWith(".mustache")
+            ? entry.name.slice(0, -".mustache".length)
+            : entry.name;
+        const destinationName = renderMustacheTemplateString(destinationNameTemplate, view);
+        const destinationPath = resolveRenderedPath(targetDir, destinationName);
+        if (entry.isDirectory()) {
+            await fsp.mkdir(destinationPath, { recursive: true });
+            await copyRenderedDirectory(sourcePath, destinationPath, view);
+            continue;
+        }
+        if (isBinaryTemplateFile(sourcePath)) {
+            await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
+            await fsp.copyFile(sourcePath, destinationPath);
+            continue;
+        }
+        const content = await fsp.readFile(sourcePath, "utf8");
+        await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
+        await fsp.writeFile(destinationPath, renderMustacheTemplateString(content, view), "utf8");
+    }
+}
+export async function copyInterpolatedDirectory(sourceDir, targetDir, view) {
+    const entries = await fsp.readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationNameTemplate = entry.name.endsWith(".mustache")
+            ? entry.name.slice(0, -".mustache".length)
+            : entry.name;
+        const destinationName = renderInterpolatedString(destinationNameTemplate, view);
+        const destinationPath = resolveRenderedPath(targetDir, destinationName);
+        if (entry.isDirectory()) {
+            await fsp.mkdir(destinationPath, { recursive: true });
+            await copyInterpolatedDirectory(sourcePath, destinationPath, view);
+            continue;
+        }
+        if (isBinaryTemplateFile(sourcePath)) {
+            await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
+            await fsp.copyFile(sourcePath, destinationPath);
+            continue;
+        }
+        const content = await fsp.readFile(sourcePath, "utf8");
+        await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
+        await fsp.writeFile(destinationPath, renderInterpolatedString(content, view), "utf8");
+    }
+}
+export function pathExists(targetPath) {
+    return fs.existsSync(targetPath);
+}

package/dist/runtime/template-source.d.ts

@@ -0,0 +1,71 @@
+type TemplateSourceFormat = "wp-typia" | "create-block-external" | "create-block-subset";
+/**
+ * Public template variables exposed to external template seeds before wp-typia
+ * normalizes them into a scaffold project.
+ */
+export interface TemplateVariableContext extends Record<string, unknown> {
+    /** Version string for `@wp-typia/api-client` used in generated dependencies. */
+    apiClientPackageVersion: string;
+    /** Version string for `@wp-typia/block-runtime` used in generated dependencies. */
+    blockRuntimePackageVersion: string;
+    /** Version string for `@wp-typia/block-types` used in generated dependencies. */
+    blockTypesPackageVersion: string;
+    /** PascalCase block type name derived from the scaffold slug. */
+    pascalCase: string;
+    /** Snake_case PHP symbol prefix used for generated functions, constants, and keys. */
+    phpPrefix: string;
+    /** Human-readable block title. */
+    title: string;
+    /** Human-readable project or block description. */
+    description: string;
+    /** Keyword string derived from the slug for generated block metadata. */
+    keyword: string;
+    /** Block namespace used in generated block names such as `namespace/slug`. */
+    namespace: string;
+    /** Kebab-case scaffold slug used for package names, paths, and block slugs. */
+    slug: string;
+    /** Kebab-case text domain used for generated i18n strings and plugin headers. */
+    textDomain: string;
+}
+export interface ResolvedTemplateSource {
+    id: string;
+    defaultCategory: string;
+    description: string;
+    features: string[];
+    format: TemplateSourceFormat;
+    isOfficialWorkspaceTemplate?: boolean;
+    templateDir: string;
+    cleanup?: () => Promise<void>;
+    selectedVariant?: string | null;
+    warnings?: string[];
+}
+interface GitHubTemplateLocator {
+    owner: string;
+    repo: string;
+    ref: string | null;
+    sourcePath: string;
+}
+interface NpmTemplateLocator {
+    fetchSpec: string;
+    name: string;
+    raw: string;
+    rawSpec: string;
+    type: string;
+}
+type RemoteTemplateLocator = {
+    kind: "github";
+    locator: GitHubTemplateLocator;
+} | {
+    kind: "npm";
+    locator: NpmTemplateLocator;
+} | {
+    kind: "path";
+    templatePath: string;
+};
+export declare function parseGitHubTemplateLocator(templateId: string): GitHubTemplateLocator | null;
+export declare function parseNpmTemplateLocator(templateId: string): NpmTemplateLocator | null;
+export declare function parseTemplateLocator(templateId: string): RemoteTemplateLocator;
+export declare function resolveTemplateSource(templateId: string, cwd: string, variables: {
+    [key: string]: string;
+}, variant?: string): Promise<ResolvedTemplateSource>;
+export {};