@wp-typia/project-tools 0.22.10 → 0.23.1

package/dist/runtime/template-source-remote.d.ts

@@ -2,8 +2,10 @@ import type { ResolvedTemplateSource, SeedSource, TemplateVariableContext } from
 /**
  * Read a remote block source and return its default block category.
  *
- * @deprecated Use `getDefaultCategoryAsync()` from async template-source paths.
- * This synchronous helper remains only for compatibility callers.
+ * @deprecated Since 0.22.10. Use `getDefaultCategoryAsync()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
  *
  * @param sourceDir Block source directory that may contain a block.json file.
  * @returns The declared block category, or "widgets" when detection fails.
@@ -20,8 +22,10 @@ export declare function getDefaultCategoryAsync(sourceDir: string): Promise<stri
  * Read `wpTypia.projectType` from a rendered or source template package
  * manifest and return it when present.
  *
- * @deprecated Use `getTemplateProjectTypeAsync()` from async template-source
- * paths. This synchronous helper remains only for compatibility callers.
+ * @deprecated Since 0.22.10. Use `getTemplateProjectTypeAsync()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
  */
 export declare function getTemplateProjectType(sourceDir: string): string | null;
 /**

package/dist/runtime/template-source-remote.js

@@ -6,6 +6,7 @@ import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, } from
 import { copyRawDirectory } from './template-render.js';
 import { createManagedTempRoot } from './temp-roots.js';
 import { pathExists } from './fs-async.js';
+import { readJsonFile, readJsonFileSync, safeJsonParse, } from './json-utils.js';
 async function cleanupSeedRootPair(cleanup, seedCleanup) {
     let cleanupError;
     try {
@@ -39,7 +40,9 @@ function readRemoteBlockJson(blockDir) {
         path.join(sourceRoot, 'block.json'),
     ]) {
         if (fs.existsSync(candidate)) {
-            return JSON.parse(fs.readFileSync(candidate, 'utf8'));
+            return readJsonFileSync(candidate, {
+                context: 'remote block metadata',
+            });
         }
     }
     throw new Error(`Unable to locate block.json in ${blockDir}`);
@@ -51,7 +54,9 @@ async function readRemoteBlockJsonAsync(blockDir) {
         path.join(sourceRoot, 'block.json'),
     ]) {
         if (await pathExists(candidate)) {
-            return JSON.parse(await fsp.readFile(candidate, 'utf8'));
+            return readJsonFile(candidate, {
+                context: 'remote block metadata',
+            });
         }
     }
     throw new Error(`Unable to locate block.json in ${blockDir}`);
@@ -59,8 +64,10 @@ async function readRemoteBlockJsonAsync(blockDir) {
 /**
  * Read a remote block source and return its default block category.
  *
- * @deprecated Use `getDefaultCategoryAsync()` from async template-source paths.
- * This synchronous helper remains only for compatibility callers.
+ * @deprecated Since 0.22.10. Use `getDefaultCategoryAsync()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
  *
  * @param sourceDir Block source directory that may contain a block.json file.
  * @returns The declared block category, or "widgets" when detection fails.
@@ -103,7 +110,10 @@ function readTemplatePackageJson(sourceDir) {
                 maxBytes: getExternalTemplatePackageJsonMaxBytes(),
             });
             return {
-                packageJson: JSON.parse(fs.readFileSync(candidate, 'utf8')),
+                packageJson: safeJsonParse(fs.readFileSync(candidate, 'utf8'), {
+                    context: 'template metadata file',
+                    filePath: candidate,
+                }),
                 sourcePath: candidate,
             };
         }
@@ -128,7 +138,10 @@ async function readTemplatePackageJsonAsync(sourceDir) {
                 maxBytes: getExternalTemplatePackageJsonMaxBytes(),
             });
             return {
-                packageJson: JSON.parse(await fsp.readFile(candidate, 'utf8')),
+                packageJson: safeJsonParse(await fsp.readFile(candidate, 'utf8'), {
+                    context: 'template metadata file',
+                    filePath: candidate,
+                }),
                 sourcePath: candidate,
             };
         }
@@ -143,8 +156,10 @@ async function readTemplatePackageJsonAsync(sourceDir) {
  * Read `wpTypia.projectType` from a rendered or source template package
  * manifest and return it when present.
  *
- * @deprecated Use `getTemplateProjectTypeAsync()` from async template-source
- * paths. This synchronous helper remains only for compatibility callers.
+ * @deprecated Since 0.22.10. Use `getTemplateProjectTypeAsync()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
  */
 export function getTemplateProjectType(sourceDir) {
     const packageJsonEntry = readTemplatePackageJson(sourceDir);
@@ -323,7 +338,9 @@ async function rewriteBlockJsonImports(directory) {
 }
 async function patchRemotePackageJson(templateDir, needsInteractivity) {
     const packageJsonPath = path.join(templateDir, 'package.json.mustache');
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, 'utf8'));
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: 'remote package template manifest',
+    });
     const existingDependencies = { ...(packageJson.dependencies ?? {}) };
     const existingDevDependencies = { ...(packageJson.devDependencies ?? {}) };
     delete existingDependencies['@wp-typia/project-tools'];

