@postxl/generator 0.74.1 → 1.0.1

package/dist/utils/sync.js

@@ -0,0 +1,325 @@
+"use strict";
+/**
+ * The virtual file system represents a file system that can be manipulated in memory.
+ *
+ * This sync extension allows a 3-way sync between the file system and the disk.
+ *
+ * The 3 sources are:
+ * 1. The data written by code/the generators to the VFS
+ * 2. The hash sums from prior generations (indicating which files were changed)
+ * 3. The actual disk files
+ *
+ * The overall usage pattern is:
+ * 1. The VFS initializes with a lock file - and reads the hash sums from the disk
+ * 2. The code/generators write to the VFS
+ * 3. The VFS "writes" to disk, performing this 3-way sync with the below algorithm
+ *
+ *
+ * ### Algorithm
+ *
+ * For each file in the VFS we have 3 different states - the file in memory (`virtual`), the hash sum from prior generations from the lock file (`lock`), and the file from disk (`disk`).
+ *
+ * Each of these 3 states can be "empty" - in case the file was not generated/generated last time/does not exist on disk - or represented by a hash value (`H`).
+ *
+ * Thus, we have the following potential states for each file:
+ * - virtual: `empty` | `Hash1` (hash sum from current generation)
+ * - lock:    `empty` | `Hash1` | `Hash0` (hash sum from prior generation)
+ * - disk:    `empty` | `Hash1` | `Hash0` | `HashX` (different hash sum from disk)
+ *
+ * The below table shows all possible combinations of these states - and the resulting action that needs to be performed:
+ *
+ * |-------|-------|---------|---------------------------------|---------------------------|
+ * | VFS   | Lock  | Disk    | Description                     | Action on disk            |
+ * |-------|-------|---------|---------------------------------|---------------------------|
+ * | Hash1 | Hash1 | Hash1   | Unchanged                       | No action                 |
+ * | Hash1 | Hash1 | HashX/0 | Ejected                         | No action                 |
+ * | Hash1 | Hash1 | empty   | Deleted on disk                 | No action                 |
+ * | Hash1 | Hash0 | Hash1   | Corrupt lock file?              | No action                 |
+ * | Hash1 | Hash0 | Hash0   | Changed, not ejected            | Update to VFS version     |
+ * | Hash1 | Hash0 | HashX   | Changed, ejected                | Create "merge conflict"(2)|
+ * | Hash1 | Hash0 | empty   | Changed, deleted on disk        | Write file (1)            |
+ * | Hash1 | empty | Hash1   | Corrupt lock file?              | No action                 |
+ * | Hash1 | empty | HashX/0 | File ejected, corrupt lock file | Create "merge conflict"(2)|
+ * | Hash1 | empty | empty   | Newly generated                 | Write file                |
+ * |-------|-------|---------|---------------------------------|---------------------------|
+ * | empty | Hash0 | Hash0   | Unejected file                  | Delete file               |
+ * | empty | Hash0 | HashX   | Ejected file was deleted        | Delete file (3)           |
+ * | empty | Hash0 | empty   | File was manually deleted first | No action                 |
+ * | empty | empty | HashX   | Manual file                     | No action                 |
+ * | empty | empty | empty   | Cannot occur                    |                           |
+ * |-------|-------|---------|---------------------------------|---------------------------|
+ *
+ * Notes:
+ * (1) In case the file was deleted on disk and changed between the last generation and the current generation, we will write the file to disk. The developer can decide to keep the "restored" file or not. Next time generator runs, it will not be regenerated, as lock file hashes match.
+ * (2) In case the file was ejected and changed between the last generation and the current generation, we will overwrite the file on disk - with git "merge conflict" markers. The developer must then decide how to resolve the conflicts.
+ * (3) In case the file was deleted by the generator but ejected by the developer, we will delete the file from disk. The developer can decide to revert the deletion or not. Next time generator runs, it will not be regenerated, as lock file hashes match.
+ *
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sync = sync;
+exports.executeAction = executeAction;
+const promises_1 = __importDefault(require("fs/promises"));
+const p_limit_1 = __importDefault(require("p-limit"));
+const utils_1 = require("@postxl/utils");
+const checksum_1 = require("./checksum");
+const fs_utils_1 = require("./fs-utils");
+const lockfile_1 = require("./lockfile");
+const merge_conflict_1 = require("./merge-conflict");
+const Path = __importStar(require("./path"));
+/**
+ * Synchronizes the virtual file system with the disk file system.
+ *
+ * It takes into account the lock file to determine the state of each file.
+ * Depending on the state/checksum of each file in VFS, lock file and disk file system,
+ * it will perform the appropriate action (write, delete, merge conflict) to update the disk file system.
+ *
+ * It also updates the lock file with the current state of the VFS.
+ *
+ * Note: File filtering is now handled at the VFS level, so only files that were added to the VFS
+ * (respecting any file pattern filter) will be synced and tracked in the lock file.
+ *
+ * IMPORTANT: Before writing any files, this function checks if there are any files with unresolved
+ * merge conflict markers. If found, the sync will abort immediately and return an error with the
+ * list of files that need to be resolved before generation can continue.
+ */
+async function sync({ vfs, lockFilePath, diskFilePath, force }) {
+    const diskPathNormalized = Path.normalize(diskFilePath);
+    const files = await getFilesStates({ vfs, lockFilePath, diskFilePath });
+    // Check for unresolved merge conflicts before writing any files
+    const filesWithConflicts = findFilesWithMergeConflicts(files);
+    if (filesWithConflicts.length > 0) {
+        return {
+            success: false,
+            error: {
+                type: 'UnresolvedMergeConflictsError',
+                message: `Cannot proceed with generation: ${filesWithConflicts.length} file(s) contain unresolved merge conflicts. Please resolve these conflicts before running the generator again.`,
+                filesWithConflicts,
+            },
+        };
+    }
+    const limit = (0, p_limit_1.default)(50);
+    const tasks = [];
+    const result = {
+        errors: [],
+        files: {},
+    };
+    for (const [filePath, inputState] of files) {
+        const [action, isEjected] = determineActionState(inputState, force);
+        const task = limit(async () => {
+            const actionResult = await executeAction(Path.join(diskPathNormalized, filePath), action);
+            if (actionResult.isErr()) {
+                result.errors.push(actionResult.unwrapErr());
+            }
+            result.files[filePath] = { action, inputState, actionResult, isEjected };
+        });
+        tasks.push(task);
+    }
+    tasks.push(limit(() => (0, lockfile_1.writeLockFile)(lockFilePath, vfs)));
+    await Promise.all(tasks);
+    return { success: true, ...result };
+}
+/**
+ * Finds all files in the disk that contain unresolved merge conflict markers.
+ *
+ * @param files - The files states map from getFilesStates
+ * @returns Array of file paths that contain merge conflict markers
+ */
+function findFilesWithMergeConflicts(files) {
+    const filesWithConflicts = [];
+    for (const [filePath, { disk }] of files) {
+        if (disk.state === 'hash' && (0, merge_conflict_1.hasMergeConflictMarkers)(disk.content)) {
+            filesWithConflicts.push(filePath);
+        }
+    }
+    return filesWithConflicts;
+}
+function getChecksum(file) {
+    switch (file.state) {
+        case 'hash':
+            return file.hash;
+        case 'empty':
+            return undefined;
+        default:
+            throw new utils_1.ExhaustiveSwitchCheck(file);
+    }
+}
+function getStateKey({ virtual, lock, disk }) {
+    const stateKey_Virtual = virtual.state === 'hash' ? 'V:Hash1' : 'V:empty';
+    const H1 = getChecksum(virtual);
+    const stateKey_Lock = getStateKey_Lock({ lock, H1 });
+    const Hash0 = getChecksum(lock);
+    const stateKey_Disk = getStateKey_Disk({ disk, H1, Hash0 });
+    return `${stateKey_Virtual}-${stateKey_Lock}-${stateKey_Disk}`;
+}
+function getStateKey_Lock({ lock, H1 }) {
+    if (lock.state === 'empty') {
+        return 'L:empty';
+    }
+    if (H1 === undefined) {
+        return 'L:Hash0';
+    }
+    if (lock.hash === H1) {
+        return 'L:Hash1';
+    }
+    return 'L:Hash0';
+}
+function getStateKey_Disk({ disk, H1, Hash0, }) {
+    if (disk.state === 'empty') {
+        return 'D:empty';
+    }
+    if (H1 !== undefined && disk.hash === H1) {
+        return 'D:Hash1';
+    }
+    if (Hash0 !== undefined && disk.hash === Hash0) {
+        return 'D:Hash0';
+    }
+    return 'D:HashX';
+}
+async function getDiskFileState(diskFilePath) {
+    if (await promises_1.default.stat(diskFilePath).catch(() => null)) {
+        const result = await (0, fs_utils_1.readFile)(diskFilePath);
+        if (result.isErr()) {
+            return { state: 'empty' };
+        }
+        const content = result.unwrap();
+        const checksum = await (0, checksum_1.calculateChecksum)(content);
+        return { state: 'hash', hash: checksum, content: content };
+    }
+    return { state: 'empty' };
+}
+async function getFilesStates({ vfs, lockFilePath, diskFilePath, }) {
+    const lockFile = await (0, lockfile_1.readLockFile)(lockFilePath);
+    const files = new Map();
+    const diskPathNormalized = Path.normalize(diskFilePath);
+    // We first add all files from the virtual file system.
+    for (const [filePath, content] of vfs.files) {
+        const virtual = { state: 'hash', hash: await (0, checksum_1.calculateChecksum)(content), content };
+        const path = filePath;
+        const lock = lockFile?.has(path) ? { state: 'hash', hash: lockFile.get(path) } : { state: 'empty' };
+        const disk = await getDiskFileState(Path.join(diskPathNormalized, path));
+        files.set(path, { virtual, lock, disk });
+    }
+    // Then we add all files from the lock file (as the last generator run might not have created all old files).
+    // However, if the VFS has a file pattern filter, we should only consider lock file entries that match the pattern.
+    if (lockFile) {
+        const virtual = { state: 'empty' };
+        for (const [filePath, content] of lockFile) {
+            if (files.has(filePath)) {
+                continue;
+            }
+            // Skip files that don't match the VFS pattern filter (if one is set)
+            if (!vfs.matchesPattern(filePath)) {
+                continue;
+            }
+            const lock = { state: 'hash', hash: content };
+            const disk = await getDiskFileState(Path.join(diskPathNormalized, filePath));
+            files.set(filePath, { virtual, lock, disk });
+        }
+    }
+    return files;
+}
+const actionMap = {
+    // No change between current and last generator run:
+    'V:Hash1-L:Hash1-D:HashX': ['NoAction', true, 'Write'], // Ejected
+    'V:Hash1-L:Hash1-D:Hash1': ['NoAction', false, 'NoAction'], // Unchanged
+    'V:Hash1-L:Hash1-D:Hash0': ['NoAction', true, 'Write'], // Should not occur, but can be considered as ejected
+    'V:Hash1-L:Hash1-D:empty': ['NoAction', true, 'Write'], // Deleted on disk, we want to keep it this way
+    // Change between current and last generator run:
+    'V:Hash1-L:Hash0-D:HashX': ['MergeConflict', true, 'Write'], // File ejected (In case the file was ejected and changed between the last generation and the current generation, we will overwrite the file on disk - with git "merge conflict" markers. The developer must then decide how to resolve the conflicts.)
+    'V:Hash1-L:Hash0-D:Hash1': ['NoAction', false, 'NoAction'], // Should not occur, corrupt lock file?
+    'V:Hash1-L:Hash0-D:Hash0': ['Write', false, 'Write'], // Changed, not ejected
+    'V:Hash1-L:Hash0-D:empty': ['Write', true, 'Write'], // Changed, deleted on disk -> overwrite (in case the file was deleted on disk and changed between the last generation and the current generation, we will write the file to disk. The developer can decide to keep the "restored" file or not. Next time generator runs, it will not be regenerated, as lock file hashes match.)
+    // Newly generated, did not exist before:
+    'V:Hash1-L:empty-D:HashX': ['MergeConflict', true, 'Write'], // File ejected or was created manually (In case the file was ejected and changed between the last generation and the current generation, we will overwrite the file on disk - with git "merge conflict" markers. The developer must then decide how to resolve the conflicts.)
+    'V:Hash1-L:empty-D:Hash1': ['NoAction', false, 'NoAction'], // File was manually created first
+    'V:Hash1-L:empty-D:Hash0': ['NoAction', true, 'Write'], // Cannot occur, but kept for type completeness
+    'V:Hash1-L:empty-D:empty': ['Write', false, 'Write'], // Newly generated file
+    // Generator did not create the file:
+    'V:empty-L:Hash1-D:HashX': ['NoAction', false, 'NoAction'], // Cannot occur, but kept for type completeness
+    'V:empty-L:Hash1-D:Hash1': ['NoAction', false, 'NoAction'], // Cannot occur, but kept for type completeness
+    'V:empty-L:Hash1-D:Hash0': ['NoAction', false, 'NoAction'], // Cannot occur, but kept for type completeness
+    'V:empty-L:Hash1-D:empty': ['NoAction', false, 'NoAction'], // Cannot occur, but kept for type completeness
+    'V:empty-L:Hash0-D:HashX': ['Delete', true, 'Delete'], // Ejected file was deleted -> delete (in case the file was deleted by the generator but ejected by the developer, we will delete the file from disk. The developer can decide to revert the deletion or not. Next time generator runs, it will not be regenerated, as lock file hashes match.)
+    'V:empty-L:Hash0-D:Hash1': ['Delete', true, 'Delete'], // Indistinguishable from "empty-Hash0-HashX"
+    'V:empty-L:Hash0-D:Hash0': ['Delete', false, 'Delete'], // Unejected file
+    'V:empty-L:Hash0-D:empty': ['NoAction', false, 'NoAction'], // File was manually deleted first
+    'V:empty-L:empty-D:HashX': ['NoAction', false, 'NoAction'], // Manual file
+    'V:empty-L:empty-D:Hash1': ['NoAction', false, 'NoAction'], // Indistinguishable from "empty-empty-HashX"
+    'V:empty-L:empty-D:Hash0': ['NoAction', false, 'NoAction'], // Indistinguishable from "empty-empty-HashX"
+    'V:empty-L:empty-D:empty': ['NoAction', false, 'NoAction'], // Cannot occur
+};
+function determineActionState({ virtual, lock, disk }, force) {
+    const stateKey = getStateKey({ virtual, lock, disk });
+    const [defaultActionType, isEjected, forceActionType] = actionMap[stateKey];
+    const actionType = force ? forceActionType : defaultActionType;
+    if (actionType === 'Write') {
+        if (virtual.state === 'empty') {
+            throw new Error(`This should not happen assuming that the actionMap only has 'Write' actions for entries starting with Hash1, ie a defined virtual file`);
+        }
+        return [{ type: 'Write', content: virtual.content }, isEjected];
+    }
+    else if (actionType === 'MergeConflict') {
+        if (disk.state === 'empty') {
+            throw new Error(`This should not happen assuming that the actionMap only has 'Write' actions for entries starting with H1, ie a defined virtual file`);
+        }
+        if (virtual.state === 'empty') {
+            throw new Error(`This should not happen assuming that the actionMap only has 'Write' actions for entries starting with H1, ie a defined virtual file`);
+        }
+        return [{ type: 'MergeConflict', diskContent: disk.content, virtualContent: virtual.content }, isEjected];
+    }
+    return [{ type: actionType }, isEjected];
+}
+async function executeAction(filePath, action) {
+    switch (action.type) {
+        case 'NoAction':
+            return utils_1.Result.ok(undefined);
+        case 'Write':
+            return (0, fs_utils_1.writeFile)(filePath, action.content);
+        case 'MergeConflict':
+            return writeMergeConflictFile(filePath, action);
+        case 'Delete':
+            return (0, fs_utils_1.deleteFile)(filePath);
+        default:
+            throw new utils_1.ExhaustiveSwitchCheck(action);
+    }
+}
+async function writeMergeConflictFile(filePath, { diskContent, virtualContent }) {
+    const content = (0, merge_conflict_1.generateMergeConflict)({ contentSource: diskContent, contentIncoming: virtualContent });
+    return (0, fs_utils_1.writeFile)(filePath, content);
+}

