@wp-typia/project-tools 0.24.4 → 0.24.6

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

@@ -0,0 +1,171 @@
+/**
+ * Shared human-readable diagnostics for non-interactive `wp-typia` CLI flows.
+ */
+export interface CliDiagnosticMessage {
+    code: CliDiagnosticCode;
+    command: string;
+    detailLines: string[];
+    summary: string;
+}
+export declare const CLI_DIAGNOSTIC_CODES: {
+    readonly COMMAND_EXECUTION: "command-execution";
+    readonly CONFIGURATION_MISSING: "configuration-missing";
+    readonly DEPENDENCIES_NOT_INSTALLED: "dependencies-not-installed";
+    readonly DOCTOR_CHECK_FAILED: "doctor-check-failed";
+    readonly INVALID_ARGUMENT: "invalid-argument";
+    readonly INVALID_COMMAND: "invalid-command";
+    readonly MISSING_ARGUMENT: "missing-argument";
+    readonly MISSING_BUILD_ARTIFACT: "missing-build-artifact";
+    readonly OUTSIDE_PROJECT_ROOT: "outside-project-root";
+    readonly TEMPLATE_SOURCE_TIMEOUT: "template-source-timeout";
+    readonly TEMPLATE_SOURCE_TOO_LARGE: "template-source-too-large";
+    readonly UNKNOWN_TEMPLATE: "unknown-template";
+    readonly UNSUPPORTED_COMMAND: "unsupported-command";
+};
+export type CliDiagnosticCode = (typeof CLI_DIAGNOSTIC_CODES)[keyof typeof CLI_DIAGNOSTIC_CODES];
+/**
+ * Human-readable guidance attached to one stable CLI diagnostic code.
+ */
+export interface CliDiagnosticCodeMetadata {
+    /** Why this diagnostic code is emitted. */
+    cause: string;
+    /** The recommended recovery path for users and automation. */
+    recovery: string;
+}
+/**
+ * Stable cause and recovery metadata for every supported CLI diagnostic code.
+ */
+export declare const CLI_DIAGNOSTIC_CODE_METADATA: {
+    "command-execution": {
+        cause: string;
+        recovery: string;
+    };
+    "configuration-missing": {
+        cause: string;
+        recovery: string;
+    };
+    "dependencies-not-installed": {
+        cause: string;
+        recovery: string;
+    };
+    "doctor-check-failed": {
+        cause: string;
+        recovery: string;
+    };
+    "invalid-argument": {
+        cause: string;
+        recovery: string;
+    };
+    "invalid-command": {
+        cause: string;
+        recovery: string;
+    };
+    "missing-argument": {
+        cause: string;
+        recovery: string;
+    };
+    "missing-build-artifact": {
+        cause: string;
+        recovery: string;
+    };
+    "outside-project-root": {
+        cause: string;
+        recovery: string;
+    };
+    "template-source-timeout": {
+        cause: string;
+        recovery: string;
+    };
+    "template-source-too-large": {
+        cause: string;
+        recovery: string;
+    };
+    "unknown-template": {
+        cause: string;
+        recovery: string;
+    };
+    "unsupported-command": {
+        cause: string;
+        recovery: string;
+    };
+};
+export type CliDiagnosticCodeError<TCode extends CliDiagnosticCode = CliDiagnosticCode> = Error & {
+    code: TCode;
+};
+type DoctorCheckLike = {
+    code?: string;
+    detail: string;
+    label: string;
+    status: "pass" | "fail" | "warn";
+};
+/**
+ * Structured CLI failure carrying a stable summary/detail layout.
+ */
+export declare class CliDiagnosticError extends Error {
+    readonly code: CliDiagnosticCode;
+    readonly command: string;
+    readonly detailLines: string[];
+    readonly summary: string;
+    constructor(message: CliDiagnosticMessage, options?: ErrorOptions);
+}
+/**
+ * Narrow an unknown error to the shared CLI diagnostic error shape.
+ */
+export declare function isCliDiagnosticError(error: unknown): error is CliDiagnosticError;
+/**
+ * Look up cause and recovery guidance for a stable CLI diagnostic code.
+ */
+export declare function getCliDiagnosticCodeMetadata(code: CliDiagnosticCode): CliDiagnosticCodeMetadata;
+/**
+ * Tag a user-facing CLI throw site with a stable diagnostic code.
+ *
+ * Prefer this helper, or `createCliCommandError({ code })`, for new known CLI
+ * failures. `inferCliDiagnosticCode()` remains only a compatibility fallback
+ * for legacy or untyped errors.
+ */
+export declare function createCliDiagnosticCodeError<TCode extends CliDiagnosticCode>(code: TCode, message: string, options?: ErrorOptions): CliDiagnosticCodeError<TCode>;
+/**
+ * Build a shared diagnostic error for one CLI command failure.
+ */
+export declare function createCliCommandError(options: {
+    command: string;
+    code?: CliDiagnosticCode;
+    detailLines?: string[];
+    error?: unknown;
+    summary?: string;
+}): CliDiagnosticError;
+/**
+ * Render a CLI diagnostic block. Non-diagnostic errors fall back to their
+ * plain message so existing non-command failures keep working.
+ */
+export declare function formatCliDiagnosticError(error: unknown): string;
+export declare function serializeCliDiagnosticError(error: unknown): {
+    code: CliDiagnosticCode;
+    command?: string;
+    detailLines?: string[];
+    kind: "command-execution";
+    message: string;
+    name: string;
+    summary?: string;
+    tag: "CommandExecutionError";
+};
+/**
+ * Format one human-readable doctor check row.
+ */
+export declare function formatDoctorCheckLine(check: DoctorCheckLike): string;
+/**
+ * Return the failing doctor checks from one doctor run.
+ */
+export declare function getFailingDoctorChecks<TCheck extends DoctorCheckLike>(checks: readonly TCheck[]): TCheck[];
+/**
+ * Format the final doctor summary row.
+ */
+export declare function formatDoctorSummaryLine(checks: readonly DoctorCheckLike[], options?: {
+    exitFailureChecks?: readonly DoctorCheckLike[];
+}): string;
+/**
+ * Build detail lines for doctor failures so the non-interactive formatter can
+ * restate the failed checks after the streaming rows.
+ */
+export declare function getDoctorFailureDetailLines(checks: readonly DoctorCheckLike[]): string[];
+export {};

