@wp-typia/project-tools 0.24.3 → 0.24.5

package/dist/runtime/add/ai-feature-capability.js

@@ -0,0 +1,139 @@
+/** Declares whether a generated feature is optional or required at runtime. */
+import { pickHigherVersionFloor } from '../shared/version-floor.js';
+/** Canonical registry of AI-related features supported by wp-typia today. */
+export const AI_FEATURE_DEFINITIONS = {
+    wordpressAiClient: {
+        description: 'WordPress 7.0 AI Client surface used by AI-capable feature endpoints.',
+        id: 'wordpress-ai-client',
+        label: 'WordPress AI Client',
+        minimumVersions: {
+            wordpress: '7.0',
+        },
+        runtimeGates: [
+            {
+                kind: 'wordpress-core-feature',
+                value: 'WordPress AI Client',
+            },
+        ],
+    },
+    wordpressCoreAbilities: {
+        description: 'Client-side ability discovery surface for editor and admin flows.',
+        id: 'wordpress-core-abilities',
+        label: '@wordpress/core-abilities',
+        minimumVersions: {
+            wordpress: '7.0',
+        },
+        runtimeGates: [
+            {
+                kind: 'script-package',
+                value: '@wordpress/core-abilities',
+            },
+        ],
+    },
+    wordpressMcpPublicMetadata: {
+        description: 'Optional MCP exposure metadata consumed by a separate adapter path rather than core alone.',
+        id: 'wordpress-mcp-public-metadata',
+        label: 'MCP public metadata',
+        runtimeGates: [
+            {
+                kind: 'adapter',
+                value: 'MCP adapter',
+            },
+        ],
+    },
+    wordpressServerAbilities: {
+        description: 'Server-side ability registration and execution surface for WordPress-native abilities.',
+        id: 'wordpress-server-abilities',
+        label: 'WordPress Abilities API',
+        minimumVersions: {
+            wordpress: '6.9',
+        },
+        runtimeGates: [
+            {
+                kind: 'php-function',
+                value: 'wp_register_ability',
+            },
+            {
+                kind: 'php-function',
+                value: 'wp_register_ability_category',
+            },
+        ],
+    },
+};
+const DEFAULT_AI_FEATURE_REGISTRY = Object.values(AI_FEATURE_DEFINITIONS).reduce((accumulator, definition) => {
+    accumulator[definition.id] = definition;
+    return accumulator;
+}, {});
+function normalizeSelections(selections) {
+    const normalized = new Map();
+    for (const selection of selections) {
+        const current = normalized.get(selection.featureId);
+        if (!current || selection.mode === 'required') {
+            normalized.set(selection.featureId, selection);
+        }
+    }
+    return [...normalized.values()];
+}
+function validateFeatureMinimumVersions(definition) {
+    for (const [platform, value] of [
+        ['wordpress', definition.minimumVersions?.wordpress],
+        ['php', definition.minimumVersions?.php],
+    ]) {
+        if (value === undefined) {
+            continue;
+        }
+        try {
+            pickHigherVersionFloor(value, undefined);
+        }
+        catch (error) {
+            throw new Error([
+                `Invalid ${platform} minimum version floor for AI feature "${definition.id}": "${value}".`,
+                'Expected dotted numeric segments such as "6.7" or "8.1.2".',
+            ].join(' '), { cause: error });
+        }
+    }
+}
+/**
+ * Resolves a normalized AI feature capability plan from a list of selections.
+ *
+ * Required selections win when the same feature id appears multiple times, and
+ * the resulting hard minimum platform floor is computed from required features
+ * only.
+ *
+ * @param selections Desired feature selections for a scaffold or projection.
+ * @param registry Feature registry to resolve against. Defaults to the built-in registry.
+ * @returns The normalized capability plan plus required version floors.
+ * @throws When a selection references an unknown feature id.
+ */
+export function resolveAiFeatureCapabilityPlan(selections, registry = DEFAULT_AI_FEATURE_REGISTRY) {
+    const requiredFeatures = [];
+    const optionalFeatures = [];
+    let wordpress;
+    let php;
+    for (const selection of normalizeSelections(selections)) {
+        const definition = registry[selection.featureId];
+        if (!definition) {
+            throw new Error(`Unknown AI feature capability "${selection.featureId}".`);
+        }
+        validateFeatureMinimumVersions(definition);
+        const resolvedDefinition = {
+            ...definition,
+            mode: selection.mode,
+        };
+        if (selection.mode === 'required') {
+            requiredFeatures.push(resolvedDefinition);
+            wordpress = pickHigherVersionFloor(wordpress, definition.minimumVersions?.wordpress);
+            php = pickHigherVersionFloor(php, definition.minimumVersions?.php);
+            continue;
+        }
+        optionalFeatures.push(resolvedDefinition);
+    }
+    return {
+        hardMinimums: {
+            ...(php ? { php } : {}),
+            ...(wordpress ? { wordpress } : {}),
+        },
+        optionalFeatures,
+        requiredFeatures,
+    };
+}

