@wp-typia/project-tools 0.23.0 → 0.23.1

package/dist/runtime/ai-feature-artifacts.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { defineEndpointManifest, syncEndpointClient, syncRestOpenApi, syncTypeSchemas, } from "@wp-typia/block-runtime/metadata-core";
 import { projectWordPressAiSchema } from "./ai-artifacts.js";
 import { isFileNotFoundError } from "./fs-async.js";
+import { readJsonFile } from "./json-utils.js";
 function normalizeGeneratedArtifactContent(content) {
     return content.replace(/\r\n?/g, "\n");
 }
@@ -120,7 +121,9 @@ export async function syncAiFeatureRestArtifacts({ clientFile, executionOptions,
  */
 export async function syncAiFeatureSchemaArtifact({ aiSchemaFile, check = false, outputDir, projectDir, }) {
     const sourceSchemaPath = path.join(projectDir, outputDir, "api-schemas", "feature-result.schema.json");
-    const responseSchema = assertJsonObject(JSON.parse(await readFile(sourceSchemaPath, "utf8")), sourceSchemaPath);
+    const responseSchema = assertJsonObject(await readJsonFile(sourceSchemaPath, {
+        context: "AI feature response schema",
+    }), sourceSchemaPath);
     const aiSchema = projectWordPressAiSchema(responseSchema);
     await reconcileGeneratedArtifact({
         check,

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

@@ -98,7 +98,7 @@ export function createBuiltInBlockSpec({ alternateRenderTargets, answers, dataSt
     };
 }
 export function buildTemplateVariablesFromBlockSpec(spec) {
-    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = getPackageVersions();
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, wpTypiaPackageVersion, } = getPackageVersions();
     const slug = spec.block.slug;
     const slugSnakeCase = toSnakeCase(slug);
     const pascalCase = toPascalCase(slug);
@@ -167,6 +167,7 @@ export function buildTemplateVariablesFromBlockSpec(spec) {
         requiresPhp: compatibility.pluginHeader.requiresPhp,
         testedUpTo: compatibility.pluginHeader.testedUpTo,
         projectToolsPackageVersion,
+        wpTypiaPackageVersion,
         cssClassName,
         dashCase: slug,
         dataStorageMode,

package/dist/runtime/cli-add-block-json.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
 import { readOptionalUtf8File } from "./fs-async.js";
+import { safeJsonParse } from "./json-utils.js";
 /**
  * Resolve an existing workspace block inventory entry by slug.
  *
@@ -32,7 +33,10 @@ export async function readWorkspaceBlockJson(projectDir, blockSlug) {
     }
     let blockJson;
     try {
-        blockJson = parseScaffoldBlockMetadata(JSON.parse(source));
+        blockJson = parseScaffoldBlockMetadata(safeJsonParse(source, {
+            context: "workspace block metadata",
+            filePath: blockJsonPath,
+        }));
     }
     catch (error) {
         throw new Error(error instanceof Error

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

@@ -8,7 +8,7 @@ export function formatAddHelpText() {
     return `Usage:
   wp-typia add admin-view <name> [--source <rest-resource:slug|core-data:kind/name>] [--dry-run]
   wp-typia add block <name> [--template <${ADD_BLOCK_TEMPLATE_IDS.join("|")}>] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--inner-blocks-preset <freeform|ordered|horizontal|locked-structure>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--dry-run]
-  wp-typia add integration-env <name> [--wp-env] [--service <none|docker-compose>] [--dry-run]
+  wp-typia add integration-env <name> [--wp-env] [--release-zip] [--service <none|docker-compose>] [--dry-run]
   wp-typia add variation <name> --block <block-slug> [--dry-run]
   wp-typia add style <name> --block <block-slug> [--dry-run]
   wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug> [--dry-run]
@@ -16,7 +16,7 @@ export function formatAddHelpText() {
   wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>] [--dry-run]
   wp-typia add contract <name> [--type <ExportedTypeName>] [--dry-run]
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <${REST_RESOURCE_METHOD_IDS.join(",")}>] [--route-pattern <route-pattern>] [--permission-callback <callback>] [--controller-class <ClassName>] [--controller-extends <BaseClass>] [--dry-run]
-  wp-typia add rest-resource <name> --manual [--namespace <vendor/v1>] [--method <GET|POST|PUT|PATCH|DELETE>] [--auth <public|authenticated|public-write-protected>] [--path <route-pattern>] [--query-type <Type>] [--body-type <Type>] [--response-type <Type>] [--dry-run]
+  wp-typia add rest-resource <name> --manual [--namespace <vendor/v1>] [--method <GET|POST|PUT|PATCH|DELETE>] [--auth <public|authenticated|public-write-protected>] [--path <route-pattern>|--route-pattern <route-pattern>] [--permission-callback <callback>] [--controller-class <ClassName>] [--controller-extends <BaseClass>] [--query-type <Type>] [--body-type <Type>] [--response-type <Type>] [--secret-field <field>] [--secret-state-field|--secret-has-value-field <field>] [--secret-preserve-on-empty <true|false>] [--dry-run]
   wp-typia add post-meta <name> --post-type <post-type> [--type <ExportedTypeName>] [--meta-key <meta-key>] [--hide-from-rest] [--dry-run]
   wp-typia add ability <name> [--dry-run]
   wp-typia add ai-feature <name> [--namespace <vendor/v1>] [--dry-run]
@@ -32,6 +32,7 @@ Notes:
   Pass \`--source core-data:postType/post\` or \`--source core-data:taxonomy/category\` to bind a WordPress-owned entity collection.
   Generated admin-view workspaces add \`@wp-typia/dataviews\` and the needed WordPress DataViews packages as opt-in dependencies.
   \`add integration-env\` generates an opt-in local smoke starter under \`scripts/integration-smoke/\`, updates \`.env.example\`, and can add \`@wordpress/env\` plus \`.wp-env.json\` when \`--wp-env\` is passed.
+  Pass \`--release-zip\` to add \`release:zip\`, \`release:zip:check\`, and \`qa:check\` scripts for plugin QA packaging.
   Pass \`--service docker-compose\` to include a placeholder local service stack that can be adapted to project-specific dependencies.
   \`query-loop\` is a create-time scaffold family. Use \`wp-typia create <project-dir> --template query-loop\` instead of \`wp-typia add block\`.
   \`add variation\` targets an existing block slug from \`scripts/block-config.ts\`.
@@ -41,7 +42,7 @@ Notes:
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`; pass \`--block\` and \`--attribute\` together to declare an end-to-end bindable attribute on an existing generated block.
   \`add contract\` registers a standalone TypeScript wire contract under \`src/contracts/\` and generates a stable JSON Schema artifact without creating PHP route glue.
   \`add rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`. Use \`--route-pattern\`, \`--permission-callback\`, \`--controller-class\`, and \`--controller-extends\` when an existing WordPress controller or permission model needs to own part of the generated route surface.
-  Pass \`--manual\` with \`add rest-resource\` to track an external REST route with typed schemas, OpenAPI, clients, and drift checks without generating PHP route/controller files.
+  Pass \`--manual\` with \`add rest-resource\` to track an external/provider REST route with typed schemas, OpenAPI, clients, and drift checks without generating PHP route/controller files. Manual routes may still declare \`--permission-callback\`, \`--controller-class\`, and \`--controller-extends\` as metadata for the route owner. Settings contracts can add \`--secret-field\` with \`--secret-preserve-on-empty\` metadata so generated schemas, clients, and admin forms treat blank secret submissions as preserve-by-default.
   \`add post-meta\` scaffolds a typed post meta contract under \`src/post-meta/\`, generates a schema artifact, and wires \`register_post_meta()\` helpers under \`inc/post-meta/\`.
   \`add ability\` scaffolds typed workflow abilities under \`src/abilities/\` and server registration under \`inc/abilities/\`.
   \`add ai-feature\` scaffolds server-owned AI feature endpoints under \`src/ai-features/\` and PHP route glue under \`inc/ai-features/\`.

package/dist/runtime/cli-add-types.d.ts

@@ -189,17 +189,17 @@ export interface RunAddPostMetaCommandOptions {
  * @property auth Optional auth intent for manual mode. Defaults to public.
  * @property bodyTypeName Optional exported TypeScript body type for manual
  * mode. Defaults to `<PascalName>Request` for write methods.
- * @property controllerClass Optional generated REST controller class reference.
- * When present, route callbacks delegate through an instantiated controller.
+ * @property controllerClass Optional REST controller class reference. Generated
+ * routes delegate through it; manual/provider routes record it as owner metadata.
  * @property controllerExtends Optional base class for the generated controller
- * wrapper when `controllerClass` is a global class name.
+ * wrapper or declared manual/provider controller owner.
  * @property cwd Working directory used to resolve the nearest official workspace.
  * @property manual Whether to scaffold a type-only external REST contract.
  * @property method HTTP method for manual REST contract mode. Defaults to GET.
  * @property methods Optional comma-separated REST method list.
  * @property namespace Optional REST namespace, defaulting to the workspace namespace.
  * @property permissionCallback Optional PHP callback used for generated REST
- * route permission checks.
+ * route permission checks or declared manual/provider route ownership.
  * @property pathPattern Route path pattern for manual mode, relative to the
  * namespace. Defaults to `/<name>`.
  * @property queryTypeName Optional exported TypeScript query type for manual
@@ -207,10 +207,17 @@ export interface RunAddPostMetaCommandOptions {
  * @property restResourceName Human-entered resource name normalized into a slug.
  * @property responseTypeName Optional exported TypeScript response type for
  * manual mode. Defaults to `<PascalName>Response`.
- * @property routePattern Optional generated item route pattern, relative to the
- * namespace. Defaults to `/<name>/item`.
+ * @property routePattern Optional generated item route pattern, or manual
+ * provider-route alias for `pathPattern`, relative to the namespace.
+ * Generated mode defaults to `/<name>/item`; manual mode defaults to `/<name>`.
  * @property secretFieldName Optional write-only secret field name for manual
  * settings contracts. Requires a request body.
+ * @property secretHasValueFieldName Optional alias for `secretStateFieldName`
+ * when the response field is a safe presence indicator.
+ * @property secretMaskedResponseFieldName Optional alias for
+ * `secretStateFieldName` when the response field represents masked state.
+ * @property secretPreserveOnEmpty Whether blank secret submissions should
+ * preserve the existing value. Defaults to true when `secretFieldName` is set.
  * @property secretStateFieldName Optional masked response boolean field for
  * `secretFieldName`. Defaults to `has<PascalSecretField>`.
  */
@@ -231,6 +238,9 @@ export interface RunAddRestResourceCommandOptions {
     responseTypeName?: string;
     routePattern?: string;
     secretFieldName?: string;
+    secretHasValueFieldName?: string;
+    secretMaskedResponseFieldName?: string;
+    secretPreserveOnEmpty?: boolean | string;
     secretStateFieldName?: string;
 }
 /**
@@ -310,12 +320,14 @@ export interface RunAddEditorPluginCommandOptions {
  * @property integrationEnvName Human-entered environment name that will be
  * normalized into script and documentation paths.
  * @property service Optional local service starter. Defaults to `none`.
+ * @property withReleaseZip Whether to add release zip packaging scripts.
  * @property withWpEnv Whether to add a local `@wordpress/env` preset and scripts.
  */
 export interface RunAddIntegrationEnvCommandOptions {
     cwd?: string;
     integrationEnvName: string;
     service?: string;
+    withReleaseZip?: boolean;
     withWpEnv?: boolean;
 }
 /**

package/dist/runtime/cli-add-validation.d.ts

@@ -110,6 +110,13 @@ export declare function assertValidManualRestContractAuth(auth?: string): Manual
  * @returns True when the pattern has no regex groups or uses only `(?P<id>...)`.
  */
 export declare function isGeneratedRestResourceRoutePatternCompatible(routePattern: string): boolean;
+/**
+ * Collect unique WordPress named capture parameters from a REST route pattern.
+ *
+ * @param routePattern Route pattern relative to the namespace.
+ * @returns Capture names in first-seen order.
+ */
+export declare function collectRestRouteNamedCaptureNames(routePattern: string): string[];
 export declare function resolveManualRestContractPathPattern(slug: string, pathPattern?: string): string;
 /**
  * Normalize and validate a generated REST resource item route pattern.

package/dist/runtime/cli-add-validation.js

@@ -332,6 +332,15 @@ export function isGeneratedRestResourceRoutePatternCompatible(routePattern) {
     return (!hasUnsupportedCapture &&
         (!hasRegexGroup || (namedCaptures.length === 1 && namedCaptures[0] === "id")));
 }
+/**
+ * Collect unique WordPress named capture parameters from a REST route pattern.
+ *
+ * @param routePattern Route pattern relative to the namespace.
+ * @returns Capture names in first-seen order.
+ */
+export function collectRestRouteNamedCaptureNames(routePattern) {
+    return Array.from(new Set(Array.from(routePattern.matchAll(REST_ROUTE_NAMED_CAPTURE_PATTERN), (match) => match[1])));
+}
 export function resolveManualRestContractPathPattern(slug, pathPattern) {
     return resolveRestRoutePathPattern({
         defaultPath: `/${slug}`,

package/dist/runtime/cli-add-workspace-ability-scaffold.js

@@ -4,6 +4,7 @@ import { syncTypeSchemas } from "@wp-typia/block-runtime/metadata-core";
 import semver from "semver";
 import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
 import { pathExists, readOptionalUtf8File } from "./fs-async.js";
+import { readJsonFile } from "./json-utils.js";
 import { buildAbilityClientSource, buildAbilityConfigEntry, buildAbilityConfigSource, buildAbilityDataSource, buildAbilityPhpSource, buildAbilityRegistrySource, buildAbilitySyncScriptSource, buildAbilityTypesSource, } from "./cli-add-workspace-ability-templates.js";
 import { ABILITY_EDITOR_ASSET, ABILITY_EDITOR_SCRIPT, ABILITY_REGISTRY_END_MARKER, ABILITY_REGISTRY_START_MARKER, ABILITY_SERVER_GLOB, WP_ABILITIES_SCRIPT_MODULE_ID, WP_CORE_ABILITIES_SCRIPT_MODULE_ID, } from "./cli-add-workspace-ability-types.js";
 import { getWorkspaceBootstrapPath, patchFile, } from "./cli-add-shared.js";
@@ -163,7 +164,9 @@ function ${enqueueFunctionName}() {
 }
 async function ensureAbilityPackageScripts(workspace) {
     const packageJsonPath = path.join(workspace.projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: "workspace package manifest",
+    });
     const nextScripts = {
         ...(packageJson.scripts ?? {}),
         "sync-abilities": packageJson.scripts?.["sync-abilities"] ?? "tsx scripts/sync-abilities.ts",

package/dist/runtime/cli-add-workspace-admin-view-scaffold.js

@@ -1,6 +1,7 @@
 import { promises as fsp } from 'node:fs';
 import path from 'node:path';
 import { pathExists, readOptionalUtf8File } from './fs-async.js';
+import { safeJsonParse } from './json-utils.js';
 import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from './workspace-inventory.js';
 import { buildAdminViewConfigEntry, buildAdminViewConfigSource, buildAdminViewEntrySource, buildAdminViewPhpSource, buildAdminViewRegistrySource, buildAdminViewScreenSource, buildAdminViewStyleSource, buildAdminViewTypesSource, buildCoreDataAdminViewDataSource, buildCoreDataAdminViewScreenSource, buildDefaultAdminViewDataSource, buildRestAdminViewDataSource, buildRestSettingsAdminViewConfigSource, buildRestSettingsAdminViewDataSource, buildRestSettingsAdminViewScreenSource, buildRestSettingsAdminViewTypesSource, } from './cli-add-workspace-admin-view-templates.js';
 import { ADMIN_VIEWS_PHP_GLOB, isAdminViewCoreDataSource, isAdminViewManualSettingsRestResource, } from './cli-add-workspace-admin-view-types.js';
@@ -60,7 +61,10 @@ async function ensureAdminViewPackageDependencies(workspace, adminViewSource, re
         packageName: '@wordpress/data',
     });
     await patchFile(packageJsonPath, (source) => {
-        const packageJson = JSON.parse(source);
+        const packageJson = safeJsonParse(source, {
+            context: 'admin view package manifest',
+            filePath: packageJsonPath,
+        });
         const needsDataViews = !isAdminViewManualSettingsRestResource(restResource);
         const coreDataDependencies = isAdminViewCoreDataSource(adminViewSource)
             ? {

package/dist/runtime/cli-add-workspace-admin-view-templates-core-data.d.ts

@@ -0,0 +1,34 @@
+import { type AdminViewCoreDataSource } from './cli-add-workspace-admin-view-types.js';
+/**
+ * Builds TypeScript item and dataset types for a core-data-backed admin view.
+ *
+ * @param adminViewSlug - Admin-view slug used to derive generated type names.
+ * @param coreDataSource - WordPress core-data entity source for the admin view.
+ * @returns Generated TypeScript source for core-data admin-view types.
+ */
+export declare function buildCoreDataAdminViewTypesSource(adminViewSlug: string, coreDataSource: AdminViewCoreDataSource): string;
+/**
+ * Builds a DataViews config module for a core-data-backed admin view.
+ *
+ * @param adminViewSlug - Admin-view slug used to derive generated identifiers.
+ * @param textDomain - WordPress i18n text domain for generated labels.
+ * @param coreDataSource - WordPress core-data entity source for field selection.
+ * @returns Generated TypeScript source for the core-data DataViews config.
+ */
+export declare function buildCoreDataAdminViewConfigSource(adminViewSlug: string, textDomain: string, coreDataSource: AdminViewCoreDataSource): string;
+/**
+ * Builds data hooks for loading records from the WordPress core-data store.
+ *
+ * @param adminViewSlug - Admin-view slug used to derive generated identifiers.
+ * @param coreDataSource - WordPress core-data entity source for generated hooks.
+ * @returns Generated TypeScript source for core-data data access.
+ */
+export declare function buildCoreDataAdminViewDataSource(adminViewSlug: string, coreDataSource: AdminViewCoreDataSource): string;
+/**
+ * Builds the React screen module for a core-data-backed admin view.
+ *
+ * @param adminViewSlug - Admin-view slug used to derive generated identifiers.
+ * @param textDomain - WordPress i18n text domain for generated labels.
+ * @returns Generated TSX source for the core-data admin-view screen.
+ */
+export declare function buildCoreDataAdminViewScreenSource(adminViewSlug: string, textDomain: string): string;