@wp-typia/project-tools 0.22.10 → 0.23.1

package/dist/runtime/json-utils.d.ts

@@ -1,7 +1,65 @@
 /**
- * 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 declare function cloneJsonValue<T>(value: T): T;
+/**
+ * Optional metadata used to enrich JSON parse errors.
+ */
+export interface SafeJsonParseOptions {
+    /** Human-readable operation label included in parse failures. */
+    context?: string;
+    /** Source file path included in parse failures when available. */
+    filePath?: string;
+}
+/**
+ * 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 declare function safeJsonParse<T = unknown>(source: string, options?: SafeJsonParseOptions): T;
+/**
+ * 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 declare function readJsonFileSync<T = unknown>(filePath: string, options?: Omit<SafeJsonParseOptions, "filePath">): T;
+/**
+ * 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 declare function readJsonFile<T = unknown>(filePath: string, options?: Omit<SafeJsonParseOptions, "filePath">): Promise<T>;

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/rest-resource-artifacts.d.ts

@@ -1,7 +1,8 @@
-import type { RestResourceMethodId } from "./cli-add-shared.js";
+import type { ManualRestContractAuthId, ManualRestContractHttpMethodId, RestResourceMethodId } from "./cli-add-shared.js";
 interface RestResourceTemplateVariablesLike {
     namespace: string;
     pascalCase: string;
+    routePattern?: string;
     slugKebabCase: string;
     title: string;
 }
@@ -14,6 +15,26 @@ interface SyncRestResourceArtifactsOptions {
     validatorsFile: string;
     variables: RestResourceTemplateVariablesLike;
 }
+interface ManualRestContractTemplateVariablesLike {
+    auth: ManualRestContractAuthId;
+    bodyTypeName?: string;
+    method: ManualRestContractHttpMethodId;
+    namespace: string;
+    pascalCase: string;
+    pathPattern: string;
+    queryTypeName: string;
+    responseTypeName: string;
+    slugKebabCase: string;
+    title: string;
+}
+interface SyncManualRestContractArtifactsOptions {
+    clientFile: string;
+    outputDir: string;
+    projectDir: string;
+    typesFile: string;
+    validatorsFile: string;
+    variables: ManualRestContractTemplateVariablesLike;
+}
 /**
  * Build the endpoint manifest for a workspace-level REST resource scaffold.
  *
@@ -24,6 +45,33 @@ interface SyncRestResourceArtifactsOptions {
 export declare function buildRestResourceEndpointManifest(variables: RestResourceTemplateVariablesLike, methods: RestResourceMethodId[]): import("@wp-typia/block-runtime/metadata-core").EndpointManifestDefinition<Record<string, {
     sourceTypeName: string;
 }>, import("@wp-typia/block-runtime/schema-core").EndpointOpenApiEndpointDefinition[]>;
+/**
+ * Build the endpoint manifest for a type-only manual REST contract. Manual
+ * contracts describe routes owned by another integration without generating PHP
+ * route glue in the workspace.
+ *
+ * @param variables Template naming data used for contract names, route path,
+ * and OpenAPI info.
+ * @returns Endpoint manifest consumed by schema, OpenAPI, and client generators.
+ */
+export declare function buildManualRestContractEndpointManifest(variables: ManualRestContractTemplateVariablesLike): import("@wp-typia/block-runtime/metadata-core").EndpointManifestDefinition<Record<string, {
+    sourceTypeName: string;
+}>, readonly [{
+    readonly wordpressAuth?: {
+        mechanism: "rest-nonce";
+    } | {
+        mechanism: "public-signed-token";
+    } | undefined;
+    readonly method: "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+    readonly operationId: `call${string}ManualRestContract`;
+    readonly path: `/${string}${string}`;
+    readonly queryContract: "query";
+    readonly responseContract: "response";
+    readonly summary: `Call external ${string} REST route.`;
+    readonly tags: readonly [string];
+    readonly bodyContract?: string | undefined;
+    readonly auth: "authenticated" | "public" | "public-write-protected";
+}]>;
 /**
  * Synchronize generated schemas, OpenAPI output, and endpoint client code for
  * a workspace-level REST resource scaffold.
@@ -32,4 +80,12 @@ export declare function buildRestResourceEndpointManifest(variables: RestResourc
  * @returns A promise that resolves after every generated REST artifact has been refreshed.
  */
 export declare function syncRestResourceArtifacts({ clientFile, methods, outputDir, projectDir, typesFile, validatorsFile, variables, }: SyncRestResourceArtifactsOptions): Promise<void>;
+/**
+ * Synchronize generated schemas, OpenAPI output, and endpoint client code for a
+ * type-only manual REST contract.
+ *
+ * @param options Contract file paths and naming variables.
+ * @returns A promise that resolves after every generated artifact has refreshed.
+ */
+export declare function syncManualRestContractArtifacts({ clientFile, outputDir, projectDir, typesFile, validatorsFile, variables, }: SyncManualRestContractArtifactsOptions): Promise<void>;
 export {};

