@wp-typia/project-tools 0.22.9 → 0.23.0

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

@@ -2,24 +2,13 @@ import { createHash, randomUUID } from 'node:crypto';
 import { promises as fsp } from 'node:fs';
 import path from 'node:path';
 import { getNodeErrorCode, pathExists } from './fs-async.js';
+import { CACHE_MARKER_FILE, CACHE_PRUNE_MARKER_FILE, externalTemplateCacheMetadataMatches, formatExternalTemplateCacheEntryMarker, formatExternalTemplateCachePruneMarker, isExternalTemplateCacheEntryFreshForTtl, parseExternalTemplateCacheEntryMarker, parseExternalTemplateCachePruneMarker, } from './template-source-cache-markers.js';
 import { getExternalTemplateCacheNowMs, getExternalTemplateCacheRoot, isExternalTemplateCacheEnabled, resolveExternalTemplateCachePruneIntervalMs, resolveExternalTemplateCacheTtlMs, } from './template-source-cache-policy.js';
 export { EXTERNAL_TEMPLATE_CACHE_DIR_ENV, EXTERNAL_TEMPLATE_CACHE_ENV, EXTERNAL_TEMPLATE_CACHE_PRUNE_INTERVAL_MS_ENV, EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, getExternalTemplateCacheRoot, isExternalTemplateCacheEnabled, } from './template-source-cache-policy.js';
-/**
- * Marker file written after a cache entry is fully populated.
- */
-const CACHE_MARKER_FILE = 'wp-typia-template-cache.json';
-/**
- * Marker file written after a full TTL prune scan completes.
- */
-const CACHE_PRUNE_MARKER_FILE = 'wp-typia-template-cache-prune.json';
 /**
  * Private directory mode used for cache roots and entries on POSIX platforms.
  */
 const PRIVATE_CACHE_DIRECTORY_MODE = 0o700;
-/**
- * Marker value used when URL-like metadata cannot be safely normalized.
- */
-const REDACTED_CACHE_METADATA_VALUE = '[redacted]';
 /**
  * Filesystem errors that mean another writer published the same cache entry.
  */
@@ -34,10 +23,6 @@ const CACHE_UNAVAILABLE_ERROR_CODES = new Set([
     'EPERM',
     'EROFS',
 ]);
-/**
- * Metadata fields that may contain credentialed or signed URLs.
- */
-const URL_LIKE_METADATA_KEY = /(url|uri|registry|tarball)/iu;
 /**
  * Cache namespaces must stay within one path segment under the cache root.
  */
@@ -126,28 +111,6 @@ async function ensurePrivateCacheDirectory(directory) {
         return false;
     }
 }
