balm-core 5.2.0 → 6.0.0-alpha.0

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,58 @@
+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 revisioner = new AssetRevisioner(config.assets.options);
+    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);
+    });
+  }
+}

package/src/tasks/html.ts

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig } from '../types/index.js';
+import { Pipeline } from '../pipeline/pipeline.js';
+import { transformHtmlmin } from '../pipeline/transforms/htmlmin.js';
+import { transformReplace } from '../pipeline/transforms/replace.js';
+import { PUBLIC_URL } from '../config/constants.js';
+
+const LIVE_RELOAD_SCRIPT = `
+<!-- BalmJS Live Reload -->
+<script>
+(() => {
+  const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+  const ws = new WebSocket(\`\${protocol}//\${location.host}/__balm_ws\`);
+  ws.onmessage = (e) => {
+    try {
+      const msg = JSON.parse(e.data);
+      if (msg.type === 'reload') {
+        console.log('[BalmJS] Reloading page...');
+        location.reload();
+      } else if (msg.type === 'reload-css') {
+        console.log('[BalmJS] Reloading CSS...');
+        const links = document.querySelectorAll('link[rel="stylesheet"]');
+        for (const link of links) {
+          const url = new URL(link.href);
+          url.searchParams.set('_balm_t', Date.now().toString());
+          link.href = url.href;
+        }
+      }
+    } catch {}
+  };
+  ws.onclose = () => {
+    setTimeout(() => location.reload(), 2000);
+  };
+})();
+</script>
+`;
+
+export class HtmlTask extends BaseTask {
+  constructor() {
+    super({ name: 'html', description: 'Process HTML templates' });
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const templateDir = config.scripts.injectHtml
+      ? config.src.base
+      : config.src.html;
+
+    const pattern = path.join(templateDir, '*.html');
+    const pipeline = Pipeline.from(pattern, {
+      cwd: config.workspace,
+      base: templateDir
+    });
+
+    // Replace %PUBLIC_URL% placeholder
+    const publicUrlReplacement = config.assets.virtualDir ? `/${config.assets.virtualDir}` : '';
+    pipeline.pipe(transformReplace(new RegExp(PUBLIC_URL, 'g'), publicUrlReplacement));
+
+    if (config.env.isProd) {
+      pipeline.pipe(transformHtmlmin(config.html.options));
+    } else {
+      pipeline.pipe(async (file) => {
+        if (/\.html$/i.test(file.extname)) {
+          let content = file.toString();
+          if (content.includes('</body>')) {
+            content = content.replace('</body>', `${LIVE_RELOAD_SCRIPT}\n</body>`);
+          } else {
+            content += `\n${LIVE_RELOAD_SCRIPT}`;
+          }
+          file.contents = Buffer.from(content);
+        }
+        return file;
+      });
+    }
+
+    await pipeline.dest(config.dest.html);
+  }
+}

package/src/tasks/index.ts

@@ -0,0 +1,13 @@
+export * from './clean.js';
+export * from './style.js';
+export * from './script.js';
+export * from './html.js';
+export * from './copy.js';
+export * from './remove.js';
+export * from './replace.js';
+export * from './cache.js';
+export * from './publish.js';
+export * from './pwa.js';
+export * from './zip.js';
+export * from './ftp.js';
+export * from './server.js';

package/src/tasks/publish.ts

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig, TemplateOption, RenameOptions } from '../types/index.js';
+import { Pipeline } from '../pipeline/pipeline.js';
+import { transformRename } from '../pipeline/transforms/rename.js';
+import { logger } from '../utilities/logger.js';
+
+export interface PublishTaskOptions {
+  input?: string | TemplateOption[];
+  output?: string;
+  renameOptions?: string | Function | RenameOptions;
+}
+
+export class PublishTask extends BaseTask {
+  private options: PublishTaskOptions;
+
+  constructor(options: PublishTaskOptions = {}) {
+    super({ name: 'publish', description: 'Publish assets or templates' });
+    this.options = options;
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    if (!config.env.isProd) {
+      logger.warn('publish', '`mix.publish()` is only supported in production mode');
+      return;
+    }
+
+    const { input, output, renameOptions } = this.options;
+
+    if (Array.isArray(input)) {
+      for (const item of input) {
+        await this.publishItem(config, item.input, item.output, item.renameOptions);
+      }
+    } else if (typeof input === 'string' && output) {
+      await this.publishItem(config, input, output, renameOptions);
+    } else {
+      // Default: publish all static assets from dest.base to assets.static
+      const srcDir = config.dest.base;
+      const targetDir = config.assets.static || path.join(config.assets.root, config.assets.mainDir);
+
+      const pipeline = Pipeline.from(['**/*'], {
+        cwd: srcDir,
+        base: srcDir
+      });
+
+      await pipeline.dest(path.resolve(config.workspace, targetDir));
+    }
+  }
+
+  private async publishItem(
+    config: BalmConfig,
+    input: string,
+    output: string,
+    rename?: string | Function | RenameOptions
+  ): Promise<void> {
+    const srcPath = path.isAbsolute(input) ? input : path.join(config.dest.base, input);
+    const destDir = path.isAbsolute(output)
+      ? output
+      : path.join(config.workspace, config.assets.root, output);
+
+    const pipeline = Pipeline.from(srcPath, {
+      cwd: config.dest.base
+    });
+
+    if (rename) {
+      pipeline.pipe(transformRename(rename));
+    }
+
+    await pipeline.dest(destDir);
+  }
+}

