@buenos_andres/compact-builder 0.5.3

package/dist/services/FileDiscovery.js

@@ -0,0 +1,76 @@
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { DEFAULT_SRC_DIR } from "../types/options.js";
+import { isExcluded } from "../utils.js";
+/**
+ * Service responsible for discovering .compact files in the source directory.
+ * Recursively scans directories and filters for .compact file extensions,
+ * applying user-supplied exclude patterns.
+ *
+ * @example
+ * ```typescript
+ * const discovery = new FileDiscovery('src', ['Mock*']);
+ * const files = await discovery.getCompactFiles('src/security');
+ * ```
+ */
+export class FileDiscovery {
+    srcDir;
+    excludes;
+    /**
+     * Creates a new FileDiscovery instance.
+     *
+     * @param srcDir   - Base source directory for relative path calculation (default: 'src')
+     * @param excludes - Glob-style patterns of `.compact` files to skip.
+     *                   Patterns containing `/` match against the full path
+     *                   (as `find <srcDir>` would emit it); others match against
+     *                   the filename only. Default: `[]`.
+     */
+    constructor(srcDir = DEFAULT_SRC_DIR, excludes = []) {
+        this.srcDir = srcDir;
+        this.excludes = excludes;
+    }
+    /**
+     * Recursively discovers all .compact files in a directory.
+     * Returns relative paths from the srcDir for consistent processing.
+     *
+     * @param dir - Directory path to search (relative or absolute)
+     * @returns Promise resolving to array of relative file paths
+     */
+    async getCompactFiles(dir) {
+        try {
+            const dirents = await readdir(dir, { withFileTypes: true });
+            const filePromises = dirents.map(async (entry) => {
+                const fullPath = join(dir, entry.name);
+                try {
+                    if (entry.isDirectory()) {
+                        return await this.getCompactFiles(fullPath);
+                    }
+                    if (entry.isFile() && fullPath.endsWith('.compact')) {
+                        const relPath = relative(this.srcDir, fullPath);
+                        // Match path-style patterns against fullPath (i.e. the path that
+                        // `find srcDir` would emit) so users can write `*/archive/*` etc.,
+                        // identical to what they'd pass to `find -path`.
+                        if (isExcluded(entry.name, fullPath, this.excludes)) {
+                            return [];
+                        }
+                        return [relPath];
+                    }
+                    return [];
+                }
+                catch (err) {
+                    // biome-ignore lint/suspicious/noConsole: Needed to display error and file path
+                    console.warn(`Error accessing ${fullPath}:`, err);
+                    return [];
+                }
+            });
+            const results = await Promise.all(filePromises);
+            return results.flat();
+        }
+        catch (err) {
+            // biome-ignore lint/suspicious/noConsole: Needed to display error and dir path
+            console.error(`Failed to read dir: ${dir}`, err);
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=FileDiscovery.js.map

package/dist/services/FileDiscovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileDiscovery.js","sourceRoot":"","sources":["../../src/services/FileDiscovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,MAAM,OAAO,aAAa;IAChB,MAAM,CAAS;IACf,QAAQ,CAAoB;IAEpC;;;;;;;;OAQG;IACH,YACE,SAAiB,eAAe,EAChC,WAA8B,EAAE;QAEhC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,eAAe,CAAC,GAAW;QAC/B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;gBAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBACvC,IAAI,CAAC;oBACH,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;wBACxB,OAAO,MAAM,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;oBAC9C,CAAC;oBAED,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;wBACpD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;wBAChD,iEAAiE;wBACjE,mEAAmE;wBACnE,iDAAiD;wBACjD,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;4BACpD,OAAO,EAAE,CAAC;wBACZ,CAAC;wBACD,OAAO,CAAC,OAAO,CAAC,CAAC;oBACnB,CAAC;oBACD,OAAO,EAAE,CAAC;gBACZ,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,gFAAgF;oBAChF,OAAO,CAAC,IAAI,CAAC,mBAAmB,QAAQ,GAAG,EAAE,GAAG,CAAC,CAAC;oBAClD,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAChD,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,+EAA+E;YAC/E,OAAO,CAAC,KAAK,CAAC,uBAAuB,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;YACjD,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;CACF"}

package/dist/services/UIService.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Utility service for handling user interface output and formatting.
+ * Provides consistent styling and formatting for compiler messages and output.
+ *
+ * @example
+ * ```typescript
+ * UIService.displayEnvInfo('compact 0.1.0', 'Compactc 0.26.0', 'security');
+ * UIService.printOutput('Compilation successful', chalk.green);
+ * ```
+ */
+export declare const UIService: {
+    /**
+     * Prints formatted output with consistent indentation and coloring.
+     * Filters empty lines and adds consistent indentation for readability.
+     *
+     * @param output  - Raw output text to format
+     * @param colorFn - Chalk color function for styling
+     */
+    printOutput(output: string, colorFn: (text: string) => string): void;
+    /**
+     * Displays environment information including tool versions and configuration.
+     * Shows developer tools version, toolchain version, and optional settings.
+     *
+     * @param devToolsVersion  - Version string of the Compact developer tools
+     * @param toolchainVersion - Version string of the Compact toolchain/compiler
+     * @param targetDir        - Optional target directory being compiled
+     * @param version          - Optional specific version being used
+     */
+    displayEnvInfo(devToolsVersion: string, toolchainVersion: string, targetDir?: string, version?: string): void;
+    /**
+     * Displays compilation start message with file count and optional location.
+     *
+     * @param fileCount - Number of files to be compiled
+     * @param targetDir - Optional target directory being compiled
+     */
+    showCompilationStart(fileCount: number, targetDir?: string): void;
+    /**
+     * Displays a warning message when no .compact files are found.
+     *
+     * @param targetDir - Optional target directory that was searched
+     */
+    showNoFiles(targetDir?: string): void;
+};

package/dist/services/UIService.js

@@ -0,0 +1,70 @@
+import chalk from 'chalk';
+import ora from 'ora';
+/**
+ * Utility service for handling user interface output and formatting.
+ * Provides consistent styling and formatting for compiler messages and output.
+ *
+ * @example
+ * ```typescript
+ * UIService.displayEnvInfo('compact 0.1.0', 'Compactc 0.26.0', 'security');
+ * UIService.printOutput('Compilation successful', chalk.green);
+ * ```
+ */
+export const UIService = {
+    /**
+     * Prints formatted output with consistent indentation and coloring.
+     * Filters empty lines and adds consistent indentation for readability.
+     *
+     * @param output  - Raw output text to format
+     * @param colorFn - Chalk color function for styling
+     */
+    printOutput(output, colorFn) {
+        const lines = output
+            .split('\n')
+            .filter((line) => line.trim() !== '')
+            .map((line) => `    ${line}`);
+        console.log(colorFn(lines.join('\n')));
+    },
+    /**
+     * Displays environment information including tool versions and configuration.
+     * Shows developer tools version, toolchain version, and optional settings.
+     *
+     * @param devToolsVersion  - Version string of the Compact developer tools
+     * @param toolchainVersion - Version string of the Compact toolchain/compiler
+     * @param targetDir        - Optional target directory being compiled
+     * @param version          - Optional specific version being used
+     */
+    displayEnvInfo(devToolsVersion, toolchainVersion, targetDir, version) {
+        const spinner = ora();
+        if (targetDir) {
+            spinner.info(chalk.blue(`[COMPILE] TARGET_DIR: ${targetDir}`));
+        }
+        spinner.info(chalk.blue(`[COMPILE] Compact developer tools: ${devToolsVersion}`));
+        spinner.info(chalk.blue(`[COMPILE] Compact toolchain: ${toolchainVersion}`));
+        if (version) {
+            spinner.info(chalk.blue(`[COMPILE] Using toolchain version: ${version}`));
+        }
+    },
+    /**
+     * Displays compilation start message with file count and optional location.
+     *
+     * @param fileCount - Number of files to be compiled
+     * @param targetDir - Optional target directory being compiled
+     */
+    showCompilationStart(fileCount, targetDir) {
+        const searchLocation = targetDir ? ` in ${targetDir}/` : '';
+        const spinner = ora();
+        spinner.info(chalk.blue(`[COMPILE] Found ${fileCount} .compact file(s) to compile${searchLocation}`));
+    },
+    /**
+     * Displays a warning message when no .compact files are found.
+     *
+     * @param targetDir - Optional target directory that was searched
+     */
+    showNoFiles(targetDir) {
+        const searchLocation = targetDir ? `${targetDir}/` : '';
+        const spinner = ora();
+        spinner.warn(chalk.yellow(`[COMPILE] No .compact files found in ${searchLocation}.`));
+    },
+};
+//# sourceMappingURL=UIService.js.map

package/dist/services/UIService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UIService.js","sourceRoot":"","sources":["../../src/services/UIService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,GAAG,MAAM,KAAK,CAAC;AAEtB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB;;;;;;OAMG;IACH,WAAW,CAAC,MAAc,EAAE,OAAiC;QAC3D,MAAM,KAAK,GAAG,MAAM;aACjB,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;aACpC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;OAQG;IACH,cAAc,CACZ,eAAuB,EACvB,gBAAwB,EACxB,SAAkB,EAClB,OAAgB;QAEhB,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC;QAEtB,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,yBAAyB,SAAS,EAAE,CAAC,CAAC,CAAC;QACjE,CAAC;QAED,OAAO,CAAC,IAAI,CACV,KAAK,CAAC,IAAI,CAAC,sCAAsC,eAAe,EAAE,CAAC,CACpE,CAAC;QACF,OAAO,CAAC,IAAI,CACV,KAAK,CAAC,IAAI,CAAC,gCAAgC,gBAAgB,EAAE,CAAC,CAC/D,CAAC;QAEF,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,sCAAsC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,SAAiB,EAAE,SAAkB;QACxD,MAAM,cAAc,GAAG,SAAS,CAAC,CAAC,CAAC,OAAO,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC;QACtB,OAAO,CAAC,IAAI,CACV,KAAK,CAAC,IAAI,CACR,mBAAmB,SAAS,+BAA+B,cAAc,EAAE,CAC5E,CACF,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,SAAkB;QAC5B,MAAM,cAAc,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC;QACtB,OAAO,CAAC,IAAI,CACV,KAAK,CAAC,MAAM,CAAC,wCAAwC,cAAc,GAAG,CAAC,CACxE,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/types/errors.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A custom error that describes the shape of an error returned from a promisfied
+ * child_process.exec
+ *
+ * @interface PromisifiedChildProcessError
+ * @typedef {PromisifiedChildProcessError}
+ * @extends {Error}
+ *
+ * @prop {string} stdout stdout of a child process
+ * @prop {string} stderr stderr of a child process
+ */
+export interface PromisifiedChildProcessError extends Error {
+    stdout: string;
+    stderr: string;
+}
+/**
+ * A type guard function for PromisifiedChildProcessError
+ *
+ * @param {unknown} error - An error caught in a try catch block
+ * @returns {error is PromisifiedChildProcessError} - Informs TS compiler if the understood
+ * type is a PromisifiedChildProcessError
+ */
+export declare function isPromisifiedChildProcessError(error: unknown): error is PromisifiedChildProcessError;
+/**
+ * Custom error thrown when the Compact CLI is not found in the system PATH.
+ * This error indicates that the Compact developer tools are not installed
+ * or not properly configured in the environment.
+ *
+ * @class CompactCliNotFoundError
+ * @extends Error
+ */
+export declare class CompactCliNotFoundError extends Error {
+    /**
+     * Creates a new CompactCliNotFoundError instance.
+     *
+     * @param message - Error message describing the CLI availability issue
+     */
+    constructor(message: string);
+}
+/**
+ * Custom error thrown when compilation of a .compact file fails.
+ * Contains additional context about which file failed to compile,
+ * making it easier to identify and debug compilation issues.
+ *
+ * @class CompilationError
+ * @extends Error
+ */
+export declare class CompilationError extends Error {
+    readonly file?: string;
+    /**
+     * Creates a new CompilationError instance.
+     *
+     * @param message - Error message describing the compilation failure
+     * @param file - Optional relative path to the file that failed to compile
+     */
+    constructor(message: string, file?: string, cause?: unknown);
+}
+/**
+ * Custom error thrown when a specified target directory does not exist.
+ * Provides specific information about which directory was not found,
+ * helping users correct path-related issues.
+ *
+ * @class DirectoryNotFoundError
+ * @extends Error
+ */
+export declare class DirectoryNotFoundError extends Error {
+    readonly directory: string;
+    /**
+     * Creates a new DirectoryNotFoundError instance.
+     *
+     * @param message - Error message describing the directory issue
+     * @param directory - The directory path that was not found
+     */
+    constructor(message: string, directory: string);
+}

package/dist/types/errors.js

@@ -0,0 +1,74 @@
+/**
+ * A type guard function for PromisifiedChildProcessError
+ *
+ * @param {unknown} error - An error caught in a try catch block
+ * @returns {error is PromisifiedChildProcessError} - Informs TS compiler if the understood
+ * type is a PromisifiedChildProcessError
+ */
+export function isPromisifiedChildProcessError(error) {
+    return error instanceof Error && 'stdout' in error && 'stderr' in error;
+}
+/**
+ * Custom error thrown when the Compact CLI is not found in the system PATH.
+ * This error indicates that the Compact developer tools are not installed
+ * or not properly configured in the environment.
+ *
+ * @class CompactCliNotFoundError
+ * @extends Error
+ */
+export class CompactCliNotFoundError extends Error {
+    /**
+     * Creates a new CompactCliNotFoundError instance.
+     *
+     * @param message - Error message describing the CLI availability issue
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'CompactCliNotFoundError';
+    }
+}
+/**
+ * Custom error thrown when compilation of a .compact file fails.
+ * Contains additional context about which file failed to compile,
+ * making it easier to identify and debug compilation issues.
+ *
+ * @class CompilationError
+ * @extends Error
+ */
+export class CompilationError extends Error {
+    file;
+    /**
+     * Creates a new CompilationError instance.
+     *
+     * @param message - Error message describing the compilation failure
+     * @param file - Optional relative path to the file that failed to compile
+     */
+    constructor(message, file, cause) {
+        super(message, { cause });
+        this.file = file;
+        this.name = 'CompilationError';
+    }
+}
+/**
+ * Custom error thrown when a specified target directory does not exist.
+ * Provides specific information about which directory was not found,
+ * helping users correct path-related issues.
+ *
+ * @class DirectoryNotFoundError
+ * @extends Error
+ */
+export class DirectoryNotFoundError extends Error {
+    directory;
+    /**
+     * Creates a new DirectoryNotFoundError instance.
+     *
+     * @param message - Error message describing the directory issue
+     * @param directory - The directory path that was not found
+     */
+    constructor(message, directory) {
+        super(message);
+        this.directory = directory;
+        this.name = 'DirectoryNotFoundError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/types/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAgBA;;;;;;GAMG;AACH,MAAM,UAAU,8BAA8B,CAC5C,KAAc;IAEd,OAAO,KAAK,YAAY,KAAK,IAAI,QAAQ,IAAI,KAAK,IAAI,QAAQ,IAAI,KAAK,CAAC;AAC1E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD;;;;OAIG;IACH,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzB,IAAI,CAAU;IAE9B;;;;;OAKG;IACH,YAAY,OAAe,EAAE,IAAa,EAAE,KAAe;QACzD,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAE1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/B,SAAS,CAAS;IAElC;;;;;OAKG;IACH,YAAY,OAAe,EAAE,SAAiB;QAC5C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}

package/dist/types/options.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared option/type definitions and defaults for the Compact CLI tools.
+ *
+ * This module is the canonical home for cross-cutting types (`CompilerOptions`,
+ * `BuilderOptions`, `ExecFunction`, …) plus their default constants. Splitting
+ * them out keeps `Compiler.ts` and `Builder.ts` focused on behaviour rather
+ * than data shapes.
+ */
+/** Default source directory containing .compact files. */
+export declare const DEFAULT_SRC_DIR = "src";
+/** Default output directory for compiled artifacts. */
+export declare const DEFAULT_OUT_DIR = "artifacts";
+/**
+ * Default `.compact` glob patterns the builder strips from `dist/` when the
+ * user hasn't supplied an explicit `--exclude` list. Covers both common mock
+ * naming conventions.
+ */
+export declare const DEFAULT_EXCLUDE_PATTERNS: readonly string[];
+/**
+ * Function type for executing a child process.
+ *
+ * Matches the shape of `promisify(child_process.execFile)`: the binary name
+ * (no shell), followed by positional arguments. This signature is injection-
+ * safe by construction — values flow as separate argv entries rather than
+ * being interpolated into a shell command string.
+ *
+ * @param file - The binary to invoke (e.g. `'compact'`)
+ * @param args - Positional arguments passed verbatim to the binary
+ * @returns Promise resolving to the captured stdout/stderr
+ */
+export type ExecFunction = (file: string, args: readonly string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Configuration options for the Compact compiler CLI.
+ *
+ * @example
+ * ```typescript
+ * const options: CompilerOptions = {
+ *   flags: '--skip-zk --verbose',
+ *   targetDir: 'security',
+ *   version: '0.26.0',
+ *   hierarchical: false,
+ * };
+ * ```
+ */
+export interface CompilerOptions {
+    /** Compiler flags to pass to the Compact CLI (e.g., '--skip-zk --verbose') */
+    flags?: string;
+    /** Optional subdirectory within srcDir to compile (e.g., 'security', 'token') */
+    targetDir?: string;
+    /** Optional toolchain version to use (e.g., '0.26.0') */
+    version?: string;
+    /**
+     * Whether to preserve directory structure in artifacts output.
+     * - `false` (default): Flattened output - `<outDir>/<ContractName>/`
+     * - `true`: Hierarchical output - `<outDir>/<subdir>/<ContractName>/`
+     */
+    hierarchical?: boolean;
+    /** Source directory containing .compact files (default: 'src') */
+    srcDir?: string;
+    /** Output directory for compiled artifacts (default: 'artifacts') */
+    outDir?: string;
+    /**
+     * Glob-style patterns to exclude `.compact` files from both the compiler's
+     * file discovery and the builder's `.compact` copy step.
+     * - Patterns without `/` match against the filename only (e.g. `'Mock*'`).
+     * - Patterns with `/` match against the path as `find <srcDir>` would emit
+     *   it (e.g. `'*\/archive\/*'`, matching `src/archive/Foo.compact`). This is
+     *   the same semantic as `find -path '<pattern>'`.
+     *
+     * Default: `undefined` (no excludes for the compiler). The builder
+     * substitutes its own default ({@link DEFAULT_EXCLUDE_PATTERNS}) when
+     * undefined; pass an explicit `[]` to disable that too.
+     */
+    exclude?: string[];
+}
+/**
+ * Subset of {@link CompilerOptions} consumed by `CompilerService` when
+ * compiling individual files.
+ */
+export type CompilerServiceOptions = Pick<CompilerOptions, 'hierarchical' | 'srcDir' | 'outDir'>;
+/**
+ * Builder-only configuration options that don't apply to the compiler.
+ *
+ * These control the *distribution* layout produced by `compact-builder`,
+ * letting consumers ship a publishable `dist/` directory matching their
+ * package's conventions (e.g. copying metadata files for npm publish).
+ *
+ * Two inherited {@link CompilerOptions} fields also affect builder behaviour:
+ * - `hierarchical` — drives both compiler artifacts layout AND `.compact` copy layout.
+ * - `exclude`     — drives both compiler file discovery AND `.compact` copy filtering.
+ *   When `exclude` is undefined, the builder substitutes its own default
+ *   ({@link DEFAULT_EXCLUDE_PATTERNS}) so mocks are stripped from the dist
+ *   even when the compiler is told to consume them.
+ */
+export interface BuilderOnlyOptions {
+    /**
+     * If true, runs `rm -rf dist && mkdir -p dist` before building.
+     * Use when you want a fully clean `dist/` on every build.
+     * @default false
+     */
+    cleanDist?: boolean;
+    /**
+     * Additional file paths to copy into `dist/` for distribution
+     * (e.g. `['package.json', '../README.md']`). Paths are relative to cwd.
+     * Each entry is copied individually with `cp <path> dist/`.
+     * @default []
+     */
+    copyToDist?: string[];
+}
+/**
+ * Configuration options for the Builder CLI.
+ * Extends {@link CompilerOptions} with builder-only distribution controls.
+ */
+export type BuilderOptions = CompilerOptions & BuilderOnlyOptions;
+/**
+ * Single build step executed by `CompactBuilder`.
+ */
+export interface BuildStep {
+    /** Shell command to execute. */
+    cmd: string;
+    /** Human-readable progress message. */
+    msg: string;
+    /** Optional explicit shell (e.g. `'/bin/bash'`) when bash features are required. */
+    shell?: string;
+}

package/dist/types/options.js

@@ -0,0 +1,22 @@
+/**
+ * Shared option/type definitions and defaults for the Compact CLI tools.
+ *
+ * This module is the canonical home for cross-cutting types (`CompilerOptions`,
+ * `BuilderOptions`, `ExecFunction`, …) plus their default constants. Splitting
+ * them out keeps `Compiler.ts` and `Builder.ts` focused on behaviour rather
+ * than data shapes.
+ */
+/** Default source directory containing .compact files. */
+export const DEFAULT_SRC_DIR = 'src';
+/** Default output directory for compiled artifacts. */
+export const DEFAULT_OUT_DIR = 'artifacts';
+/**
+ * Default `.compact` glob patterns the builder strips from `dist/` when the
+ * user hasn't supplied an explicit `--exclude` list. Covers both common mock
+ * naming conventions.
+ */
+export const DEFAULT_EXCLUDE_PATTERNS = [
+    'Mock*',
+    '*.mock.compact',
+];
+//# sourceMappingURL=options.js.map

package/dist/types/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/types/options.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC,uDAAuD;AACvD,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB;IACzD,OAAO;IACP,gBAAgB;CACjB,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Internal helpers for the Compact CLI tools.
+ *
+ * - **Glob matching** ({@link globToRegex}, {@link isExcluded}) — used by
+ *   `FileDiscovery` to skip `.compact` files matching user-supplied patterns.
+ * - **Shell quoting** ({@link shellQuote}, {@link buildFindExcludes}) — used by
+ *   `CompactBuilder` to interpolate user-supplied values into bash commands
+ *   safely.
+ */
+/**
+ * Converts a simple glob pattern to a regular expression.
+ * Supports `*` (any sequence) and `?` (single char). All other glob features
+ * (brace expansion, character classes) are not supported — keep patterns simple.
+ */
+export declare function globToRegex(glob: string): RegExp;
+/**
+ * Returns true if `filename`/`fullPath` matches any of the given glob patterns.
+ *
+ * - Patterns containing `/` are matched against `fullPath` (the path as
+ *   `find srcDir` would emit it, e.g. `'src/archive/Foo.compact'`).
+ * - Patterns without `/` are matched against `filename` only.
+ *
+ * This mirrors the semantic of `find -name <pattern>` vs `find -path <pattern>`.
+ */
+export declare function isExcluded(filename: string, fullPath: string, patterns: readonly string[]): boolean;
+/**
+ * Shell-quotes a string for safe interpolation into a single-quoted bash arg.
+ *
+ * @example
+ * shellQuote("foo")       // "'foo'"
+ * shellQuote("it's")      // "'it'\\''s'"
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * Builds the `find`-compatible exclusion fragment for the given patterns.
+ * Patterns containing `/` are emitted as `! -path '<pattern>'`; others as
+ * `! -name '<pattern>'`. Single-quoting ensures safe shell interpolation.
+ *
+ * @example
+ * buildFindExcludes(['Mock*', '*\/archive\/*'])
+ * // "! -name 'Mock*' ! -path '*\/archive\/*'"
+ */
+export declare function buildFindExcludes(patterns: readonly string[]): string;

package/dist/utils.js

@@ -0,0 +1,61 @@
+/**
+ * Internal helpers for the Compact CLI tools.
+ *
+ * - **Glob matching** ({@link globToRegex}, {@link isExcluded}) — used by
+ *   `FileDiscovery` to skip `.compact` files matching user-supplied patterns.
+ * - **Shell quoting** ({@link shellQuote}, {@link buildFindExcludes}) — used by
+ *   `CompactBuilder` to interpolate user-supplied values into bash commands
+ *   safely.
+ */
+/**
+ * Converts a simple glob pattern to a regular expression.
+ * Supports `*` (any sequence) and `?` (single char). All other glob features
+ * (brace expansion, character classes) are not supported — keep patterns simple.
+ */
+export function globToRegex(glob) {
+    const escaped = glob.replace(/[\\^$+|.()[\]{}]/g, '\\$&');
+    const pattern = escaped.replace(/\*/g, '.*').replace(/\?/g, '.');
+    return new RegExp(`^${pattern}$`);
+}
+/**
+ * Returns true if `filename`/`fullPath` matches any of the given glob patterns.
+ *
+ * - Patterns containing `/` are matched against `fullPath` (the path as
+ *   `find srcDir` would emit it, e.g. `'src/archive/Foo.compact'`).
+ * - Patterns without `/` are matched against `filename` only.
+ *
+ * This mirrors the semantic of `find -name <pattern>` vs `find -path <pattern>`.
+ */
+export function isExcluded(filename, fullPath, patterns) {
+    return patterns.some((pattern) => {
+        const target = pattern.includes('/') ? fullPath : filename;
+        return globToRegex(pattern).test(target);
+    });
+}
+/**
+ * Shell-quotes a string for safe interpolation into a single-quoted bash arg.
+ *
+ * @example
+ * shellQuote("foo")       // "'foo'"
+ * shellQuote("it's")      // "'it'\\''s'"
+ */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Builds the `find`-compatible exclusion fragment for the given patterns.
+ * Patterns containing `/` are emitted as `! -path '<pattern>'`; others as
+ * `! -name '<pattern>'`. Single-quoting ensures safe shell interpolation.
+ *
+ * @example
+ * buildFindExcludes(['Mock*', '*\/archive\/*'])
+ * // "! -name 'Mock*' ! -path '*\/archive\/*'"
+ */
+export function buildFindExcludes(patterns) {
+    return patterns
+        .map((pattern) => pattern.includes('/')
+        ? `! -path ${shellQuote(pattern)}`
+        : `! -name ${shellQuote(pattern)}`)
+        .join(' ');
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACjE,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CACxB,QAAgB,EAChB,QAAgB,EAChB,QAA2B;IAE3B,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC3D,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAA2B;IAC3D,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACf,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QACnB,CAAC,CAAC,WAAW,UAAU,CAAC,OAAO,CAAC,EAAE;QAClC,CAAC,CAAC,WAAW,UAAU,CAAC,OAAO,CAAC,EAAE,CACrC;SACA,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@buenos_andres/compact-builder",
+  "description": "Programmatic library for compiling and building Compact smart contracts",
+  "version": "0.5.3",
+  "keywords": [
+    "compact",
+    "midnight",
+    "compiler",
+    "builder",
+    "library"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "types": "tsc -p tsconfig.json --noEmit",
+    "test": "yarn vitest run",
+    "clean": "git clean -fXd"
+  },
+  "devDependencies": {
+    "@tsconfig/node24": "^24.0.3",
+    "@types/node": "24.10.1",
+    "@types/shell-quote": "^1.7.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "log-symbols": "^7.0.0",
+    "ora": "^9.0.0",
+    "shell-quote": "^1.8.3"
+  }
+}