package/dist/runtime/template-source-seeds.js

@@ -9,6 +9,7 @@ import { createExternalTemplateTimeoutError, fetchWithExternalTemplateTimeout, g
 import { findReusableExternalTemplateSourceCache, isExternalTemplateCacheEnabled, resolveExternalTemplateSourceCache, } from './template-source-cache.js';
 import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from './cli-diagnostics.js';
 import { pathExists } from './fs-async.js';
+import { readJsonFile, readJsonFileSync } from './json-utils.js';
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, OFFICIAL_WORKSPACE_TEMPLATE_ALIAS, PROJECT_TOOLS_PACKAGE_ROOT, TEMPLATE_IDS, } from './template-registry.js';
 import { isPlainObject } from './object-utils.js';
 import { createManagedTempRoot } from './temp-roots.js';
@@ -206,7 +207,9 @@ function resolveInstalledNpmTemplateSource(locator, cwd) {
             if (!fs.existsSync(packageJsonPath)) {
                 continue;
             }
-            const manifest = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+            const manifest = readJsonFileSync(packageJsonPath, {
+                context: 'workspace template package manifest',
+            });
             if (manifest.name === locator.name) {
                 return {
                     blockDir: packageDir,
@@ -259,7 +262,9 @@ export function isOfficialWorkspaceTemplateSeed(seed) {
         return false;
     }
     try {
-        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        const packageJson = readJsonFileSync(packageJsonPath, {
+            context: 'workspace template seed manifest',
+        });
         return packageJson.name === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
     }
     catch {
@@ -278,7 +283,9 @@ export async function isOfficialWorkspaceTemplateSeedAsync(seed) {
         return false;
     }
     try {
-        const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, 'utf8'));
+        const packageJson = await readJsonFile(packageJsonPath, {
+            context: 'workspace template seed manifest',
+        });
         return packageJson.name === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
     }
     catch {

package/dist/runtime/workspace-inventory-mutations.js

@@ -1,13 +1,13 @@
 import path from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import { escapeRegex } from "./php-utils.js";
-import { BLOCK_INVENTORY_SECTION, INVENTORY_SECTIONS, } from "./workspace-inventory-parser.js";
+import { BLOCK_INVENTORY_SECTION, INVENTORY_SECTIONS, } from "./workspace-inventory-section-descriptors.js";
 import { WORKSPACE_COMPATIBILITY_CONFIG_FIELD } from "./workspace-inventory-templates.js";
 function ensureWorkspaceInventorySections(source) {
     let nextSource = source.trimEnd();
     for (const section of INVENTORY_SECTIONS) {
         if (section.interface &&
-            !hasExportedInterface(nextSource, section.interface.name)) {
+            !hasExportedTypeDeclaration(nextSource, section.interface.name)) {
             nextSource += section.interface.section;
         }
         if (section.value && !hasExportedConst(nextSource, section.value.name)) {
@@ -16,8 +16,8 @@ function ensureWorkspaceInventorySections(source) {
     }
     return `${nextSource}\n`;
 }
-function hasExportedInterface(source, interfaceName) {
-    return new RegExp(`export\\s+interface\\s+${escapeRegex(interfaceName)}\\b`, "u").test(source);
+function hasExportedTypeDeclaration(source, interfaceName) {
+    return new RegExp(`export\\s+(?:interface|type)\\s+${escapeRegex(interfaceName)}\\b`, "u").test(source);
 }
 function hasExportedConst(source, constName) {
     return new RegExp(`export\\s+const\\s+${escapeRegex(constName)}\\b`, "u").test(source);
@@ -67,6 +67,36 @@ function ensureInterfaceField(source, interfaceName, fieldName, fieldSource) {
         return `${start}${body}${body.length > 0 && !body.endsWith(lineEnding) ? lineEnding : ""}${formattedFieldSource}${end}`;
     });
 }
+function upsertInterfaceField(source, interfaceName, fieldName, fieldSource) {
+    const interfacePattern = new RegExp(`(export\\s+interface\\s+${escapeRegex(interfaceName)}\\s*\\{\\r?\\n)([\\s\\S]*?)(\\r?\\n\\})`, "u");
+    return source.replace(interfacePattern, (match, start, body, end) => {
+        const lineEnding = start.endsWith("\r\n") ? "\r\n" : "\n";
+        const formattedFieldSource = `${fieldSource
+            .replace(/\r?\n$/u, "")
+            .split("\n")
+            .join(lineEnding)}${lineEnding}`;
+        const existingFieldPattern = new RegExp(`(^[ \\t]*${escapeRegex(fieldName)}\\??:\\s*[^;\\r\\n]+;?\\r?\\n?)`, "mu");
+        const existingFieldMatch = existingFieldPattern.exec(body);
+        if (existingFieldMatch?.[0]) {
+            if (existingFieldMatch[0].trim() === fieldSource.trim()) {
+                return match;
+            }
+            return `${start}${body.slice(0, existingFieldMatch.index)}${formattedFieldSource}${body.slice(existingFieldMatch.index + existingFieldMatch[0].length)}${end}`;
+        }
+        const memberPattern = /^[ \t]*([A-Za-z_$][\w$]*)\??:/gmu;
+        for (const member of body.matchAll(memberPattern)) {
+            const memberIndex = member.index;
+            const memberName = member[1];
+            if (memberIndex === undefined || !memberName) {
+                continue;
+            }
+            if (memberName.localeCompare(fieldName) > 0) {
+                return `${start}${body.slice(0, memberIndex)}${formattedFieldSource}${body.slice(memberIndex)}${end}`;
+            }
+        }
+        return `${start}${body}${body.length > 0 && !body.endsWith(lineEnding) ? lineEnding : ""}${formattedFieldSource}${end}`;
+    });
+}
 function normalizeInterfaceFieldBlock(source, interfaceName, fieldName, fieldSource, requiredFragments) {
     const interfacePattern = new RegExp(`(export\\s+interface\\s+${escapeRegex(interfaceName)}\\s*\\{\\r?\\n)([\\s\\S]*?)(\\r?\\n\\})`, "u");
     return source.replace(interfacePattern, (match, start, body, end) => {
@@ -112,6 +142,26 @@ export function updateWorkspaceInventorySource(source, options = {}) {
     nextSource = normalizeInterfaceFieldBlock(nextSource, "WorkspaceAbilityConfig", "compatibility", WORKSPACE_COMPATIBILITY_CONFIG_FIELD, ["optionalFeatureIds: string[];", "requiredFeatureIds: string[];"]);
     nextSource = ensureInterfaceField(nextSource, "WorkspaceAiFeatureConfig", "compatibility", WORKSPACE_COMPATIBILITY_CONFIG_FIELD);
     nextSource = normalizeInterfaceFieldBlock(nextSource, "WorkspaceAiFeatureConfig", "compatibility", WORKSPACE_COMPATIBILITY_CONFIG_FIELD, ["optionalFeatureIds: string[];", "requiredFeatureIds: string[];"]);
+    for (const [fieldName, fieldSource] of [
+        ["auth", "\tauth?: 'authenticated' | 'public' | 'public-write-protected';"],
+        ["bodyTypeName", "\tbodyTypeName?: string;"],
+        ["controllerClass", "\tcontrollerClass?: string;"],
+        ["controllerExtends", "\tcontrollerExtends?: string;"],
+        ["dataFile", "\tdataFile?: string;"],
+        ["method", "\tmethod?: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';"],
+        ["mode", "\tmode?: 'generated' | 'manual';"],
+        ["pathPattern", "\tpathPattern?: string;"],
+        ["permissionCallback", "\tpermissionCallback?: string;"],
+        ["phpFile", "\tphpFile?: string;"],
+        ["queryTypeName", "\tqueryTypeName?: string;"],
+        ["responseTypeName", "\tresponseTypeName?: string;"],
+        ["routePattern", "\troutePattern?: string;"],
+        ["secretFieldName", "\tsecretFieldName?: string;"],
+        ["secretPreserveOnEmpty", "\tsecretPreserveOnEmpty?: boolean;"],
+        ["secretStateFieldName", "\tsecretStateFieldName?: string;"],
+    ]) {
+        nextSource = upsertInterfaceField(nextSource, "WorkspaceRestResourceConfig", fieldName, fieldSource);
+    }
     return nextSource;
 }
 /**

package/dist/runtime/workspace-inventory-parser-entries.d.ts

@@ -0,0 +1,17 @@
+import ts from "typescript";
+import { type InventorySectionDescriptor } from "./workspace-inventory-parser-validation.js";
+/**
+ * Parse one descriptor-backed inventory section from a TypeScript source file.
+ *
+ * The generic `T` is the typed entry shape returned in `entries`. The
+ * `descriptor` supplies the exported array name, parser field metadata, and
+ * whether the section is required; this helper uses `findExportedArrayLiteral`
+ * and `parseInventoryEntries` to guarantee object-literal entries and literal
+ * field values. It returns parsed entries plus a `found` flag, and throws when
+ * required exports are missing, descriptors cannot resolve an export name, or
+ * exported values are not array literals.
+ */
+export declare function parseInventorySection<T extends object>(sourceFile: ts.SourceFile, descriptor: InventorySectionDescriptor): {
+    entries: T[];
+    found: boolean;
+};

package/dist/runtime/workspace-inventory-parser-entries.js

@@ -0,0 +1,157 @@
+import ts from "typescript";
+import { getPropertyNameText } from "./ts-property-names.js";
+import { assertParsedInventoryEntry, } from "./workspace-inventory-parser-validation.js";
+function findExportedArrayLiteral(sourceFile, exportName) {
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement)) {
+            continue;
+        }
+        if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+            continue;
+        }
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) ||
+                declaration.name.text !== exportName) {
+                continue;
+            }
+            if (declaration.initializer &&
+                ts.isArrayLiteralExpression(declaration.initializer)) {
+                return {
+                    array: declaration.initializer,
+                    found: true,
+                };
+            }
+            return {
+                array: null,
+                found: true,
+            };
+        }
+    }
+    return {
+        array: null,
+        found: false,
+    };
+}
+function getOptionalStringProperty(entryName, elementIndex, objectLiteral, key) {
+    for (const property of objectLiteral.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            continue;
+        }
+        const propertyName = getPropertyNameText(property.name);
+        if (propertyName !== key) {
+            continue;
+        }
+        if (ts.isStringLiteralLike(property.initializer)) {
+            return property.initializer.text;
+        }
+        throw new Error(`${entryName}[${elementIndex}] must use a string literal for "${key}" in scripts/block-config.ts.`);
+    }
+    return undefined;
+}
+function getOptionalStringArrayProperty(entryName, elementIndex, objectLiteral, key) {
+    for (const property of objectLiteral.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            continue;
+        }
+        const propertyName = getPropertyNameText(property.name);
+        if (propertyName !== key) {
+            continue;
+        }
+        if (!ts.isArrayLiteralExpression(property.initializer)) {
+            throw new Error(`${entryName}[${elementIndex}] must use an array literal for "${key}" in scripts/block-config.ts.`);
+        }
+        return property.initializer.elements.map((element, itemIndex) => {
+            if (!ts.isStringLiteralLike(element)) {
+                throw new Error(`${entryName}[${elementIndex}].${key}[${itemIndex}] must use a string literal in scripts/block-config.ts.`);
+            }
+            return element.text;
+        });
+    }
+    return undefined;
+}
+function getOptionalBooleanProperty(entryName, elementIndex, objectLiteral, key) {
+    for (const property of objectLiteral.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            continue;
+        }
+        const propertyName = getPropertyNameText(property.name);
+        if (propertyName !== key) {
+            continue;
+        }
+        if (property.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+            return true;
+        }
+        if (property.initializer.kind === ts.SyntaxKind.FalseKeyword) {
+            return false;
+        }
+        throw new Error(`${entryName}[${elementIndex}] must use a boolean literal for "${key}" in scripts/block-config.ts.`);
+    }
+    return undefined;
+}
+function parseInventoryEntries(arrayLiteral, descriptor) {
+    return arrayLiteral.elements.map((element, elementIndex) => {
+        if (!ts.isObjectLiteralExpression(element)) {
+            throw new Error(`${descriptor.entryName}[${elementIndex}] must be an object literal in scripts/block-config.ts.`);
+        }
+        const entry = {};
+        for (const field of descriptor.fields) {
+            const kind = field.kind ?? "string";
+            const value = kind === "stringArray"
+                ? getOptionalStringArrayProperty(descriptor.entryName, elementIndex, element, field.key)
+                : kind === "boolean"
+                    ? getOptionalBooleanProperty(descriptor.entryName, elementIndex, element, field.key)
+                    : getOptionalStringProperty(descriptor.entryName, elementIndex, element, field.key);
+            field.validate?.(value, {
+                elementIndex,
+                entryName: descriptor.entryName,
+                key: field.key,
+            });
+            entry[field.key] = value;
+        }
+        assertParsedInventoryEntry(entry, descriptor, elementIndex);
+        return entry;
+    });
+}
+/**
+ * Parse one descriptor-backed inventory section from a TypeScript source file.
+ *
+ * The generic `T` is the typed entry shape returned in `entries`. The
+ * `descriptor` supplies the exported array name, parser field metadata, and
+ * whether the section is required; this helper uses `findExportedArrayLiteral`
+ * and `parseInventoryEntries` to guarantee object-literal entries and literal
+ * field values. It returns parsed entries plus a `found` flag, and throws when
+ * required exports are missing, descriptors cannot resolve an export name, or
+ * exported values are not array literals.
+ */
+export function parseInventorySection(sourceFile, descriptor) {
+    if (!descriptor.parse) {
+        return {
+            entries: [],
+            found: false,
+        };
+    }
+    const exportName = descriptor.parse.exportName ?? descriptor.value?.name;
+    if (!exportName) {
+        throw new Error("Inventory parser descriptor is missing an export name.");
+    }
+    const exportedArray = findExportedArrayLiteral(sourceFile, exportName);
+    if (!exportedArray.found) {
+        if (descriptor.parse.required) {
+            throw new Error(`scripts/block-config.ts must export a ${exportName} array.`);
+        }
+        return {
+            entries: [],
+            found: false,
+        };
+    }
+    if (!exportedArray.array) {
+        if (descriptor.parse.required) {
+            throw new Error(`scripts/block-config.ts must export a ${exportName} array.`);
+        }
+        throw new Error(`scripts/block-config.ts must export ${exportName} as an array literal.`);
+    }
+    return {
+        entries: parseInventoryEntries(exportedArray.array, descriptor.parse.entry),
+        found: true,
+    };
+}

