@vertesia/build-tools 0.24.0-dev.202601221707

package/src/plugin.ts

@@ -0,0 +1,166 @@
+/**
+ * Core Rollup plugin implementation for transforming imports
+ */
+
+import type { Plugin } from 'rollup';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import type { PluginConfig, TransformerRule, AssetFile } from './types.js';
+import { copyAssets } from './utils/asset-copy.js';
+import { compileWidgets } from './utils/widget-compiler.js';
+import type { WidgetMetadata } from './utils/asset-discovery.js';
+
+/**
+ * Creates a Rollup plugin that transforms imports based on configured rules
+ */
+export function vertesiaImportPlugin(config: PluginConfig): Plugin {
+    const { transformers, assetsDir = './dist', widgetConfig } = config;
+
+    if (!transformers || transformers.length === 0) {
+        throw new Error('vertesiaImportPlugin: At least one transformer must be configured');
+    }
+
+    // Track assets to copy and widgets to compile
+    const assetsToProcess: AssetFile[] = [];
+    const widgetsToCompile: WidgetMetadata[] = [];
+    const shouldCopyAssets = assetsDir !== false;
+    const shouldCompileWidgets = widgetConfig !== undefined && assetsDir !== false;
+
+    return {
+        name: 'vertesia-import-plugin',
+
+        /**
+         * Resolve import IDs to handle pattern-based imports
+         */
+        resolveId(source: string, importer: string | undefined) {
+            // Check if any transformer pattern matches
+            for (const transformer of transformers) {
+                if (transformer.pattern.test(source)) {
+                    // Handle relative imports
+                    if (source.startsWith('.') && importer) {
+                        const cleanSource = source.replace(transformer.pattern, '');
+                        // Strip query parameters from importer to get the file path
+                        const cleanImporter = importer.indexOf('?') >= 0
+                            ? importer.substring(0, importer.indexOf('?'))
+                            : importer;
+                        // Always use dirname to get the directory containing the importer
+                        const baseDir = path.dirname(cleanImporter);
+                        const resolved = path.resolve(baseDir, cleanSource);
+                        // Return with the pattern suffix to identify it in load
+                        const suffix = source.match(transformer.pattern)?.[0] || '';
+                        return resolved + suffix;
+                    }
+                    return source;
+                }
+            }
+            return null; // Let other plugins handle it
+        },
+
+        /**
+         * Load and transform the file content
+         */
+        async load(id: string) {
+            // Find matching transformer
+            let matchedTransformer: TransformerRule | undefined;
+            let cleanId = id;
+
+            for (const transformer of transformers) {
+                if (transformer.pattern.test(id)) {
+                    matchedTransformer = transformer;
+                    // Remove query parameters to get actual file path
+                    // For example: '/path/file.md?skill' -> '/path/file.md'
+                    //              '/path/file.html?raw' -> '/path/file.html'
+                    const queryIndex = id.indexOf('?');
+                    cleanId = queryIndex >= 0 ? id.substring(0, queryIndex) : id;
+                    break;
+                }
+            }
+
+            if (!matchedTransformer) {
+                return null; // Not for us
+            }
+
+            try {
+                // Read file content (skip for virtual transforms)
+                const content = matchedTransformer.virtual
+                    ? ''
+                    : readFileSync(cleanId, 'utf-8');
+
+                // Transform the content
+                const result = await matchedTransformer.transform(content, cleanId);
+
+                // Collect assets if any
+                if (result.assets && shouldCopyAssets) {
+                    assetsToProcess.push(...result.assets);
+                }
+
+                // Collect widgets if any
+                if (result.widgets && shouldCompileWidgets) {
+                    widgetsToCompile.push(...result.widgets);
+                }
+
+                // Validate if schema provided
+                if (matchedTransformer.schema) {
+                    const validation = matchedTransformer.schema.safeParse(result.data);
+                    if (!validation.success) {
+                        const errors = validation.error.errors
+                            .map((err) => `  - ${err.path.join('.')}: ${err.message}`)
+                            .join('\n');
+                        throw new Error(
+                            `Validation failed for ${id}:\n${errors}`
+                        );
+                    }
+                }
+
+                // Generate code
+                const imports = result.imports ? result.imports.join('\n') + '\n\n' : '';
+                if (result.code) {
+                    // Custom code provided - prepend imports
+                    return imports + result.code;
+                } else {
+                    // Default: export data (escape if string, otherwise stringify as JSON)
+                    const dataJson = JSON.stringify(result.data, null, 2);
+                    return `${imports}export default ${dataJson};`;
+                }
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.error(`Failed to transform ${id}: ${message}`);
+            }
+        },
+
+        /**
+         * Copy assets and compile widgets after all modules are loaded
+         */
+        async buildEnd() {
+            // Copy script assets
+            if (shouldCopyAssets && assetsToProcess.length > 0) {
+                try {
+                    const copied = copyAssets(assetsToProcess, assetsDir as string);
+                    console.log(`Copied ${copied} asset file(s) to ${assetsDir}`);
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.warn(`Failed to copy assets: ${message}`);
+                }
+            }
+
+            // Compile widgets
+            if (shouldCompileWidgets && widgetsToCompile.length > 0) {
+                try {
+                    const widgetsDir = config.widgetsDir || 'widgets';
+                    const outputDir = path.join(assetsDir as string, widgetsDir);
+
+                    console.log(`Compiling ${widgetsToCompile.length} widget(s)...`);
+                    const compiled = await compileWidgets(
+                        widgetsToCompile,
+                        outputDir,
+                        widgetConfig
+                    );
+                    console.log(`Compiled ${compiled} widget(s) to ${outputDir}`);
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.error(`Failed to compile widgets: ${message}`);
+                }
+            }
+        }
+    };
+}

