@vertesia/build-tools 1.3.0 → 1.4.0-dev.20260614.160504Z

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@vertesia/build-tools",
-  "version": "1.3.0",
-  "description": "Build tools for Vertesia projects - Rollup and Vite plugins for transforming imports, bundling skills, and compiling widgets",
+  "version": "1.4.0-dev.20260614.160504Z",
+  "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/esm/index.js",
-  "types": "./lib/types/index.d.ts",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "bin": {
+    "vertesia-build": "lib/bin/build.js"
+  },
   "files": [
     "lib",
     "src"
@@ -12,38 +15,45 @@
   "license": "Apache-2.0",
   "exports": {
     ".": {
-      "types": "./lib/types/index.d.ts",
-      "import": "./lib/esm/index.js",
-      "require": "./lib/cjs/index.js"
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
     },
     "./vite": {
-      "types": "./lib/types/vite.d.ts",
-      "import": "./lib/esm/vite.js",
-      "require": "./lib/cjs/vite.js"
+      "types": "./lib/vite/index.d.ts",
+      "default": "./lib/vite/index.js"
     }
   },
   "devDependencies": {
+    "@hono/node-server": "^2.0.4",
+    "@types/node": "^24.12.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.8",
+    "@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",
-    "@types/node": "^24.1.0",
-    "rollup": "^4.59.0",
-    "ts-dual-module": "^0.6.3",
-    "typescript": "^6.0.2",
-    "vitest": "^4.0.16"
-  },
-  "dependencies": {
+    "esbuild": "^0.28.0",
     "gray-matter": "^4.0.3",
-    "zod": "^3.24.1",
-    "@llumiverse/common": "1.3.0",
-    "@vertesia/common": "1.3.0"
+    "zod": "^4.4.3",
+    "@vertesia/common": "1.4.0-dev.20260614.160504Z",
+    "@llumiverse/common": "1.3.0"
   },
   "peerDependencies": {
-    "rollup": "^4.59.0"
+    "@hono/node-server": "^2.0.0",
+    "vite": "^8.0.0"
   },
-  "ts_dual_module": {
-    "outDir": "lib"
+  "peerDependenciesMeta": {
+    "@hono/node-server": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",
@@ -52,14 +62,12 @@
   },
   "keywords": [
     "vertesia",
-    "rollup",
-    "rollup-plugin",
     "vite",
     "vite-plugin",
     "build-tools",
     "imports",
     "transform",
-    "compiler",
+    "esbuild",
     "skill",
     "markdown",
     "frontmatter",
@@ -69,8 +77,10 @@
     "validation"
   ],
   "scripts": {
+    "lint": "biome lint src",
     "test": "vitest run",
-    "build": "pnpm exec tsmod build && pnpm exec rollup -c",
-    "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
+    "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
+    "build": "rm -rf ./lib ./tsconfig.tsbuildinfo && tsc && chmod +x ./lib/bin/build.js",
+    "clean": "rm -rf ./node_modules ./lib ./tsconfig.tsbuildinfo"
   }
 }

package/src/bin/build.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * `vertesia-build` — Vertesia plugin build CLI.
+ *
+ * Today this runs the post-`tsc` finalization step: import transformation
+ * (`?skill` / `?raw` / `?prompt` / `?template` / `?skills` / `?templates`
+ * and bare `SKILL.md` / `TEMPLATE.md` imports), asset copying, and esbuild
+ * widget bundling.
+ *
+ * Reads its configuration from the consuming package's `package.json` under
+ * the `vertesia-build` key, then delegates to `transformImports` in
+ * `@vertesia/build-tools`.
+ *
+ * Usage in a plugin's package.json:
+ *
+ *     {
+ *         "scripts": {
+ *             "build:server": "tsc -p tsconfig.tool-server.json && vertesia-build"
+ *         },
+ *         "vertesia-build": {
+ *             "libDir": "./lib",
+ *             "srcDir": "./src/tool-server",
+ *             "transformers": ["skill", "skills", "template", "templates", "prompt", "raw"],
+ *             "assetsDir": "./dist",
+ *             "widgetsDir": "widgets",
+ *             "widgetConfig": { "minify": false }
+ *         }
+ *     }
+ *
+ * Available transformer names: skill, skills, template, templates, prompt, raw.
+ * The `transformers` field is required so consumers explicitly opt in to each
+ * preset (and so missing or misspelled names fail loudly at build time).
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { transformImports } from '../import-transform/index.js';
+import { resolveConfig, VertesiaBuildConfigError } from './config.js';
+
+function fail(message: string): never {
+    console.error(`vertesia-build: ${message}`);
+    process.exit(1);
+}
+
+function readPackageJson(cwd: string): Record<string, unknown> {
+    const pkgPath = path.join(cwd, 'package.json');
+    let raw: string;
+    try {
+        raw = readFileSync(pkgPath, 'utf-8');
+    } catch (error) {
+        fail(`could not read ${pkgPath}: ${(error as Error).message}`);
+    }
+    try {
+        return JSON.parse(raw) as Record<string, unknown>;
+    } catch (error) {
+        fail(`could not parse ${pkgPath}: ${(error as Error).message}`);
+    }
+}
+
+async function main(): Promise<void> {
+    const cwd = process.cwd();
+    const pkg = readPackageJson(cwd);
+    let options;
+    try {
+        options = resolveConfig(pkg, cwd);
+    } catch (error) {
+        if (error instanceof VertesiaBuildConfigError) {
+            fail(error.message);
+        }
+        throw error;
+    }
+    const result = await transformImports(options);
+    console.log(
+        `vertesia-build: files=${result.filesProcessed} chunks=${result.chunksEmitted} ` +
+            `assets=${result.assetsCopied} widgets=${result.widgetsCompiled}`,
+    );
+}
+
+main().catch((error) => {
+    console.error(`vertesia-build: ${(error as Error).stack ?? (error as Error).message}`);
+    process.exit(1);
+});

package/src/bin/config.ts

@@ -0,0 +1,113 @@
+/**
+ * Pure config-parsing logic for the `vertesia-build` CLI.
+ *
+ * Lives in its own module so it can be unit-tested without spawning a
+ * subprocess. Errors are surfaced as thrown exceptions — the CLI entry
+ * point (`build.ts`) catches them and translates to `process.exit(1)`
+ * with a clear message.
+ */
+
+import path from 'node:path';
+import { resolveTransformerNames } from '../import-transform/builtins.js';
+import type { TransformImportsOptions } from '../import-transform/index.js';
+
+export const CONFIG_KEY = 'vertesia-build';
+
+export class VertesiaBuildConfigError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'VertesiaBuildConfigError';
+    }
+}
+
+interface RawConfig {
+    libDir?: unknown;
+    srcDir?: unknown;
+    transformers?: unknown;
+    assetsDir?: unknown;
+    widgetsDir?: unknown;
+    widgetConfig?: unknown;
+}
+
+/**
+ * Parse and validate the `vertesia-build` block of a package.json.
+ *
+ * @param pkg  Parsed contents of the consuming `package.json`.
+ * @param cwd  Working directory used to resolve relative paths in the config.
+ * @returns Resolved options suitable for passing to `transformImports`.
+ * @throws {VertesiaBuildConfigError} when the config is missing, malformed,
+ *         or references unknown transformers.
+ */
+export function resolveConfig(pkg: Record<string, unknown>, cwd: string): TransformImportsOptions {
+    const raw = pkg[CONFIG_KEY];
+
+    if (raw === undefined) {
+        throw new VertesiaBuildConfigError(`missing "${CONFIG_KEY}" key in package.json at ${cwd}.`);
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new VertesiaBuildConfigError(`"${CONFIG_KEY}" must be an object in package.json.`);
+    }
+    const cfg = raw as RawConfig;
+
+    if (typeof cfg.libDir !== 'string' || cfg.libDir.length === 0) {
+        throw new VertesiaBuildConfigError(`"${CONFIG_KEY}.libDir" must be a non-empty string.`);
+    }
+    if (typeof cfg.srcDir !== 'string' || cfg.srcDir.length === 0) {
+        throw new VertesiaBuildConfigError(`"${CONFIG_KEY}.srcDir" must be a non-empty string.`);
+    }
+    if (!Array.isArray(cfg.transformers) || cfg.transformers.length === 0) {
+        throw new VertesiaBuildConfigError(
+            `"${CONFIG_KEY}.transformers" must be a non-empty array of transformer names.`,
+        );
+    }
+    const names: string[] = [];
+    for (const entry of cfg.transformers) {
+        if (typeof entry !== 'string' || entry.length === 0) {
+            throw new VertesiaBuildConfigError(
+                `every entry in "${CONFIG_KEY}.transformers" must be a non-empty string.`,
+            );
+        }
+        names.push(entry);
+    }
+
+    let transformers: TransformImportsOptions['transformers'];
+    try {
+        transformers = resolveTransformerNames(names);
+    } catch (error) {
+        // resolveTransformerNames throws plain Error; rewrap so callers can
+        // identify config-level failures uniformly.
+        throw new VertesiaBuildConfigError((error as Error).message);
+    }
+
+    const resolved: TransformImportsOptions = {
+        libDir: path.resolve(cwd, cfg.libDir),
+        srcDir: path.resolve(cwd, cfg.srcDir),
+        transformers,
+    };
+
+    if (cfg.assetsDir !== undefined) {
+        if (cfg.assetsDir === false) {
+            resolved.assetsDir = false;
+        } else if (typeof cfg.assetsDir === 'string' && cfg.assetsDir.length > 0) {
+            resolved.assetsDir = path.resolve(cwd, cfg.assetsDir);
+        } else {
+            throw new VertesiaBuildConfigError(`"${CONFIG_KEY}.assetsDir" must be a string path or false.`);
+        }
+    }
+
+    if (cfg.widgetsDir !== undefined) {
+        if (typeof cfg.widgetsDir !== 'string' || cfg.widgetsDir.length === 0) {
+            throw new VertesiaBuildConfigError(`"${CONFIG_KEY}.widgetsDir" must be a non-empty string when set.`);
+        }
+        resolved.widgetsDir = cfg.widgetsDir;
+    }
+
+    if (cfg.widgetConfig !== undefined) {
+        if (typeof cfg.widgetConfig !== 'object' || cfg.widgetConfig === null || Array.isArray(cfg.widgetConfig)) {
+            throw new VertesiaBuildConfigError(`"${CONFIG_KEY}.widgetConfig" must be an object when set.`);
+        }
+        resolved.widgetConfig = cfg.widgetConfig as TransformImportsOptions['widgetConfig'];
+    }
+
+    return resolved;
+}

