@wp-typia/project-tools 0.14.0 → 0.15.1

package/dist/runtime/cli-add.js

@@ -2,8 +2,9 @@ import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { defineEndpointManifest, syncBlockMetadata, syncEndpointClient, syncRestOpenApi, syncTypeSchemas, } from "@wp-typia/block-runtime/metadata-core";
+import { syncBlockMetadata, } from "@wp-typia/block-runtime/metadata-core";
 import { ensureMigrationDirectories, parseMigrationConfig, writeInitialMigrationScaffold, writeMigrationConfig, } from "./migration-project.js";
+import { syncPersistenceRestArtifacts, } from "./persistence-rest-artifacts.js";
 import { snapshotProjectVersion } from "./migrations.js";
 import { getDefaultAnswers, scaffoldProject } from "./scaffold.js";
 import { SHARED_WORKSPACE_TEMPLATE_ROOT, } from "./template-registry.js";
@@ -84,15 +85,21 @@ function buildPersistenceBlockConfigEntry(variables) {
         `\t\tattributeTypeName: ${quoteTsString(`${variables.pascalCase}Attributes`)},`,
         "\t\trestManifest: defineEndpointManifest( {",
         "\t\t\tcontracts: {",
+        "\t\t\t\t'bootstrap-query': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}BootstrapQuery`)},`,
+        "\t\t\t\t},",
+        "\t\t\t\t'bootstrap-response': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}BootstrapResponse`)},`,
+        "\t\t\t\t},",
         "\t\t\t\t'state-query': {",
         `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}StateQuery`)},`,
         "\t\t\t\t},",
-        "\t\t\t\t'write-state-request': {",
-        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}WriteStateRequest`)},`,
-        "\t\t\t\t},",
         "\t\t\t\t'state-response': {",
         `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}StateResponse`)},`,
         "\t\t\t\t},",
+        "\t\t\t\t'write-state-request': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}WriteStateRequest`)},`,
+        "\t\t\t\t},",
         "\t\t\t},",
         "\t\t\tendpoints: [",
         "\t\t\t\t{",
@@ -118,6 +125,16 @@ function buildPersistenceBlockConfigEntry(variables) {
         `\t\t\t\t\t\tmechanism: ${quoteTsString(variables.restWriteAuthMechanism)},`,
         "\t\t\t\t\t},",
         "\t\t\t\t},",
+        "\t\t\t\t{",
+        "\t\t\t\t\tauth: 'public',",
+        "\t\t\t\t\tmethod: 'GET',",
+        `\t\t\t\t\toperationId: ${quoteTsString(`get${variables.pascalCase}Bootstrap`)},`,
+        `\t\t\t\t\tpath: ${quoteTsString(`/${variables.namespace}/v1/${variables.slugKebabCase}/bootstrap`)},`,
+        "\t\t\t\t\tqueryContract: 'bootstrap-query',",
+        "\t\t\t\t\tresponseContract: 'bootstrap-response',",
+        `\t\t\t\t\tsummary: 'Read fresh session bootstrap state for the current viewer.',`,
+        `\t\t\t\t\ttags: [ ${quoteTsString(variables.title)} ],`,
+        "\t\t\t\t},",
         "\t\t\t],",
         "\t\t\tinfo: {",
         `\t\t\t\ttitle: ${quoteTsString(`${variables.title} REST API`)},`,
@@ -130,50 +147,6 @@ function buildPersistenceBlockConfigEntry(variables) {
         "\t},",
     ].join("\n");
 }
