@buenos_andres/compact-builder 0.5.3

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to `@buenos_andres/compact-builder` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Added
+
+- Initial public release of `@buenos_andres/compact-builder`.
+- Programmatic API for orchestrating the Compact toolchain:
+  - `CompactCompiler` — compiles `.compact` files to artifacts.
+  - `CompactBuilder` — runs `CompactCompiler` then assembles a publishable
+    `dist/`.
+- Composable service classes: `EnvironmentValidator`, `FileDiscovery`,
+  `CompilerService`, and the `UIService` helper object.
+- Option types: `CompilerOptions`, `BuilderOptions`, `BuilderOnlyOptions`,
+  `CompilerServiceOptions`, `BuildStep`, `ExecFunction`.
+- Configurable behaviours:
+  - `hierarchical` — preserve source tree in compiler artifacts and the
+    builder's `.compact` copy step.
+  - `exclude` — glob-style patterns to skip in file discovery and dist copy
+    (`Mock*` / `*.mock.compact` excluded by default).
+  - `cleanDist` — `rm -rf dist` before building.
+  - `copyToDist` — extra files (e.g. `package.json`, `README.md`) to copy into
+    `dist/` for publishable layouts.
+  - `srcDir` / `outDir` — customize source and artifact directories.
+- Structured error types: `CompactCliNotFoundError`, `CompilationError`,
+  `DirectoryNotFoundError`, plus the `isPromisifiedChildProcessError` type guard.
+- Dependency-injectable `ExecFunction` for testing.
+
+### Notes
+
+- This package contains the library code that previously lived under
+  `@buenos_andres/compact-cli`. The CLI package now ships only the bin
+  entries (`compact-compiler`, `compact-builder`) and depends on this library.

package/README.md