package/dist/runtime/add/alternate-render-targets.d.ts

@@ -0,0 +1,5 @@
+export declare const ALTERNATE_RENDER_TARGET_IDS: readonly ["email", "mjml", "plain-text"];
+export type AlternateRenderTargetId = (typeof ALTERNATE_RENDER_TARGET_IDS)[number];
+export declare function isAlternateRenderTargetId(value: string): value is AlternateRenderTargetId;
+export declare function parseAlternateRenderTargets(value?: string): AlternateRenderTargetId[];
+export declare function formatAlternateRenderTargets(targets: readonly AlternateRenderTargetId[]): string;

package/dist/runtime/add/alternate-render-targets.js

@@ -0,0 +1,29 @@
+export const ALTERNATE_RENDER_TARGET_IDS = [
+    "email",
+    "mjml",
+    "plain-text",
+];
+export function isAlternateRenderTargetId(value) {
+    return ALTERNATE_RENDER_TARGET_IDS.includes(value);
+}
+export function parseAlternateRenderTargets(value) {
+    if (typeof value !== "string") {
+        return [];
+    }
+    const normalized = value
+        .split(",")
+        .map((entry) => entry.trim().toLowerCase())
+        .filter(Boolean);
+    if (normalized.length === 0) {
+        return [];
+    }
+    const deduped = Array.from(new Set(normalized));
+    const invalid = deduped.filter((entry) => !isAlternateRenderTargetId(entry));
+    if (invalid.length > 0) {
+        throw new Error(`Unsupported alternate render target${invalid.length > 1 ? "s" : ""} "${invalid.join(", ")}". Expected one of: ${ALTERNATE_RENDER_TARGET_IDS.join(", ")}.`);
+    }
+    return deduped;
+}
+export function formatAlternateRenderTargets(targets) {
+    return targets.join(", ");
+}

package/dist/runtime/add/block-targets.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Caller-owned error messages for full block name validation.
+ */
+export interface FullBlockNameDiagnostics {
+    /**
+     * Message returned when the candidate block name is empty.
+     */
+    empty: () => string;
+    /**
+     * Message returned when the candidate is not `namespace/block-slug`.
+     */
+    invalidFormat: () => string;
+}
+export interface WorkspaceBlockTargetName {
+    blockName: string;
+    blockSlug: string;
+}
+export interface WorkspaceBlockTargetDiagnostics {
+    empty: () => string;
+    emptySegment: (input: string) => string;
+    invalidFormat: (input: string) => string;
+    namespaceMismatch: (input: string, actualNamespace: string, expectedNamespace: string) => string;
+}
+/**
+ * Validate a full `namespace/block-slug` block name.
+ *
+ * @param blockName Candidate block name.
+ * @param diagnostics CLI flag name or diagnostic builders for caller-owned UX.
+ * @returns The trimmed full block name.
+ * @throws {Error} When the block name is empty or not a full block name.
+ */
+export declare function assertFullBlockName(blockName: string, diagnostics: string | FullBlockNameDiagnostics): string;
+/**
+ * Resolve a workspace block target from either `block-slug` or
+ * `namespace/block-slug` input while preserving caller-owned diagnostics.
+ *
+ * @param blockName Candidate block target.
+ * @param namespace Expected workspace namespace.
+ * @param diagnostics Error message builders for the caller's UX context.
+ * @returns The normalized workspace block target.
+ * @throws {Error} When the target is empty, malformed, or references another namespace.
+ */
+export declare function resolveWorkspaceBlockTargetName(blockName: string, namespace: string, diagnostics: WorkspaceBlockTargetDiagnostics): WorkspaceBlockTargetName;
+/**
+ * Resolve the standard `--to` style workspace block target used by add flows.
+ *
+ * @param blockName Candidate block target.
+ * @param namespace Expected workspace namespace.
+ * @param flagName CLI flag name used in diagnostics.
+ * @returns The normalized workspace block target.
+ * @throws {Error} When the target is empty, malformed, or references another namespace.
+ */
+export declare function resolveWorkspaceTargetBlockName(blockName: string, namespace: string, flagName: string): WorkspaceBlockTargetName;

