balm-core 5.2.0 → 6.0.0-alpha.1

package/src/tasks/static.ts

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig } from '../types/index.js';
+import { Pipeline } from '../pipeline/pipeline.js';
+import { PUBLIC_URL } from '../config/constants.js';
+
+export class StaticTask extends BaseTask {
+  constructor() {
+    super({ name: 'static', description: 'Copy static assets, images, fonts, and manifest' });
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const srcBase = config.src.base;
+    const destBase = config.dest.base;
+
+    // 1. Copy root static files (favicon.ico, robots.txt, icons, etc.)
+    const staticPatterns = [
+      path.join(srcBase, '*.{ico,png,svg,json,txt,xml,webmanifest}'),
+      `!${path.join(srcBase, '*.html')}`
+    ];
+
+    const pipeline = Pipeline.from(staticPatterns, {
+      cwd: config.workspace,
+      base: srcBase
+    });
+
+    const publicUrlReplacement = config.assets.virtualDir ? `/${config.assets.virtualDir}` : '';
+    pipeline.pipe(async (file) => {
+      if (file.basename === 'manifest.json' || file.extname === '.json') {
+        let content = file.toString();
+        content = content.replaceAll(PUBLIC_URL, publicUrlReplacement);
+        file.contents = Buffer.from(content);
+      }
+      return file;
+    });
+
+    await pipeline.dest(destBase);
+
+    // 2. Copy images folder if exists in src
+    if (config.src.img && existsSync(config.src.img)) {
+      const imgPipeline = Pipeline.from(path.join(config.src.img, '**/*'), {
+        cwd: config.workspace,
+        base: config.src.img
+      });
+      await imgPipeline.dest(config.dest.img);
+
+      // If source and target img dirs differ (e.g. images vs img), also copy to source dir for compatibility
+      if (config.paths.source.img && config.paths.target.img && config.paths.source.img !== config.paths.target.img) {
+        const compatPipeline = Pipeline.from(path.join(config.src.img, '**/*'), {
+          cwd: config.workspace,
+          base: config.src.img
+        });
+        await compatPipeline.dest(path.join(destBase, config.paths.source.img));
+      }
+    }
+
+    // 3. Copy fonts folder if exists in src
+    if (config.src.font && existsSync(config.src.font)) {
+      const fontPipeline = Pipeline.from(path.join(config.src.font, '**/*'), {
+        cwd: config.workspace,
+        base: config.src.font
+      });
+      await fontPipeline.dest(config.dest.font);
+
+      // Ensure both 'font' and 'fonts' directories exist in dest for compatibility
+      const targetFontsDir = path.join(destBase, 'fonts');
+      if (config.dest.font !== targetFontsDir) {
+        const fontsPipeline = Pipeline.from(path.join(config.src.font, '**/*'), {
+          cwd: config.workspace,
+          base: config.src.font
+        });
+        await fontsPipeline.dest(targetFontsDir);
+      }
+      const targetFontDir = path.join(destBase, 'font');
+      if (config.dest.font !== targetFontDir) {
+        const fontCompatPipeline = Pipeline.from(path.join(config.src.font, '**/*'), {
+          cwd: config.workspace,
+          base: config.src.font
+        });
+        await fontCompatPipeline.dest(targetFontDir);
+      }
+    }
+
+    // 4. Copy media folder if exists in src
+    if (config.src.media && existsSync(config.src.media)) {
+      const mediaPipeline = Pipeline.from(path.join(config.src.media, '**/*'), {
+        cwd: config.workspace,
+        base: config.src.media
+      });
+      await mediaPipeline.dest(config.dest.media);
+    }
+
+    // 5. Copy public folder if exists in workspace
+    const publicDir = path.join(config.workspace, 'public');
+    if (existsSync(publicDir)) {
+      const pubPipeline = Pipeline.from(path.join(publicDir, '**/*'), {
+        cwd: config.workspace,
+        base: publicDir
+      });
+      await pubPipeline.dest(destBase);
+    }
+  }
+}

