@tiveor/scg 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,653 @@
+import fs from 'fs';
+
+/**
+ * Utility class for common string manipulation operations.
+ *
+ * @example
+ * ```typescript
+ * StringHelper.replace('Hello {{name}}!', '{{name}}', 'World');
+ * // => "Hello World!"
+ *
+ * StringHelper.capitalize('hello');
+ * // => "Hello"
+ * ```
+ */
+declare class StringHelper {
+    /**
+     * Escapes all regex special characters in a string.
+     *
+     * @param string - The string to escape
+     * @returns The escaped string safe for use in `new RegExp()`
+     *
+     * @example
+     * ```typescript
+     * StringHelper.escapeRegex('$100.00 (test)');
+     * // => "\\$100\\.00 \\(test\\)"
+     * ```
+     */
+    static escapeRegex(string: string): string;
+    /**
+     * Replaces all occurrences of a token in a string. The token is treated
+     * as a literal string (regex special characters are escaped automatically).
+     *
+     * @param line - The source string to search in. Returns `''` if not a string.
+     * @param token - The token to search for. Returns `line` unchanged if not a string.
+     * @param value - The replacement value
+     * @returns The string with all occurrences replaced
+     *
+     * @example
+     * ```typescript
+     * StringHelper.replace('Price: $10.00', '$10.00', '$20.00');
+     * // => "Price: $20.00"
+     * ```
+     */
+    static replace(line: unknown, token: unknown, value: string): string;
+    /**
+     * Capitalizes the first character of a string.
+     *
+     * @param s - The string to capitalize. Returns `''` if not a string.
+     * @returns The string with the first character uppercased
+     *
+     * @example
+     * ```typescript
+     * StringHelper.capitalize('hello world');
+     * // => "Hello world"
+     * ```
+     */
+    static capitalize(s: unknown): string;
+}
+
+/** Defines a single token replacement with optional template-based dynamic replacement. */
+interface Replacement {
+    /** The token string to search for in the template (e.g., `'{{name}}'`). */
+    token: string;
+    /** The static value to replace the token with. */
+    value?: string;
+    /** Path to a sub-template for dynamic replacement. */
+    template?: string;
+    /** Variables for dynamic replacement keyed by identifier. */
+    variables?: Record<string, Replacement[]>;
+}
+/** Options for creating a file from a template with variable replacements. */
+interface CreateFileOptions {
+    /** Path to the template file. */
+    template: string;
+    /** Path for the output file. */
+    newFile: string;
+    /** Array of token replacements to apply. */
+    variables: Replacement[];
+}
+/** Options for creating a string from a template with variable replacements. */
+interface CreateStringOptions {
+    /** Path to the template file. */
+    template: string;
+    /** Array of token replacements to apply. */
+    variables: Replacement[];
+}
+/**
+ * Utility class for file system operations, both synchronous and asynchronous.
+ *
+ * Provides methods for reading, writing, creating, and removing files and directories,
+ * as well as template-based file generation with variable replacement.
+ *
+ * @example
+ * ```typescript
+ * // Sync
+ * const content = FileHelper.readFileToString('config.txt');
+ * const config = FileHelper.convertJsonFileToObject('config.json');
+ *
+ * // Async
+ * const data = await FileHelper.readFileAsync('config.txt');
+ * await FileHelper.writeFileAsync('output.txt', 'content');
+ * ```
+ */
+declare class FileHelper {
+    /**
+     * Reads a file synchronously and returns its content as a UTF-8 string.
+     *
+     * @param fileName - Path to the file to read
+     * @returns The file content as a string
+     */
+    static readFileToString(fileName: string): string;
+    /**
+     * Reads a JSON file synchronously and parses it into an object.
+     *
+     * @typeParam T - The expected type of the parsed object
+     * @param fileName - Path to the JSON file
+     * @returns The parsed object
+     */
+    static convertJsonFileToObject<T = unknown>(fileName: string): T;
+    /**
+     * Creates a directory (and any parent directories) if it doesn't exist.
+     *
+     * @param folderName - Path to the directory to create
+     */
+    static createFolder(folderName: string): void;
+    /**
+     * Removes a directory and all its contents recursively.
+     *
+     * @param folderName - Path to the directory to remove
+     */
+    static removeFolder(folderName: string): void;
+    /**
+     * Removes a file if it exists.
+     *
+     * @param filename - Path to the file to remove
+     */
+    static removeFile(filename: string): void;
+    /**
+     * Reads a file asynchronously and returns its content as a UTF-8 string.
+     *
+     * @param fileName - Path to the file to read
+     * @returns A promise resolving to the file content
+     */
+    static readFileAsync(fileName: string): Promise<string>;
+    /**
+     * Reads a JSON file asynchronously and parses it into an object.
+     *
+     * @typeParam T - The expected type of the parsed object
+     * @param fileName - Path to the JSON file
+     * @returns A promise resolving to the parsed object
+     */
+    static readJsonFileAsync<T = unknown>(fileName: string): Promise<T>;
+    /**
+     * Writes content to a file asynchronously, creating parent directories as needed.
+     *
+     * @param fileName - Path to the file to write
+     * @param content - The string content to write
+     */
+    static writeFileAsync(fileName: string, content: string): Promise<void>;
+    /**
+     * Creates a directory asynchronously (with recursive parent creation).
+     *
+     * @param folderName - Path to the directory to create
+     */
+    static createFolderAsync(folderName: string): Promise<void>;
+    /**
+     * Removes a directory and its contents recursively (async).
+     *
+     * @param folderName - Path to the directory to remove
+     */
+    static removeFolderAsync(folderName: string): Promise<void>;
+    /**
+     * Removes a file asynchronously.
+     *
+     * @param filename - Path to the file to remove
+     */
+    static removeFileAsync(filename: string): Promise<void>;
+    /**
+     * Checks whether a file or directory exists asynchronously.
+     *
+     * @param filePath - Path to check
+     * @returns `true` if the path exists, `false` otherwise
+     */
+    static existsAsync(filePath: string): Promise<boolean>;
+    /**
+     * Performs a simple token replacement on a single line.
+     *
+     * @param line - The source line
+     * @param replacement - The replacement definition (uses `token` and `value`)
+     * @returns The line with the token replaced
+     */
+    static simpleReplace(line: string, replacement: Replacement): string;
+    /**
+     * Performs dynamic replacement using a sub-template and variables.
+     * Reads the sub-template line by line and applies all variable replacements.
+     *
+     * @param replacement - The replacement definition with `template` and `variables`
+     * @returns A promise resolving to the processed string
+     */
+    static dynamicReplace(replacement: Replacement): Promise<string>;
+    /**
+     * Creates a new file from a template file, applying variable replacements line by line.
+     * The special token `@date` is automatically replaced with the current UTC date.
+     *
+     * @param options - The template path, output path, and variables to apply
+     *
+     * @example
+     * ```typescript
+     * await FileHelper.createFileFromFile({
+     *   template: 'templates/component.txt',
+     *   newFile: 'output/Button.tsx',
+     *   variables: [
+     *     { token: '{{name}}', value: 'Button' },
+     *     { token: '{{style}}', value: 'primary' }
+     *   ]
+     * });
+     * ```
+     */
+    static createFileFromFile({ template, newFile, variables }: CreateFileOptions): Promise<void>;
+    /**
+     * Creates a string from a template file, applying variable replacements line by line.
+     * The special token `@date` is automatically replaced with the current UTC date.
+     *
+     * @param options - The template path and variables to apply
+     * @returns A promise resolving to the processed string
+     */
+    static createStringFromFile({ template, variables }: CreateStringOptions): Promise<string>;
+    /**
+     * Reads a file line by line and invokes a callback for each line.
+     *
+     * @param fileName - Path to the file to read
+     * @param callback - Function called for each line
+     */
+    static readLineByLine(fileName: string, callback: (line: string) => void | Promise<void>): Promise<void>;
+    /**
+     * Creates a writable stream for appending to a file.
+     *
+     * @param filename - Path to the file
+     * @returns A writable stream in append mode
+     */
+    static writer(filename: string): fs.WriteStream;
+    /**
+     * Writes a single line to a writable stream with CRLF line ending.
+     *
+     * @param writer - The writable stream
+     * @param newLine - The line content to write
+     */
+    static writeLineByLine(writer: fs.WriteStream, newLine: string): Promise<void>;
+}
+
+/**
+ * Utility class for executing shell commands as promises with input sanitization.
+ *
+ * Commands are validated against a set of forbidden patterns (shell metacharacters,
+ * command substitution, path traversal) before execution.
+ *
+ * @example
+ * ```typescript
+ * const output = await CommandHelper.run('.', 'echo hello');
+ * const version = await CommandHelper.runClean('.', 'node --version');
+ * ```
+ */
+declare class CommandHelper {
+    /**
+     * Executes one or more shell commands in the given directory.
+     * Multiple commands are joined with `&&` (sequential execution).
+     *
+     * @param directory - Working directory for command execution
+     * @param command - One or more command strings to execute
+     * @returns A promise resolving to the command's stdout (or stderr if stdout is empty)
+     * @throws If the directory is empty, no commands are provided, or a command matches a forbidden pattern
+     *
+     * @example
+     * ```typescript
+     * const output = await CommandHelper.run('.', 'echo hello');
+     * // => "hello\n"
+     *
+     * const result = await CommandHelper.run('.', 'git add .', 'git status');
+     * ```
+     */
+    static run(directory: string, ...command: string[]): Promise<string>;
+    /**
+     * Executes commands and returns the output with newlines stripped.
+     *
+     * @param folder - Working directory for command execution
+     * @param command - One or more command strings to execute
+     * @returns A promise resolving to the cleaned output (no newlines)
+     *
+     * @example
+     * ```typescript
+     * const version = await CommandHelper.runClean('.', 'node --version');
+     * // => "v20.10.0"
+     * ```
+     */
+    static runClean(folder: string, ...command: string[]): Promise<string>;
+}
+
+/**
+ * Utility class for parsing CLI parameters from `process.argv`.
+ *
+ * @example
+ * ```typescript
+ * // node script.js --name=Alice --port=3000
+ * const params = ParamHelper.getParams();
+ * // => { name: "Alice", port: "3000" }
+ * ```
+ */
+declare class ParamHelper {
+    /**
+     * Appends a custom parameter string to `process.argv`.
+     *
+     * @param customParam - The parameter to add (e.g., `'--env=production'`)
+     */
+    static addCustomParam(customParam: string): void;
+    /**
+     * Retrieves the command-line argument at the given index.
+     *
+     * @param index - Zero-based index into `process.argv`
+     * @returns The argument at the given index, or `''` if out of bounds
+     */
+    static getCommandByIndex(index: number): string;
+    /**
+     * Parses all `--key=value` parameters from `process.argv` into an object.
+     * Surrounding quotes on values are stripped automatically.
+     *
+     * @returns An object mapping parameter names to their string values
+     *
+     * @example
+     * ```typescript
+     * // node script.js --name=Alice --port=3000
+     * ParamHelper.getParams();
+     * // => { name: "Alice", port: "3000" }
+     * ```
+     */
+    static getParams(): Record<string, string>;
+}
+
+/**
+ * Enum-like object defining the built-in template engine identifiers.
+ *
+ * @example
+ * ```typescript
+ * const builder = new TemplateBuilder(TEMPLATE_HANDLERS.EJS);
+ * ```
+ */
+declare const TEMPLATE_HANDLERS: {
+    readonly HANDLEBARS: "HANDLEBARS";
+    readonly EJS: "EJS";
+    readonly PUG: "PUG";
+};
+/**
+ * Union type of all valid built-in template handler names.
+ */
+type TemplateHandler = (typeof TEMPLATE_HANDLERS)[keyof typeof TEMPLATE_HANDLERS];
+
+/**
+ * Interface that custom template engines must implement to be registered
+ * with {@link TemplateBuilder.registerEngine}.
+ */
+interface TemplateEngine {
+    /** Renders a template from a source string with the given data. */
+    render: (source: string, data: Record<string, unknown>, options?: Record<string, unknown>) => Promise<string>;
+    /** Renders a template from a file path with the given data. */
+    renderFile: (fileName: string, data: Record<string, unknown>, options?: Record<string, unknown>) => Promise<string>;
+}
+/**
+ * Unified interface to render templates with EJS, Handlebars, Pug, or any custom engine.
+ *
+ * Supports a plugin system for registering custom template engines at runtime.
+ *
+ * @example
+ * ```typescript
+ * // Built-in engines
+ * const builder = new TemplateBuilder(TEMPLATE_HANDLERS.EJS);
+ * const html = await builder.render('Hello <%= name %>', { name: 'World' });
+ *
+ * // Custom engine
+ * TemplateBuilder.registerEngine('nunjucks', {
+ *   render: async (source, data) => nunjucks.renderString(source, data),
+ *   renderFile: async (file, data) => nunjucks.render(file, data),
+ * });
+ * const nj = new TemplateBuilder('nunjucks');
+ * ```
+ */
+declare class TemplateBuilder {
+    private templateHandler;
+    /**
+     * Creates a new TemplateBuilder for the specified engine.
+     *
+     * @param templateHandler - The engine name (e.g., `'EJS'`, `'HANDLEBARS'`, `'PUG'`, or a custom name)
+     */
+    constructor(templateHandler: TemplateHandler | string);
+    /**
+     * Registers a custom template engine that can be used with `new TemplateBuilder(name)`.
+     *
+     * @param name - A unique name for the engine
+     * @param engine - An object implementing the {@link TemplateEngine} interface
+     * @throws If `name` is empty or `engine` doesn't implement `render()` and `renderFile()`
+     *
+     * @example
+     * ```typescript
+     * TemplateBuilder.registerEngine('nunjucks', {
+     *   render: async (source, data) => nunjucks.renderString(source, data),
+     *   renderFile: async (file, data) => nunjucks.render(file, data),
+     * });
+     * ```
+     */
+    static registerEngine(name: string, engine: TemplateEngine): void;
+    /**
+     * Retrieves a registered engine by name (custom engines take precedence over built-in).
+     *
+     * @param name - The engine name to look up
+     * @returns The engine implementation, or `undefined` if not found
+     */
+    static getEngine(name: string): TemplateEngine | undefined;
+    /**
+     * Returns an array of all registered engine names (built-in + custom).
+     *
+     * @returns Array of engine name strings
+     *
+     * @example
+     * ```typescript
+     * TemplateBuilder.getRegisteredEngines();
+     * // => ['HANDLEBARS', 'EJS', 'PUG']
+     * ```
+     */
+    static getRegisteredEngines(): string[];
+    private resolveEngine;
+    /**
+     * Renders a template from a source string.
+     *
+     * @param source - The template source string
+     * @param data - Data object to pass to the template
+     * @param options - Optional engine-specific options
+     * @returns A promise resolving to the rendered string
+     */
+    render(source: string, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<string>;
+    /**
+     * Renders a template from a file path.
+     *
+     * @param fileName - Path to the template file
+     * @param data - Data object to pass to the template
+     * @param options - Optional engine-specific options
+     * @returns A promise resolving to the rendered string
+     */
+    renderFile(fileName: string, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<string>;
+}
+
+/** A function that transforms a string, optionally returning a promise. */
+type TransformFn = (content: string) => string | Promise<string>;
+/**
+ * Chainable pipeline for composing template rendering and string transformations.
+ *
+ * Supports multiple input sources (string, file, template) and sequential
+ * transforms before writing the result to a file or returning it.
+ *
+ * @example
+ * ```typescript
+ * const result = await new Pipeline()
+ *   .fromTemplate('component.ejs', { name: 'Button' }, 'EJS')
+ *   .transform((content) => content.toUpperCase())
+ *   .writeTo('src/components/Button.tsx');
+ * ```
+ */
+declare class Pipeline {
+    private content;
+    private contentPromise;
+    private transforms;
+    /**
+     * Sets the pipeline content from a raw string.
+     *
+     * @param source - The string content
+     * @returns This pipeline instance for chaining
+     */
+    fromString(source: string): Pipeline;
+    /**
+     * Sets the pipeline content by reading a file synchronously.
+     *
+     * @param filePath - Path to the file to read
+     * @returns This pipeline instance for chaining
+     */
+    fromFile(filePath: string): Pipeline;
+    /**
+     * Sets the pipeline content by rendering a template file.
+     * If no engine is specified, it is auto-detected from the file extension.
+     *
+     * @param templatePath - Path to the template file
+     * @param data - Data to pass to the template
+     * @param engine - Template engine name (auto-detected if omitted)
+     * @param options - Optional engine-specific options
+     * @returns This pipeline instance for chaining
+     */
+    fromTemplate(templatePath: string, data: Record<string, unknown>, engine?: TemplateHandler | string, options?: Record<string, unknown>): Pipeline;
+    /**
+     * Sets the pipeline content by rendering a template from a source string.
+     *
+     * @param source - The template source string
+     * @param data - Data to pass to the template
+     * @param engine - The template engine name
+     * @param options - Optional engine-specific options
+     * @returns This pipeline instance for chaining
+     */
+    fromTemplateString(source: string, data: Record<string, unknown>, engine: TemplateHandler | string, options?: Record<string, unknown>): Pipeline;
+    /**
+     * Adds a transformation function to the pipeline.
+     * Transforms are executed sequentially in the order they are added.
+     *
+     * @param fn - A sync or async function that receives and returns a string
+     * @returns This pipeline instance for chaining
+     */
+    transform(fn: TransformFn): Pipeline;
+    /**
+     * Executes the pipeline: resolves the content and applies all transforms.
+     *
+     * @returns A promise resolving to the final transformed string
+     * @throws If no content source has been set
+     */
+    execute(): Promise<string>;
+    /**
+     * Executes the pipeline and writes the result to a file.
+     * Creates parent directories automatically if they don't exist.
+     *
+     * @param filePath - Path to the output file
+     * @returns A promise resolving to the written content
+     */
+    writeTo(filePath: string): Promise<string>;
+}
+
+/** Defines a single file in a scaffold structure. */
+interface ScaffoldFile {
+    /** Relative path to the template file (within `templateDir`). */
+    template: string;
+    /** Output filename pattern (supports `{{variable}}` interpolation). */
+    output: string;
+}
+/** Configuration options for scaffold generation. */
+interface ScaffoldOptions {
+    /** Template engine to use (e.g., `'EJS'`, `'HANDLEBARS'`, `'PUG'`). */
+    engine: string;
+    /** Base directory containing the template files. */
+    templateDir: string;
+    /** Output directory pattern (supports `{{variable}}` interpolation). */
+    outputDir: string;
+    /** Variables for template rendering and path interpolation. */
+    variables: Record<string, string>;
+    /** List of files to generate. */
+    structure: ScaffoldFile[];
+    /** If `true`, returns the file list without writing files. */
+    dryRun?: boolean;
+}
+/** Result of a scaffold generation operation. */
+interface ScaffoldResult {
+    /** List of file paths that were created (or would be created in dry-run mode). */
+    files: string[];
+    /** Whether this was a dry-run execution. */
+    dryRun: boolean;
+}
+/**
+ * Generates directory structures from a manifest configuration.
+ *
+ * Reads template files, renders them with the specified engine, and writes
+ * the output to a directory structure with variable-interpolated paths.
+ *
+ * @example
+ * ```typescript
+ * const result = await Scaffold.from({
+ *   engine: 'EJS',
+ *   templateDir: './templates/react-component',
+ *   outputDir: './src/components/{{name}}',
+ *   variables: { name: 'UserProfile', style: 'module' },
+ *   structure: [
+ *     { template: 'component.ejs', output: '{{name}}.tsx' },
+ *     { template: 'styles.ejs', output: '{{name}}.module.css' },
+ *     { template: 'test.ejs', output: '{{name}}.test.tsx' },
+ *   ]
+ * });
+ *
+ * console.log(result.files); // List of created file paths
+ * ```
+ */
+declare class Scaffold {
+    /**
+     * Generates files from a scaffold manifest.
+     *
+     * @param options - The scaffold configuration
+     * @returns A promise resolving to a {@link ScaffoldResult} with the list of created files
+     */
+    static from(options: ScaffoldOptions): Promise<ScaffoldResult>;
+}
+
+/** Configuration options for the file watcher. */
+interface WatcherOptions {
+    /** Directory containing template files to watch. */
+    templateDir: string;
+    /** Directory where rendered output files are written. */
+    outputDir: string;
+    /** Template engine to use for rendering (e.g., `'EJS'`, `'HANDLEBARS'`, `'PUG'`). */
+    engine: string;
+    /** Variables to pass to the template engine during rendering. */
+    variables: Record<string, unknown>;
+    /** File extensions to watch (defaults to `['.ejs', '.hbs', '.handlebars', '.pug']`). */
+    extensions?: string[];
+    /** Callback invoked after a file is successfully rebuilt. */
+    onRebuild?: (file: string) => void;
+    /** Callback invoked when a rebuild error occurs. */
+    onError?: (error: Error, file: string) => void;
+}
+/**
+ * Watches a template directory and automatically re-renders templates when they change.
+ *
+ * Uses `fs.watch()` with `AbortController` for clean start/stop lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const watcher = new Watcher({
+ *   templateDir: './templates',
+ *   outputDir: './generated',
+ *   engine: 'EJS',
+ *   variables: { project: 'MyApp' },
+ *   onRebuild: (file) => console.log(`Rebuilt: ${file}`),
+ *   onError: (err, file) => console.error(`Error in ${file}: ${err.message}`),
+ * });
+ *
+ * watcher.start();
+ * // Later: watcher.stop();
+ * ```
+ */
+declare class Watcher {
+    private options;
+    private abortController;
+    /**
+     * Creates a new Watcher instance.
+     *
+     * @param options - Watcher configuration
+     */
+    constructor(options: WatcherOptions);
+    /**
+     * Starts watching the template directory for changes.
+     * Does nothing if the watcher is already running.
+     */
+    start(): void;
+    /**
+     * Stops watching for changes and cleans up resources.
+     */
+    stop(): void;
+    /**
+     * Whether the watcher is currently active.
+     */
+    get isRunning(): boolean;
+    private handleChange;
+}
+
+export { CommandHelper, type CreateFileOptions, type CreateStringOptions, FileHelper, ParamHelper, Pipeline, type Replacement, Scaffold, type ScaffoldFile, type ScaffoldOptions, type ScaffoldResult, StringHelper, TEMPLATE_HANDLERS, TemplateBuilder, type TemplateEngine, type TemplateHandler, type TransformFn, Watcher, type WatcherOptions };