@wp-typia/project-tools 0.22.10 → 0.23.1

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

@@ -1,11 +1,101 @@
 import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_IDS, } from "./hooked-blocks.js";
 import { toSnakeCase, } from "./string-case.js";
-import { ADD_BLOCK_TEMPLATE_IDS, EDITOR_PLUGIN_SLOT_IDS, REST_RESOURCE_METHOD_IDS, resolveEditorPluginSlotAlias, } from "./cli-add-types.js";
+import { ADD_BLOCK_TEMPLATE_IDS, EDITOR_PLUGIN_SLOT_IDS, INTEGRATION_ENV_SERVICE_IDS, MANUAL_REST_CONTRACT_AUTH_IDS, MANUAL_REST_CONTRACT_HTTP_METHOD_IDS, REST_RESOURCE_METHOD_IDS, resolveEditorPluginSlotAlias, } from "./cli-add-types.js";
 const WORKSPACE_GENERATED_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
+const WORDPRESS_POST_TYPE_PATTERN = /^[a-z0-9_][a-z0-9_-]*$/u;
+const TYPESCRIPT_IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+const TYPESCRIPT_RESERVED_IDENTIFIERS = new Set([
+    "abstract",
+    "any",
+    "as",
+    "asserts",
+    "async",
+    "await",
+    "bigint",
+    "boolean",
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "constructor",
+    "continue",
+    "debugger",
+    "declare",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "from",
+    "function",
+    "get",
+    "global",
+    "if",
+    "implements",
+    "import",
+    "in",
+    "infer",
+    "instanceof",
+    "interface",
+    "intrinsic",
+    "is",
+    "keyof",
+    "let",
+    "module",
+    "namespace",
+    "never",
+    "new",
+    "null",
+    "number",
+    "object",
+    "of",
+    "out",
+    "override",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "readonly",
+    "require",
+    "return",
+    "satisfies",
+    "set",
+    "static",
+    "string",
+    "super",
+    "switch",
+    "symbol",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "type",
+    "typeof",
+    "undefined",
+    "unique",
+    "unknown",
+    "using",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+]);
 /**
  * Namespace format accepted by plugin-level REST resources.
  */
 export const REST_RESOURCE_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*(?:\/[a-z0-9-]+)+$/u;
