@wp-typia/project-tools 0.16.12 → 0.16.14

package/dist/runtime/block-generator-service.js

@@ -1,389 +1,2 @@
-import { getPackageVersions } from "./package-versions.js";
-import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, } from "./template-defaults.js";
-import { getTemplateById, } from "./template-registry.js";
-import { resolveBuiltInTemplateSource } from "./template-builtins.js";
-import { toPascalCase, toSnakeCase, } from "./string-case.js";
-import { applyBuiltInScaffoldProjectFiles, buildGitignore, buildReadme, } from "./scaffold-apply-utils.js";
-import { buildBlockCssClassName, buildFrontendCssClassName, resolveScaffoldIdentifiers, } from "./scaffold-identifiers.js";
-import { buildBuiltInBlockArtifacts, } from "./built-in-block-artifacts.js";
-import { buildBuiltInCodeArtifacts, } from "./built-in-block-code-artifacts.js";
-import { stableJsonStringify } from "./object-utils.js";
-import { getStarterManifestFiles } from "./starter-manifests.js";
-import { resolveTemplateSeed, parseTemplateLocator } from "./template-source.js";
-import { assertExternalTemplateLayersDoNotWriteProtectedOutputs, resolveExternalTemplateLayers, } from "./template-layers.js";
-import { getBuiltInTemplateOverlayDir, getBuiltInTemplateSharedLayerDirs, resolveBuiltInTemplateSourceFromLayerDirs, } from "./template-builtins.js";
-const renderedArtifactCache = new WeakMap();
-function createVariablesFingerprint(variables) {
-    return stableJsonStringify(variables);
-}
-function buildProtectedTemplateOutputPaths({ codeArtifacts, spec, variables, artifacts, }) {
-    const protectedOutputs = new Set([
-        ".gitignore",
-        "package.json",
-        "scripts/add-compound-child.ts",
-        "scripts/block-config.ts",
-        "scripts/sync-project.ts",
-        "scripts/sync-rest-contracts.ts",
-        "scripts/sync-types-to-block-json.ts",
-        "tsconfig.json",
-        "webpack.config.js",
-        `${variables.slugKebabCase}.php`,
-    ]);
-    for (const artifact of codeArtifacts) {
-        protectedOutputs.add(artifact.relativePath);
-    }
-    for (const artifact of artifacts) {
-        protectedOutputs.add(`${artifact.relativeDir}/block.json`);
-        protectedOutputs.add(`${artifact.relativeDir}/types.ts`);
-    }
-    for (const manifest of getStarterManifestFiles(spec.template.family, variables)) {
-        protectedOutputs.add(manifest.relativePath);
-    }
-    return protectedOutputs;
-}
-function buildCombinedTemplateLayerDirs({ baseLayerDirs, externalEntries, templateId, }) {
-    const orderedLayerDirs = [];
-    const seenLayerDirs = new Set();
-    for (const layerDir of baseLayerDirs) {
-        if (seenLayerDirs.has(layerDir)) {
-            continue;
-        }
-        orderedLayerDirs.push(layerDir);
-        seenLayerDirs.add(layerDir);
-    }
-    for (const entry of externalEntries) {
-        if (seenLayerDirs.has(entry.dir)) {
-            continue;
-        }
-        orderedLayerDirs.push(entry.dir);
-        seenLayerDirs.add(entry.dir);
-    }
-    const overlayDir = getBuiltInTemplateOverlayDir(templateId);
-    if (!seenLayerDirs.has(overlayDir)) {
-        orderedLayerDirs.push(overlayDir);
-    }
-    return orderedLayerDirs;
-}
-function getBuiltInPersistenceSpec({ templateId, dataStorageMode, persistencePolicy, }) {
-    if (templateId === "persistence") {
-        return {
-            dataStorageMode: dataStorageMode ?? "custom-table",
-            enabled: true,
-            persistencePolicy: persistencePolicy ?? "authenticated",
-            scope: "single",
-        };
-    }
-    if (templateId === "compound" && (dataStorageMode || persistencePolicy)) {
-        return {
-            dataStorageMode: dataStorageMode ?? "custom-table",
-            enabled: true,
-            persistencePolicy: persistencePolicy ?? "authenticated",
-            scope: "compound-parent",
-        };
-    }
-    return {
-        enabled: false,
-    };
-}
-export function createBuiltInBlockSpec({ answers, dataStorageMode, persistencePolicy, templateId, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
-    const template = getTemplateById(templateId);
-    const metadataDefaults = getBuiltInTemplateMetadataDefaults(templateId);
-    const identifiers = resolveScaffoldIdentifiers({
-        namespace: answers.namespace,
-        phpPrefix: answers.phpPrefix,
-        slug: answers.slug,
-        textDomain: answers.textDomain,
-    });
-    const resolvedDataStorageMode = dataStorageMode ?? answers.dataStorageMode;
-    const resolvedPersistencePolicy = persistencePolicy ?? answers.persistencePolicy;
-    return {
-        block: identifiers,
-        metadata: {
-            category: metadataDefaults.category,
-            description: answers.description.trim(),
-            icon: metadataDefaults.icon,
-            keyword: identifiers.slug.replace(/-/g, " "),
-            title: answers.title.trim(),
-        },
-        persistence: getBuiltInPersistenceSpec({
-            dataStorageMode: resolvedDataStorageMode,
-            persistencePolicy: resolvedPersistencePolicy,
-            templateId,
-        }),
-        project: {
-            author: answers.author.trim(),
-        },
-        runtime: {
-            withMigrationUi,
-            withTestPreset,
-            withWpEnv,
-        },
-        template: {
-            description: template.description,
-            family: templateId,
-            features: [...template.features],
-        },
-    };
-}
-export function buildTemplateVariablesFromBlockSpec(spec) {
-    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = getPackageVersions();
-    const slug = spec.block.slug;
-    const slugSnakeCase = toSnakeCase(slug);
-    const pascalCase = toPascalCase(slug);
-    const title = spec.metadata.title;
-    const namespace = spec.block.namespace;
-    const textDomain = spec.block.textDomain;
-    const phpPrefix = spec.block.phpPrefix;
-    const phpPrefixUpper = phpPrefix.toUpperCase();
-    const compoundChildTitle = `${title} Item`;
-    const cssClassName = buildBlockCssClassName(namespace, slug);
-    const compoundChildCssClassName = buildBlockCssClassName(namespace, `${slug}-item`);
-    const persistenceEnabled = spec.persistence.enabled;
-    const dataStorageMode = persistenceEnabled ? spec.persistence.dataStorageMode : "custom-table";
-    const persistencePolicy = persistenceEnabled
-        ? spec.persistence.persistencePolicy
-        : "authenticated";
-    return {
-        apiClientPackageVersion,
-        author: spec.project.author,
-        blockRuntimePackageVersion,
-        blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
-        blockTypesPackageVersion,
-        category: spec.metadata.category,
-        icon: spec.metadata.icon,
-        compoundChildTitle,
-        compoundChildCategory: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.category,
-        compoundChildCssClassName,
-        compoundChildIcon: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.icon,
-        compoundChildTitleJson: JSON.stringify(compoundChildTitle),
-        compoundPersistenceEnabled: spec.template.family === "compound" && persistenceEnabled ? "true" : "false",
-        projectToolsPackageVersion,
-        cssClassName,
-        dashCase: slug,
-        dataStorageMode,
-        description: spec.metadata.description,
-        frontendCssClassName: buildFrontendCssClassName(cssClassName),
-        isAuthenticatedPersistencePolicy: persistencePolicy === "authenticated" ? "true" : "false",
-        isPublicPersistencePolicy: persistencePolicy === "public" ? "true" : "false",
-        bootstrapCredentialDeclarations: persistencePolicy === "public"
-            ? "publicWriteExpiresAt?: number & tags.Type< 'uint32' >;\n\tpublicWriteToken?: string & tags.MinLength< 1 > & tags.MaxLength< 512 >;"
-            : "restNonce?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
-        persistencePolicyDescriptionJson: JSON.stringify(persistencePolicy === "authenticated"
-            ? "Writes require a logged-in user and a valid REST nonce."
-            : "Anonymous writes use signed short-lived public tokens, per-request ids, and coarse rate limiting."),
-        keyword: spec.metadata.keyword,
-        namespace,
-        needsMigration: "{{needsMigration}}",
-        pascalCase,
-        phpPrefix,
-        phpPrefixUpper,
-        restPackageVersion,
-        publicWriteRequestIdDeclaration: persistencePolicy === "public"
-            ? "publicWriteRequestId: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;"
-            : "publicWriteRequestId?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
-        restWriteAuthIntent: persistencePolicy === "public"
-            ? "public-write-protected"
-            : "authenticated",
-        restWriteAuthMechanism: persistencePolicy === "public" ? "public-signed-token" : "rest-nonce",
-        restWriteAuthMode: persistencePolicy === "public" ? "public-signed-token" : "authenticated-rest-nonce",
-        slug,
-        slugCamelCase: pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1),
-        slugKebabCase: slug,
-        slugSnakeCase,
-        textDomain,
-        textdomain: textDomain,
-        title,
-        titleJson: JSON.stringify(title),
-        titleCase: pascalCase,
-        persistencePolicy,
-    };
-}
-export class BlockGeneratorService {
-    async plan({ allowExistingDir = false, answers, cwd = process.cwd(), dataStorageMode, externalLayerId, externalLayerSource, externalLayerSourceLabel, noInstall = false, packageManager, persistencePolicy, projectDir, repositoryReference, templateId, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
-        return {
-            spec: createBuiltInBlockSpec({
-                answers,
-                dataStorageMode,
-                persistencePolicy,
-                templateId,
-                withMigrationUi,
-                withTestPreset,
-                withWpEnv,
-            }),
-            target: {
-                allowExistingDir,
-                cwd,
-                externalLayerId,
-                externalLayerSource,
-                externalLayerSourceLabel,
-                noInstall,
-                packageManager,
-                projectDir,
-                repositoryReference,
-                variant,
-            },
-        };
-    }
-    async validate({ plan }) {
-        if (plan.target.externalLayerId && !plan.target.externalLayerSource) {
-            throw new Error("externalLayerId requires externalLayerSource when composing built-in template layers.");
-        }
-        if (plan.target.variant) {
-            throw new Error(`--variant is only supported for official external template configs. Received variant "${plan.target.variant}" for built-in template "${plan.spec.template.family}".`);
-        }
-        return plan;
-    }
-    async render({ validated }) {
-        const variables = buildTemplateVariablesFromBlockSpec(validated.spec);
-        const persistenceEnabled = validated.spec.persistence.enabled;
-        const artifacts = buildBuiltInBlockArtifacts({
-            templateId: validated.spec.template.family,
-            variables,
-        });
-        const codeArtifacts = buildBuiltInCodeArtifacts({
-            templateId: validated.spec.template.family,
-            variables,
-        });
-        const templateVariantOptions = {
-            persistenceEnabled,
-            persistencePolicy: validated.spec.persistence.enabled &&
-                validated.spec.persistence.persistencePolicy === "public"
-                ? "public"
-                : "authenticated",
-        };
-        let templateSource = await resolveBuiltInTemplateSource(validated.spec.template.family, templateVariantOptions);
-        const warnings = [...(templateSource.warnings ?? [])];
-        if (validated.target.externalLayerSource) {
-            let layerSeed;
-            try {
-                layerSeed = await resolveTemplateSeed(parseTemplateLocator(validated.target.externalLayerSource), validated.target.cwd);
-                const resolvedLayers = await resolveExternalTemplateLayers({
-                    externalLayerId: validated.target.externalLayerId,
-                    sourceRoot: layerSeed.rootDir,
-                });
-                const baseLayerDirs = getBuiltInTemplateSharedLayerDirs(validated.spec.template.family, templateVariantOptions);
-                await assertExternalTemplateLayersDoNotWriteProtectedOutputs({
-                    externalEntries: resolvedLayers.entries,
-                    protectedOutputPaths: buildProtectedTemplateOutputPaths({
-                        artifacts,
-                        codeArtifacts,
-                        spec: validated.spec,
-                        variables,
-                    }),
-                    view: variables,
-                });
-                await templateSource.cleanup?.();
-                templateSource = await resolveBuiltInTemplateSourceFromLayerDirs(validated.spec.template.family, buildCombinedTemplateLayerDirs({
-                    baseLayerDirs,
-                    externalEntries: resolvedLayers.entries,
-                    templateId: validated.spec.template.family,
-                }));
-                const layerSourceCleanup = layerSeed.cleanup;
-                const templateCleanup = templateSource.cleanup;
-                templateSource.cleanup = async () => {
-                    const cleanupErrors = [];
-                    try {
-                        await templateCleanup?.();
-                    }
-                    catch (error) {
-                        cleanupErrors.push(error instanceof Error ? error : new Error(String(error)));
-                    }
-                    try {
-                        await layerSourceCleanup?.();
-                    }
-                    catch (error) {
-                        cleanupErrors.push(error instanceof Error ? error : new Error(String(error)));
-                    }
-                    if (cleanupErrors.length > 0) {
-                        throw new Error([
-                            "Failed to cleanup composed template sources.",
-                            ...cleanupErrors.map((error) => `- ${error.message}`),
-                        ].join("\n"));
-                    }
-                };
-                warnings.push(`Applied external layer "${resolvedLayers.selectedLayerId}" from "${validated.target.externalLayerSourceLabel ?? validated.target.externalLayerSource}".`);
-            }
-            catch (error) {
-                await templateSource.cleanup?.();
-                await layerSeed?.cleanup?.();
-                throw error;
-            }
-        }
-        const rendered = {
-            ...validated,
-            cleanup: templateSource.cleanup,
-            gitignoreContent: buildGitignore(),
-            postRender: {
-                applyLocalDevPresets: true,
-                applyMigrationUiCapability: validated.spec.runtime.withMigrationUi,
-                seedPersistenceArtifacts: validated.spec.template.family === "persistence" ||
-                    (validated.spec.template.family === "compound" && persistenceEnabled),
-                seedStarterManifestFiles: true,
-            },
-            readmeContent: buildReadme(validated.spec.template.family, variables, validated.target.packageManager, {
-                withMigrationUi: validated.spec.runtime.withMigrationUi,
-                withTestPreset: validated.spec.runtime.withTestPreset,
-                withWpEnv: validated.spec.runtime.withWpEnv,
-            }),
-            selectedVariant: null,
-            templateDir: templateSource.templateDir,
-            variables,
-            warnings,
-        };
-        renderedArtifactCache.set(rendered, {
-            artifacts,
-            codeArtifacts,
-            variablesFingerprint: createVariablesFingerprint(variables),
-        });
-        return rendered;
-    }
-    async apply({ rendered, installDependencies, }) {
-        const cachedArtifacts = renderedArtifactCache.get(rendered);
-        const currentVariablesFingerprint = createVariablesFingerprint(rendered.variables);
-        const artifacts = cachedArtifacts &&
-            cachedArtifacts.variablesFingerprint === currentVariablesFingerprint
-            ? cachedArtifacts.artifacts
-            : buildBuiltInBlockArtifacts({
-                templateId: rendered.spec.template.family,
-                variables: rendered.variables,
-            });
-        const codeArtifacts = cachedArtifacts &&
-            cachedArtifacts.variablesFingerprint === currentVariablesFingerprint
-            ? cachedArtifacts.codeArtifacts
-            : buildBuiltInCodeArtifacts({
-                templateId: rendered.spec.template.family,
-                variables: rendered.variables,
-            });
-        try {
-            await applyBuiltInScaffoldProjectFiles({
-                allowExistingDir: rendered.target.allowExistingDir,
-                artifacts,
-                codeArtifacts,
-                installDependencies,
-                noInstall: rendered.target.noInstall,
-                packageManager: rendered.target.packageManager,
-                projectDir: rendered.target.projectDir,
-                repositoryReference: rendered.target.repositoryReference,
-                gitignoreContent: rendered.gitignoreContent,
-                readmeContent: rendered.readmeContent,
-                templateDir: rendered.templateDir,
-                templateId: rendered.spec.template.family,
-                variables: rendered.variables,
-                withMigrationUi: rendered.spec.runtime.withMigrationUi,
-                withTestPreset: rendered.spec.runtime.withTestPreset,
-                withWpEnv: rendered.spec.runtime.withWpEnv,
-            });
-        }
-        finally {
-            await rendered.cleanup?.();
-        }
-        return {
-            packageManager: rendered.target.packageManager,
-            projectDir: rendered.target.projectDir,
-            selectedVariant: rendered.selectedVariant,
-            templateId: rendered.spec.template.family,
-            variables: rendered.variables,
-            warnings: rendered.warnings,
-        };
-    }
-}
+export * from "./block-generator-service-spec.js";
+export * from "./block-generator-service-core.js";

package/dist/runtime/cli-diagnostics.js

@@ -4,12 +4,84 @@ const DEFAULT_CLI_FAILURE_SUMMARIES = {
     doctor: "One or more doctor checks failed.",
     migrate: "Unable to complete the requested migration command.",
 };
+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 lines = [`wp-typia ${message.command} failed`, `Summary: ${message.summary}`];
+    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(`- ${detailLine}`);
+            lines.push(...formatWrappedPrefixedLine("- ", detailLine, columns));
         }
     }
     return lines.join("\n");