package/src/core/compilers/widget.ts

@@ -0,0 +1,69 @@
+/**
+ * Widget bundler using esbuild.
+ *
+ * Takes already-compiled JavaScript widget entries (produced by `tsc` from
+ * `.tsx` sources) and emits a single-file ESM bundle with React-family
+ * packages left as external imports.
+ *
+ * No TypeScript / JSX transformation happens here — `tsc` does that during
+ * the main build step. This module is a pure module concatenator.
+ */
+
+import path from 'node:path';
+import { build } from 'esbuild';
+
+const DEFAULT_EXTERNALS = ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'react-dom/client'];
+
+export interface WidgetCompilerConfig {
+    /** External package names that should not be bundled. */
+    external?: string[];
+
+    /** Minify the output. Default: false */
+    minify?: boolean;
+
+    /** Emit source maps. Default: true */
+    sourcemap?: boolean | 'inline' | 'external';
+}
+
+export interface WidgetInput {
+    /** Widget name (used for the output file name, without extension). */
+    name: string;
+
+    /** Absolute path to the already-compiled `.js` entry to bundle. */
+    entry: string;
+}
+
+export async function compileWidget(
+    widget: WidgetInput,
+    outputDir: string,
+    config: WidgetCompilerConfig = {},
+): Promise<string> {
+    const { external = DEFAULT_EXTERNALS, minify = false, sourcemap = true } = config;
+    const outfile = path.join(outputDir, `${widget.name}.js`);
+
+    await build({
+        entryPoints: [widget.entry],
+        outfile,
+        bundle: true,
+        format: 'esm',
+        platform: 'browser',
+        external,
+        minify,
+        sourcemap,
+        logLevel: 'silent',
+    });
+
+    return outfile;
+}
+
+export async function compileWidgets(
+    widgets: WidgetInput[],
+    outputDir: string,
+    config: WidgetCompilerConfig = {},
+): Promise<number> {
+    if (widgets.length === 0) {
+        return 0;
+    }
+    await Promise.all(widgets.map((widget) => compileWidget(widget, outputDir, config)));
+    return widgets.length;
+}

