@wp-typia/project-tools 0.15.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.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.
  *
@@ -57,6 +56,7 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     isAuthenticatedPersistencePolicy: "false" | "true";
     isPublicPersistencePolicy: "false" | "true";
     bootstrapCredentialDeclarations: string;
+    persistencePolicyDescriptionJson: string;
     publicWriteRequestIdDeclaration: string;
     restPackageVersion: string;
     restWriteAuthIntent: "authenticated" | "public-write-protected";
@@ -73,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"],
@@ -265,6 +267,9 @@ export function getTemplateVariables(templateId, answers) {
         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}}",
@@ -412,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") {
@@ -557,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/template-builtins.js

@@ -59,7 +59,7 @@ export async function resolveBuiltInTemplateSource(templateId, options = {}) {
         throw error;
     }
     return {
-        id: template.id,
+        id: templateId,
         defaultCategory: template.defaultCategory,
         description: template.description,
         features: template.features,

package/dist/runtime/template-registry.d.ts

@@ -15,10 +15,11 @@ export declare const SHARED_WORKSPACE_TEMPLATE_ROOT: string;
 export declare const SHARED_TEST_PRESET_TEMPLATE_ROOT: string;
 export declare const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT: string;
 export declare const BUILTIN_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound"];
+export declare const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
 export type BuiltInTemplateId = (typeof BUILTIN_TEMPLATE_IDS)[number];
 export type PersistencePolicy = "authenticated" | "public";
 export interface TemplateDefinition {
-    id: BuiltInTemplateId;
+    id: string;
     description: string;
     defaultCategory: string;
     features: string[];

package/dist/runtime/template-registry.js

@@ -41,6 +41,7 @@ export const SHARED_WORKSPACE_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "w
 export const SHARED_TEST_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "test-preset");
 export const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "wp-env");
 export const BUILTIN_TEMPLATE_IDS = ["basic", "interactivity", "persistence", "compound"];