package/src/presets/index.ts

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

package/src/presets/prompt.ts

@@ -0,0 +1,227 @@
+/**
+ * Prompt transformer preset for template files with frontmatter
+ * Supports .jst, .hbs, and plain text files
+ */
+
+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';
+
+/**
+ * Re-export types for backwards compatibility
+ */
+export { TemplateType, PromptRole };
+
+/**
+ * Template type alias
+ */
+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();
+
+/**
+ * MUST be kept in sync with @vertesia/common InCodePrompt
+ * Zod schema for prompt definition
+ */
+export const PromptDefinitionSchema = z.object({
+    role: z.nativeEnum(PromptRole),
+    content: z.string(),
+    content_type: z.nativeEnum(TemplateType),
+    schema: z.any().optional(),
+    name: z.string().optional(),
+    externalId: z.string().optional(),
+});
+
+/**
+ * TypeScript type inferred from the Zod schema
+ */
+export type PromptDefinition = z.infer<typeof PromptDefinitionSchema>;
+
+/**
+ * Normalize schema path for import
+ * - Adds './' prefix if not a relative path
+ * - Replaces .ts with .js
+ * - Adds .js if no extension
+ *
+ * @param schemaPath - Original schema path from frontmatter
+ * @returns Normalized path for ES module import
+ */
+function normalizeSchemaPath(schemaPath: string): string {
+    let normalized = schemaPath.trim();
+
+    // Add './' prefix if not already a relative path
+    if (!normalized.startsWith('.')) {
+        normalized = './' + normalized;
+    }
+
+    // Get the extension
+    const ext = path.extname(normalized);
+
+    if (ext === '.ts') {
+        // Replace .ts with .js
+        normalized = normalized.slice(0, -3) + '.js';
+    } else if (!ext) {
+        // No extension, add .js
+        normalized = normalized + '.js';
+    }
+    // If extension is already .js or something else, leave as is
+
+    return normalized;
+}
+
+/**
+ * Infer content type from file extension
+ *
+ * @param filePath - Path to the prompt file
+ * @returns Inferred content type
+ */
+function inferContentType(filePath: string): TemplateType {
+    const ext = path.extname(filePath).toLowerCase();
+
+    switch (ext) {
+        case '.jst':
+            return TemplateType.jst;
+        case '.hbs':
+            return TemplateType.handlebars;
+        default:
+            return TemplateType.text;
+    }
+}
+
+/**
+ * Build a PromptDefinition from frontmatter and content
+ *
+ * @param frontmatter - Parsed frontmatter object
+ * @param content - Prompt content (body of the file)
+ * @param filePath - Path to the prompt file (for content type inference)
+ * @returns Prompt definition object and optional imports
+ */
+function buildPromptDefinition(
+    frontmatter: Record<string, any>,
+    content: 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 prompt: PromptDefinition = {
+        role: frontmatter.role,
+        content,
+        content_type,
+    };
+
+    // Add optional fields
+    if (frontmatter.name) {
+        prompt.name = frontmatter.name;
+    }
+    if (frontmatter.externalId) {
+        prompt.externalId = frontmatter.externalId;
+    }
+
+    // Handle schema import if specified
+    let imports: string[] | undefined;
+    let schemaImportName: string | undefined;
+
+    if (frontmatter.schema) {
+        const normalizedPath = normalizeSchemaPath(frontmatter.schema);
+        schemaImportName = '__promptSchema';
+        imports = [`import ${schemaImportName} from '${normalizedPath}';`];
+    }
+
+    return { prompt, imports, schemaImportName };
+}
+
+/**
+ * Prompt transformer preset
+ * Transforms template files with ?prompt suffix into prompt definition objects
+ *
+ * Supported file types:
+ * - .jst (JavaScript template literals) → content_type: 'jst'
+ * - .hbs (Handlebars templates) → content_type: 'handlebars'
+ * - .txt or other → content_type: 'text'
+ *
+ * @example
+ * ```typescript
+ * import PROMPT from './prompt.hbs?prompt';
+ * // PROMPT is an InCodePrompt object
+ * ```
+ */
+export const promptTransformer: TransformerPreset = {
+    pattern: /\?prompt$/,
+    schema: PromptDefinitionSchema,
+    transform: (content: string, filePath: string) => {
+        const { frontmatter, content: promptContent } = parseFrontmatter(content);
+
+        // Validate frontmatter
+        const frontmatterValidation = PromptFrontmatterSchema.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}`
+            );
+        }
+
+        // Build prompt definition
+        const { prompt, imports, schemaImportName } = buildPromptDefinition(
+            frontmatter,
+            promptContent,
+            filePath
+        );
+
+        // If schema is specified, generate custom code with schema reference
+        if (schemaImportName) {
+            // Build the code manually to avoid JSON.stringify issues with schema reference
+            const lines = [
+                'export default {',
+                `  role: "${prompt.role}",`,
+                `  content: ${JSON.stringify(prompt.content)},`,
+                `  content_type: "${prompt.content_type}",`,
+                `  schema: ${schemaImportName}`,
+            ];
+
+            if (prompt.name) {
+                lines.splice(4, 0, `  name: ${JSON.stringify(prompt.name)},`);
+            }
+            if (prompt.externalId) {
+                lines.splice(4, 0, `  externalId: ${JSON.stringify(prompt.externalId)},`);
+            }
+
+            lines.push('};');
+            const code = lines.join('\n');
+
+            return {
+                data: prompt,
+                imports,
+                code,
+            };
+        }
+
+        // Standard case without schema
+        return {
+            data: prompt,
+        };
+    }
+};

package/src/presets/raw.ts

@@ -0,0 +1,24 @@
+/**
+ * Raw transformer preset for importing file content as strings
+ */
+
+import type { TransformerPreset } from '../types.js';
+
+/**
+ * Raw transformer preset
+ * Transforms any file with ?raw suffix into a string export
+ *
+ * @example
+ * ```typescript
+ * import template from './template.html?raw';
+ * // template is a string containing the file content
+ * ```
+ */
+export const rawTransformer: TransformerPreset = {
+    pattern: /\?raw$/,
+    transform: (content: string) => {
+        return {
+            data: content
+        };
+    }
+};

package/src/presets/skill-collection.ts

@@ -0,0 +1,86 @@
+/**
+ * Skill collection transformer for directory-based skill imports
+ * Scans a directory for subdirectories containing SKILL.md files
+ */
+
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import type { TransformerPreset } from '../types.js';
+
+/**
+ * Skill collection transformer preset
+ * Transforms directory imports with ?skills suffix into an array of skill imports
+ *
+ * Matches:
+ * - ./all?skills (recommended - generates all.js in the directory)
+ * - ./_skills?skills (generates _skills.js in the directory)
+ * - Any path ending with a filename and ?skills
+ *
+ * NOTE: A filename before ?skills is REQUIRED to avoid naming conflicts.
+ * The filename becomes the output module name.
+ *
+ * @example
+ * ```typescript
+ * import skills from './all?skills';
+ * // Scans current directory for subdirectories with SKILL.md
+ * // Generates all.js containing array of all skills
+ * ```
+ */
+export const skillCollectionTransformer: TransformerPreset = {
+    pattern: /\/[^/?]+\?skills$/,
+    virtual: true, // Indicates this doesn't transform a real file
+    transform: (_content: string, filePath: string) => {
+        // Remove ?skills suffix and the filename to get directory path
+        // Example: /path/code/all?skills -> /path/code/all -> /path/code/
+        const pathWithoutQuery = filePath.replace(/\?skills$/, '');
+        const dirPath = path.dirname(pathWithoutQuery);
+
+        if (!existsSync(dirPath)) {
+            throw new Error(`Directory not found: ${dirPath}`);
+        }
+
+        if (!statSync(dirPath).isDirectory()) {
+            throw new Error(`Not a directory: ${dirPath}`);
+        }
+
+        // Scan for subdirectories containing SKILL.md
+        const entries = readdirSync(dirPath);
+        const imports: string[] = [];
+        const names: string[] = [];
+
+        for (const entry of entries) {
+            const entryPath = path.join(dirPath, entry);
+
+            try {
+                if (statSync(entryPath).isDirectory()) {
+                    const skillFile = path.join(entryPath, 'SKILL.md');
+                    if (existsSync(skillFile)) {
+                        // Generate unique identifier from directory name
+                        const identifier = `Skill_${entry.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+                        imports.push(`import ${identifier} from './${entry}/SKILL.md';`);
+                        names.push(identifier);
+                    }
+                }
+            } catch (err) {
+                // Skip entries that can't be read
+                continue;
+            }
+        }
+
+        if (names.length === 0) {
+            console.warn(`No SKILL.md files found in subdirectories of ${dirPath}`);
+        }
+
+        // Generate code that imports all skills and exports as array
+        const code = [
+            ...imports,
+            '',
+            `export default [${names.join(', ')}];`
+        ].join('\n');
+
+        return {
+            data: null, // Not used when custom code is provided
+            code
+        };
+    }
+};