package/dist/runtime/add/block-targets.js

@@ -0,0 +1,81 @@
+import { normalizeBlockSlug } from "../templates/scaffold-identifiers.js";
+const FULL_BLOCK_NAME_PATTERN = /^[a-z0-9-]+\/[a-z0-9-]+$/u;
+function resolveFullBlockNameDiagnostics(diagnostics) {
+    if (typeof diagnostics !== "string") {
+        return diagnostics;
+    }
+    return {
+        empty: () => `\`${diagnostics}\` requires a block name.`,
+        invalidFormat: () => `\`${diagnostics}\` must use <namespace/block-slug> format.`,
+    };
+}
+/**
+ * Validate a full `namespace/block-slug` block name.
+ *
+ * @param blockName Candidate block name.
+ * @param diagnostics CLI flag name or diagnostic builders for caller-owned UX.
+ * @returns The trimmed full block name.
+ * @throws {Error} When the block name is empty or not a full block name.
+ */
+export function assertFullBlockName(blockName, diagnostics) {
+    const messages = resolveFullBlockNameDiagnostics(diagnostics);
+    const trimmed = blockName.trim();
+    if (!trimmed) {
+        throw new Error(messages.empty());
+    }
+    if (!FULL_BLOCK_NAME_PATTERN.test(trimmed)) {
+        throw new Error(messages.invalidFormat());
+    }
+    return trimmed;
+}
+/**
+ * Resolve a workspace block target from either `block-slug` or
+ * `namespace/block-slug` input while preserving caller-owned diagnostics.
+ *
+ * @param blockName Candidate block target.
+ * @param namespace Expected workspace namespace.
+ * @param diagnostics Error message builders for the caller's UX context.
+ * @returns The normalized workspace block target.
+ * @throws {Error} When the target is empty, malformed, or references another namespace.
+ */
+export function resolveWorkspaceBlockTargetName(blockName, namespace, diagnostics) {
+    const trimmed = blockName.trim();
+    if (!trimmed) {
+        throw new Error(diagnostics.empty());
+    }
+    const blockNameSegments = trimmed.split("/");
+    if (blockNameSegments.length > 2) {
+        throw new Error(diagnostics.invalidFormat(trimmed));
+    }
+    if (blockNameSegments.some((segment) => segment.trim() === "")) {
+        throw new Error(diagnostics.emptySegment(trimmed));
+    }
+    const [maybeNamespace, maybeSlug] = blockNameSegments.length === 2
+        ? blockNameSegments
+        : [undefined, blockNameSegments[0]];
+    if (maybeNamespace && maybeNamespace !== namespace) {
+        throw new Error(diagnostics.namespaceMismatch(trimmed, maybeNamespace, namespace));
+    }
+    const blockSlug = normalizeBlockSlug(maybeSlug ?? "");
+    return {
+        blockName: `${namespace}/${blockSlug}`,
+        blockSlug,
+    };
+}
+/**
+ * Resolve the standard `--to` style workspace block target used by add flows.
+ *
+ * @param blockName Candidate block target.
+ * @param namespace Expected workspace namespace.
+ * @param flagName CLI flag name used in diagnostics.
+ * @returns The normalized workspace block target.
+ * @throws {Error} When the target is empty, malformed, or references another namespace.
+ */
+export function resolveWorkspaceTargetBlockName(blockName, namespace, flagName) {
+    return resolveWorkspaceBlockTargetName(blockName, namespace, {
+        empty: () => `\`${flagName}\` requires <block-slug|namespace/block-slug>.`,
+        emptySegment: () => `\`${flagName}\` must use <block-slug|namespace/block-slug> format.`,
+        invalidFormat: () => `\`${flagName}\` must use <block-slug|namespace/block-slug> format.`,
+        namespaceMismatch: (_input, actualNamespace, expectedNamespace) => `\`${flagName}\` references namespace "${actualNamespace}". Expected "${expectedNamespace}".`,
+    });
+}