package/dist/runtime/rest-resource-artifacts.js

@@ -1,5 +1,18 @@
 import path from "node:path";
 import { defineEndpointManifest, syncEndpointClient, syncRestOpenApi, syncTypeSchemas, } from "@wp-typia/block-runtime/metadata-core";
+function resolveManualRestContractWordPressAuth(auth) {
+    if (auth === "authenticated") {
+        return {
+            mechanism: "rest-nonce",
+        };
+    }
+    if (auth === "public-write-protected") {
+        return {
+            mechanism: "public-signed-token",
+        };
+    }
+    return undefined;
+}
 /**
  * Build the endpoint manifest for a workspace-level REST resource scaffold.
  *
@@ -9,7 +22,12 @@ import { defineEndpointManifest, syncEndpointClient, syncRestOpenApi, syncTypeSc
  */
 export function buildRestResourceEndpointManifest(variables, methods) {
     const basePath = `/${variables.namespace}/${variables.slugKebabCase}`;
-    const itemPath = `${basePath}/item`;
+    const routePattern = variables.routePattern == null
+        ? `/${variables.slugKebabCase}/item`
+        : variables.routePattern.startsWith("/")
+            ? variables.routePattern
+            : `/${variables.routePattern}`;
+    const itemPath = `/${variables.namespace}${routePattern}`;
     const contracts = {};
     const endpoints = [];
     if (methods.includes("list")) {
@@ -124,6 +142,52 @@ export function buildRestResourceEndpointManifest(variables, methods) {
         },
     });
 }
+/**
+ * Build the endpoint manifest for a type-only manual REST contract. Manual
+ * contracts describe routes owned by another integration without generating PHP
+ * route glue in the workspace.
+ *
+ * @param variables Template naming data used for contract names, route path,
+ * and OpenAPI info.
+ * @returns Endpoint manifest consumed by schema, OpenAPI, and client generators.
+ */
+export function buildManualRestContractEndpointManifest(variables) {
+    const contracts = {
+        query: {
+            sourceTypeName: variables.queryTypeName,
+        },
+        response: {
+            sourceTypeName: variables.responseTypeName,
+        },
+    };
+    if (variables.bodyTypeName) {
+        contracts.request = {
+            sourceTypeName: variables.bodyTypeName,
+        };
+    }
+    const wordpressAuth = resolveManualRestContractWordPressAuth(variables.auth);
+    return defineEndpointManifest({
+        contracts,
+        endpoints: [
+            {
+                auth: variables.auth,
+                ...(variables.bodyTypeName ? { bodyContract: "request" } : {}),
+                method: variables.method,
+                operationId: `call${variables.pascalCase}ManualRestContract`,
+                path: `/${variables.namespace}${variables.pathPattern}`,
+                queryContract: "query",
+                responseContract: "response",
+                summary: `Call external ${variables.title} REST route.`,
+                tags: [variables.title],
+                ...(wordpressAuth ? { wordpressAuth } : {}),
+            },
+        ],
+        info: {
+            title: `${variables.title} Manual REST Contract`,
+            version: "1.0.0",
+        },
+    });
+}
 /**
  * Synchronize generated schemas, OpenAPI output, and endpoint client code for
  * a workspace-level REST resource scaffold.
@@ -156,3 +220,35 @@ export async function syncRestResourceArtifacts({ clientFile, methods, outputDir
         validatorsFile,
     });
 }
+/**
+ * Synchronize generated schemas, OpenAPI output, and endpoint client code for a
+ * type-only manual REST contract.
+ *
+ * @param options Contract file paths and naming variables.
+ * @returns A promise that resolves after every generated artifact has refreshed.
+ */
+export async function syncManualRestContractArtifacts({ clientFile, outputDir, projectDir, typesFile, validatorsFile, variables, }) {
+    const manifest = buildManualRestContractEndpointManifest(variables);
+    for (const [baseName, contract] of Object.entries(manifest.contracts)) {
+        await syncTypeSchemas({
+            jsonSchemaFile: path.join(outputDir, "api-schemas", `${baseName}.schema.json`),
+            openApiFile: path.join(outputDir, "api-schemas", `${baseName}.openapi.json`),
+            projectRoot: projectDir,
+            sourceTypeName: contract.sourceTypeName,
+            typesFile,
+        });
+    }
+    await syncRestOpenApi({
+        manifest,
+        openApiFile: path.join(outputDir, "api.openapi.json"),
+        projectRoot: projectDir,
+        typesFile,
+    });
+    await syncEndpointClient({
+        clientFile,
+        manifest,
+        projectRoot: projectDir,
+        typesFile,
+        validatorsFile,
+    });
+}

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>;