@wp-typia/project-tools 0.16.10 → 0.16.12

package/dist/runtime/scaffold.js

@@ -2,112 +2,24 @@ import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
-import { PACKAGE_MANAGER_IDS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
-import { replaceTextRecursively } from "./scaffold-apply-utils.js";
-import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, getPrimaryDevelopmentScript, } from "./local-dev-presets.js";
+import { PACKAGE_MANAGER_IDS, getPackageManager, } from "./package-managers.js";
+import { buildGitignore, buildReadme, mergeTextLines, replaceTextRecursively, } from "./scaffold-apply-utils.js";
+import { buildBlockCssClassName, buildFrontendCssClassName, normalizeBlockSlug, resolveScaffoldIdentifiers, validateBlockSlug, validateNamespace, } from "./scaffold-identifiers.js";
+import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, } from "./local-dev-presets.js";
 import { applyMigrationUiCapability } from "./migration-ui-capability.js";
 import { getPackageVersions } from "./package-versions.js";
-import { ensureMigrationDirectories, writeInitialMigrationScaffold, writeMigrationConfig, } from "./migration-project.js";
-import { syncPersistenceRestArtifacts } from "./persistence-rest-artifacts.js";
-import { getCompoundExtensionWorkflowSection, getOptionalOnboardingNote, getOptionalOnboardingSteps, getPhpRestExtensionPointsSection, getTemplateSourceOfTruthNote, } from "./scaffold-onboarding.js";
-import { getStarterManifestFiles, stringifyStarterManifest } from "./starter-manifests.js";
-import { toKebabCase, toPascalCase, toSnakeCase, toTitleCase, } from "./string-case.js";
+import { applyWorkspaceMigrationCapability, ensureScaffoldDirectory, isOfficialWorkspaceProject, seedBuiltInPersistenceArtifacts, writeStarterManifestFiles, } from "./scaffold-bootstrap.js";
+import { defaultInstallDependencies, normalizePackageJson, normalizePackageManagerFiles, removeUnexpectedLockfiles, } from "./scaffold-package-manager-files.js";
+import { toPascalCase, toSnakeCase, toTitleCase, } from "./string-case.js";
 import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from "./template-defaults.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId, } from "./template-registry.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId, } from "./template-registry.js";
 import { resolveTemplateSource } from "./template-source.js";
 import { BlockGeneratorService, buildTemplateVariablesFromBlockSpec, createBuiltInBlockSpec, } from "./block-generator-service.js";
-const BLOCK_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
-const PHP_PREFIX_PATTERN = /^[a-z_][a-z0-9_]*$/;
-const PHP_PREFIX_MAX_LENGTH = 50;
 const WORKSPACE_TEMPLATE_ALIAS = "workspace";
-const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
-const LOCKFILES = {
-    bun: ["bun.lock", "bun.lockb"],
-    npm: ["package-lock.json"],
-    pnpm: ["pnpm-lock.yaml"],
-    yarn: ["yarn.lock"],
-};
 export const DATA_STORAGE_MODES = ["post-meta", "custom-table"];
 export const PERSISTENCE_POLICIES = ["authenticated", "public"];
