@wp-typia/project-tools 0.16.0 → 0.16.2

package/README.md

@@ -14,6 +14,12 @@ Supported public imports:
 - `@wp-typia/project-tools`
 - `@wp-typia/project-tools/schema-core`
 
+Implementation note:
+
+- `@wp-typia/project-tools/schema-core` remains the preferred project-tooling
+  import path.
+- The shared implementation now lives in `@wp-typia/block-runtime/schema-core`.
+
 Example:
 
 ```ts

package/dist/runtime/cli-help.js

@@ -34,7 +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 ...\`.
+  Use \`--template workspace\` as shorthand for \`@wp-typia/create-workspace-template\`, 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/package-versions.js

@@ -15,6 +15,9 @@ function normalizeVersionRange(value) {
     if (!trimmed) {
         return DEFAULT_VERSION_RANGE;
     }
+    if (trimmed.startsWith("workspace:")) {
+        return DEFAULT_VERSION_RANGE;
+    }
     return /^[~^<>=]/.test(trimmed) ? trimmed : `^${trimmed}`;
 }
 function readPackageManifest(packageJsonPath) {
@@ -52,11 +55,13 @@ export function getPackageVersions() {
     const wpTypiaManifest = readPackageManifest(path.join(PROJECT_TOOLS_PACKAGE_ROOT, "..", "wp-typia", "package.json")) ??
         resolveInstalledPackageManifest("wp-typia") ??
         {};
+    const blockRuntimeDependencyVersion = normalizeVersionRange(createManifest.dependencies?.["@wp-typia/block-runtime"]);
     cachedPackageVersions = {
         apiClientPackageVersion: normalizeVersionRange(createManifest.dependencies?.["@wp-typia/api-client"] ??
             resolveInstalledPackageManifest("@wp-typia/api-client")?.version),
-        blockRuntimePackageVersion: normalizeVersionRange(createManifest.dependencies?.["@wp-typia/block-runtime"] ??
-            blockRuntimeManifest.version),
+        blockRuntimePackageVersion: blockRuntimeDependencyVersion !== DEFAULT_VERSION_RANGE
+            ? blockRuntimeDependencyVersion
+            : normalizeVersionRange(blockRuntimeManifest.version),
         blockTypesPackageVersion: normalizeVersionRange(createManifest.dependencies?.["@wp-typia/block-types"] ??
             resolveInstalledPackageManifest("@wp-typia/block-types")?.version),
         projectToolsPackageVersion: normalizeVersionRange(createManifest.version),

package/dist/runtime/scaffold.js

@@ -19,6 +19,7 @@ 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 WORKSPACE_TEMPLATE_ALIAS = "workspace";
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 const LOCKFILES = {
     bun: ["bun.lock", "bun.lockb"],
@@ -138,15 +139,21 @@ export function getDefaultAnswers(projectName, templateId) {
         title: toTitleCase(slugDefault),
     };
 }
+function normalizeTemplateSelection(templateId) {
+    return templateId === WORKSPACE_TEMPLATE_ALIAS
+        ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        : templateId;
+}
 export async function resolveTemplateId({ templateId, yes = false, isInteractive = false, selectTemplate, }) {
     if (templateId) {
+        const normalizedTemplateId = normalizeTemplateSelection(templateId);
         if (isRemovedBuiltInTemplateId(templateId)) {
             throw new Error(getRemovedBuiltInTemplateMessage(templateId));
         }
-        if (isBuiltInTemplateId(templateId)) {
-            return getTemplateById(templateId).id;
+        if (isBuiltInTemplateId(normalizedTemplateId)) {
+            return getTemplateById(normalizedTemplateId).id;
         }
-        return templateId;
+        return normalizedTemplateId;
     }
     if (yes) {
         return "basic";
@@ -154,7 +161,7 @@ export async function resolveTemplateId({ templateId, yes = false, isInteractive
     if (!isInteractive || !selectTemplate) {
         throw new Error(`Template is required in non-interactive mode. Use --template <${TEMPLATE_IDS.join("|")}|./path|github:owner/repo/path[#ref]|npm-package>.`);
     }
