@wp-typia/project-tools 0.19.1 → 0.19.3

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

@@ -1,393 +1,16 @@
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { ensureBlockConfigCanAddRestManifests } from "./cli-add-block-legacy-validator.js";
-import { assertRestResourceDoesNotExist, assertValidGeneratedSlug, assertValidRestResourceMethods, getWorkspaceBootstrapPath, normalizeBlockSlug, patchFile, quoteTsString, resolveRestResourceNamespace, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
-import { buildRestResourceEndpointManifest, syncRestResourceArtifacts } from "./rest-resource-artifacts.js";
+import { assertRestResourceDoesNotExist, assertValidGeneratedSlug, assertValidRestResourceMethods, getWorkspaceBootstrapPath, normalizeBlockSlug, resolveRestResourceNamespace, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ensureRestResourceBootstrapAnchors, ensureRestResourceSyncScriptAnchors, } from "./cli-add-workspace-rest-anchors.js";
+import { buildRestResourceApiSource, buildRestResourceConfigEntry, buildRestResourceDataSource, buildRestResourceTypesSource, buildRestResourceValidatorsSource, toPascalCaseFromSlug, } from "./cli-add-workspace-rest-source-emitters.js";
+import { syncRestResourceArtifacts } from "./rest-resource-artifacts.js";
 import { toTitleCase } from "./string-case.js";
 import { appendWorkspaceInventoryEntries, readWorkspaceInventory, } from "./workspace-inventory.js";
-import { resolveWorkspaceProject, } from "./workspace-project.js";
-const REST_RESOURCE_SERVER_GLOB = "/inc/rest/*.php";
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-}
+import { resolveWorkspaceProject } from "./workspace-project.js";
 function quotePhpString(value) {
     return `'${value.replace(/\\/gu, "\\\\").replace(/'/gu, "\\'")}'`;
 }