package/dist/runtime/workspace-inventory-parser-validation.d.ts

@@ -0,0 +1,104 @@
+import type { WorkspaceInventoryAppendOptionKey, WorkspaceInventoryEntriesKey, WorkspaceInventorySectionFlagKey } from "./workspace-inventory-types.js";
+/**
+ * Literal value shape accepted by descriptor-driven inventory entry fields.
+ */
+export type InventoryEntryFieldValue = string | string[] | boolean | undefined;
+/**
+ * Context passed to custom field validators while parsing one inventory entry.
+ */
+export type InventoryEntryFieldValidationContext = {
+    elementIndex: number;
+    entryName: string;
+    key: string;
+};
+type InventoryEntryFieldDescriptor = {
+    key: string;
+    kind?: "boolean" | "string" | "stringArray";
+    required?: boolean;
+    validate?: (value: InventoryEntryFieldValue, context: InventoryEntryFieldValidationContext) => void;
+};
+/**
+ * Runtime parser contract for one exported inventory array.
+ *
+ * `entryName` is used in diagnostics and `fields` defines the literal values,
+ * required flags, and custom validators accepted for each object entry.
+ */
+export type InventoryEntryParserDescriptor = {
+    entryName: string;
+    fields: readonly InventoryEntryFieldDescriptor[];
+};
+type RequiredInventoryEntryKey<T extends object> = Extract<{
+    [Key in keyof T]-?: undefined extends T[Key] ? never : Key;
+}[keyof T], string>;
+type TypedInventoryEntryFieldDescriptor<T extends object, TKey extends Extract<keyof T, string> = Extract<keyof T, string>> = TKey extends Extract<keyof T, string> ? Omit<InventoryEntryFieldDescriptor, "key" | "required"> & {
+    key: TKey;
+} & (TKey extends RequiredInventoryEntryKey<T> ? {
+    required: true;
+} : {
+    required?: boolean;
+}) : never;
+type RequiredInventoryEntryFieldDescriptor<T extends object> = Omit<InventoryEntryFieldDescriptor, "key" | "required"> & {
+    key: RequiredInventoryEntryKey<T>;
+    required: true;
+};
+type MissingRequiredInventoryEntryKeys<T extends object, TFields extends readonly TypedInventoryEntryFieldDescriptor<T>[]> = Exclude<RequiredInventoryEntryKey<T>, TFields[number]["key"]>;
+type RequiredInventoryEntryFieldsPresent<T extends object, TFields extends readonly TypedInventoryEntryFieldDescriptor<T>[]> = MissingRequiredInventoryEntryKeys<T, TFields> extends never ? unknown : {
+    missingRequiredInventoryEntryFields: MissingRequiredInventoryEntryKeys<T, TFields>;
+};
+type RequiredInventoryEntryFieldsMarkedRequired<T extends object, TFields extends readonly TypedInventoryEntryFieldDescriptor<T>[]> = Extract<TFields[number], {
+    key: RequiredInventoryEntryKey<T>;
+}> extends RequiredInventoryEntryFieldDescriptor<T> ? unknown : {
+    requiredInventoryEntryFieldsMustSetRequiredTrue: RequiredInventoryEntryKey<T>;
+};
+/**
+ * Shared descriptor contract for generated workspace inventory sections.
+ *
+ * Callers rely on `append` markers when inserting generated entries, `parse`
+ * metadata when reading exported arrays, and `interface`/`value` sections when
+ * repairing older `scripts/block-config.ts` files.
+ */
+export type InventorySectionDescriptor = {
+    /** Optional marker metadata used when appending generated entries. */
+    append?: {
+        marker: string;
+        optionKey: WorkspaceInventoryAppendOptionKey;
+    };
+    /** Optional exported interface that backs the inventory section entries. */
+    interface?: {
+        name: string;
+        section: string;
+    };
+    /** Optional parser metadata for descriptor-driven inventory reads. */
+    parse?: {
+        entriesKey: WorkspaceInventoryEntriesKey;
+        entry: InventoryEntryParserDescriptor;
+        exportName?: string;
+        hasSectionKey?: WorkspaceInventorySectionFlagKey;
+        required?: boolean;
+    };
+    /** Optional exported const array that stores the inventory section entries. */
+    value?: {
+        name: string;
+        section: string;
+    };
+};
+/**
+ * Define a typed inventory entry parser while enforcing required fields at
+ * compile time.
+ *
+ * The returned descriptor is consumed by `parseInventorySection` to extract
+ * literal field values and run runtime validators.
+ */
+export declare function defineInventoryEntryParser<T extends object>(): <const TFields extends readonly TypedInventoryEntryFieldDescriptor<T>[]>(descriptor: {
+    entryName: string;
+    fields: TFields;
+} & RequiredInventoryEntryFieldsPresent<T, TFields> & RequiredInventoryEntryFieldsMarkedRequired<T, TFields>) => InventoryEntryParserDescriptor;
+/**
+ * Assert that a parsed inventory entry contains every required descriptor
+ * field.
+ *
+ * Missing `undefined` values and empty strings throw with diagnostics tied to
+ * the original exported inventory array name and element index.
+ */
+export declare function assertParsedInventoryEntry<T extends object>(entry: Record<string, InventoryEntryFieldValue>, descriptor: InventoryEntryParserDescriptor, elementIndex: number): asserts entry is Record<string, InventoryEntryFieldValue> & T;
+export {};