package/dist/runtime/cli/cli-diagnostics.js

@@ -0,0 +1,393 @@
+export const CLI_DIAGNOSTIC_CODES = {
+    COMMAND_EXECUTION: "command-execution",
+    CONFIGURATION_MISSING: "configuration-missing",
+    DEPENDENCIES_NOT_INSTALLED: "dependencies-not-installed",
+    DOCTOR_CHECK_FAILED: "doctor-check-failed",
+    INVALID_ARGUMENT: "invalid-argument",
+    INVALID_COMMAND: "invalid-command",
+    MISSING_ARGUMENT: "missing-argument",
+    MISSING_BUILD_ARTIFACT: "missing-build-artifact",
+    OUTSIDE_PROJECT_ROOT: "outside-project-root",
+    TEMPLATE_SOURCE_TIMEOUT: "template-source-timeout",
+    TEMPLATE_SOURCE_TOO_LARGE: "template-source-too-large",
+    UNKNOWN_TEMPLATE: "unknown-template",
+    UNSUPPORTED_COMMAND: "unsupported-command",
+};
+/**
+ * Stable cause and recovery metadata for every supported CLI diagnostic code.
+ */
+export const CLI_DIAGNOSTIC_CODE_METADATA = {
+    [CLI_DIAGNOSTIC_CODES.COMMAND_EXECUTION]: {
+        cause: "The command failed after argument parsing and preflight checks completed.",
+        recovery: "Read the detail lines for the underlying tool failure, rerun with the same command once corrected, and report the full JSON envelope if the recovery is unclear.",
+    },
+    [CLI_DIAGNOSTIC_CODES.CONFIGURATION_MISSING]: {
+        cause: "A command needs configuration that is not present in the current project.",
+        recovery: "Add the missing wp-typia config section or rerun the scaffold/init flow that creates the expected configuration.",
+    },
+    [CLI_DIAGNOSTIC_CODES.DEPENDENCIES_NOT_INSTALLED]: {
+        cause: "Generated project or workspace dependencies are missing from the local install.",
+        recovery: "Run the package-manager install command from the reported project root, then rerun the wp-typia command.",
+    },
+    [CLI_DIAGNOSTIC_CODES.DOCTOR_CHECK_FAILED]: {
+        cause: "One or more doctor checks reported a failing environment or workspace row.",
+        recovery: "Inspect the failed check labels and details, fix the reported drift or missing prerequisite, then rerun `wp-typia doctor`.",
+    },
+    [CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT]: {
+        cause: "An argument was present but did not match the supported value, shape, or project state.",
+        recovery: "Correct the argument value using command help or the detail lines, then rerun the command.",
+    },
+    [CLI_DIAGNOSTIC_CODES.INVALID_COMMAND]: {
+        cause: "The command or subcommand is not part of the supported wp-typia command tree.",
+        recovery: "Run `wp-typia --help` or the relevant command help and switch to a supported command/subcommand.",
+    },
+    [CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT]: {
+        cause: "A required positional argument or flag value was omitted.",
+        recovery: "Provide the missing argument or flag value shown in the detail lines, then rerun the command.",
+    },
+    [CLI_DIAGNOSTIC_CODES.MISSING_BUILD_ARTIFACT]: {
+        cause: "The published or standalone CLI layout is missing bundled build artifacts.",
+        recovery: "Reinstall the package or standalone binary, or rebuild the workspace before invoking the command again.",
+    },
+    [CLI_DIAGNOSTIC_CODES.OUTSIDE_PROJECT_ROOT]: {
+        cause: "The command was run outside a generated wp-typia project or official workspace root.",
+        recovery: "Change into the scaffolded project/workspace root, or rerun the scaffold/init workflow that creates the expected root files.",
+    },
+    [CLI_DIAGNOSTIC_CODES.TEMPLATE_SOURCE_TIMEOUT]: {
+        cause: "External template resolution did not complete within the allowed time.",
+        recovery: "Retry with a reachable template source, use a local path, or cache the template package before rerunning.",
+    },
+    [CLI_DIAGNOSTIC_CODES.TEMPLATE_SOURCE_TOO_LARGE]: {
+        cause: "External template content exceeded the safety size limit.",
+        recovery: "Reduce the template package size or point wp-typia at a smaller official template layer.",
+    },
+    [CLI_DIAGNOSTIC_CODES.UNKNOWN_TEMPLATE]: {
+        cause: "The requested scaffold template or add-block template id is not registered.",
+        recovery: "Run `wp-typia templates list` and rerun with one of the listed template ids.",
+    },
+    [CLI_DIAGNOSTIC_CODES.UNSUPPORTED_COMMAND]: {
+        cause: "The requested command exists conceptually but is not supported by the current runtime surface.",
+        recovery: "Install Bun 1.3.11+ or use the standalone wp-typia binary when the detail lines say the Bun-powered runtime is required.",
+    },
+};
+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.",
+    init: "Unable to preview the requested retrofit init plan.",
+    mcp: "Unable to inspect or sync MCP metadata.",
+    migrate: "Unable to complete the requested migration command.",
+    sync: "Unable to complete the requested sync workflow.",
+    templates: "Unable to inspect scaffold templates.",
+};
+const MIN_CLI_WRAP_COLUMNS = 32;
+function parseCliColumns(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed >= MIN_CLI_WRAP_COLUMNS ? parsed : null;
+}
+function resolveCliWrapColumns(streamColumns) {
+    return parseCliColumns(process.env.COLUMNS) ??
+        (typeof streamColumns === "number" && streamColumns >= MIN_CLI_WRAP_COLUMNS
+            ? streamColumns
+            : null);
+}
+function wrapCliText(text, maxWidth) {
+    const words = text.trim().split(/\s+/u).filter((word) => word.length > 0);
+    if (words.length === 0) {
+        return [""];
+    }
+    const lines = [];
+    let currentLine = words[0] ?? "";
+    for (const word of words.slice(1)) {
+        const nextLine = `${currentLine} ${word}`;
+        if (nextLine.length <= maxWidth) {
+            currentLine = nextLine;
+            continue;
+        }
+        lines.push(currentLine);
+        currentLine = word;
+    }
+    lines.push(currentLine);
+    return lines;
+}
+function formatWrappedPrefixedLine(prefix, text, columns, continuationIndent = "  ") {
+    const singleLine = `${prefix}${text}`;
+    if (columns === null || singleLine.length <= columns) {
+        return [singleLine];
+    }
+    const words = text.trim().split(/\s+/u).filter((word) => word.length > 0);
+    if (words.length === 0) {
+        return [prefix.trimEnd()];
+    }
+    const continuationWidth = Math.max(1, columns - continuationIndent.length);
+    const firstLineWidth = columns - prefix.length;
+    if (firstLineWidth <= 0 || (words[0]?.length ?? 0) > firstLineWidth) {
+        return [
+            prefix.trimEnd(),
+            ...wrapCliText(text, continuationWidth).map((line) => `${continuationIndent}${line}`),
+        ];
+    }
+    const lines = [];
+    let currentPrefix = prefix;
+    let currentWidth = Math.max(1, columns - currentPrefix.length);
+    let currentLine = words[0] ?? "";
+    for (const word of words.slice(1)) {
+        const nextLine = `${currentLine} ${word}`;
+        if (nextLine.length <= currentWidth) {
+            currentLine = nextLine;
+            continue;
+        }
+        lines.push(`${currentPrefix}${currentLine}`);
+        currentPrefix = continuationIndent;
+        currentWidth = continuationWidth;
+        currentLine = word;
+    }
+    lines.push(`${currentPrefix}${currentLine}`);
+    return lines;
+}
+function formatCliDiagnosticBlock(message) {
+    const columns = resolveCliWrapColumns(process.stderr.columns);
+    const lines = [
+        `wp-typia ${message.command} failed`,
+        ...formatWrappedPrefixedLine("Summary: ", message.summary, columns),
+    ];
+    if (message.detailLines.length > 0) {
+        lines.push("Details:");
+        for (const detailLine of message.detailLines) {
+            lines.push(...formatWrappedPrefixedLine("- ", detailLine, columns));
+        }
+    }
+    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.code = message.code;
+        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;
+}
+function isCliDiagnosticCode(value) {
+    return Object.values(CLI_DIAGNOSTIC_CODES).includes(value);
+}
+function readCliDiagnosticCode(error) {
+    if (isCliDiagnosticError(error)) {
+        return error.code;
+    }
+    if (typeof error === "object" && error !== null && "code" in error) {
+        const { code } = error;
+        if (isCliDiagnosticCode(code)) {
+            return code;
+        }
+    }
+    return null;
+}
+/**
+ * Look up cause and recovery guidance for a stable CLI diagnostic code.
+ */
+export function getCliDiagnosticCodeMetadata(code) {
+    return CLI_DIAGNOSTIC_CODE_METADATA[code];
+}
+/**
+ * Tag a user-facing CLI throw site with a stable diagnostic code.
+ *
+ * Prefer this helper, or `createCliCommandError({ code })`, for new known CLI
+ * failures. `inferCliDiagnosticCode()` remains only a compatibility fallback
+ * for legacy or untyped errors.
+ */
+export function createCliDiagnosticCodeError(code, message, options) {
+    const error = new Error(message, options);
+    error.code = code;
+    return error;
+}
+/**
+ * Compatibility-only fallback for legacy or third-party errors that have not
+ * yet been tagged by their throw site.
+ *
+ * The regexes below intentionally couple this classifier to existing
+ * project-tools runtime validation messages. Treat them as compatibility shims:
+ * changing a validation message can silently change, downgrade, or remove the
+ * inferred diagnostic code. New user-facing runtime validation failures should
+ * pass an explicit code through `createCliDiagnosticCodeError()` or
+ * `createCliCommandError({ code })` instead of adding new message patterns.
+ */
+function inferCliDiagnosticCode(options) {
+    const inheritedCode = readCliDiagnosticCode(options.error);
+    if (inheritedCode) {
+        return inheritedCode;
+    }
+    const haystack = normalizeDetailLines([
+        ...options.detailLines,
+        options.error === undefined ? undefined : getErrorMessage(options.error),
+    ]).join("\n");
+    if (/No MCP schema sources are configured\./u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.CONFIGURATION_MISSING;
+    }
+    if (/Missing bundled build artifacts/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.MISSING_BUILD_ARTIFACT;
+    }
+    if (/No generated wp-typia project root was found/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.OUTSIDE_PROJECT_ROOT;
+    }
+    if (/dependencies have not been installed yet/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.DEPENDENCIES_NOT_INSTALLED;
+    }
+    if (/Timed out while .*external template|Timed out while .*npm template|Timed out while .*GitHub template/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.TEMPLATE_SOURCE_TIMEOUT;
+    }
+    if (/external template size limit/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.TEMPLATE_SOURCE_TOO_LARGE;
+    }
+    if (options.command === "doctor") {
+        return CLI_DIAGNOSTIC_CODES.DOCTOR_CHECK_FAILED;
+    }
+    if (/requires <|requires --|requires a value/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT;
+    }
+    if (/Unknown (?:add-block )?template\s+(?:"|\\")/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.UNKNOWN_TEMPLATE;
+    }
+    if (/Unknown .*subcommand|Unknown add kind|removed in favor|does not support|The positional alias only accepts/u.test(haystack)) {
+        return haystack.includes("does not support")
+            ? CLI_DIAGNOSTIC_CODES.UNSUPPORTED_COMMAND
+            : CLI_DIAGNOSTIC_CODES.INVALID_COMMAND;
+    }
+    if (/Invalid |must start with|cannot hook|cannot nest|cannot use|cannot be|already defines|already exists|Expected one of/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT;
+    }
+    return CLI_DIAGNOSTIC_CODES.COMMAND_EXECUTION;
+}
+/**
+ * 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)]);
+    const code = options.code ??
+        inferCliDiagnosticCode({
+            command: options.command,
+            detailLines,
+            error: options.error,
+        });
+    return new CliDiagnosticError({
+        code,
+        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({
+        code: error.code,
+        command: error.command,
+        detailLines: error.detailLines,
+        summary: error.summary,
+    });
+}
+export function serializeCliDiagnosticError(error) {
+    if (isCliDiagnosticError(error)) {
+        return {
+            code: error.code,
+            command: error.command,
+            detailLines: [...error.detailLines],
+            kind: "command-execution",
+            message: formatCliDiagnosticBlock({
+                code: error.code,
+                command: error.command,
+                detailLines: error.detailLines,
+                summary: error.summary,
+            }),
+            name: error.name,
+            summary: error.summary,
+            tag: "CommandExecutionError",
+        };
+    }
+    return {
+        code: inferCliDiagnosticCode({
+            command: "unknown",
+            detailLines: [],
+            error,
+        }),
+        kind: "command-execution",
+        message: getErrorMessage(error),
+        name: error instanceof Error ? error.name : "Error",
+        tag: "CommandExecutionError",
+    };
+}
+/**
+ * Format one human-readable doctor check row.
+ */
+export function formatDoctorCheckLine(check) {
+    const statusLabel = check.status === "pass" ? "PASS" : check.status === "warn" ? "WARN" : "FAIL";
+    return formatWrappedPrefixedLine(`${statusLabel} ${check.label}: `, check.detail, resolveCliWrapColumns(process.stdout.columns)).join("\n");
+}
+/**
+ * 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, options = {}) {
+    const failedChecks = getFailingDoctorChecks(checks);
+    const exitFailureChecks = options.exitFailureChecks ?? failedChecks;
+    const advisoryFailureCount = failedChecks.length - exitFailureChecks.length;
+    const warningCount = checks.filter((check) => check.status === "warn").length;
+    const summaryStatus = exitFailureChecks.length > 0
+        ? "FAIL"
+        : advisoryFailureCount > 0 || warningCount > 0
+            ? "WARN"
+            : "PASS";
+    return formatWrappedPrefixedLine(`${summaryStatus} wp-typia doctor summary: `, [
+        `${checks.length - failedChecks.length - warningCount}/${checks.length} checks passed`,
+        advisoryFailureCount > 0 ? `${advisoryFailureCount} advisory failure(s)` : null,
+        warningCount > 0 ? `${warningCount} warning(s)` : null,
+    ]
+        .filter((detail) => detail !== null)
+        .join(", "), resolveCliWrapColumns(process.stdout.columns)).join("\n");
+}
+/**
+ * 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/cli-help.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Return the canonical CLI usage text for `wp-typia`.
+ *
+ * The rendered help includes the current built-in template ids and supported
+ * package manager ids from the runtime registry.
+ *
+ * @returns Human-readable help text for CLI usage output.
+ */
+export declare function formatHelpText(): string;