package/dist/utils/template.d.ts

@@ -0,0 +1,66 @@
+import { Result } from '@postxl/utils';
+/**
+ * Error thrown when a template variable is not found in the context.
+ */
+export declare class TemplateVariableError extends Error {
+    readonly variablePath: string;
+    readonly availableKeys: string[];
+    constructor(variablePath: string, availableKeys: string[]);
+}
+export type RenderTemplateOptions = {
+    /**
+     * If true, undefined variables will be replaced with an empty string.
+     * If false (default), an error will be thrown for undefined variables.
+     */
+    allowUndefined?: boolean;
+};
+/**
+ * Renders a template string by replacing `<%expression%>` placeholders with values from the context.
+ *
+ * The expression supports dot notation for accessing nested properties.
+ *
+ * @example
+ * renderTemplate('Hello <%name%>!', { name: 'World' })
+ * // returns 'Hello World!'
+ *
+ * @example
+ * renderTemplate('Project: <%schema.slug%>', { schema: { slug: 'demo' } })
+ * // returns 'Project: demo'
+ *
+ * @param template - The template string containing `<%expression%>` placeholders
+ * @param context - The context object containing values to substitute
+ * @param options - Optional configuration
+ * @returns The rendered string with all placeholders replaced
+ * @throws {TemplateVariableError} If a variable is not found and allowUndefined is false
+ */
+export declare function renderTemplate(template: string, context: Record<string, unknown>, options?: RenderTemplateOptions): string;
+type ReadTemplateError = {
+    type: 'ReadTemplateError';
+    message: string;
+    error: Error;
+};
+/**
+ * Reads a template file from disk and renders it with the given context.
+ *
+ * This is a convenience function for loading static template files and
+ * replacing placeholders in a single operation.
+ *
+ * @example
+ * // In a generator:
+ * const content = await generateFromTemplate({
+ *   file: path.resolve(__dirname, './template/scripts/docker.sh'),
+ *   context: { schema: context.schema }
+ * })
+ * vfs.write('/scripts/docker.sh', content)
+ *
+ * @param params.file - Absolute path to the template file on disk
+ * @param params.context - The context object containing values to substitute
+ * @param params.options - Optional render options
+ * @returns The rendered template content
+ */
+export declare function generateFromTemplate({ file, context, options, }: {
+    file: string;
+    context: Record<string, unknown>;
+    options?: RenderTemplateOptions;
+}): Promise<Result<string, ReadTemplateError>>;
+export {};