+const PHP_IDENTIFIER_PATTERN = "[A-Za-z_][A-Za-z0-9_]*";
+const PHP_QUALIFIED_NAME_PATTERN = new RegExp(`^\\\\?${PHP_IDENTIFIER_PATTERN}(?:\\\\${PHP_IDENTIFIER_PATTERN})*$`, "u");
+const PHP_CALLBACK_REFERENCE_PATTERN = new RegExp(`^\\\\?${PHP_IDENTIFIER_PATTERN}(?:\\\\${PHP_IDENTIFIER_PATTERN})*(?:::${PHP_IDENTIFIER_PATTERN})?$`, "u");
+const REST_ROUTE_NAMED_CAPTURE_PATTERN = /\(\?P<([A-Za-z_][A-Za-z0-9_]*)>/gu;
+const REST_ROUTE_UNSUPPORTED_CAPTURE_PATTERN = /\((?!\?(?:P<[A-Za-z_][A-Za-z0-9_]*>|:))/u;
 /**
  * Validate a normalized workspace-generated slug.
  *
@@ -24,6 +114,28 @@ export function assertValidGeneratedSlug(label, slug, usage) {
     }
     return slug;
 }
+/**
+ * Validate a source type name used by generated schema artifact workflows.
+ *
+ * @param label Human-readable field label used in error messages.
+ * @param value TypeScript identifier candidate from CLI input or defaults.
+ * @param usage CLI usage hint shown when the identifier is empty.
+ * @returns The trimmed, validated TypeScript identifier.
+ * @throws {Error} When the value is empty or not a TypeScript identifier.
+ */
+export function assertValidTypeScriptIdentifier(label, value, usage) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(`${label} is required. Use \`${usage}\`.`);
+    }
+    if (!TYPESCRIPT_IDENTIFIER_PATTERN.test(trimmed)) {
+        throw new Error(`${label} must be a valid TypeScript identifier, such as ExternalRetrieveResponse.`);
+    }
+    if (TYPESCRIPT_RESERVED_IDENTIFIERS.has(trimmed)) {
+        throw new Error(`${label} must not be a reserved TypeScript keyword, such as ${trimmed}.`);
+    }
+    return trimmed;
+}
 /**
  * Validate a REST resource namespace.
  *
@@ -52,6 +164,44 @@ export function assertValidRestResourceNamespace(namespace) {
 export function resolveRestResourceNamespace(workspaceNamespace, namespace) {
     return assertValidRestResourceNamespace(namespace ?? `${workspaceNamespace}/v1`);
 }
+/**
+ * Validate a WordPress post type key used as post-meta scope.
+ *
+ * @param postType Raw post type key from CLI input.
+ * @returns The trimmed post type key.
+ * @throws {Error} When the key is empty or contains unsupported characters.
+ */
+export function assertValidPostMetaPostType(postType) {
+    const trimmed = postType.trim();
+    if (!trimmed) {
+        throw new Error("`wp-typia add post-meta` requires --post-type <post-type>.");
+    }
+    if (trimmed.length > 20) {
+        throw new Error("Post meta post type must be 20 characters or fewer.");
+    }
+    if (!WORDPRESS_POST_TYPE_PATTERN.test(trimmed)) {
+        throw new Error("Post meta post type must use a WordPress post type key such as `post` or `example_post_type`.");
+    }
+    return trimmed;
+}
+/**
+ * Resolve a post-meta key from explicit input or the workspace slug default.
+ *
+ * @param options Optional explicit meta key plus workspace prefix and slug.
+ * @returns A validated post-meta key.
+ * @throws {Error} When the key is empty or contains whitespace/control characters.
+ */
+export function resolvePostMetaKey({ metaKey, phpPrefix, slug, }) {
+    const resolvedMetaKey = metaKey ?? `_${toSnakeCase(`${phpPrefix}_${slug}`)}`;
+    const trimmed = resolvedMetaKey.trim();
+    if (!trimmed) {
+        throw new Error("Post meta key cannot be empty.");
+    }
+    if (/[\p{Cc}\s]/u.test(trimmed)) {
+        throw new Error("Post meta key must not contain whitespace or control characters.");
+    }
+    return trimmed;
+}
 /**
  * Parse and validate REST resource method ids from a comma-separated list.
  *
@@ -73,6 +223,154 @@ export function assertValidRestResourceMethods(methods) {
     }
     return normalizedMethods;
 }
+/**
+ * Validate a PHP callable reference supplied to generated REST route metadata.
+ *
+ * @param label Human-readable field label for errors.
+ * @param callback Optional PHP function or `ClassName::method` callback string.
+ * @returns The trimmed callback when present.
+ * @throws {Error} When the callback cannot be emitted as a safe PHP callable string.
+ */
+export function resolveOptionalPhpCallbackReference(label, callback) {
+    if (callback == null) {
+        return undefined;
+    }
+    const trimmed = callback.trim();
+    if (!trimmed) {
+        throw new Error(`${label} cannot be empty.`);
+    }
+    if (!PHP_CALLBACK_REFERENCE_PATTERN.test(trimmed)) {
+        throw new Error(`${label} must be a PHP function reference or ClassName::method callback.`);
+    }
+    return trimmed;
+}
+/**
+ * Validate a PHP class reference used by generated REST controller wrappers.
+ *
+ * @param label Human-readable field label for errors.
+ * @param classReference Optional PHP class name.
+ * @returns The trimmed class reference when present.
+ * @throws {Error} When the class reference cannot be emitted safely.
+ */
+export function resolveOptionalPhpClassReference(label, classReference) {
+    if (classReference == null) {
+        return undefined;
+    }
+    const trimmed = classReference.trim();
+    if (!trimmed) {
+        throw new Error(`${label} cannot be empty.`);
+    }
+    if (!PHP_QUALIFIED_NAME_PATTERN.test(trimmed)) {
+        throw new Error(`${label} must be a PHP class reference such as Demo_Rest_Controller or Vendor\\Plugin\\Controller.`);
+    }
+    return trimmed;
+}
+/**
+ * Normalize and validate the HTTP method used by a manual REST contract.
+ *
+ * @param method Optional method input. Defaults to GET.
+ * @returns A canonical uppercase HTTP method.
+ * @throws {Error} When the method is unsupported.
+ */
+export function assertValidManualRestContractHttpMethod(method = "GET") {
+    const normalized = method.trim().toUpperCase();
+    if (MANUAL_REST_CONTRACT_HTTP_METHOD_IDS.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Manual REST contract method must be one of: ${MANUAL_REST_CONTRACT_HTTP_METHOD_IDS.join(", ")}.`);
+}
+/**
+ * Normalize and validate the auth intent used by a manual REST contract.
+ *
+ * @param auth Optional auth intent input. Defaults to public.
+ * @returns A canonical auth intent.
+ * @throws {Error} When the auth intent is unsupported.
+ */
+export function assertValidManualRestContractAuth(auth = "public") {
+    const normalized = auth.trim().toLowerCase();
+    if (MANUAL_REST_CONTRACT_AUTH_IDS.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Manual REST contract auth must be one of: ${MANUAL_REST_CONTRACT_AUTH_IDS.join(", ")}.`);
+}
+/**
+ * Normalize and validate a manual REST contract route path pattern.
+ *
+ * @param slug Generated contract slug used for the default route path.
+ * @param pathPattern Optional route path pattern, relative to the namespace.
+ * @returns A route pattern with a leading slash.
+ * @throws {Error} When the path pattern is empty or clearly not a route path.
+ */
+function resolveRestRoutePathPattern(options) {
+    const explicitPath = typeof options.pathPattern === "string" ? options.pathPattern.trim() : undefined;
+    if (explicitPath === "") {
+        throw new Error(options.emptyMessage);
+    }
+    const trimmed = explicitPath ?? options.defaultPath;
+    if (/^https?:\/\//iu.test(trimmed)) {
+        throw new Error(`${options.label} must be a route pattern relative to the namespace, not an absolute URL.`);
+    }
+    const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    if (!withLeadingSlash || withLeadingSlash === "/") {
+        throw new Error(options.emptyMessage);
+    }
+    if (/\s/u.test(withLeadingSlash)) {
+        throw new Error(`${options.label} must not contain whitespace.`);
+    }
+    return withLeadingSlash;
+}
+/**
+ * Check whether a generated REST item route keeps the generated `id` contract aligned.
+ *
+ * @param routePattern Route pattern relative to the namespace.
+ * @returns True when the pattern has no regex groups or uses only `(?P<id>...)`.
+ */
+export function isGeneratedRestResourceRoutePatternCompatible(routePattern) {
+    const namedCaptures = Array.from(routePattern.matchAll(REST_ROUTE_NAMED_CAPTURE_PATTERN), (match) => match[1]);
+    const hasRegexGroup = routePattern.includes("(");
+    const hasUnsupportedCapture = REST_ROUTE_UNSUPPORTED_CAPTURE_PATTERN.test(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}`,
+        emptyMessage: "Manual REST contract path is required. Use `--path <route-pattern>` such as `/external-record/(?P<id>[\\d]+)`.",
+        label: "Manual REST contract path",
+        pathPattern,
+    });
+}
+/**
+ * Normalize and validate a generated REST resource item route pattern.
+ *
+ * @param slug Generated resource slug used for the default item route path.
+ * @param routePattern Optional route path pattern, relative to the namespace.
+ * @returns A route pattern with a leading slash.
+ * @throws {Error} When the route pattern is empty or clearly not a route path.
+ */
+export function resolveGeneratedRestResourceRoutePattern(slug, routePattern) {
+    const resolvedRoutePattern = resolveRestRoutePathPattern({
+        defaultPath: `/${slug}/item`,
+        emptyMessage: "Generated REST resource route pattern is required. Use `--route-pattern <route-pattern>` such as `/records/(?P<id>[\\d]+)`.",
+        label: "Generated REST resource route pattern",
+        pathPattern: routePattern,
+    });
+    const hasExplicitRoutePattern = typeof routePattern === "string" && routePattern.trim().length > 0;
+    if (hasExplicitRoutePattern &&
+        !isGeneratedRestResourceRoutePatternCompatible(resolvedRoutePattern)) {
+        throw new Error("Generated REST resource route pattern must use only an `(?P<id>...)` named capture when using regex groups.");
+    }
+    return resolvedRoutePattern;
+}
 /**
  * Validate a hooked block insertion position.
  *
@@ -145,3 +443,17 @@ export function assertValidEditorPluginSlot(slot = "sidebar") {
     }
     throw new Error(`Editor plugin slot must be one of: ${EDITOR_PLUGIN_SLOT_IDS.join(", ")}. Legacy aliases: PluginSidebar, PluginDocumentSettingPanel.`);
 }
+/**
+ * Validate and normalize the optional integration environment service starter.
+ *
+ * @param service Optional service starter id. Defaults to `none`.
+ * @returns The canonical integration environment service id.
+ * @throws {Error} When the service starter is unsupported.
+ */
+export function assertValidIntegrationEnvService(service = "none") {
+    const trimmed = service.trim();
+    if (INTEGRATION_ENV_SERVICE_IDS.includes(trimmed)) {
+        return trimmed;
+    }
+    throw new Error(`Integration environment service must be one of: ${INTEGRATION_ENV_SERVICE_IDS.join(", ")}.`);
+}

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,9 +1,11 @@
 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, } from './cli-add-workspace-admin-view-templates.js';
-import { ADMIN_VIEWS_PHP_GLOB, isAdminViewCoreDataSource, } from './cli-add-workspace-admin-view-types.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';
+import { buildManualRestContractApiSource } from './cli-add-workspace-rest-source-emitters.js';
 import { getWorkspaceBootstrapPath, patchFile, } from './cli-add-shared.js';
 import { appendPhpSnippetBeforeClosingTag, executeWorkspaceMutationPlan, insertPhpSnippetBeforeWorkspaceAnchors, } from './cli-add-workspace-mutation.js';
 import { DEFAULT_WORDPRESS_CORE_DATA_VERSION, DEFAULT_WORDPRESS_DATA_VERSION, DEFAULT_WORDPRESS_DATAVIEWS_VERSION, DEFAULT_WP_TYPIA_DATAVIEWS_VERSION, resolveManagedPackageVersionRange, } from './package-versions.js';
@@ -12,7 +14,34 @@ function detectJsonIndent(source) {
     const indentMatch = /\n([ \t]+)"/u.exec(source);
     return indentMatch?.[1] ?? 2;
 }
-async function ensureAdminViewPackageDependencies(workspace, adminViewSource) {
+const LEGACY_MANUAL_REST_API_SOURCE_PATTERN = /^\s*export\s+\*\s+from\s+["']\.\/api-client["'];?\s*$/u;
+const MANUAL_REST_API_DIRECT_CALL_EXPORT_PATTERN = /(?:^|\n)\s*export\s+(?:(?:async\s+)?function|const|let|var)\s+callManualRestContract\b/u;
+const MANUAL_REST_API_NAMED_EXPORT_PATTERN = /(?:^|\n)\s*export\s*\{([^}]*)\}/gu;
+function hasManualRestContractCallerExport(apiSource) {
+    if (MANUAL_REST_API_DIRECT_CALL_EXPORT_PATTERN.test(apiSource)) {
+        return true;
+    }
+    return Array.from(apiSource.matchAll(MANUAL_REST_API_NAMED_EXPORT_PATTERN)).some((match) => match[1].split(',').some((specifier) => {
+        const [localName, exportedName] = specifier.trim().split(/\s+as\s+/u);
+        return (exportedName ?? localName)?.trim() === 'callManualRestContract';
+    }));
+}
+async function ensureManualSettingsRestApiShim(workspace, restResource) {
+    const apiPath = path.join(workspace.projectDir, restResource.apiFile);
+    const apiSource = await fsp.readFile(apiPath, 'utf8');
+    if (hasManualRestContractCallerExport(apiSource)) {
+        return;
+    }
+    if (!LEGACY_MANUAL_REST_API_SOURCE_PATTERN.test(apiSource)) {
+        throw new Error(`Manual REST resource source "${restResource.slug}" must export callManualRestContract from ${restResource.apiFile}. Restore the generated manual REST api.ts or update it before scaffolding a settings admin view.`);
+    }
+    await fsp.writeFile(apiPath, buildManualRestContractApiSource({
+        bodyTypeName: restResource.bodyTypeName,
+        queryTypeName: restResource.queryTypeName,
+        restResourceSlug: restResource.slug,
+    }), 'utf8');
+}
+async function ensureAdminViewPackageDependencies(workspace, adminViewSource, restResource) {
     const packageJsonPath = path.join(workspace.projectDir, 'package.json');
     const wpTypiaDataViewsVersion = resolveManagedPackageVersionRange({
         fallback: DEFAULT_WP_TYPIA_DATAVIEWS_VERSION,
@@ -32,7 +61,11 @@ async function ensureAdminViewPackageDependencies(workspace, adminViewSource) {
         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)
             ? {
                 '@wordpress/core-data': packageJson.dependencies?.['@wordpress/core-data'] ??
@@ -43,14 +76,22 @@ async function ensureAdminViewPackageDependencies(workspace, adminViewSource) {
             : {};
         const nextDependencies = {
             ...(packageJson.dependencies ?? {}),
-            '@wordpress/dataviews': packageJson.dependencies?.['@wordpress/dataviews'] ??
-                wordpressDataViewsVersion,
+            ...(needsDataViews
+                ? {
+                    '@wordpress/dataviews': packageJson.dependencies?.['@wordpress/dataviews'] ??
+                        wordpressDataViewsVersion,
+                }
+                : {}),
             ...coreDataDependencies,
         };
         const nextDevDependencies = {
             ...(packageJson.devDependencies ?? {}),
-            '@wp-typia/dataviews': packageJson.devDependencies?.['@wp-typia/dataviews'] ??
-                wpTypiaDataViewsVersion,
+            ...(needsDataViews
+                ? {
+                    '@wp-typia/dataviews': packageJson.devDependencies?.['@wp-typia/dataviews'] ??
+                        wpTypiaDataViewsVersion,
+                }
+                : {}),
         };
         if (JSON.stringify(nextDependencies) ===
             JSON.stringify(packageJson.dependencies ?? {}) &&
@@ -193,6 +234,10 @@ export async function scaffoldAdminViewWorkspace(options) {
     const webpackConfigPath = path.join(workspace.projectDir, 'webpack.config.js');
     const adminViewsIndexPath = await resolveAdminViewRegistryPath(workspace.projectDir);
     const adminViewDir = path.join(workspace.projectDir, 'src', 'admin-views', adminViewSlug);
+    const manualSettingsRestResource = isAdminViewManualSettingsRestResource(restResource) ? restResource : undefined;
+    const manualSettingsRestApiPath = manualSettingsRestResource
+        ? path.join(workspace.projectDir, manualSettingsRestResource.apiFile)
+        : undefined;
     const adminViewPhpPath = path.join(workspace.projectDir, 'inc', 'admin-views', `${adminViewSlug}.php`);
     await executeWorkspaceMutationPlan({
         filePaths: [
@@ -202,26 +247,40 @@ export async function scaffoldAdminViewWorkspace(options) {
             buildScriptPath,
             packageJsonPath,
             webpackConfigPath,
+            ...(manualSettingsRestApiPath ? [manualSettingsRestApiPath] : []),
         ],
         targetPaths: [adminViewDir, adminViewPhpPath],
         run: async () => {
             await fsp.mkdir(adminViewDir, { recursive: true });
             await fsp.mkdir(path.dirname(adminViewPhpPath), { recursive: true });
-            await ensureAdminViewPackageDependencies(workspace, parsedSource);
+            await ensureAdminViewPackageDependencies(workspace, parsedSource, restResource);
             await ensureAdminViewBootstrapAnchors(workspace);
             await ensureAdminViewBuildScriptAnchors(workspace);
             await ensureAdminViewWebpackAnchors(workspace);
-            await fsp.writeFile(path.join(adminViewDir, 'types.ts'), buildAdminViewTypesSource(adminViewSlug, restResource, coreDataSource), 'utf8');
-            await fsp.writeFile(path.join(adminViewDir, 'config.ts'), buildAdminViewConfigSource(adminViewSlug, workspace.workspace.textDomain, parsedSource, restResource), 'utf8');
-            await fsp.writeFile(path.join(adminViewDir, 'data.ts'), coreDataSource
-                ? buildCoreDataAdminViewDataSource(adminViewSlug, coreDataSource)
-                : restResource
-                    ? buildRestAdminViewDataSource(adminViewSlug, restResource)
-                    : buildDefaultAdminViewDataSource(adminViewSlug), 'utf8');
-            await fsp.writeFile(path.join(adminViewDir, 'Screen.tsx'), coreDataSource
-                ? buildCoreDataAdminViewScreenSource(adminViewSlug, workspace.workspace.textDomain)
-                : buildAdminViewScreenSource(adminViewSlug, workspace.workspace.textDomain), 'utf8');
-            await fsp.writeFile(path.join(adminViewDir, 'index.tsx'), buildAdminViewEntrySource(adminViewSlug), 'utf8');
+            if (manualSettingsRestResource) {
+                await ensureManualSettingsRestApiShim(workspace, manualSettingsRestResource);
+            }
+            await fsp.writeFile(path.join(adminViewDir, 'types.ts'), manualSettingsRestResource
+                ? buildRestSettingsAdminViewTypesSource(adminViewSlug, manualSettingsRestResource)
+                : buildAdminViewTypesSource(adminViewSlug, restResource, coreDataSource), 'utf8');
+            await fsp.writeFile(path.join(adminViewDir, 'config.ts'), manualSettingsRestResource
+                ? buildRestSettingsAdminViewConfigSource(adminViewSlug, workspace.workspace.textDomain, manualSettingsRestResource)
+                : buildAdminViewConfigSource(adminViewSlug, workspace.workspace.textDomain, parsedSource, restResource), 'utf8');
+            await fsp.writeFile(path.join(adminViewDir, 'data.ts'), manualSettingsRestResource
+                ? buildRestSettingsAdminViewDataSource(adminViewSlug, manualSettingsRestResource)
+                : coreDataSource
+                    ? buildCoreDataAdminViewDataSource(adminViewSlug, coreDataSource)
+                    : restResource
+                        ? buildRestAdminViewDataSource(adminViewSlug, restResource)
+                        : buildDefaultAdminViewDataSource(adminViewSlug), 'utf8');
+            await fsp.writeFile(path.join(adminViewDir, 'Screen.tsx'), manualSettingsRestResource
+                ? buildRestSettingsAdminViewScreenSource(adminViewSlug, workspace.workspace.textDomain)
+                : coreDataSource
+                    ? buildCoreDataAdminViewScreenSource(adminViewSlug, workspace.workspace.textDomain)
+                    : buildAdminViewScreenSource(adminViewSlug, workspace.workspace.textDomain), 'utf8');
+            await fsp.writeFile(path.join(adminViewDir, 'index.tsx'), buildAdminViewEntrySource(adminViewSlug, {
+                includeDataViewsStyle: !manualSettingsRestResource,
+            }), 'utf8');
             await fsp.writeFile(path.join(adminViewDir, 'style.scss'), buildAdminViewStyleSource(), 'utf8');
             await fsp.writeFile(adminViewPhpPath, buildAdminViewPhpSource(adminViewSlug, workspace), 'utf8');
             await writeAdminViewRegistry(workspace.projectDir, adminViewSlug);

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

@@ -1,5 +1,5 @@
 import { assertValidGeneratedSlug } from './cli-add-shared.js';
-import { ADMIN_VIEW_CORE_DATA_ENTITY_KIND_IDS, ADMIN_VIEW_CORE_DATA_ENTITY_NAME_PATTERN, ADMIN_VIEW_CORE_DATA_ENTITY_SEGMENT_PATTERN, ADMIN_VIEW_CORE_DATA_SOURCE_KIND, ADMIN_VIEW_REST_SOURCE_KIND, ADMIN_VIEW_SOURCE_USAGE, isAdminViewCoreDataSource, isAdminViewRestResourceSource, } from './cli-add-workspace-admin-view-types.js';
+import { ADMIN_VIEW_CORE_DATA_ENTITY_KIND_IDS, ADMIN_VIEW_CORE_DATA_ENTITY_NAME_PATTERN, ADMIN_VIEW_CORE_DATA_ENTITY_SEGMENT_PATTERN, ADMIN_VIEW_CORE_DATA_SOURCE_KIND, ADMIN_VIEW_REST_SOURCE_KIND, ADMIN_VIEW_SOURCE_USAGE, hasAdminViewManualSettingsRouteParameters, isAdminViewCoreDataSource, isAdminViewManualSettingsRestResource, isAdminViewRestResourceSource, } from './cli-add-workspace-admin-view-types.js';
 /**
  * Assert that admin-view package dependencies are available before file writes.
  *
@@ -75,8 +75,17 @@ export function resolveRestResourceSource(restResources, source) {
     if (!restResource) {
         throw new Error(`Unknown REST resource source "${source.slug}". Choose one of: ${restResources.map((entry) => entry.slug).join(', ') || '<none>'}.`);
     }
+    if (isAdminViewManualSettingsRestResource(restResource)) {
+        if (hasAdminViewManualSettingsRouteParameters(restResource)) {
+            throw new Error(`REST resource source "${source.slug}" uses route parameters or regex groups and cannot scaffold a singleton admin settings form. Use a manual REST contract without path parameters or build a custom admin UI.`);
+        }
+        return restResource;
+    }
+    if (restResource.mode === 'manual') {
+        throw new Error(`REST resource source "${source.slug}" must define a request body type before it can scaffold an admin settings form.`);
+    }
     if (!restResource.methods.includes('list')) {
-        throw new Error(`REST resource source "${source.slug}" must include the list method for DataViews pagination.`);
+        throw new Error(`REST resource source "${source.slug}" must include the list method for DataViews pagination or be a manual settings contract with a body type.`);
     }
     return restResource;
 }

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;