@vertesia/build-tools 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260804.124748Z

package/lib/vite/dev-server.js

@@ -31,13 +31,42 @@
  */
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { loadSkillCatalog, readPackageJson, resolveSkillCatalogPath } from '../core/skill-markdown/load-catalog.js';
+import { createSkillTransformer, isSkillTransformer } from '../core/transformers/skill.js';
 import { BUILTIN_TRANSFORMER_NAMES, resolveTransformerNames } from '../import-transform/builtins.js';
 export function vertesiaDevServerPlugin(options = {}) {
     const names = options.transformers ?? BUILTIN_TRANSFORMER_NAMES;
     const transformers = resolveTransformerNames([...names]);
+    // Resolved once, lazily: the catalog module is compiled output, so it may not exist when the
+    // config is first evaluated.
+    let root = process.cwd();
+    let boundPromise;
+    /** The catalog-bound skill transformer, or null when this package configures no catalog. */
+    const boundSkillTransformer = () => {
+        if (!boundPromise) {
+            boundPromise = (async () => {
+                if (options.skillCatalog === false)
+                    return null;
+                const markdown = typeof options.skillCatalog === 'object'
+                    ? options.skillCatalog
+                    : await (async () => {
+                        const modulePath = typeof options.skillCatalog === 'string'
+                            ? path.resolve(root, options.skillCatalog)
+                            : resolveSkillCatalogPath(readPackageJson(root) ?? {}, root);
+                        return modulePath ? await loadSkillCatalog(modulePath) : null;
+                    })();
+                return markdown ? createSkillTransformer({ markdown }) : null;
+            })();
+        }
+        return boundPromise;
+    };
     return {
         name: 'vertesia-dev-server',
         enforce: 'pre',
+        configResolved(config) {
+            if (config.root)
+                root = config.root;
+        },
         /**
          * Map relative query-style imports to absolute paths so Vite's loader
          * sees a stable id keyed by the original file location. The query
@@ -72,12 +101,15 @@ export function vertesiaDevServerPlugin(options = {}) {
             const matched = findMatchingTransformer(id, transformers);
             if (!matched)
                 return null;
+            // Bind the skill transformer to the catalog on first use. Matched by identity rather
+            // than by pattern so a consumer's own transformer for the same files is left alone.
+            const active = isSkillTransformer(matched) ? ((await boundSkillTransformer()) ?? matched) : matched;
             const cleanId = stripQuery(id);
             try {
-                const content = matched.virtual ? '' : readFileSync(cleanId, 'utf-8');
-                const result = await matched.transform(content, cleanId);
-                if (matched.schema) {
-                    const validation = matched.schema.safeParse(result.data);
+                const content = active.virtual ? '' : readFileSync(cleanId, 'utf-8');
+                const result = await active.transform(content, cleanId);
+                if (active.schema) {
+                    const validation = active.schema.safeParse(result.data);
                     if (!validation.success) {
                         const errors = validation.error.issues
                             .map((err) => `  - ${err.path.join('.')}: ${err.message}`)

package/lib/vite/dev-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"dev-server.js","sourceRoot":"","sources":["../../src/vite/dev-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dev-server.js","sourceRoot":"","sources":["../../src/vite/dev-server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/build-tools",
-  "version": "1.5.0-dev.20260725.083715Z",
+  "version": "1.5.0-dev.20260804.124748Z",
   "description": "Build tools for Vertesia projects - import transformers (skill / template / prompt / raw), esbuild widget bundler, vertesia-build CLI, and a Vite dev plugin",
   "type": "module",
   "main": "./lib/index.js",
@@ -24,7 +24,7 @@
     }
   },
   "devDependencies": {
-    "@hono/node-server": "^2.0.10",
+    "@hono/node-server": "^2.0.11",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.13.3",
     "typescript": "^6.0.3",
@@ -33,20 +33,17 @@
     "@vertesia/tsconfig": "0.1.0"
   },
   "dependencies": {
-    "@rollup/plugin-commonjs": "^28.0.3",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^12.1.2",
+    "ajv": "^8.20.0",
+    "es-module-lexer": "^1.7.0",
     "esbuild": "^0.28.1",
     "js-yaml": "^5.2.1",
     "zod": "^4.4.3",
-    "@vertesia/studio-utils": "1.5.0-dev.20260725.083715Z",
-    "@vertesia/common": "1.5.0-dev.20260725.083715Z",
-    "@llumiverse/common": "1.5.0-dev.20260725.065646Z"
+    "@llumiverse/common": "1.5.0-dev.20260804.122431Z",
+    "@vertesia/common": "1.5.0-dev.20260804.124748Z",
+    "@vertesia/studio-utils": "1.5.0-dev.20260804.124748Z"
   },
   "peerDependencies": {
-    "@hono/node-server": "^2.0.10",
+    "@hono/node-server": "^2.0.11",
     "vite": "^8.1.4"
   },
   "peerDependenciesMeta": {
@@ -78,7 +75,7 @@
     "zod",
     "validation"
   ],
-  "gitHead": "57bcc2f27dd17b3387f27c18e89329c4c37f98ac",
+  "gitHead": "87ac9166db2b38bd1be6e37adf0414ea83e402ee",
   "scripts": {
     "lint": "biome lint src",
     "test": "vitest run",

package/src/bin/build.ts

@@ -35,8 +35,11 @@
 
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { loadSkillCatalog } from '../core/skill-markdown/load-catalog.js';
+import { createSkillTransformer, isSkillTransformer } from '../core/transformers/skill.js';
+import type { TransformerRule } from '../core/types.js';
 import { transformImports } from '../import-transform/index.js';
-import { resolveConfig, VertesiaBuildConfigError } from './config.js';
+import { resolveConfig, resolveSkillCatalogPath, VertesiaBuildConfigError } from './config.js';
 
 function fail(message: string): never {
     console.error(`vertesia-build: ${message}`);
@@ -61,15 +64,41 @@ function readPackageJson(cwd: string): Record<string, unknown> {
 async function main(): Promise<void> {
     const cwd = process.cwd();
     const pkg = readPackageJson(cwd);
-    let options;
+    let options: ReturnType<typeof resolveConfig>;
+    let catalogPath: string | undefined;
     try {
         options = resolveConfig(pkg, cwd);
+        catalogPath = resolveSkillCatalogPath(pkg, cwd);
     } catch (error) {
         if (error instanceof VertesiaBuildConfigError) {
             fail(error.message);
         }
         throw error;
     }
+
+    if (catalogPath) {
+        let markdown: Awaited<ReturnType<typeof loadSkillCatalog>>;
+        try {
+            markdown = await loadSkillCatalog(catalogPath);
+        } catch (error) {
+            fail((error as Error).message);
+        }
+        const bound = createSkillTransformer({ markdown });
+        // Swap by identity, not by pattern: a consumer's own transformer registered for the same
+        // files must not be silently replaced by ours.
+        const replaced = options.transformers.filter(isSkillTransformer).length;
+        if (replaced === 0) {
+            fail('skillCatalog is configured but "skill" is not in vertesia-build.transformers.');
+        }
+        options = {
+            ...options,
+            transformers: options.transformers.map((rule: TransformerRule) =>
+                isSkillTransformer(rule) ? bound : rule,
+            ),
+        };
+        console.log(`vertesia-build: skill catalog loaded (${markdown.tools.size} tools, ${markdown.skills.size} skills)`);
+    }
+
     const result = await transformImports(options);
     console.log(
         `vertesia-build: files=${result.filesProcessed} chunks=${result.chunksEmitted} ` +

package/src/bin/config.ts

@@ -27,6 +27,33 @@ interface RawConfig {
     assetsDir?: unknown;
     widgetsDir?: unknown;
     widgetConfig?: unknown;
+    skillCatalog?: unknown;
+}
+
+/**
+ * Absolute path of the module the CLI imports to obtain the skill catalog, if configured.
+ *
+ * A path rather than an inline object because the catalog is derived from compiled code — this
+ * package's own tool registry, or a dependency's catalog artifact. Naming the module in
+ * package.json keeps the dependency explicit and reviewable instead of having build-tools go
+ * looking for a registry it should not know about.
+ *
+ * Kept separate from `resolveConfig` because loading it is asynchronous I/O, and `resolveConfig`
+ * is deliberately pure.
+ */
+export function resolveSkillCatalogPath(pkg: Record<string, unknown>, cwd: string): string | undefined {
+    const raw = pkg[CONFIG_KEY];
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return undefined;
+    }
+    const value = (raw as RawConfig).skillCatalog;
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new VertesiaBuildConfigError(`"${CONFIG_KEY}.skillCatalog" must be a non-empty path when set.`);
+    }
+    return path.resolve(cwd, value);
 }
 
 /**

package/src/core/skill-markdown/load-catalog.ts

@@ -0,0 +1,100 @@
+/**
+ * Loading the skill catalog named by `vertesia-build.skillCatalog`.
+ *
+ * Shared by the `vertesia-build` CLI and the Vite dev-server plugin so both resolve
+ * `{@tool …}` / `{@skill …}` against the same registry. Without this the two paths disagree:
+ * a build would validate a skill body that `vite dev` and `vitest` then refuse to transform.
+ *
+ * The catalog is named as a *module path* rather than inlined, because it is derived from compiled
+ * code — a package's own tool registry, or a dependency's catalog artifact. Naming it in
+ * package.json keeps that dependency explicit instead of having build-tools go looking for a
+ * registry it should not know about.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { PreprocessSkillMarkdownOptions } from './preprocess.js';
+
+export const CONFIG_KEY = 'vertesia-build';
+
+/**
+ * Shape a `skillCatalog` module may export.
+ *
+ * The name collections are `Iterable<string>` rather than `ReadonlySet`, so a catalog can export
+ * plain arrays — which is what a JSON-derived one naturally produces. They are normalised to sets
+ * here, which is why this cannot simply extend `PreprocessSkillMarkdownOptions`.
+ */
+interface RawCatalog extends Omit<Partial<PreprocessSkillMarkdownOptions>, keyof RawCatalogNames> {
+    tools?: Iterable<string>;
+    skills?: Iterable<string>;
+    ambiguousTools?: Iterable<string>;
+    ambiguousSkills?: Iterable<string>;
+    unvalidatableTools?: Iterable<string>;
+    exampleLanguages?: Iterable<string>;
+}
+
+/** The option keys `RawCatalog` widens to `Iterable`. */
+interface RawCatalogNames {
+    tools: unknown;
+    skills: unknown;
+    ambiguousTools: unknown;
+    ambiguousSkills: unknown;
+    unvalidatableTools: unknown;
+    exampleLanguages: unknown;
+}
+
+/**
+ * Import a catalog module and normalise it into preprocessor options.
+ *
+ * @throws when the module does not export both `tools` and `skills`.
+ */
+export async function loadSkillCatalog(modulePath: string): Promise<PreprocessSkillMarkdownOptions> {
+    const loaded = (await import(pathToFileURL(modulePath).href)) as Record<string, unknown>;
+    const source = (loaded.default ?? loaded) as RawCatalog;
+
+    if (!source.tools || !source.skills) {
+        throw new Error(`skillCatalog module ${modulePath} must export { tools, skills }.`);
+    }
+    return {
+        tools: new Set(source.tools),
+        skills: new Set(source.skills),
+        ambiguousTools: source.ambiguousTools ? new Set(source.ambiguousTools) : undefined,
+        ambiguousSkills: source.ambiguousSkills ? new Set(source.ambiguousSkills) : undefined,
+        unvalidatableTools: source.unvalidatableTools ? new Set(source.unvalidatableTools) : undefined,
+        validateExample: source.validateExample,
+        validateField: source.validateField,
+        skillToolPrefix: source.skillToolPrefix,
+        exampleLanguages: source.exampleLanguages ? new Set(source.exampleLanguages) : undefined,
+    };
+}
+
+/**
+ * Absolute path of the catalog module configured in a package.json, if any.
+ *
+ * Returns `undefined` when the key is absent — a package that uses no constructs needs no catalog,
+ * and the transformer only fails when a body actually uses one.
+ */
+export function resolveSkillCatalogPath(pkg: Record<string, unknown>, cwd: string): string | undefined {
+    const raw = pkg[CONFIG_KEY];
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return undefined;
+    }
+    const value = (raw as { skillCatalog?: unknown }).skillCatalog;
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`"${CONFIG_KEY}.skillCatalog" must be a non-empty path when set.`);
+    }
+    return path.resolve(cwd, value);
+}
+
+/** Read `<dir>/package.json`, or `undefined` when it is missing or unparseable. */
+export function readPackageJson(dir: string): Record<string, unknown> | undefined {
+    try {
+        return JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf-8')) as Record<string, unknown>;
+    } catch {
+        return undefined;
+    }
+}