-function validateBlockSlug(input) {
-    return BLOCK_SLUG_PATTERN.test(input) || "Use lowercase letters, numbers, and hyphens only";
-}
-function validateNamespace(input) {
-    return BLOCK_SLUG_PATTERN.test(toKebabCase(input))
-        ? true
-        : "Use lowercase letters, numbers, and hyphens only";
-}
-function validateTextDomain(input) {
-    return BLOCK_SLUG_PATTERN.test(toKebabCase(input))
-        ? true
-        : "Use lowercase letters, numbers, and hyphens only";
-}
-function validatePhpPrefix(input) {
-    const normalizedPrefix = toSnakeCase(input);
-    if (normalizedPrefix.length > PHP_PREFIX_MAX_LENGTH) {
-        return `Use ${PHP_PREFIX_MAX_LENGTH} characters or fewer to keep generated database identifiers within MySQL limits`;
-    }
-    return PHP_PREFIX_PATTERN.test(normalizedPrefix)
-        ? true
-        : "Use letters, numbers, and underscores only, starting with a letter";
-}
-function assertValidIdentifier(label, value, validate) {
-    const result = validate(value);
-    if (result !== true) {
-        throw new Error(typeof result === "string" ? `${label}: ${result}` : `${label} is invalid`);
-    }
-    return value;
-}
-function normalizeBlockSlug(input) {
-    return toKebabCase(input);
-}
-function resolveValidatedBlockSlug(value) {
-    return assertValidIdentifier("Block slug", normalizeBlockSlug(value), validateBlockSlug);
-}
-function resolveValidatedNamespace(value) {
-    return assertValidIdentifier("Namespace", toKebabCase(value), validateNamespace);
-}
-function resolveValidatedTextDomain(value) {
-    return assertValidIdentifier("Text domain", toKebabCase(value), validateTextDomain);
-}
-function resolveValidatedPhpPrefix(value) {
-    return assertValidIdentifier("PHP prefix", toSnakeCase(value), validatePhpPrefix);
-}
-/**
- * Builds the generated WordPress wrapper CSS class for a scaffolded block.
- *
- * Returns `wp-block-{namespace}-{slug}` when a non-empty namespace is present,
- * or `wp-block-{slug}` when the namespace is empty or undefined. When the
- * normalized namespace equals the normalized slug, appends `-block` so the
- * generated class avoids repeated namespace segments without colliding with the
- * default core wrapper classes. Both inputs are normalized and validated with
- * the same scaffold identifier rules used for block names.
- */
-export function buildBlockCssClassName(namespace, slug) {
-    const normalizedSlug = resolveValidatedBlockSlug(slug);
-    const normalizedNamespace = typeof namespace === "string" && namespace.trim().length > 0
-        ? resolveValidatedNamespace(namespace)
-        : "";
-    if (normalizedNamespace === normalizedSlug) {
-        return `wp-block-${normalizedSlug}-block`;
-    }
-    return normalizedNamespace.length > 0
-        ? `wp-block-${normalizedNamespace}-${normalizedSlug}`
-        : `wp-block-${normalizedSlug}`;
-}
-function buildFrontendCssClassName(blockCssClassName) {
-    return `${blockCssClassName}-frontend`;
-}
-function resolveScaffoldIdentifiers({ namespace, phpPrefix, slug, textDomain, }) {
-    const normalizedSlug = resolveValidatedBlockSlug(slug);
-    return {
-        namespace: resolveValidatedNamespace(namespace),
-        phpPrefix: resolveValidatedPhpPrefix(phpPrefix ?? normalizedSlug),
-        slug: normalizedSlug,
-        textDomain: resolveValidatedTextDomain(textDomain ?? normalizedSlug),
-    };
-}
+export { buildBlockCssClassName } from "./scaffold-identifiers.js";
 export function isDataStorageMode(value) {
     return DATA_STORAGE_MODES.includes(value);
 }
@@ -313,301 +225,6 @@ export function getTemplateVariables(templateId, answers) {
         persistencePolicy,
     };
 }
