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

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

@@ -1,116 +1,121 @@
-/**
- * Template transformer preset for markdown files with frontmatter
- */
-
-import path from 'node:path';
-import { z } from 'zod';
-import type { TransformerPreset } from '../types.js';
-import { parseFrontmatter } from '../parsers/frontmatter.js';
-import { discoverTemplateAssets } from '../utils/template-asset-discovery.js';
-
-/**
- * Zod schema for template frontmatter validation.
- * Only includes fields authored by the user.
- * The name and id are inferred from the directory structure.
- */
-const TemplateFrontmatterSchema = z.object({
-    title: z.string().optional(),
-    description: z.string().min(1, 'Template description is required'),
-    tags: z.array(z.string()).optional(),
-    type: z.enum(['presentation', 'document']),
-}).strict();
-
-/**
- * MUST be kept in sync with @vertesia/tools-sdk RenderingTemplateDefinition
- * Zod schema for template definition
- */
-export const RenderingTemplateDefinitionSchema = z.object({
-    id: z.string().min(1, 'Template id is required'),
-    name: z.string().min(1, 'Template name is required'),
-    title: z.string().optional(),
-    description: z.string().min(1, 'Template description is required'),
-    instructions: z.string(),
-    tags: z.array(z.string()).optional(),
-    type: z.enum(['presentation', 'document']),
-    assets: z.array(z.string()),
-}).passthrough();
-
-/**
- * TypeScript type inferred from the Zod schema
- */
-export type RenderingTemplateDefinition = z.infer<typeof RenderingTemplateDefinitionSchema>;
-
-/**
- * Derive the template path segments from the file path.
- *
- * Example: .../templates/examples/report/TEMPLATE.md
- *   → category: "examples", name: "report", relative: "examples/report"
- */
-function deriveTemplatePathInfo(filePath: string): { category: string; templateName: string; relative: string } {
-    const templateDir = path.dirname(filePath);
-    const templateName = path.basename(templateDir);
-    const collectionDir = path.dirname(templateDir);
-    const category = path.basename(collectionDir);
-    return { category, templateName, relative: `${category}/${templateName}` };
-}
-
-/**
- * Template transformer preset
- * Transforms markdown files with ?template suffix OR TEMPLATE.md files into template definition objects
- *
- * Matches:
- * - Files with ?template suffix: ./my-template.md?template
- * - TEMPLATE.md files: ./my-template/TEMPLATE.md
- *
- * @example
- * ```typescript
- * import template1 from './my-template.md?template';
- * import template2 from './my-template/TEMPLATE.md';
- * // Both are RenderingTemplateDefinition objects
- * ```
- */
-export const templateTransformer: TransformerPreset = {
-    pattern: /(\.md\?template$|\/TEMPLATE\.md$)/,
-    schema: RenderingTemplateDefinitionSchema,
-    transform: (content: string, filePath: string) => {
-        const { frontmatter, content: markdown } = parseFrontmatter(content);
-
-        // Validate frontmatter
-        const frontmatterValidation = TemplateFrontmatterSchema.safeParse(frontmatter);
-        if (!frontmatterValidation.success) {
-            const errors = frontmatterValidation.error.errors
-                .map((err) => {
-                    const pathStr = err.path.length > 0 ? err.path.join('.') : 'frontmatter';
-                    return `  - ${pathStr}: ${err.message}`;
-                })
-                .join('\n');
-            throw new Error(
-                `Invalid frontmatter in ${filePath}:\n${errors}`
-            );
-        }
-
-        // Derive template path from directory structure
-        const { category, templateName, relative: templatePath } = deriveTemplatePathInfo(filePath);
-
-        // Discover asset files in the template directory
-        const assets = discoverTemplateAssets(filePath, templatePath);
-
-        // Build template definition
-        // Assets use absolute paths for direct server-side resolution
-        const templateData: RenderingTemplateDefinition = {
-            id: `${category}:${templateName}`,
-            name: templateName,
-            title: frontmatter.title,
-            description: frontmatter.description,
-            instructions: markdown,
-            tags: frontmatter.tags,
-            type: frontmatter.type,
-            assets: assets.fileNames.map(f => `/templates/${templatePath}/${f}`),
-        };
-
-        return {
-            data: templateData,
-            assets: assets.assetFiles,
-        };
-    }
-};
+/**
+ * Template transformer preset for markdown files with frontmatter
+ */
+
+import path from 'node:path';
+import { z } from 'zod';
+import { parseFrontmatter } from '../parsers/frontmatter.js';
+import type { TransformerPreset } from '../types.js';
+import { discoverTemplateAssets } from '../utils/template-asset-discovery.js';
+
+/**
+ * Zod schema for template frontmatter validation.
+ * Only includes fields authored by the user.
+ * The name and id are inferred from the directory structure.
+ */
+const TemplateFrontmatterSchema = z
+    .object({
+        title: z.string().optional(),
+        description: z.string().min(1, 'Template description is required'),
+        tags: z.array(z.string()).optional(),
+        type: z.enum(['presentation', 'document']),
+    })
+    .strict();
+
+type TemplateFrontmatter = z.infer<typeof TemplateFrontmatterSchema>;
+
+/**
+ * MUST be kept in sync with @vertesia/tools-sdk RenderingTemplateDefinition
+ * Zod schema for template definition
+ */
+export const RenderingTemplateDefinitionSchema = z
+    .object({
+        id: z.string().min(1, 'Template id is required'),
+        name: z.string().min(1, 'Template name is required'),
+        title: z.string().optional(),
+        description: z.string().min(1, 'Template description is required'),
+        instructions: z.string(),
+        tags: z.array(z.string()).optional(),
+        type: z.enum(['presentation', 'document']),
+        assets: z.array(z.string()),
+    })
+    .passthrough();
+
+/**
+ * TypeScript type inferred from the Zod schema
+ */
+export type RenderingTemplateDefinition = z.infer<typeof RenderingTemplateDefinitionSchema>;
+
+/**
+ * Derive the template path segments from the file path.
+ *
+ * Example: .../templates/examples/report/TEMPLATE.md
+ *   → category: "examples", name: "report", relative: "examples/report"
+ */
+function deriveTemplatePathInfo(filePath: string): { category: string; templateName: string; relative: string } {
+    const templateDir = path.dirname(filePath);
+    const templateName = path.basename(templateDir);
+    const collectionDir = path.dirname(templateDir);
+    const category = path.basename(collectionDir);
+    return { category, templateName, relative: `${category}/${templateName}` };
+}
+
+/**
+ * Template transformer preset
+ * Transforms markdown files with ?template suffix OR TEMPLATE.md files into template definition objects
+ *
+ * Matches:
+ * - Files with ?template suffix: ./my-template.md?template
+ * - TEMPLATE.md files: ./my-template/TEMPLATE.md
+ *
+ * @example
+ * ```typescript
+ * import template1 from './my-template.md?template';
+ * import template2 from './my-template/TEMPLATE.md';
+ * // Both are RenderingTemplateDefinition objects
+ * ```
+ */
+export const templateTransformer: TransformerPreset = {
+    pattern: /(\.md\?template$|\/TEMPLATE\.md$)/,
+    schema: RenderingTemplateDefinitionSchema,
+    transform: (content: string, filePath: string) => {
+        const { frontmatter, content: markdown } = parseFrontmatter(content);
+
+        // Validate frontmatter
+        const frontmatterValidation = TemplateFrontmatterSchema.safeParse(frontmatter);
+        if (!frontmatterValidation.success) {
+            const errors = frontmatterValidation.error.issues
+                .map((err) => {
+                    const pathStr = err.path.length > 0 ? err.path.join('.') : 'frontmatter';
+                    return `  - ${pathStr}: ${err.message}`;
+                })
+                .join('\n');
+            throw new Error(`Invalid frontmatter in ${filePath}:\n${errors}`);
+        }
+        const validatedFrontmatter: TemplateFrontmatter = frontmatterValidation.data;
+
+        // Derive template path from directory structure
+        const { category, templateName, relative: templatePath } = deriveTemplatePathInfo(filePath);
+
+        // Discover asset files in the template directory
+        const assets = discoverTemplateAssets(filePath, templatePath);
+
+        // Build template definition
+        // Assets use absolute paths for direct server-side resolution
+        const templateData: RenderingTemplateDefinition = {
+            id: `${category}:${templateName}`,
+            name: templateName,
+            title: validatedFrontmatter.title,
+            description: validatedFrontmatter.description,
+            instructions: markdown,
+            tags: validatedFrontmatter.tags,
+            type: validatedFrontmatter.type,
+            assets: assets.fileNames.map((f) => `/templates/${templatePath}/${f}`),
+        };
+
+        return {
+            data: templateData,
+            assets: assets.assetFiles,
+        };
+    },
+};

