@vertesia/build-tools 0.24.0-dev.202601221707

package/src/presets/skill.ts

@@ -0,0 +1,271 @@
+/**
+ * Skill transformer preset for markdown files with frontmatter
+ */
+
+import { z } from 'zod';
+import type { TransformerPreset } from '../types.js';
+import { parseFrontmatter } from '../parsers/frontmatter.js';
+import { discoverSkillAssets } from '../utils/asset-discovery.js';
+
+/**
+ * Content type for skill instructions
+ */
+export type SkillContentType = 'md' | 'jst';
+
+/**
+ * Context triggers for auto-injection of skills (for frontmatter validation)
+ */
+const SkillContextTriggersFrontmatterSchema = z.object({
+    keywords: z.array(z.string()).optional(),
+    tool_names: z.array(z.string()).optional(),
+    data_patterns: z.array(z.string()).optional()
+}).strict();
+
+/**
+ * Context triggers for auto-injection of skills (for output validation)
+ */
+const SkillContextTriggersSchema = z.object({
+    keywords: z.array(z.string()).optional(),
+    tool_names: z.array(z.string()).optional(),
+    data_patterns: z.array(z.string()).optional()
+}).optional();
+
+/**
+ * Execution configuration for skills that need code execution (for frontmatter validation)
+ */
+const SkillExecutionFrontmatterSchema = z.object({
+    language: z.string(),
+    packages: z.array(z.string()).optional(),
+    system_packages: z.array(z.string()).optional(),
+    template: z.string().optional()
+}).strict();
+
+/**
+ * Execution configuration for skills that need code execution (for output validation)
+ */
+const SkillExecutionSchema = z.object({
+    language: z.string(),
+    packages: z.array(z.string()).optional(),
+    system_packages: z.array(z.string()).optional(),
+    template: z.string().optional()
+}).optional();
+
+/**
+ * Zod schema for skill frontmatter validation
+ * This validates the YAML frontmatter before transformation
+ * Supports both flat and nested structures
+ */
+const SkillFrontmatterSchema = z.object({
+    // Required fields
+    name: z.string().min(1, 'Skill name is required'),
+    description: z.string().min(1, 'Skill description is required'),
+
+    // Optional fields
+    title: z.string().optional(),
+    content_type: z.enum(['md', 'jst']).optional(),
+
+    // Flat structure fields (legacy)
+    keywords: z.array(z.string()).optional(),
+    tools: z.array(z.string()).optional(),
+    data_patterns: z.array(z.string()).optional(),
+    language: z.string().optional(),
+    packages: z.array(z.string()).optional(),
+    system_packages: z.array(z.string()).optional(),
+
+    // Nested structure fields
+    context_triggers: SkillContextTriggersFrontmatterSchema.optional(),
+    execution: SkillExecutionFrontmatterSchema.optional(),
+    related_tools: z.array(z.string()).optional(),
+    input_schema: z.object({
+        type: z.literal('object'),
+        properties: z.record(z.any()).optional(),
+        required: z.array(z.string()).optional()
+    }).optional(),
+
+    // Asset fields (auto-discovered but can be overridden)
+    scripts: z.array(z.string()).optional(),
+    widgets: z.array(z.string()).optional()
+}).strict();
+
+/**
+ * MUST be kept in sync with @vertesia/tools-sdk SkillDefinition
+ * Zod schema for skill definition
+ * This validates the structure of skill objects generated from markdown
+ * Matches the SkillDefinition interface from @vertesia/tools-sdk
+ */
+export const SkillDefinitionSchema = z.object({
+    name: z.string().min(1, 'Skill name is required'),
+    title: z.string().optional(),
+    description: z.string().min(1, 'Skill description is required'),
+    instructions: z.string(),
+    content_type: z.enum(['md', 'jst']),
+    input_schema: z.object({
+        type: z.literal('object'),
+        properties: z.record(z.any()).optional(),
+        required: z.array(z.string()).optional()
+    }).optional(),
+    context_triggers: SkillContextTriggersSchema,
+    execution: SkillExecutionSchema,
+    related_tools: z.array(z.string()).optional(),
+    scripts: z.array(z.string()).optional(),
+    widgets: z.array(z.string()).optional()
+});
+
+/**
+ * TypeScript type inferred from the Zod schema
+ * Can also be imported from consumer packages for type safety
+ */
+export type SkillDefinition = z.infer<typeof SkillDefinitionSchema>;
+
+/**
+ * Build a SkillDefinition from frontmatter and markdown content.
+ * This mirrors the logic in @vertesia/tools-sdk parseSkillFile function.
+ *
+ * Supports two frontmatter structures:
+ *
+ * 1. Flat structure (matches parseSkillFile in tools-sdk):
+ *    keywords: [...]
+ *    tools: [...]
+ *    language: python
+ *    packages: [...]
+ *
+ * 2. Nested structure (for more explicit YAML):
+ *    context_triggers:
+ *      keywords: [...]
+ *      tool_names: [...]
+ *    execution:
+ *      language: python
+ *      packages: [...]
+ *    related_tools: [...]
+ *
+ * @param frontmatter - Parsed frontmatter object
+ * @param instructions - Markdown content (body of the file)
+ * @param contentType - Content type ('md' or 'jst')
+ * @param widgets - Discovered widget names
+ * @param scripts - Discovered script names
+ * @returns Skill definition object
+ */
+function buildSkillDefinition(
+    frontmatter: Record<string, any>,
+    instructions: string,
+    contentType: SkillContentType,
+    widgets: string[],
+    scripts: string[]
+): SkillDefinition {
+    const skill: SkillDefinition = {
+        name: frontmatter.name,
+        title: frontmatter.title,
+        description: frontmatter.description,
+        instructions,
+        content_type: contentType,
+        widgets: widgets.length > 0 ? widgets : undefined,
+        scripts: scripts.length > 0 ? scripts : undefined,
+    };
+
+    // Build context triggers - support both flat and nested structure
+    // Nested: context_triggers: { keywords: [...], tool_names: [...] }
+    // Flat: keywords: [...], tools: [...]
+    const contextTriggers = frontmatter.context_triggers;
+    const hasNestedTriggers = contextTriggers && typeof contextTriggers === 'object';
+    const hasFlatTriggers = frontmatter.keywords || frontmatter.tools || frontmatter.data_patterns;
+
+    if (hasNestedTriggers || hasFlatTriggers) {
+        skill.context_triggers = {
+            keywords: hasNestedTriggers ? contextTriggers.keywords : frontmatter.keywords,
+            tool_names: hasNestedTriggers ? contextTriggers.tool_names : frontmatter.tools,
+            data_patterns: hasNestedTriggers ? contextTriggers.data_patterns : frontmatter.data_patterns,
+        };
+    }
+
+    // Build execution config - support both flat and nested structure
+    const execution = frontmatter.execution;
+    const hasNestedExecution = execution && typeof execution === 'object';
+    const hasFlatExecution = frontmatter.language;
+
+    if (hasNestedExecution || hasFlatExecution) {
+        skill.execution = {
+            language: hasNestedExecution ? execution.language : frontmatter.language,
+            packages: hasNestedExecution ? execution.packages : frontmatter.packages,
+            system_packages: hasNestedExecution ? execution.system_packages : frontmatter.system_packages,
+        };
+
+        // Extract code template from instructions if present
+        const codeBlockMatch = instructions.match(/```(?:python|javascript|typescript|js|ts|py)\n([\s\S]*?)```/);
+        if (codeBlockMatch) {
+            skill.execution.template = codeBlockMatch[1].trim();
+        }
+    }
+
+    // Related tools - support both direct field and from tools field
+    if (frontmatter.related_tools) {
+        skill.related_tools = frontmatter.related_tools;
+    } else if (frontmatter.tools && !hasNestedTriggers) {
+        // If tools is not part of context_triggers, use it as related_tools
+        skill.related_tools = frontmatter.tools;
+    }
+
+    // Input schema from frontmatter
+    if (frontmatter.input_schema) {
+        skill.input_schema = frontmatter.input_schema;
+    }
+
+    return skill;
+}
+
+/**
+ * Skill transformer preset
+ * Transforms markdown files with ?skill suffix OR SKILL.md files into skill definition objects
+ *
+ * Matches:
+ * - Files with ?skill suffix: ./my-skill.md?skill
+ * - SKILL.md files: ./my-skill/SKILL.md
+ *
+ * @example
+ * ```typescript
+ * import skill1 from './my-skill.md?skill';
+ * import skill2 from './my-skill/SKILL.md';
+ * // Both are SkillDefinition objects
+ * ```
+ */
+export const skillTransformer: TransformerPreset = {
+    pattern: /(\.md\?skill$|\/SKILL\.md$)/,
+    schema: SkillDefinitionSchema,
+    transform: (content: string, filePath: string) => {
+        const { frontmatter, content: markdown } = parseFrontmatter(content);
+
+        // Validate frontmatter first to catch unknown properties
+        const frontmatterValidation = SkillFrontmatterSchema.safeParse(frontmatter);
+        if (!frontmatterValidation.success) {
+            const errors = frontmatterValidation.error.errors
+                .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}`
+            );
+        }
+
+        // Determine content type from frontmatter or file extension
+        const content_type: SkillContentType = frontmatter.content_type || 'md';
+
+        // Discover assets (scripts and widgets) in the skill directory
+        const assets = discoverSkillAssets(filePath);
+
+        // Build skill definition using the same logic as parseSkillFile in tools-sdk
+        const skillData = buildSkillDefinition(
+            frontmatter,
+            markdown,
+            content_type,
+            assets.widgets,
+            assets.scripts
+        );
+
+        return {
+            data: skillData,
+            assets: assets.assetFiles,
+            widgets: assets.widgetMetadata
+        };
+    }
+};

package/src/types.ts

@@ -0,0 +1,140 @@
+/**
+ * Type definitions for the Vertesia Rollup Import Plugin
+ */
+
+import type { Plugin } from 'rollup';
+import type { z } from 'zod';
+
+/**
+ * Asset file to be copied during build
+ */
+export interface AssetFile {
+    /** Source file path (absolute) */
+    sourcePath: string;
+
+    /** Relative destination path within assets directory */
+    destPath: string;
+
+    /** Asset type for categorization */
+    type: 'script';
+}
+
+/**
+ * Result of a transform function
+ */
+export interface TransformResult {
+    /** The data to export (can be text or JSON object) */
+    data: unknown;
+
+    /** Optional: additional imports to inject at the top of the generated module */
+    imports?: string[];
+
+    /** Optional: custom code to generate instead of default JSON export */
+    code?: string;
+
+    /** Optional: additional asset files to copy */
+    assets?: AssetFile[];
+
+    /** Optional: widget metadata for compilation */
+    widgets?: Array<{ name: string; path: string }>;
+}
+
+/**
+ * Transform function that converts file content into exportable data
+ */
+export type TransformFunction = (
+    content: string,
+    filePath: string
+) => TransformResult | Promise<TransformResult>;
+
+/**
+ * Configuration for a single import transformer rule
+ */
+export interface TransformerRule {
+    /** Pattern to match import paths (e.g., /\.md\?skill$/ or /\?raw$/) */
+    pattern: RegExp;
+
+    /** Transform function to convert file content */
+    transform: TransformFunction;
+
+    /** Optional: Zod schema for validation */
+    schema?: z.ZodType<any>;
+
+    /** Optional: If true, the transformer generates virtual modules (no file to read) */
+    virtual?: boolean;
+
+    /** Optional: additional options for this transformer */
+    options?: Record<string, unknown>;
+}
+
+/**
+ * Widget compilation configuration
+ */
+export interface WidgetConfig {
+    /**
+     * External dependencies that should not be bundled
+     * Default: ['react', 'react-dom', 'react/jsx-runtime']
+     */
+    external?: string[];
+
+    /**
+     * Path to tsconfig.json for widget compilation
+     * Default: './tsconfig.json'
+     */
+    tsconfig?: string;
+
+    /**
+     * Additional options to pass to @rollup/plugin-typescript
+     */
+    typescript?: Record<string, unknown>;
+
+    /**
+     * Minify widget output
+     * Default: false
+     */
+    minify?: boolean;
+}
+
+/**
+ * Plugin configuration
+ */
+export interface PluginConfig {
+    /** Array of transformer rules to apply */
+    transformers: TransformerRule[];
+
+    /**
+     * Root directory for asset output (scripts, widgets, etc.)
+     * - If specified: assets will be copied to this directory
+     * - If false: asset copying is disabled
+     * - Default: './dist'
+     */
+    assetsDir?: string | false;
+
+    /**
+     * Directory for script files relative to assetsDir
+     * Default: 'scripts'
+     */
+    scriptsDir?: string;
+
+    /**
+     * Directory for widget files relative to assetsDir
+     * Default: 'widgets'
+     */
+    widgetsDir?: string;
+
+    /**
+     * Widget compilation configuration
+     * If provided, discovered widgets will be automatically compiled
+     */
+    widgetConfig?: WidgetConfig;
+}
+
+/**
+ * Type for transformer presets
+ */
+export type TransformerPreset = TransformerRule;
+
+/**
+ * Plugin factory return type
+ */
+export type VertesiaImportPlugin = (config: PluginConfig) => Plugin;

package/src/utils/asset-copy.ts

@@ -0,0 +1,63 @@
+/**
+ * Utilities for copying asset files during build
+ */
+
+import { copyFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import type { AssetFile } from '../types.js';
+
+/**
+ * Ensure a directory exists, creating it recursively if needed
+ */
+function ensureDirectory(dirPath: string): void {
+    try {
+        mkdirSync(dirPath, { recursive: true });
+    } catch (error) {
+        // Ignore if directory already exists
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+            throw error;
+        }
+    }
+}
+
+/**
+ * Copy an asset file to its destination
+ *
+ * @param asset - Asset file information
+ * @param assetsRoot - Root directory for assets
+ */
+export function copyAssetFile(asset: AssetFile, assetsRoot: string): void {
+    const destPath = path.join(assetsRoot, asset.destPath);
+    const destDir = path.dirname(destPath);
+
+    // Ensure destination directory exists
+    ensureDirectory(destDir);
+
+    // Copy file
+    try {
+        copyFileSync(asset.sourcePath, destPath);
+    } catch (error) {
+        throw new Error(
+            `Failed to copy asset from ${asset.sourcePath} to ${destPath}: ${error instanceof Error ? error.message : String(error)
+            }`
+        );
+    }
+}
+
+/**
+ * Copy multiple asset files
+ *
+ * @param assets - Array of asset files to copy
+ * @param assetsRoot - Root directory for assets
+ * @returns Number of files copied
+ */
+export function copyAssets(assets: AssetFile[], assetsRoot: string): number {
+    let copied = 0;
+
+    for (const asset of assets) {
+        copyAssetFile(asset, assetsRoot);
+        copied++;
+    }
+
+    return copied;
+}

package/src/utils/asset-discovery.ts

@@ -0,0 +1,138 @@
+/**
+ * Utilities for discovering asset files (scripts, widgets) in skill directories
+ */
+
+import { readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import type { AssetFile } from '../types.js';
+
+/**
+ * Widget metadata for compilation
+ */
+export interface WidgetMetadata {
+    /** Widget name (without .tsx extension) */
+    name: string;
+
+    /** Absolute path to widget file */
+    path: string;
+}
+
+/**
+ * Discovered assets in a skill directory
+ */
+export interface DiscoveredAssets {
+    /** Script file names (with extensions: .js, .py) */
+    scripts: string[];
+
+    /** Widget file names (without .tsx extension) */
+    widgets: string[];
+
+    /** Widget metadata for compilation */
+    widgetMetadata: WidgetMetadata[];
+
+    /** Asset files to be copied */
+    assetFiles: AssetFile[];
+}
+
+/**
+ * Check if a file exists and is a regular file
+ */
+function isFile(filePath: string): boolean {
+    try {
+        return statSync(filePath).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Get all files in a directory (non-recursive)
+ */
+function getFilesInDirectory(dirPath: string): string[] {
+    try {
+        return readdirSync(dirPath).filter(file => {
+            const fullPath = path.join(dirPath, file);
+            return isFile(fullPath);
+        });
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Check if a file is a script file (.js or .py)
+ */
+function isScriptFile(fileName: string): boolean {
+    return /\.(js|py)$/.test(fileName);
+}
+
+/**
+ * Check if a file is a widget file (.tsx)
+ */
+function isWidgetFile(fileName: string): boolean {
+    return /\.tsx$/.test(fileName);
+}
+
+/**
+ * Extract widget name from .tsx file (remove extension)
+ */
+function getWidgetName(fileName: string): string {
+    return fileName.replace(/\.tsx$/, '');
+}
+
+/**
+ * Discover assets (scripts and widgets) in a skill directory
+ *
+ * @param skillFilePath - Absolute path to the skill.md file
+ * @param options - Asset discovery options
+ * @returns Discovered assets and metadata
+ */
+export function discoverSkillAssets(
+    skillFilePath: string,
+    options: {
+        scriptsDir?: string;
+        widgetsDir?: string;
+    } = {}
+): DiscoveredAssets {
+    const skillDir = path.dirname(skillFilePath);
+    const files = getFilesInDirectory(skillDir);
+
+    const scripts: string[] = [];
+    const widgets: string[] = [];
+    const widgetMetadata: WidgetMetadata[] = [];
+    const assetFiles: AssetFile[] = [];
+
+    const scriptsDir = options.scriptsDir || 'scripts';
+
+    for (const file of files) {
+        const fullPath = path.join(skillDir, file);
+
+        if (isScriptFile(file)) {
+            // Script file (.js or .py)
+            scripts.push(file);
+            assetFiles.push({
+                sourcePath: fullPath,
+                destPath: path.join(scriptsDir, file),
+                type: 'script'
+            });
+        } else if (isWidgetFile(file)) {
+            // Widget file (.tsx)
+            const widgetName = getWidgetName(file);
+            widgets.push(widgetName);
+            widgetMetadata.push({
+                name: widgetName,
+                path: fullPath
+            });
+
+            // Note: We don't add widget .tsx files to assetFiles
+            // Widgets are compiled by the plugin if widgetConfig is provided
+        }
+    }
+
+    return {
+        scripts,
+        widgets,
+        widgetMetadata,
+        assetFiles
+    };
+}

package/src/utils/widget-compiler.ts

@@ -0,0 +1,98 @@
+/**
+ * Widget compilation utility using Rollup
+ */
+
+import { rollup, type RollupOptions, type Plugin } from 'rollup';
+import path from 'node:path';
+import type { WidgetConfig } from '../types.js';
+import type { WidgetMetadata } from './asset-discovery.js';
+
+/**
+ * Default external dependencies for widgets
+ */
+const DEFAULT_EXTERNALS = [
+    'react',
+    'react-dom',
+    'react/jsx-runtime',
+    'react/jsx-dev-runtime',
+    'react-dom/client'
+];
+
+/**
+ * Compile widgets using Rollup
+ *
+ * @param widgets - Array of widget metadata to compile
+ * @param outputDir - Directory to write compiled widgets
+ * @param config - Widget compilation configuration
+ * @returns Number of widgets compiled
+ */
+export async function compileWidgets(
+    widgets: WidgetMetadata[],
+    outputDir: string,
+    config: WidgetConfig = {}
+): Promise<number> {
+    if (widgets.length === 0) {
+        return 0;
+    }
+
+    const {
+        external = DEFAULT_EXTERNALS,
+        tsconfig = './tsconfig.json',
+        typescript: typescriptOptions = {},
+        minify = false
+    } = config;
+
+    // Build each widget separately to get individual bundles
+    const buildPromises = widgets.map(async (widget) => {
+        // Dynamically import plugins - use any to bypass TypeScript module resolution issues
+        const typescript = (await import('@rollup/plugin-typescript' as any)).default as any;
+        const nodeResolve = (await import('@rollup/plugin-node-resolve' as any)).default as any;
+        const commonjs = (await import('@rollup/plugin-commonjs' as any)).default as any;
+
+        const plugins: Plugin[] = [
+            typescript({
+                tsconfig,
+                declaration: false,
+                sourceMap: true,
+                ...typescriptOptions
+            }),
+            nodeResolve({
+                browser: true,
+                preferBuiltins: false,
+                extensions: ['.tsx', '.ts', '.jsx', '.js']
+            }),
+            commonjs()
+        ];
+
+        // Add minification if requested
+        if (minify) {
+            const { terser } = await import('rollup-plugin-terser' as any);
+            plugins.push(
+                terser({
+                    compress: {
+                        drop_console: false
+                    }
+                })
+            );
+        }
+
+        const rollupConfig: RollupOptions = {
+            input: widget.path,
+            output: {
+                file: path.join(outputDir, `${widget.name}.js`),
+                format: 'es',
+                sourcemap: true,
+                inlineDynamicImports: true
+            },
+            external,
+            plugins
+        };
+
+        const bundle = await rollup(rollupConfig);
+        await bundle.write(rollupConfig.output as any);
+        await bundle.close();
+    });
+
+    await Promise.all(buildPromises);
+    return widgets.length;
+}