+export const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
 export const TEMPLATE_REGISTRY = Object.freeze([
     {
         id: "basic",
@@ -70,8 +71,15 @@ export const TEMPLATE_REGISTRY = Object.freeze([
         features: ["InnerBlocks", "Hidden child blocks", "Optional persistence layer"],
         templateDir: path.join(TEMPLATE_ROOT, "compound"),
     },
+    {
+        id: OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE,
+        description: "The official empty workspace template that powers `wp-typia add ...` workflows",
+        defaultCategory: "workspace",
+        features: ["Workspace inventory", "Add block workflows", "Workspace doctor and migrate"],
+        templateDir: path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", "create-workspace-template"),
+    },
 ]);
-export const TEMPLATE_IDS = TEMPLATE_REGISTRY.map((template) => template.id);
+export const TEMPLATE_IDS = [...BUILTIN_TEMPLATE_IDS];
 export function isBuiltInTemplateId(templateId) {
     return BUILTIN_TEMPLATE_IDS.includes(templateId);
 }
@@ -81,7 +89,10 @@ export function listTemplates() {
 export function getTemplateById(templateId) {
     const template = TEMPLATE_REGISTRY.find((entry) => entry.id === templateId);
     if (!template) {
-        throw new Error(`Unknown template "${templateId}". Expected one of: ${TEMPLATE_IDS.join(", ")}`);
+        throw new Error(`Unknown template "${templateId}". Expected one of: ${[
+            ...TEMPLATE_IDS,
+            OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE,
+        ].join(", ")}`);
     }
     return template;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -69,6 +69,7 @@
     "npm-package-arg": "^13.0.0",
     "semver": "^7.7.3",
     "tar": "^7.4.3",
+    "typia": "^12.0.1",
     "typescript": "^5.9.2"
   },
   "devDependencies": {

package/templates/_shared/compound/core/scripts/add-compound-child.ts.mustache

@@ -2,14 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const PARENT_BLOCK_NAME = '{{namespace}}/{{slugKebabCase}}';
-const PARENT_BLOCK_NAMESPACE = '{{namespace}}';
-const PARENT_BLOCK_SLUG = '{{slugKebabCase}}';
-const PARENT_BLOCK_TITLE = {{titleJson}};
-const PARENT_TYPE_NAME = '{{pascalCase}}';
-const PARENT_STYLE_IMPORT = '../{{slugKebabCase}}/style.scss';
 const PROJECT_ROOT = process.cwd();
-const TEXT_DOMAIN = '{{textDomain}}';
 
 const ALLOWED_CHILD_MARKER = '// add-child: insert new allowed child block names here';
 const BLOCK_CONFIG_MARKER = '// add-child: insert new block config entries here';
@@ -22,6 +15,16 @@ type StarterManifestDocument = {
 	sourceType: string;
 };
 
+type CompoundParentConfig = {
+	blockName: string;
+	namespace: string;
+	slug: string;
+	styleImport: string;
+	textDomain: string;
+	title: string;
+	typeName: string;
+};
+
 function parseArgs() {
 	const args = process.argv.slice( 2 );
 	const parsed: {
@@ -81,6 +84,26 @@ function toTitleCase( input: string ): string {
 		.join( ' ' );
 }
 
+function readJsonFile( filePath: string ): Record< string, unknown > {
+	let parsed: unknown;
+
+	try {
+		parsed = JSON.parse( fs.readFileSync( filePath, 'utf8' ) );
+	} catch ( error ) {
+		const errorMessage = error instanceof Error ? error.message : String( error );
+		throw new Error(
+			`Unable to parse JSON from ${ filePath }: ${ errorMessage }`,
+			{ cause: error instanceof Error ? error : undefined }
+		);
+	}
+
+	if ( ! parsed || typeof parsed !== 'object' || Array.isArray( parsed ) ) {
+		throw new Error( `${ filePath } must contain a JSON object.` );
+	}
+
+	return parsed as Record< string, unknown >;
+}
+
 function resolveValidatedNamespace( value: string ): string {
 	const normalizedNamespace = toKebabCase( value );
 
@@ -101,6 +124,79 @@ function resolveValidatedBlockSlug( value: string ): string {
 	return normalizedSlug;
 }
 
+function resolveCompoundParentConfig(): CompoundParentConfig {
+	const blocksRoot = path.join( PROJECT_ROOT, 'src', 'blocks' );
+
+	if ( ! fs.existsSync( blocksRoot ) ) {
+		throw new Error(
+			'This command expects a compound scaffold with src/blocks/<parent>/children.ts and scripts/block-config.ts.'
+		);
+	}
+
+	const parentCandidates = fs
+		.readdirSync( blocksRoot, { withFileTypes: true } )
+		.filter( ( entry ) => entry.isDirectory() )
+		.map( ( entry ) => path.join( blocksRoot, entry.name ) )
+		.filter( ( candidateDir ) =>
+			fs.existsSync( path.join( candidateDir, 'children.ts' ) )
+		);
+
+	if ( parentCandidates.length !== 1 ) {
+		throw new Error(
+			`Unable to resolve the compound parent block. Expected exactly one src/blocks/<parent>/children.ts entry, found ${ parentCandidates.length }.`
+		);
+	}
+
+	const parentDir = parentCandidates[ 0 ];
+	const parentSlug = resolveValidatedBlockSlug( path.basename( parentDir ) );
+	const blockJsonPath = path.join( parentDir, 'block.json' );
+
+	if ( ! fs.existsSync( blockJsonPath ) ) {
+		throw new Error( `Unable to resolve ${ blockJsonPath } for the compound parent block.` );
+	}
+
+	const blockJson = readJsonFile( blockJsonPath );
+	const blockName = typeof blockJson.name === 'string' ? blockJson.name.trim() : '';
+	const separatorIndex = blockName.indexOf( '/' );
+
+	if ( separatorIndex <= 0 || separatorIndex === blockName.length - 1 ) {
+		throw new Error(
+			`The parent block metadata at ${ blockJsonPath } must declare a valid "name" like "namespace/slug".`
+		);
+	}
+
+	const namespace = resolveValidatedNamespace( blockName.slice( 0, separatorIndex ) );
+	const title =
+		typeof blockJson.title === 'string' && blockJson.title.trim().length > 0
+			? blockJson.title.trim()
+			: toTitleCase( parentSlug );
+	const textDomain =
+		typeof blockJson.textdomain === 'string' &&
+		blockJson.textdomain.trim().length > 0
+			? blockJson.textdomain.trim()
+			: parentSlug;
+
+	return {
+		blockName,
+		namespace,
+		slug: parentSlug,
+		styleImport: `../${ parentSlug }/style.scss`,
+		textDomain,
+		title,
+		typeName: toPascalCase( parentSlug ),
+	};
+}
+
+const {
+	blockName: PARENT_BLOCK_NAME,
+	namespace: PARENT_BLOCK_NAMESPACE,
+	slug: PARENT_BLOCK_SLUG,
+	styleImport: PARENT_STYLE_IMPORT,
+	textDomain: TEXT_DOMAIN,
+	title: PARENT_BLOCK_TITLE,
+	typeName: PARENT_TYPE_NAME,
+} = resolveCompoundParentConfig();
+
 function buildBlockCssClassName( namespace: string, slug: string ): string {
 	const normalizedSlug = resolveValidatedBlockSlug( slug );
 	const normalizedNamespace =

package/templates/_shared/persistence/core/src/api-validators.ts.mustache

@@ -5,11 +5,17 @@ import {
 	type ValidationResult,
 } from '@wp-typia/api-client';
 import type {
+	{{pascalCase}}BootstrapQuery,
+	{{pascalCase}}BootstrapResponse,
 	{{pascalCase}}StateQuery,
 	{{pascalCase}}StateResponse,
 	{{pascalCase}}WriteStateRequest,
 } from './api-types';
 
+const validateBootstrapQuery =
+	typia.createValidate< {{pascalCase}}BootstrapQuery >();
+const validateBootstrapResponse =
+	typia.createValidate< {{pascalCase}}BootstrapResponse >();
 const validateStateQuery = typia.createValidate< {{pascalCase}}StateQuery >();
 const validateWriteStateRequest =
 	typia.createValidate< {{pascalCase}}WriteStateRequest >();
@@ -17,6 +23,14 @@ const validateStateResponse =
 	typia.createValidate< {{pascalCase}}StateResponse >();
 
 export const apiValidators = {
+	bootstrapQuery: (
+		input: unknown
+	): ValidationResult< {{pascalCase}}BootstrapQuery > =>
+		toValidationResult( validateBootstrapQuery( input ) ),
+	bootstrapResponse: (
+		input: unknown
+	): ValidationResult< {{pascalCase}}BootstrapResponse > =>
+		toValidationResult( validateBootstrapResponse( input ) ),
 	stateQuery: (
 		input: unknown
 	): ValidationResult< {{pascalCase}}StateQuery > =>

package/templates/_shared/persistence/core/src/api.ts.mustache

@@ -1,5 +1,6 @@
 import {
 	callEndpoint,
+	type ApiEndpoint as RestApiEndpoint,
 } from '@wp-typia/rest';
 
 import {
@@ -17,17 +18,35 @@ import {
 	type PersistenceTransportOptions,
 } from './transport';
 
-export const bootstrapEndpoint = {
-	...get{{pascalCase}}BootstrapEndpoint,
-};
+function createRestEndpoint< Req, Res >(
+	endpoint: {
+		method: RestApiEndpoint< Req, Res >[ 'method' ];
+		path: string;
+		validateRequest: RestApiEndpoint< Req, Res >[ 'validateRequest' ];
+		validateResponse: RestApiEndpoint< Req, Res >[ 'validateResponse' ];
+	}
+): RestApiEndpoint< Req, Res > {
+	// Strip generator-only helper fields so the runtime client only sees the
+	// canonical RestApiEndpoint surface it expects.
+	return {
+		method: endpoint.method,
+		path: endpoint.path,
+		validateRequest: endpoint.validateRequest,
+		validateResponse: endpoint.validateResponse,
+	};
+}
+
+export const bootstrapEndpoint = createRestEndpoint(
+	get{{pascalCase}}BootstrapEndpoint
+);
 
-export const stateEndpoint = {
-	...get{{pascalCase}}StateEndpoint,
-};
+export const stateEndpoint = createRestEndpoint(
+	get{{pascalCase}}StateEndpoint
+);
 
-export const writeStateEndpoint = {
-	...write{{pascalCase}}StateEndpoint,
-};
+export const writeStateEndpoint = createRestEndpoint(
+	write{{pascalCase}}StateEndpoint
+);
 
 export function fetchState(
 	request: {{pascalCase}}StateQuery,

package/templates/_shared/persistence/core/src/interactivity.ts.mustache

@@ -7,6 +7,9 @@ import type {
 	{{pascalCase}}Context,
 	{{pascalCase}}State,
 } from './types';
+import type {
+	{{pascalCase}}WriteStateRequest,
+} from './api-types';
 
 function hasExpiredPublicWriteToken(
 	expiresAt?: number
@@ -123,6 +126,7 @@ const { actions, state } = store( '{{slugKebabCase}}', {
 			let bootstrapSucceeded = false;
 			let lastBootstrapError =
 				'Unable to initialize write access';
+			const includeRestNonce = {{isAuthenticatedPersistencePolicy}};
 
 			for ( let attempt = 1; attempt <= BOOTSTRAP_MAX_ATTEMPTS; attempt += 1 ) {
 				try {
@@ -156,6 +160,8 @@ const { actions, state } = store( '{{slugKebabCase}}', {
 							? result.data.publicWriteToken
 							: '';
 					clientState.writeNonce =
+						includeRestNonce &&
+						'restNonce' in result.data &&
 						typeof result.data.restNonce === 'string' &&
 						result.data.restNonce.length > 0
 							? result.data.restNonce
@@ -231,20 +237,20 @@ const { actions, state } = store( '{{slugKebabCase}}', {
 			context.error = '';
 
 			try {
-				const result = await writeState( {
+				const request = {
 					delta: 1,
 					postId: context.postId,
-					publicWriteRequestId:
-						context.persistencePolicy === 'public'
-							? generatePublicWriteRequestId()
-							: undefined,
-					publicWriteToken:
-						context.persistencePolicy === 'public' &&
-						clientState.writeToken.length > 0
-							? clientState.writeToken
-							: undefined,
 					resourceKey: context.resourceKey,
-				}, {
+				} as {{pascalCase}}WriteStateRequest;
+				if ( {{isPublicPersistencePolicy}} ) {
+					request.publicWriteRequestId =
+						generatePublicWriteRequestId() as {{pascalCase}}WriteStateRequest[ 'publicWriteRequestId' ];
+					if ( clientState.writeToken.length > 0 ) {
+						request.publicWriteToken =
+							clientState.writeToken as {{pascalCase}}WriteStateRequest[ 'publicWriteToken' ];
+					}
+				}
+				const result = await writeState( request, {
 					restNonce:
 						clientState.writeNonce.length > 0
 							? clientState.writeNonce

package/templates/interactivity/src/block.json.mustache

@@ -68,6 +68,7 @@
 	},
 	"textdomain": "{{textDomain}}",
 	"editorScript": "file:./index.js",
+	"editorStyle": "file:./index.css",
 	"style": "file:./style-index.css",
 	"viewScriptModule": "file:./interactivity.js"
 }

package/templates/interactivity/src/editor.scss.mustache

@@ -0,0 +1,8 @@
+/**
+ * {{title}} Block Editor Styles
+ */
+
+.{{cssClassName}} {
+	outline: 1px dashed #ddd;
+	outline-offset: -1px;
+}

package/templates/interactivity/src/index.tsx.mustache

@@ -9,6 +9,7 @@ import {
 import Edit from './edit';
 import Save from './save';
 import metadata from './block.json';
+import './editor.scss';
 import './style.scss';
 
 import type { {{pascalCase}}Attributes } from './types';

package/templates/persistence/src/edit.tsx.mustache

@@ -66,15 +66,15 @@ export default function Edit( {
 		validateEditorUpdate
 	);
 	const alignmentValue = editorFields.getStringValue(
-		attributes,
+		attributes as unknown as Record< string, unknown >,
 		'alignment',
 		'left'
 	);
 	const persistencePolicy = '{{persistencePolicy}}';
-	const persistencePolicyDescription =
-		persistencePolicy === 'authenticated'
-			? __( 'Writes require a logged-in user and a valid REST nonce.', '{{textDomain}}' )
-			: __( 'Anonymous writes use signed short-lived public tokens, per-request ids, and coarse rate limiting.', '{{textDomain}}' );
+	const persistencePolicyDescription = __(
+		{{persistencePolicyDescriptionJson}},
+		'{{textDomain}}'
+	);
 
 	return (
 		<>
@@ -91,7 +91,7 @@ export default function Edit( {
 			</BlockControls>
 			<InspectorControls>
 				<InspectorFromManifest
-					attributes={ attributes }
+					attributes={ attributes as unknown as Record< string, unknown > }
 					fieldLookup={ editorFields }
 					onChange={ updateField }
 					paths={ [ 'alignment', 'isVisible', 'showCount', 'buttonLabel' ] }