package/src/tasks/style.ts

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig } from '../types/index.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';
+
+export class StyleTask extends BaseTask {
+  constructor() {
+    super({ name: 'style', description: 'Compile stylesheets' });
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const ext = config.styles.extname;
+    const srcPattern = path.join(config.src.css, `**/*.${ext}`);
+    const isProd = config.env.isProd;
+
+    const pipeline = Pipeline.from([srcPattern, `!${path.join(config.src.css, '**/_*.scss')}`, `!${path.join(config.src.css, '**/_*.less')}`], {
+      cwd: config.workspace,
+      base: config.src.css
+    });
+
+    const styleAlias = {
+      ...config.alias,
+      ...config.styles.alias
+    };
+
+    if (ext === 'scss' || ext === 'sass') {
+      pipeline.pipe(
+        transformSass({
+          includePaths: [config.src.css, ...config.styles.atImportPaths],
+          alias: styleAlias,
+          ...config.styles.sassOptions
+        })
+      );
+    } else if (ext === 'less') {
+      pipeline.pipe(
+        transformLess({
+          paths: [config.src.css, ...config.styles.atImportPaths],
+          alias: styleAlias,
+          ...config.styles.lessOptions
+        })
+      );
+    }
+
+    pipeline.pipe(
+      transformPostcss({
+        plugins: config.styles.postcssPlugins,
+        minify: isProd || config.styles.minify,
+        ...config.styles.postcssLoaderOptions
+      })
+    );
+
+    await pipeline.dest(config.dest.css);
+  }
+}