package/dist/utils/template.js

@@ -0,0 +1,159 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateVariableError = void 0;
+exports.renderTemplate = renderTemplate;
+exports.generateFromTemplate = generateFromTemplate;
+const fs = __importStar(require("node:fs/promises"));
+const utils_1 = require("@postxl/utils");
+const Path = __importStar(require("./path"));
+/**
+ * Template delimiter configuration.
+ * Uses ERB-style `<%...%>` syntax which doesn't interfere with:
+ * - TypeScript/JavaScript template literals (`${...}`)
+ * - JSX/TSX syntax
+ * - Markdown syntax
+ * - Bash variables (`$VAR`, `${VAR}`)
+ * - Bash conditionals (`[[ ... ]]`)
+ */
+const TEMPLATE_REGEX = /<%\s*([^%]+?)\s*%>/g;
+/**
+ * Gets a nested property value from an object using dot notation.
+ *
+ * @example
+ * getNestedValue({ schema: { slug: 'demo' } }, 'schema.slug') // returns 'demo'
+ * getNestedValue({ name: 'test' }, 'name') // returns 'test'
+ */
+function getNestedValue(obj, path) {
+    const keys = path.split('.');
+    let current = obj;
+    for (const key of keys) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Error thrown when a template variable is not found in the context.
+ */
+class TemplateVariableError extends Error {
+    variablePath;
+    availableKeys;
+    constructor(variablePath, availableKeys) {
+        super(`Template variable "<%${variablePath}%>" not found in context. Available top-level keys: ${availableKeys.join(', ')}`);
+        this.variablePath = variablePath;
+        this.availableKeys = availableKeys;
+        this.name = 'TemplateVariableError';
+    }
+}
+exports.TemplateVariableError = TemplateVariableError;
+/**
+ * Renders a template string by replacing `<%expression%>` placeholders with values from the context.
+ *
+ * The expression supports dot notation for accessing nested properties.
+ *
+ * @example
+ * renderTemplate('Hello <%name%>!', { name: 'World' })
+ * // returns 'Hello World!'
+ *
+ * @example
+ * renderTemplate('Project: <%schema.slug%>', { schema: { slug: 'demo' } })
+ * // returns 'Project: demo'
+ *
+ * @param template - The template string containing `<%expression%>` placeholders
+ * @param context - The context object containing values to substitute
+ * @param options - Optional configuration
+ * @returns The rendered string with all placeholders replaced
+ * @throws {TemplateVariableError} If a variable is not found and allowUndefined is false
+ */
+function renderTemplate(template, context, options = {}) {
+    const { allowUndefined = false } = options;
+    return template.replaceAll(TEMPLATE_REGEX, (_match, expression) => {
+        const trimmedExpr = expression.trim();
+        const value = getNestedValue(context, trimmedExpr);
+        if (value === undefined) {
+            if (allowUndefined) {
+                return '';
+            }
+            throw new TemplateVariableError(trimmedExpr, Object.keys(context));
+        }
+        // Convert value to string
+        if (typeof value === 'string') {
+            return value;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return String(value);
+        }
+        // For objects/arrays, stringify them
+        return JSON.stringify(value);
+    });
+}
+/**
+ * Reads a template file from disk and renders it with the given context.
+ *
+ * This is a convenience function for loading static template files and
+ * replacing placeholders in a single operation.
+ *
+ * @example
+ * // In a generator:
+ * const content = await generateFromTemplate({
+ *   file: path.resolve(__dirname, './template/scripts/docker.sh'),
+ *   context: { schema: context.schema }
+ * })
+ * vfs.write('/scripts/docker.sh', content)
+ *
+ * @param params.file - Absolute path to the template file on disk
+ * @param params.context - The context object containing values to substitute
+ * @param params.options - Optional render options
+ * @returns The rendered template content
+ */
+async function generateFromTemplate({ file, context, options, }) {
+    const normalizedPath = Path.normalize(file);
+    const result = await utils_1.Result.fromPromise(() => fs.readFile(normalizedPath, { encoding: 'utf-8' }), (error) => ({
+        type: 'ReadTemplateError',
+        message: `Error reading template file "${file}"`,
+        error: error,
+    }));
+    if (result.isErr()) {
+        return result;
+    }
+    const rendered = renderTemplate(result.unwrap(), context, options);
+    return utils_1.Result.ok(rendered);
+}

package/dist/utils/vfs.class.d.ts

@@ -0,0 +1,115 @@
+import { FileContent } from './fs-utils';
+import * as Path from './path';
+/**
+ * Options for configuring the VirtualFileSystem.
+ */
+export type VFSOptions = {
+    /**
+     * Optional glob pattern to filter files.
+     * Examples: `**\/*.ts` or `backend/libs/**`
+     * When specified, only files matching this pattern will be stored in the VFS.
+     */
+    filePattern?: string;
+};
+/**
+ * The virtual file system (VFS) represents a file system that can be manipulated in memory.
+ *
+ * It exposes the following methods:
+ * - `write(path, content)`: Writes the given content to the given path
+ * - `read(path)`: Reads the content of the given path
+ * - `insertFromVfs(path, vfs)`: Inserts the content of the given VFS into the current VFS
+ * - `insertFromDisk(path, disk)`: Inserts the content of the given disk into the current VFS
+ * - `transform(fn, filter?)`: Transforms the content of all files in the VFS using the given function
+ *
+ * ## Implementation details
+ *
+ * All paths are relative to the root of the VFS - and are normalized to use the POSIX path separator.
+ * For this we use the `path` utils (path.normalize, path.join, path.parse). All paths are represented
+ * as branded strings (`Path.PosixPath`).
+ *
+ * The file content can either be a (UTF8) string or a Buffer.
+ *
+ * ## File Pattern Filtering
+ *
+ * The VFS can be configured with an optional file pattern filter during construction.
+ * When a pattern is set, only files matching the pattern will be stored in the VFS.
+ * This optimization ensures that linting, formatting, and lock file updates only affect
+ * the filtered files, significantly improving performance.
+ */
+export declare class VirtualFileSystem {
+    #private;
+    /**
+     * Constructs a new VirtualFileSystem.
+     *
+     * @param options - Optional configuration options for the VFS.
+     */
+    constructor(options?: VFSOptions);
+    /**
+     * Returns all file names in the VFS.
+     */
+    get fileNames(): Path.PosixPath[];
+    /**
+     * Returns all files in the VFS.
+     */
+    get files(): Map<Path.PosixPath | string, FileContent>;
+    /**
+     * Returns the file pattern filter if one is set.
+     */
+    get filePattern(): string | undefined;
+    /**
+     * Checks if a file path matches the VFS file pattern (if one is set).
+     * Returns true if no pattern is set, or if the path matches the pattern.
+     */
+    matchesPattern(filePath: Path.PosixPath | string): boolean;
+    /**
+     * Writes the given content to the specified path.
+     * If a file pattern is set, only files matching the pattern will be stored.
+     */
+    write(path: string, content: FileContent): void;
+    /**
+     * Reads the content of a file from the specified path.
+     */
+    get(path: string): FileContent | undefined;
+    /**
+     * Reads the content of the specified folder.
+     */
+    getFolder(path: string): VirtualFileSystem | undefined;
+    /**
+     * Inserts the content of another VFS into this VFS at the specified path.
+     */
+    insertFromVfs({ vfs, targetPath }: {
+        vfs: VirtualFileSystem;
+        targetPath?: string;
+    }): void;
+    /**
+     * Loads the content from the folder on disk into this VFS at the specified path.
+     */
+    loadFolder({ diskPath, targetPath, recursive, filter, }: {
+        diskPath: string;
+        targetPath?: string;
+        filter?: (path: Path.PosixPath) => boolean;
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Loads the content from the file on disk into this VFS at the specified path.
+     */
+    loadFile({ diskPath, targetPath }: {
+        diskPath: string;
+        targetPath?: string;
+    }): Promise<void>;
+    /**
+     * Transforms the content of all files using the provided function.
+     * An optional filter function can be provided to select specific files.
+     */
+    transform(fn: (params: {
+        content: FileContent;
+        path: Path.PosixPath;
+    }) => Promise<FileContent>, { filter, onError, }?: {
+        filter?: (path: Path.PosixPath) => boolean;
+        onError?: (data: {
+            path: Path.PosixPath;
+            content: FileContent;
+            error: Error;
+        }) => void;
+    }): Promise<void>;
+}