package/src/{parsers → core/parsers}/frontmatter.ts

@@ -6,7 +6,7 @@ import matter from 'gray-matter';
 
 export interface FrontmatterResult {
     /** Parsed frontmatter data */
-    frontmatter: Record<string, any>;
+    frontmatter: Record<string, unknown>;
 
     /** Content without frontmatter */
     content: string;
@@ -27,6 +27,6 @@ export function parseFrontmatter(content: string): FrontmatterResult {
     return {
         frontmatter: result.data,
         content: result.content,
-        original: content
+        original: content,
     };
 }

package/src/core/transformers/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Preset transformers for common use cases
+ */
+
+export {
+    type PromptContentType,
+    type PromptDefinition,
+    PromptDefinitionSchema,
+    PromptRole,
+    promptTransformer,
+    TemplateType,
+} from './prompt.js';
+export { rawTransformer } from './raw.js';
+export {
+    type SkillContentType,
+    type SkillDefinition,
+    SkillDefinitionSchema,
+    SkillPropertiesSchema,
+    skillTransformer,
+} from './skill.js';
+export { skillCollectionTransformer } from './skill-collection.js';
+export {
+    type RenderingTemplateDefinition,
+    RenderingTemplateDefinitionSchema,
+    templateTransformer,
+} from './template.js';
+export { templateCollectionTransformer } from './template-collection.js';

package/src/{presets → core/transformers}/prompt.ts

@@ -3,17 +3,17 @@
  * Supports .jst, .hbs, and plain text files
  */
 
+import path from 'node:path';
+import { PromptRole } from '@llumiverse/common';
+import { type JSONSchema, TemplateType } from '@vertesia/common';
 import { z } from 'zod';
-import type { TransformerPreset } from '../types.js';
 import { parseFrontmatter } from '../parsers/frontmatter.js';
-import path from 'path';
-import { TemplateType } from '@vertesia/common';
-import { PromptRole } from '@llumiverse/common';
+import type { TransformerPreset } from '../types.js';
 
 /**
  * Re-export types for backwards compatibility
  */
-export { TemplateType, PromptRole };
+export { PromptRole, TemplateType };
 
 /**
  * Template type alias
@@ -23,18 +23,20 @@ export type PromptContentType = TemplateType;
 /**
  * Zod schema for prompt frontmatter validation
  */
-const PromptFrontmatterSchema = z.object({
-    // Required fields
-    role: z.nativeEnum(PromptRole, {
-        errorMap: () => ({ message: 'Role must be one of: safety, system, user, assistant, negative' })
-    }),
-
-    // Optional fields
-    content_type: z.nativeEnum(TemplateType).optional(),
-    schema: z.string().optional(),
-    name: z.string().optional(),
-    externalId: z.string().optional(),
-}).strict();
+const PromptFrontmatterSchema = z
+    .object({
+        // Required fields
+        role: z.nativeEnum(PromptRole, {
+            error: 'Role must be one of: safety, system, user, assistant, negative',
+        }),
+
+        // Optional fields
+        content_type: z.nativeEnum(TemplateType).optional(),
+        schema: z.string().optional(),
+        name: z.string().optional(),
+        externalId: z.string().optional(),
+    })
+    .strict();
 
 /**
  * MUST be kept in sync with @vertesia/common InCodePrompt
@@ -44,7 +46,7 @@ export const PromptDefinitionSchema = z.object({
     role: z.nativeEnum(PromptRole),
     content: z.string(),
     content_type: z.nativeEnum(TemplateType),
-    schema: z.any().optional(),
+    schema: z.custom<JSONSchema>().optional(),
     name: z.string().optional(),
     externalId: z.string().optional(),
 });
@@ -54,6 +56,8 @@ export const PromptDefinitionSchema = z.object({
  */
 export type PromptDefinition = z.infer<typeof PromptDefinitionSchema>;
 
+type PromptFrontmatter = z.infer<typeof PromptFrontmatterSchema>;
+
 /**
  * Normalize schema path for import
  * - Adds './' prefix if not a relative path
@@ -68,7 +72,7 @@ function normalizeSchemaPath(schemaPath: string): string {
 
     // Add './' prefix if not already a relative path
     if (!normalized.startsWith('.')) {
-        normalized = './' + normalized;
+        normalized = `./${normalized}`;
     }
 
     // Get the extension
@@ -76,10 +80,10 @@ function normalizeSchemaPath(schemaPath: string): string {
 
     if (ext === '.ts') {
         // Replace .ts with .js
-        normalized = normalized.slice(0, -3) + '.js';
+        normalized = `${normalized.slice(0, -3)}.js`;
     } else if (!ext) {
         // No extension, add .js
-        normalized = normalized + '.js';
+        normalized = `${normalized}.js`;
     }
     // If extension is already .js or something else, leave as is
 
@@ -114,13 +118,12 @@ function inferContentType(filePath: string): TemplateType {
  * @returns Prompt definition object and optional imports
  */
 function buildPromptDefinition(
-    frontmatter: Record<string, any>,
+    frontmatter: PromptFrontmatter,
     content: string,
-    filePath: string
+    filePath: string,
 ): { prompt: PromptDefinition; imports?: string[]; schemaImportName?: string } {
     // Determine content type from frontmatter or file extension
-    const content_type: TemplateType =
-        frontmatter.content_type || inferContentType(filePath);
+    const content_type: TemplateType = frontmatter.content_type || inferContentType(filePath);
 
     const prompt: PromptDefinition = {
         role: frontmatter.role,
@@ -173,22 +176,22 @@ export const promptTransformer: TransformerPreset = {
         // Validate frontmatter
         const frontmatterValidation = PromptFrontmatterSchema.safeParse(frontmatter);
         if (!frontmatterValidation.success) {
-            const errors = frontmatterValidation.error.errors
+            const errors = frontmatterValidation.error.issues
                 .map((err) => {
                     const path = err.path.length > 0 ? err.path.join('.') : 'frontmatter';
                     return `  - ${path}: ${err.message}`;
                 })
                 .join('\n');
-            throw new Error(
-                `Invalid frontmatter in ${filePath}:\n${errors}`
-            );
+            throw new Error(`Invalid frontmatter in ${filePath}:\n${errors}`);
         }
 
+        const validatedFrontmatter = frontmatterValidation.data;
+
         // Build prompt definition
         const { prompt, imports, schemaImportName } = buildPromptDefinition(
-            frontmatter,
+            validatedFrontmatter,
             promptContent,
-            filePath
+            filePath,
         );
 
         // If schema is specified, generate custom code with schema reference
@@ -223,5 +226,5 @@ export const promptTransformer: TransformerPreset = {
         return {
             data: prompt,
         };
-    }
+    },
 };

package/src/{presets → core/transformers}/raw.ts

@@ -18,7 +18,7 @@ export const rawTransformer: TransformerPreset = {
     pattern: /\?raw$/,
     transform: (content: string) => {
         return {
-            data: content
+            data: content,
         };
-    }
+    },
 };

package/src/{presets → core/transformers}/skill-collection.ts

@@ -3,7 +3,7 @@
  * Scans a directory for subdirectories containing SKILL.md files
  */
 
-import { readdirSync, statSync, existsSync } from 'node:fs';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import type { TransformerPreset } from '../types.js';
 
@@ -61,10 +61,7 @@ export const skillCollectionTransformer: TransformerPreset = {
                         names.push(identifier);
                     }
                 }
-            } catch (err) {
-                // Skip entries that can't be read
-                continue;
-            }
+            } catch {}
         }
 
         if (names.length === 0) {
@@ -72,15 +69,11 @@ export const skillCollectionTransformer: TransformerPreset = {
         }
 
         // Generate code that imports all skills and exports as array
-        const code = [
-            ...imports,
-            '',
-            `export default [${names.join(', ')}];`
-        ].join('\n');
+        const code = [...imports, '', `export default [${names.join(', ')}];`].join('\n');
 
         return {
             data: null, // Not used when custom code is provided
-            code
+            code,
         };
-    }
+    },
 };