package/dist/runtime/cli/cli-help.js

@@ -0,0 +1,84 @@
+import { PACKAGE_MANAGER_IDS } from "../shared/package-managers.js";
+import { TEMPLATE_IDS } from "../templates/template-registry.js";
+/**
+ * Return the canonical CLI usage text for `wp-typia`.
+ *
+ * The rendered help includes the current built-in template ids and supported
+ * package manager ids from the runtime registry.
+ *
+ * @returns Human-readable help text for CLI usage output.
+ */
+export function formatHelpText() {
+    return `Usage:
+  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] [--dry-run] [--no-install] [--package-manager <id>]
+  wp-typia create <project-dir> [--template workspace] [--profile <plugin-qa>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
+  wp-typia create <project-dir> [--template query-loop] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--query-post-type <post-type>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--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] [--dry-run] [--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] [--dry-run] [--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>] [--alternate-render-targets <email,mjml,plain-text>] [--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] [--dry-run] [--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>] [--inner-blocks-preset <freeform|ordered|horizontal|locked-structure>] [--alternate-render-targets <email,mjml,plain-text>] [--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] [--dry-run] [--no-install] [--package-manager <id>]
+  wp-typia <project-dir> [create flags...]
+  wp-typia init [project-dir] [--apply] [--package-manager <id>]
+  wp-typia add admin-view <name> [--source <rest-resource:slug|core-data:kind/name>]
+  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>] [--inner-blocks-preset <freeform|ordered|horizontal|locked-structure>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>]
+  wp-typia add integration-env <name> [--wp-env] [--release-zip] [--service <none|docker-compose>]
+  wp-typia add core-variation <block-name> <name>
+  wp-typia add core-variation <name> --block <namespace/block>
+  wp-typia add variation <name> --block <block-slug>
+  wp-typia add style <name> --block <block-slug>
+  wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug>
+  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--catalog-title <title>] [--tags <tag,...>] [--tag <tag>...] [--thumbnail-url <url>]
+  wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>] [--from-post-meta|--post-meta <post-meta> [--meta-path <field>]]
+  wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <method[,method...]>]
+  wp-typia add rest-resource <name> --manual [--namespace <vendor/v1>] [--method <GET|POST|PUT|PATCH|DELETE>] [--auth <public|authenticated|public-write-protected>] [--path <route-pattern>|--route-pattern <route-pattern>] [--permission-callback <callback>] [--controller-class <ClassName>] [--controller-extends <BaseClass>] [--query-type <Type>] [--body-type <Type>] [--response-type <Type>] [--secret-field <field>] [--secret-state-field|--secret-has-value-field <field>] [--secret-preserve-on-empty <true|false>]
+  wp-typia add post-meta <name> --post-type <post-type> [--type <ExportedTypeName>] [--meta-key <meta-key>] [--hide-from-rest]
+  wp-typia add ability <name>
+  wp-typia add ai-feature <name> [--namespace <vendor/v1>]
+  wp-typia add editor-plugin <name> [--slot <sidebar|document-setting-panel>]
+  wp-typia add hooked-block <block-slug> --anchor <anchor-block-name> --position <before|after|firstChild|lastChild>
+  wp-typia migrate <init|snapshot|diff|scaffold|verify|doctor|fixtures|fuzz> [...]
+  wp-typia templates list
+  wp-typia templates inspect <id>
+  wp-typia doctor
+  wp-typia mcp <list|sync>
+  wp-typia skills <list|sync>
+  wp-typia completions <bash|zsh|fish|powershell>
+
+Built-in templates: ${TEMPLATE_IDS.join(", ")}
+Package managers: ${PACKAGE_MANAGER_IDS.join(", ")}
+Output environment:
+  WP_TYPIA_ASCII=1 forces ASCII status markers; WP_TYPIA_ASCII=0 opts back into Unicode markers even when NO_COLOR is set.
+  A non-empty NO_COLOR requests ASCII-safe markers such as [ok], [dry-run], [!], and [...] when WP_TYPIA_ASCII is not set.
+Notes:
+  \`wp-typia create\` is the canonical scaffold command.
+  \`wp-typia <project-dir>\` remains a backward-compatible alias to \`create\` when \`<project-dir>\` is the only positional argument.
+  \`wp-typia init\` previews the minimum retrofit sync surface by default; rerun with \`--apply\` to write package.json updates and generated helper scripts.
+  Use \`--template workspace\` as shorthand for \`@wp-typia/create-workspace-template\`, the official empty workspace scaffold behind \`wp-typia add ...\`.
+  Use \`--profile plugin-qa\` with \`--template workspace\` when a plugin needs local wp-env smoke checks, \`.env.example\`, and release zip scripts from day one; omit it for the minimal workspace shell.
+  Interactive add flows let you choose a template when \`--template\` is omitted; non-interactive runs default to \`basic\`.
+  Unknown \`core/*\` targets for \`add core-variation\` warn instead of failing so newer WordPress core blocks remain scaffoldable; third-party namespaces are allowed without local discovery.
+  \`add admin-view\` scaffolds an opt-in DataViews-powered WordPress admin screen under \`src/admin-views/\`.
+  Pass \`--source rest-resource:<slug>\` to reuse a list-capable REST resource.
+  Pass \`--source core-data:postType/post\` or \`--source core-data:taxonomy/category\` to bind a WordPress-owned entity collection.
+  Generated admin-view workspaces add \`@wp-typia/dataviews\` and the needed WordPress DataViews packages as opt-in dependencies.
+  \`add integration-env\` generates an opt-in local smoke starter under \`scripts/integration-smoke/\`, updates \`.env.example\`, and can add \`@wordpress/env\` plus \`.wp-env.json\` when \`--wp-env\` is passed.
+  Pass \`--release-zip\` to add \`release:zip\`, \`release:zip:check\`, and \`qa:check\` scripts for plugin QA packaging.
+  Pass \`--service docker-compose\` to include a placeholder local service stack that can be adapted to project-specific dependencies.
+  \`query-loop\` is create-only. Use \`wp-typia create <project-dir> --template query-loop\`; \`wp-typia add block\` accepts only basic, interactivity, persistence, and compound families.
+  \`add variation\` uses an existing workspace block from \`scripts/block-config.ts\`.
+  \`add style\` registers a Block Styles option for an existing generated block.
+  \`add transform\` adds a block-to-block transform into an existing generated block.
+  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\`; pass \`--catalog-title "Hero Photo"\` to override the generated catalog title, pass \`--tags hero,landing\` for a comma-separated tag list, and repeat \`--tag hero --tag landing\` for single tag values.
+  \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`; pass \`--block\` and \`--attribute\` together to declare a bindable generated-block attribute. Pass \`--from-post-meta\` or \`--post-meta\` to back the source from a typed post-meta contract and \`--meta-path\` to choose its default top-level field.
+  \`add rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`.
+  \`add rest-resource --manual\` tracks an external/provider REST route with typed schemas, OpenAPI, clients, and drift checks without generating PHP route/controller files while still allowing route-owner metadata such as permission callbacks and controller classes. Settings contracts can add \`--secret-field\` plus \`--secret-preserve-on-empty\` to model write-only credentials and preserve blank submissions.
+  \`add post-meta\` scaffolds typed post meta contracts under \`src/post-meta/\`, emits schema artifacts, and wires generated \`register_post_meta()\` helpers under \`inc/post-meta/\`.
+  \`add ability\` scaffolds typed workflow abilities under \`src/abilities/\` and server registration under \`inc/abilities/\`.
+  \`add ai-feature\` scaffolds server-owned AI feature endpoints under \`src/ai-features/\` and PHP route glue under \`inc/ai-features/\`.
+  \`add editor-plugin\` scaffolds a document-level editor extension under \`src/editor-plugins/\`; legacy aliases \`PluginSidebar\` and \`PluginDocumentSettingPanel\` resolve to \`sidebar\` and \`document-setting-panel\`.
+  \`add hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.
+  \`wp-typia doctor\` always checks environment readiness and reports when it only ran environment-level diagnostics; official workspace roots also get inventory, source-tree drift, shared convention checks, and iframe/API v3 compatibility checks.
+  \`wp-typia init\` previews or applies the minimum sync/doctor/migration adoption layer for supported existing layouts; pass \`--package-manager <id>\` to pin emitted scripts and next steps.
+  \`wp-typia migrate doctor --all\` checks migration target alignment, snapshots, fixtures, and generated migration artifacts.
+  \`migrate\` is the canonical migration command; \`migrations\` is no longer supported.`;
+}