@@ -0,0 +1,71 @@
+# @buenos_andres/compact-builder
+
+Programmatic library for compiling and building Compact smart contracts on the
+Midnight network. Drives the `compactc` toolchain with progress reporting,
+structured error handling, and configurable output layouts.
+
+This is the **library** — it ships no CLI binaries. If you want the bins
+(`compact-compiler`, `compact-builder`) for use in `package.json` scripts,
+install [`@buenos_andres/compact-cli`](../cli) instead, which is a thin
+wrapper around this library.
+
+## Install
+
+```bash
+yarn add --dev @buenos_andres/compact-builder
+```
+
+## Quick Start
+
+```ts
+import { CompactCompiler, CompactBuilder } from '@buenos_andres/compact-builder';
+
+// Compile all .compact files in src/ to artifacts/
+await new CompactCompiler({ flags: '--skip-zk' }).compile();
+
+// Or run the full build pipeline (compile + dist assembly)
+const builder = new CompactBuilder({
+  cleanDist: true,
+  hierarchical: true,
+  exclude: ['Mock*', '*/archive/*'],
+  copyToDist: ['package.json', '../README.md'],
+});
+await builder.build();
+```
+
+## Public API
+
+```ts
+// Orchestrators
+export class CompactCompiler { /* … */ }
+export class CompactBuilder  { /* … */ }
+
+// Service classes (use for advanced custom pipelines)
+export class EnvironmentValidator { /* … */ }
+export class FileDiscovery        { /* … */ }
+export class CompilerService      { /* … */ }
+export const UIService = { /* … */ };
+
+// Option types
+export interface CompilerOptions { /* flags, targetDir, version, hierarchical, srcDir, outDir, exclude */ }
+export type BuilderOptions = CompilerOptions & {
+  cleanDist?: boolean;
+  copyToDist?: string[];
+};
+
+// Errors
+export class CompactCliNotFoundError extends Error { /* … */ }
+export class CompilationError        extends Error { /* … */ }
+export class DirectoryNotFoundError  extends Error { /* … */ }
+```
+
+## See also
+
+- [`@buenos_andres/compact-cli`](https://www.npmjs.com/package/@buenos_andres/compact-cli) — bin wrapper around this library
+- [`@buenos_andres/compact-simulator`](https://www.npmjs.com/package/@buenos_andres/compact-simulator) — TypeScript simulator for testing Compact contracts locally
+
+See the [monorepo README](https://github.com/buenos_andres/compact-tools#readme) for the full developer guide.
+
+## License
+
+MIT

package/dist/Builder.d.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { type BuilderOnlyOptions, type BuilderOptions, type BuildStep } from './types/options.ts';
+export type { BuilderOnlyOptions, BuilderOptions };
+/**
+ * A class to handle the build process for a project.
+ * Runs CompactCompiler as a prerequisite, then executes build steps (TypeScript compilation,
+ * artifact copying, etc.) with progress feedback and colored output for success and error states.
+ *
+ * Build steps are derived from {@link BuilderOptions} so consumers can produce a
+ * publishable distribution that matches their package conventions
+ * (preserve source tree, copy metadata, clean dist, custom excludes).
+ *
+ * @notice `cmd` scripts discard `stderr` output and fail silently because this is
+ * handled in `executeStep`.
+ *
+ * @example
+ * ```typescript
+ * // Default: flatten .compact files, exclude Mock*
+ * const builder = new CompactBuilder({ flags: '--skip-zk' });
+ *
+ * // Library publish: clean dist, hierarchical tree, exclude mocks + archive, copy metadata.
+ * const builder = new CompactBuilder({
+ *   cleanDist: true,
+ *   hierarchical: true,
+ *   exclude: ['Mock*', '*\/archive\/*'],
+ *   copyToDist: ['package.json', '../README.md'],
+ * });
+ * builder.build().catch(err => console.error(err));
+ * ```
+ */
+export declare class CompactBuilder {
+    private readonly options;
+    private readonly steps;
+    /**
+     * Constructs a new CompactBuilder instance.
+     * @param options - Compiler + builder options (see {@link BuilderOptions}).
+     */
+    constructor(options?: BuilderOptions);
+    /**
+     * Factory method to create a CompactBuilder from command-line arguments.
+     *
+     * @param args - Array of command-line arguments
+     * @param env - Environment variables (defaults to process.env)
+     * @returns New CompactBuilder instance configured from arguments
+     */
+    static fromArgs(args: string[], env?: typeof process.env): CompactBuilder;
+    /**
+     * Parses command-line arguments into {@link BuilderOptions}.
+     * Builder-only flags are extracted here; remaining args are forwarded to
+     * {@link CompactCompiler.parseArgs} for compiler-side parsing.
+     *
+     * Builder-only flags (compiler flags like `--hierarchical` and `--exclude`
+     * are forwarded to {@link CompactCompiler.parseArgs}):
+     * - `--clean-dist`            - rm -rf dist before building
+     * - `--copy <path>`           - copy an extra file into dist/ (repeatable)
+     *
+     * @throws {Error} If `--copy` is provided without a value.
+     */
+    static parseArgs(args: string[], env?: typeof process.env): BuilderOptions;
+    /**
+     * Executes the full build process: compiles .compact files first, then runs build steps.
+     * Displays progress with spinners and outputs results in color.
+     *
+     * @returns A promise that resolves when all steps complete successfully
+     * @throws Error if compilation or any build step fails
+     */
+    build(): Promise<void>;
+    /**
+     * Exposes the resolved build steps. Public for testing/introspection.
+     */
+    getSteps(): readonly BuildStep[];
+    /**
+     * Assembles the build-step pipeline from the configured options.
+     */
+    private buildSteps;
+    /**
+     * Executes a single build step.
+     * Runs the command, shows a spinner, and prints output with indentation.
+     *
+     * @param step - The build step containing command and message
+     * @param index - Current step index (0-based) for progress display
+     * @param total - Total number of steps for progress display
+     * @returns A promise that resolves when the step completes successfully
+     * @throws Error if the step fails
+     */
+    private executeStep;
+    /**
+     * Prints command output with indentation and specified color.
+     * Filters out empty lines and indents each line for readability.
+     *
+     * @param output - The command output string to print (stdout or stderr)
+     * @param colorFn - Chalk color function to style the output (e.g., `chalk.cyan` for success, `chalk.red` for errors)
+     */
+    private printOutput;
+}

package/dist/Builder.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import chalk from 'chalk';
+import ora, {} from 'ora';
+import { CompactCompiler } from "./Compiler.js";
+import { isPromisifiedChildProcessError } from "./types/errors.js";
+import { DEFAULT_EXCLUDE_PATTERNS, } from "./types/options.js";
+import { buildFindExcludes, shellQuote } from "./utils.js";
+// Promisified exec for async execution
+const execAsync = promisify(exec);
+/**
+ * A class to handle the build process for a project.
+ * Runs CompactCompiler as a prerequisite, then executes build steps (TypeScript compilation,
+ * artifact copying, etc.) with progress feedback and colored output for success and error states.
+ *
+ * Build steps are derived from {@link BuilderOptions} so consumers can produce a
+ * publishable distribution that matches their package conventions
+ * (preserve source tree, copy metadata, clean dist, custom excludes).
+ *
+ * @notice `cmd` scripts discard `stderr` output and fail silently because this is
+ * handled in `executeStep`.
+ *
+ * @example
+ * ```typescript
+ * // Default: flatten .compact files, exclude Mock*
+ * const builder = new CompactBuilder({ flags: '--skip-zk' });
+ *
+ * // Library publish: clean dist, hierarchical tree, exclude mocks + archive, copy metadata.
+ * const builder = new CompactBuilder({
+ *   cleanDist: true,
+ *   hierarchical: true,
+ *   exclude: ['Mock*', '*\/archive\/*'],
+ *   copyToDist: ['package.json', '../README.md'],
+ * });
+ * builder.build().catch(err => console.error(err));
+ * ```
+ */
+export class CompactBuilder {
+    options;
+    steps;
+    /**
+     * Constructs a new CompactBuilder instance.
+     * @param options - Compiler + builder options (see {@link BuilderOptions}).
+     */
+    constructor(options = {}) {
+        this.options = options;
+        this.steps = this.buildSteps();
+    }
+    /**
+     * Factory method to create a CompactBuilder from command-line arguments.
+     *
+     * @param args - Array of command-line arguments
+     * @param env - Environment variables (defaults to process.env)
+     * @returns New CompactBuilder instance configured from arguments
+     */
+    static fromArgs(args, env = process.env) {
+        const options = CompactBuilder.parseArgs(args, env);
+        return new CompactBuilder(options);
+    }
+    /**
+     * Parses command-line arguments into {@link BuilderOptions}.
+     * Builder-only flags are extracted here; remaining args are forwarded to
+     * {@link CompactCompiler.parseArgs} for compiler-side parsing.
+     *
+     * Builder-only flags (compiler flags like `--hierarchical` and `--exclude`
+     * are forwarded to {@link CompactCompiler.parseArgs}):
+     * - `--clean-dist`            - rm -rf dist before building
+     * - `--copy <path>`           - copy an extra file into dist/ (repeatable)
+     *
+     * @throws {Error} If `--copy` is provided without a value.
+     */
+    static parseArgs(args, env = process.env) {
+        const builderOnly = {};
+        const compilerArgs = [];
+        for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            if (arg === '--clean-dist') {
+                builderOnly.cleanDist = true;
+            }
+            else if (arg === '--copy') {
+                const value = args[i + 1];
+                if (value === undefined || value.startsWith('--')) {
+                    throw new Error('--copy flag requires a path');
+                }
+                builderOnly.copyToDist ??= [];
+                builderOnly.copyToDist.push(value);
+                i++;
+            }
+            else {
+                compilerArgs.push(arg);
+            }
+        }
+        const compilerOptions = CompactCompiler.parseArgs(compilerArgs, env);
+        return { ...compilerOptions, ...builderOnly };
+    }
+    /**
+     * Executes the full build process: compiles .compact files first, then runs build steps.
+     * Displays progress with spinners and outputs results in color.
+     *
+     * @returns A promise that resolves when all steps complete successfully
+     * @throws Error if compilation or any build step fails
+     */
+    async build() {
+        // Run compact compilation as a prerequisite. CompactCompiler ignores
+        // BuilderOnlyOptions because they aren't in its resolved shape.
+        const compiler = new CompactCompiler(this.options);
+        await compiler.compile();
+        for (const [index, step] of this.steps.entries()) {
+            await this.executeStep(step, index, this.steps.length);
+        }
+    }
+    /**
+     * Exposes the resolved build steps. Public for testing/introspection.
+     */
+    getSteps() {
+        return this.steps;
+    }
+    /**
+     * Assembles the build-step pipeline from the configured options.
+     */
+    buildSteps() {
+        const srcDir = this.options.srcDir ?? 'src';
+        const quotedSrc = shellQuote(srcDir);
+        const excludes = buildFindExcludes(this.options.exclude ?? DEFAULT_EXCLUDE_PATTERNS);
+        const steps = [];
+        if (this.options.cleanDist) {
+            steps.push({
+                cmd: 'rm -rf dist && mkdir -p dist',
+                msg: 'Cleaning dist directory',
+                shell: '/bin/bash',
+            });
+        }
+        steps.push({
+            cmd: 'tsc --project tsconfig.build.json',
+            msg: 'Compiling TypeScript',
+        });
+        steps.push({
+            cmd: `mkdir -p dist/artifacts && cp -Rf ${quotedSrc}/artifacts/* dist/artifacts/ 2>/dev/null || true`,
+            msg: 'Copying artifacts',
+            shell: '/bin/bash',
+        });
+        if (this.options.hierarchical) {
+            steps.push({
+                // biome-ignore-start lint/suspicious/noUselessEscapeInString: shell vars must survive JS template-literal interpolation
+                cmd: `
+          SRC_DIR=${quotedSrc}
+          find "$SRC_DIR" -type f -name '*.compact' ${excludes} | while read -r file; do
+            rel_path="\${file#$SRC_DIR/}"
+            mkdir -p "dist/$(dirname "$rel_path")"
+            cp "$file" "dist/$rel_path"
+          done
+        `,
+                // biome-ignore-end lint/suspicious/noUselessEscapeInString: shell vars must survive JS template-literal interpolation
+                msg: 'Copying .compact files (preserving structure)',
+                shell: '/bin/bash',
+            });
+        }
+        else {
+            steps.push({
+                cmd: `mkdir -p dist && find ${quotedSrc} -type f -name '*.compact' ${excludes} -exec cp {} dist/ \\; 2>/dev/null || true`,
+                msg: 'Copying .compact files',
+                shell: '/bin/bash',
+            });
+        }
+        const copyTargets = this.options.copyToDist ?? [];
+        if (copyTargets.length > 0) {
+            const copyCmds = copyTargets
+                .map((path) => `cp ${shellQuote(path)} dist/ 2>/dev/null || true`)
+                .join(' && ');
+            steps.push({
+                cmd: `mkdir -p dist && ${copyCmds}`,
+                msg: 'Copying additional files to dist',
+                shell: '/bin/bash',
+            });
+        }
+        return steps;
+    }
+    /**
+     * Executes a single build step.
+     * Runs the command, shows a spinner, and prints output with indentation.
+     *
+     * @param step - The build step containing command and message
+     * @param index - Current step index (0-based) for progress display
+     * @param total - Total number of steps for progress display
+     * @returns A promise that resolves when the step completes successfully
+     * @throws Error if the step fails
+     */
+    async executeStep(step, index, total) {
+        const stepLabel = `[${index + 1}/${total}]`;
+        const spinner = ora(`[BUILD] ${stepLabel} ${step.msg}`).start();
+        try {
+            const { stdout, stderr } = await execAsync(step.cmd, {
+                shell: step.shell, // Only pass shell where needed
+            });
+            spinner.succeed(`[BUILD] ${stepLabel} ${step.msg}`);
+            this.printOutput(stdout, chalk.cyan);
+            this.printOutput(stderr, chalk.yellow); // Show stderr (warnings) in yellow if present
+        }
+        catch (error) {
+            spinner.fail(`[BUILD] ${stepLabel} ${step.msg}`);
+            if (isPromisifiedChildProcessError(error)) {
+                this.printOutput(error.stdout, chalk.cyan);
+                this.printOutput(error.stderr, chalk.red);
+                // biome-ignore lint/suspicious/noConsole: Needed to display build failure reason
+                console.error(chalk.red('[BUILD] ❌ Build failed:', error.message));
+            }
+            else if (error instanceof Error) {
+                // biome-ignore lint/suspicious/noConsole: Needed to display build failure reason
+                console.error(chalk.red('[BUILD] ❌ Build failed:', error.message));
+            }
+            // Library code must not call process.exit — let the caller (CLI wrapper
+            // or programmatic consumer) decide how to react. We've already surfaced
+            // the failure to the user via the spinner + printOutput above.
+            if (error instanceof Error) {
+                throw error;
+            }
+            throw new Error('[BUILD] Build failed with a non-Error exception');
+        }
+    }
+    /**
+     * Prints command output with indentation and specified color.
+     * Filters out empty lines and indents each line for readability.
+     *
+     * @param output - The command output string to print (stdout or stderr)
+     * @param colorFn - Chalk color function to style the output (e.g., `chalk.cyan` for success, `chalk.red` for errors)
+     */
+    printOutput(output, colorFn) {
+        const lines = output
+            .split('\n')
+            .filter((line) => line.trim() !== '')
+            .map((line) => `    ${line}`);
+        console.log(colorFn(lines.join('\n')));
+    }
+}
+//# sourceMappingURL=Builder.js.map

package/dist/Builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Builder.js","sourceRoot":"","sources":["../src/Builder.ts"],"names":[],"mappings":"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"}

package/dist/Compiler.d.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { type CompilerOptions, type CompilerServiceOptions, type ExecFunction } from './types/options.ts';
+export { CompilerService } from './services/CompilerService.ts';
+export { EnvironmentValidator } from './services/EnvironmentValidator.ts';
+export { FileDiscovery } from './services/FileDiscovery.ts';
+export { UIService } from './services/UIService.ts';
+export type { CompilerOptions, CompilerServiceOptions, ExecFunction };
+/** Resolved compiler options with defaults applied */
+type ResolvedCompilerOptions = Required<Pick<CompilerOptions, 'flags' | 'hierarchical' | 'srcDir' | 'outDir' | 'exclude'>> & Pick<CompilerOptions, 'targetDir' | 'version'>;
+/**
+ * Main compiler class that orchestrates the compilation process.
+ * Coordinates environment validation, file discovery, and compilation services
+ * to provide a complete .compact file compilation solution.
+ *
+ * Features:
+ * - Dependency injection for testability
+ * - Structured error propagation with custom error types
+ * - Progress reporting and user feedback
+ * - Support for compiler flags and toolchain versions
+ * - Environment variable integration
+ * - Configurable artifact output structure (flattened or hierarchical)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with options object (flattened artifacts by default)
+ * const compiler = new CompactCompiler({
+ *   flags: '--skip-zk',
+ *   targetDir: 'security',
+ *   version: '0.26.0',
+ * });
+ * await compiler.compile();
+ *
+ * // Factory method usage
+ * const compiler = CompactCompiler.fromArgs(['--dir', 'security', '--skip-zk']);
+ * await compiler.compile();
+ *
+ * // With hierarchical artifacts structure
+ * const compiler = CompactCompiler.fromArgs(['--hierarchical', '--skip-zk']);
+ * await compiler.compile();
+ *
+ * // With environment variables
+ * process.env.SKIP_ZK = 'true';
+ * const compiler = CompactCompiler.fromArgs(['--dir', 'token']);
+ * await compiler.compile();
+ * ```
+ */
+export declare class CompactCompiler {
+    /** Environment validation service */
+    private readonly environmentValidator;
+    /** File discovery service */
+    private readonly fileDiscovery;
+    /** Compilation execution service */
+    private readonly compilerService;
+    /** Compiler options */
+    private readonly options;
+    /**
+     * Creates a new CompactCompiler instance with specified configuration.
+     *
+     * @param options - Compiler configuration options
+     * @param execFn  - Optional custom exec function for dependency injection
+     */
+    constructor(options?: CompilerOptions, execFn?: ExecFunction);
+    /**
+     * Parses command-line arguments into a CompilerOptions object.
+     *
+     * Supported argument patterns:
+     * - `--dir <directory>` - Target specific subdirectory within srcDir
+     * - `--src <directory>` - Source directory containing .compact files (default: 'src')
+     * - `--out <directory>` - Output directory for artifacts (default: 'artifacts')
+     * - `--hierarchical` - Preserve source directory structure in artifacts output
+     * - `--exclude <pattern>` - Skip `.compact` files matching the glob pattern (repeatable)
+     * - `+<version>` - Use specific toolchain version
+     * - Other arguments - Treated as compiler flags
+     * - `SKIP_ZK=true` environment variable - Adds --skip-zk flag
+     *
+     * @param args - Array of command-line arguments
+     * @param env  - Environment variables (defaults to process.env)
+     * @returns Parsed CompilerOptions object
+     * @throws {Error} If --dir, --src, --out, or --exclude is provided without a value
+     */
+    static parseArgs(args: string[], env?: typeof process.env): CompilerOptions;
+    /**
+     * Factory method to create a CompactCompiler from command-line arguments.
+     * See {@link CompactCompiler.parseArgs} for the supported argument shapes.
+     *
+     * @param args - Array of command-line arguments
+     * @param env  - Environment variables (defaults to process.env)
+     * @returns New CompactCompiler instance configured from arguments
+     * @throws {Error} If --dir, --src, --out, or --exclude is provided without a value
+     */
+    static fromArgs(args: string[], env?: typeof process.env): CompactCompiler;
+    /**
+     * Validates the compilation environment and displays version information.
+     *
+     * @throws {CompactCliNotFoundError} If Compact CLI is not available in PATH
+     * @throws {Error} If version retrieval or other validation steps fail
+     */
+    validateEnvironment(): Promise<void>;
+    /**
+     * Main compilation method that orchestrates the entire compilation process.
+     *
+     * @throws {CompactCliNotFoundError} If Compact CLI is not available
+     * @throws {DirectoryNotFoundError} If target directory doesn't exist
+     * @throws {CompilationError} If any file compilation fails
+     */
+    compile(): Promise<void>;
+    /**
+     * Compiles a single file with progress reporting and error handling.
+     *
+     * @param file  - Relative path to the .compact file
+     * @param index - Current file index (0-based) for progress tracking
+     * @param total - Total number of files being compiled
+     * @throws {CompilationError} If compilation fails
+     */
+    private compileFile;
+    /**
+     * For testing - returns the resolved options object
+     */
+    get testOptions(): ResolvedCompilerOptions;
+}