-async function ensureDirectory(targetDir, allowExisting = false) {
-    if (!fs.existsSync(targetDir)) {
-        await fsp.mkdir(targetDir, { recursive: true });
-        return;
-    }
-    if (allowExisting) {
-        return;
-    }
-    const entries = await fsp.readdir(targetDir);
-    if (entries.length > 0) {
-        throw new Error(`Target directory is not empty: ${targetDir}`);
-    }
-}
-function buildReadme(templateId, variables, packageManager, { withMigrationUi = false, withTestPreset = false, withWpEnv = false, } = {}) {
-    const optionalOnboardingSteps = getOptionalOnboardingSteps(packageManager, templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
-    });
-    const sourceOfTruthNote = getTemplateSourceOfTruthNote(templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
-    });
-    const compoundPersistenceEnabled = variables.compoundPersistenceEnabled === "true";
-    const publicPersistencePolicyNote = variables.isPublicPersistencePolicy === "true"
-        ? "Public persistence writes use signed short-lived tokens, per-request ids, and coarse rate limiting by default. Add application-specific abuse controls before using the same pattern for high-value metrics or experiments."
-        : null;
-    const compoundExtensionWorkflowSection = getCompoundExtensionWorkflowSection(packageManager, templateId);
-    const phpRestExtensionPointsSection = getPhpRestExtensionPointsSection(templateId, {
-        compoundPersistenceEnabled,
-        slug: variables.slug,
-    });
-    const developmentScript = getPrimaryDevelopmentScript(templateId);
-    const wpEnvSection = withWpEnv
-        ? `## Local WordPress\n\n\`\`\`bash\n${formatRunScript(packageManager, "wp-env:start")}\n${formatRunScript(packageManager, "wp-env:stop")}\n${formatRunScript(packageManager, "wp-env:reset")}\n\`\`\``
-        : "";
-    const testPresetSection = withTestPreset
-        ? `## Local Test Preset\n\n\`\`\`bash\n${formatRunScript(packageManager, "wp-env:start:test")}\n${formatRunScript(packageManager, "wp-env:wait:test")}\n${formatRunScript(packageManager, "test:e2e")}\n\`\`\`\n\nThe generated smoke test uses \`.wp-env.test.json\` and verifies that the scaffolded block registers in the WordPress editor.`
-        : "";
-    const migrationSection = withMigrationUi
-        ? `## Migration UI\n\nThis scaffold already includes an initialized migration workspace at \`v1\`, generated deprecated/runtime artifacts, and an editor-embedded migration dashboard. Migration versions are schema lineage labels and are separate from your package or plugin release version. Use the existing CLI commands to snapshot, diff, scaffold, verify, and fuzz future schema changes.\n\n\`\`\`bash\n${formatRunScript(packageManager, "migration:doctor")}\n${formatRunScript(packageManager, "migration:verify")}\n${formatRunScript(packageManager, "migration:fuzz")}\n\`\`\`\n\nRun \`migration:init\` only when retrofitting migration support into an older project that was not scaffolded with \`--with-migration-ui\`.`
-        : "";
-    return `# ${variables.title}
-
-${variables.description}
-
-## Template
-
-${templateId}
-
-## Development
-
-\`\`\`bash
-${formatInstallCommand(packageManager)}
-${formatRunScript(packageManager, developmentScript)}
-\`\`\`
-
-## Build
-
-\`\`\`bash
-${formatRunScript(packageManager, "build")}
-\`\`\`
-
-## Optional First Sync
-
-\`\`\`bash
-${optionalOnboardingSteps.join("\n")}
-\`\`\`
-
-${getOptionalOnboardingNote(packageManager, templateId, {
-        compoundPersistenceEnabled,
-    })}
-
-${sourceOfTruthNote}${publicPersistencePolicyNote ? `\n\n${publicPersistencePolicyNote}` : ""}${migrationSection ? `\n\n${migrationSection}` : ""}${compoundExtensionWorkflowSection ? `\n\n${compoundExtensionWorkflowSection}` : ""}${wpEnvSection ? `\n\n${wpEnvSection}` : ""}${testPresetSection ? `\n\n${testPresetSection}` : ""}${phpRestExtensionPointsSection ? `\n\n${phpRestExtensionPointsSection}` : ""}
-`;
-}
-function buildGitignore() {
-    return `# Dependencies
-node_modules/
-.yarn/
-.pnp.*
-
-# Build
-build/
-dist/
-
-# Editor
-.vscode/
-.idea/
-
-# OS
-.DS_Store
-Thumbs.db
-
-# WordPress
-*.log
-.wp-env/
-`;
-}
-function mergeTextLines(primaryContent, existingContent) {
-    const normalizedPrimary = primaryContent.replace(/\r\n/g, "\n").trimEnd();
-    const normalizedExisting = existingContent.replace(/\r\n/g, "\n").trimEnd();
-    const mergedLines = [];
-    const seen = new Set();
-    for (const line of [...normalizedPrimary.split("\n"), ...normalizedExisting.split("\n")]) {
-        if (line.length === 0 && mergedLines[mergedLines.length - 1] === "") {
-            continue;
-        }
-        if (line.length > 0 && seen.has(line)) {
-            continue;
-        }
-        if (line.length > 0) {
-            seen.add(line);
-        }
-        mergedLines.push(line);
-    }
-    return `${mergedLines.join("\n").replace(/\n{3,}/g, "\n\n")}\n`;
-}
-async function writeStarterManifestFiles(targetDir, templateId, variables) {
-    const manifests = getStarterManifestFiles(templateId, variables);
-    for (const { document, relativePath } of manifests) {
-        const destinationPath = path.join(targetDir, relativePath);
-        await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
-        await fsp.writeFile(destinationPath, stringifyStarterManifest(document), "utf8");
-    }
-}
-/**
- * Seed REST-derived persistence artifacts into a newly scaffolded built-in
- * project before the first manual `sync-rest` run.
- *
- * @param targetDir Absolute scaffold target directory.
- * @param templateId Built-in template id being scaffolded.
- * @param variables Resolved scaffold template variables for the project.
- * @returns A promise that resolves after any required persistence artifacts are generated.
- */
-async function seedBuiltInPersistenceArtifacts(targetDir, templateId, variables) {
-    const needsPersistenceArtifacts = templateId === "persistence" ||
-        (templateId === "compound" && variables.compoundPersistenceEnabled === "true");
-    if (!needsPersistenceArtifacts) {
-        return;
-    }
-    await withEphemeralScaffoldNodeModules(targetDir, async () => {
-        if (templateId === "persistence") {
-            await syncPersistenceRestArtifacts({
-                apiTypesFile: path.join("src", "api-types.ts"),
-                outputDir: "src",
-                projectDir: targetDir,
-                variables,
-            });
-            return;
-        }
-        await syncPersistenceRestArtifacts({
-            apiTypesFile: path.join("src", "blocks", variables.slugKebabCase, "api-types.ts"),
-            outputDir: path.join("src", "blocks", variables.slugKebabCase),
-            projectDir: targetDir,
-            variables,
-        });
-    });
-}
-/**
- * Locate a node_modules directory containing `typia` relative to the project
- * tools package root.
- *
- * Search order:
- * 1. `PROJECT_TOOLS_PACKAGE_ROOT/node_modules`
- * 2. The monorepo root resolved from `PROJECT_TOOLS_PACKAGE_ROOT`
- * 3. The monorepo root `node_modules`
- *
- * @returns The first matching path, or `null` when no candidate contains `typia`.
- */
-function resolveScaffoldGeneratorNodeModulesPath() {
-    const candidates = [
-        path.join(PROJECT_TOOLS_PACKAGE_ROOT, "node_modules"),
-        path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", ".."),
-        path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", "..", "node_modules"),
-    ];
-    for (const candidate of candidates) {
-        if (fs.existsSync(path.join(candidate, "typia", "package.json"))) {
-            return candidate;
-        }
-    }
-    return null;
-}
-/**
- * Temporarily symlink a scaffold generator node_modules directory into the
- * target project while running an async callback.
- *
- * The helper resolves the source path via `resolveScaffoldGeneratorNodeModulesPath()`
- * and uses `EPHEMERAL_NODE_MODULES_LINK_TYPE` for the symlink. The temporary
- * link is removed in the `finally` block so cleanup still happens if the
- * callback throws.
- *
- * @param targetDir Absolute scaffold target directory.
- * @param callback Async work that requires a resolvable `node_modules`.
- * @returns A promise that resolves after the callback and cleanup complete.
- */
-async function withEphemeralScaffoldNodeModules(targetDir, callback) {
-    const targetNodeModulesPath = path.join(targetDir, "node_modules");
-    if (fs.existsSync(targetNodeModulesPath)) {
-        await callback();
-        return;
-    }
-    const sourceNodeModulesPath = resolveScaffoldGeneratorNodeModulesPath();
-    if (!sourceNodeModulesPath) {
-        throw new Error("Unable to resolve a node_modules directory with typia for scaffold-time REST artifact generation.");
-    }
-    await fsp.symlink(sourceNodeModulesPath, targetNodeModulesPath, EPHEMERAL_NODE_MODULES_LINK_TYPE);
-    try {
-        await callback();
-    }
-    finally {
-        await fsp.rm(targetNodeModulesPath, { force: true, recursive: true });
-    }
-}
-async function normalizePackageManagerFiles(targetDir, packageManagerId) {
-    const yarnRcPath = path.join(targetDir, ".yarnrc.yml");
-    if (packageManagerId === "yarn") {
-        await fsp.writeFile(yarnRcPath, "nodeLinker: node-modules\n", "utf8");
-        return;
-    }
-    if (fs.existsSync(yarnRcPath)) {
-        await fsp.rm(yarnRcPath, { force: true });
-    }
-}
-async function normalizePackageJson(targetDir, packageManagerId) {
-    const packageJsonPath = path.join(targetDir, "package.json");
-    if (!fs.existsSync(packageJsonPath)) {
-        return;
-    }
-    const packageManager = getPackageManager(packageManagerId);
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
-    packageJson.packageManager = packageManager.packageManagerField;
-    if (packageJson.scripts) {
-        for (const [key, value] of Object.entries(packageJson.scripts)) {
-            if (typeof value === "string") {
-                packageJson.scripts[key] = transformPackageManagerText(value, packageManagerId);
-            }
-        }
-    }
-    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
-}
-async function removeUnexpectedLockfiles(targetDir, packageManagerId) {
-    const keep = new Set(LOCKFILES[packageManagerId] ?? []);
-    const allLockfiles = Object.values(LOCKFILES).flat();
-    await Promise.all(allLockfiles.map(async (filename) => {
-        if (keep.has(filename)) {
-            return;
-        }
-        const filePath = path.join(targetDir, filename);
-        if (fs.existsSync(filePath)) {
-            await fsp.rm(filePath, { force: true });
-        }
-    }));
-}
-async function defaultInstallDependencies({ projectDir, packageManager, }) {
-    execSync(formatInstallCommand(packageManager), {
-        cwd: projectDir,
-        stdio: "inherit",
-    });
-}
-function isOfficialWorkspaceProject(projectDir) {
-    const packageJsonPath = path.join(projectDir, "package.json");
-    if (!fs.existsSync(packageJsonPath)) {
-        return false;
-    }
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-    return (packageJson.wpTypia?.projectType === "workspace" &&
-        packageJson.wpTypia?.templatePackage === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE);
-}
-async function applyWorkspaceMigrationCapability(projectDir, packageManager) {
-    const packageJsonPath = path.join(projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
-    const wpTypiaPackageVersion = getPackageVersions().wpTypiaPackageVersion;
-    const canonicalCliSpecifier = wpTypiaPackageVersion === "^0.0.0"
-        ? "wp-typia"
-        : `wp-typia@${wpTypiaPackageVersion.replace(/^[~^]/u, "")}`;
-    const migrationCli = (args) => formatPackageExecCommand(packageManager, canonicalCliSpecifier, `migrate ${args}`);
-    packageJson.scripts = {
-        ...(packageJson.scripts ?? {}),
-        "migration:init": migrationCli("init --current-migration-version v1"),
-        "migration:snapshot": migrationCli("snapshot"),
-        "migration:diff": migrationCli("diff"),
-        "migration:scaffold": migrationCli("scaffold"),
-        "migration:doctor": migrationCli("doctor --all"),
-        "migration:fixtures": migrationCli("fixtures --all"),
-        "migration:verify": migrationCli("verify --all"),
-        "migration:fuzz": migrationCli("fuzz --all"),
-    };
-    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
-    writeMigrationConfig(projectDir, {
-        blocks: [],
-        currentMigrationVersion: "v1",
-        snapshotDir: "src/migrations/versions",
-        supportedMigrationVersions: ["v1"],
-    });
-    ensureMigrationDirectories(projectDir, []);
-    writeInitialMigrationScaffold(projectDir, "v1", []);
-}
 export async function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
     const resolvedTemplateId = normalizeTemplateSelection(templateId);
     const resolvedPackageManager = getPackageManager(packageManager).id;
@@ -658,7 +275,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
         throw new Error("`--with-migration-ui` is currently supported only for built-in templates and @wp-typia/create-workspace-template.");
     }
     try {
-        await ensureDirectory(projectDir, allowExistingDir);
+        await ensureScaffoldDirectory(projectDir, allowExistingDir);
         await copyInterpolatedDirectory(templateSource.templateDir, projectDir, variables);
     }
     finally {

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

@@ -0,0 +1,81 @@
+import type { UnknownRecord } from './object-utils.js';
+export 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 UnknownRecord {
+    /** 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[];
+}
+export interface GitHubTemplateLocator {
+    owner: string;
+    repo: string;
+    ref: string | null;
+    sourcePath: string;
+}
+export interface NpmTemplateLocator {
+    fetchSpec: string;
+    name: string;
+    raw: string;
+    rawSpec: string;
+    type: string;
+}
+export interface ExternalTemplateConfig<TView extends UnknownRecord = TemplateVariableContext> {
+    assetsPath?: string;
+    blockTemplatesPath?: string;
+    defaultValues?: Partial<TView>;
+    folderName?: string;
+    transformer?: (view: TView) => UnknownRecord | Promise<UnknownRecord>;
+    variants?: Record<string, Partial<TView>>;
+}
+export interface SeedSource {
+    assetsDir?: string;
+    blockDir: string;
+    cleanup?: () => Promise<void>;
+    rootDir: string;
+    selectedVariant?: string | null;
+    warnings?: string[];
+}
+export type RemoteTemplateLocator = {
+    kind: 'github';
+    locator: GitHubTemplateLocator;
+} | {
+    kind: 'npm';
+    locator: NpmTemplateLocator;
+} | {
+    kind: 'path';
+    templatePath: string;
+};

package/dist/runtime/template-source-contracts.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,21 @@
+import type { SeedSource, TemplateVariableContext } from './template-source-contracts.js';
+/**
+ * Candidate filenames for official external template config entrypoints.
+ */
+export declare const EXTERNAL_TEMPLATE_ENTRY_CANDIDATES: readonly ["index.js", "index.cjs", "index.mjs"];
+/**
+ * Search a source directory for the first supported external template entry.
+ *
+ * @param sourceDir Directory that may contain an external template config entry.
+ * @returns The first matching entry path, or null when no supported entry exists.
+ */
+export declare function getExternalTemplateEntry(sourceDir: string): string | null;
+/**
+ * Load an official external create-block template config and render its seed.
+ *
+ * @param sourceDir Source directory that contains the external template config.
+ * @param context Template render context used for the selected variant.
+ * @param requestedVariant Optional explicit variant override.
+ * @returns A rendered temporary seed directory with optional assets and cleanup.
+ */
+export declare function renderCreateBlockExternalTemplate(sourceDir: string, context: TemplateVariableContext, requestedVariant?: string): Promise<SeedSource>;