-function buildPersistenceEndpointManifest(variables) {
-    return defineEndpointManifest({
-        contracts: {
-            "state-query": {
-                sourceTypeName: `${variables.pascalCase}StateQuery`,
-            },
-            "write-state-request": {
-                sourceTypeName: `${variables.pascalCase}WriteStateRequest`,
-            },
-            "state-response": {
-                sourceTypeName: `${variables.pascalCase}StateResponse`,
-            },
-        },
-        endpoints: [
-            {
-                auth: "public",
-                method: "GET",
-                operationId: `get${variables.pascalCase}State`,
-                path: `/${variables.namespace}/v1/${variables.slugKebabCase}/state`,
-                queryContract: "state-query",
-                responseContract: "state-response",
-                summary: "Read the current persisted state.",
-                tags: [variables.title],
-            },
-            {
-                auth: variables.restWriteAuthIntent,
-                bodyContract: "write-state-request",
-                method: "POST",
-                operationId: `write${variables.pascalCase}State`,
-                path: `/${variables.namespace}/v1/${variables.slugKebabCase}/state`,
-                responseContract: "state-response",
-                summary: "Write the current persisted state.",
-                tags: [variables.title],
-                wordpressAuth: {
-                    mechanism: variables.restWriteAuthMechanism,
-                },
-            },
-        ],
-        info: {
-            title: `${variables.title} REST API`,
-            version: "1.0.0",
-        },
-    });
-}
 function buildCompoundChildConfigEntry(variables) {
     return [
         "\t{",
@@ -732,28 +705,11 @@ async function syncWorkspaceBlockMetadata(projectDir, slug, sourceTypeName, type
     });
 }
 async function syncWorkspacePersistenceArtifacts(projectDir, variables) {
-    const manifest = buildPersistenceEndpointManifest(variables);
-    const apiTypesFile = path.join("src", "blocks", variables.slugKebabCase, "api-types.ts");
-    for (const [baseName, contract] of Object.entries(manifest.contracts)) {
-        await syncTypeSchemas({
-            jsonSchemaFile: path.join("src", "blocks", variables.slugKebabCase, "api-schemas", `${baseName}.schema.json`),
-            openApiFile: path.join("src", "blocks", variables.slugKebabCase, "api-schemas", `${baseName}.openapi.json`),
-            projectRoot: projectDir,
-            sourceTypeName: contract.sourceTypeName,
-            typesFile: apiTypesFile,
-        });
-    }
-    await syncRestOpenApi({
-        manifest,
-        openApiFile: path.join("src", "blocks", variables.slugKebabCase, "api.openapi.json"),
-        projectRoot: projectDir,
-        typesFile: apiTypesFile,
-    });
-    await syncEndpointClient({
-        clientFile: path.join("src", "blocks", variables.slugKebabCase, "api-client.ts"),
-        manifest,
-        projectRoot: projectDir,
-        typesFile: apiTypesFile,
+    await syncPersistenceRestArtifacts({
+        apiTypesFile: path.join("src", "blocks", variables.slugKebabCase, "api-types.ts"),
+        outputDir: path.join("src", "blocks", variables.slugKebabCase),
+        projectDir,
+        variables,
     });
 }
 async function syncWorkspaceAddedBlockArtifacts(projectDir, templateId, variables) {

package/dist/runtime/cli-doctor.js

@@ -5,7 +5,7 @@ import { execFileSync } from "node:child_process";
 import { access, constants as fsConstants, rm, writeFile } from "node:fs/promises";
 import { getBuiltInTemplateLayerDirs } from "./template-builtins.js";
 import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_SET, } from "./hooked-blocks.js";
-import { listTemplates } from "./template-registry.js";
+import { isBuiltInTemplateId, listTemplates } from "./template-registry.js";
 import { readWorkspaceInventory } from "./workspace-inventory.js";
 import { getInvalidWorkspaceProjectReason, parseWorkspacePackageJson, WORKSPACE_TEMPLATE_PACKAGE, tryResolveWorkspaceProject, } from "./workspace-project.js";
 const WORKSPACE_COLLECTION_IMPORT_LINE = "import '../../collection';";
@@ -285,24 +285,40 @@ export async function getDoctorChecks(cwd) {
         detail: tempWritable ? "Writable" : "Not writable",
     });
     for (const template of listTemplates()) {
-        const layerDirs = template.id === "persistence"
+        if (!isBuiltInTemplateId(template.id)) {
+            const templateDirExists = fs.existsSync(template.templateDir);
+            const hasAssets = templateDirExists &&
+                fs.existsSync(path.join(template.templateDir, "package.json.mustache"));
+            checks.push({
+                status: !templateDirExists || hasAssets ? "pass" : "fail",
+                label: `Template ${template.id}`,
+                detail: !templateDirExists
+                    ? "External template metadata only; local overlay package is not installed."
+                    : hasAssets
+                        ? template.templateDir
+                        : "Missing core template assets",
+            });
+            continue;
+        }
+        const builtInTemplateId = template.id;
+        const layerDirs = builtInTemplateId === "persistence"
             ? Array.from(new Set([
-                ...getBuiltInTemplateLayerDirs(template.id, { persistencePolicy: "authenticated" }),
-                ...getBuiltInTemplateLayerDirs(template.id, { persistencePolicy: "public" }),
+                ...getBuiltInTemplateLayerDirs(builtInTemplateId, { persistencePolicy: "authenticated" }),
+                ...getBuiltInTemplateLayerDirs(builtInTemplateId, { persistencePolicy: "public" }),
             ]))
-            : template.id === "compound"
+            : builtInTemplateId === "compound"
                 ? Array.from(new Set([
-                    ...getBuiltInTemplateLayerDirs(template.id),
-                    ...getBuiltInTemplateLayerDirs(template.id, {
+                    ...getBuiltInTemplateLayerDirs(builtInTemplateId),
+                    ...getBuiltInTemplateLayerDirs(builtInTemplateId, {
                         persistenceEnabled: true,
                         persistencePolicy: "authenticated",
                     }),
-                    ...getBuiltInTemplateLayerDirs(template.id, {
+                    ...getBuiltInTemplateLayerDirs(builtInTemplateId, {
                         persistenceEnabled: true,
                         persistencePolicy: "public",
                     }),
                 ]))
-                : getBuiltInTemplateLayerDirs(template.id);
+                : getBuiltInTemplateLayerDirs(builtInTemplateId);
         const hasAssets = layerDirs.every((layerDir) => fs.existsSync(layerDir)) &&
             layerDirs.some((layerDir) => fs.existsSync(path.join(layerDir, "package.json.mustache"))) &&
             layerDirs.some((layerDir) => fs.existsSync(path.join(layerDir, "src")));

package/dist/runtime/cli-help.js

@@ -34,6 +34,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\`.
+  Use \`--template @wp-typia/create-workspace-template\` for the official empty workspace scaffold behind \`wp-typia add ...\`.
   \`add variation\` uses an existing workspace block from \`scripts/block-config.ts\`.
   \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.

package/dist/runtime/cli-templates.js

@@ -30,6 +30,16 @@ export function formatTemplateFeatures(template) {
  * @returns Multi-line template details text for CLI output.
  */
 export function formatTemplateDetails(template) {
+    if (!isBuiltInTemplateId(template.id)) {
+        return [
+            template.id,
+            template.description,
+            `Category: ${template.defaultCategory}`,
+            `Overlay path: ${template.templateDir}`,
+            "Layers: workspace package scaffold",
+            `Features: ${template.features.join(", ")}`,
+        ].join("\n");
+    }
     const layers = template.id === "persistence"
         ? [
             `authenticated: ${getBuiltInTemplateLayerDirs(template.id, { persistencePolicy: "authenticated" }).join(" -> ")}`,

package/dist/runtime/persistence-rest-artifacts.d.ts

@@ -0,0 +1,76 @@
+interface PersistenceTemplateVariablesLike {
+    namespace: string;
+    pascalCase: string;
+    restWriteAuthIntent: "authenticated" | "public-write-protected";
+    restWriteAuthMechanism: "public-signed-token" | "rest-nonce";
+    slugKebabCase: string;
+    title: string;
+}
+interface SyncPersistenceRestArtifactsOptions {
+    apiTypesFile: string;
+    outputDir: string;
+    projectDir: string;
+    variables: PersistenceTemplateVariablesLike;
+}
+/**
+ * Build the canonical persistence REST endpoint manifest for scaffold-time
+ * schema, OpenAPI, and client generation.
+ *
+ * @param variables Persistence template naming and auth metadata.
+ * @returns Endpoint manifest covering bootstrap, state read, and state write operations.
+ */
+export declare function buildPersistenceEndpointManifest(variables: PersistenceTemplateVariablesLike): import("@wp-typia/block-runtime/metadata-core").EndpointManifestDefinition<{
+    readonly "bootstrap-query": {
+        readonly sourceTypeName: `${string}BootstrapQuery`;
+    };
+    readonly "bootstrap-response": {
+        readonly sourceTypeName: `${string}BootstrapResponse`;
+    };
+    readonly "state-query": {
+        readonly sourceTypeName: `${string}StateQuery`;
+    };
+    readonly "state-response": {
+        readonly sourceTypeName: `${string}StateResponse`;
+    };
+    readonly "write-state-request": {
+        readonly sourceTypeName: `${string}WriteStateRequest`;
+    };
+}, readonly [{
+    readonly auth: "public";
+    readonly method: "GET";
+    readonly operationId: `get${string}State`;
+    readonly path: `/${string}/v1/${string}/state`;
+    readonly queryContract: "state-query";
+    readonly responseContract: "state-response";
+    readonly summary: "Read the current persisted state.";
+    readonly tags: readonly [string];
+}, {
+    readonly auth: "authenticated" | "public-write-protected";
+    readonly bodyContract: "write-state-request";
+    readonly method: "POST";
+    readonly operationId: `write${string}State`;
+    readonly path: `/${string}/v1/${string}/state`;
+    readonly responseContract: "state-response";
+    readonly summary: "Write the current persisted state.";
+    readonly tags: readonly [string];
+    readonly wordpressAuth: {
+        readonly mechanism: "public-signed-token" | "rest-nonce";
+    };
+}, {
+    readonly auth: "public";
+    readonly method: "GET";
+    readonly operationId: `get${string}Bootstrap`;
+    readonly path: `/${string}/v1/${string}/bootstrap`;
+    readonly queryContract: "bootstrap-query";
+    readonly responseContract: "bootstrap-response";
+    readonly summary: "Read fresh session bootstrap state for the current viewer.";
+    readonly tags: readonly [string];
+}]>;
+/**
+ * Generate the REST-derived persistence artifacts for a scaffolded block.
+ *
+ * @param options Scaffold output paths plus persistence template variables.
+ * @returns A promise that resolves after schema, OpenAPI, and client files are written.
+ */
+export declare function syncPersistenceRestArtifacts({ apiTypesFile, outputDir, projectDir, variables, }: SyncPersistenceRestArtifactsOptions): Promise<void>;
+export {};

package/dist/runtime/persistence-rest-artifacts.js

@@ -0,0 +1,99 @@
+import path from "node:path";
+import { defineEndpointManifest, syncEndpointClient, syncRestOpenApi, syncTypeSchemas, } from "@wp-typia/block-runtime/metadata-core";
+/**
+ * Build the canonical persistence REST endpoint manifest for scaffold-time
+ * schema, OpenAPI, and client generation.
+ *
+ * @param variables Persistence template naming and auth metadata.
+ * @returns Endpoint manifest covering bootstrap, state read, and state write operations.
+ */
+export function buildPersistenceEndpointManifest(variables) {
+    return defineEndpointManifest({
+        contracts: {
+            "bootstrap-query": {
+                sourceTypeName: `${variables.pascalCase}BootstrapQuery`,
+            },
+            "bootstrap-response": {
+                sourceTypeName: `${variables.pascalCase}BootstrapResponse`,
+            },
+            "state-query": {
+                sourceTypeName: `${variables.pascalCase}StateQuery`,
+            },
+            "state-response": {
+                sourceTypeName: `${variables.pascalCase}StateResponse`,
+            },
+            "write-state-request": {
+                sourceTypeName: `${variables.pascalCase}WriteStateRequest`,
+            },
+        },
+        endpoints: [
+            {
+                auth: "public",
+                method: "GET",
+                operationId: `get${variables.pascalCase}State`,
+                path: `/${variables.namespace}/v1/${variables.slugKebabCase}/state`,
+                queryContract: "state-query",
+                responseContract: "state-response",
+                summary: "Read the current persisted state.",
+                tags: [variables.title],
+            },
+            {
+                auth: variables.restWriteAuthIntent,
+                bodyContract: "write-state-request",
+                method: "POST",
+                operationId: `write${variables.pascalCase}State`,
+                path: `/${variables.namespace}/v1/${variables.slugKebabCase}/state`,
+                responseContract: "state-response",
+                summary: "Write the current persisted state.",
+                tags: [variables.title],
+                wordpressAuth: {
+                    mechanism: variables.restWriteAuthMechanism,
+                },
+            },
+            {
+                auth: "public",
+                method: "GET",
+                operationId: `get${variables.pascalCase}Bootstrap`,
+                path: `/${variables.namespace}/v1/${variables.slugKebabCase}/bootstrap`,
+                queryContract: "bootstrap-query",
+                responseContract: "bootstrap-response",
+                summary: "Read fresh session bootstrap state for the current viewer.",
+                tags: [variables.title],
+            },
+        ],
+        info: {
+            title: `${variables.title} REST API`,
+            version: "1.0.0",
+        },
+    });
+}
+/**
+ * Generate the REST-derived persistence artifacts for a scaffolded block.
+ *
+ * @param options Scaffold output paths plus persistence template variables.
+ * @returns A promise that resolves after schema, OpenAPI, and client files are written.
+ */
+export async function syncPersistenceRestArtifacts({ apiTypesFile, outputDir, projectDir, variables, }) {
+    const manifest = buildPersistenceEndpointManifest(variables);
+    for (const [baseName, contract] of Object.entries(manifest.contracts)) {
+        await syncTypeSchemas({
+            jsonSchemaFile: path.join(outputDir, "api-schemas", `${baseName}.schema.json`),
+            openApiFile: path.join(outputDir, "api-schemas", `${baseName}.openapi.json`),
+            projectRoot: projectDir,
+            sourceTypeName: contract.sourceTypeName,
+            typesFile: apiTypesFile,
+        });
+    }
+    await syncRestOpenApi({
+        manifest,
+        openApiFile: path.join(outputDir, "api.openapi.json"),
+        projectRoot: projectDir,
+        typesFile: apiTypesFile,
+    });
+    await syncEndpointClient({
+        clientFile: path.join(outputDir, "api-client.ts"),
+        manifest,
+        projectRoot: projectDir,
+        typesFile: apiTypesFile,
+    });
+}

package/dist/runtime/scaffold-onboarding.js

@@ -42,7 +42,7 @@ export function getTemplateSourceOfTruthNote(templateId, { compoundPersistenceEn
         return compoundBase;
     }
     if (templateId === "persistence") {
-        return "`src/types.ts` remains the source of truth for `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include a starter `typia.manifest.json` so editor imports resolve before the first sync. `src/api-types.ts` remains the source of truth for `src/api-schemas/*` when you run `sync-rest`, while `src/transport.ts` is the first-class transport seam for editor and frontend requests. This scaffold is intentionally server-rendered: `src/render.php` is the canonical frontend entry, and `src/save.tsx` returns `null` so PHP can inject post context, storage-backed state, and write-policy bootstrap data before hydration.";
+        return "`src/types.ts` remains the source of truth for `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include a starter `typia.manifest.json` so editor imports resolve before the first sync. `src/api-types.ts` remains the source of truth for `src/api-schemas/*` when you run `sync-rest`, while `src/transport.ts` is the first-class transport seam for editor and frontend requests. This scaffold is intentionally server-rendered: `src/render.php` is the canonical frontend entry, `src/save.tsx` returns `null`, and session-only write data now refreshes through the dedicated `/bootstrap` endpoint after hydration instead of being frozen into markup.";
     }
     return "`src/types.ts` remains the source of truth for `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include a starter `typia.manifest.json` so editor imports resolve before the first sync. The basic scaffold stays static by design: `src/render.php` is only an opt-in server placeholder, `src/save.tsx` remains the canonical frontend output, and the generated webpack config keeps the current `@wordpress/scripts` CommonJS baseline unless you intentionally add `render` to `block.json`.";
 }
@@ -87,12 +87,13 @@ export function getPhpRestExtensionPointsSection(templateId, { compoundPersisten
             mainPhpPath: `${slug}.php`,
             mainPhpScope: "change storage helpers, route handlers, response shaping, or route registration",
             transportPath: "src/transport.ts",
+            extraNote: "Keep durable state on the `/state` endpoints and treat the dedicated `/bootstrap` endpoint as the place to return fresh session-only write access data such as nonces or public write tokens.",
         });
     }
     if (templateId === "compound" && compoundPersistenceEnabled) {
         return formatPhpRestExtensionPointsSection({
             apiTypesPath: `src/blocks/${slug}/api-types.ts`,
-            extraNote: "The hidden child block does not own REST routes or storage.",
+            extraNote: "The hidden child block does not own REST routes or storage. Keep durable parent-block state on the `/state` endpoints and return fresh session-only write access data from the dedicated `/bootstrap` endpoint.",
             mainPhpPath: `${slug}.php`,
             mainPhpScope: "change parent-block storage helpers, route handlers, response shaping, or route registration",
             transportPath: `src/blocks/${slug}/transport.ts`,

package/dist/runtime/scaffold.d.ts

@@ -1,5 +1,4 @@
 import type { PackageManagerId } from "./package-managers.js";
-import type { BuiltInTemplateId } from "./template-registry.js";
 /**
  * User-facing scaffold answers before template rendering.
  *
@@ -56,6 +55,8 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     phpPrefixUpper: string;
     isAuthenticatedPersistencePolicy: "false" | "true";
     isPublicPersistencePolicy: "false" | "true";
+    bootstrapCredentialDeclarations: string;
+    persistencePolicyDescriptionJson: string;
     publicWriteRequestIdDeclaration: string;
     restPackageVersion: string;
     restWriteAuthIntent: "authenticated" | "public-write-protected";
@@ -72,9 +73,17 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     titleCase: string;
     persistencePolicy: PersistencePolicy;
 }
+/**
+ * Resolve scaffold template input from either built-in template ids or custom
+ * template identifiers such as local paths, GitHub refs, and npm packages.
+ *
+ * The callback returns `Promise<string>` on purpose so interactive selection
+ * can surface custom ids. Downstream code uses `isBuiltInTemplateId()` to
+ * distinguish built-in templates from custom sources.
+ */
 interface ResolveTemplateOptions {
     isInteractive?: boolean;
-    selectTemplate?: () => Promise<BuiltInTemplateId>;
+    selectTemplate?: () => Promise<string>;
     templateId?: string;
     yes?: boolean;
 }

package/dist/runtime/scaffold.js

@@ -7,17 +7,19 @@ import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, getPrimar
 import { applyMigrationUiCapability } from "./migration-ui-capability.js";
 import { getPackageVersions } from "./package-versions.js";
 import { ensureMigrationDirectories, writeInitialMigrationScaffold, writeMigrationConfig, } from "./migration-project.js";
+import { syncPersistenceRestArtifacts } from "./persistence-rest-artifacts.js";
 import { getCompoundExtensionWorkflowSection, getOptionalOnboardingNote, getOptionalOnboardingSteps, getPhpRestExtensionPointsSection, getTemplateSourceOfTruthNote, } from "./scaffold-onboarding.js";
 import { getStarterManifestFiles, stringifyStarterManifest } from "./starter-manifests.js";
 import { toKebabCase, toPascalCase, toSnakeCase, toTitleCase, } from "./string-case.js";
 import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from "./template-defaults.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId } from "./template-registry.js";
+import { PROJECT_TOOLS_PACKAGE_ROOT, TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId, } from "./template-registry.js";
 import { resolveTemplateSource } from "./template-source.js";
 const BLOCK_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
 const PHP_PREFIX_PATTERN = /^[a-z_][a-z0-9_]*$/;
 const PHP_PREFIX_MAX_LENGTH = 50;
 const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 const LOCKFILES = {
     bun: ["bun.lock", "bun.lockb"],
     npm: ["package-lock.json"],
@@ -262,6 +264,12 @@ export function getTemplateVariables(templateId, answers) {
         frontendCssClassName: buildFrontendCssClassName(cssClassName),
         isAuthenticatedPersistencePolicy: persistencePolicy === "authenticated" ? "true" : "false",
         isPublicPersistencePolicy: persistencePolicy === "public" ? "true" : "false",
+        bootstrapCredentialDeclarations: persistencePolicy === "public"
+            ? "publicWriteExpiresAt?: number & tags.Type< 'uint32' >;\n\tpublicWriteToken?: string & tags.MinLength< 1 > & tags.MaxLength< 512 >;"
+            : "restNonce?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
+        persistencePolicyDescriptionJson: JSON.stringify(persistencePolicy === "authenticated"
+            ? "Writes require a logged-in user and a valid REST nonce."
+            : "Anonymous writes use signed short-lived public tokens, per-request ids, and coarse rate limiting."),
         keyword: slug.replace(/-/g, " "),
         namespace,
         needsMigration: "{{needsMigration}}",
@@ -409,6 +417,94 @@ async function writeStarterManifestFiles(targetDir, templateId, variables) {
         await fsp.writeFile(destinationPath, stringifyStarterManifest(document), "utf8");
     }
 }
+/**
+ * Seed REST-derived persistence artifacts into a newly scaffolded built-in
+ * project before the first manual `sync-rest` run.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param templateId Built-in template id being scaffolded.
+ * @param variables Resolved scaffold template variables for the project.
+ * @returns A promise that resolves after any required persistence artifacts are generated.
+ */
+async function seedBuiltInPersistenceArtifacts(targetDir, templateId, variables) {
+    const needsPersistenceArtifacts = templateId === "persistence" ||
+        (templateId === "compound" && variables.compoundPersistenceEnabled === "true");
+    if (!needsPersistenceArtifacts) {
+        return;
+    }
+    await withEphemeralScaffoldNodeModules(targetDir, async () => {
+        if (templateId === "persistence") {
+            await syncPersistenceRestArtifacts({
+                apiTypesFile: path.join("src", "api-types.ts"),
+                outputDir: "src",
+                projectDir: targetDir,
+                variables,
+            });
+            return;
+        }
+        await syncPersistenceRestArtifacts({
+            apiTypesFile: path.join("src", "blocks", variables.slugKebabCase, "api-types.ts"),
+            outputDir: path.join("src", "blocks", variables.slugKebabCase),
+            projectDir: targetDir,
+            variables,
+        });
+    });
+}
+/**
+ * Locate a node_modules directory containing `typia` relative to the project
+ * tools package root.
+ *
+ * Search order:
+ * 1. `PROJECT_TOOLS_PACKAGE_ROOT/node_modules`
+ * 2. The monorepo root resolved from `PROJECT_TOOLS_PACKAGE_ROOT`
+ * 3. The monorepo root `node_modules`
+ *
+ * @returns The first matching path, or `null` when no candidate contains `typia`.
+ */
+function resolveScaffoldGeneratorNodeModulesPath() {
+    const candidates = [
+        path.join(PROJECT_TOOLS_PACKAGE_ROOT, "node_modules"),
+        path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", ".."),
+        path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", "..", "node_modules"),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(path.join(candidate, "typia", "package.json"))) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Temporarily symlink a scaffold generator node_modules directory into the
+ * target project while running an async callback.
+ *
+ * The helper resolves the source path via `resolveScaffoldGeneratorNodeModulesPath()`
+ * and uses `EPHEMERAL_NODE_MODULES_LINK_TYPE` for the symlink. The temporary
+ * link is removed in the `finally` block so cleanup still happens if the
+ * callback throws.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param callback Async work that requires a resolvable `node_modules`.
+ * @returns A promise that resolves after the callback and cleanup complete.
+ */
+async function withEphemeralScaffoldNodeModules(targetDir, callback) {
+    const targetNodeModulesPath = path.join(targetDir, "node_modules");
+    if (fs.existsSync(targetNodeModulesPath)) {
+        await callback();
+        return;
+    }
+    const sourceNodeModulesPath = resolveScaffoldGeneratorNodeModulesPath();
+    if (!sourceNodeModulesPath) {
+        throw new Error("Unable to resolve a node_modules directory with typia for scaffold-time REST artifact generation.");
+    }
+    await fsp.symlink(sourceNodeModulesPath, targetNodeModulesPath, EPHEMERAL_NODE_MODULES_LINK_TYPE);
+    try {
+        await callback();
+    }
+    finally {
+        await fsp.rm(targetNodeModulesPath, { force: true, recursive: true });
+    }
+}
 async function normalizePackageManagerFiles(targetDir, packageManagerId) {
     const yarnRcPath = path.join(targetDir, ".yarnrc.yml");
     if (packageManagerId === "yarn") {
@@ -554,6 +650,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
     const isOfficialWorkspace = isOfficialWorkspaceProject(projectDir);
     if (isBuiltInTemplate) {
         await writeStarterManifestFiles(projectDir, templateId, variables);
+        await seedBuiltInPersistenceArtifacts(projectDir, templateId, variables);
         await applyLocalDevPresetFiles({
             projectDir,
             variables,

package/dist/runtime/schema-core.d.ts

@@ -59,6 +59,7 @@ export interface OpenApiResponse extends JsonSchemaObject {
         "application/json": OpenApiMediaType;
     };
     description: string;
+    headers?: Record<string, JsonSchemaObject>;
 }
 /**
  * Header-based security scheme used by authenticated WordPress REST routes.