@wp-typia/project-tools 0.16.7 → 0.16.9

package/dist/runtime/cli-diagnostics.js

@@ -0,0 +1,101 @@
+const DEFAULT_CLI_FAILURE_SUMMARIES = {
+    add: "Unable to complete the requested add workflow.",
+    create: "Unable to complete the requested create workflow.",
+    doctor: "One or more doctor checks failed.",
+    migrate: "Unable to complete the requested migration command.",
+};
+function formatCliDiagnosticBlock(message) {
+    const lines = [`wp-typia ${message.command} failed`, `Summary: ${message.summary}`];
+    if (message.detailLines.length > 0) {
+        lines.push("Details:");
+        for (const detailLine of message.detailLines) {
+            lines.push(`- ${detailLine}`);
+        }
+    }
+    return lines.join("\n");
+}
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function normalizeDetailLines(detailLines) {
+    return detailLines
+        .flatMap((detailLine) => typeof detailLine === "string" ? detailLine.split("\n") : [])
+        .map((detailLine) => detailLine.trim())
+        .filter((detailLine) => detailLine.length > 0);
+}
+/**
+ * Structured CLI failure carrying a stable summary/detail layout.
+ */
+export class CliDiagnosticError extends Error {
+    constructor(message, options) {
+        super(formatCliDiagnosticBlock(message), options);
+        this.command = message.command;
+        this.detailLines = [...message.detailLines];
+        this.name = "CliDiagnosticError";
+        this.summary = message.summary;
+    }
+}
+/**
+ * Narrow an unknown error to the shared CLI diagnostic error shape.
+ */
+export function isCliDiagnosticError(error) {
+    return error instanceof CliDiagnosticError;
+}
+/**
+ * Build a shared diagnostic error for one CLI command failure.
+ */
+export function createCliCommandError(options) {
+    if (isCliDiagnosticError(options.error)) {
+        return options.error;
+    }
+    const summary = options.summary ?? DEFAULT_CLI_FAILURE_SUMMARIES[options.command] ?? "Command failed.";
+    const detailLines = normalizeDetailLines(options.detailLines ?? [options.error === undefined ? undefined : getErrorMessage(options.error)]);
+    return new CliDiagnosticError({
+        command: options.command,
+        detailLines,
+        summary,
+    }, options.error instanceof Error ? { cause: options.error } : undefined);
+}
+/**
+ * Render a CLI diagnostic block. Non-diagnostic errors fall back to their
+ * plain message so existing non-command failures keep working.
+ */
+export function formatCliDiagnosticError(error) {
+    if (!isCliDiagnosticError(error)) {
+        return getErrorMessage(error);
+    }
+    return formatCliDiagnosticBlock({
+        command: error.command,
+        detailLines: error.detailLines,
+        summary: error.summary,
+    });
+}
+/**
+ * Format one human-readable doctor check row.
+ */
+export function formatDoctorCheckLine(check) {
+    return `${check.status === "pass" ? "PASS" : "FAIL"} ${check.label}: ${check.detail}`;
+}
+/**
+ * Return the failing doctor checks from one doctor run.
+ */
+export function getFailingDoctorChecks(checks) {
+    return checks.filter((check) => check.status === "fail");
+}
+/**
+ * Format the final doctor summary row.
+ */
+export function formatDoctorSummaryLine(checks) {
+    const failedChecks = getFailingDoctorChecks(checks);
+    return `${failedChecks.length === 0 ? "PASS" : "FAIL"} wp-typia doctor summary: ${checks.length - failedChecks.length}/${checks.length} checks passed`;
+}
+/**
+ * Build detail lines for doctor failures so the non-interactive formatter can
+ * restate the failed checks after the streaming rows.
+ */
+export function getDoctorFailureDetailLines(checks) {
+    return getFailingDoctorChecks(checks).map((check) => `${check.label}: ${check.detail}`);
+}

package/dist/runtime/cli-doctor.d.ts

@@ -11,6 +11,7 @@ export interface DoctorCheck {
 }
 interface RunDoctorOptions {
     renderLine?: (check: DoctorCheck) => void;
+    renderSummaryLine?: (summaryLine: string) => void;
 }
 /**
  * Collect all runtime doctor checks for the current environment.
@@ -30,5 +31,5 @@ export declare function getDoctorChecks(cwd: string): Promise<DoctorCheck[]>;
  * @returns The completed list of doctor checks.
  * @throws {Error} When one or more checks fail.
  */