package/src/core/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Type definitions shared across the Vertesia build-tools pipeline:
+ * transformers, transformer results, and asset metadata produced by them.
+ */
+
+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' | 'template';
+}
+
+/**
+ * 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<unknown>;
+
+    /** Optional: If true, the transformer generates virtual modules (no file to read) */
+    virtual?: boolean;
+
+    /** Optional: additional options for this transformer */
+    options?: Record<string, unknown>;
+}
+
+/**
+ * Type for transformer presets — alias for `TransformerRule` used by the
+ * built-in preset modules (skill, raw, prompt, template, …).
+ */
+export type TransformerPreset = TransformerRule;

package/src/{utils → core/utils}/asset-copy.ts

@@ -38,8 +38,9 @@ export function copyAssetFile(asset: AssetFile, assetsRoot: string): void {
         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)
-            }`
+            `Failed to copy asset from ${asset.sourcePath} to ${destPath}: ${
+                error instanceof Error ? error.message : String(error)
+            }`,
         );
     }
 }

package/src/{utils → core/utils}/asset-discovery.ts

@@ -50,7 +50,7 @@ function isFile(filePath: string): boolean {
  */
 function getFilesInDirectory(dirPath: string): string[] {
     try {
-        return readdirSync(dirPath).filter(file => {
+        return readdirSync(dirPath).filter((file) => {
             const fullPath = path.join(dirPath, file);
             return isFile(fullPath);
         });
@@ -92,7 +92,7 @@ export function discoverSkillAssets(
     options: {
         scriptsDir?: string;
         widgetsDir?: string;
-    } = {}
+    } = {},
 ): DiscoveredAssets {
     const skillDir = path.dirname(skillFilePath);
     const files = getFilesInDirectory(skillDir);
@@ -113,7 +113,7 @@ export function discoverSkillAssets(
             assetFiles.push({
                 sourcePath: fullPath,
                 destPath: path.join(scriptsDir, file),
-                type: 'script'
+                type: 'script',
             });
         } else if (isWidgetFile(file)) {
             // Widget file (.tsx)
@@ -121,7 +121,7 @@ export function discoverSkillAssets(
             widgets.push(widgetName);
             widgetMetadata.push({
                 name: widgetName,
-                path: fullPath
+                path: fullPath,
             });
 
             // Note: We don't add widget .tsx files to assetFiles
@@ -133,6 +133,6 @@ export function discoverSkillAssets(
         scripts,
         widgets,
         widgetMetadata,
-        assetFiles
+        assetFiles,
     };
 }

package/src/{utils → core/utils}/template-asset-discovery.ts

@@ -1,77 +1,70 @@
-/**
- * Utilities for discovering asset files in template directories
- */
-
-import { readdirSync, statSync } from 'node:fs';
-import path from 'node:path';
-import type { AssetFile } from '../types.js';
-
-/**
- * Discovered assets in a template directory
- */
-export interface DiscoveredTemplateAssets {
-    /** Asset file names (relative to template dir) */
-    fileNames: string[];
-
-    /** Asset files to be copied */
-    assetFiles: AssetFile[];
-}
-
-/**
- * Files to exclude from template asset discovery
- * (source files and the template definition itself)
- */
-const EXCLUDED_PATTERNS = [
-    /^TEMPLATE\.md$/,
-    /\.ts$/,
-    /\.js$/,
-];
-
-function isExcluded(fileName: string): boolean {
-    return EXCLUDED_PATTERNS.some(p => p.test(fileName));
-}
-
-/**
- * Discover asset files in a template directory.
- * All files except TEMPLATE.md, *.ts, and *.js are considered assets.
- *
- * @param templateFilePath - Absolute path to the TEMPLATE.md file
- * @param templatePath - The template path segment (e.g., "examples/report")
- * @returns Discovered assets and metadata
- */
-export function discoverTemplateAssets(
-    templateFilePath: string,
-    templatePath: string,
-): DiscoveredTemplateAssets {
-    const templateDir = path.dirname(templateFilePath);
-    const fileNames: string[] = [];
-    const assetFiles: AssetFile[] = [];
-
-    let files: string[];
-    try {
-        files = readdirSync(templateDir).filter(file => {
-            try {
-                return statSync(path.join(templateDir, file)).isFile();
-            } catch {
-                return false;
-            }
-        });
-    } catch {
-        files = [];
-    }
-
-    for (const file of files) {
-        if (isExcluded(file)) {
-            continue;
-        }
-
-        fileNames.push(file);
-        assetFiles.push({
-            sourcePath: path.join(templateDir, file),
-            destPath: path.join('templates', templatePath, file),
-            type: 'template',
-        });
-    }
-
-    return { fileNames, assetFiles };
-}
+/**
+ * Utilities for discovering asset files in template directories
+ */
+
+import { readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import type { AssetFile } from '../types.js';
+
+/**
+ * Discovered assets in a template directory
+ */
+export interface DiscoveredTemplateAssets {
+    /** Asset file names (relative to template dir) */
+    fileNames: string[];
+
+    /** Asset files to be copied */
+    assetFiles: AssetFile[];
+}
+
+/**
+ * Files to exclude from template asset discovery
+ * (source files and the template definition itself)
+ */
+const EXCLUDED_PATTERNS = [/^TEMPLATE\.md$/, /\.ts$/, /\.js$/];
+
+function isExcluded(fileName: string): boolean {
+    return EXCLUDED_PATTERNS.some((p) => p.test(fileName));
+}
+
+/**
+ * Discover asset files in a template directory.
+ * All files except TEMPLATE.md, *.ts, and *.js are considered assets.
+ *
+ * @param templateFilePath - Absolute path to the TEMPLATE.md file
+ * @param templatePath - The template path segment (e.g., "examples/report")
+ * @returns Discovered assets and metadata
+ */
+export function discoverTemplateAssets(templateFilePath: string, templatePath: string): DiscoveredTemplateAssets {
+    const templateDir = path.dirname(templateFilePath);
+    const fileNames: string[] = [];
+    const assetFiles: AssetFile[] = [];
+
+    let files: string[];
+    try {
+        files = readdirSync(templateDir).filter((file) => {
+            try {
+                return statSync(path.join(templateDir, file)).isFile();
+            } catch {
+                return false;
+            }
+        });
+    } catch {
+        files = [];
+    }
+
+    for (const file of files) {
+        if (isExcluded(file)) {
+            continue;
+        }
+
+        fileNames.push(file);
+        assetFiles.push({
+            sourcePath: path.join(templateDir, file),
+            destPath: path.join('templates', templatePath, file),
+            type: 'template',
+        });
+    }
+
+    return { fileNames, assetFiles };
+}

package/src/import-transform/builtins.ts

@@ -0,0 +1,56 @@
+/**
+ * CLI-friendly name registry for the built-in transformers.
+ *
+ * Names mirror the query-suffix convention used in source code:
+ *   `?skill`   → 'skill'
+ *   `?skills`  → 'skills'         (collection)
+ *   `?template`→ 'template'
+ *   `?templates`→ 'templates'     (collection)
+ *   `?prompt`  → 'prompt'
+ *   `?raw`     → 'raw'
+ */
+
+import { promptTransformer } from '../core/transformers/prompt.js';
+import { rawTransformer } from '../core/transformers/raw.js';
+import { skillTransformer } from '../core/transformers/skill.js';
+import { skillCollectionTransformer } from '../core/transformers/skill-collection.js';
+import { templateTransformer } from '../core/transformers/template.js';
+import { templateCollectionTransformer } from '../core/transformers/template-collection.js';
+import type { TransformerRule } from '../core/types.js';
+
+export const BUILTIN_TRANSFORMERS: Readonly<Record<string, TransformerRule>> = Object.freeze({
+    skill: skillTransformer,
+    skills: skillCollectionTransformer,
+    template: templateTransformer,
+    templates: templateCollectionTransformer,
+    prompt: promptTransformer,
+    raw: rawTransformer,
+});
+
+/** Names of all registered transformers, in stable order. */
+export const BUILTIN_TRANSFORMER_NAMES: readonly string[] = Object.freeze(Object.keys(BUILTIN_TRANSFORMERS));
+
+/**
+ * Resolve a list of transformer names to their concrete `TransformerRule`
+ * instances. Throws if any name is unknown.
+ */
+export function resolveTransformerNames(names: readonly string[]): TransformerRule[] {
+    const resolved: TransformerRule[] = [];
+    const unknown: string[] = [];
+
+    for (const name of names) {
+        const rule = BUILTIN_TRANSFORMERS[name];
+        if (rule) {
+            resolved.push(rule);
+        } else {
+            unknown.push(name);
+        }
+    }
+
+    if (unknown.length > 0) {
+        const known = BUILTIN_TRANSFORMER_NAMES.join(', ');
+        throw new Error(`Unknown transformer name(s): ${unknown.join(', ')}. Known transformers: ${known}.`);
+    }
+
+    return resolved;
+}

package/src/import-transform/chunk-emitter.ts

@@ -0,0 +1,60 @@
+/**
+ * Runs a transformer against a source file and writes the resulting module
+ * as a standalone `.js` chunk inside the lib output.
+ *
+ * The generated module mirrors the historical code produced by the legacy
+ * rollup `load()` hook — it supports `imports`, `code`, and default
+ * `export default <data>` payloads — so the runtime behavior of
+ * import-transformed builds matches the legacy rollup-based pipeline
+ * byte-for-byte.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import type { AssetFile, TransformerRule } from '../core/types.js';
+import type { WidgetMetadata } from '../core/utils/asset-discovery.js';
+
+export interface EmittedChunk {
+    /** Absolute path of the written chunk. */
+    chunkPath: string;
+
+    /** Generated module source (the same bytes written to `chunkPath`). */
+    content: string;
+
+    /** Assets returned by the transformer that should be copied. */
+    assets: AssetFile[];
+
+    /** Widget entries returned by the transformer that should be bundled. */
+    widgets: WidgetMetadata[];
+}
+
+export async function emitChunk(
+    srcPath: string,
+    chunkPath: string,
+    transformer: TransformerRule,
+): Promise<EmittedChunk> {
+    const content = transformer.virtual ? '' : readFileSync(srcPath, 'utf-8');
+    const result = await transformer.transform(content, srcPath);
+
+    if (transformer.schema) {
+        const validation = transformer.schema.safeParse(result.data);
+        if (!validation.success) {
+            const errors = validation.error.issues.map((err) => `  - ${err.path.join('.')}: ${err.message}`).join('\n');
+            throw new Error(`Validation failed for ${srcPath}:\n${errors}`);
+        }
+    }
+
+    const importsBlock = result.imports && result.imports.length > 0 ? `${result.imports.join('\n')}\n\n` : '';
+    const body = result.code ?? `export default ${JSON.stringify(result.data, null, 2)};`;
+    const moduleCode = importsBlock + body;
+
+    mkdirSync(path.dirname(chunkPath), { recursive: true });
+    writeFileSync(chunkPath, moduleCode, 'utf-8');
+
+    return {
+        chunkPath,
+        content: moduleCode,
+        assets: result.assets ?? [],
+        widgets: result.widgets ?? [],
+    };
+}