@wp-typia/project-tools 0.23.0 → 0.23.1

package/dist/runtime/json-utils.js

@@ -1,7 +1,81 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
 /**
- * Re-exports JSON cloning helpers from `@wp-typia/block-runtime`.
- * This adapter keeps the existing project-tools module path stable while the
- * runtime implementation now lives in block-runtime.
+ * JSON helpers shared by project-tools runtime modules.
+ *
+ * File-backed runtime JSON readers should use `safeJsonParse`,
+ * `readJsonFileSync`, or `readJsonFile` so malformed JSON reports the file path
+ * and operation context. Raw `JSON.parse` remains intentional for trusted
+ * in-memory clones, subprocess output, test fixtures, generated workspace
+ * script templates that embed their own path-aware parse handling,
+ * package-version manifest cache probes with colocated path-aware wrappers,
+ * and cache/discovery probes that immediately catch malformed documents to
+ * continue with fallback behavior.
+ *
+ * This module keeps `cloneJsonValue` local instead of re-exporting the
+ * block-runtime helper so Bunli CLI bundles that only need project-tools JSON
+ * readers do not need to resolve the block-runtime subpath at runtime.
+ *
  * @module
  */
-export * from "@wp-typia/block-runtime/json-utils";
+/**
+ * Create a deep clone of a JSON-serializable value.
+ *
+ * @remarks
+ * Values that are not JSON-serializable, such as functions, `undefined`,
+ * `BigInt`, class instances, and `Date` objects, are not preserved faithfully.
+ *
+ * @param value JSON-compatible data to clone.
+ * @returns A deep-cloned copy created with `JSON.parse(JSON.stringify(...))`.
+ */
+export function cloneJsonValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function formatJsonParseTarget({ context, filePath }) {
+    const operation = context?.trim() || "JSON";
+    return filePath ? `${operation} at ${filePath}` : operation;
+}
+/**
+ * Parse JSON and include operation/file context when decoding fails.
+ *
+ * @param source Raw JSON source text.
+ * @param options Optional file path and human-readable operation context.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ * @throws {Error} When the source is malformed JSON.
+ */
+export function safeJsonParse(source, options = {}) {
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse ${formatJsonParseTarget(options)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Read and parse a JSON file synchronously with path-aware parse errors.
+ *
+ * @param filePath JSON file path to read.
+ * @param options Optional parse context. `filePath` is always set from the
+ * reader argument.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ */
+export function readJsonFileSync(filePath, options = {}) {
+    return safeJsonParse(fs.readFileSync(filePath, "utf8"), {
+        ...options,
+        filePath,
+    });
+}
+/**
+ * Read and parse a JSON file asynchronously with path-aware parse errors.
+ *
+ * @param filePath JSON file path to read.
+ * @param options Optional parse context. `filePath` is always set from the
+ * reader argument.
+ * @returns Parsed JSON value cast to the caller-specified type.
+ */
+export async function readJsonFile(filePath, options = {}) {
+    return safeJsonParse(await fsp.readFile(filePath, "utf8"), {
+        ...options,
+        filePath,
+    });
+}

package/dist/runtime/local-dev-presets.js

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { formatRunScript, } from "./package-managers.js";
+import { readJsonFile } from "./json-utils.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, SHARED_TEST_PRESET_TEMPLATE_ROOT, SHARED_WP_ENV_PRESET_TEMPLATE_ROOT, } from "./template-registry.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
 function templateHasPersistenceSync(templateId, compoundPersistenceEnabled) {
@@ -54,7 +55,9 @@ function getDevScript(packageManager, compoundPersistenceEnabled, templateId) {
 }
 async function mutatePackageJson(projectDir, mutate) {
     const packageJsonPath = path.join(projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: "local dev package manifest",
+    });
     mutate(packageJson);
     await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
 }

package/dist/runtime/migration-ui-capability.js

@@ -2,6 +2,7 @@ import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { getPackageVersions } from "./package-versions.js";
 import { formatPackageExecCommand } from "./package-managers.js";
+import { readJsonFile } from "./json-utils.js";
 import { seedProjectMigrations } from "./migrations.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
 import { SHARED_MIGRATION_UI_TEMPLATE_ROOT, } from "./template-registry.js";
@@ -10,7 +11,9 @@ const BLOCK_METADATA_IMPORT_LINE = "import metadata from './block-metadata';";
 const LEGACY_BLOCK_JSON_IMPORT_LINE = "import metadata from './block.json';";
 async function mutatePackageJson(projectDir, mutate) {
     const packageJsonPath = path.join(projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: "migration UI package manifest",
+    });
     mutate(packageJson);
     await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
 }

package/dist/runtime/migration-utils.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { formatRunScript, inferPackageManagerId, parsePackageManagerField, } from './package-managers.js';
 import { isPlainObject } from './object-utils.js';
+import { readJsonFileSync } from './json-utils.js';
 export { cloneJsonValue } from './json-utils.js';
 const MIGRATION_VERSION_LABEL_PATTERN = /^v([1-9]\d*)$/;
 const LEGACY_SEMVER_MIGRATION_VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
@@ -66,7 +67,9 @@ export function createTransformFixtureValue(attribute, pathLabel) {
     }
 }
 export function readJson(filePath) {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return readJsonFileSync(filePath, {
+        context: 'migration JSON file',
+    });
 }
 export function renderPhpValue(value, indentLevel) {
     const indent = '\t'.repeat(indentLevel);

package/dist/runtime/package-managers.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { readJsonFileSync } from "./json-utils.js";
 const PACKAGE_MANAGER_DATA = [
     {
         id: "bun",
@@ -73,12 +74,16 @@ function readPackageManagerField(projectDir) {
         if (!fs.existsSync(packageJsonPath)) {
             return undefined;
         }
-        const manifest = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        const manifest = readJsonFileSync(packageJsonPath, {
+            context: "package manager manifest",
+        });
         return typeof manifest.packageManager === "string"
             ? manifest.packageManager
             : undefined;
     }
     catch {
+        // Package manager inference intentionally falls back to lockfile signals
+        // when package.json is absent or malformed.
         return undefined;
     }
 }

package/dist/runtime/package-versions.js

@@ -92,7 +92,12 @@ function readPackageManifest(location) {
     if (!location.packageJsonPath || location.source === null) {
         return null;
     }
-    return JSON.parse(location.source);
+    try {
+        return JSON.parse(location.source);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse package version manifest at ${location.packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 function tryReadPackageManifest(location) {
     if (!location) {

package/dist/runtime/scaffold-bootstrap.js

@@ -9,6 +9,7 @@ import { getStarterManifestFiles, stringifyStarterManifest } from "./starter-man
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, } from "./template-registry.js";
 import { getScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
 import { pathExists } from "./fs-async.js";
+import { readJsonFile, readJsonFileSync } from "./json-utils.js";
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 /**
  * Ensures the scaffold target directory exists and is empty unless explicitly allowed.
@@ -32,7 +33,9 @@ function readGeneratedPackageJson(projectDir) {
     if (!fs.existsSync(packageJsonPath)) {
         return null;
     }
-    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return readJsonFileSync(packageJsonPath, {
+        context: "generated package manifest",
+    });
 }
 /**
  * Format the actionable error message used when a scaffold target directory
@@ -125,7 +128,9 @@ export function isOfficialWorkspaceProject(projectDir) {
  */
 export async function applyWorkspaceMigrationCapability(projectDir, packageManager) {
     const packageJsonPath = path.join(projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: "workspace package manifest",
+    });
     const wpTypiaPackageVersion = getPackageVersions().wpTypiaPackageVersion;
     const canonicalCliSpecifier = wpTypiaPackageVersion === "^0.0.0"
         ? "wp-typia"

package/dist/runtime/scaffold-package-manager-files.js

@@ -3,6 +3,7 @@ import { execSync } from "node:child_process";
 import path from "node:path";
 import { formatInstallCommand, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
 import { readOptionalUtf8File } from "./fs-async.js";
+import { safeJsonParse } from "./json-utils.js";
 const LOCKFILES = {
     bun: ["bun.lock", "bun.lockb"],
     npm: ["package-lock.json"],
@@ -38,7 +39,10 @@ export async function normalizePackageJson(targetDir, packageManagerId) {
         return;
     }
     const packageManager = getPackageManager(packageManagerId);
-    const packageJson = JSON.parse(packageJsonSource);
+    const packageJson = safeJsonParse(packageJsonSource, {
+        context: "generated package manifest",
+        filePath: packageJsonPath,
+    });
     if (packageManagerId === "npm") {
         delete packageJson.packageManager;
     }

package/dist/runtime/scaffold-repository-reference.js

@@ -1,7 +1,7 @@
-import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { getOptionalNodeErrorCode } from "./fs-async.js";
+import { readJsonFileSync } from "./json-utils.js";
 import { PROJECT_TOOLS_PACKAGE_ROOT } from "./template-registry.js";
 const require = createRequire(import.meta.url);
 /**
@@ -11,7 +11,9 @@ const require = createRequire(import.meta.url);
 export const DEFAULT_SCAFFOLD_REPOSITORY_REFERENCE = "imjlk/wp-typia";
 function readRepositoryPackageManifest(packageJsonPath) {
     try {
-        return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        return readJsonFileSync(packageJsonPath, {
+            context: "repository package manifest",
+        });
     }
     catch (error) {
         if (getOptionalNodeErrorCode(error) === "ENOENT") {

package/dist/runtime/scaffold-template-variables.js

@@ -23,7 +23,7 @@ export function getTemplateVariables(templateId, answers) {
             templateId,
         }));
     }
-    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = getPackageVersions();
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, wpTypiaPackageVersion, } = getPackageVersions();
     const template = isBuiltInTemplateId(templateId) ? getTemplateById(templateId) : null;
     const metadataDefaults = isBuiltInTemplateId(templateId)
         ? getBuiltInTemplateMetadataDefaults(templateId)
@@ -94,6 +94,7 @@ export function getTemplateVariables(templateId, answers) {
         hasAlternatePlainTextRenderTarget: 'false',
         hasAlternateRenderTargets: 'false',
         projectToolsPackageVersion,
+        wpTypiaPackageVersion,
         requiresAtLeast: compatibility.pluginHeader.requiresAtLeast,
         requiresPhp: compatibility.pluginHeader.requiresPhp,
         cssClassName,

package/dist/runtime/scaffold.d.ts

@@ -27,6 +27,10 @@ export declare const DATA_STORAGE_MODES: readonly ["post-meta", "custom-table"];
 export type DataStorageMode = (typeof DATA_STORAGE_MODES)[number];
 export declare const PERSISTENCE_POLICIES: readonly ["authenticated", "public"];
 export type PersistencePolicy = (typeof PERSISTENCE_POLICIES)[number];
+/** Supported create profile ids for opt-in workspace scaffold presets. */
+export declare const CREATE_PROFILE_IDS: readonly ["plugin-qa"];
+/** Union of supported `wp-typia create --profile` id strings. */
+export type CreateProfileId = (typeof CREATE_PROFILE_IDS)[number];
 /**
  * Normalized template variables shared by built-in and remote scaffold flows.
  */
@@ -58,6 +62,7 @@ export interface FlatScaffoldTemplateVariables extends Record<string, string> {
     hasAlternatePlainTextRenderTarget: "false" | "true";
     hasAlternateRenderTargets: "false" | "true";
     projectToolsPackageVersion: string;
+    wpTypiaPackageVersion: string;
     requiresAtLeast: string;
     requiresPhp: string;
     cssClassName: string;
@@ -163,6 +168,7 @@ interface ScaffoldProjectOptions {
     onProgress?: ((event: ScaffoldProgressEvent) => void | Promise<void>) | undefined;
     packageManager: PackageManagerId;
     persistencePolicy?: PersistencePolicy;
+    profile?: CreateProfileId;
     projectDir: string;
     repositoryReference?: string;
     templateId: string;
@@ -185,4 +191,15 @@ export { getTemplateVariables } from "./scaffold-template-variables.js";
 export { getScaffoldTemplateVariableGroups, type BasicScaffoldTemplateVariableGroups, type CompoundScaffoldTemplateVariableGroups, type ExternalScaffoldTemplateVariableGroups, type InteractivityScaffoldTemplateVariableGroups, type PersistenceScaffoldTemplateVariableGroups, type QueryLoopScaffoldTemplateVariableGroups, type ScaffoldTemplateFamily, type ScaffoldTemplateVariableGroups, type ScaffoldTemplateVariableGroupsCarrier, } from "./scaffold-template-variable-groups.js";
 export declare function isDataStorageMode(value: string): value is DataStorageMode;
 export declare function isPersistencePolicy(value: string): value is PersistencePolicy;
-export declare function scaffoldProject({ projectDir, templateId, answers, alternateRenderTargets, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd, allowExistingDir, noInstall, installDependencies, onProgress, variant, withMigrationUi, withTestPreset, withWpEnv, }: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;
+/**
+ * Return whether a raw string is a supported create profile id.
+ */
+export declare function isCreateProfileId(value: string): value is CreateProfileId;
+/**
+ * Resolve an optional create profile flag into a validated profile id.
+ *
+ * Empty input disables profile application; unknown ids throw with the allowed
+ * profile list for CLI diagnostics.
+ */
+export declare function resolveCreateProfileId(profile?: string): CreateProfileId | undefined;
+export declare function scaffoldProject({ projectDir, templateId, answers, alternateRenderTargets, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, profile, repositoryReference, cwd, allowExistingDir, noInstall, installDependencies, onProgress, variant, withMigrationUi, withTestPreset, withWpEnv, }: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;

package/dist/runtime/scaffold.js

@@ -3,11 +3,12 @@ import path from "node:path";
 import { getPackageManager } from "./package-managers.js";
 import { buildGitignore, buildReadme, mergeTextLines, removeQueryLoopPlaceholderFiles, replaceTextRecursively, } from "./scaffold-apply-utils.js";
 import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, } from "./local-dev-presets.js";
+import { runAddIntegrationEnvCommand } from "./cli-add-workspace-integration-env.js";
 import { applyMigrationUiCapability } from "./migration-ui-capability.js";
 import { applyWorkspaceMigrationCapability, ensureScaffoldDirectory, isWorkspaceProject, seedBuiltInPersistenceArtifacts, writeStarterManifestFiles, } from "./scaffold-bootstrap.js";
 import { defaultInstallDependencies, normalizePackageJson, normalizePackageManagerFiles, removeUnexpectedLockfiles, } from "./scaffold-package-manager-files.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { isBuiltInTemplateId, normalizeTemplateLookupId, } from "./template-registry.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, normalizeTemplateLookupId, } from "./template-registry.js";
 import { resolveTemplateSource } from "./template-source.js";
 import { BlockGeneratorService, } from "./block-generator-service.js";
 import { getTemplateVariables } from "./scaffold-template-variables.js";
@@ -16,6 +17,8 @@ import { assertExternalLayerCompositionOptions, } from "./cli-validation.js";
 import { pathExists } from "./fs-async.js";
 export const DATA_STORAGE_MODES = ["post-meta", "custom-table"];
 export const PERSISTENCE_POLICIES = ["authenticated", "public"];
+/** Supported create profile ids for opt-in workspace scaffold presets. */
+export const CREATE_PROFILE_IDS = ["plugin-qa"];
 export { buildBlockCssClassName } from "./scaffold-identifiers.js";
 export { collectScaffoldAnswers, detectAuthor, getDefaultAnswers, resolvePackageManagerId, resolveTemplateId, } from "./scaffold-answer-resolution.js";
 export { getTemplateVariables } from "./scaffold-template-variables.js";
@@ -26,16 +29,62 @@ export function isDataStorageMode(value) {
 export function isPersistencePolicy(value) {
     return PERSISTENCE_POLICIES.includes(value);
 }
+/**
+ * Return whether a raw string is a supported create profile id.
+ */
+export function isCreateProfileId(value) {
+    return CREATE_PROFILE_IDS.includes(value);
+}
+/**
+ * Resolve an optional create profile flag into a validated profile id.
+ *
+ * Empty input disables profile application; unknown ids throw with the allowed
+ * profile list for CLI diagnostics.
+ */
+export function resolveCreateProfileId(profile) {
+    if (profile === undefined || profile.trim().length === 0) {
+        return undefined;
+    }
+    const normalizedProfile = profile.trim();
+    if (isCreateProfileId(normalizedProfile)) {
+        return normalizedProfile;
+    }
+    throw new Error(`Unknown create profile "${profile}". Expected one of: ${CREATE_PROFILE_IDS.join(", ")}.`);
+}
 function normalizeTemplateSelection(templateId) {
     return normalizeTemplateLookupId(templateId);
 }
+function assertCreateProfileTemplateCompatibility({ profile, templateId, }) {
+    if (!profile) {
+        return;
+    }
+    if (profile === "plugin-qa" && templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        throw new Error("`--profile plugin-qa` currently supports only the official workspace template. Use `--template workspace` or add QA files later with `wp-typia add integration-env <name> --wp-env --release-zip`.");
+    }
+}
+async function applyCreateProfile({ profile, projectDir, }) {
+    if (profile !== "plugin-qa") {
+        return;
+    }
+    await runAddIntegrationEnvCommand({
+        cwd: projectDir,
+        integrationEnvName: "local-smoke",
+        service: "none",
+        withReleaseZip: true,
+        withWpEnv: true,
+    });
+}
 async function reportScaffoldProgress(onProgress, event) {
     await onProgress?.(event);
 }
-export async function scaffoldProject({ projectDir, templateId, answers, alternateRenderTargets, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, onProgress = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+export async function scaffoldProject({ projectDir, templateId, answers, alternateRenderTargets, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, profile, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, onProgress = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
     const resolvedTemplateId = normalizeTemplateSelection(templateId);
     const resolvedPackageManager = getPackageManager(packageManager).id;
     const isBuiltInTemplate = isBuiltInTemplateId(resolvedTemplateId);
+    assertCreateProfileTemplateCompatibility({
+        profile,
+        templateId: resolvedTemplateId,
+    });
     assertExternalLayerCompositionOptions({
         externalLayerId,
         externalLayerSource,
@@ -174,6 +223,10 @@ export async function scaffoldProject({ projectDir, templateId, answers, alterna
             withWpEnv,
         });
     }
+    await applyCreateProfile({
+        profile,
+        projectDir,
+    });
     await normalizePackageManagerFiles(projectDir, resolvedPackageManager);
     await removeUnexpectedLockfiles(projectDir, resolvedPackageManager);
     await replaceTextRecursively(projectDir, resolvedPackageManager, {

package/dist/runtime/temp-roots.js

@@ -23,7 +23,10 @@ function cleanupTrackedTempRootsSync() {
         try {
             fs.rmSync(tempRoot, { force: true, recursive: true });
         }
-        catch { }
+        catch {
+            // Process-exit cleanup is best-effort: shutdown-time rm failures
+            // such as EPERM are intentionally ignored rather than made fatal.
+        }
     }
 }
 function installCleanupHandlers() {

package/dist/runtime/template-layers.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { promises as fsp } from "node:fs";
 import { pathExists } from "./fs-async.js";
+import { readJsonFile } from "./json-utils.js";
 import { isPlainObject } from "./object-utils.js";
 import { getBuiltInSharedTemplateLayerDir, isBuiltInSharedTemplateLayerId, } from "./template-builtins.js";
 import { listInterpolatedDirectoryOutputs } from "./template-render.js";
@@ -59,7 +60,9 @@ export async function loadExternalTemplateLayerManifest(sourceRoot) {
     if (!(await pathExists(manifestPath))) {
         return null;
     }
-    const raw = JSON.parse(await fsp.readFile(manifestPath, "utf8"));
+    const raw = await readJsonFile(manifestPath, {
+        context: "template layer manifest",
+    });
     if (!isPlainObject(raw)) {
         throw new Error(`${TEMPLATE_LAYER_MANIFEST_FILENAME} must export a JSON object.`);
     }

package/dist/runtime/template-registry.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { readJsonFileSync } from "./json-utils.js";
 import { getBuiltInTemplateMetadataDefaults } from "./template-defaults.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PROJECT_TOOLS_PACKAGE_ROOT_ENV = "WP_TYPIA_PROJECT_TOOLS_PACKAGE_ROOT";
@@ -11,7 +12,9 @@ function resolveValidProjectToolsPackageRoot(candidateRoot) {
         return undefined;
     }
     try {
-        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        const packageJson = readJsonFileSync(packageJsonPath, {
+            context: "project-tools package manifest override",
+        });
         return packageJson.name === PROJECT_TOOLS_PACKAGE_NAME
             ? candidateRoot
             : undefined;
@@ -42,13 +45,16 @@ export function resolvePackageRoot(startDir) {
         const packageJsonPath = path.join(currentDir, "package.json");
         if (fs.existsSync(packageJsonPath)) {
             try {
-                const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+                const packageJson = readJsonFileSync(packageJsonPath, {
+                    context: "project-tools package root discovery manifest",
+                });
                 if (packageJson.name === PROJECT_TOOLS_PACKAGE_NAME) {
                     return currentDir;
                 }
             }
             catch {
-                // Ignore malformed package.json while walking upward.
+                // Ignore malformed package.json while walking upward; discovery should
+                // keep searching parent directories instead of failing on unrelated files.
             }
         }
         const parentDir = path.dirname(currentDir);

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

@@ -11,6 +11,8 @@ export interface TemplateVariableContext extends UnknownRecord {
     blockRuntimePackageVersion: string;
     /** Version string for `@wp-typia/block-types` used in generated dependencies. */
     blockTypesPackageVersion: string;
+    /** Version string for `wp-typia` used when templates include the CLI binary locally. */
+    wpTypiaPackageVersion: string;
     /** PascalCase block type name derived from the scaffold slug. */
     pascalCase: string;
     /** Snake_case PHP symbol prefix used for generated functions, constants, and keys. */

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

@@ -8,13 +8,14 @@ import { pathExists } from './fs-async.js';
 export { renderCreateBlockExternalTemplate } from './template-source-external.js';
 export { getTemplateProjectType, getTemplateProjectTypeAsync, getDefaultCategory, getDefaultCategoryAsync, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, } from './template-source-remote.js';
 export function getTemplateVariableContext(variables) {
-    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = getPackageVersions();
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, wpTypiaPackageVersion, } = getPackageVersions();
     return {
         ...variables,
         apiClientPackageVersion: variables.apiClientPackageVersion ?? apiClientPackageVersion,
         blockRuntimePackageVersion: variables.blockRuntimePackageVersion ?? blockRuntimePackageVersion,
         blockTypesPackageVersion: variables.blockTypesPackageVersion ?? blockTypesPackageVersion,
         projectToolsPackageVersion: variables.projectToolsPackageVersion ?? projectToolsPackageVersion,
+        wpTypiaPackageVersion: variables.wpTypiaPackageVersion ?? wpTypiaPackageVersion,
         description: variables.description,
         keyword: variables.keyword,
         namespace: variables.namespace,

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

@@ -6,6 +6,7 @@ import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, } from
 import { copyRawDirectory } from './template-render.js';
 import { createManagedTempRoot } from './temp-roots.js';
 import { pathExists } from './fs-async.js';
+import { readJsonFile, readJsonFileSync, safeJsonParse, } from './json-utils.js';
 async function cleanupSeedRootPair(cleanup, seedCleanup) {
     let cleanupError;
     try {
@@ -39,7 +40,9 @@ function readRemoteBlockJson(blockDir) {
         path.join(sourceRoot, 'block.json'),
     ]) {
         if (fs.existsSync(candidate)) {
-            return JSON.parse(fs.readFileSync(candidate, 'utf8'));
+            return readJsonFileSync(candidate, {
+                context: 'remote block metadata',
+            });
         }
     }
     throw new Error(`Unable to locate block.json in ${blockDir}`);
@@ -51,7 +54,9 @@ async function readRemoteBlockJsonAsync(blockDir) {
         path.join(sourceRoot, 'block.json'),
     ]) {
         if (await pathExists(candidate)) {
-            return JSON.parse(await fsp.readFile(candidate, 'utf8'));
+            return readJsonFile(candidate, {
+                context: 'remote block metadata',
+            });
         }
     }
     throw new Error(`Unable to locate block.json in ${blockDir}`);
@@ -105,7 +110,10 @@ function readTemplatePackageJson(sourceDir) {
                 maxBytes: getExternalTemplatePackageJsonMaxBytes(),
             });
             return {
-                packageJson: JSON.parse(fs.readFileSync(candidate, 'utf8')),
+                packageJson: safeJsonParse(fs.readFileSync(candidate, 'utf8'), {
+                    context: 'template metadata file',
+                    filePath: candidate,
+                }),
                 sourcePath: candidate,
             };
         }
@@ -130,7 +138,10 @@ async function readTemplatePackageJsonAsync(sourceDir) {
                 maxBytes: getExternalTemplatePackageJsonMaxBytes(),
             });
             return {
-                packageJson: JSON.parse(await fsp.readFile(candidate, 'utf8')),
+                packageJson: safeJsonParse(await fsp.readFile(candidate, 'utf8'), {
+                    context: 'template metadata file',
+                    filePath: candidate,
+                }),
                 sourcePath: candidate,
             };
         }
@@ -327,7 +338,9 @@ async function rewriteBlockJsonImports(directory) {
 }
 async function patchRemotePackageJson(templateDir, needsInteractivity) {
     const packageJsonPath = path.join(templateDir, 'package.json.mustache');
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, 'utf8'));
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: 'remote package template manifest',
+    });
     const existingDependencies = { ...(packageJson.dependencies ?? {}) };
     const existingDevDependencies = { ...(packageJson.devDependencies ?? {}) };
     delete existingDependencies['@wp-typia/project-tools'];

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

@@ -9,6 +9,7 @@ import { createExternalTemplateTimeoutError, fetchWithExternalTemplateTimeout, g
 import { findReusableExternalTemplateSourceCache, isExternalTemplateCacheEnabled, resolveExternalTemplateSourceCache, } from './template-source-cache.js';
 import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from './cli-diagnostics.js';
 import { pathExists } from './fs-async.js';
+import { readJsonFile, readJsonFileSync } from './json-utils.js';
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, OFFICIAL_WORKSPACE_TEMPLATE_ALIAS, PROJECT_TOOLS_PACKAGE_ROOT, TEMPLATE_IDS, } from './template-registry.js';
 import { isPlainObject } from './object-utils.js';
 import { createManagedTempRoot } from './temp-roots.js';
@@ -206,7 +207,9 @@ function resolveInstalledNpmTemplateSource(locator, cwd) {
             if (!fs.existsSync(packageJsonPath)) {
                 continue;
             }
-            const manifest = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+            const manifest = readJsonFileSync(packageJsonPath, {
+                context: 'workspace template package manifest',
+            });
             if (manifest.name === locator.name) {
                 return {
                     blockDir: packageDir,
@@ -259,7 +262,9 @@ export function isOfficialWorkspaceTemplateSeed(seed) {
         return false;
     }
     try {
-        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        const packageJson = readJsonFileSync(packageJsonPath, {
+            context: 'workspace template seed manifest',
+        });
         return packageJson.name === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
     }
     catch {
@@ -278,7 +283,9 @@ export async function isOfficialWorkspaceTemplateSeedAsync(seed) {
         return false;
     }
     try {
-        const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, 'utf8'));
+        const packageJson = await readJsonFile(packageJsonPath, {
+            context: 'workspace template seed manifest',
+        });
         return packageJson.name === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
     }
     catch {

package/dist/runtime/workspace-inventory-mutations.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import { escapeRegex } from "./php-utils.js";
-import { BLOCK_INVENTORY_SECTION, INVENTORY_SECTIONS, } from "./workspace-inventory-parser.js";
+import { BLOCK_INVENTORY_SECTION, INVENTORY_SECTIONS, } from "./workspace-inventory-section-descriptors.js";
 import { WORKSPACE_COMPATIBILITY_CONFIG_FIELD } from "./workspace-inventory-templates.js";
 function ensureWorkspaceInventorySections(source) {
     let nextSource = source.trimEnd();
@@ -157,6 +157,7 @@ export function updateWorkspaceInventorySource(source, options = {}) {
         ["responseTypeName", "\tresponseTypeName?: string;"],
         ["routePattern", "\troutePattern?: string;"],
         ["secretFieldName", "\tsecretFieldName?: string;"],
+        ["secretPreserveOnEmpty", "\tsecretPreserveOnEmpty?: boolean;"],
         ["secretStateFieldName", "\tsecretStateFieldName?: string;"],
     ]) {
         nextSource = upsertInterfaceField(nextSource, "WorkspaceRestResourceConfig", fieldName, fieldSource);