@wp-typia/project-tools 0.20.2 → 0.21.0

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

@@ -8,6 +8,7 @@
  * Import `formatAddHelpText`, `runAddBlockCommand`,
  * `runAddVariationCommand`, `runAddPatternCommand`,
  * `runAddBindingSourceCommand`, `runAddHookedBlockCommand`,
+ * `runAddAdminViewCommand` for DataViews-backed admin screen scaffolds,
  * `runAddAbilityCommand` for typed workflow ability scaffolds,
  * and `HOOKED_BLOCK_POSITION_IDS`,
  * `getWorkspaceBlockSelectOptions`, and `seedWorkspaceMigrationProject` for
@@ -15,8 +16,10 @@
  * `runAddAiFeatureCommand` for server-owned WordPress AI feature scaffolds,
  * `runAddRestResourceCommand` for plugin-level REST resource scaffolds,
  * `getDoctorChecks`, `runDoctor`, and `DoctorCheck` for diagnostics,
- * `createCliCommandError` and `formatCliDiagnosticError` for shared
- * non-interactive failure rendering,
+ * `createCliCommandError`, `createCliDiagnosticCodeError`,
+ * `CLI_DIAGNOSTIC_CODES`, `CLI_DIAGNOSTIC_CODE_METADATA`,
+ * `getCliDiagnosticCodeMetadata`, and `formatCliDiagnosticError` for shared
+ * non-interactive failure rendering and explicit diagnostic-code ownership,
  * `formatHelpText` for top-level CLI usage output, scaffold helpers such as
  * `createReadlinePrompt`, `getNextSteps`, `getOptionalOnboarding`,
  * `runScaffoldFlow`, and `ReadlinePrompt` for interactive project creation,
@@ -26,9 +29,9 @@
  * template inspection flows.
  */
 export { getDoctorChecks, runDoctor, type DoctorCheck } from "./cli-doctor.js";
-export { createCliCommandError, CliDiagnosticError, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
-export type { CliDiagnosticMessage } from "./cli-diagnostics.js";
-export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
+export { createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODE_METADATA, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getCliDiagnosticCodeMetadata, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
+export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, } from "./cli-diagnostics.js";
+export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
 export { COMPOUND_INNER_BLOCKS_PRESET_IDS, getCompoundInnerBlocksPresetDefinition, } from "./compound-inner-blocks.js";
 export type { CompoundInnerBlocksPresetId } from "./compound-inner-blocks.js";
 export { HOOKED_BLOCK_POSITION_IDS } from "./hooked-blocks.js";

package/dist/runtime/cli-core.js

@@ -8,6 +8,7 @@
  * Import `formatAddHelpText`, `runAddBlockCommand`,
  * `runAddVariationCommand`, `runAddPatternCommand`,
  * `runAddBindingSourceCommand`, `runAddHookedBlockCommand`,
+ * `runAddAdminViewCommand` for DataViews-backed admin screen scaffolds,
  * `runAddAbilityCommand` for typed workflow ability scaffolds,
  * and `HOOKED_BLOCK_POSITION_IDS`,
  * `getWorkspaceBlockSelectOptions`, and `seedWorkspaceMigrationProject` for
@@ -15,8 +16,10 @@
  * `runAddAiFeatureCommand` for server-owned WordPress AI feature scaffolds,
  * `runAddRestResourceCommand` for plugin-level REST resource scaffolds,
  * `getDoctorChecks`, `runDoctor`, and `DoctorCheck` for diagnostics,
- * `createCliCommandError` and `formatCliDiagnosticError` for shared
- * non-interactive failure rendering,
+ * `createCliCommandError`, `createCliDiagnosticCodeError`,
+ * `CLI_DIAGNOSTIC_CODES`, `CLI_DIAGNOSTIC_CODE_METADATA`,
+ * `getCliDiagnosticCodeMetadata`, and `formatCliDiagnosticError` for shared
+ * non-interactive failure rendering and explicit diagnostic-code ownership,
  * `formatHelpText` for top-level CLI usage output, scaffold helpers such as
  * `createReadlinePrompt`, `getNextSteps`, `getOptionalOnboarding`,
  * `runScaffoldFlow`, and `ReadlinePrompt` for interactive project creation,
@@ -26,8 +29,8 @@
  * template inspection flows.
  */
 export { getDoctorChecks, runDoctor } from "./cli-doctor.js";
-export { createCliCommandError, CliDiagnosticError, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
-export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
+export { createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODE_METADATA, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getCliDiagnosticCodeMetadata, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
+export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
 export { COMPOUND_INNER_BLOCKS_PRESET_IDS, getCompoundInnerBlocksPresetDefinition, } from "./compound-inner-blocks.js";
 export { HOOKED_BLOCK_POSITION_IDS } from "./hooked-blocks.js";
 export { formatHelpText } from "./cli-help.js";

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

@@ -23,10 +23,80 @@ export declare const CLI_DIAGNOSTIC_CODES: {
     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";
+    status: "pass" | "fail" | "warn";
 };
 /**
  * Structured CLI failure carrying a stable summary/detail layout.
@@ -42,6 +112,18 @@ export declare class CliDiagnosticError extends Error {
  * 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.
  */

package/dist/runtime/cli-diagnostics.js

@@ -13,6 +13,63 @@ export const CLI_DIAGNOSTIC_CODES = {
     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.",
@@ -151,6 +208,24 @@ function readCliDiagnosticCode(error) {
     }
     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;
+}
 function inferCliDiagnosticCode(options) {
     const inheritedCode = readCliDiagnosticCode(options.error);
     if (inheritedCode) {
@@ -269,7 +344,8 @@ export function serializeCliDiagnosticError(error) {
  * Format one human-readable doctor check row.
  */
 export function formatDoctorCheckLine(check) {
-    return formatWrappedPrefixedLine(`${check.status === "pass" ? "PASS" : "FAIL"} ${check.label}: `, check.detail, resolveCliWrapColumns(process.stdout.columns)).join("\n");
+    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.
@@ -282,7 +358,14 @@ export function getFailingDoctorChecks(checks) {
  */
 export function formatDoctorSummaryLine(checks) {
     const failedChecks = getFailingDoctorChecks(checks);
-    return formatWrappedPrefixedLine(`${failedChecks.length === 0 ? "PASS" : "FAIL"} wp-typia doctor summary: `, `${checks.length - failedChecks.length}/${checks.length} checks passed`, resolveCliWrapColumns(process.stdout.columns)).join("\n");
+    const warningCount = checks.filter((check) => check.status === "warn").length;
+    const summaryStatus = failedChecks.length > 0 ? "FAIL" : warningCount > 0 ? "WARN" : "PASS";
+    return formatWrappedPrefixedLine(`${summaryStatus} wp-typia doctor summary: `, [
+        `${checks.length - failedChecks.length - warningCount}/${checks.length} checks passed`,
+        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