🍕 clay build — esbuild + PostCSS 8 asset pipeline, full backward compatibility, tests, and docs

.gitignore

@@ -50,3 +50,4 @@ website/build/
 website/yarn.lock
 website/node_modules
 website/i18n/*
+*.tgz

.nvmrc

@@ -0,0 +1 @@
+22

cli/build.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const { build, watch } = require('../lib/cmd/build');
+const log = require('./log').setup({ file: __filename });
+
+function builder(yargs) {
+  return yargs
+    .usage('Usage: $0 [options]')
+    .option('watch', {
+      alias: 'w',
+      type: 'boolean',
+      description: 'Watch for file changes and rebuild automatically',
+      default: false,
+    })
+    .option('minify', {
+      alias: 'm',
+      type: 'boolean',
+      description: 'Minify output (also enabled by CLAYCLI_COMPILE_MINIFIED env var)',
+      default: !!process.env.CLAYCLI_COMPILE_MINIFIED,
+    })
+    .option('entry', {
+      alias: 'e',
+      type: 'array',
+      description: 'Additional entry-point file paths (supplements the default component globs)',
+      default: [],
+    })
+    .example('$0', 'Build all component scripts with esbuild')
+    .example('$0 --watch', 'Rebuild on every file change')
+    .example('$0 --minify', 'Build and minify for production');
+}
+
+async function handler(argv) {
+  const options = {
+    minify: argv.minify,
+    extraEntries: argv.entry || [],
+  };
+
+  if (argv.watch) {
+    try {
+      const ctx = await watch({
+        ...options,
+        onRebuild(errors) {
+          // In watch mode only surface errors — esbuild reports warnings for
+          // every file it touches on each incremental rebuild, not just the
+          // changed file, which floods the terminal with irrelevant noise.
+          // Warnings are still visible in full during `make compile`.
+          if (errors.length > 0) {
+            errors.forEach(e => log('error', e.text, { location: e.location }));
+          } else {
+            log('info', '[js] Rebuilt successfully');
+          }
+        },
+      });
+
+      log('info', 'Watching for changes — press Ctrl+C to stop');
+
+      process.on('SIGINT', () => {
+        ctx.dispose().then(() => process.exit(0));
+      });
+
+      process.on('SIGTERM', () => {
+        ctx.dispose().then(() => process.exit(0));
+      });
+    } catch (error) {
+      log('error', 'Watch setup failed', { error: error.message });
+      process.exit(1);
+    }
+  } else {
+    try {
+      const result = await build(options);
+
+      if (result.errors.length > 0) {
+        result.errors.forEach(e => log('error', e.text, { location: e.location }));
+        process.exit(1);
+      }
+
+      // esbuild warnings are pre-existing code issues (duplicate object keys,
+      // typeof-null, etc.) that are not actionable build failures. Log a count
+      // so they are visible without flooding the terminal with full locations.
+      if (result.warnings.length > 0) {
+        log('warn', `${result.warnings.length} esbuild warning(s) — run with --log-level=verbose to see details`);
+      }
+    } catch (error) {
+      log('error', 'Build failed', { error: error.message });
+      process.exit(1);
+    }
+  }
+}
+
+exports.aliases = ['pack-next', 'pn']; // pack-next kept for backward compat with existing Makefiles
+exports.builder = builder;
+exports.command = 'build';
+exports.describe = 'Compile component scripts and assets with esbuild';
+exports.handler = handler;

cli/index.js

@@ -21,7 +21,10 @@ const yargs = require('yargs'),
     e: 'export',
     i: 'import',
     l: 'lint',
-    p: 'pack'
+    b: 'build',
+    p: 'pack',
+    pn: 'build',         // legacy alias: pn → build
+    'pack-next': 'build' // legacy alias: clay pack-next → clay build
   },
   listCommands = Object.keys(commands).concat(Object.values(commands));
 

lib/cmd/build/fonts.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs-extra');
+const { globSync } = require('glob');
+
+const CWD = process.cwd();
+
+const FONT_EXTS = 'css,woff,woff2,otf,ttf';
+const FONTS_SRC_GLOB = path.join(CWD, 'styleguides', '*', 'fonts', `*.{${FONT_EXTS}}`);
+
+// Output destinations
+const CSS_DEST = path.join(CWD, 'public', 'css');
+const BINARY_DEST = path.join(CWD, 'public', 'fonts');
+
+const ASSET_HOST = process.env.CLAYCLI_COMPILE_ASSET_HOST
+  ? process.env.CLAYCLI_COMPILE_ASSET_HOST.replace(/\/$/, '')
+  : '';
+const ASSET_PATH = process.env.CLAYCLI_COMPILE_ASSET_PATH || '';
+
+/**
+ * Extract the styleguide name from an absolute font file path.
+ * Expected structure: .../styleguides/{sg}/fonts/{file}
+ *
+ * @param {string} srcPath
+ * @returns {string} styleguide name
+ */
+function getStyleguide(srcPath) {
+  const parts = srcPath.split(path.sep);
+  const sgIdx = parts.lastIndexOf('styleguides');
+
+  return parts[sgIdx + 1];
+}
+
+/**
+ * Process fonts:
+ *   - CSS files: apply $asset-host / $asset-path substitution, then concatenate
+ *     all per-styleguide CSS into public/css/_linked-fonts.{sg}.css so that
+ *     amphora-html can find and inline the @font-face declarations.
+ *   - Binary files (.woff, .woff2, .otf, .ttf): copy as-is to
+ *     public/fonts/{styleguide}/ for cases where fonts are self-hosted.
+ *
+ * @returns {Promise<number>} count of files processed
+ */
+async function buildFonts() {
+  const files = globSync(FONTS_SRC_GLOB);
+
+  if (files.length === 0) return 0;
+
+  // Group by styleguide
+  const byStyleguide = {};
+
+  for (const srcPath of files) {
+    const sg = getStyleguide(srcPath);
+
+    if (!byStyleguide[sg]) {
+      byStyleguide[sg] = { css: [], binary: [] };
+    }
+
+    const ext = path.extname(srcPath).toLowerCase();
+
+    if (ext === '.css') {
+      byStyleguide[sg].css.push(srcPath);
+    } else {
+      byStyleguide[sg].binary.push(srcPath);
+    }
+  }
+
+  await Promise.all([
+    fs.ensureDir(CSS_DEST),
+    fs.ensureDir(BINARY_DEST),
+  ]);
+
+  await Promise.all(Object.entries(byStyleguide).map(async ([sg, { css, binary }]) => {
+    // Write _linked-fonts.{sg}.css — amphora-html looks for this file to inject
+    // @font-face declarations into every page that uses this styleguide.
+    if (css.length > 0) {
+      const cssChunks = await Promise.all(css.map(async (srcPath) => {
+        let content = await fs.readFile(srcPath, 'utf8');
+
+        content = content.replace(/\$asset-host/g, ASSET_HOST);
+        content = content.replace(/\$asset-path/g, ASSET_PATH);
+
+        return content;
+      }));
+
+      await fs.writeFile(
+        path.join(CSS_DEST, `_linked-fonts.${sg}.css`),
+        cssChunks.join('\n'),
+        'utf8'
+      );
+    }
+
+    // Copy binary font files (self-hosted scenarios)
+    await Promise.all(binary.map(async (srcPath) => {
+      const destPath = path.join(BINARY_DEST, sg, path.basename(srcPath));
+
+      await fs.ensureDir(path.dirname(destPath));
+      await fs.copy(srcPath, destPath, { overwrite: true });
+    }));
+  }));
+
+  return files.length;
+}
+
+module.exports = { buildFonts, FONTS_SRC_GLOB };