package/src/tasks/zip.ts

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import archiver from 'archiver';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig } from '../types/index.js';
+import { file as fsUtil } from '../utilities/file.js';
+import { logger } from '../utilities/logger.js';
+
+export interface ZipTaskOptions {
+  input?: string | string[];
+  output?: string;
+  filename?: string;
+}
+
+export class ZipTask extends BaseTask {
+  private options: ZipTaskOptions;
+
+  constructor(options: ZipTaskOptions = {}) {
+    super({ name: 'zip', description: 'Compress files into archive' });
+    this.options = options;
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const input = this.options.input || config.dest.base;
+    const outputDir = this.options.output
+      ? (path.isAbsolute(this.options.output) ? this.options.output : path.join(config.workspace, this.options.output))
+      : config.workspace;
+    const filename = this.options.filename || 'archive.zip';
+    const zipPath = path.join(outputDir, filename);
+
+    await fsUtil.ensureDir(outputDir);
+
+    return new Promise((resolve, reject) => {
+      const outputStream = fs.createWriteStream(zipPath);
+      const archive = archiver('zip', { zlib: { level: 9 } });
+
+      outputStream.on('close', () => {
+        logger.success('zip', `Created ${zipPath} (${archive.pointer()} total bytes)`);
+        resolve();
+      });
+
+      archive.on('error', (err) => {
+        logger.error('zip', err.message);
+        reject(err);
+      });
+
+      archive.pipe(outputStream);
+
+      const inputs = Array.isArray(input) ? input : [input];
+      for (const item of inputs) {
+        const fullPath = path.isAbsolute(item) ? item : path.join(config.workspace, item);
+        if (fs.existsSync(fullPath)) {
+          const stat = fs.statSync(fullPath);
+          if (stat.isDirectory()) {
+            archive.directory(fullPath, false);
+          } else {
+            archive.file(fullPath, { name: path.basename(fullPath) });
+          }
+        }
+      }
+
+      archive.finalize();
+    });
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,202 @@
+export type LooseObject = Record<string, any>;
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+export type BalmEntry = string | string[] | Record<string, string | string[]>;
+
+export interface BalmRoots {
+  source: string;
+  tmp: string;
+  target: string;
+}
+
+export interface BalmPathMap {
+  base: string;
+  html: string;
+  css: string;
+  js: string;
+  img: string;
+  font: string;
+  media: string;
+}
+
+export interface BalmPaths {
+  source: BalmPathMap;
+  tmp: Omit<BalmPathMap, 'html'>;
+  target: Omit<BalmPathMap, 'html'>;
+}
+
+export interface BalmStyles {
+  extname: string;
+  minify: boolean;
+  atImportPaths: string[];
+  alias: Record<string, string>;
+  options: Record<string, any>;
+  sassOptions: Record<string, any>;
+  lessOptions: Record<string, any>;
+  postcssLoaderOptions: Record<string, any>;
+  postcssPlugins: any[];
+  sprites: string[];
+  spriteOptions: Record<string, any>;
+}
+
+export enum BundlerType {
+  webpack = 'webpack',
+  rollup = 'rollup',
+  esbuild = 'esbuild'
+}
+
+export interface BalmScripts {
+  bundler: BundlerType | 'webpack' | 'rollup' | 'esbuild';
+  minify: boolean;
+  minifyOptions: Record<string, any>;
+  entry: BalmEntry;
+  target: string | string[];
+  library: string | Record<string, any>;
+  libraryTarget: string;
+  externals: string | string[] | Record<string, any> | RegExp | Function;
+  injectHtml: boolean;
+  htmlName: string;
+  htmlPluginOptions?: Record<string, any>;
+  alias: Record<string, string>;
+  extensions?: string[];
+  plugins: any[];
+  loaders: any[];
+  defaultLoaders: {
+    html?: boolean;
+    css?: boolean;
+    js?: boolean;
+    url?: boolean;
+  };
+  options: Record<string, any>;
+  esbuildOptions: Record<string, any>;
+  rollupOptions: Record<string, any>;
+  webpackOptions: Record<string, any>;
+  useCache: boolean;
+}
+
+export interface BalmHtml {
+  options: Record<string, any>;
+}
+
+export interface BalmAssets {
+  root: string;
+  mainDir: string;
+  subDir: string;
+  buildDir: string;
+  virtualDir: string;
+  cache: boolean;
+  options: {
+    fileNameManifest?: string;
+    dontRenameFile?: (string | RegExp)[];
+    dontUpdateReference?: (string | RegExp)[];
+    hashLength?: number;
+    [key: string]: any;
+  };
+  includes: string[];
+  excludes: string[];
+  static?: string;
+  [key: string]: any;
+}
+
+export interface BalmServer {
+  host: string | null;
+  port: number;
+  open: boolean | string;
+  proxy: boolean | Record<string, any> | Array<Record<string, any>>;
+  proxyOptions: boolean | Record<string, any> | Array<Record<string, any>>;
+  historyOptions: boolean | Record<string, any>;
+  useHMR: boolean;
+  options: Record<string, any>;
+}
+
+export interface BalmPwa {
+  enabled: boolean;
+  mode: 'generateSW' | 'injectManifest';
+  version: string;
+  manifest: string;
+  swSrcFilename: string;
+  swDestFilename: string;
+  options: Record<string, any>;
+}
+
+export interface BalmFtp {
+  options: Record<string, any>;
+  watchFiles: string[];
+}
+
+export interface BalmImages {
+  plugins: any[];
+}
+
+export interface BalmEnv {
+  isProd: boolean;
+  isDev: boolean;
+  isTest: boolean;
+  inFrontend: boolean;
+  inSSR: boolean;
+  inDesktopApp: boolean;
+  isMP: boolean;
+}
+
+export interface BalmWorkspaces {
+  local: string;
+  global: string;
+}
+
+export type BalmWorkspaceConfig = string | { local?: string; global?: string };
+
+export interface BalmConfig {
+  workspace: string;
+  workspaces: BalmWorkspaces;
+  alias: Record<string, string>;
+  env: BalmEnv;
+  inFrontend: boolean;
+  useDefaults: boolean;
+  roots: BalmRoots;
+  paths: BalmPaths;
+  styles: BalmStyles;
+  scripts: BalmScripts;
+  html: BalmHtml;
+  assets: BalmAssets;
+  server: BalmServer;
+  pwa: BalmPwa;
+  ftp: BalmFtp;
+  images: BalmImages;
+  logs: {
+    level: number;
+  };
+  src: BalmPathMap;
+  dest: BalmPathMap & { static: string };
+  [key: string]: any;
+}
+
+export type BalmCustomConfig = Omit<DeepPartial<BalmConfig>, 'workspace'> & {
+  workspace?: BalmWorkspaceConfig;
+};
+
+export interface RenameOptions {
+  dirname?: string;
+  prefix?: string;
+  basename?: string;
+  suffix?: string;
+  extname?: string;
+}
+
+export interface ReplaceOptions {
+  substr: string | RegExp;
+  replacement: string | ((substring: string, ...args: any[]) => string);
+}
+
+export interface TemplateOption {
+  input: string;
+  output: string;
+  renameOptions?: string | Function | RenameOptions;
+}
+
+export interface TaskContext {
+  config: BalmConfig;
+}
+
+export type TaskFn = (context: TaskContext) => Promise<any> | any;

package/src/utilities/file.ts

@@ -0,0 +1,120 @@
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import fg from 'fast-glob';
+
+export class FileSystem {
+  workspace: string = process.cwd();
+
+  resolveApp(...paths: string[]): string {
+    return path.resolve(this.workspace, ...paths);
+  }
+
+  absPath(filePath: string): string {
+    return path.isAbsolute(filePath) ? filePath : this.resolveApp(filePath);
+  }
+
+  absPaths(filePaths: string | string[]): string | string[] {
+    if (Array.isArray(filePaths)) {
+      return filePaths.map((p) => this.absPath(p));
+    }
+    return this.absPath(filePaths);
+  }
+
+  async exists(targetPath: string): Promise<boolean> {
+    try {
+      await fs.access(this.absPath(targetPath));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  existsSync(targetPath: string): boolean {
+    return existsSync(this.absPath(targetPath));
+  }
+
+  async ensureDir(dirPath: string): Promise<void> {
+    await fs.mkdir(this.absPath(dirPath), { recursive: true });
+  }
+
+  async readFile(filePath: string, encoding: BufferEncoding = 'utf8'): Promise<string> {
+    return fs.readFile(this.absPath(filePath), { encoding });
+  }
+
+  async readBuffer(filePath: string): Promise<Buffer> {
+    return fs.readFile(this.absPath(filePath));
+  }
+
+  async writeFile(filePath: string, data: string | Buffer): Promise<void> {
+    const fullPath = this.absPath(filePath);
+    await this.ensureDir(path.dirname(fullPath));
+    await fs.writeFile(fullPath, data);
+  }
+
+  async remove(targetPath: string | string[]): Promise<string[]> {
+    const targets = Array.isArray(targetPath) ? targetPath : [targetPath];
+    const removed: string[] = [];
+
+    for (const item of targets) {
+      const fullPath = this.absPath(item);
+      try {
+        const stat = await fs.stat(fullPath);
+        if (stat.isDirectory()) {
+          await fs.rm(fullPath, { recursive: true, force: true });
+        } else {
+          await fs.unlink(fullPath);
+        }
+        removed.push(fullPath);
+      } catch {
+        // file doesn't exist or already removed
+      }
+    }
+
+    return removed;
+  }
+
+  async copyFile(src: string, dest: string): Promise<void> {
+    const srcPath = this.absPath(src);
+    const destPath = this.absPath(dest);
+    await this.ensureDir(path.dirname(destPath));
+    await fs.copyFile(srcPath, destPath);
+  }
+
+  async copyDir(srcDir: string, destDir: string): Promise<void> {
+    const src = this.absPath(srcDir);
+    const dest = this.absPath(destDir);
+    await this.ensureDir(dest);
+
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcItem = path.join(src, entry.name);
+      const destItem = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        await this.copyDir(srcItem, destItem);
+      } else {
+        await this.copyFile(srcItem, destItem);
+      }
+    }
+  }
+
+  async matchFiles(
+    patterns: string | string[],
+    options: fg.Options = {}
+  ): Promise<string[]> {
+    const defaultOptions: fg.Options = {
+      cwd: this.workspace,
+      absolute: true,
+      dot: true,
+      onlyFiles: true
+    };
+    return fg(patterns, { ...defaultOptions, ...options });
+  }
+
+  hash(content: string | Buffer, length = 8): string {
+    return crypto.createHash('md5').update(content).digest('hex').slice(0, length);
+  }
+}
+
+export const file = new FileSystem();

package/src/utilities/logger.ts

@@ -0,0 +1,63 @@
+import pc from 'picocolors';
+
+export enum LogLevel {
+  Debug = 0,
+  Info = 1,
+  Warn = 2,
+  Error = 3,
+  Silent = 4
+}
+
+class Logger {
+  level: LogLevel = LogLevel.Info;
+
+  private formatTag(tag?: string): string {
+    return tag ? pc.cyan(`[${tag}]`) : pc.bgBlue(pc.black(' BalmJS '));
+  }
+
+  private timestamp(): string {
+    const d = new Date();
+    const pad = (n: number) => n.toString().padStart(2, '0');
+    return pc.gray(`[${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}]`);
+  }
+
+  debug(tag: string, message: any, ...args: any[]): void {
+    if (this.level <= LogLevel.Debug) {
+      console.log(this.timestamp(), this.formatTag(tag), pc.magenta('※'), message, ...args);
+    }
+  }
+
+  info(tag: string, message: any, ...args: any[]): void {
+    if (this.level <= LogLevel.Info) {
+      console.log(this.timestamp(), this.formatTag(tag), pc.blue('ℹ'), message, ...args);
+    }
+  }
+
+  success(tag: string, message: any, ...args: any[]): void {
+    if (this.level <= LogLevel.Info) {
+      console.log(this.timestamp(), this.formatTag(tag), pc.green('✔'), pc.green(message), ...args);
+    }
+  }
+
+  warn(tag: string, message: any, ...args: any[]): void {
+    if (this.level <= LogLevel.Warn) {
+      console.warn(this.timestamp(), this.formatTag(tag), pc.yellow('⚠'), pc.yellow(message), ...args);
+    }
+  }
+
+  error(tag: string, message: any, ...args: any[]): void {
+    if (this.level <= LogLevel.Error) {
+      console.error(this.timestamp(), this.formatTag(tag), pc.red('✖'), pc.red(message), ...args);
+    }
+  }
+
+  time(label: string): () => void {
+    const start = performance.now();
+    return () => {
+      const duration = (performance.now() - start).toFixed(2);
+      this.info('time', `${label} completed in ${pc.bold(duration + 'ms')}`);
+    };
+  }
+}
+
+export const logger = new Logger();

package/src/utilities/utils.ts

@@ -0,0 +1,46 @@
+export function isObject(val: any): val is Record<string, any> {
+  return val !== null && typeof val === 'object' && !Array.isArray(val);
+}
+
+export function isArray(val: any): val is any[] {
+  return Array.isArray(val);
+}
+
+export function isString(val: any): val is string {
+  return typeof val === 'string';
+}
+
+export function isFunction(val: any): val is Function {
+  return typeof val === 'function';
+}
+
+export function isBoolean(val: any): val is boolean {
+  return typeof val === 'boolean';
+}
+
+export function deepMerge<T extends Record<string, any>>(target: T, ...sources: any[]): T {
+  if (!sources.length) return target;
+  const source = sources.shift();
+
+  if (isObject(target) && isObject(source)) {
+    for (const key in source) {
+      if (isObject(source[key])) {
+        if (!target[key]) Object.assign(target, { [key]: {} });
+        deepMerge(target[key], source[key]);
+      } else if (isArray(source[key])) {
+        (target as any)[key] = [...source[key]];
+      } else if (source[key] !== undefined) {
+        Object.assign(target, { [key]: source[key] });
+      }
+    }
+  }
+
+  return deepMerge(target, ...sources);
+}
+
+export function toNamespace(name: string | string[], namespace = 'balm'): string | string[] {
+  if (isArray(name)) {
+    return name.map((item) => `${namespace}:${item}`);
+  }
+  return `${namespace}:${name}`;
+}

package/src/utilities/workspace.ts

@@ -0,0 +1,38 @@
+import path from 'node:path';
+
+export interface WorkspacePaths {
+  local: string;
+  global: string;
+}
+
+let currentLocalWorkspace: string = process.cwd();
+let currentGlobalWorkspace: string = path.resolve(process.cwd(), '..');
+
+export function setWorkspaces(local?: string, global?: string): void {
+  if (local) {
+    currentLocalWorkspace = path.resolve(local);
+  }
+  if (global) {
+    currentGlobalWorkspace = path.resolve(global);
+  } else if (local && !global) {
+    currentGlobalWorkspace = path.resolve(currentLocalWorkspace, '..');
+  }
+}
+
+export function getWorkspaces(): WorkspacePaths {
+  return {
+    local: currentLocalWorkspace,
+    global: currentGlobalWorkspace
+  };
+}
+
+export function localWorkspace(subPath: string = ''): string {
+  return subPath ? path.resolve(currentLocalWorkspace, subPath) : currentLocalWorkspace;
+}
+
+export function globalWorkspace(subPath: string = ''): string {
+  return subPath ? path.resolve(currentGlobalWorkspace, subPath) : currentGlobalWorkspace;
+}
+
+export const localResolve = localWorkspace;
+export const globalResolve = globalWorkspace;