package/dist/runtime/workspace-inventory-parser-validation.js

@@ -0,0 +1,34 @@
+/**
+ * Define a typed inventory entry parser while enforcing required fields at
+ * compile time.
+ *
+ * The returned descriptor is consumed by `parseInventorySection` to extract
+ * literal field values and run runtime validators.
+ */
+export function defineInventoryEntryParser() {
+    return (descriptor) => descriptor;
+}
+function isMissingRequiredInventoryValue(value) {
+    return (value === undefined || (typeof value === "string" && value.length === 0));
+}
+function formatMissingRequiredInventoryFields(keys) {
+    return keys.length === 1
+        ? `required "${keys[0]}"`
+        : `required fields ${keys.map((key) => `"${key}"`).join(", ")}`;
+}
+/**
+ * Assert that a parsed inventory entry contains every required descriptor
+ * field.
+ *
+ * Missing `undefined` values and empty strings throw with diagnostics tied to
+ * the original exported inventory array name and element index.
+ */
+export function assertParsedInventoryEntry(entry, descriptor, elementIndex) {
+    const missingRequiredKeys = descriptor.fields
+        .filter((field) => field.required === true &&
+        isMissingRequiredInventoryValue(entry[field.key]))
+        .map((field) => field.key);
+    if (missingRequiredKeys.length > 0) {
+        throw new Error(`${descriptor.entryName}[${elementIndex}] is missing ${formatMissingRequiredInventoryFields(missingRequiredKeys)} in scripts/block-config.ts.`);
+    }
+}

