balm-core 5.2.0 → 6.0.0-alpha.1

package/src/pipeline/transforms/postcss.ts

@@ -0,0 +1,43 @@
+import postcss, { AcceptedPlugin } from 'postcss';
+import autoprefixer from 'autoprefixer';
+import postcssPresetEnv from 'postcss-preset-env';
+import cssnano from 'cssnano';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export interface PostcssTransformOptions {
+  plugins?: AcceptedPlugin[];
+  minify?: boolean;
+  [key: string]: any;
+}
+
+export function transformPostcss(options: PostcssTransformOptions = {}): TransformFn {
+  const plugins: AcceptedPlugin[] = [
+    ...(options.plugins || []),
+    autoprefixer(),
+    postcssPresetEnv()
+  ];
+
+  if (options.minify) {
+    plugins.push(cssnano({ preset: 'default' }));
+  }
+
+  const processor = postcss(plugins);
+
+  return async (file) => {
+    if (!/\.css$/i.test(file.extname)) return file;
+
+    try {
+      const result = await processor.process(file.toString(), {
+        from: file.path,
+        to: file.path
+      });
+
+      file.contents = Buffer.from(result.css);
+      return file;
+    } catch (err: any) {
+      logger.error('postcss', `Error processing ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}

package/src/pipeline/transforms/rename.ts

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { TransformFn } from '../pipeline.js';
+import { RenameOptions } from '../../types/index.js';
+
+export function transformRename(
+  options: string | Function | RenameOptions = {}
+): TransformFn {
+  return async (file) => {
+    if (typeof options === 'string') {
+      file.path = path.resolve(path.dirname(file.path), options);
+      return file;
+    }
+
+    if (typeof options === 'function') {
+      const parsed = {
+        dirname: path.dirname(file.path),
+        basename: file.stem,
+        extname: file.extname
+      };
+      const result = options(parsed);
+      if (result) {
+        if (result.dirname) file.path = path.join(result.dirname, path.basename(file.path));
+        if (result.basename) file.stem = result.basename;
+        if (result.extname) file.extname = result.extname;
+      }
+      return file;
+    }
+
+    const { dirname, prefix = '', basename, suffix = '', extname } = options;
+    const currentDir = dirname ? path.resolve(file.cwd, dirname) : path.dirname(file.path);
+    const base = basename !== undefined ? basename : file.stem;
+    const ext = extname !== undefined ? extname : file.extname;
+
+    file.path = path.join(currentDir, `${prefix}${base}${suffix}${ext.startsWith('.') ? ext : `.${ext}`}`);
+    return file;
+  };
+}

package/src/pipeline/transforms/replace.ts

@@ -0,0 +1,30 @@
+import { TransformFn } from '../pipeline.js';
+import { ReplaceOptions } from '../../types/index.js';
+
+export function transformReplace(
+  options: ReplaceOptions | ReplaceOptions[] | string | RegExp,
+  replacement?: string | ((substring: string, ...args: any[]) => string)
+): TransformFn {
+  let rules: ReplaceOptions[] = [];
+
+  if (Array.isArray(options)) {
+    rules = options;
+  } else if (typeof options === 'object' && 'substr' in options) {
+    rules = [options];
+  } else if (typeof options === 'string' || options instanceof RegExp) {
+    rules = [{ substr: options, replacement: replacement || '' }];
+  }
+
+  return async (file) => {
+    let content = file.toString();
+    for (const rule of rules) {
+      if (typeof rule.replacement === 'function') {
+        content = content.replace(rule.substr, rule.replacement as any);
+      } else {
+        content = content.replace(rule.substr, rule.replacement);
+      }
+    }
+    file.contents = Buffer.from(content);
+    return file;
+  };
+}

package/src/pipeline/transforms/sass.ts

@@ -0,0 +1,106 @@
+import * as sass from 'sass';
+import path from 'node:path';
+import fs from 'node:fs';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export interface SassTransformOptions {
+  includePaths?: string[];
+  alias?: Record<string, string>;
+  style?: 'expanded' | 'compressed';
+  sourceMap?: boolean;
+  [key: string]: any;
+}
+
+function resolveFile(baseDir: string, url: string): string | null {
+  const possiblePaths = [
+    path.resolve(baseDir, url),
+    path.resolve(baseDir, `${url}.scss`),
+    path.resolve(baseDir, `${url}.sass`),
+    path.resolve(baseDir, `${url}.css`),
+    path.resolve(baseDir, path.dirname(url), `_${path.basename(url)}.scss`),
+    path.resolve(baseDir, path.dirname(url), `_${path.basename(url)}.sass`),
+    path.resolve(baseDir, url, '_index.scss'),
+    path.resolve(baseDir, url, '_index.sass'),
+    path.resolve(baseDir, url, 'index.scss'),
+    path.resolve(baseDir, url, 'index.sass')
+  ];
+
+  for (const p of possiblePaths) {
+    try {
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+        return p;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return null;
+}
+
+export function transformSass(options: SassTransformOptions = {}): TransformFn {
+  return async (file) => {
+    // Only process .scss / .sass files
+    if (!/\.(scss|sass)$/i.test(file.extname)) return file;
+    // Skip partials starting with '_'
+    if (path.basename(file.path).startsWith('_')) return null;
+
+    try {
+      const searchDirs = [
+        path.dirname(file.path),
+        path.resolve(file.cwd, 'node_modules'),
+        path.resolve(process.cwd(), 'node_modules'),
+        path.resolve(process.cwd(), '..', 'node_modules'),
+        ...(options.includePaths || [])
+      ];
+
+      const customImporter: sass.FileImporter<'async'> = {
+        findFileUrl(url) {
+          let cleanUrl = url;
+          if (cleanUrl.startsWith('~')) {
+            cleanUrl = cleanUrl.slice(1);
+          }
+
+          // 1. Check alias resolution
+          if (options.alias) {
+            for (const [aliasKey, aliasTarget] of Object.entries(options.alias)) {
+              if (cleanUrl === aliasKey) {
+                const resolved = resolveFile(path.dirname(aliasTarget), path.basename(aliasTarget));
+                if (resolved) return new URL(`file://${resolved}`);
+              } else if (cleanUrl.startsWith(`${aliasKey}/`)) {
+                const subPath = cleanUrl.slice(aliasKey.length + 1);
+                const resolved = resolveFile(aliasTarget, subPath);
+                if (resolved) return new URL(`file://${resolved}`);
+              }
+            }
+          }
+
+          // 2. Check searchDirs
+          for (const dir of searchDirs) {
+            const resolved = resolveFile(dir, cleanUrl);
+            if (resolved) {
+              return new URL(`file://${resolved}`);
+            }
+          }
+          return null;
+        }
+      };
+
+      const result = await sass.compileStringAsync(file.toString(), {
+        url: new URL(`file://${file.path}`),
+        syntax: file.extname === '.sass' ? 'indented' : 'scss',
+        loadPaths: searchDirs,
+        importers: [customImporter, new sass.NodePackageImporter()],
+        style: options.style || 'expanded',
+        sourceMap: options.sourceMap || false
+      });
+
+      file.contents = Buffer.from(result.css);
+      file.extname = '.css';
+      return file;
+    } catch (err: any) {
+      logger.error('sass', `Error compiling ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}

package/src/pipeline/transforms/terser.ts

@@ -0,0 +1,20 @@
+import { minify, MinifyOptions } from 'terser';
+import { TransformFn } from '../pipeline.js';
+import { logger } from '../../utilities/logger.js';
+
+export function transformTerser(options: MinifyOptions = {}): TransformFn {
+  return async (file) => {
+    if (!/\.js$/i.test(file.extname)) return file;
+
+    try {
+      const result = await minify(file.toString(), options);
+      if (result.code) {
+        file.contents = Buffer.from(result.code);
+      }
+      return file;
+    } catch (err: any) {
+      logger.error('terser', `Error minifying ${file.path}: ${err.message}`);
+      throw err;
+    }
+  };
+}

package/src/runner/dag.ts

@@ -0,0 +1,77 @@
+import { BaseTask } from './task.js';
+import { BalmConfig } from '../types/index.js';
+import { logger } from '../utilities/logger.js';
+import pc from 'picocolors';
+
+export class TaskDAG {
+  private tasks = new Map<string, BaseTask>();
+
+  registerTask(task: BaseTask): void {
+    this.tasks.set(task.name, task);
+  }
+
+  getTask(name: string): BaseTask | undefined {
+    return this.tasks.get(name);
+  }
+
+  hasTask(name: string): boolean {
+    return this.tasks.has(name);
+  }
+
+  clear(): void {
+    this.tasks.clear();
+  }
+
+  /**
+   * Run a list of tasks in strict series
+   */
+  async runSeries(taskNames: string[], config: BalmConfig): Promise<void> {
+    for (const name of taskNames) {
+      await this.executeTask(name, config);
+    }
+  }
+
+  /**
+   * Run a list of tasks in parallel
+   */
+  async runParallel(taskNames: string[], config: BalmConfig): Promise<void> {
+    await Promise.all(taskNames.map((name) => this.executeTask(name, config)));
+  }
+
+  /**
+   * Execute a single task resolving its dependencies first
+   */
+  async executeTask(
+    taskName: string,
+    config: BalmConfig,
+    executed = new Set<string>()
+  ): Promise<void> {
+    if (executed.has(taskName)) return;
+
+    const task = this.tasks.get(taskName);
+    if (!task) {
+      logger.warn('task', `Task ${pc.bold(taskName)} not found, skipping.`);
+      return;
+    }
+
+    // Execute dependencies first
+    if (task.deps && task.deps.length > 0) {
+      for (const dep of task.deps) {
+        await this.executeTask(dep, config, executed);
+      }
+    }
+
+    const start = performance.now();
+    try {
+      await task.run(config);
+      executed.add(taskName);
+      const duration = (performance.now() - start).toFixed(1);
+      if (!task.hidden) {
+        logger.info('task', `${pc.cyan(task.name)} finished in ${pc.bold(duration + 'ms')}`);
+      }
+    } catch (error: any) {
+      logger.error('task', `Task ${pc.bold(task.name)} failed: ${error?.message || error}`);
+      throw error;
+    }
+  }
+}

package/src/runner/task.ts

@@ -0,0 +1,38 @@
+import { BalmConfig } from '../types/index.js';
+import { logger } from '../utilities/logger.js';
+
+export interface TaskOptions {
+  name: string;
+  deps?: string[];
+  description?: string;
+  hidden?: boolean;
+}
+
+export abstract class BaseTask {
+  name: string;
+  deps: string[];
+  description?: string;
+  hidden: boolean;
+
+  constructor(options: TaskOptions) {
+    this.name = options.name;
+    this.deps = options.deps || [];
+    this.description = options.description;
+    this.hidden = options.hidden || false;
+  }
+
+  abstract run(config: BalmConfig): Promise<void> | void;
+}
+
+export class FunctionTask extends BaseTask {
+  private fn: (config: BalmConfig) => Promise<void> | void;
+
+  constructor(name: string, fn: (config: BalmConfig) => Promise<void> | void, deps: string[] = []) {
+    super({ name, deps });
+    this.fn = fn;
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    await this.fn(config);
+  }
+}

package/src/shims.d.ts

@@ -0,0 +1,5 @@
+declare module 'postcss-preset-env';
+declare module 'connect';
+declare module 'serve-static';
+declare module 'html-minifier-terser';
+

package/src/tasks/cache.ts

@@ -0,0 +1,72 @@
+import path from 'node:path';
+import fg from 'fast-glob';
+import fs from 'node:fs/promises';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig } from '../types/index.js';
+import { VirtualFile } from '../pipeline/file.js';
+import { AssetRevisioner } from '../pipeline/transforms/cache.js';
+import { file as fsUtil } from '../utilities/file.js';
+import { logger } from '../utilities/logger.js';
+
+export class CacheTask extends BaseTask {
+  constructor() {
+    super({ name: 'cache', description: 'Revision assets and generate manifest' });
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const destDir = config.dest.base;
+    const filesToRev = await fg(['**/*'], {
+      cwd: destDir,
+      absolute: true,
+      onlyFiles: true
+    });
+
+    if (!filesToRev.length) {
+      logger.warn('cache', 'No files found to cache');
+      return;
+    }
+
+    const virtualFiles = await Promise.all(
+      filesToRev.map(async (filePath) => {
+        const buffer = await fs.readFile(filePath);
+        return new VirtualFile({
+          cwd: config.workspace,
+          base: destDir,
+          path: filePath,
+          contents: buffer
+        });
+      })
+    );
+
+    const cacheOptions = {
+      ...config.assets.options,
+      dontRenameFile: [
+        '.html',
+        'favicon.ico',
+        'manifest.json',
+        'robots.txt',
+        '*.ico',
+        'icons/*',
+        '**/icons/**',
+        ...(config.assets.excludes || []),
+        ...(config.assets.options?.dontRenameFile || [])
+      ]
+    };
+    const revisioner = new AssetRevisioner(cacheOptions);
+    const resultFiles = revisioner.process(virtualFiles);
+
+    // Remove old files that have been renamed
+    for (const vFile of resultFiles) {
+      if (vFile.revPathOriginal && vFile.revPathOriginal !== vFile.path) {
+        await fsUtil.remove(vFile.revPathOriginal);
+      }
+    }
+
+    // Write new / updated files
+    for (const vFile of resultFiles) {
+      await fsUtil.writeFile(vFile.path, vFile.contents);
+    }
+
+    logger.success('cache', 'Asset revisioning and rev-manifest.json completed');
+  }
+}

package/src/tasks/clean.ts

@@ -0,0 +1,21 @@
+import path from 'node:path';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig } from '../types/index.js';
+import { file } from '../utilities/file.js';
+import { logger } from '../utilities/logger.js';
+
+export class CleanTask extends BaseTask {
+  constructor() {
+    super({ name: 'clean', description: 'Clean output directories' });
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const targets = [
+      path.join(config.workspace, config.roots.tmp),
+      path.join(config.workspace, config.roots.target)
+    ];
+
+    const deleted = await file.remove(targets);
+    logger.info('clean', `Deleted ${deleted.length} directories`);
+  }
+}

package/src/tasks/copy.ts

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig, RenameOptions } from '../types/index.js';
+import { Pipeline } from '../pipeline/pipeline.js';
+import { transformRename } from '../pipeline/transforms/rename.js';
+
+export interface CopyTaskOptions {
+  input: string | string[];
+  output: string;
+  rename?: RenameOptions | string | Function;
+}
+
+export class CopyTask extends BaseTask {
+  private options: CopyTaskOptions;
+
+  constructor(options: CopyTaskOptions) {
+    super({ name: 'copy', description: 'Copy files to destination' });
+    this.options = options;
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const pipeline = Pipeline.from(this.options.input, {
+      cwd: config.workspace
+    });
+
+    if (this.options.rename) {
+      pipeline.pipe(transformRename(this.options.rename));
+    }
+
+    const outDir = path.isAbsolute(this.options.output)
+      ? this.options.output
+      : path.join(config.workspace, this.options.output);
+
+    await pipeline.dest(outDir);
+  }
+}

package/src/tasks/ftp.ts

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { Client } from 'ssh2';
+import fg from 'fast-glob';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig } from '../types/index.js';
+import { logger } from '../utilities/logger.js';
+
+export interface FtpTaskOptions {
+  localFiles?: string | string[];
+  options?: {
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    privateKey?: string;
+    remotePath?: string;
+    [key: string]: any;
+  };
+}
+
+export class FtpTask extends BaseTask {
+  private ftpOptions: FtpTaskOptions;
+
+  constructor(ftpOptions: FtpTaskOptions = {}) {
+    super({ name: 'ftp', description: 'Upload files via SFTP' });
+    this.ftpOptions = ftpOptions;
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const options = {
+      port: 22,
+      remotePath: '/',
+      ...config.ftp.options,
+      ...this.ftpOptions.options
+    };
+
+    if (!options.host) {
+      logger.error('ftp', '`host` required for SFTP');
+      return;
+    }
+
+    const localFiles = this.ftpOptions.localFiles || config.dest.base;
+    const files = await fg(localFiles, { cwd: config.workspace, absolute: true, onlyFiles: true });
+
+    if (!files.length) {
+      logger.warn('ftp', 'No files to upload');
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      const conn = new Client();
+
+      conn.on('ready', () => {
+        conn.sftp((err, sftp) => {
+          if (err) {
+            conn.end();
+            return reject(err);
+          }
+
+          let pending = files.length;
+          for (const file of files) {
+            const rel = path.relative(config.workspace, file);
+            const remoteFile = path.posix.join(options.remotePath, rel);
+
+            sftp.fastPut(file, remoteFile, (putErr) => {
+              if (putErr) {
+                logger.error('ftp', `Failed uploading ${file}: ${putErr.message}`);
+              } else {
+                logger.info('ftp', `Uploaded ${file} -> ${remoteFile}`);
+              }
+              pending--;
+              if (pending === 0) {
+                conn.end();
+                resolve();
+              }
+            });
+          }
+        });
+      });
+
+      conn.on('error', (connErr) => {
+        logger.error('ftp', connErr.message);
+        reject(connErr);
+      });
+
+      conn.connect(options as any);
+    });
+  }
+}