-    return selectTemplate();
+    return normalizeTemplateSelection(await selectTemplate());
 }
 export async function resolvePackageManagerId({ packageManager, yes = false, isInteractive = false, selectPackageManager, }) {
     if (packageManager) {
@@ -628,14 +635,15 @@ async function applyWorkspaceMigrationCapability(projectDir, packageManager) {
     writeInitialMigrationScaffold(projectDir, "v1", []);
 }
 export async function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+    const resolvedTemplateId = normalizeTemplateSelection(templateId);
     const resolvedPackageManager = getPackageManager(packageManager).id;
-    const isBuiltInTemplate = isBuiltInTemplateId(templateId);
-    const variables = getTemplateVariables(templateId, {
+    const isBuiltInTemplate = isBuiltInTemplateId(resolvedTemplateId);
+    const variables = getTemplateVariables(resolvedTemplateId, {
         ...answers,
         dataStorageMode: dataStorageMode ?? answers.dataStorageMode,
         persistencePolicy: persistencePolicy ?? answers.persistencePolicy,
     });
-    const templateSource = await resolveTemplateSource(templateId, cwd, variables, variant);
+    const templateSource = await resolveTemplateSource(resolvedTemplateId, cwd, variables, variant);
     const supportsMigrationUi = isBuiltInTemplate || templateSource.isOfficialWorkspaceTemplate === true;
     if (withMigrationUi && !supportsMigrationUi) {
         await templateSource.cleanup?.();
@@ -652,8 +660,8 @@ 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 writeStarterManifestFiles(projectDir, resolvedTemplateId, variables);
+        await seedBuiltInPersistenceArtifacts(projectDir, resolvedTemplateId, variables);
         await applyLocalDevPresetFiles({
             projectDir,
             variables,
@@ -664,7 +672,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
             await applyMigrationUiCapability({
                 packageManager: resolvedPackageManager,
                 projectDir,
-                templateId,
+                templateId: resolvedTemplateId,
                 variables,
             });
         }
@@ -674,7 +682,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
     }
     const readmePath = path.join(projectDir, "README.md");
     if (!fs.existsSync(readmePath)) {
-        await fsp.writeFile(readmePath, buildReadme(templateId, variables, resolvedPackageManager, {
+        await fsp.writeFile(readmePath, buildReadme(resolvedTemplateId, variables, resolvedPackageManager, {
             withMigrationUi: isBuiltInTemplate || isOfficialWorkspace ? withMigrationUi : false,
             withTestPreset: isBuiltInTemplate ? withTestPreset : false,
             withWpEnv: isBuiltInTemplate ? withWpEnv : false,
@@ -691,7 +699,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
             compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
             packageManager: resolvedPackageManager,
             projectDir,
-            templateId,
+            templateId: resolvedTemplateId,
             withTestPreset,
             withWpEnv,
         });
@@ -709,7 +717,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
     return {
         projectDir,
         selectedVariant: templateSource.selectedVariant ?? null,
-        templateId,
+        templateId: resolvedTemplateId,
         packageManager: resolvedPackageManager,
         variables,
         warnings: templateSource.warnings ?? [],

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

@@ -1,268 +1,7 @@
-import type { JsonValue, ManifestAttribute, ManifestDocument } from "./migration-types.js";
-export interface JsonSchemaObject {
-    [key: string]: JsonValue | JsonSchemaObject | JsonSchemaObject[] | undefined;
-}
 /**
- * Full JSON Schema document for a manifest-derived root object.
+ * Re-exports schema and OpenAPI helpers from `@wp-typia/block-runtime`.
+ * This adapter preserves the public `@wp-typia/project-tools/schema-core`
+ * path while sharing the canonical implementation with block-runtime.
+ * @module
  */
-export interface JsonSchemaDocument extends JsonSchemaObject {
-    $schema: string;
-    additionalProperties: boolean;
-    properties: Record<string, JsonSchemaObject>;
-    required: string[];
-    title: string;
-    type: "object";
-}
-/**
- * Document-level metadata applied to generated OpenAPI files.
- */
-export interface OpenApiInfo {
-    description?: string;
-    title?: string;
-    version?: string;
-}
-/**
- * JSON Schema reference used inside generated OpenAPI documents.
- */
-export interface OpenApiSchemaReference extends JsonSchemaObject {
-    $ref: string;
-}
-/**
- * OpenAPI query parameter emitted from a manifest attribute.
- */
-export interface OpenApiParameter extends JsonSchemaObject {
-    in: "query";
-    name: string;
-    required: boolean;
-    schema: JsonSchemaObject;
-}
-/**
- * OpenAPI media type wrapper for JSON responses and request bodies.
- */
-export interface OpenApiMediaType extends JsonSchemaObject {
-    schema: OpenApiSchemaReference;
-}
-/**
- * OpenAPI request body definition for generated JSON endpoints.
- */
-export interface OpenApiRequestBody extends JsonSchemaObject {
-    content: {
-        "application/json": OpenApiMediaType;
-    };
-    required: true;
-}
-/**
- * Successful JSON response entry in the generated OpenAPI document.
- */
-export interface OpenApiResponse extends JsonSchemaObject {
-    content: {
-        "application/json": OpenApiMediaType;
-    };
-    description: string;
-    headers?: Record<string, JsonSchemaObject>;
-}
-/**
- * Header-based security scheme used by authenticated WordPress REST routes.
- */
-export interface OpenApiSecurityScheme extends JsonSchemaObject {
-    description?: string;
-    in: "header";
-    name: string;
-    type: "apiKey";
-}
-/**
- * One generated OpenAPI operation for a scaffolded REST endpoint.
- */
-export interface OpenApiOperation extends JsonSchemaObject {
-    operationId: string;
-    parameters?: OpenApiParameter[];
-    requestBody?: OpenApiRequestBody;
-    responses: Record<string, OpenApiResponse>;
-    security?: Array<Record<string, string[]>>;
-    summary?: string;
-    tags: string[];
-    "x-typia-authIntent": EndpointAuthIntent;
-    "x-wp-typia-authPolicy"?: EndpointOpenApiAuthMode;
-    "x-wp-typia-publicTokenField"?: string;
-}
-/**
- * Path item containing one or more generated REST operations.
- */
-export type OpenApiPathItem = JsonSchemaObject & Partial<Record<Lowercase<EndpointOpenApiMethod>, OpenApiOperation>>;
-/**
- * Named tag entry surfaced at the top level of generated OpenAPI docs.
- */
-export interface OpenApiTag extends JsonSchemaObject {
-    name: string;
-}
-/**
- * OpenAPI component registry for generated schemas and security schemes.
- */
-export interface OpenApiComponents extends JsonSchemaObject {
-    schemas: Record<string, JsonSchemaDocument>;
-    securitySchemes?: Record<string, OpenApiSecurityScheme>;
-}
-/**
- * Complete OpenAPI 3.1 document emitted for endpoint-aware REST contracts.
- */
-export interface OpenApiDocument extends JsonSchemaObject {
-    components: OpenApiComponents;
-    info: {
-        description?: string;
-        title: string;
-        version: string;
-    };
-    openapi: "3.1.0";
-    paths: Record<string, OpenApiPathItem>;
-    tags?: OpenApiTag[];
-}
-/**
- * Backend-neutral auth intent for one manifest-defined endpoint.
- */
-export type EndpointAuthIntent = "authenticated" | "public" | "public-write-protected";
-/**
- * WordPress-specific authentication mechanisms that can implement neutral auth intent.
- */
-export type EndpointWordPressAuthMechanism = "public-signed-token" | "rest-nonce";
-/**
- * Optional WordPress adapter metadata that explains how the default runtime satisfies auth intent.
- */
-export interface EndpointWordPressAuthDefinition {
-    mechanism: EndpointWordPressAuthMechanism;
-    publicTokenField?: string;
-}
-/**
- * Legacy WordPress auth-mode literals kept for backward compatibility.
- */
-export type EndpointOpenApiAuthMode = "authenticated-rest-nonce" | "public-read" | "public-signed-token";
-/**
- * Supported HTTP methods for generated REST OpenAPI endpoints.
- */
-export type EndpointOpenApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
-/**
- * Contract document used when composing an endpoint-aware OpenAPI file.
- */
-export interface EndpointOpenApiContractDocument {
-    /** Manifest-derived contract document for this schema component. */
-    document: ManifestDocument;
-    /** Optional component name override for the generated schema reference. */
-    schemaName?: string;
-}
-interface EndpointOpenApiEndpointBaseDefinition {
-    /** Authentication policy surfaced in OpenAPI metadata. */
-    auth?: EndpointAuthIntent;
-    /** @deprecated Prefer `auth` plus `wordpressAuth` for new manifests. */
-    authMode?: EndpointOpenApiAuthMode;
-    /** Contract key for a JSON request body, when the endpoint accepts one. */
-    bodyContract?: string;
-    /** HTTP method exposed by the route. */
-    method: EndpointOpenApiMethod;
-    /** Stable OpenAPI operation id for this route. */
-    operationId: string;
-    /** Absolute REST path including namespace and version. */
-    path: string;
-    /** Contract key for query parameters, when the endpoint reads from the query string. */
-    queryContract?: string;
-    /** Contract key for the successful JSON response body. */
-    responseContract: string;
-    /** Optional short endpoint summary shown in generated docs. */
-    summary?: string;
-    /** OpenAPI tag names applied to this endpoint. */
-    tags: readonly string[];
-    /** Optional WordPress adapter metadata for the default runtime. */
-    wordpressAuth?: EndpointWordPressAuthDefinition;
-}
-/**
- * Route metadata for one REST endpoint in the aggregate OpenAPI document.
- */
-export type EndpointOpenApiEndpointDefinition = (EndpointOpenApiEndpointBaseDefinition & {
-    auth: EndpointAuthIntent;
-}) | (EndpointOpenApiEndpointBaseDefinition & {
-    /** @deprecated Prefer `auth` plus `wordpressAuth` for new manifests. */
-    authMode: EndpointOpenApiAuthMode;
-});
-export interface NormalizedEndpointAuthDefinition {
-    auth: EndpointAuthIntent;
-    authMode?: EndpointOpenApiAuthMode;
-    wordpressAuth?: EndpointWordPressAuthDefinition;
-}
-/**
- * Options for building an aggregate endpoint-aware OpenAPI document.
- */
-export interface EndpointOpenApiDocumentOptions {
-    /** Named contract documents keyed by the endpoint registry identifiers. */
-    contracts: Readonly<Record<string, EndpointOpenApiContractDocument>>;
-    /** Route definitions that should appear in the generated OpenAPI file. */
-    endpoints: readonly EndpointOpenApiEndpointDefinition[];
-    /** Optional document-level OpenAPI info metadata. */
-    info?: OpenApiInfo;
-}
-/**
- * Supported schema projection profiles derived from one canonical wp-typia JSON Schema document.
- */
-export type JsonSchemaProjectionProfile = "ai-structured-output" | "rest";
-/**
- * Options for projecting one generated JSON Schema document into another consumer-facing profile.
- */
-export interface JsonSchemaProjectionOptions {
-    /** Projection profile that controls schema transformation rules. */
-    profile: JsonSchemaProjectionProfile;
-}
-/**
- * Converts one manifest attribute definition into a JSON Schema fragment.
- *
- * @param attribute Manifest-derived attribute metadata.
- * @returns A JSON-compatible schema fragment for the attribute.
- */
-export declare function manifestAttributeToJsonSchema(attribute: ManifestAttribute): JsonSchemaObject;
-/**
- * Builds a full JSON Schema document from a Typia manifest document.
- *
- * @param doc Manifest-derived attribute document.
- * @returns A draft 2020-12 JSON Schema document for the manifest root object.
- */
-export declare function manifestToJsonSchema(doc: ManifestDocument): JsonSchemaDocument;
-/**
- * Projects one generated wp-typia JSON Schema document into a consumer-facing profile.
- *
- * @param schema Existing generated JSON Schema document.
- * @param options Projection profile options.
- * @returns A cloned schema document adjusted for the requested profile.
- */
-export declare function projectJsonSchemaDocument<Schema extends JsonSchemaDocument | JsonSchemaObject>(schema: Schema, options: JsonSchemaProjectionOptions): Schema;
-/**
- * Wraps a manifest-derived JSON Schema document in a minimal OpenAPI 3.1 shell.
- *
- * @param doc Manifest-derived attribute document.
- * @param info Optional OpenAPI document metadata.
- * @returns An OpenAPI document containing the schema as a single component.
- */
-export declare function manifestToOpenApi(doc: ManifestDocument, info?: OpenApiInfo): OpenApiDocument;
-/**
- * Normalizes endpoint auth metadata into backend-neutral intent plus optional
- * WordPress adapter details.
- *
- * This public runtime helper accepts either the authored `auth` and optional
- * `wordpressAuth` shape or the deprecated `authMode` field. It validates that
- * the provided fields are compatible, resolves the legacy compatibility mode,
- * and returns a normalized definition without mutating the input endpoint.
- *
- * @param endpoint - Endpoint auth fields to normalize, including `auth`,
- * `authMode`, `wordpressAuth`, and optional identity fields used in error
- * messages (`operationId`, `path`, and `method`).
- * @returns The normalized auth definition for the endpoint.
- * @throws When `auth` and deprecated `authMode` conflict.
- * @throws When `wordpressAuth` is attached to the `public` auth intent.
- * @throws When the selected `wordpressAuth` mechanism is incompatible with the
- * chosen auth intent.
- * @throws When neither `auth` nor deprecated `authMode` is defined.
- */
-export declare function normalizeEndpointAuthDefinition(endpoint: Pick<EndpointOpenApiEndpointDefinition, "auth" | "authMode" | "operationId" | "path" | "wordpressAuth" | "method">): NormalizedEndpointAuthDefinition;
-/**
- * Build a complete OpenAPI 3.1 document from contract manifests and route metadata.
- *
- * @param options Aggregate contract and endpoint definitions for the REST surface.
- * @returns A JSON-compatible OpenAPI document with paths, components, and auth metadata.
- */
-export declare function buildEndpointOpenApiDocument(options: EndpointOpenApiDocumentOptions): OpenApiDocument;
-export {};
+export * from "@wp-typia/block-runtime/schema-core";