package/dist/runtime/add/cli-add-block-config.d.ts

@@ -0,0 +1,6 @@
+import type { MigrationBlockConfig } from "../migration/migration-types.js";
+import type { ScaffoldTemplateVariables } from "../templates/scaffold.js";
+import { type AddBlockTemplateId } from "./cli-add-shared.js";
+export declare function buildServerTemplateRoot(persistencePolicy: string | undefined): string;
+export declare function buildConfigEntries(templateId: AddBlockTemplateId, variables: ScaffoldTemplateVariables): string[];
+export declare function buildMigrationBlocks(templateId: AddBlockTemplateId, variables: ScaffoldTemplateVariables): MigrationBlockConfig[];

package/dist/runtime/add/cli-add-block-config.js

@@ -0,0 +1,144 @@
+import path from "node:path";
+import { SHARED_WORKSPACE_TEMPLATE_ROOT, } from "../templates/template-registry.js";
+import { isCompoundPersistenceEnabled } from "../templates/scaffold-template-variable-groups.js";
+import { quoteTsString, } from "./cli-add-shared.js";
+export function buildServerTemplateRoot(persistencePolicy) {
+    return path.join(SHARED_WORKSPACE_TEMPLATE_ROOT, persistencePolicy === "public" ? "persistence-public" : "persistence-auth");
+}
+function buildSingleBlockConfigEntry(variables) {
+    return [
+        "\t{",
+        `\t\tslug: ${quoteTsString(variables.slugKebabCase)},`,
+        `\t\tattributeTypeName: ${quoteTsString(`${variables.pascalCase}Attributes`)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}/types.ts`)},`,
+        "\t},",
+    ].join("\n");
+}
+function buildPersistenceBlockConfigEntry(variables) {
+    return [
+        "\t{",
+        `\t\tapiTypesFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}/api-types.ts`)},`,
+        `\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'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{",
+        "\t\t\t\t\tauth: 'public',",
+        "\t\t\t\t\tmethod: 'GET',",
+        `\t\t\t\t\toperationId: ${quoteTsString(`get${variables.pascalCase}State`)},`,
+        `\t\t\t\t\tpath: ${quoteTsString(`/${variables.namespace}/v1/${variables.slugKebabCase}/state`)},`,
+        "\t\t\t\t\tqueryContract: 'state-query',",
+        "\t\t\t\t\tresponseContract: 'state-response',",
+        `\t\t\t\t\tsummary: 'Read the current persisted state.',`,
+        `\t\t\t\t\ttags: [ ${quoteTsString(variables.title)} ],`,
+        "\t\t\t\t},",
+        "\t\t\t\t{",
+        `\t\t\t\t\tauth: ${quoteTsString(variables.restWriteAuthIntent)},`,
+        "\t\t\t\t\tbodyContract: 'write-state-request',",
+        "\t\t\t\t\tmethod: 'POST',",
+        `\t\t\t\t\toperationId: ${quoteTsString(`write${variables.pascalCase}State`)},`,
+        `\t\t\t\t\tpath: ${quoteTsString(`/${variables.namespace}/v1/${variables.slugKebabCase}/state`)},`,
+        "\t\t\t\t\tresponseContract: 'state-response',",
+        `\t\t\t\t\tsummary: 'Write the current persisted state.',`,
+        `\t\t\t\t\ttags: [ ${quoteTsString(variables.title)} ],`,
+        "\t\t\t\t\twordpressAuth: {",
+        `\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`)},`,
+        "\t\t\t\tversion: '1.0.0',",
+        "\t\t\t},",
+        "\t\t} ),",
+        `\t\topenApiFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}/api.openapi.json`)},`,
+        `\t\tslug: ${quoteTsString(variables.slugKebabCase)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}/types.ts`)},`,
+        "\t},",
+    ].join("\n");
+}
+function buildCompoundChildConfigEntry(variables) {
+    return [
+        "\t{",
+        `\t\tslug: ${quoteTsString(`${variables.slugKebabCase}-item`)},`,
+        `\t\tattributeTypeName: ${quoteTsString(`${variables.pascalCase}ItemAttributes`)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}-item/types.ts`)},`,
+        "\t},",
+    ].join("\n");
+}
+export function buildConfigEntries(templateId, variables) {
+    if (templateId === "basic" || templateId === "interactivity") {
+        return [buildSingleBlockConfigEntry(variables)];
+    }
+    if (templateId === "persistence") {
+        return [buildPersistenceBlockConfigEntry(variables)];
+    }
+    if (isCompoundPersistenceEnabled(variables)) {
+        return [
+            buildPersistenceBlockConfigEntry(variables),
+            buildCompoundChildConfigEntry(variables),
+        ];
+    }
+    return [
+        buildSingleBlockConfigEntry(variables),
+        buildCompoundChildConfigEntry(variables),
+    ];
+}
+export function buildMigrationBlocks(templateId, variables) {
+    if (templateId === "compound") {
+        return [
+            {
+                blockJsonFile: `src/blocks/${variables.slugKebabCase}/block.json`,
+                blockName: `${variables.namespace}/${variables.slugKebabCase}`,
+                key: variables.slugKebabCase,
+                manifestFile: `src/blocks/${variables.slugKebabCase}/typia.manifest.json`,
+                saveFile: `src/blocks/${variables.slugKebabCase}/save.tsx`,
+                typesFile: `src/blocks/${variables.slugKebabCase}/types.ts`,
+            },
+            {
+                blockJsonFile: `src/blocks/${variables.slugKebabCase}-item/block.json`,
+                blockName: `${variables.namespace}/${variables.slugKebabCase}-item`,
+                key: `${variables.slugKebabCase}-item`,
+                manifestFile: `src/blocks/${variables.slugKebabCase}-item/typia.manifest.json`,
+                saveFile: `src/blocks/${variables.slugKebabCase}-item/save.tsx`,
+                typesFile: `src/blocks/${variables.slugKebabCase}-item/types.ts`,
+            },
+        ];
+    }
+    return [
+        {
+            blockJsonFile: `src/blocks/${variables.slugKebabCase}/block.json`,
+            blockName: `${variables.namespace}/${variables.slugKebabCase}`,
+            key: variables.slugKebabCase,
+            manifestFile: `src/blocks/${variables.slugKebabCase}/typia.manifest.json`,
+            saveFile: `src/blocks/${variables.slugKebabCase}/save.tsx`,
+            typesFile: `src/blocks/${variables.slugKebabCase}/types.ts`,
+        },
+    ];
+}

package/dist/runtime/add/cli-add-block-json.d.ts

@@ -0,0 +1,31 @@
+import type { WorkspaceInventory } from "../workspace/workspace-inventory.js";
+/**
+ * Resolve an existing workspace block inventory entry by slug.
+ *
+ * @param inventory Parsed workspace inventory that owns available blocks.
+ * @param blockSlug Workspace block slug to locate.
+ * @returns The matching workspace block inventory entry.
+ * @throws {Error} When the block slug is not present in the inventory.
+ */
+export declare function resolveWorkspaceBlock(inventory: WorkspaceInventory, blockSlug: string): WorkspaceInventory["blocks"][number];
+/**
+ * Read and validate a workspace block's `block.json` metadata from disk.
+ *
+ * @param projectDir Absolute workspace root directory.
+ * @param blockSlug Workspace block slug whose metadata should be read.
+ * @returns Parsed block metadata and the absolute `block.json` path.
+ * @throws {Error} When the file is missing or cannot be parsed as scaffold metadata.
+ */
+export declare function readWorkspaceBlockJson(projectDir: string, blockSlug: string): Promise<{
+    blockJson: Record<string, unknown>;
+    blockJsonPath: string;
+}>;
+/**
+ * Return a mutable `blockHooks` object for a parsed block metadata document.
+ *
+ * @param blockJson Parsed block metadata object that may be mutated.
+ * @param blockJsonRelativePath Relative path used in validation error messages.
+ * @returns The existing or newly created mutable `blockHooks` map.
+ * @throws {Error} When `blockHooks` exists but is not an object.
+ */
+export declare function getMutableBlockHooks(blockJson: Record<string, unknown>, blockJsonRelativePath: string): Record<string, string>;

package/dist/runtime/add/cli-add-block-json.js

@@ -0,0 +1,70 @@
+import path from "node:path";
+import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
+import { readOptionalUtf8File } from "../shared/fs-async.js";
+import { safeJsonParse } from "../shared/json-utils.js";
+/**
+ * Resolve an existing workspace block inventory entry by slug.
+ *
+ * @param inventory Parsed workspace inventory that owns available blocks.
+ * @param blockSlug Workspace block slug to locate.
+ * @returns The matching workspace block inventory entry.
+ * @throws {Error} When the block slug is not present in the inventory.
+ */
+export function resolveWorkspaceBlock(inventory, blockSlug) {
+    const block = inventory.blocks.find((entry) => entry.slug === blockSlug);
+    if (!block) {
+        throw new Error(`Unknown workspace block "${blockSlug}". Choose one of: ${inventory.blocks.map((entry) => entry.slug).join(", ")}`);
+    }
+    return block;
+}
+/**
+ * Read and validate a workspace block's `block.json` metadata from disk.
+ *
+ * @param projectDir Absolute workspace root directory.
+ * @param blockSlug Workspace block slug whose metadata should be read.
+ * @returns Parsed block metadata and the absolute `block.json` path.
+ * @throws {Error} When the file is missing or cannot be parsed as scaffold metadata.
+ */
+export async function readWorkspaceBlockJson(projectDir, blockSlug) {
+    const blockJsonPath = path.join(projectDir, "src", "blocks", blockSlug, "block.json");
+    const source = await readOptionalUtf8File(blockJsonPath);
+    if (source === null) {
+        throw new Error(`Missing ${path.relative(projectDir, blockJsonPath)} for workspace block "${blockSlug}".`);
+    }
+    let blockJson;
+    try {
+        blockJson = parseScaffoldBlockMetadata(safeJsonParse(source, {
+            context: "workspace block metadata",
+            filePath: blockJsonPath,
+        }));
+    }
+    catch (error) {
+        throw new Error(error instanceof Error
+            ? `Failed to parse ${path.relative(projectDir, blockJsonPath)}: ${error.message}`
+            : `Failed to parse ${path.relative(projectDir, blockJsonPath)}.`);
+    }
+    return {
+        blockJson,
+        blockJsonPath,
+    };
+}
+/**
+ * Return a mutable `blockHooks` object for a parsed block metadata document.
+ *
+ * @param blockJson Parsed block metadata object that may be mutated.
+ * @param blockJsonRelativePath Relative path used in validation error messages.
+ * @returns The existing or newly created mutable `blockHooks` map.
+ * @throws {Error} When `blockHooks` exists but is not an object.
+ */
+export function getMutableBlockHooks(blockJson, blockJsonRelativePath) {
+    const blockHooks = blockJson.blockHooks;
+    if (blockHooks === undefined) {
+        const nextHooks = {};
+        blockJson.blockHooks = nextHooks;
+        return nextHooks;
+    }
+    if (!blockHooks || typeof blockHooks !== "object" || Array.isArray(blockHooks)) {
+        throw new Error(`${blockJsonRelativePath} must define blockHooks as an object when present.`);
+    }
+    return blockHooks;
+}

package/dist/runtime/add/cli-add-block-legacy-validator.d.ts

@@ -0,0 +1,4 @@
+export declare const COMPOUND_SHARED_SUPPORT_FILES: readonly ["hooks.ts", "validator-toolkit.ts"];
+export declare function ensureBlockConfigCanAddRestManifests(source: string): string;
+export declare function collectLegacyCompoundValidatorPaths(projectDir: string): Promise<string[]>;
+export declare function ensureCompoundWorkspaceSupportFiles(projectDir: string, tempProjectDir: string, legacyValidatorPaths: readonly string[]): Promise<void>;