-function sanitizeCacheMetadataValue(key, value) {
-    if (!URL_LIKE_METADATA_KEY.test(key)) {
-        return value;
-    }
-    try {
-        const url = new URL(value);
-        url.username = '';
-        url.password = '';
-        url.search = '';
-        url.hash = '';
-        return url.toString();
-    }
-    catch {
-        return REDACTED_CACHE_METADATA_VALUE;
-    }
-}
-function sanitizeCacheMetadata(metadata) {
-    return Object.fromEntries(Object.entries(metadata).map(([key, value]) => [
-        key,
-        value === null ? null : sanitizeCacheMetadataValue(key, value),
-    ]));
-}
 function resolveCacheNamespaceDir(cacheRoot, namespace) {
     if (namespace === '.' ||
         namespace === '..' ||
@@ -185,51 +148,14 @@ async function isReusableCacheEntry(entryDir, markerPath, sourceDir) {
         (await pathExists(markerPath)) &&
         (await isDirectoryPath(sourceDir)));
 }
-function parseCacheMarkerMetadata(markerText) {
-    let marker;
-    try {
-        marker = JSON.parse(markerText);
-    }
-    catch {
-        return null;
-    }
-    if (typeof marker !== 'object' || marker === null || Array.isArray(marker)) {
-        return null;
-    }
-    const rawMetadata = marker.metadata;
-    if (typeof rawMetadata !== 'object' ||
-        rawMetadata === null ||
-        Array.isArray(rawMetadata)) {
-        return null;
-    }
-    const metadata = {};
-    for (const [key, value] of Object.entries(rawMetadata)) {
-        if (typeof value !== 'string' && value !== null) {
-            return null;
-        }
-        metadata[key] = value;
-    }
-    const rawCreatedAt = marker.createdAt;
-    const createdAtMs = typeof rawCreatedAt === 'string' ? Date.parse(rawCreatedAt) : 0;
-    return {
-        createdAtMs: Number.isFinite(createdAtMs) ? createdAtMs : 0,
-        metadata,
-    };
-}
 async function readCacheEntryMarker(markerPath) {
     try {
-        return parseCacheMarkerMetadata(await fsp.readFile(markerPath, 'utf8'));
+        return parseExternalTemplateCacheEntryMarker(await fsp.readFile(markerPath, 'utf8'));
     }
     catch {
         return null;
     }
 }
-function cacheMetadataMatches(actual, expected) {
-    return Object.entries(expected).every(([key, value]) => actual[key] === value);
-}
-function isCacheEntryFreshForTtl(createdAtMs, nowMs, ttlMs) {
-    return ttlMs === null || createdAtMs >= nowMs - ttlMs;
-}
 async function getReusableCacheEntryMarker(entryDir, markerPath, sourceDir) {
     if (!(await isReusableCacheEntry(entryDir, markerPath, sourceDir))) {
         return null;
@@ -238,7 +164,8 @@ async function getReusableCacheEntryMarker(entryDir, markerPath, sourceDir) {
 }
 async function isReusableFreshCacheEntry(entryDir, markerPath, sourceDir, nowMs, ttlMs) {
     const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
-    return (marker !== null && isCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs));
+    return (marker !== null &&
+        isExternalTemplateCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs));
 }
 function isPathInsideDirectory(directory, candidatePath) {
     const relativePath = path.relative(directory, candidatePath);
@@ -261,39 +188,6 @@ async function removeCacheEntryWithinRoot(cacheRoot, entryDir) {
 function getCachePruneMarkerPath(cacheRoot) {
     return path.join(cacheRoot, CACHE_PRUNE_MARKER_FILE);
 }
-function parseCachePruneMarker(markerText) {
-    let marker;
-    try {
-        marker = JSON.parse(markerText);
-    }
-    catch {
-        return null;
-    }
-    if (typeof marker !== 'object' || marker === null || Array.isArray(marker)) {
-        return null;
-    }
-    const rawPrunedAt = marker.prunedAt;
-    const prunedAtMs = typeof rawPrunedAt === 'string' ? Date.parse(rawPrunedAt) : Number.NaN;
-    const rawPruneIntervalMs = marker
-        .pruneIntervalMs;
-    const rawTtlMs = marker.ttlMs;
-    if (typeof rawTtlMs !== 'number' || !Number.isFinite(rawTtlMs)) {
-        return null;
-    }
-    if (!Number.isFinite(prunedAtMs)) {
-        return null;
-    }
-    if (rawPruneIntervalMs !== null &&
-        (typeof rawPruneIntervalMs !== 'number' ||
-            !Number.isFinite(rawPruneIntervalMs))) {
-        return null;
-    }
-    return {
-        prunedAtMs,
-        pruneIntervalMs: rawPruneIntervalMs ?? null,
-        ttlMs: rawTtlMs,
-    };
-}
 async function shouldSkipExternalTemplateCachePrune({ cacheRoot, force, nowMs, pruneIntervalMs, ttlMs, }) {
     if (force || pruneIntervalMs === null) {
         return false;
@@ -305,7 +199,7 @@ async function shouldSkipExternalTemplateCachePrune({ cacheRoot, force, nowMs, p
     catch {
         return false;
     }
-    const marker = parseCachePruneMarker(markerText);
+    const marker = parseExternalTemplateCachePruneMarker(markerText);
     if (!marker ||
         marker.ttlMs !== ttlMs ||
         marker.pruneIntervalMs !== pruneIntervalMs) {
@@ -316,11 +210,11 @@ async function shouldSkipExternalTemplateCachePrune({ cacheRoot, force, nowMs, p
 }
 async function writeExternalTemplateCachePruneMarker({ cacheRoot, nowMs, pruneIntervalMs, ttlMs, }) {
     try {
-        await fsp.writeFile(getCachePruneMarkerPath(cacheRoot), `${JSON.stringify({
-            prunedAt: new Date(nowMs).toISOString(),
+        await fsp.writeFile(getCachePruneMarkerPath(cacheRoot), formatExternalTemplateCachePruneMarker({
+            nowMs,
             pruneIntervalMs,
             ttlMs,
-        }, null, 2)}\n`, 'utf8');
+        }), 'utf8');
     }
     catch {
         // Prune markers are an optimization; failing to write one keeps TTL safe.
@@ -476,8 +370,8 @@ export async function findReusableExternalTemplateSourceCache(descriptor) {
         const sourceDir = path.join(entryDir, 'source');
         const marker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
         if (!marker ||
-            !isCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs) ||
-            !cacheMetadataMatches(marker.metadata, descriptor.metadata)) {
+            !isExternalTemplateCacheEntryFreshForTtl(marker.createdAtMs, nowMs, ttlMs) ||
+            !externalTemplateCacheMetadataMatches(marker.metadata, descriptor.metadata)) {
             continue;
         }
         if (!bestEntry || marker.createdAtMs > bestEntry.createdAtMs) {
@@ -523,7 +417,7 @@ export async function resolveExternalTemplateSourceCache(descriptor, populateSou
     await pruneExternalTemplateCache();
     const existingMarker = await getReusableCacheEntryMarker(entryDir, markerPath, sourceDir);
     if (existingMarker &&
-        isCacheEntryFreshForTtl(existingMarker.createdAtMs, nowMs, ttlMs)) {
+        isExternalTemplateCacheEntryFreshForTtl(existingMarker.createdAtMs, nowMs, ttlMs)) {
         return {
             cacheHit: true,
             sourceDir,
@@ -550,12 +444,12 @@ export async function resolveExternalTemplateSourceCache(descriptor, populateSou
             populateFailed = true;
             throw error;
         }
-        await fsp.writeFile(path.join(temporaryEntryDir, CACHE_MARKER_FILE), `${JSON.stringify({
-            createdAt: new Date().toISOString(),
-            key: cacheKey,
-            metadata: sanitizeCacheMetadata(descriptor.metadata),
+        await fsp.writeFile(path.join(temporaryEntryDir, CACHE_MARKER_FILE), formatExternalTemplateCacheEntryMarker({
+            cacheKey,
+            createdAt: new Date(),
+            metadata: descriptor.metadata,
             namespace: descriptor.namespace,
-        }, null, 2)}\n`, 'utf8');
+        }), 'utf8');
         await fsp.rename(temporaryEntryDir, entryDir);
         return {
             cacheHit: false,

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

@@ -7,8 +7,10 @@ export declare const EXTERNAL_TEMPLATE_TRUST_WARNING = "External template config
 /**
  * Search a source directory for the first supported external template entry.
  *
- * @deprecated Use `findExternalTemplateEntry()` from async template-source
- * paths. This synchronous helper remains only for compatibility callers.
+ * @deprecated Since 0.22.10. Use `findExternalTemplateEntry()` 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 Directory that may contain an external template config entry.
  * @returns The first matching entry path, or null when no supported entry exists.

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

@@ -33,8 +33,10 @@ function resolveSourceSubpath(sourceDir, relativePath) {
 /**
  * Search a source directory for the first supported external template entry.
  *
- * @deprecated Use `findExternalTemplateEntry()` from async template-source
- * paths. This synchronous helper remains only for compatibility callers.
+ * @deprecated Since 0.22.10. Use `findExternalTemplateEntry()` 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 Directory that may contain an external template config entry.
  * @returns The first matching entry path, or null when no supported entry exists.

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

@@ -59,8 +59,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.
@@ -143,8 +145,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);

package/dist/runtime/typia-llm.js

@@ -1,5 +1,6 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { getOptionalNodeErrorCode, isFileNotFoundError, } from './fs-async.js';
 import { cloneJsonValue } from './json-utils.js';
 import { normalizeEndpointAuthDefinition, } from './schema-core.js';
 const TYPESCRIPT_RESERVED_WORDS = new Set([
@@ -433,13 +434,11 @@ async function reconcileGeneratedTypiaLlmArtifacts(artifacts, check) {
             }
         }
         catch (error) {
-            const code = error && typeof error === 'object' && 'code' in error
-                ? error.code
-                : undefined;
-            if (code === 'ENOENT') {
+            if (isFileNotFoundError(error)) {
                 issues.push(`- ${artifact.filePath} (missing)`);
                 continue;
             }
+            const code = getOptionalNodeErrorCode(error);
             issues.push(`- ${artifact.filePath} (unreadable: ${error instanceof Error ? error.message : code ?? 'unknown'})`);
         }
     }

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

@@ -0,0 +1,24 @@
+import type { WorkspaceInventoryUpdateOptions } from "./workspace-inventory-types.js";
+/**
+ * Update `scripts/block-config.ts` source text with additional inventory entries.
+ *
+ * Missing inventory sections for variations, patterns, binding sources, REST
+ * resources, workflow abilities, AI features, editor plugins, block styles, and
+ * block transforms are created
+ * automatically before new entries are appended at their marker comments.
+ * When provided, `transformSource` runs before any entries are inserted.
+ *
+ * @param source Existing `scripts/block-config.ts` source.
+ * @param options Entry lists plus an optional source transformer.
+ * @returns Updated source text with all requested inventory entries appended.
+ */
+export declare function updateWorkspaceInventorySource(source: string, options?: WorkspaceInventoryUpdateOptions): string;
+/**
+ * Append new entries to the canonical workspace inventory file on disk.
+ *
+ * @param projectDir Workspace root directory.
+ * @param options Entry lists and optional source transform passed through to
+ * `updateWorkspaceInventorySource`.
+ * @returns Resolves once `scripts/block-config.ts` has been updated if needed.
+ */
+export declare function appendWorkspaceInventoryEntries(projectDir: string, options: Parameters<typeof updateWorkspaceInventorySource>[1]): Promise<void>;

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

@@ -0,0 +1,181 @@
+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 { 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 &&
+            !hasExportedTypeDeclaration(nextSource, section.interface.name)) {
+            nextSource += section.interface.section;
+        }
+        if (section.value && !hasExportedConst(nextSource, section.value.name)) {
+            nextSource += section.value.section;
+        }
+    }
+    return `${nextSource}\n`;
+}
+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);
+}
+function appendEntriesAtMarker(source, marker, entries) {
+    if (entries.length === 0) {
+        return source;
+    }
+    if (!source.includes(marker)) {
+        throw new Error(`Workspace inventory marker "${marker}" is missing in scripts/block-config.ts.`);
+    }
+    const replacement = `${entries.join("\n")}\n${marker}`;
+    return source.replace(marker, () => replacement);
+}
+function appendInventorySectionEntries(source, options) {
+    let nextSource = source;
+    for (const section of [BLOCK_INVENTORY_SECTION, ...INVENTORY_SECTIONS]) {
+        if (!section.append) {
+            continue;
+        }
+        nextSource = appendEntriesAtMarker(nextSource, section.append.marker, options[section.append.optionKey] ?? []);
+    }
+    return nextSource;
+}
+function ensureInterfaceField(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) => {
+        if (new RegExp(`^[ \t]*${escapeRegex(fieldName)}\\??:`, "mu").test(body)) {
+            return match;
+        }
+        const lineEnding = start.endsWith("\r\n") ? "\r\n" : "\n";
+        const formattedFieldSource = `${fieldSource
+            .replace(/\r?\n$/u, "")
+            .split("\n")
+            .join(lineEnding)}${lineEnding}`;
+        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 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) => {
+        const fieldPattern = new RegExp(`(^([ \\t]*)${escapeRegex(fieldName)}\\??:\\s*\\{[ \\t]*\\r?\\n)([\\s\\S]*?)(^\\2\\};\\r?\\n?)`, "mu");
+        const fieldMatch = fieldPattern.exec(body);
+        if (!fieldMatch) {
+            return match;
+        }
+        const existingFieldSource = fieldMatch[0];
+        if (requiredFragments.every((fragment) => existingFieldSource.includes(fragment))) {
+            return match;
+        }
+        const lineEnding = start.endsWith("\r\n") ? "\r\n" : "\n";
+        const formattedFieldSource = `${fieldSource
+            .replace(/\r?\n$/u, "")
+            .split("\n")
+            .join(lineEnding)}${lineEnding}`;
+        return `${start}${body.slice(0, fieldMatch.index)}${formattedFieldSource}${body.slice(fieldMatch.index + existingFieldSource.length)}${end}`;
+    });
+}
+/**
+ * Update `scripts/block-config.ts` source text with additional inventory entries.
+ *
+ * Missing inventory sections for variations, patterns, binding sources, REST
+ * resources, workflow abilities, AI features, editor plugins, block styles, and
+ * block transforms are created
+ * automatically before new entries are appended at their marker comments.
+ * When provided, `transformSource` runs before any entries are inserted.
+ *
+ * @param source Existing `scripts/block-config.ts` source.
+ * @param options Entry lists plus an optional source transformer.
+ * @returns Updated source text with all requested inventory entries appended.
+ */
+export function updateWorkspaceInventorySource(source, options = {}) {
+    let nextSource = ensureWorkspaceInventorySections(source);
+    if (options.transformSource) {
+        nextSource = options.transformSource(nextSource);
+    }
+    nextSource = appendInventorySectionEntries(nextSource, options);
+    nextSource = ensureInterfaceField(nextSource, "WorkspaceBindingSourceConfig", "attribute", "\tattribute?: string;");
+    nextSource = ensureInterfaceField(nextSource, "WorkspaceBindingSourceConfig", "block", "\tblock?: string;");
+    nextSource = ensureInterfaceField(nextSource, "WorkspaceAbilityConfig", "compatibility", WORKSPACE_COMPATIBILITY_CONFIG_FIELD);
+    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;"],
+        ["secretStateFieldName", "\tsecretStateFieldName?: string;"],
+    ]) {
+        nextSource = upsertInterfaceField(nextSource, "WorkspaceRestResourceConfig", fieldName, fieldSource);
+    }
+    return nextSource;
+}
+/**
+ * Append new entries to the canonical workspace inventory file on disk.
+ *
+ * @param projectDir Workspace root directory.
+ * @param options Entry lists and optional source transform passed through to
+ * `updateWorkspaceInventorySource`.
+ * @returns Resolves once `scripts/block-config.ts` has been updated if needed.
+ */
+export async function appendWorkspaceInventoryEntries(projectDir, options) {
+    const blockConfigPath = path.join(projectDir, "scripts", "block-config.ts");
+    const source = await readFile(blockConfigPath, "utf8");
+    const nextSource = updateWorkspaceInventorySource(source, options);
+    if (nextSource !== source) {
+        await writeFile(blockConfigPath, nextSource, "utf8");
+    }
+}

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

@@ -0,0 +1,53 @@
+import type { WorkspaceInventory, WorkspaceInventoryAppendOptionKey, WorkspaceInventoryEntriesKey, WorkspaceInventorySectionFlagKey } from "./workspace-inventory-types.js";
+type InventoryEntryFieldValue = string | string[] | boolean | undefined;
+type InventoryEntryFieldValidationContext = {
+    elementIndex: number;
+    entryName: string;
+    key: string;
+};
+type InventoryEntryFieldDescriptor = {
+    key: string;
+    kind?: "boolean" | "string" | "stringArray";
+    required?: boolean;
+    validate?: (value: InventoryEntryFieldValue, 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[];
+/**
+ * Parse workspace inventory entries from the source of `scripts/block-config.ts`.
+ *
+ * @param source Raw TypeScript source from `scripts/block-config.ts`.
+ * @returns Parsed inventory sections without the resolved `blockConfigPath`.
+ * @throws {Error} When `BLOCKS` is missing or any inventory entry is malformed.
+ */
+export declare function parseWorkspaceInventorySource(source: string): Omit<WorkspaceInventory, "blockConfigPath">;
+export {};