@wp-typia/project-tools 0.22.10 → 0.23.0

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

@@ -50,23 +50,296 @@ function replaceRequiredSyncRestSource(nextSource, target, anchor, replacement,
     assertSyncRestAnchor(nextSource, target, anchorDescription, hasAnchor, syncRestScriptPath);
     return nextSource.replace(anchor, replacement);
 }
+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(" ");
+}
+function replaceBlockConfigImportForContracts(nextSource, syncRestScriptPath) {
+    const importPatterns = [
+        /^import\s*\{\n(?:\t[^\n]*\n)+\} from ["']\.\/block-config["'];?$/mu,
+        /^import\s*\{[^\n]*\}\s*from\s*["']\.\/block-config["'];?$/mu,
+    ];
+    const importMatch = importPatterns.map((pattern) => pattern.exec(nextSource)).find(Boolean) ??
+        null;
+    if (!importMatch) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureContractSyncScriptAnchors", syncRestScriptPath, "block-config import", "CONTRACTS"));
+    }
+    const importSource = importMatch[0];
+    if (importSource.includes("CONTRACTS") &&
+        importSource.includes("WorkspaceContractConfig")) {
+        return nextSource;
+    }
+    if (!importSource.includes("BLOCKS") ||
+        !importSource.includes("WorkspaceBlockConfig")) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureContractSyncScriptAnchors", syncRestScriptPath, "BLOCKS import", "CONTRACTS"));
+    }
+    const hasAiFeatures = importSource.includes("AI_FEATURES");
+    const hasAiFeatureConfig = importSource.includes("WorkspaceAiFeatureConfig");
+    const hasRestResources = importSource.includes("REST_RESOURCES");
+    const hasRestResourceConfig = importSource.includes("WorkspaceRestResourceConfig");
+    const hasPostMeta = importSource.includes("POST_META");
+    const hasPostMetaConfig = importSource.includes("WorkspacePostMetaConfig");
+    const replacement = [
+        "import {",
+        ...(hasAiFeatures ? ["\tAI_FEATURES,"] : []),
+        "\tBLOCKS,",
+        "\tCONTRACTS,",
+        ...(hasPostMeta ? ["\tPOST_META,"] : []),
+        ...(hasRestResources ? ["\tREST_RESOURCES,"] : []),
+        ...(hasAiFeatureConfig ? ["\ttype WorkspaceAiFeatureConfig,"] : []),
+        "\ttype WorkspaceBlockConfig,",
+        "\ttype WorkspaceContractConfig,",
+        ...(hasPostMetaConfig ? ["\ttype WorkspacePostMetaConfig,"] : []),
+        ...(hasRestResourceConfig ? ["\ttype WorkspaceRestResourceConfig,"] : []),
+        "} from './block-config';",
+    ].join("\n");
+    return nextSource.replace(importSource, replacement);
+}
+function replaceBlockConfigImportForRestResources(nextSource, syncRestScriptPath) {
+    const importPatterns = [
+        /^import\s*\{\n(?:\t[^\n]*\n)+\} from ["']\.\/block-config["'];?$/mu,
+        /^import\s*\{[^\n]*\}\s*from\s*["']\.\/block-config["'];?$/mu,
+    ];
+    const importMatch = importPatterns.map((pattern) => pattern.exec(nextSource)).find(Boolean) ??
+        null;
+    if (!importMatch) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureRestResourceSyncScriptAnchors", syncRestScriptPath, "block-config import", "REST_RESOURCES"));
+    }
+    const importSource = importMatch[0];
+    if (importSource.includes("REST_RESOURCES") &&
+        importSource.includes("WorkspaceRestResourceConfig")) {
+        return nextSource;
+    }
+    if (!importSource.includes("BLOCKS") ||
+        !importSource.includes("WorkspaceBlockConfig")) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureRestResourceSyncScriptAnchors", syncRestScriptPath, "BLOCKS import", "REST_RESOURCES"));
+    }
+    const hasAiFeatures = importSource.includes("AI_FEATURES");
+    const hasAiFeatureConfig = importSource.includes("WorkspaceAiFeatureConfig");
+    const hasContracts = importSource.includes("CONTRACTS");
+    const hasContractConfig = importSource.includes("WorkspaceContractConfig");
+    const hasPostMeta = importSource.includes("POST_META");
+    const hasPostMetaConfig = importSource.includes("WorkspacePostMetaConfig");
+    const replacement = [
+        "import {",
+        ...(hasAiFeatures ? ["\tAI_FEATURES,"] : []),
+        "\tBLOCKS,",
+        ...(hasContracts ? ["\tCONTRACTS,"] : []),
+        ...(hasPostMeta ? ["\tPOST_META,"] : []),
+        "\tREST_RESOURCES,",
+        ...(hasAiFeatureConfig ? ["\ttype WorkspaceAiFeatureConfig,"] : []),
+        "\ttype WorkspaceBlockConfig,",
+        ...(hasContractConfig ? ["\ttype WorkspaceContractConfig,"] : []),
+        ...(hasPostMetaConfig ? ["\ttype WorkspacePostMetaConfig,"] : []),
+        "\ttype WorkspaceRestResourceConfig,",
+        "} from './block-config';",
+    ].join("\n");
+    return nextSource.replace(importSource, replacement);
+}
+function replaceRequiredContractSyncRestSource(nextSource, target, anchor, replacement, anchorDescription, syncRestScriptPath) {
+    if (nextSource.includes(target)) {
+        return nextSource;
+    }
+    const hasAnchor = typeof anchor === "string" ? nextSource.includes(anchor) : anchor.test(nextSource);
+    if (!hasAnchor) {
+        throw new Error(getSyncRestPatchErrorMessage("ensureContractSyncScriptAnchors", syncRestScriptPath, anchorDescription, "CONTRACTS"));
+    }
+    return nextSource.replace(anchor, 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}`;
+}
+function buildContractNoResourcesGuard({ hasAiFeatures, hasPostMeta, hasRestResources, }) {
+    const condition = ["restBlocks.length === 0 &&", "standaloneContracts.length === 0"];
+    if (hasPostMeta) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("postMetaContracts.length === 0");
+    }
+    if (hasRestResources) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("restResources.length === 0");
+    }
+    if (hasAiFeatures) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("aiFeatures.length === 0");
+    }
+    const noResourcesSubject = formatNoResourcesSubject([
+        "REST-enabled workspace blocks",
+        "standalone contracts",
+        ...(hasPostMeta ? ["post meta contracts"] : []),
+        ...(hasRestResources ? ["plugin-level REST resources"] : []),
+        ...(hasAiFeatures ? ["AI features"] : []),
+    ]);
+    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;
+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);
+}
+function insertStandaloneContractFilter(nextSource, syncRestScriptPath) {
+    if (nextSource.includes("const standaloneContracts = CONTRACTS.filter")) {
+        return nextSource;
+    }
+    const restResourcesFilter = "const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );";
+    if (nextSource.includes(restResourcesFilter)) {
+        return nextSource.replace(restResourcesFilter, [
+            "const standaloneContracts = CONTRACTS.filter( isWorkspaceStandaloneContract );",
+            restResourcesFilter,
+        ].join("\n\t"));
+    }
+    const restBlocksFilter = "const restBlocks = BLOCKS.filter( isRestEnabledBlock );";
+    return replaceRequiredContractSyncRestSource(nextSource, "const standaloneContracts = CONTRACTS.filter", restBlocksFilter, [
+        restBlocksFilter,
+        "const standaloneContracts = CONTRACTS.filter( isWorkspaceStandaloneContract );",
+    ].join("\n\t"), "restBlocks filter", syncRestScriptPath);
+}
+function insertStandaloneContractNoResourcesGuard(nextSource, syncRestScriptPath) {
+    const hasRestResources = nextSource.includes("const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );");
+    const hasAiFeatures = nextSource.includes("const aiFeatures = AI_FEATURES.filter( isWorkspaceAiFeature );");
+    const hasPostMeta = nextSource.includes("const postMetaContracts = POST_META.filter( isWorkspacePostMetaContract );");
+    return replaceNoResourcesGuard(nextSource, buildContractNoResourcesGuard({
+        hasAiFeatures,
+        hasPostMeta,
+        hasRestResources,
+    }), "ensureContractSyncScriptAnchors", syncRestScriptPath, "CONTRACTS");
+}
+function buildRestResourceNoResourcesGuard({ hasAiFeatures, hasPostMeta, hasStandaloneContracts, }) {
+    const condition = ["restBlocks.length === 0"];
+    if (hasStandaloneContracts) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("standaloneContracts.length === 0");
+    }
+    if (hasPostMeta) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("postMetaContracts.length === 0");
+    }
+    condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+    condition.push("restResources.length === 0");
+    if (hasAiFeatures) {
+        condition[condition.length - 1] = `${condition[condition.length - 1]} &&`;
+        condition.push("aiFeatures.length === 0");
+    }
+    const noResourcesSubject = formatNoResourcesSubject([
+        "REST-enabled workspace blocks",
+        ...(hasStandaloneContracts ? ["standalone contracts"] : []),
+        ...(hasPostMeta ? ["post meta contracts"] : []),
+        "plugin-level REST resources",
+        ...(hasAiFeatures ? ["AI features"] : []),
+    ]);
+    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");
+}
+function insertRestResourceNoResourcesGuard(nextSource, syncRestScriptPath) {
+    const hasStandaloneContracts = nextSource.includes("const standaloneContracts = CONTRACTS.filter( isWorkspaceStandaloneContract );");
+    const hasAiFeatures = nextSource.includes("const aiFeatures = AI_FEATURES.filter( isWorkspaceAiFeature );");
+    const hasPostMeta = nextSource.includes("const postMetaContracts = POST_META.filter( isWorkspacePostMetaContract );");
+    return replaceNoResourcesGuard(nextSource, buildRestResourceNoResourcesGuard({
+        hasAiFeatures,
+        hasPostMeta,
+        hasStandaloneContracts,
+    }), "ensureRestResourceSyncScriptAnchors", syncRestScriptPath, "REST_RESOURCES");
+}
+function insertStandaloneContractSyncLoop(nextSource, syncRestScriptPath) {
+    if (nextSource.includes("for ( const contract of standaloneContracts )")) {
+        return nextSource;
+    }
+    const loopSource = [
+        "\tfor ( const contract of standaloneContracts ) {",
+        "\t\tawait syncTypeSchemas(",
+        "\t\t\t{",
+        "\t\t\t\tjsonSchemaFile: contract.schemaFile,",
+        "\t\t\t\tsourceTypeName: contract.sourceTypeName,",
+        "\t\t\t\ttypesFile: contract.typesFile,",
+        "\t\t\t},",
+        "\t\t\t{",
+        "\t\t\t\tcheck: options.check,",
+        "\t\t\t}",
+        "\t\t);",
+        "\t}",
+    ].join("\n");
+    const resourceLoopAnchor = "\n\tfor ( const resource of restResources ) {";
+    if (nextSource.includes(resourceLoopAnchor)) {
+        return nextSource.replace(resourceLoopAnchor, `\n${loopSource}\n${resourceLoopAnchor}`);
+    }
+    const consoleLogPattern = /\n\tconsole\.log\(\n\t\toptions\.check/u;
+    return replaceRequiredContractSyncRestSource(nextSource, "for ( const contract of standaloneContracts )", consoleLogPattern, [
+        "",
+        loopSource,
+        "",
+        "\tconsole.log(",
+        "\t\toptions.check",
+    ].join("\n"), "success log insertion point", syncRestScriptPath);
+}
+export async function ensureContractSyncScriptAnchors(workspace) {
+    const syncRestScriptPath = path.join(workspace.projectDir, "scripts", "sync-rest-contracts.ts");
+    await patchFile(syncRestScriptPath, (source) => {
+        let nextSource = replaceBlockConfigImportForContracts(source, syncRestScriptPath);
+        const helperInsertionAnchor = "async function assertTypeArtifactsCurrent";
+        nextSource = replaceRequiredContractSyncRestSource(nextSource, "function isWorkspaceStandaloneContract(", helperInsertionAnchor, [
+            "function isWorkspaceStandaloneContract(",
+            "\tcontract: WorkspaceContractConfig",
+            "): contract is WorkspaceContractConfig & {",
+            "\tschemaFile: string;",
+            "\tsourceTypeName: string;",
+            "\ttypesFile: string;",
+            "} {",
+            "\treturn (",
+            "\t\ttypeof contract.schemaFile === 'string' &&",
+            "\t\ttypeof contract.sourceTypeName === 'string' &&",
+            "\t\ttypeof contract.typesFile === 'string'",
+            "\t);",
+            "}",
+            "",
+            "async function assertTypeArtifactsCurrent",
+        ].join("\n"), "type artifact assertion helper", syncRestScriptPath);
+        nextSource = insertStandaloneContractFilter(nextSource, syncRestScriptPath);
+        nextSource = insertStandaloneContractNoResourcesGuard(nextSource, syncRestScriptPath);
+        nextSource = insertStandaloneContractSyncLoop(nextSource, syncRestScriptPath);
+        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents are already up to date for workspace blocks and plugin-level resources!", "✅ REST contract schemas, standalone schemas, portable API clients, and endpoint-aware OpenAPI documents are already up to date for workspace blocks, standalone contracts, and plugin-level resources!");
+        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents generated for workspace blocks and plugin-level resources!", "✅ REST contract schemas, standalone schemas, portable API clients, and endpoint-aware OpenAPI documents generated for workspace blocks, standalone contracts, and plugin-level resources!");
+        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents are already up to date with the TypeScript types!", "✅ REST contract schemas, standalone schemas, portable API clients, and endpoint-aware OpenAPI documents are already up to date with the TypeScript types!");
+        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents generated from TypeScript types!", "✅ REST contract schemas, standalone schemas, portable API clients, and endpoint-aware OpenAPI documents generated from TypeScript types!");
+        return nextSource;
+    });
+}
 export async function ensureRestResourceSyncScriptAnchors(workspace) {
     const syncRestScriptPath = path.join(workspace.projectDir, "scripts", "sync-rest-contracts.ts");
     await patchFile(syncRestScriptPath, (source) => {
-        let nextSource = source;
-        const importAnchor = "import { BLOCKS, type WorkspaceBlockConfig } from './block-config';";
+        let nextSource = replaceBlockConfigImportForRestResources(source, syncRestScriptPath);
         const helperInsertionAnchor = "async function assertTypeArtifactsCurrent";
         const restBlocksAnchor = "const restBlocks = BLOCKS.filter( isRestEnabledBlock );";
-        const noResourcesPattern = /if \( restBlocks.length === 0 \) \{[\s\S]*?\n\t\treturn;\n\t\}/u;
         const consoleLogPattern = /\n\tconsole\.log\(\n\t\toptions\.check/u;
-        nextSource = replaceRequiredSyncRestSource(nextSource, "REST_RESOURCES", importAnchor, [
-            "import {",
-            "\tBLOCKS,",
-            "\tREST_RESOURCES,",
-            "\ttype WorkspaceBlockConfig,",
-            "\ttype WorkspaceRestResourceConfig,",
-            "} from './block-config';",
-        ].join("\n"), "BLOCKS import", syncRestScriptPath);
         nextSource = replaceRequiredSyncRestSource(nextSource, "function isWorkspaceRestResource(", helperInsertionAnchor, [
             "function isWorkspaceRestResource(",
             "\tresource: WorkspaceRestResourceConfig",
@@ -93,16 +366,7 @@ export async function ensureRestResourceSyncScriptAnchors(workspace) {
             "const restBlocks = BLOCKS.filter( isRestEnabledBlock );",
             "const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );",
         ].join("\n"), "restBlocks filter", syncRestScriptPath);
-        nextSource = replaceRequiredSyncRestSource(nextSource, "restBlocks.length === 0 && restResources.length === 0", noResourcesPattern, [
-            "if ( restBlocks.length === 0 && restResources.length === 0 ) {",
-            "\t\tconsole.log(",
-            "\t\t\toptions.check",
-            "\t\t\t\t? 'ℹ️ No REST-enabled workspace blocks or plugin-level REST resources are registered yet. `sync-rest --check` is already clean.'",
-            "\t\t\t\t: 'ℹ️ No REST-enabled workspace blocks or plugin-level REST resources are registered yet.'",
-            "\t\t);",
-            "\t\treturn;",
-            "\t}",
-        ].join("\n"), "no-resources guard", syncRestScriptPath);
+        nextSource = insertRestResourceNoResourcesGuard(nextSource, syncRestScriptPath);
         nextSource = replaceRequiredSyncRestSource(nextSource, "for ( const resource of restResources ) {", consoleLogPattern, [
             "",
             "\tfor ( const resource of restResources ) {",

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

@@ -1,5 +1,93 @@
-import { type RestResourceMethodId } from "./cli-add-shared.js";
-export declare function buildRestResourceConfigEntry(restResourceSlug: string, namespace: string, methods: RestResourceMethodId[]): string;
+import { type ManualRestContractAuthId, type ManualRestContractHttpMethodId, type RestResourceMethodId } from "./cli-add-shared.js";
+/**
+ * Build a generated REST resource config entry for `scripts/block-config.ts`.
+ *
+ * @param options REST resource metadata. `restResourceSlug`, `namespace`, and
+ * `methods` are required; `controllerClass`, `controllerExtends`,
+ * `permissionCallback`, and `routePattern` opt into generated controller,
+ * permission, and item-route escape hatches.
+ * @returns TypeScript object literal source for one generated REST resource entry.
+ */
+export declare function buildRestResourceConfigEntry(options: {
+    controllerClass?: string;
+    controllerExtends?: string;
+    methods: RestResourceMethodId[];
+    namespace: string;
+    permissionCallback?: string;
+    restResourceSlug: string;
+    routePattern?: string;
+}): string;
+/**
+ * Build the `REST_RESOURCES` config entry appended for a manual REST contract.
+ *
+ * @param options Manual contract file, route, type, and auth metadata.
+ * @param options.auth Auth intent stored in the endpoint manifest.
+ * @param options.bodyTypeName Optional exported body type name.
+ * @param options.method Uppercase HTTP method for the external route.
+ * @param options.namespace REST namespace such as `vendor/v1`.
+ * @param options.pathPattern Route pattern relative to the namespace.
+ * @param options.queryTypeName Exported query type name.
+ * @param options.responseTypeName Exported response type name.
+ * @param options.restResourceSlug Normalized workspace REST contract slug.
+ * @returns A TypeScript object literal string for `scripts/block-config.ts`.
+ */
+export declare function buildManualRestContractConfigEntry(options: {
+    auth: ManualRestContractAuthId;
+    bodyTypeName?: string;
+    method: ManualRestContractHttpMethodId;
+    namespace: string;
+    pathPattern: string;
+    queryTypeName: string;
+    responseTypeName: string;
+    restResourceSlug: string;
+    secretFieldName?: string;
+    secretStateFieldName?: string;
+}): string;
+/**
+ * Build the editable TypeScript type source for a manual REST contract.
+ *
+ * @param options Manual contract type naming metadata.
+ * @param options.bodyTypeName Optional exported body type name.
+ * @param options.queryTypeName Exported query type name.
+ * @param options.responseTypeName Exported response type name.
+ * @param options.restResourceSlug Normalized workspace REST contract slug.
+ * @param options.secretFieldName Optional raw secret field included only in the request body.
+ * @param options.secretStateFieldName Optional masked response boolean field.
+ * @returns TypeScript source for `api-types.ts`.
+ */
+export declare function buildManualRestContractTypesSource(options: {
+    bodyTypeName?: string;
+    queryTypeName: string;
+    responseTypeName: string;
+    restResourceSlug: string;
+    secretFieldName?: string;
+    secretStateFieldName?: string;
+}): string;
+/**
+ * Build Typia validator source for a manual REST contract.
+ *
+ * @param options Manual contract type names to validate.
+ * @param options.bodyTypeName Optional exported body type name.
+ * @param options.queryTypeName Exported query type name.
+ * @param options.responseTypeName Exported response type name.
+ * @returns TypeScript source for `api-validators.ts`.
+ */
+export declare function buildManualRestContractValidatorsSource(options: {
+    bodyTypeName?: string;
+    queryTypeName: string;
+    responseTypeName: string;
+}): string;
+/**
+ * Build the public API shim for a manual REST contract.
+ *
+ * @param options Manual REST contract operation and request type metadata.
+ * @returns TypeScript source that re-exports the generated endpoint client.
+ */
+export declare function buildManualRestContractApiSource(options: {
+    bodyTypeName?: string;
+    queryTypeName: string;
+    restResourceSlug: string;
+}): string;
 export declare function buildRestResourceTypesSource(restResourceSlug: string, methods: RestResourceMethodId[]): string;
 export declare function buildRestResourceValidatorsSource(restResourceSlug: string, methods: RestResourceMethodId[]): string;
 export declare function buildRestResourceApiSource(restResourceSlug: string, methods: RestResourceMethodId[]): string;