@wp-typia/project-tools 0.23.0 → 0.24.0

package/dist/runtime/cli-add-workspace-rest-source-utils.js

@@ -0,0 +1,50 @@
+/**
+ * Prefix every line in a multi-line source fragment.
+ *
+ * @param source Source fragment to indent.
+ * @param prefix Prefix to prepend to every line.
+ * @returns The source fragment with each line prefixed.
+ */
+export function indentMultiline(source, prefix) {
+    return source
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+const RESOLVE_REST_NONCE_SOURCE = `function resolveRestNonce( fallback?: string ): string | undefined {
+\tif ( typeof fallback === 'string' && fallback.length > 0 ) {
+\t\treturn fallback;
+\t}
+
+\tif ( typeof window === 'undefined' ) {
+\t\treturn undefined;
+\t}
+
+\tconst wpApiSettings = (
+\t\twindow as typeof window & {
+\t\t\twpApiSettings?: { nonce?: string };
+\t\t}
+\t).wpApiSettings;
+
+\treturn typeof wpApiSettings?.nonce === 'string' &&
+\t\twpApiSettings.nonce.length > 0
+\t\t? wpApiSettings.nonce
+\t\t: undefined;
+}`;
+/**
+ * Render the shared REST nonce helper in the formatting style expected by a
+ * generated source file.
+ *
+ * @param style Compact output is used by manual-contract shims; spaced output
+ * matches generated REST resource shims.
+ * @returns TypeScript source for the embedded `resolveRestNonce()` helper.
+ */
+export function formatResolveRestNonceSource(style) {
+    if (style === "spaced") {
+        return RESOLVE_REST_NONCE_SOURCE;
+    }
+    return RESOLVE_REST_NONCE_SOURCE
+        .replace("function resolveRestNonce( fallback?: string ): string | undefined {", "function resolveRestNonce(fallback?: string): string | undefined {")
+        .replace("\tif ( typeof fallback === 'string' && fallback.length > 0 ) {", "\tif (typeof fallback === 'string' && fallback.length > 0) {")
+        .replace("\tif ( typeof window === 'undefined' ) {", "\tif (typeof window === 'undefined') {");
+}

package/dist/runtime/cli-add-workspace-rest-sync-script-shared.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Build the standard sync-rest patch failure message for missing anchors.
+ *
+ * @param functionName Name of the patcher that could not complete.
+ * @param syncRestScriptPath Path to the workspace sync-rest script.
+ * @param anchorDescription Human-readable description of the missing anchor.
+ * @param subject Configuration subject the patcher was trying to wire.
+ * @returns A formatted error message with manual recovery guidance.
+ */
+export declare function getSyncRestPatchErrorMessage(functionName: string, syncRestScriptPath: string, anchorDescription: string, subject: string): string;
+/**
+ * Add a required block-config value and type import to sync-rest source.
+ *
+ * @param options Import patching options.
+ * @param options.functionName Name of the calling patcher for error messages.
+ * @param options.nextSource Current sync-rest script source.
+ * @param options.subject Value and type names that must be imported.
+ * @param options.syncRestScriptPath Path to the target sync-rest script.
+ * @returns Source with the block-config import updated or left unchanged.
+ * @throws When the generated block-config import anchor cannot be found.
+ */
+export declare function replaceBlockConfigImport({ functionName, nextSource, subject, syncRestScriptPath, }: {
+    functionName: string;
+    nextSource: string;
+    subject: {
+        configTypeName: string;
+        constName: string;
+    };
+    syncRestScriptPath: string;
+}): string;
+/**
+ * Render a sync-rest guard for the selected empty resource collections.
+ *
+ * @param options Guard rendering options.
+ * @param options.subjects Candidate guard subjects and conditions.
+ * @returns TypeScript source for the no-resources guard block.
+ */
+export declare function buildNoResourcesGuard({ subjects, }: {
+    subjects: readonly {
+        condition: string;
+        include: boolean;
+        subject: string;
+    }[];
+}): string;
+/**
+ * Replace the generated no-resources guard in sync-rest source.
+ *
+ * @param nextSource Current sync-rest script source.
+ * @param replacement New no-resources guard source.
+ * @param functionName Name of the calling patcher for error messages.
+ * @param syncRestScriptPath Path to the target sync-rest script.
+ * @param subject Configuration subject the patcher was trying to wire.
+ * @returns Source with the no-resources guard replaced.
+ * @throws When the generated no-resources guard cannot be found.
+ */
+export declare function replaceNoResourcesGuard(nextSource: string, replacement: string, functionName: string, syncRestScriptPath: string, subject: string): string;

package/dist/runtime/cli-add-workspace-rest-sync-script-shared.js

@@ -0,0 +1,122 @@
+import path from "node:path";
+/**
+ * Build the standard sync-rest patch failure message for missing anchors.
+ *
+ * @param functionName Name of the patcher that could not complete.
+ * @param syncRestScriptPath Path to the workspace sync-rest script.
+ * @param anchorDescription Human-readable description of the missing anchor.
+ * @param subject Configuration subject the patcher was trying to wire.
+ * @returns A formatted error message with manual recovery guidance.
+ */
+export function getSyncRestPatchErrorMessage(functionName, syncRestScriptPath, anchorDescription, subject) {
+    return [
+        `${functionName} could not patch ${path.basename(syncRestScriptPath)}.`,
+        `Missing expected ${anchorDescription} anchor in scripts/sync-rest-contracts.ts.`,
+        `Restore the generated template or add the ${subject} wiring manually before retrying.`,
+    ].join(" ");
+}
+const BLOCK_CONFIG_IMPORT_PATTERNS = [
+    /^import\s*\{\n(?:\t[^\n]*\n)+\} from ["']\.\/block-config["'];?$/mu,
+    /^import\s*\{[^\n]*\}\s*from\s*["']\.\/block-config["'];?$/mu,
+];
+const BLOCK_CONFIG_VALUE_IMPORT_ORDER = [
+    "AI_FEATURES",
+    "BLOCKS",
+    "CONTRACTS",
+    "POST_META",
+    "REST_RESOURCES",
+];
+const BLOCK_CONFIG_TYPE_IMPORT_ORDER = [
+    "WorkspaceAiFeatureConfig",
+    "WorkspaceBlockConfig",
+    "WorkspaceContractConfig",
+    "WorkspacePostMetaConfig",
+    "WorkspaceRestResourceConfig",
+];
+/**
+ * Add a required block-config value and type import to sync-rest source.
+ *
+ * @param options Import patching options.
+ * @param options.functionName Name of the calling patcher for error messages.
+ * @param options.nextSource Current sync-rest script source.
+ * @param options.subject Value and type names that must be imported.
+ * @param options.syncRestScriptPath Path to the target sync-rest script.
+ * @returns Source with the block-config import updated or left unchanged.
+ * @throws When the generated block-config import anchor cannot be found.
+ */
+export function replaceBlockConfigImport({ functionName, nextSource, subject, syncRestScriptPath, }) {
+    const importMatch = BLOCK_CONFIG_IMPORT_PATTERNS.map((pattern) => pattern.exec(nextSource)).find(Boolean) ?? null;
+    if (!importMatch) {
+        throw new Error(getSyncRestPatchErrorMessage(functionName, syncRestScriptPath, "block-config import", subject.constName));
+    }
+    const importSource = importMatch[0];
+    if (importSource.includes(subject.constName) &&
+        importSource.includes(subject.configTypeName)) {
+        return nextSource;
+    }
+    if (!importSource.includes("BLOCKS") ||
+        !importSource.includes("WorkspaceBlockConfig")) {
+        throw new Error(getSyncRestPatchErrorMessage(functionName, syncRestScriptPath, "BLOCKS import", subject.constName));
+    }
+    const replacement = [
+        "import {",
+        ...BLOCK_CONFIG_VALUE_IMPORT_ORDER.flatMap((constName) => constName === subject.constName || importSource.includes(constName)
+            ? [`\t${constName},`]
+            : []),
+        ...BLOCK_CONFIG_TYPE_IMPORT_ORDER.flatMap((configTypeName) => configTypeName === subject.configTypeName ||
+            importSource.includes(configTypeName)
+            ? [`\ttype ${configTypeName},`]
+            : []),
+        "} from './block-config';",
+    ].join("\n");
+    return nextSource.replace(importSource, replacement);
+}
+function formatNoResourcesSubject(subjects) {
+    if (subjects.length <= 2) {
+        return subjects.join(" or ");
+    }
+    const lastSubject = subjects[subjects.length - 1];
+    return `${subjects.slice(0, -1).join(", ")}, or ${lastSubject}`;
+}
+/**
+ * Render a sync-rest guard for the selected empty resource collections.
+ *
+ * @param options Guard rendering options.
+ * @param options.subjects Candidate guard subjects and conditions.
+ * @returns TypeScript source for the no-resources guard block.
+ */
+export function buildNoResourcesGuard({ subjects, }) {
+    const includedSubjects = subjects.filter((subject) => subject.include);
+    const condition = includedSubjects.map(({ condition }, index) => index === includedSubjects.length - 1 ? condition : `${condition} &&`);
+    const noResourcesSubject = formatNoResourcesSubject(includedSubjects.map(({ subject }) => subject));
+    return [
+        "if (",
+        ...condition.map((line) => `\t\t${line}`),
+        "\t) {",
+        "\t\tconsole.log(",
+        "\t\t\toptions.check",
+        `\t\t\t\t? 'ℹ️ No ${noResourcesSubject} are registered yet. \`sync-rest --check\` is already clean.'`,
+        `\t\t\t\t: 'ℹ️ No ${noResourcesSubject} are registered yet.'`,
+        "\t\t);",
+        "\t\treturn;",
+        "\t}",
+    ].join("\n");
+}
+const NO_RESOURCES_GUARD_PATTERN = /if \(\s*restBlocks\.length === 0(?:\s*&&\s*standaloneContracts\.length === 0)?(?:\s*&&\s*postMetaContracts\.length === 0)?(?:\s*&&\s*restResources\.length === 0)?(?:\s*&&\s*aiFeatures\.length === 0)?\s*\) \{[\s\S]*?\n\t\treturn;\n\t\}/u;
+/**
+ * Replace the generated no-resources guard in sync-rest source.
+ *
+ * @param nextSource Current sync-rest script source.
+ * @param replacement New no-resources guard source.
+ * @param functionName Name of the calling patcher for error messages.
+ * @param syncRestScriptPath Path to the target sync-rest script.
+ * @param subject Configuration subject the patcher was trying to wire.
+ * @returns Source with the no-resources guard replaced.
+ * @throws When the generated no-resources guard cannot be found.
+ */
+export function replaceNoResourcesGuard(nextSource, replacement, functionName, syncRestScriptPath, subject) {
+    if (!NO_RESOURCES_GUARD_PATTERN.test(nextSource)) {
+        throw new Error(getSyncRestPatchErrorMessage(functionName, syncRestScriptPath, "no-resources guard", subject));
+    }
+    return nextSource.replace(NO_RESOURCES_GUARD_PATTERN, replacement);
+}

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

@@ -0,0 +1,108 @@
+import type { ManualRestContractAuthId, ManualRestContractHttpMethodId, RestResourceMethodId } from "./cli-add-shared.js";
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Normalized metadata returned after `wp-typia add rest-resource` completes.
+ *
+ * @property auth Manual-mode authentication policy when `mode` is `"manual"`.
+ * @property bodyTypeName Optional manual-mode request body type export.
+ * @property controllerClass Optional PHP controller class reference. Generated
+ * mode uses it for callbacks; manual mode records it as route-owner metadata.
+ * @property methods Generated-mode REST operation ids, or an empty array for
+ * manual contracts.
+ * @property mode Whether the scaffold wrote generated REST glue or a type-only
+ * manual contract.
+ * @property namespace REST namespace in `vendor/v1` format.
+ * @property projectDir Absolute workspace project directory.
+ * @property restResourceSlug Normalized kebab-case REST resource slug.
+ * @property secretPreserveOnEmpty Whether blank settings secret submissions
+ * should preserve the stored value when `secretFieldName` is set.
+ */
+export interface RunAddRestResourceCommandResult {
+    auth?: ManualRestContractAuthId;
+    bodyTypeName?: string;
+    controllerClass?: string;
+    controllerExtends?: string;
+    method?: ManualRestContractHttpMethodId;
+    methods: RestResourceMethodId[];
+    mode: "generated" | "manual";
+    namespace: string;
+    permissionCallback?: string;
+    pathPattern?: string;
+    projectDir: string;
+    queryTypeName?: string;
+    restResourceSlug: string;
+    responseTypeName?: string;
+    routePattern?: string;
+    secretFieldName?: string;
+    secretHasValueFieldName?: string;
+    secretMaskedResponseFieldName?: string;
+    secretPreserveOnEmpty?: boolean;
+    secretStateFieldName?: string;
+}
+/**
+ * Raw command options passed from the REST orchestrator into manual-mode
+ * contract scaffolding.
+ *
+ * @property auth Optional raw manual authentication id, validated before use.
+ * @property bodyTypeName Optional exported request body type name.
+ * @property method Optional raw HTTP method id, validated as a manual REST
+ * contract method.
+ * @property namespace Resolved REST namespace in `vendor/v1` format.
+ * @property pathPattern Optional manual route path pattern relative to the
+ * namespace.
+ * @property permissionCallback Optional manual route-owner permission callback
+ * metadata.
+ * @property restResourceSlug Normalized kebab-case REST resource slug.
+ * @property routePattern Optional manual route path alias for `pathPattern`.
+ * @property secretHasValueFieldName Optional alias for `secretStateFieldName`.
+ * @property secretMaskedResponseFieldName Optional alias for
+ * `secretStateFieldName`.
+ * @property secretFieldName Optional write-only request secret field.
+ * @property secretPreserveOnEmpty Optional normalized boolean for blank-secret
+ * preservation. Defaults to true when `secretFieldName` is set.
+ * @property workspace Resolved official workspace project.
+ */
+export interface ManualRestContractScaffoldOptions {
+    auth: string | undefined;
+    bodyTypeName: string | undefined;
+    controllerClass: string | undefined;
+    controllerExtends: string | undefined;
+    method: string | undefined;
+    namespace: string;
+    pathPattern: string | undefined;
+    permissionCallback: string | undefined;
+    queryTypeName: string | undefined;
+    responseTypeName: string | undefined;
+    restResourceSlug: string;
+    routePattern: string | undefined;
+    secretFieldName: string | undefined;
+    secretHasValueFieldName: string | undefined;
+    secretMaskedResponseFieldName: string | undefined;
+    secretPreserveOnEmpty: boolean | undefined;
+    secretStateFieldName: string | undefined;
+    workspace: WorkspaceProject;
+}
+/**
+ * Raw command options passed from the REST orchestrator into generated-mode
+ * resource scaffolding.
+ *
+ * @property controllerClass Optional PHP controller class reference.
+ * @property controllerExtends Optional PHP base class reference; requires
+ * `controllerClass`.
+ * @property methods Optional comma-separated REST method list validated into
+ * `RestResourceMethodId` values.
+ * @property namespace Resolved REST namespace in `vendor/v1` format.
+ * @property permissionCallback Optional PHP permission callback reference.
+ * @property restResourceSlug Normalized kebab-case REST resource slug.
+ * @property workspace Resolved official workspace project.
+ */
+export interface GeneratedRestResourceScaffoldOptions {
+    controllerClass: string | undefined;
+    controllerExtends: string | undefined;
+    methods: string | undefined;
+    namespace: string;
+    permissionCallback: string | undefined;
+    restResourceSlug: string;
+    routePattern: string | undefined;
+    workspace: WorkspaceProject;
+}

package/dist/runtime/cli-add-workspace-rest-types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/cli-add-workspace-rest.d.ts

@@ -1,4 +1,5 @@
-import { type ManualRestContractAuthId, type ManualRestContractHttpMethodId, type RestResourceMethodId, type RunAddRestResourceCommandOptions } from "./cli-add-shared.js";
+import { type RunAddRestResourceCommandOptions } from "./cli-add-shared.js";
+import { type RunAddRestResourceCommandResult } from "./cli-add-workspace-rest-types.js";
 /**
  * Scaffold a workspace-level REST resource and synchronize its generated
  * TypeScript and PHP artifacts.
@@ -6,22 +7,4 @@ import { type ManualRestContractAuthId, type ManualRestContractHttpMethodId, typ
  * @param options Command options for the REST resource scaffold workflow.
  * @returns Resolved scaffold metadata for the created REST resource.
  */
-export declare function runAddRestResourceCommand({ auth, bodyTypeName, controllerClass, controllerExtends, cwd, manual, method, methods, namespace, permissionCallback, pathPattern, queryTypeName, restResourceName, responseTypeName, routePattern, secretFieldName, secretStateFieldName, }: RunAddRestResourceCommandOptions): Promise<{
-    auth?: ManualRestContractAuthId;
-    bodyTypeName?: string;
-    controllerClass?: string;
-    controllerExtends?: string;
-    method?: ManualRestContractHttpMethodId;
-    methods: RestResourceMethodId[];
-    mode: "generated" | "manual";
-    namespace: string;
-    permissionCallback?: string;
-    pathPattern?: string;
-    projectDir: string;
-    queryTypeName?: string;
-    restResourceSlug: string;
-    responseTypeName?: string;
-    routePattern?: string;
-    secretFieldName?: string;
-    secretStateFieldName?: string;
-}>;
+export declare function runAddRestResourceCommand({ auth, bodyTypeName, controllerClass, controllerExtends, cwd, manual, method, methods, namespace, permissionCallback, pathPattern, queryTypeName, restResourceName, responseTypeName, routePattern, secretFieldName, secretHasValueFieldName, secretMaskedResponseFieldName, secretPreserveOnEmpty, secretStateFieldName, }: RunAddRestResourceCommandOptions): Promise<RunAddRestResourceCommandResult>;