package/src/tasks/pwa.ts

@@ -0,0 +1,49 @@
+import path from 'node:path';
+import { generateSW, injectManifest } from 'workbox-build';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig } from '../types/index.js';
+import { logger } from '../utilities/logger.js';
+
+export interface PwaTaskOptions {
+  mode?: 'generateSW' | 'injectManifest';
+  options?: Record<string, any>;
+}
+
+export class PwaTask extends BaseTask {
+  private options: PwaTaskOptions;
+
+  constructor(options: PwaTaskOptions = {}) {
+    super({ name: 'pwa', description: 'Generate Progressive Web App Service Worker' });
+    this.options = options;
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const mode = this.options.mode || config.pwa.mode || 'generateSW';
+    const globDirectory = config.dest.base;
+    const swDest = path.join(globDirectory, config.pwa.swDestFilename);
+    const swSrc = path.join(config.src.base, config.pwa.swSrcFilename);
+
+    const mergedOptions: any = {
+      globDirectory,
+      swDest,
+      ...config.pwa.options,
+      ...this.options.options
+    };
+
+    if (mode === 'injectManifest') {
+      mergedOptions.swSrc = mergedOptions.swSrc || swSrc;
+    }
+
+    try {
+      if (mode === 'generateSW') {
+        const { count, size } = await generateSW(mergedOptions);
+        logger.info('pwa', `Generated '${swDest}', precaching ${count} files (${size} bytes)`);
+      } else {
+        const { count, size } = await injectManifest(mergedOptions);
+        logger.info('pwa', `Injected manifest into '${swDest}', precaching ${count} files (${size} bytes)`);
+      }
+    } catch (err: any) {
+      logger.warn('pwa', `Service worker generation failed: ${err.message || err}`);
+    }
+  }
+}

package/src/tasks/remove.ts

@@ -0,0 +1,24 @@
+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 RemoveTask extends BaseTask {
+  private target: string | string[];
+
+  constructor(target: string | string[]) {
+    super({ name: 'remove', description: 'Remove files and directories' });
+    this.target = target;
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const targets = Array.isArray(this.target) ? this.target : [this.target];
+    const resolvedTargets = targets.map((t) =>
+      path.isAbsolute(t) ? t : path.join(config.workspace, t)
+    );
+
+    const deleted = await file.remove(resolvedTargets);
+    logger.warn('remove', `Removed: ${deleted.join(', ')}`);
+  }
+}

package/src/tasks/replace.ts

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig, ReplaceOptions } from '../types/index.js';
+import { Pipeline } from '../pipeline/pipeline.js';
+import { transformReplace } from '../pipeline/transforms/replace.js';
+
+export interface ReplaceTaskOptions {
+  input: string | string[];
+  output: string;
+  options: ReplaceOptions | ReplaceOptions[];
+}
+
+export class ReplaceTask extends BaseTask {
+  private taskOptions: ReplaceTaskOptions;
+
+  constructor(taskOptions: ReplaceTaskOptions) {
+    super({ name: 'replace', description: 'Replace content in files' });
+    this.taskOptions = taskOptions;
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const pipeline = Pipeline.from(this.taskOptions.input, {
+      cwd: config.workspace
+    });
+
+    pipeline.pipe(transformReplace(this.taskOptions.options));
+
+    const outDir = path.isAbsolute(this.taskOptions.output)
+      ? this.taskOptions.output
+      : path.join(config.workspace, this.taskOptions.output);
+
+    await pipeline.dest(outDir);
+  }
+}

package/src/tasks/script.ts

@@ -0,0 +1,28 @@
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig, BundlerType } from '../types/index.js';
+import { runWebpack } from '../bundler/webpack.js';
+import { runRollup } from '../bundler/rollup.js';
+import { runEsbuild } from '../bundler/esbuild.js';
+
+export class ScriptTask extends BaseTask {
+  constructor() {
+    super({ name: 'script', description: 'Bundle JavaScript/TypeScript' });
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    const bundler = config.scripts.bundler;
+
+    switch (bundler) {
+      case BundlerType.rollup:
+        await runRollup(config);
+        break;
+      case BundlerType.esbuild:
+        await runEsbuild(config);
+        break;
+      case BundlerType.webpack:
+      default:
+        await runWebpack(config);
+        break;
+    }
+  }
+}