-function toPascalCaseFromSlug(slug) {
-    return normalizeBlockSlug(slug)
-        .split("-")
-        .filter(Boolean)
-        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
-        .join("");
-}
-function indentMultiline(source, prefix) {
-    return source
-        .split("\n")
-        .map((line) => `${prefix}${line}`)
-        .join("\n");
-}
-function buildRestResourceConfigEntry(restResourceSlug, namespace, methods) {
-    const pascalCase = toPascalCaseFromSlug(restResourceSlug);
-    const title = toTitleCase(restResourceSlug);
-    const manifest = buildRestResourceEndpointManifest({
-        namespace,
-        pascalCase,
-        slugKebabCase: restResourceSlug,
-        title,
-    }, methods);
-    return [
-        "\t{",
-        `\t\tapiFile: ${quoteTsString(`src/rest/${restResourceSlug}/api.ts`)},`,
-        `\t\tclientFile: ${quoteTsString(`src/rest/${restResourceSlug}/api-client.ts`)},`,
-        `\t\tdataFile: ${quoteTsString(`src/rest/${restResourceSlug}/data.ts`)},`,
-        `\t\tmethods: [ ${methods.map((method) => quoteTsString(method)).join(", ")} ],`,
-        `\t\tnamespace: ${quoteTsString(namespace)},`,
-        `\t\topenApiFile: ${quoteTsString(`src/rest/${restResourceSlug}/api.openapi.json`)},`,
-        `\t\tphpFile: ${quoteTsString(`inc/rest/${restResourceSlug}.php`)},`,
-        "\t\trestManifest: defineEndpointManifest(",
-        indentMultiline(JSON.stringify(manifest, null, "\t"), "\t\t\t"),
-        "\t\t),",
-        `\t\tslug: ${quoteTsString(restResourceSlug)},`,
-        `\t\ttypesFile: ${quoteTsString(`src/rest/${restResourceSlug}/api-types.ts`)},`,
-        `\t\tvalidatorsFile: ${quoteTsString(`src/rest/${restResourceSlug}/api-validators.ts`)},`,
-        "\t},",
-    ].join("\n");
-}
-function buildRestResourceTypesSource(restResourceSlug, methods) {
-    const pascalCase = toPascalCaseFromSlug(restResourceSlug);
-    const lines = [
-        "import { tags } from 'typia';",
-        "",
-        `export type ${pascalCase}Status = 'draft' | 'published';`,
-        "",
-        `export interface ${pascalCase}Record {`,
-        "\tid: number & tags.Type< 'uint32' >;",
-        "\ttitle: string & tags.MinLength< 1 > & tags.MaxLength< 120 >;",
-        "\tcontent?: string & tags.MaxLength< 2000 >;",
-        `\tstatus: ${pascalCase}Status;`,
-        "\tupdatedAt: string;",
-        "}",
-    ];
-    if (methods.includes("list")) {
-        lines.push("", `export interface ${pascalCase}ListQuery {`, "\tpage?: number & tags.Type< 'uint32' > & tags.Minimum< 1 > & tags.Default< 1 >;", "\tperPage?: number & tags.Type< 'uint32' > & tags.Minimum< 1 > & tags.Maximum< 50 > & tags.Default< 10 >;", "\tsearch?: string & tags.MaxLength< 120 >;", "}", "", `export interface ${pascalCase}ListResponse {`, `\titems: ${pascalCase}Record[];`, "\tpage: number & tags.Type< 'uint32' >;", "\tperPage: number & tags.Type< 'uint32' >;", "\ttotal: number & tags.Type< 'uint32' >;", "}");
-    }
-    if (methods.includes("read")) {
-        lines.push("", `export interface ${pascalCase}ReadQuery {`, "\tid: number & tags.Type< 'uint32' >;", "}", "", `export type ${pascalCase}ReadResponse = ${pascalCase}Record;`);
-    }
-    if (methods.includes("create")) {
-        lines.push("", `export interface ${pascalCase}CreateRequest {`, "\ttitle: string & tags.MinLength< 1 > & tags.MaxLength< 120 >;", "\tcontent?: string & tags.MaxLength< 2000 >;", `\tstatus?: ${pascalCase}Status;`, "}", "", `export type ${pascalCase}CreateResponse = ${pascalCase}Record;`);
-    }
-    if (methods.includes("update")) {
-        lines.push("", `export interface ${pascalCase}UpdateQuery {`, "\tid: number & tags.Type< 'uint32' >;", "}", "", `export interface ${pascalCase}UpdateRequest {`, "\ttitle?: string & tags.MinLength< 1 > & tags.MaxLength< 120 >;", "\tcontent?: string & tags.MaxLength< 2000 >;", `\tstatus?: ${pascalCase}Status;`, "}", "", `export type ${pascalCase}UpdateResponse = ${pascalCase}Record;`);
-    }
-    if (methods.includes("delete")) {
-        lines.push("", `export interface ${pascalCase}DeleteQuery {`, "\tid: number & tags.Type< 'uint32' >;", "}", "", `export interface ${pascalCase}DeleteResponse {`, "\tdeleted: true;", "\tid: number & tags.Type< 'uint32' >;", "}");
-    }
-    return `${lines.join("\n")}\n`;
-}
-function buildRestResourceValidatorsSource(restResourceSlug, methods) {
-    const pascalCase = toPascalCaseFromSlug(restResourceSlug);
-    const importedTypes = new Set();
-    const validatorDeclarations = [];
-    const validatorEntries = [];
-    const addValidator = (propertyName, typeName, validateIdentifier) => {
-        importedTypes.add(typeName);
-        validatorDeclarations.push(`const ${validateIdentifier} = typia.createValidate< ${typeName} >();`);
-        validatorEntries.push(`\t${propertyName}: ( input: unknown ) => toValidationResult< ${typeName} >( ${validateIdentifier}( input ) ),`);
-    };
-    if (methods.includes("list")) {
-        addValidator("listQuery", `${pascalCase}ListQuery`, "validateListQuery");
-        addValidator("listResponse", `${pascalCase}ListResponse`, "validateListResponse");
-    }
-    if (methods.includes("read")) {
-        addValidator("readQuery", `${pascalCase}ReadQuery`, "validateReadQuery");
-        addValidator("readResponse", `${pascalCase}ReadResponse`, "validateReadResponse");
-    }
-    if (methods.includes("create")) {
-        addValidator("createRequest", `${pascalCase}CreateRequest`, "validateCreateRequest");
-        addValidator("createResponse", `${pascalCase}CreateResponse`, "validateCreateResponse");
-    }
-    if (methods.includes("update")) {
-        addValidator("updateQuery", `${pascalCase}UpdateQuery`, "validateUpdateQuery");
-        addValidator("updateRequest", `${pascalCase}UpdateRequest`, "validateUpdateRequest");
-        addValidator("updateResponse", `${pascalCase}UpdateResponse`, "validateUpdateResponse");
-    }
-    if (methods.includes("delete")) {
-        addValidator("deleteQuery", `${pascalCase}DeleteQuery`, "validateDeleteQuery");
-        addValidator("deleteResponse", `${pascalCase}DeleteResponse`, "validateDeleteResponse");
-    }
-    return `import typia from 'typia';
-
-import { toValidationResult } from '@wp-typia/rest';
-import type {
-\t${Array.from(importedTypes).sort().join(",\n\t")},
-} from './api-types';
-
-${validatorDeclarations.join("\n")}
-
-export const apiValidators = {
-${validatorEntries.join("\n")}
-};
-`;
-}
-function buildRestResourceApiSource(restResourceSlug, methods) {
-    const pascalCase = toPascalCaseFromSlug(restResourceSlug);
-    const typeImports = new Set();
-    const clientEndpointImports = [];
-    const exportedBindings = [];
-    const writeMethods = methods.filter((method) => ["create", "update", "delete"].includes(method));
-    if (methods.includes("list")) {
-        typeImports.add(`${pascalCase}ListQuery`);
-        clientEndpointImports.push(`list${pascalCase}ResourcesEndpoint`);
-        exportedBindings.push(`export const restResourceListEndpoint = {
-\t...list${pascalCase}ResourcesEndpoint,
-\tbuildRequestOptions: () => ( {
-\t\turl: resolveRestRouteUrl( list${pascalCase}ResourcesEndpoint.path ),
-\t} ),
-};
-
-export function listResource( request: ${pascalCase}ListQuery ) {
-\treturn callEndpoint( restResourceListEndpoint, request );
-}`);
-    }
-    if (methods.includes("read")) {
-        typeImports.add(`${pascalCase}ReadQuery`);
-        clientEndpointImports.push(`read${pascalCase}ResourceEndpoint`);
-        exportedBindings.push(`export const restResourceReadEndpoint = {
-\t...read${pascalCase}ResourceEndpoint,
-\tbuildRequestOptions: () => ( {
-\t\turl: resolveRestRouteUrl( read${pascalCase}ResourceEndpoint.path ),
-\t} ),
-};
-
-export function readResource( request: ${pascalCase}ReadQuery ) {
-\treturn callEndpoint( restResourceReadEndpoint, request );
-}`);
-    }
-    if (methods.includes("create")) {
-        typeImports.add(`${pascalCase}CreateRequest`);
-        clientEndpointImports.push(`create${pascalCase}ResourceEndpoint`);
-        exportedBindings.push(`export const restResourceCreateEndpoint = {
-\t...create${pascalCase}ResourceEndpoint,
-\tbuildRequestOptions: () => {
-\t\tconst nonce = resolveRestNonce();
-\t\treturn {
-\t\t\theaders: nonce
-\t\t\t\t? {
-\t\t\t\t\t'X-WP-Nonce': nonce,
-\t\t\t\t}
-\t\t\t\t: undefined,
-\t\t\turl: resolveRestRouteUrl( create${pascalCase}ResourceEndpoint.path ),
-\t\t};
-\t},
-};
-
-export function createResource( request: ${pascalCase}CreateRequest ) {
-\treturn callEndpoint( restResourceCreateEndpoint, request );
-}`);
-    }
-    if (methods.includes("update")) {
-        typeImports.add(`${pascalCase}UpdateQuery`);
-        typeImports.add(`${pascalCase}UpdateRequest`);
-        clientEndpointImports.push(`update${pascalCase}ResourceEndpoint`);
-        exportedBindings.push(`export const restResourceUpdateEndpoint = {
-\t...update${pascalCase}ResourceEndpoint,
-\tbuildRequestOptions: () => {
-\t\tconst nonce = resolveRestNonce();
-\t\treturn {
-\t\t\theaders: nonce
-\t\t\t\t? {
-\t\t\t\t\t'X-WP-Nonce': nonce,
-\t\t\t\t}
-\t\t\t\t: undefined,
-\t\t\turl: resolveRestRouteUrl( update${pascalCase}ResourceEndpoint.path ),
-\t\t};
-\t},
-};
-
-export function updateResource( request: {
-\tbody: ${pascalCase}UpdateRequest;
-\tquery: ${pascalCase}UpdateQuery;
-} ) {
-\treturn callEndpoint( restResourceUpdateEndpoint, request );
-}`);
-    }
-    if (methods.includes("delete")) {
-        typeImports.add(`${pascalCase}DeleteQuery`);
-        clientEndpointImports.push(`delete${pascalCase}ResourceEndpoint`);
-        exportedBindings.push(`export const restResourceDeleteEndpoint = {
-\t...delete${pascalCase}ResourceEndpoint,
-\tbuildRequestOptions: () => {
-\t\tconst nonce = resolveRestNonce();
-\t\treturn {
-\t\t\theaders: nonce
-\t\t\t\t? {
-\t\t\t\t\t'X-WP-Nonce': nonce,
-\t\t\t\t}
-\t\t\t\t: undefined,
-\t\t\turl: resolveRestRouteUrl( delete${pascalCase}ResourceEndpoint.path ),
-\t\t};
-\t},
-};
-
-export function deleteResource( request: ${pascalCase}DeleteQuery ) {
-\treturn callEndpoint( restResourceDeleteEndpoint, request );
-}`);
-    }
-    return `import {
-\tcallEndpoint,
-\tresolveRestRouteUrl,
-} from '@wp-typia/rest';
-
-import type {
-\t${Array.from(typeImports).sort().join(",\n\t")},
-} from './api-types';
-import {
-\t${clientEndpointImports.sort().join(",\n\t")},
-} from './api-client';
-${writeMethods.length > 0
-        ? `
-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;
-}
-`
-        : ""}
-${exportedBindings.join("\n\n")}
-`;
-}
-function buildRestResourceDataSource(restResourceSlug, methods) {
-    const pascalCase = toPascalCaseFromSlug(restResourceSlug);
-    const typeImports = new Set();
-    const endpointImports = [];
-    const exportedBindings = [];
-    if (methods.includes("list")) {
-        typeImports.add(`${pascalCase}ListQuery`);
-        typeImports.add(`${pascalCase}ListResponse`);
-        endpointImports.push("restResourceListEndpoint");
-        exportedBindings.push(`export type Use${pascalCase}ListQueryOptions<
-\tSelected = ${pascalCase}ListResponse,
-> = UseEndpointQueryOptions<
-\t${pascalCase}ListQuery,
-\t${pascalCase}ListResponse,
-\tSelected
->;
-
-export function use${pascalCase}ListQuery<
-\tSelected = ${pascalCase}ListResponse,
->(
-\trequest: ${pascalCase}ListQuery,
-\toptions: Use${pascalCase}ListQueryOptions< Selected > = {}
-) {
-\treturn useEndpointQuery( restResourceListEndpoint, request, options );
-}`);
-    }
-    if (methods.includes("read")) {
-        typeImports.add(`${pascalCase}ReadQuery`);
-        typeImports.add(`${pascalCase}ReadResponse`);
-        endpointImports.push("restResourceReadEndpoint");
-        exportedBindings.push(`export type Use${pascalCase}ReadQueryOptions<
-\tSelected = ${pascalCase}ReadResponse,
-> = UseEndpointQueryOptions<
-\t${pascalCase}ReadQuery,
-\t${pascalCase}ReadResponse,
-\tSelected
->;
-
-export function use${pascalCase}ReadQuery<
-\tSelected = ${pascalCase}ReadResponse,
->(
-\trequest: ${pascalCase}ReadQuery,
-\toptions: Use${pascalCase}ReadQueryOptions< Selected > = {}
-) {
-\treturn useEndpointQuery( restResourceReadEndpoint, request, options );
-}`);
-    }
-    if (methods.includes("create")) {
-        typeImports.add(`${pascalCase}CreateRequest`);
-        typeImports.add(`${pascalCase}CreateResponse`);
-        endpointImports.push("restResourceCreateEndpoint");
-        exportedBindings.push(`export type UseCreate${pascalCase}ResourceMutationOptions = UseEndpointMutationOptions<
-\t${pascalCase}CreateRequest,
-\t${pascalCase}CreateResponse,
-\tunknown
->;
-
-export function useCreate${pascalCase}ResourceMutation(
-\toptions: UseCreate${pascalCase}ResourceMutationOptions = {}
-) {
-\treturn useEndpointMutation( restResourceCreateEndpoint, options );
-}`);
-    }
-    if (methods.includes("update")) {
-        typeImports.add(`${pascalCase}UpdateQuery`);
-        typeImports.add(`${pascalCase}UpdateRequest`);
-        typeImports.add(`${pascalCase}UpdateResponse`);
-        endpointImports.push("restResourceUpdateEndpoint");
-        exportedBindings.push(`export type UseUpdate${pascalCase}ResourceMutationOptions = UseEndpointMutationOptions<
-\t{
-\t\tbody: ${pascalCase}UpdateRequest;
-\t\tquery: ${pascalCase}UpdateQuery;
-\t},
-\t${pascalCase}UpdateResponse,
-\tunknown
->;
-
-export function useUpdate${pascalCase}ResourceMutation(
-\toptions: UseUpdate${pascalCase}ResourceMutationOptions = {}
-) {
-\treturn useEndpointMutation( restResourceUpdateEndpoint, options );
-}`);
-    }
-    if (methods.includes("delete")) {
-        typeImports.add(`${pascalCase}DeleteQuery`);
-        typeImports.add(`${pascalCase}DeleteResponse`);
-        endpointImports.push("restResourceDeleteEndpoint");
-        exportedBindings.push(`export type UseDelete${pascalCase}ResourceMutationOptions = UseEndpointMutationOptions<
-\t${pascalCase}DeleteQuery,
-\t${pascalCase}DeleteResponse,
-\tunknown
->;
-
-export function useDelete${pascalCase}ResourceMutation(
-\toptions: UseDelete${pascalCase}ResourceMutationOptions = {}
-) {
-\treturn useEndpointMutation( restResourceDeleteEndpoint, options );
-}`);
-    }
-    return `import {
-\tuseEndpointMutation,
-\tuseEndpointQuery,
-\ttype UseEndpointMutationOptions,
-\ttype UseEndpointQueryOptions,
-} from '@wp-typia/rest/react';
-
-import type {
-\t${Array.from(typeImports).sort().join(",\n\t")},
-} from './api-types';
-import {
-\t${endpointImports.sort().join(",\n\t")},
-} from './api';
-
-${exportedBindings.join("\n\n")}
-`;
-}
 function buildRestResourceRouteRegistrations(restResourceSlug, methods, functions) {
     const collectionRoutes = [];
     const itemRoutes = [];
@@ -801,188 +424,6 @@ ${routeRegistrations}
 add_action( 'rest_api_init', '${registerRoutesFunctionName}' );
 `;
 }
-async function ensureRestResourceBootstrapAnchors(workspace) {
-    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
-    await patchFile(bootstrapPath, (source) => {
-        let nextSource = source;
-        const registerFunctionName = `${workspace.workspace.phpPrefix}_register_rest_resources`;
-        const registerHook = `add_action( 'init', '${registerFunctionName}', 20 );`;
-        const registerFunction = `
-
-function ${registerFunctionName}() {
-\tforeach ( glob( __DIR__ . '${REST_RESOURCE_SERVER_GLOB}' ) ?: array() as $rest_resource_module ) {
-\t\trequire_once $rest_resource_module;
-\t}
-}
-`;
-        const insertionAnchors = [
-            /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
-            /\?>\s*$/u,
-        ];
-        const hasPhpFunctionDefinition = (functionName) => new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\(`, "u").test(nextSource);
-        const insertPhpSnippet = (snippet) => {
-            for (const anchor of insertionAnchors) {
-                const candidate = nextSource.replace(anchor, (match) => `${snippet}\n${match}`);
-                if (candidate !== nextSource) {
-                    nextSource = candidate;
-                    return;
-                }
-            }
-            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
-        };
-        const appendPhpSnippet = (snippet) => {
-            const closingTagPattern = /\?>\s*$/u;
-            if (closingTagPattern.test(nextSource)) {
-                nextSource = nextSource.replace(closingTagPattern, `${snippet}\n?>`);
-                return;
-            }
-            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
-        };
-        if (!hasPhpFunctionDefinition(registerFunctionName)) {
-            insertPhpSnippet(registerFunction);
-        }
-        else if (!nextSource.includes(REST_RESOURCE_SERVER_GLOB)) {
-            throw new Error([
-                `Unable to patch ${path.basename(bootstrapPath)} in ensureRestResourceBootstrapAnchors.`,
-                `The existing ${registerFunctionName}() definition does not include ${REST_RESOURCE_SERVER_GLOB}.`,
-                "Restore the generated bootstrap shape or wire the REST resource loader manually before retrying.",
-            ].join(" "));
-        }
-        if (!nextSource.includes(registerHook)) {
-            appendPhpSnippet(registerHook);
-        }
-        return nextSource;
-    });
-}
-function assertSyncRestAnchor(nextSource, target, anchorDescription, hasAnchor, syncRestScriptPath) {
-    if (!nextSource.includes(target) && !hasAnchor) {
-        throw new Error([
-            `ensureRestResourceSyncScriptAnchors could not patch ${path.basename(syncRestScriptPath)}.`,
-            `Missing expected ${anchorDescription} anchor in scripts/sync-rest-contracts.ts.`,
-            "Restore the generated template or add the REST_RESOURCES wiring manually before retrying.",
-        ].join(" "));
-    }
-}
-function replaceRequiredSyncRestSource(nextSource, target, anchor, replacement, anchorDescription, syncRestScriptPath) {
-    if (nextSource.includes(target)) {
-        return nextSource;
-    }
-    const hasAnchor = typeof anchor === "string" ? nextSource.includes(anchor) : anchor.test(nextSource);
-    assertSyncRestAnchor(nextSource, target, anchorDescription, hasAnchor, syncRestScriptPath);
-    return nextSource.replace(anchor, replacement);
-}
-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';";
-        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",
-            "): resource is WorkspaceRestResourceConfig & {",
-            "\tclientFile: string;",
-            "\topenApiFile: string;",
-            "\trestManifest: NonNullable< WorkspaceRestResourceConfig[ 'restManifest' ] >;",
-            "\ttypesFile: string;",
-            "\tvalidatorsFile: string;",
-            "} {",
-            "\treturn (",
-            "\t\ttypeof resource.clientFile === 'string' &&",
-            "\t\ttypeof resource.openApiFile === 'string' &&",
-            "\t\ttypeof resource.typesFile === 'string' &&",
-            "\t\ttypeof resource.validatorsFile === 'string' &&",
-            "\t\ttypeof resource.restManifest === 'object' &&",
-            "\t\tresource.restManifest !== null",
-            "\t);",
-            "}",
-            "",
-            "async function assertTypeArtifactsCurrent",
-        ].join("\n"), "type artifact assertion helper", syncRestScriptPath);
-        nextSource = replaceRequiredSyncRestSource(nextSource, "const restResources = REST_RESOURCES.filter( isWorkspaceRestResource );", restBlocksAnchor, [
-            "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 = replaceRequiredSyncRestSource(nextSource, "for ( const resource of restResources ) {", consoleLogPattern, [
-            "",
-            "\tfor ( const resource of restResources ) {",
-            "\t\tconst contracts = resource.restManifest.contracts;",
-            "",
-            "\t\tfor ( const [ baseName, contract ] of Object.entries( contracts ) ) {",
-            "\t\t\tawait syncTypeSchemas(",
-            "\t\t\t\t{",
-            "\t\t\t\t\tjsonSchemaFile: path.join(",
-            "\t\t\t\t\t\tpath.dirname( resource.typesFile ),",
-            "\t\t\t\t\t\t'api-schemas',",
-            "\t\t\t\t\t\t`${ baseName }.schema.json`",
-            "\t\t\t\t\t),",
-            "\t\t\t\t\topenApiFile: path.join(",
-            "\t\t\t\t\t\tpath.dirname( resource.typesFile ),",
-            "\t\t\t\t\t\t'api-schemas',",
-            "\t\t\t\t\t\t`${ baseName }.openapi.json`",
-            "\t\t\t\t\t),",
-            "\t\t\t\t\tsourceTypeName: contract.sourceTypeName,",
-            "\t\t\t\t\ttypesFile: resource.typesFile,",
-            "\t\t\t\t},",
-            "\t\t\t\t{",
-            "\t\t\t\t\tcheck: options.check,",
-            "\t\t\t\t}",
-            "\t\t\t);",
-            "\t\t}",
-            "",
-            "\t\tawait syncRestOpenApi(",
-            "\t\t\t{",
-            "\t\t\t\tmanifest: resource.restManifest,",
-            "\t\t\t\topenApiFile: resource.openApiFile,",
-            "\t\t\t\ttypesFile: resource.typesFile,",
-            "\t\t\t},",
-            "\t\t\t{",
-            "\t\t\t\tcheck: options.check,",
-            "\t\t\t}",
-            "\t\t);",
-            "",
-            "\t\tawait syncEndpointClient(",
-            "\t\t\t{",
-            "\t\t\t\tclientFile: resource.clientFile,",
-            "\t\t\t\tmanifest: resource.restManifest,",
-            "\t\t\t\ttypesFile: resource.typesFile,",
-            "\t\t\t\tvalidatorsFile: resource.validatorsFile,",
-            "\t\t\t},",
-            "\t\t\t{",
-            "\t\t\t\tcheck: options.check,",
-            "\t\t\t}",
-            "\t\t);",
-            "\t}",
-            "",
-            "\tconsole.log(",
-            "\t\toptions.check",
-        ].join("\n"), "success log insertion point", syncRestScriptPath);
-        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, portable API clients, and endpoint-aware OpenAPI documents are already up to date for workspace blocks and plugin-level resources!");
-        nextSource = nextSource.replace("✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents generated from TypeScript types!", "✅ REST contract schemas, portable API clients, and endpoint-aware OpenAPI documents generated for workspace blocks and plugin-level resources!");
-        return nextSource;
-    });
-}
 /**
  * Scaffold a workspace-level REST resource and synchronize its generated
  * TypeScript and PHP artifacts.

package/dist/runtime/cli-diagnostics.d.ts

@@ -17,6 +17,8 @@ export declare const CLI_DIAGNOSTIC_CODES: {
     readonly MISSING_ARGUMENT: "missing-argument";
     readonly MISSING_BUILD_ARTIFACT: "missing-build-artifact";
     readonly OUTSIDE_PROJECT_ROOT: "outside-project-root";
+    readonly TEMPLATE_SOURCE_TIMEOUT: "template-source-timeout";
+    readonly TEMPLATE_SOURCE_TOO_LARGE: "template-source-too-large";
     readonly UNSUPPORTED_COMMAND: "unsupported-command";
 };
 export type CliDiagnosticCode = (typeof CLI_DIAGNOSTIC_CODES)[keyof typeof CLI_DIAGNOSTIC_CODES];

package/dist/runtime/cli-diagnostics.js

@@ -8,12 +8,15 @@ export const CLI_DIAGNOSTIC_CODES = {
     MISSING_ARGUMENT: "missing-argument",
     MISSING_BUILD_ARTIFACT: "missing-build-artifact",
     OUTSIDE_PROJECT_ROOT: "outside-project-root",
+    TEMPLATE_SOURCE_TIMEOUT: "template-source-timeout",
+    TEMPLATE_SOURCE_TOO_LARGE: "template-source-too-large",
     UNSUPPORTED_COMMAND: "unsupported-command",
 };
 const DEFAULT_CLI_FAILURE_SUMMARIES = {
     add: "Unable to complete the requested add workflow.",
     create: "Unable to complete the requested create workflow.",
     doctor: "One or more doctor checks failed.",
+    init: "Unable to preview the requested retrofit init plan.",
     mcp: "Unable to inspect or sync MCP metadata.",
     migrate: "Unable to complete the requested migration command.",
     sync: "Unable to complete the requested sync workflow.",
@@ -168,10 +171,16 @@ function inferCliDiagnosticCode(options) {
     if (/dependencies have not been installed yet/u.test(haystack)) {
         return CLI_DIAGNOSTIC_CODES.DEPENDENCIES_NOT_INSTALLED;
     }
+    if (/Timed out while .*external template|Timed out while .*npm template|Timed out while .*GitHub template/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.TEMPLATE_SOURCE_TIMEOUT;
+    }
+    if (/external template size limit/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.TEMPLATE_SOURCE_TOO_LARGE;
+    }
     if (options.command === "doctor") {
         return CLI_DIAGNOSTIC_CODES.DOCTOR_CHECK_FAILED;
     }
-    if (/requires <|requires --/u.test(haystack)) {
+    if (/requires <|requires --|requires a value/u.test(haystack)) {
         return CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT;
     }
     if (/Unknown .*subcommand|Unknown add kind|Unknown template|removed in favor|does not support|The Bun-free fallback runtime does not support|The positional alias only accepts/u.test(haystack)) {

package/dist/runtime/cli-help.js

@@ -17,6 +17,7 @@ export function formatHelpText() {
   wp-typia create <project-dir> [--template persistence] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
   wp-typia create <project-dir> [--template compound] [--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>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
   wp-typia <project-dir> [create flags...]
+  wp-typia init [project-dir]
   wp-typia add block <name> --template <basic|interactivity|persistence|compound> [--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>]
   wp-typia add variation <name> --block <block-slug>
   wp-typia add pattern <name>
@@ -37,6 +38,7 @@ Package managers: ${PACKAGE_MANAGER_IDS.join(", ")}
 Notes:
   \`wp-typia create\` is the canonical scaffold command.
   \`wp-typia <project-dir>\` remains a backward-compatible alias to \`create\` when \`<project-dir>\` is the only positional argument.
+  \`wp-typia init\` is a preview-only retrofit planner for existing projects. It does not write files yet.
   Use \`--template workspace\` as shorthand for \`@wp-typia/create-workspace-template\`, the official empty workspace scaffold behind \`wp-typia add ...\`.
   \`query-loop\` is create-only. Use \`wp-typia create <project-dir> --template query-loop\`; \`wp-typia add block\` accepts only basic, interactivity, persistence, and compound families.
   \`add variation\` uses an existing workspace block from \`scripts/block-config.ts\`.
@@ -46,6 +48,7 @@ Notes:
   \`add editor-plugin\` scaffolds a document-level editor extension under \`src/editor-plugins/\`.
   \`add hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.
   \`wp-typia doctor\` always checks environment readiness and reports when it only ran environment-level diagnostics; official workspace roots also get inventory and source-tree drift checks.
+  \`wp-typia init\` previews the minimum sync/doctor/migration adoption layer for supported existing layouts before a future write mode exists.
   \`wp-typia migrate doctor --all\` checks migration target alignment, snapshots, fixtures, and generated migration artifacts.
   \`migrate\` is the canonical migration command; \`migrations\` is no longer supported.`;
 }