balm-core 5.2.0 → 6.0.0-alpha.1

package/src/hooks/index.ts

@@ -0,0 +1,224 @@
+import {
+  CopyTask,
+  RemoveTask,
+  ReplaceTask,
+  PublishTask,
+  PwaTask,
+  ZipTask,
+  FtpTask,
+  ServerTask
+} from '../tasks/index.js';
+import { FunctionTask } from '../runner/task.js';
+import { Pipeline } from '../pipeline/pipeline.js';
+import { transformSass } from '../pipeline/transforms/sass.js';
+import { transformLess } from '../pipeline/transforms/less.js';
+import { transformPostcss } from '../pipeline/transforms/postcss.js';
+import { runWebpack } from '../bundler/webpack.js';
+import { runRollup } from '../bundler/rollup.js';
+import { runEsbuild } from '../bundler/esbuild.js';
+import { TaskDAG } from '../runner/dag.js';
+import {
+  RenameOptions,
+  ReplaceOptions,
+  TemplateOption,
+  BalmConfig
+} from '../types/index.js';
+import { logger } from '../utilities/logger.js';
+
+export class BalmHooks {
+  private dag: TaskDAG;
+  private _config: BalmConfig;
+  private recipeIndex = 0;
+
+  constructor(dag: TaskDAG, config: BalmConfig) {
+    this.dag = dag;
+    this._config = config;
+  }
+
+  get config(): BalmConfig {
+    return this._config;
+  }
+
+  get env() {
+    return this._config.env;
+  }
+
+  private addRecipeTask(fn: (config: BalmConfig) => Promise<void> | void): void {
+    this.recipeIndex++;
+    const taskName = `recipe:${this.recipeIndex}`;
+    this.dag.registerTask(new FunctionTask(taskName, fn));
+  }
+
+  copy(
+    input: string | string[],
+    output: string,
+    options: { rename?: RenameOptions | string | Function } = {}
+  ): this {
+    this.addRecipeTask(async (config) => {
+      const task = new CopyTask({ input, output, rename: options.rename });
+      await task.run(config);
+    });
+    return this;
+  }
+
+  remove(target: string | string[]): this {
+    this.addRecipeTask(async (config) => {
+      const task = new RemoveTask(target);
+      await task.run(config);
+    });
+    return this;
+  }
+
+  replace(
+    input: string | string[],
+    output: string,
+    options: ReplaceOptions | ReplaceOptions[]
+  ): this {
+    this.addRecipeTask(async (config) => {
+      const task = new ReplaceTask({ input, output, options });
+      await task.run(config);
+    });
+    return this;
+  }
+
+  sass(input: string | string[], output: string, options = {}): this {
+    this.addRecipeTask(async (config) => {
+      const pipeline = Pipeline.from(input, { cwd: config.workspace });
+      pipeline.pipe(transformSass(options));
+      pipeline.pipe(transformPostcss({ minify: config.env.isProd }));
+      await pipeline.dest(output);
+    });
+    return this;
+  }
+
+  less(input: string | string[], output: string, options = {}): this {
+    this.addRecipeTask(async (config) => {
+      const pipeline = Pipeline.from(input, { cwd: config.workspace });
+      pipeline.pipe(transformLess(options));
+      pipeline.pipe(transformPostcss({ minify: config.env.isProd }));
+      await pipeline.dest(output);
+    });
+    return this;
+  }
+
+  css(input: string | string[], output: string, options = {}): this {
+    this.addRecipeTask(async (config) => {
+      const pipeline = Pipeline.from(input, { cwd: config.workspace });
+      pipeline.pipe(transformPostcss({ minify: config.env.isProd, ...options }));
+      await pipeline.dest(output);
+    });
+    return this;
+  }
+
+  webpack(entry?: any, output?: string, customOptions: any = {}): this {
+    this.addRecipeTask(async (config) => {
+      const mergedOptions = {
+        ...customOptions,
+        ...(entry ? { entry } : {}),
+        output: {
+          ...(output ? { path: output } : {}),
+          ...customOptions.output
+        }
+      };
+      await runWebpack(config, mergedOptions);
+    });
+    return this;
+  }
+
+  rollup(
+    input?: any,
+    output?: any,
+    customInputOptions: any = {},
+    customOutputOptions: any = {}
+  ): this {
+    this.addRecipeTask(async (config) => {
+      let inputOptions: any = {};
+      let outputOptions: any = {};
+
+      if (typeof input === 'object' && !Array.isArray(input) && input.input) {
+        inputOptions = { ...input, ...customInputOptions };
+        outputOptions =
+          typeof output === 'object'
+            ? { ...output, ...customOutputOptions }
+            : { ...(output ? { dir: output } : {}), ...customOutputOptions };
+      } else {
+        inputOptions = { ...(input ? { input } : {}), ...customInputOptions };
+        outputOptions =
+          typeof output === 'object'
+            ? { ...output, ...customOutputOptions }
+            : { ...(output ? { dir: output } : {}), ...customOutputOptions };
+      }
+
+      await runRollup(config, inputOptions, outputOptions);
+    });
+    return this;
+  }
+
+  esbuild(entryPoints?: any, outdir?: string, customOptions = {}): this {
+    this.addRecipeTask(async (config) => {
+      await runEsbuild(config, {
+        ...(entryPoints ? { entryPoints } : {}),
+        ...(outdir ? { outdir } : {}),
+        ...customOptions
+      });
+    });
+    return this;
+  }
+
+  js(input?: any, output?: any, options = {}): this {
+    logger.warn('balm api', '`mix.js` is deprecated, please use `mix.webpack`/`mix.rollup`/`mix.esbuild` instead.');
+    return this.webpack(input, output, options);
+  }
+
+  publish(
+    input?: string | TemplateOption[],
+    output?: string,
+    renameOptions?: string | Function | RenameOptions
+  ): this {
+    this.addRecipeTask(async (config) => {
+      const task = new PublishTask({ input, output, renameOptions });
+      await task.run(config);
+    });
+    return this;
+  }
+
+  generateSW(options = {}): this {
+    this.addRecipeTask(async (config) => {
+      const task = new PwaTask({ mode: 'generateSW', options });
+      await task.run(config);
+    });
+    return this;
+  }
+
+  injectManifest(options = {}): this {
+    this.addRecipeTask(async (config) => {
+      const task = new PwaTask({ mode: 'injectManifest', options });
+      await task.run(config);
+    });
+    return this;
+  }
+
+  ftp(localFiles?: string | string[], options = {}): this {
+    this.addRecipeTask(async (config) => {
+      const task = new FtpTask({ localFiles, options });
+      await task.run(config);
+    });
+    return this;
+  }
+
+  zip(input?: string | string[], output?: string, filename?: string): this {
+    this.addRecipeTask(async (config) => {
+      const task = new ZipTask({ input, output, filename });
+      await task.run(config);
+    });
+    return this;
+  }
+
+  serve(): this {
+    this.addRecipeTask(async (config) => {
+      const task = new ServerTask();
+      await task.run(config);
+    });
+    return this;
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+import { balm, Balm } from './balm.js';
+
+export default balm;
+export { Balm, balm };
+export * from './types/index.js';
+export * from './config/index.js';
+export * from './runner/task.js';
+export * from './runner/dag.js';
+export * from './pipeline/index.js';
+export * from './bundler/index.js';
+export * from './tasks/index.js';
+export * from './hooks/index.js';
+export * from './utilities/logger.js';
+export * from './utilities/file.js';
+export * from './utilities/utils.js';
+export * from './utilities/workspace.js';

package/src/pipeline/file.ts

@@ -0,0 +1,69 @@
+import path from 'node:path';
+
+export interface VirtualFileOptions {
+  cwd: string;
+  base: string;
+  path: string;
+  contents: Buffer | string;
+}
+
+export class VirtualFile {
+  cwd: string;
+  base: string;
+  path: string;
+  contents: Buffer;
+  revPathOriginal?: string;
+
+  constructor(options: VirtualFileOptions) {
+    this.cwd = options.cwd;
+    this.base = options.base;
+    this.path = options.path;
+    this.contents = typeof options.contents === 'string'
+      ? Buffer.from(options.contents)
+      : options.contents;
+  }
+
+  get relative(): string {
+    return path.relative(this.base, this.path);
+  }
+
+  get extname(): string {
+    return path.extname(this.path);
+  }
+  set extname(val: string) {
+    const dir = path.dirname(this.path);
+    const basename = path.basename(this.path, this.extname);
+    this.path = path.join(dir, `${basename}${val.startsWith('.') ? val : `.${val}`}`);
+  }
+
+  get basename(): string {
+    return path.basename(this.path);
+  }
+  set basename(val: string) {
+    const dir = path.dirname(this.path);
+    this.path = path.join(dir, val);
+  }
+
+  get stem(): string {
+    return path.basename(this.path, this.extname);
+  }
+  set stem(val: string) {
+    const dir = path.dirname(this.path);
+    this.path = path.join(dir, `${val}${this.extname}`);
+  }
+
+  toString(encoding: BufferEncoding = 'utf8'): string {
+    return this.contents.toString(encoding);
+  }
+
+  clone(): VirtualFile {
+    const cloned = new VirtualFile({
+      cwd: this.cwd,
+      base: this.base,
+      path: this.path,
+      contents: Buffer.from(this.contents)
+    });
+    cloned.revPathOriginal = this.revPathOriginal;
+    return cloned;
+  }
+}

package/src/pipeline/index.ts

@@ -0,0 +1,10 @@
+export * from './file.js';
+export * from './pipeline.js';
+export * from './transforms/sass.js';
+export * from './transforms/less.js';
+export * from './transforms/postcss.js';
+export * from './transforms/htmlmin.js';
+export * from './transforms/terser.js';
+export * from './transforms/replace.js';
+export * from './transforms/rename.js';
+export * from './transforms/cache.js';

package/src/pipeline/pipeline.ts

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import fg from 'fast-glob';
+import fs from 'node:fs/promises';
+import { VirtualFile } from './file.js';
+import { file as fsUtil } from '../utilities/file.js';
+
+export type TransformFn = (
+  file: VirtualFile
+) => Promise<VirtualFile | VirtualFile[] | null | void> | VirtualFile | VirtualFile[] | null | void;
+
+export interface PipelineOptions {
+  cwd?: string;
+  base?: string;
+  allowEmpty?: boolean;
+}
+
+export class Pipeline {
+  private cwd: string;
+  private base?: string;
+  private allowEmpty: boolean;
+  private files: VirtualFile[] = [];
+  private transforms: TransformFn[] = [];
+
+  constructor(options: PipelineOptions = {}) {
+    this.cwd = options.cwd || process.cwd();
+    this.base = options.base;
+    this.allowEmpty = options.allowEmpty ?? true;
+  }
+
+  static from(
+    patterns: string | string[],
+    options: PipelineOptions = {}
+  ): Pipeline {
+    const pipeline = new Pipeline(options);
+    return pipeline.src(patterns);
+  }
+
+  src(patterns: string | string[], options: PipelineOptions = {}): this {
+    if (options.cwd) this.cwd = options.cwd;
+    if (options.base) this.base = options.base;
+    if (options.allowEmpty !== undefined) this.allowEmpty = options.allowEmpty;
+
+    this.transforms.push(async () => {
+      const patternArr = Array.isArray(patterns) ? patterns : [patterns];
+      const posPatterns = patternArr.filter((p) => !p.startsWith('!'));
+      const ignorePatterns = patternArr.filter((p) => p.startsWith('!')).map((p) => p.slice(1));
+
+      const fileList: VirtualFile[] = [];
+      for (const p of posPatterns) {
+        let patternBase = this.base;
+        if (!patternBase) {
+          const globIdx = p.search(/[*?{[\\]/);
+          if (globIdx !== -1) {
+            patternBase = path.resolve(this.cwd, p.slice(0, globIdx));
+          } else {
+            patternBase = path.resolve(this.cwd, path.dirname(p));
+          }
+        }
+
+        const matched = await fg(p, {
+          cwd: this.cwd,
+          absolute: true,
+          dot: true,
+          onlyFiles: true,
+          ignore: ignorePatterns
+        });
+
+        for (const filePath of matched) {
+          const buffer = await fs.readFile(filePath);
+          fileList.push(
+            new VirtualFile({
+              cwd: this.cwd,
+              base: patternBase,
+              path: filePath,
+              contents: buffer
+            })
+          );
+        }
+      }
+
+      if (!fileList.length && !this.allowEmpty) {
+        throw new Error(`File not found with pattern: ${patterns}`);
+      }
+
+      this.files = fileList;
+    });
+
+    return this;
+  }
+
+  pipe(transform: TransformFn): this {
+    this.transforms.push(transform);
+    return this;
+  }
+
+  async process(): Promise<VirtualFile[]> {
+    let isSrcLoaded = false;
+    for (const transform of this.transforms) {
+      if (!isSrcLoaded) {
+        // Initial src loader
+        await transform(null as any);
+        isSrcLoaded = true;
+      } else {
+        if (this.files.length === 0) break;
+        const nextFiles: VirtualFile[] = [];
+        for (const file of this.files) {
+          const result = await transform(file);
+          if (result === undefined || result === file) {
+            nextFiles.push(file);
+          } else if (Array.isArray(result)) {
+            nextFiles.push(...result);
+          } else if (result !== null) {
+            nextFiles.push(result);
+          }
+        }
+        this.files = nextFiles;
+      }
+    }
+    return this.files;
+  }
+
+  async dest(outDir: string): Promise<string[]> {
+    const files = await this.process();
+    const writtenPaths: string[] = [];
+    const absOutDir = path.isAbsolute(outDir) ? outDir : path.resolve(this.cwd, outDir);
+
+    for (const file of files) {
+      const targetPath = path.resolve(absOutDir, file.relative);
+      await fsUtil.writeFile(targetPath, file.contents);
+      writtenPaths.push(targetPath);
+    }
+
+    return writtenPaths;
+  }
+}

package/src/pipeline/transforms/cache.ts

@@ -0,0 +1,146 @@
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { VirtualFile } from '../file.js';
+import { file as fsUtil } from '../../utilities/file.js';
+
+export interface CacheTransformOptions {
+  fileNameManifest?: string;
+  dontRenameFile?: (string | RegExp)[];
+  dontUpdateReference?: (string | RegExp)[];
+  hashLength?: number;
+  [key: string]: any;
+}
+
+function matchesAny(filePath: string, rules?: (string | RegExp)[]): boolean {
+  if (!rules || !rules.length) return false;
+  const normalized = filePath.replace(/\\/g, '/');
+  const baseName = path.basename(normalized);
+  for (const rawRule of rules) {
+    if (typeof rawRule === 'string') {
+      const rule = rawRule.replace(/\\/g, '/');
+      const cleanRule = rule.replace(/^dist\//, '').replace(/^\.\/dist\//, '');
+      if (
+        normalized.endsWith(rule) ||
+        normalized.endsWith(cleanRule) ||
+        baseName === rule ||
+        baseName === cleanRule ||
+        baseName.endsWith(rule) ||
+        picomatch.isMatch(normalized, rule) ||
+        picomatch.isMatch(normalized, cleanRule) ||
+        picomatch.isMatch(normalized, `**/${cleanRule}`) ||
+        picomatch.isMatch(baseName, rule) ||
+        picomatch.isMatch(baseName, cleanRule)
+      ) {
+        return true;
+      }
+    } else if (rawRule instanceof RegExp) {
+      if (rawRule.test(normalized) || rawRule.test(baseName)) return true;
+    }
+  }
+  return false;
+}
+
+export class AssetRevisioner {
+  private options: CacheTransformOptions;
+  private manifest: Record<string, string> = {};
+
+  constructor(options: CacheTransformOptions = {}) {
+    const baseDontRename = [
+      '.html',
+      'favicon.ico',
+      'manifest.json',
+      'robots.txt',
+      '*.ico',
+      'workbox-sw.js',
+      'workbox-sw.js.map',
+      'service-worker.js',
+      'sw.js'
+    ];
+    this.options = {
+      fileNameManifest: 'rev-manifest.json',
+      dontRenameFile: baseDontRename,
+      dontUpdateReference: [],
+      hashLength: 8,
+      ...options
+    };
+    if (options.dontRenameFile) {
+      this.options.dontRenameFile = [
+        ...baseDontRename,
+        ...options.dontRenameFile
+      ];
+    }
+  }
+
+  process(files: VirtualFile[]): VirtualFile[] {
+    const hashLength = this.options.hashLength || 8;
+    const outputFiles: VirtualFile[] = [];
+
+    // Phase 1: Calculate hashes and renames
+    for (const file of files) {
+      const origRelative = file.relative;
+      file.revPathOriginal = file.path;
+
+      // Check if file is already hashed (e.g. app.0e94aeee.js or chunk.22810145.js)
+      const alreadyHashed = /\.[a-f0-9]{8}$/i.test(file.stem);
+
+      const shouldRename =
+        !alreadyHashed &&
+        !matchesAny(file.path, this.options.dontRenameFile) &&
+        !matchesAny(file.relative, this.options.dontRenameFile);
+
+      if (shouldRename) {
+        const fileHash = fsUtil.hash(file.contents, hashLength);
+        const dir = path.dirname(file.path);
+        const newFilename = `${file.stem}.${fileHash}${file.extname}`;
+        file.path = path.join(dir, newFilename);
+      }
+
+      if (alreadyHashed) {
+        const unhashedRelative = file.relative.replace(/\.[a-f0-9]{8}(\.[^.]+)$/i, '$1');
+        this.manifest[unhashedRelative] = file.relative;
+      }
+      this.manifest[origRelative] = file.relative;
+      outputFiles.push(file);
+    }
+
+    // Phase 2: Rewrite references
+    const manifestEntries = Object.entries(this.manifest)
+      .filter(([orig, reved]) => orig !== reved)
+      .sort((a, b) => b[0].length - a[0].length);
+
+    for (const file of outputFiles) {
+      const shouldUpdate =
+        !matchesAny(file.path, this.options.dontUpdateReference) &&
+        !matchesAny(file.relative, this.options.dontUpdateReference);
+
+      if (shouldUpdate && /\.(html|css|js)$/i.test(file.extname)) {
+        let content = file.toString();
+        for (const [orig, reved] of manifestEntries) {
+          // Replace full relative path first
+          content = content.replaceAll(orig, reved);
+
+          // Replace basename with boundary check to avoid substring collision (e.g. .woff matching .woff2)
+          const origBase = path.basename(orig);
+          const revedBase = path.basename(reved);
+          const escapedBase = origBase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+          const baseRegex = new RegExp(`${escapedBase}(?![a-zA-Z0-9_])`, 'g');
+          content = content.replace(baseRegex, revedBase);
+        }
+        file.contents = Buffer.from(content);
+      }
+    }
+
+    // Phase 3: Add manifest file
+    const manifestName = this.options.fileNameManifest || 'rev-manifest.json';
+    const firstBase = files[0]?.base || process.cwd();
+    const manifestFile = new VirtualFile({
+      cwd: files[0]?.cwd || process.cwd(),
+      base: firstBase,
+      path: path.join(firstBase, manifestName),
+      contents: JSON.stringify(this.manifest, null, 2)
+    });
+    outputFiles.push(manifestFile);
+
+    return outputFiles;
+  }
+}

package/src/pipeline/transforms/htmlmin.ts

@@ -0,0 +1,18 @@
+import { minify } from 'html-minifier-terser';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export function transformHtmlmin(options: Record<string, any> = {}): TransformFn {
+  return async (file) => {
+    if (!/\.html$/i.test(file.extname)) return file;
+
+    try {
+      const minified = await minify(file.toString(), options);
+      file.contents = Buffer.from(minified);
+      return file;
+    } catch (err: any) {
+      logger.error('htmlmin', `Error minifying ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}

package/src/pipeline/transforms/less.ts

@@ -0,0 +1,75 @@
+import less from 'less';
+import path from 'node:path';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export interface LessTransformOptions {
+  paths?: string[];
+  alias?: Record<string, string>;
+  [key: string]: any;
+}
+
+class AliasFileManager extends less.FileManager {
+  private alias: Record<string, string>;
+
+  constructor(alias: Record<string, string> = {}) {
+    super();
+    this.alias = alias;
+  }
+
+  supports(filename: string): boolean {
+    const clean = filename.startsWith('~') ? filename.slice(1) : filename;
+    return Object.keys(this.alias).some((k) => clean === k || clean.startsWith(`${k}/`));
+  }
+
+  loadFile(filename: string, currentDirectory: string, options: any, environment: any): Promise<any> {
+    const clean = filename.startsWith('~') ? filename.slice(1) : filename;
+    for (const [k, v] of Object.entries(this.alias)) {
+      if (clean === k) {
+        return super.loadFile(v, currentDirectory, options, environment);
+      } else if (clean.startsWith(`${k}/`)) {
+        const sub = clean.slice(k.length + 1);
+        return super.loadFile(path.join(v, sub), currentDirectory, options, environment);
+      }
+    }
+    return super.loadFile(filename, currentDirectory, options, environment);
+  }
+}
+
+export function transformLess(options: LessTransformOptions = {}): TransformFn {
+  return async (file) => {
+    if (!/\.less$/i.test(file.extname)) return file;
+    if (path.basename(file.path).startsWith('_')) return null;
+
+    try {
+      const paths = [
+        path.dirname(file.path),
+        path.resolve(file.cwd, 'node_modules'),
+        ...(options.paths || [])
+      ];
+
+      const plugins = [...(options.plugins || [])];
+      if (options.alias && Object.keys(options.alias).length > 0) {
+        plugins.push({
+          install: (lessInstance: any, pluginManager: any) => {
+            pluginManager.addFileManager(new AliasFileManager(options.alias));
+          }
+        });
+      }
+
+      const result = await less.render(file.toString(), {
+        filename: file.path,
+        paths,
+        ...options,
+        plugins
+      });
+
+      file.contents = Buffer.from(result.css);
+      file.extname = '.css';
+      return file;
+    } catch (err: any) {
+      logger.error('less', `Error compiling ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}