package/dist/runtime/workspace-inventory-parser.d.ts

@@ -1,46 +1,6 @@
-import type { WorkspaceInventory, WorkspaceInventoryAppendOptionKey, WorkspaceInventoryEntriesKey, WorkspaceInventorySectionFlagKey } from "./workspace-inventory-types.js";
-type InventoryEntryFieldValidationContext = {
-    elementIndex: number;
-    entryName: string;
-    key: string;
-};
-type InventoryEntryFieldDescriptor = {
-    key: string;
-    kind?: "string" | "stringArray";
-    required?: boolean;
-    validate?: (value: string | string[] | undefined, context: InventoryEntryFieldValidationContext) => void;
-};
-type InventoryEntryParserDescriptor = {
-    entryName: string;
-    fields: readonly InventoryEntryFieldDescriptor[];
-};
-export type InventorySectionDescriptor = {
-    /** Optional marker metadata used when appending generated entries. */
-    append?: {
-        marker: string;
-        optionKey: WorkspaceInventoryAppendOptionKey;
-    };
-    /** Optional exported interface that backs the inventory section entries. */
-    interface?: {
-        name: string;
-        section: string;
-    };
-    /** Optional parser metadata for descriptor-driven inventory reads. */
-    parse?: {
-        entriesKey: WorkspaceInventoryEntriesKey;
-        entry: InventoryEntryParserDescriptor;
-        exportName?: string;
-        hasSectionKey?: WorkspaceInventorySectionFlagKey;
-        required?: boolean;
-    };
-    /** Optional exported const array that stores the inventory section entries. */
-    value?: {
-        name: string;
-        section: string;
-    };
-};
-export declare const BLOCK_INVENTORY_SECTION: InventorySectionDescriptor;
-export declare const INVENTORY_SECTIONS: readonly InventorySectionDescriptor[];
+import type { WorkspaceInventory } from "./workspace-inventory-types.js";
+export { BLOCK_INVENTORY_SECTION, INVENTORY_SECTIONS, } from "./workspace-inventory-section-descriptors.js";
+export type { InventorySectionDescriptor } from "./workspace-inventory-parser-validation.js";
 /**
  * Parse workspace inventory entries from the source of `scripts/block-config.ts`.
  *
@@ -49,4 +9,3 @@ export declare const INVENTORY_SECTIONS: readonly InventorySectionDescriptor[];
  * @throws {Error} When `BLOCKS` is missing or any inventory entry is malformed.
  */
 export declare function parseWorkspaceInventorySource(source: string): Omit<WorkspaceInventory, "blockConfigPath">;
-export {};