balm-core 5.2.0 → 6.0.0-alpha.1

package/src/tasks/html.ts

@@ -0,0 +1,232 @@
+import path from 'node:path';
+import fg from 'fast-glob';
+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 customTemplate = config.scripts.htmlPluginOptions?.template;
+    let pipeline: Pipeline;
+
+    if (customTemplate) {
+      const templatePath = path.isAbsolute(customTemplate)
+        ? customTemplate
+        : path.join(config.workspace, customTemplate);
+      pipeline = Pipeline.from(templatePath, {
+        cwd: config.workspace,
+        base: path.dirname(templatePath)
+      });
+    } else {
+      const templateDir = config.scripts.injectHtml
+        ? config.src.base
+        : config.src.html;
+
+      const pattern = path.join(templateDir, '*.html');
+      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));
+
+    // Ensure output filename is index.html if custom template was used
+    if (customTemplate) {
+      pipeline.pipe(async (file) => {
+        file.basename = 'index.html';
+        return file;
+      });
+    }
+
+    // In production, map source paths to target paths in HTML
+    if (config.env.isProd) {
+      pipeline.pipe(async (file) => {
+        if (/\.html$/i.test(file.extname)) {
+          let content = file.toString();
+          if (
+            config.paths.source.css &&
+            config.paths.target.css &&
+            config.paths.source.css !== config.paths.target.css
+          ) {
+            content = content.replaceAll(
+              `/${config.paths.source.css}/`,
+              `/${config.paths.target.css}/`
+            );
+            content = content.replaceAll(
+              `"${config.paths.source.css}/`,
+              `"${config.paths.target.css}/`
+            );
+            content = content.replaceAll(
+              `'${config.paths.source.css}/`,
+              `'${config.paths.target.css}/`
+            );
+          }
+          if (
+            config.paths.source.js &&
+            config.paths.target.js &&
+            config.paths.source.js !== config.paths.target.js
+          ) {
+            content = content.replaceAll(
+              `/${config.paths.source.js}/`,
+              `/${config.paths.target.js}/`
+            );
+            content = content.replaceAll(
+              `"${config.paths.source.js}/`,
+              `"${config.paths.target.js}/`
+            );
+            content = content.replaceAll(
+              `'${config.paths.source.js}/`,
+              `'${config.paths.target.js}/`
+            );
+          }
+          if (
+            config.paths.source.img &&
+            config.paths.target.img &&
+            config.paths.source.img !== config.paths.target.img
+          ) {
+            content = content.replaceAll(
+              `/${config.paths.source.img}/`,
+              `/${config.paths.target.img}/`
+            );
+            content = content.replaceAll(
+              `"${config.paths.source.img}/`,
+              `"${config.paths.target.img}/`
+            );
+            content = content.replaceAll(
+              `'${config.paths.source.img}/`,
+              `'${config.paths.target.img}/`
+            );
+          }
+          if (
+            config.paths.source.font &&
+            config.paths.target.font &&
+            config.paths.source.font !== config.paths.target.font
+          ) {
+            content = content.replaceAll(
+              `/${config.paths.source.font}/`,
+              `/${config.paths.target.font}/`
+            );
+            content = content.replaceAll(
+              `"${config.paths.source.font}/`,
+              `"${config.paths.target.font}/`
+            );
+            content = content.replaceAll(
+              `'${config.paths.source.font}/`,
+              `'${config.paths.target.font}/`
+            );
+          }
+          file.contents = Buffer.from(content);
+        }
+        return file;
+      });
+    }
+
+    // Auto-inject script tags if injectHtml is enabled
+    if (config.scripts.injectHtml) {
+      pipeline.pipe(async (file) => {
+        if (/\.html$/i.test(file.extname)) {
+          let content = file.toString();
+          const entries =
+            typeof config.scripts.entry === 'object' && !Array.isArray(config.scripts.entry)
+              ? Object.keys(config.scripts.entry)
+              : ['main'];
+
+          const jsDir = config.env.isProd ? config.paths.target.js : config.paths.tmp.js;
+          const jsPathPrefix = config.assets.virtualDir ? `/${config.assets.virtualDir}/${jsDir}` : `/${jsDir}`;
+          const destJsFolder = config.dest.js;
+
+          const scriptTags = entries
+            .filter(
+              (entryName) =>
+                !new RegExp(`<script[^>]+src=["'][^"']*${entryName}[^"']*\\.js["']`, 'i').test(
+                  content
+                )
+            )
+            .map((entryName) => {
+              let actualFilename = `${entryName}.js`;
+              try {
+                const matched = fg.sync(`${entryName}.*.js`, { cwd: destJsFolder });
+                if (matched.length) {
+                  const valid = matched.find((f) => !f.endsWith('.map') && !f.endsWith('.txt'));
+                  if (valid) {
+                    actualFilename = valid;
+                  }
+                }
+              } catch {}
+              return `<script defer src="${jsPathPrefix}/${actualFilename}"></script>`;
+            })
+            .join('\n');
+
+          if (scriptTags) {
+            if (content.includes('</body>')) {
+              content = content.replace('</body>', `${scriptTags}\n</body>`);
+            } else {
+              content += `\n${scriptTags}`;
+            }
+            file.contents = Buffer.from(content);
+          }
+        }
+        return file;
+      });
+    }
+
+    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,14 @@
+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';
+export * from './static.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,99 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { generateSW, injectManifest } from 'workbox-build';
+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 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 globDirectory = config.dest.base;
+    const swDest = path.join(globDirectory, config.pwa.swDestFilename);
+    const swSrc = path.join(config.src.base, config.pwa.swSrcFilename);
+
+    // 1. Copy workbox-sw.js and workbox-sw.js.map to dest
+    const require = createRequire(import.meta.url);
+    const candidatePaths: string[] = [
+      path.join(config.workspace, 'node_modules/workbox-sw/build/workbox-sw.js'),
+      path.join(config.workspace, 'node_modules/workbox-sw/controllers/WorkboxSW.mjs')
+    ];
+    try {
+      const resolved = require.resolve('workbox-sw/build/workbox-sw.js');
+      candidatePaths.unshift(resolved);
+    } catch {}
+    try {
+      const resolvedPkg = require.resolve('workbox-sw');
+      candidatePaths.push(path.join(path.dirname(resolvedPkg), 'build/workbox-sw.js'));
+    } catch {}
+
+    for (const p of candidatePaths) {
+      if (existsSync(p)) {
+        const destFile = path.join(globDirectory, 'workbox-sw.js');
+        await fs.copyFile(p, destFile);
+        const mapFile = `${p}.map`;
+        if (existsSync(mapFile)) {
+          await fs.copyFile(mapFile, path.join(globDirectory, 'workbox-sw.js.map'));
+        }
+        break;
+      }
+    }
+
+    // 2. Generate or inject manifest
+    const mode = this.options.mode || config.pwa.mode || 'generateSW';
+    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)`);
+      }
+
+      // 3. Replace version placeholder in swDest
+      if (existsSync(swDest) && config.pwa.version) {
+        let swContent = await fs.readFile(swDest, 'utf-8');
+        swContent = swContent
+          .replaceAll('{{ version }}', config.pwa.version)
+          .replaceAll('{{version}}', config.pwa.version);
+        await fs.writeFile(swDest, swContent, 'utf-8');
+      }
+
+      // 4. Ensure both service-worker.js and sw.js exist in dest for compatibility
+      const swJsDest = path.join(globDirectory, 'sw.js');
+      const serviceWorkerJsDest = path.join(globDirectory, 'service-worker.js');
+      if (existsSync(serviceWorkerJsDest) && !existsSync(swJsDest)) {
+        await fs.copyFile(serviceWorkerJsDest, swJsDest);
+      } else if (existsSync(swJsDest) && !existsSync(serviceWorkerJsDest)) {
+        await fs.copyFile(swJsDest, serviceWorkerJsDest);
+      }
+    } 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;
+    }
+  }
+}

package/src/tasks/server.ts

@@ -0,0 +1,183 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import connect from 'connect';
+import serveStatic from 'serve-static';
+import { WebSocketServer, WebSocket } from 'ws';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+import { BaseTask } from '../runner/task.js';
+import { BalmConfig } from '../types/index.js';
+import { FileWatcher } from '../watcher/index.js';
+import { logger } from '../utilities/logger.js';
+import pc from 'picocolors';
+
+export class ServerTask extends BaseTask {
+  private watcher: FileWatcher | null = null;
+  private wsServer: WebSocketServer | null = null;
+  private clients = new Set<WebSocket>();
+
+  constructor() {
+    super({ name: 'serve', description: 'Start development server with live reload' });
+  }
+
+  broadcast(data: { type: 'reload' | 'reload-css'; file?: string }): void {
+    const payload = JSON.stringify(data);
+    for (const client of this.clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(payload);
+      }
+    }
+  }
+
+  async run(config: BalmConfig): Promise<void> {
+    if (config.env.isProd) {
+      logger.warn('server', 'Development server is disabled in production mode');
+      return;
+    }
+
+    const app = connect();
+    const port = config.server.port || 3000;
+    const host = config.server.host || 'localhost';
+
+    // Rewrite %PUBLIC_URL% in request URLs
+    app.use((req: any, _res: any, next: any) => {
+      if (req.url?.includes('%PUBLIC_URL%')) {
+        req.url = req.url.replace('/%PUBLIC_URL%', '').replace('%PUBLIC_URL%', '') || '/';
+      }
+      next();
+    });
+
+    // Dynamic manifest.json replacement for %PUBLIC_URL%
+    app.use((req: any, res: any, next: any) => {
+      if (req.url === '/manifest.json' || req.url?.endsWith('/manifest.json')) {
+        const candidates = [
+          path.join(config.dest.base, 'manifest.json'),
+          path.join(config.src.base, 'manifest.json'),
+          path.join(config.workspace, 'manifest.json')
+        ];
+        const file = candidates.find((f) => fs.existsSync(f));
+        if (file) {
+          let content = fs.readFileSync(file, 'utf-8');
+          const replacement = config.assets.virtualDir ? `/${config.assets.virtualDir}` : '';
+          content = content.replaceAll('%PUBLIC_URL%', replacement);
+          res.setHeader('Content-Type', 'application/json; charset=utf-8');
+          return res.end(content);
+        }
+      }
+      next();
+    });
+
+    // Static assets routing
+    if (config.paths.source.css) {
+      app.use('/' + config.paths.source.css, serveStatic(config.dest.css));
+    }
+    if (config.paths.tmp.css && config.paths.tmp.css !== config.paths.source.css) {
+      app.use('/' + config.paths.tmp.css, serveStatic(config.dest.css));
+    }
+
+    if (config.paths.source.js) {
+      app.use('/' + config.paths.source.js, serveStatic(config.dest.js));
+    }
+    if (config.paths.tmp.js && config.paths.tmp.js !== config.paths.source.js) {
+      app.use('/' + config.paths.tmp.js, serveStatic(config.dest.js));
+    }
+    app.use('/chunk', serveStatic(path.join(config.dest.js, 'chunk')));
+    app.use('/chunk', serveStatic(path.join(config.dest.base, 'chunk')));
+
+    if (config.paths.source.img) {
+      app.use(
+        '/' + config.paths.source.img,
+        serveStatic(path.join(config.src.base, config.paths.source.img))
+      );
+    }
+    if (config.paths.tmp.img) {
+      app.use('/' + config.paths.tmp.img, serveStatic(config.dest.img));
+    }
+    app.use('/img', serveStatic(path.join(config.dest.base, 'img')));
+    app.use('/img', serveStatic(path.join(config.dest.js, 'img')));
+
+    if (config.paths.source.font) {
+      app.use(
+        '/' + config.paths.source.font,
+        serveStatic(path.join(config.src.base, config.paths.source.font))
+      );
+    }
+    if (config.paths.tmp.font) {
+      app.use('/' + config.paths.tmp.font, serveStatic(config.dest.font));
+    }
+    app.use('/font', serveStatic(path.join(config.dest.base, 'font')));
+    app.use('/font', serveStatic(path.join(config.dest.js, 'font')));
+    app.use('/fonts', serveStatic(path.join(config.src.base, 'fonts')));
+    app.use('/fonts', serveStatic(path.join(config.dest.base, 'fonts')));
+
+    app.use(serveStatic(config.dest.base));
+    app.use(serveStatic(config.src.base));
+    app.use(serveStatic(config.workspace));
+
+    // History API fallback for SPA
+    if (config.server.historyOptions) {
+      app.use((req: any, res: any, next: any) => {
+        const isGetOrHead = req.method === 'GET' || req.method === 'HEAD';
+        const isHtmlNav = !req.url?.includes('.') || req.headers.accept?.includes('text/html');
+        if (isGetOrHead && isHtmlNav) {
+          const indexPath = path.join(config.dest.html, 'index.html');
+          const srcIndexPath = path.join(config.src.base, 'index.html');
+          const fileToServe = fs.existsSync(indexPath) ? indexPath : srcIndexPath;
+          if (fs.existsSync(fileToServe)) {
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            if (req.method === 'HEAD') {
+              return res.end();
+            }
+            return fs.createReadStream(fileToServe).pipe(res);
+          }
+        }
+        next();
+      });
+    }
+
+    // Proxy middleware
+    if (config.server.proxy && typeof config.server.proxy === 'object') {
+      const proxyEntries = Array.isArray(config.server.proxy)
+        ? config.server.proxy
+        : [config.server.proxy];
+
+      for (const entry of proxyEntries) {
+        if (entry.context && entry.options) {
+          app.use(createProxyMiddleware(entry.options));
+        }
+      }
+    }
+
+    const server = http.createServer(app);
+
+    // WebSocket Live Reload Server
+    this.wsServer = new WebSocketServer({ server, path: '/__balm_ws' });
+    this.wsServer.on('connection', (socket) => {
+      this.clients.add(socket);
+      socket.on('close', () => this.clients.delete(socket));
+    });
+
+    // Start File Watcher
+    this.watcher = new FileWatcher(config, (data) => {
+      this.broadcast(data);
+    });
+    this.watcher.start();
+
+    return new Promise((resolve) => {
+      server.listen(port, host, () => {
+        console.log('');
+        logger.success('server', pc.bold('BalmJS Dev Server is ready!'));
+        console.log(`  ${pc.green('➜')}  ${pc.bold('Local:')}   ${pc.cyan(`http://${host}:${port}/`)}`);
+        console.log(`  ${pc.green('➜')}  ${pc.bold('Network:')} ${pc.cyan(`http://127.0.0.1:${port}/`)}`);
+        console.log('');
+
+        if (config.env.isTest) {
+          this.watcher?.stop();
+          this.wsServer?.close();
+          server.close();
+          resolve();
+        }
+      });
+    });
+  }
+}