@wp-typia/project-tools 0.15.0 → 0.15.2

package/dist/runtime/metadata-projection.js

@@ -1,233 +1,7 @@
-import { cloneJsonValue } from "./json-utils.js";
-import { getWordPressKind, } from "./metadata-model.js";
-export function createBlockJsonAttribute(node, warnings) {
-    const attribute = {
-        type: getWordPressKind(node),
-    };
-    if (node.defaultValue !== undefined) {
-        attribute.default = cloneJsonValue(node.defaultValue);
-    }
-    if (node.enumValues !== null && node.enumValues.length > 0) {
-        attribute.enum = [...node.enumValues];
-    }
-    if (node.wp.source !== null) {
-        attribute.source = node.wp.source;
-    }
-    if (node.wp.selector !== null) {
-        attribute.selector = node.wp.selector;
-    }
-    const reasons = [];
-    if (node.constraints.exclusiveMaximum !== null)
-        reasons.push("exclusiveMaximum");
-    if (node.constraints.exclusiveMinimum !== null)
-        reasons.push("exclusiveMinimum");
-    if (node.constraints.format !== null)
-        reasons.push("format");
-    if (node.constraints.maxLength !== null)
-        reasons.push("maxLength");
-    if (node.constraints.maxItems !== null)
-        reasons.push("maxItems");
-    if (node.constraints.maximum !== null)
-        reasons.push("maximum");
-    if (node.constraints.minLength !== null)
-        reasons.push("minLength");
-    if (node.constraints.minItems !== null)
-        reasons.push("minItems");
-    if (node.constraints.minimum !== null)
-        reasons.push("minimum");
-    if (node.constraints.multipleOf !== null)
-        reasons.push("multipleOf");
-    if (node.constraints.pattern !== null)
-        reasons.push("pattern");
-    if (node.constraints.typeTag !== null)
-        reasons.push("typeTag");
-    if (node.kind === "array" && node.items !== undefined)
-        reasons.push("items");
-    if (node.kind === "object" && node.properties !== undefined)
-        reasons.push("properties");
-    if (node.kind === "union" && node.union !== null)
-        reasons.push("union");
-    if (reasons.length > 0) {
-        warnings.push(`${node.path}: ${reasons.join(", ")}`);
-    }
-    return attribute;
-}
-export function createManifestAttribute(node) {
-    return {
-        typia: {
-            constraints: { ...node.constraints },
-            defaultValue: node.defaultValue === undefined ? null : cloneJsonValue(node.defaultValue),
-            hasDefault: node.defaultValue !== undefined,
-        },
-        ts: {
-            items: node.items ? createManifestAttribute(node.items) : null,
-            kind: node.kind,
-            properties: node.properties
-                ? Object.fromEntries(Object.entries(node.properties).map(([key, property]) => [
-                    key,
-                    createManifestAttribute(property),
-                ]))
-                : null,
-            required: node.required,
-            union: node.union
-                ? {
-                    branches: Object.fromEntries(Object.entries(node.union.branches).map(([key, branch]) => [
-                        key,
-                        createManifestAttribute(branch),
-                    ])),
-                    discriminator: node.union.discriminator,
-                }
-                : null,
-        },
-        wp: {
-            defaultValue: node.defaultValue === undefined ? null : cloneJsonValue(node.defaultValue),
-            enum: node.enumValues ? [...node.enumValues] : null,
-            hasDefault: node.defaultValue !== undefined,
-            ...(node.wp.selector !== null ? { selector: node.wp.selector } : {}),
-            ...(node.wp.source !== null ? { source: node.wp.source } : {}),
-            type: getWordPressKind(node),
-        },
-    };
-}
-export function createManifestDocument(sourceTypeName, attributes) {
-    return {
-        attributes: Object.fromEntries(Object.entries(attributes).map(([key, node]) => [
-            key,
-            createManifestAttribute(node),
-        ])),
-        manifestVersion: 2,
-        sourceType: sourceTypeName,
-    };
-}
-export function validateWordPressExtractionAttributes(attributes) {
-    for (const attribute of Object.values(attributes)) {
-        validateWordPressExtractionAttribute(attribute, true);
-    }
-}
-export function validateWordPressExtractionAttribute(node, isTopLevel = false) {
-    const hasSelector = node.wp.selector !== null;
-    const hasSource = node.wp.source !== null;
-    if (hasSelector || hasSource) {
-        if (!isTopLevel) {
-            throw new Error(`WordPress extraction tags are only supported on top-level block attributes at ${node.path}`);
-        }
-        if (!hasSelector || !hasSource) {
-            throw new Error(`WordPress extraction tags require both Source and Selector at ${node.path}`);
-        }
-        if (node.kind !== "string") {
-            throw new Error(`WordPress extraction tags are only supported on string attributes at ${node.path}`);
-        }
-    }
-    if (node.items !== undefined) {
-        validateWordPressExtractionAttribute(node.items, false);
-    }
-    if (node.properties !== undefined) {
-        for (const property of Object.values(node.properties)) {
-            validateWordPressExtractionAttribute(property, false);
-        }
-    }
-    if (node.union?.branches) {
-        for (const branch of Object.values(node.union.branches)) {
-            validateWordPressExtractionAttribute(branch, false);
-        }
-    }
-}
-export function createExampleValue(node, key) {
-    if (node.defaultValue !== undefined) {
-        return cloneJsonValue(node.defaultValue);
-    }
-    if (node.enumValues !== null && node.enumValues.length > 0) {
-        return cloneJsonValue(node.enumValues[0]);
-    }
-    switch (node.kind) {
-        case "string":
-            return fitStringExampleToConstraints(createFormattedStringExample(node.constraints.format, key), node.constraints);
-        case "number":
-            return createNumericExample(node);
-        case "boolean":
-            return true;
-        case "array":
-            return createArrayExample(node, key);
-        case "object":
-            return Object.fromEntries(Object.entries(node.properties ?? {}).map(([propertyKey, propertyNode]) => [
-                propertyKey,
-                createExampleValue(propertyNode, propertyKey),
-            ]));
-        case "union": {
-            const firstBranch = node.union
-                ? Object.values(node.union.branches)[0]
-                : undefined;
-            if (!firstBranch || firstBranch.kind !== "object") {
-                return {};
-            }
-            return Object.fromEntries(Object.entries(firstBranch.properties ?? {}).map(([propertyKey, propertyNode]) => [
-                propertyKey,
-                createExampleValue(propertyNode, propertyKey),
-            ]));
-        }
-    }
-}
-function createFormattedStringExample(format, key) {
-    switch (format) {
-        case "uuid":
-            return "00000000-0000-4000-8000-000000000000";
-        case "email":
-            return "example@example.com";
-        case "url":
-        case "uri":
-            return "https://example.com";
-        case "ipv4":
-            return "127.0.0.1";
-        case "ipv6":
-            return "::1";
-        case "date-time":
-            return "2024-01-01T00:00:00Z";
-        default:
-            return `Example ${key}`;
-    }
-}
-function fitStringExampleToConstraints(value, constraints) {
-    let nextValue = value;
-    if (constraints.maxLength !== null &&
-        nextValue.length > constraints.maxLength) {
-        nextValue = nextValue.slice(0, constraints.maxLength);
-    }
-    if (constraints.minLength !== null &&
-        nextValue.length < constraints.minLength) {
-        nextValue = nextValue.padEnd(constraints.minLength, "x");
-    }
-    return nextValue;
-}
-function createNumericExample(node) {
-    const { exclusiveMaximum, exclusiveMinimum, maximum, minimum, multipleOf, } = node.constraints;
-    const step = multipleOf && multipleOf !== 0 ? multipleOf : 1;
-    const minCandidate = minimum ?? (exclusiveMinimum !== null ? exclusiveMinimum + step : null);
-    const maxCandidate = maximum ?? (exclusiveMaximum !== null ? exclusiveMaximum - step : null);
-    let candidate = multipleOf && multipleOf !== 0
-        ? minCandidate !== null
-            ? Math.ceil(minCandidate / multipleOf) * multipleOf
-            : maxCandidate !== null
-                ? Math.floor(maxCandidate / multipleOf) * multipleOf
-                : multipleOf
-        : minCandidate ?? maxCandidate ?? 42;
-    if (maxCandidate !== null && candidate > maxCandidate) {
-        candidate =
-            multipleOf && multipleOf !== 0
-                ? Math.floor(maxCandidate / multipleOf) * multipleOf
-                : maxCandidate;
-    }
-    if (minCandidate !== null && candidate < minCandidate) {
-        candidate =
-            multipleOf && multipleOf !== 0
-                ? Math.ceil(minCandidate / multipleOf) * multipleOf
-                : minCandidate;
-    }
-    return candidate;
-}
-function createArrayExample(node, key) {
-    const minimumItems = Math.max(node.constraints.minItems ?? 0, 0);
-    if (minimumItems === 0 || node.items === undefined) {
-        return [];
-    }
-    return Array.from({ length: minimumItems }, (_value, index) => createExampleValue(node.items, `${key}${index + 1}`));
-}
+/**
+ * Re-exports metadata projection utilities from `@wp-typia/block-runtime`.
+ * This adapter keeps the public project-tools runtime path stable while the
+ * implementation is consolidated in block-runtime.
+ * @module
+ */
+export * from "@wp-typia/block-runtime/metadata-projection";

package/dist/runtime/object-utils.d.ts

@@ -3,7 +3,7 @@
  */
 export type UnknownRecord = Record<string, unknown>;
 /**
- * Check whether a value is a plain object record.
+ * Delegate plain-object detection to the shared runtime primitive owner.
  *
  * @param value Runtime value to inspect.
  * @returns `true` when the value is a non-null plain object with an

package/dist/runtime/object-utils.js

@@ -1,14 +1,11 @@
+import { isPlainObject as isSharedPlainObject } from "@wp-typia/api-client/runtime-primitives";
 /**
- * Check whether a value is a plain object record.
+ * Delegate plain-object detection to the shared runtime primitive owner.
  *
  * @param value Runtime value to inspect.
  * @returns `true` when the value is a non-null plain object with an
  * `Object.prototype` or `null` prototype.
  */
 export function isPlainObject(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
+    return isSharedPlainObject(value);
 }

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;
 }