-export declare function runDoctor(cwd: string, { renderLine, }?: RunDoctorOptions): Promise<DoctorCheck[]>;
+export declare function runDoctor(cwd: string, options?: RunDoctorOptions): Promise<DoctorCheck[]>;
 export {};

package/dist/runtime/cli-doctor.js

@@ -3,11 +3,13 @@ import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { access, constants as fsConstants, rm, writeFile } from "node:fs/promises";
+import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
 import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, } from "./template-builtins.js";
 import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_SET, } from "./hooked-blocks.js";
 import { isBuiltInTemplateId, listTemplates } from "./template-registry.js";
 import { readWorkspaceInventory } from "./workspace-inventory.js";
 import { getInvalidWorkspaceProjectReason, parseWorkspacePackageJson, WORKSPACE_TEMPLATE_PACKAGE, tryResolveWorkspaceProject, } from "./workspace-project.js";
+import { createCliCommandError, formatDoctorCheckLine, formatDoctorSummaryLine, getDoctorFailureDetailLines, } from "./cli-diagnostics.js";
 const WORKSPACE_COLLECTION_IMPORT_LINE = "import '../../collection';";
 const WORKSPACE_COLLECTION_IMPORT_PATTERN = /^\s*import\s+["']\.\.\/\.\.\/collection["']\s*;?\s*$/m;
 const WORKSPACE_BINDING_SERVER_GLOB = "/src/bindings/*/server.php";
@@ -116,7 +118,7 @@ function checkWorkspaceBlockMetadata(projectDir, workspace, block) {
     }
     let blockJson;
     try {
-        blockJson = JSON.parse(fs.readFileSync(blockJsonPath, "utf8"));
+        blockJson = parseScaffoldBlockMetadata(JSON.parse(fs.readFileSync(blockJsonPath, "utf8")));
     }
     catch (error) {
         return createDoctorCheck(`Block metadata ${block.slug}`, "fail", error instanceof Error ? error.message : String(error));
@@ -141,7 +143,7 @@ function checkWorkspaceBlockHooks(projectDir, blockSlug) {
     }
     let blockJson;
     try {
-        blockJson = JSON.parse(fs.readFileSync(blockJsonPath, "utf8"));
+        blockJson = parseScaffoldBlockMetadata(JSON.parse(fs.readFileSync(blockJsonPath, "utf8")));
     }
     catch (error) {
         return createDoctorCheck(`Block hooks ${blockSlug}`, "fail", error instanceof Error ? error.message : String(error));
@@ -419,13 +421,22 @@ export async function getDoctorChecks(cwd) {
  * @returns The completed list of doctor checks.
  * @throws {Error} When one or more checks fail.
  */
-export async function runDoctor(cwd, { renderLine = (check) => console.log(`${check.status.toUpperCase()} ${check.label}: ${check.detail}`), } = {}) {
+export async function runDoctor(cwd, options = {}) {
+    const renderLine = options.renderLine ?? ((check) => console.log(formatDoctorCheckLine(check)));
+    const renderSummaryLine = options.renderSummaryLine ??
+        (options.renderLine ? () => undefined : (summaryLine) => console.log(summaryLine));
     const checks = await getDoctorChecks(cwd);
     for (const check of checks) {
         renderLine(check);
     }
-    if (checks.some((check) => check.status === "fail")) {
-        throw new Error("Doctor found one or more failing checks.");
+    renderSummaryLine(formatDoctorSummaryLine(checks));
+    const failureDetailLines = getDoctorFailureDetailLines(checks);
+    if (failureDetailLines.length > 0) {
+        throw createCliCommandError({
+            command: "doctor",
+            detailLines: failureDetailLines,
+            summary: "One or more doctor checks failed.",
+        });
     }
     return checks;
 }

package/dist/runtime/cli-help.js

@@ -10,13 +10,13 @@ import { TEMPLATE_IDS } from "./template-registry.js";
  */
 export function formatHelpText() {
     return `Usage:
-  wp-typia create <project-dir> [--template <basic|interactivity>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--no-install] [--package-manager <id>]
+  wp-typia create <project-dir> [--template <basic|interactivity>] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--no-install] [--package-manager <id>]
   wp-typia create <project-dir> [--template <./path|github:owner/repo/path[#ref]>] [--variant <name>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-wp-env] [--with-test-preset] [--yes] [--no-install] [--package-manager <id>]
   wp-typia create <project-dir> [--template <npm-package>] [--variant <name>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-wp-env] [--with-test-preset] [--yes] [--no-install] [--package-manager <id>]
-  wp-typia create <project-dir> [--template persistence] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--no-install] [--package-manager <id>]
-  wp-typia create <project-dir> [--template compound] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--no-install] [--package-manager <id>]
+  wp-typia create <project-dir> [--template persistence] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--no-install] [--package-manager <id>]
+  wp-typia create <project-dir> [--template compound] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--no-install] [--package-manager <id>]
   wp-typia <project-dir> [create flags...]
-  wp-typia add block <name> --template <basic|interactivity|persistence|compound> [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>]
+  wp-typia add block <name> --template <basic|interactivity|persistence|compound> [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>]
   wp-typia add variation <name> --block <block-slug>
   wp-typia add pattern <name>
   wp-typia add binding-source <name>

package/dist/runtime/cli-scaffold.d.ts

@@ -1,6 +1,7 @@
 import { collectScaffoldAnswers, scaffoldProject } from "./scaffold.js";
 import type { DataStorageMode, PersistencePolicy } from "./scaffold.js";
 import type { PackageManagerId } from "./package-managers.js";
+import { type ExternalLayerSelectionOption } from "./external-layer-selection.js";
 import type { TemplateDefinition } from "./template-registry.js";
 interface GetNextStepsOptions {
     noInstall: boolean;
@@ -23,6 +24,8 @@ interface RunScaffoldFlowOptions {
     allowExistingDir?: boolean;
     cwd?: string;
     dataStorageMode?: string;
+    externalLayerId?: string;
+    externalLayerSource?: string;
     installDependencies?: Parameters<typeof scaffoldProject>[0]["installDependencies"];
     isInteractive?: boolean;
     namespace?: string;
@@ -32,6 +35,7 @@ interface RunScaffoldFlowOptions {
     projectInput: string;
     promptText?: Parameters<typeof collectScaffoldAnswers>[0]["promptText"];
     selectDataStorage?: () => Promise<DataStorageMode>;
+    selectExternalLayerId?: (options: ExternalLayerSelectionOption[]) => Promise<string>;
     selectPackageManager?: () => Promise<PackageManagerId>;
     selectPersistencePolicy?: () => Promise<PersistencePolicy>;
     selectTemplate?: () => Promise<TemplateDefinition["id"]>;
@@ -69,7 +73,7 @@ export declare function getOptionalOnboarding({ availableScripts, packageManager
  * project.
  * @returns The scaffold result together with next-step guidance.
  */
-export declare function runScaffoldFlow({ projectInput, cwd, templateId, dataStorageMode, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, yes, noInstall, isInteractive, allowExistingDir, selectTemplate, selectDataStorage, selectPersistencePolicy, selectPackageManager, promptText, installDependencies, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }: RunScaffoldFlowOptions): Promise<{
+export declare function runScaffoldFlow({ projectInput, cwd, templateId, dataStorageMode, externalLayerId, externalLayerSource, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, yes, noInstall, isInteractive, allowExistingDir, selectTemplate, selectDataStorage, selectExternalLayerId, selectPersistencePolicy, selectPackageManager, promptText, installDependencies, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }: RunScaffoldFlowOptions): Promise<{
     optionalOnboarding: OptionalOnboardingGuidance;
     projectDir: string;
     projectInput: string;

package/dist/runtime/cli-scaffold.js

@@ -5,6 +5,7 @@ import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
 import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
 import { getOptionalOnboardingNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
+import { resolveOptionalInteractiveExternalLayerId, } from "./external-layer-selection.js";
 function templateUsesPersistenceSettings(templateId, options) {
     if (templateId === "persistence") {
         return true;
@@ -98,7 +99,14 @@ export function getOptionalOnboarding({ availableScripts, packageManager, templa
  * project.
  * @returns The scaffold result together with next-step guidance.
  */
-export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templateId, dataStorageMode, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, yes = false, noInstall = false, isInteractive = false, allowExistingDir = false, selectTemplate, selectDataStorage, selectPersistencePolicy, selectPackageManager, promptText, installDependencies = undefined, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }) {
+export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templateId, dataStorageMode, externalLayerId, externalLayerSource, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, yes = false, noInstall = false, isInteractive = false, allowExistingDir = false, selectTemplate, selectDataStorage, selectExternalLayerId, selectPersistencePolicy, selectPackageManager, promptText, installDependencies = undefined, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }) {
+    const normalizedExternalLayerId = typeof externalLayerId === "string" && externalLayerId.trim().length > 0
+        ? externalLayerId.trim()
+        : undefined;
+    const normalizedExternalLayerSource = typeof externalLayerSource === "string" &&
+        externalLayerSource.trim().length > 0
+        ? externalLayerSource.trim()
+        : undefined;
     if (!projectInput) {
         throw new Error("Project directory is required. Usage: wp-typia create <project-dir> (or wp-typia <project-dir>).");
     }
@@ -108,119 +116,138 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
         isInteractive,
         selectTemplate,
     });
-    const shouldResolvePersistence = templateUsesPersistenceSettings(resolvedTemplateId, {
-        dataStorageMode,
-        persistencePolicy,
-    });
-    const resolvedDataStorage = await resolveOptionalSelection({
-        allowedValues: DATA_STORAGE_MODES,
-        defaultValue: "custom-table",
-        explicitValue: dataStorageMode,
-        isInteractive,
-        isValue: isDataStorageMode,
-        label: "data storage mode",
-        select: selectDataStorage,
-        shouldResolve: shouldResolvePersistence,
-        yes,
-    });
-    const resolvedPersistencePolicy = await resolveOptionalSelection({
-        allowedValues: PERSISTENCE_POLICIES,
-        defaultValue: "authenticated",
-        explicitValue: persistencePolicy,
-        isInteractive,
-        isValue: isPersistencePolicy,
-        label: "persistence policy",
-        select: selectPersistencePolicy,
-        shouldResolve: shouldResolvePersistence,
-        yes,
-    });
-    const resolvedPackageManager = await resolvePackageManagerId({
-        packageManager,
-        yes,
-        isInteractive,
-        selectPackageManager,
-    });
-    const resolvedWithWpEnv = await resolveOptionalBooleanFlag({
-        explicitValue: withWpEnv,
-        isInteractive,
-        select: selectWithWpEnv,
-        yes,
-    });
-    const resolvedWithTestPreset = await resolveOptionalBooleanFlag({
-        explicitValue: withTestPreset,
-        isInteractive,
-        select: selectWithTestPreset,
-        yes,
-    });
-    const resolvedWithMigrationUi = await resolveOptionalBooleanFlag({
-        disabled: !isBuiltInTemplateId(resolvedTemplateId) &&
-            resolvedTemplateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE,
-        explicitValue: withMigrationUi,
-        isInteractive,
-        select: selectWithMigrationUi,
-        yes,
-    });
-    const projectDir = path.resolve(cwd, projectInput);
-    const projectName = path.basename(projectDir);
-    const answers = await collectScaffoldAnswers({
-        dataStorageMode: resolvedDataStorage,
-        namespace,
-        persistencePolicy: resolvedPersistencePolicy,
-        phpPrefix,
-        projectName,
-        templateId: resolvedTemplateId,
-        textDomain,
-        yes,
-        promptText,
-    });
-    const result = await scaffoldProject({
-        answers,
-        allowExistingDir,
-        cwd,
-        dataStorageMode: resolvedDataStorage,
-        installDependencies,
-        noInstall,
-        packageManager: resolvedPackageManager,
-        persistencePolicy: resolvedPersistencePolicy,
-        projectDir,
-        templateId: resolvedTemplateId,
-        variant,
-        withMigrationUi: resolvedWithMigrationUi,
-        withTestPreset: resolvedWithTestPreset,
-        withWpEnv: resolvedWithWpEnv,
-    });
-    let availableScripts;
+    const resolvedExternalLayerSelection = isBuiltInTemplateId(resolvedTemplateId) && isInteractive
+        ? await resolveOptionalInteractiveExternalLayerId({
+            callerCwd: cwd,
+            externalLayerId: normalizedExternalLayerId,
+            externalLayerSource: normalizedExternalLayerSource,
+            selectExternalLayerId,
+        })
+        : {
+            externalLayerId: normalizedExternalLayerId,
+            externalLayerSource: normalizedExternalLayerSource,
+        };
     try {
-        const parsedPackageJson = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8"));
-        const scripts = parsedPackageJson.scripts &&
-            typeof parsedPackageJson.scripts === "object" &&
-            !Array.isArray(parsedPackageJson.scripts)
-            ? parsedPackageJson.scripts
-            : {};
-        availableScripts = Object.entries(scripts)
-            .filter(([, value]) => typeof value === "string")
-            .map(([scriptName]) => scriptName);
-    }
-    catch {
-        availableScripts = undefined;
-    }
-    return {
-        optionalOnboarding: getOptionalOnboarding({
-            availableScripts,
+        const shouldResolvePersistence = templateUsesPersistenceSettings(resolvedTemplateId, {
+            dataStorageMode,
+            persistencePolicy,
+        });
+        const resolvedDataStorage = await resolveOptionalSelection({
+            allowedValues: DATA_STORAGE_MODES,
+            defaultValue: "custom-table",
+            explicitValue: dataStorageMode,
+            isInteractive,
+            isValue: isDataStorageMode,
+            label: "data storage mode",
+            select: selectDataStorage,
+            shouldResolve: shouldResolvePersistence,
+            yes,
+        });
+        const resolvedPersistencePolicy = await resolveOptionalSelection({
+            allowedValues: PERSISTENCE_POLICIES,
+            defaultValue: "authenticated",
+            explicitValue: persistencePolicy,
+            isInteractive,
+            isValue: isPersistencePolicy,
+            label: "persistence policy",
+            select: selectPersistencePolicy,
+            shouldResolve: shouldResolvePersistence,
+            yes,
+        });
+        const resolvedPackageManager = await resolvePackageManagerId({
+            packageManager,
+            yes,
+            isInteractive,
+            selectPackageManager,
+        });
+        const resolvedWithWpEnv = await resolveOptionalBooleanFlag({
+            explicitValue: withWpEnv,
+            isInteractive,
+            select: selectWithWpEnv,
+            yes,
+        });
+        const resolvedWithTestPreset = await resolveOptionalBooleanFlag({
+            explicitValue: withTestPreset,
+            isInteractive,
+            select: selectWithTestPreset,
+            yes,
+        });
+        const resolvedWithMigrationUi = await resolveOptionalBooleanFlag({
+            disabled: !isBuiltInTemplateId(resolvedTemplateId) &&
+                resolvedTemplateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE,
+            explicitValue: withMigrationUi,
+            isInteractive,
+            select: selectWithMigrationUi,
+            yes,
+        });
+        const projectDir = path.resolve(cwd, projectInput);
+        const projectName = path.basename(projectDir);
+        const answers = await collectScaffoldAnswers({
+            dataStorageMode: resolvedDataStorage,
+            namespace,
+            persistencePolicy: resolvedPersistencePolicy,
+            phpPrefix,
+            projectName,
+            templateId: resolvedTemplateId,
+            textDomain,
+            yes,
+            promptText,
+        });
+        const result = await scaffoldProject({
+            answers,
+            allowExistingDir,
+            cwd,
+            dataStorageMode: resolvedDataStorage,
+            externalLayerId: resolvedExternalLayerSelection.externalLayerId,
+            externalLayerSource: resolvedExternalLayerSelection.externalLayerSource,
+            externalLayerSourceLabel: normalizedExternalLayerSource,
+            installDependencies,
+            noInstall,
             packageManager: resolvedPackageManager,
+            persistencePolicy: resolvedPersistencePolicy,
+            projectDir,
             templateId: resolvedTemplateId,
-            compoundPersistenceEnabled: result.variables.compoundPersistenceEnabled === "true",
-        }),
-        projectDir,
-        projectInput,
-        packageManager: resolvedPackageManager,
-        result,
-        nextSteps: getNextSteps({
-            projectInput,
+            variant,
+            withMigrationUi: resolvedWithMigrationUi,
+            withTestPreset: resolvedWithTestPreset,
+            withWpEnv: resolvedWithWpEnv,
+        });
+        let availableScripts;
+        try {
+            const parsedPackageJson = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8"));
+            const scripts = parsedPackageJson.scripts &&
+                typeof parsedPackageJson.scripts === "object" &&
+                !Array.isArray(parsedPackageJson.scripts)
+                ? parsedPackageJson.scripts
+                : {};
+            availableScripts = Object.entries(scripts)
+                .filter(([, value]) => typeof value === "string")
+                .map(([scriptName]) => scriptName);
+        }
+        catch {
+            availableScripts = undefined;
+        }
+        return {
+            optionalOnboarding: getOptionalOnboarding({
+                availableScripts,
+                packageManager: resolvedPackageManager,
+                templateId: resolvedTemplateId,
+                compoundPersistenceEnabled: result.variables.compoundPersistenceEnabled === "true",
+            }),
             projectDir,
+            projectInput,
             packageManager: resolvedPackageManager,
-            noInstall,
-            templateId: resolvedTemplateId,
-        }),
-    };
+            result,
+            nextSteps: getNextSteps({
+                projectInput,
+                projectDir,
+                packageManager: resolvedPackageManager,
+                noInstall,
+                templateId: resolvedTemplateId,
+            }),
+        };
+    }
+    finally {
+        await resolvedExternalLayerSelection.cleanup?.();
+    }
 }

package/dist/runtime/external-layer-selection.d.ts

@@ -0,0 +1,14 @@
+import { type SelectableExternalTemplateLayer } from "./template-layers.js";
+export interface ExternalLayerSelectionOption extends SelectableExternalTemplateLayer {
+}
+export interface ResolvedExternalLayerSelection {
+    cleanup?: () => Promise<void>;
+    externalLayerId?: string;
+    externalLayerSource?: string;
+}
+export declare function resolveOptionalInteractiveExternalLayerId({ callerCwd, externalLayerId, externalLayerSource, selectExternalLayerId, }: {
+    callerCwd: string;
+    externalLayerId?: string;
+    externalLayerSource?: string;
+    selectExternalLayerId?: (options: ExternalLayerSelectionOption[]) => Promise<string>;
+}): Promise<ResolvedExternalLayerSelection>;

package/dist/runtime/external-layer-selection.js

@@ -0,0 +1,35 @@
+import { parseTemplateLocator, resolveTemplateSeed, } from "./template-source.js";
+import { listSelectableExternalTemplateLayers, } from "./template-layers.js";
+export async function resolveOptionalInteractiveExternalLayerId({ callerCwd, externalLayerId, externalLayerSource, selectExternalLayerId, }) {
+    if (!externalLayerSource || externalLayerId || !selectExternalLayerId) {
+        return {
+            externalLayerId,
+            externalLayerSource,
+        };
+    }
+    const layerSeed = await resolveTemplateSeed(parseTemplateLocator(externalLayerSource), callerCwd);
+    try {
+        const selectableLayers = await listSelectableExternalTemplateLayers(layerSeed.rootDir);
+        if (selectableLayers.length <= 1) {
+            await layerSeed.cleanup?.();
+            return {
+                externalLayerId,
+                externalLayerSource,
+            };
+        }
+        const selectedLayerId = await selectExternalLayerId(selectableLayers);
+        if (selectableLayers.some((layer) => layer.id === selectedLayerId)) {
+            return {
+                cleanup: layerSeed.cleanup,
+                externalLayerId: selectedLayerId,
+                externalLayerSource: layerSeed.rootDir,
+            };
+        }
+        await layerSeed.cleanup?.();
+        throw new Error(`Unknown external layer "${selectedLayerId}". Expected one of: ${selectableLayers.map((layer) => layer.id).join(", ")}`);
+    }
+    catch (error) {
+        await layerSeed.cleanup?.();
+        throw error;
+    }
+}

package/dist/runtime/index.d.ts

@@ -12,6 +12,8 @@
 export { scaffoldProject, collectScaffoldAnswers, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
 export { BlockGeneratorService } from "./block-generator-service.js";
 export type { ApplyBlockInput, BlockGenerationTarget, BlockSpec, PlanBlockInput, PlanBlockResult, RenderBlockInput, RenderBlockResult, ValidateBlockInput, ValidateBlockResult, } from "./block-generator-service.js";
+export { BLOCK_GENERATION_TOOL_CONTRACT_VERSION, inspectBlockGeneration, } from "./block-generator-tool-contract.js";
+export type { BlockGenerationEmittedFilePreview, BlockGenerationRenderPreview, BlockGenerationStarterManifestPreview, BlockGenerationTemplateCopyPreview, BlockGenerationToolStage, InspectBlockGenerationInput, InspectBlockGenerationPlanResult, InspectBlockGenerationRenderResult, InspectBlockGenerationResult, InspectBlockGenerationValidateResult, } from "./block-generator-tool-contract.js";
 export { formatMigrationHelpText, parseMigrationArgs, runMigrationCommand, } from "./migrations.js";
 export { parseWorkspacePackageManagerId, resolveWorkspaceProject, tryResolveWorkspaceProject, } from "./workspace-project.js";
 export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, } from "./schema-core.js";
@@ -19,5 +21,5 @@ export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, str
 export type { EndpointAuthIntent, EndpointOpenApiAuthMode, EndpointOpenApiContractDocument, EndpointOpenApiDocumentOptions, EndpointOpenApiEndpointDefinition, EndpointOpenApiMethod, EndpointWordPressAuthDefinition, EndpointWordPressAuthMechanism, JsonSchemaDocument, JsonSchemaProjectionProfile, JsonSchemaObject, NormalizedEndpointAuthDefinition, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiSecurityScheme, } from "./schema-core.js";
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
-export { createReadlinePrompt, formatAddHelpText, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, runAddBindingSourceCommand, runAddBlockCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
-export type { DoctorCheck, HookedBlockPositionId, ReadlinePrompt } from "./cli-core.js";
+export { createReadlinePrompt, createCliCommandError, CliDiagnosticError, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, isCliDiagnosticError, runAddBindingSourceCommand, runAddBlockCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
+export type { CliDiagnosticMessage, DoctorCheck, HookedBlockPositionId, ReadlinePrompt, } from "./cli-core.js";

package/dist/runtime/index.js

@@ -11,10 +11,11 @@
  */
 export { scaffoldProject, collectScaffoldAnswers, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
 export { BlockGeneratorService } from "./block-generator-service.js";
+export { BLOCK_GENERATION_TOOL_CONTRACT_VERSION, inspectBlockGeneration, } from "./block-generator-tool-contract.js";
 export { formatMigrationHelpText, parseMigrationArgs, runMigrationCommand, } from "./migrations.js";
 export { parseWorkspacePackageManagerId, resolveWorkspaceProject, tryResolveWorkspaceProject, } from "./workspace-project.js";
 export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, } from "./schema-core.js";
 export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
-export { createReadlinePrompt, formatAddHelpText, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, runAddBindingSourceCommand, runAddBlockCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
+export { createReadlinePrompt, createCliCommandError, CliDiagnosticError, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, isCliDiagnosticError, runAddBindingSourceCommand, runAddBlockCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";

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

@@ -3,8 +3,30 @@ export declare function formatDiffReport(diff: MigrationDiff, { includeRiskSumma
     includeRiskSummary?: boolean;
 }): string;
 export declare function renderMigrationRuleFile({ block, currentAttributes, currentTypeName, diff, fromVersion, projectDir, rulePath, targetVersion, }: MigrationRuleFileInput): string;
+/**
+ * Renders the generated migration registry module for a block target.
+ *
+ * Prefers manifest wrapper modules when they are available in the project,
+ * while still validating the imported manifest before the registry consumes it.
+ *
+ * @param state The resolved migration project state.
+ * @param blockKey The stable key for the block whose registry is being generated.
+ * @param entries The generated migration entries to include in the registry.
+ * @returns The generated TypeScript source code for the migration registry file.
+ */
 export declare function renderMigrationRegistryFile(state: MigrationProjectState, blockKey: string, entries: GeneratedMigrationEntry[]): string;
-export declare function renderGeneratedDeprecatedFile(entries: MigrationEntry[]): string;
+/**
+ * Renders the generated deprecated module for a block target.
+ *
+ * The emitted module exposes the ordered deprecation array consumed by block
+ * registration and migration helpers.
+ *
+ * @param state The resolved migration project state.
+ * @param blockKey The stable key for the block whose deprecated entries are being generated.
+ * @param entries The migration entries that define deprecated manifest versions.
+ * @returns The generated TypeScript source code for the deprecated module.
+ */
+export declare function renderGeneratedDeprecatedFile(state: MigrationProjectState, blockKey: string, entries: MigrationEntry[]): string;
 export declare function renderGeneratedMigrationIndexFile(state: MigrationProjectState, entries: MigrationEntry[]): string;
 export declare function renderPhpMigrationRegistryFile(state: MigrationProjectState, entries: MigrationEntry[]): string;
 export declare function renderVerifyFile(state: MigrationProjectState, blockKey: string, entries: MigrationEntry[]): string;