@@ -77,7 +149,7 @@ export function formatCliDiagnosticError(error) {
  * Format one human-readable doctor check row.
  */
 export function formatDoctorCheckLine(check) {
-    return `${check.status === "pass" ? "PASS" : "FAIL"} ${check.label}: ${check.detail}`;
+    return formatWrappedPrefixedLine(`${check.status === "pass" ? "PASS" : "FAIL"} ${check.label}: `, check.detail, resolveCliWrapColumns(process.stdout.columns)).join("\n");
 }
 /**
  * Return the failing doctor checks from one doctor run.
@@ -90,7 +162,7 @@ export function getFailingDoctorChecks(checks) {
  */
 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`;
+    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");
 }
 /**
  * Build detail lines for doctor failures so the non-interactive formatter can

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

@@ -2,11 +2,15 @@ import type { DoctorCheck } from "./cli-doctor.js";
 /**
  * Collect workspace-scoped doctor checks for the given working directory.
  *
- * When the directory is not an official workspace, the function returns an
- * empty array or a single failing "Workspace package metadata" row describing
- * the reason. When workspace resolution or metadata parsing throws, the
- * corresponding failing row is returned early and the remaining checks are
- * skipped.
+ * When the directory is not an official workspace, the function returns a
+ * "Doctor scope" row explaining that only environment checks ran, plus a
+ * failing workspace metadata row when a nearby candidate workspace is invalid.
+ * When workspace resolution or metadata parsing throws, the corresponding
+ * failing rows are returned early and the remaining checks are skipped.
+ * When an official workspace is detected, a passing "Doctor scope" row is
+ * emitted first so the remaining package metadata, inventory, source-tree
+ * drift, and optional migration hint rows are clearly framed as workspace
+ * diagnostics for that run.
  *
  * @param cwd Working directory expected to host an official workspace.
  * @returns Ordered workspace check rows ready for CLI rendering.

package/dist/runtime/cli-doctor-workspace.js

@@ -19,6 +19,9 @@ const WORKSPACE_GENERATED_BLOCK_ARTIFACTS = [
 function createDoctorCheck(label, status, detail) {
     return { detail, label, status };
 }
+function createDoctorScopeCheck(status, detail) {
+    return createDoctorCheck("Doctor scope", status, detail);
+}
 function getWorkspaceBootstrapRelativePath(packageName) {
     const packageBaseName = packageName.split("/").pop() ?? packageName;
     return `${packageBaseName}.php`;
@@ -207,11 +210,15 @@ function checkMigrationWorkspaceHint(workspace, packageJson) {
 /**
  * Collect workspace-scoped doctor checks for the given working directory.
  *
- * When the directory is not an official workspace, the function returns an
- * empty array or a single failing "Workspace package metadata" row describing
- * the reason. When workspace resolution or metadata parsing throws, the
- * corresponding failing row is returned early and the remaining checks are
- * skipped.
+ * When the directory is not an official workspace, the function returns a
+ * "Doctor scope" row explaining that only environment checks ran, plus a
+ * failing workspace metadata row when a nearby candidate workspace is invalid.
+ * When workspace resolution or metadata parsing throws, the corresponding
+ * failing rows are returned early and the remaining checks are skipped.
+ * When an official workspace is detected, a passing "Doctor scope" row is
+ * emitted first so the remaining package metadata, inventory, source-tree
+ * drift, and optional migration hint rows are clearly framed as workspace
+ * diagnostics for that run.
  *
  * @param cwd Working directory expected to host an official workspace.
  * @returns Ordered workspace check rows ready for CLI rendering.
@@ -225,16 +232,21 @@ export function getWorkspaceDoctorChecks(cwd) {
         workspace = tryResolveWorkspaceProject(cwd);
     }
     catch (error) {
+        checks.push(createDoctorScopeCheck("fail", "Environment checks ran, but workspace discovery could not continue. Fix the nearby workspace package metadata and rerun `wp-typia doctor`."));
         checks.push(createDoctorCheck("Workspace package metadata", "fail", error instanceof Error ? error.message : String(error)));
         return checks;
     }
     if (!workspace) {
         if (invalidWorkspaceReason) {
+            checks.push(createDoctorScopeCheck("fail", "Environment checks ran, but workspace diagnostics could not continue because a nearby wp-typia workspace candidate is invalid. Fix the workspace package metadata and rerun `wp-typia doctor`."));
             checks.push(createDoctorCheck("Workspace package metadata", "fail", invalidWorkspaceReason));
         }
+        else {
+            checks.push(createDoctorScopeCheck("pass", "No official wp-typia workspace root was detected, so this run only covered environment readiness. Re-run `wp-typia doctor` from a workspace root if you expected package metadata, inventory, or generated artifact checks."));
+        }
         return checks;
     }
-    checks.push(createDoctorCheck("Workspace marker", "pass", `Official workspace detected for ${workspace.workspace.namespace}`));
+    checks.push(createDoctorScopeCheck("pass", `Official workspace detected for ${workspace.workspace.namespace}; environment readiness checks ran and workspace-scoped diagnostics are enabled for the package metadata, inventory, source-tree drift, and any configured migration hint rows below.`));
     let workspacePackageJson;
     try {
         workspacePackageJson = parseWorkspacePackageJson(workspace.projectDir);

package/dist/runtime/cli-help.js

@@ -39,7 +39,7 @@ Notes:
   \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.
   \`add hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.
-  \`wp-typia doctor\` checks environment readiness plus workspace inventory and source-tree drift.
+  \`wp-typia doctor\` always checks environment readiness and reports when it only ran environment-level diagnostics; official workspace roots also get inventory and source-tree drift checks.
   \`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.`;
 }