emily-css 1.2.9 → 1.2.10

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `emily-css` are documented here.
 
 ---
 
+## v1.2.10 — May 2026
+
+**v1.2.10 — Config validation & CI/CD**
+
+### Added
+- feat: add config validation, E2E chaos testing, and GitHub Actions CI
+
+### Changed
+- add randomized E2E config fuzzing suite
+- add GitHub Actions test workflow and PR template
+
+---
 ## v1.2.9 — May 2026
 
 **Fix baseFontSize handling in emily-css init and generated CSS**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emily-css",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "A config-driven utility CSS framework. Define your brand once, generate the CSS.",
   "main": "src/index.js",
   "bin": {
@@ -19,7 +19,8 @@
     "dev": "nodemon src/index.js",
     "dev:full": "nodemon src/index.js -- --keep-full",
     "init": "node src/init.js",
-    "test": "node tests/test.js",
+    "test": "node tests/test.js && node src/test/e2e.test.js",
+    "test:e2e": "node src/test/e2e.test.js",
     "emily:showcase": "node src/showcase.js",
     "commit": "node scripts/commit.js",
     "release": "node scripts/release.js",

package/src/index.js

@@ -1,9 +1,10 @@
 'use strict';
 
 const fs = require('fs');
-const path = require('path');
-const { generateManifest } = require('./manifest');
-const { generateIntellisense } = require('./intellisense');
+const path = require('path');
+const { generateManifest } = require('./manifest');
+const { generateIntellisense } = require('./intellisense');
+const { validateConfigOrExit } = require('./validateConfig');
 const {
   getConfigPath,
   getConfig,
@@ -1508,8 +1509,9 @@ function generatePatternComponents() {
 // BUILD FUNCTION
 // ============================================================================
 
-function buildFullFramework() {
-  const config = getConfig();
+function buildFullFramework() {
+  validateConfigOrExit();
+  const config = getConfig();
 
   console.log('Building EmilyCSS full framework...');
 

package/src/init.js

@@ -3,9 +3,16 @@ const path = require("path");
 const crossSpawn = require("cross-spawn");
 const { Select, Input, Confirm } = require("enquirer");
 const chalk = require("chalk");
-const ora = require("ora");
-const boxen = require("boxen");
-const { DEFAULT_PURGE_IGNORE, PURGE_EXTENSIONS } = require("./constants.js");
+const ora = require("ora");
+const boxen = require("boxen");
+const { DEFAULT_PURGE_IGNORE, PURGE_EXTENSIONS } = require("./constants.js");
+const {
+  ALLOWED_FONT_FAMILIES,
+  validateHexColour,
+  validateSpacingValue,
+  validateFontFamily,
+  validateConfigShape,
+} = require("./validate.js");
 
 // ============================================================================
 // CONSTANTS
@@ -48,15 +55,7 @@ const COLOUR_PRESETS = {
   ],
 };
 
-const FONT_OPTIONS = [
-  { name: "lexend", message: "Lexend (clear, accessible - recommended)" },
-  { name: "inter", message: "Inter (clean, widely used)" },
-  { name: "dm-sans", message: "DM Sans (modern, geometric)" },
-  { name: "nunito", message: "Nunito (friendly, rounded)" },
-  { name: "atkinson", message: "Atkinson Hyperlegible (maximum legibility)" },
-  { name: "system", message: "System sans-serif (no download required)" },
-];
-const CORE_COLOUR_KEYS = new Set([
+const CORE_COLOUR_KEYS = new Set([
   "brand",
   "accent",
   "btn-primary",
@@ -71,13 +70,9 @@ const CORE_COLOUR_KEYS = new Set([
 // HELPERS
 // ============================================================================
 
-function isValidHex(hex) {
-  return /^#[0-9A-F]{6}$/i.test(hex);
-}
-
-function isPlainObject(value) {
-  return (
-    value !== null &&
+function isPlainObject(value) {
+  return (
+    value !== null &&
     typeof value === "object" &&
     !Array.isArray(value)
   );
@@ -110,26 +105,63 @@ function colourSwatch(hex) {
   return chalk.hex(hex)("■");
 }
 
-function normaliseHex(value) {
-  return typeof value === "string" && isValidHex(value)
-    ? value.toUpperCase()
-    : null;
-}
-
-async function askHex(promptName, message, initial) {
-  const value = await new Input({
-    name: promptName,
-    message,
-    initial: initial || "#000000",
-    validate(value) {
-      return isValidHex(value)
-        ? true
-        : "Enter a valid hex colour, e.g. #0077B6";
-    },
-  }).run();
-
-  return value.toUpperCase();
-}
+function normaliseHex(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  const result = validateHexColour(trimmed);
+  return result.valid ? trimmed.toUpperCase() : null;
+}
+
+function formatValueForMessage(value) {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  return "'" + String(value) + "'";
+}
+
+async function askValidatedInput({
+  promptName,
+  message,
+  initial,
+  validator,
+  normalise,
+}) {
+  let nextInitial = initial;
+
+  while (true) {
+    const raw = await new Input({
+      name: promptName,
+      message,
+      initial: nextInitial,
+    }).run();
+
+    const value = typeof raw === "string" ? raw.trim() : raw;
+    const result = validator(value);
+
+    if (result.valid) {
+      console.log(chalk.green("✓ Valid"));
+      return typeof normalise === "function" ? normalise(value) : value;
+    }
+
+    console.log(
+      chalk.red(
+        "✗ Invalid: " + result.reason + " (got " + formatValueForMessage(raw) + ")",
+      ),
+    );
+    nextInitial = value || initial;
+  }
+}
+
+async function askHex(promptName, message, initial) {
+  return askValidatedInput({
+    promptName,
+    message,
+    initial: initial || "#000000",
+    validator: validateHexColour,
+    normalise: function (value) {
+      return String(value).toUpperCase();
+    },
+  });
+}
 
 async function askColourFromPresets(label, presets, defaultHex, currentHex) {
   const defaultHexValue = normaliseHex(defaultHex);
@@ -224,14 +256,7 @@ function readExistingConfig() {
   }
 }
 
-function getFontInitialIndex(fontKey, fallbackIndex) {
-  if (!fontKey || typeof fontKey !== "string") return fallbackIndex;
-  const normalised = fontKey.toLowerCase();
-  const index = FONT_OPTIONS.findIndex((option) => option.name === normalised);
-  return index === -1 ? fallbackIndex : index;
-}
-
-function getExistingAdditionalColours(existingColours) {
+function getExistingAdditionalColours(existingColours) {
   if (!isPlainObject(existingColours)) return {};
 
   const additional = {};
@@ -247,14 +272,13 @@ function getExistingAdditionalColours(existingColours) {
   return additional;
 }
 
-function getBaseUnitInitial(config) {
-  const rawBaseUnit = config && typeof config.baseUnit === "string"
-    ? config.baseUnit
-    : "";
-  const parsed = Number.parseInt(rawBaseUnit, 10);
-  if (Number.isNaN(parsed) || parsed <= 0) return "18";
-  return String(parsed);
-}
+function getBaseUnitInitial(config) {
+  const rawBaseUnit = config && typeof config.baseUnit === "string"
+    ? config.baseUnit.trim()
+    : "";
+  if (validateSpacingValue(rawBaseUnit).valid) return rawBaseUnit;
+  return "18px";
+}
 
 function hasDependency(packageJson, dependencyName) {
   if (!packageJson) return false;
@@ -435,11 +459,11 @@ function detectProject() {
 // CONFIG BUILDER
 // ============================================================================
 
-function createDefaultConfig({
-  name,
-  colours,
-  headingFont,
-  bodyFont,
+function createDefaultConfig({
+  name,
+  colours,
+  headingFont,
+  bodyFont,
   baseUnit,
   baseFontSize,
   detectedProject,
@@ -448,7 +472,7 @@ function createDefaultConfig({
     name,
     description: name + " design system",
 
-    baseUnit: baseUnit + "px",
+    baseUnit,
     baseFontSize: baseFontSize || "16px",
 
     fontFamily: {
@@ -656,14 +680,17 @@ async function init() {
         ? titleCasePackageName(packageJsonData.name)
         : "My Design System";
 
-    const projectName = await new Input({
-      name: "projectName",
-      message: "Project name",
-      initial: pkgName,
-      validate: function (value) {
-        return value.trim() ? true : "Project name is required";
-      },
-    }).run();
+    const projectName = await askValidatedInput({
+      promptName: "projectName",
+      message: "Project name",
+      initial: pkgName,
+      validator: function (value) {
+        if (typeof value !== "string" || !value.trim()) {
+          return { valid: false, reason: "project name is required" };
+        }
+        return { valid: true };
+      },
+    });
 
     if (!projectName || !projectName.trim()) {
       console.log(chalk.red("\nProject name is required.\n"));
@@ -778,29 +805,45 @@ async function init() {
 
     console.log(chalk.bold("\n" + chalk.magenta("→") + " Typography"));
 
-    const headingFont = await new Select({
-      name: "headingFont",
-      message: "Heading font",
-      choices: FONT_OPTIONS,
-      initial: getFontInitialIndex(
-        isPlainObject(existingConfig && existingConfig.fontFamily)
-          ? existingConfig.fontFamily.heading
-          : existingConfig && existingConfig.fontFamily,
-        0,
-      ),
-    }).run();
-
-    const bodyFont = await new Select({
-      name: "bodyFont",
-      message: "Body font",
-      choices: FONT_OPTIONS,
-      initial: getFontInitialIndex(
-        isPlainObject(existingConfig && existingConfig.fontFamily)
-          ? existingConfig.fontFamily.body
-          : existingConfig && existingConfig.fontFamily,
-        1,
-      ),
-    }).run();
+    console.log(
+      chalk.gray(
+        "  Allowed font families: " + ALLOWED_FONT_FAMILIES.join(", "),
+      ),
+    );
+
+    const headingFont = await askValidatedInput({
+      promptName: "headingFont",
+      message: "Heading font family",
+      initial: (function () {
+        const existingHeading = isPlainObject(existingConfig && existingConfig.fontFamily)
+          ? existingConfig.fontFamily.heading
+          : existingConfig && existingConfig.fontFamily;
+        if (typeof existingHeading !== "string") return "lexend";
+        const candidate = existingHeading.trim().toLowerCase();
+        return validateFontFamily(candidate).valid ? candidate : "lexend";
+      })(),
+      validator: validateFontFamily,
+      normalise: function (value) {
+        return String(value).trim().toLowerCase();
+      },
+    });
+
+    const bodyFont = await askValidatedInput({
+      promptName: "bodyFont",
+      message: "Body font family",
+      initial: (function () {
+        const existingBody = isPlainObject(existingConfig && existingConfig.fontFamily)
+          ? existingConfig.fontFamily.body
+          : existingConfig && existingConfig.fontFamily;
+        if (typeof existingBody !== "string") return "inter";
+        const candidate = existingBody.trim().toLowerCase();
+        return validateFontFamily(candidate).valid ? candidate : "inter";
+      })(),
+      validator: validateFontFamily,
+      normalise: function (value) {
+        return String(value).trim().toLowerCase();
+      },
+    });
 
     const baseFontSize = await new Select({
       name: "baseFontSize",
@@ -817,22 +860,15 @@ async function init() {
     // SPACING
     // =========================================================================
 
-    const baseUnitRaw = await new Input({
-      name: "baseUnit",
-      message: "Base spacing unit in px (label/documentation only)",
-      initial: getBaseUnitInitial(existingConfig),
-      validate: function (value) {
-        const parsed = Number.parseInt(value, 10);
-
-        if (Number.isNaN(parsed) || parsed <= 0) {
-          return "Must be a positive number.";
-        }
-
-        return true;
-      },
-    }).run();
-
-    const baseUnit = Number.parseInt(baseUnitRaw, 10);
+    const baseUnit = await askValidatedInput({
+      promptName: "baseUnit",
+      message: "Base spacing unit in px (label/documentation only) e.g. 1rem or 10px",
+      initial: getBaseUnitInitial(existingConfig),
+      validator: validateSpacingValue,
+      normalise: function (value) {
+        return String(value).trim().toLowerCase();
+      },
+    });
 
     // =========================================================================
     // PURGE / OUTPUT
@@ -875,15 +911,24 @@ async function init() {
       config.description = config.name + " design system";
     }
 
-    config.baseUnit = baseUnit + "px";
-    config.baseFontSize = baseFontSize || "16px";
-    config.fontFamily = {
-      heading: headingFont,
-      body: bodyFont,
-    };
-    config.colours = colours;
-
-    const configPath = path.join(process.cwd(), "emily.config.json");
+    config.baseUnit = baseUnit;
+    config.baseFontSize = baseFontSize || "16px";
+    config.fontFamily = {
+      heading: headingFont,
+      body: bodyFont,
+    };
+    config.colours = colours;
+
+    const finalValidation = validateConfigShape(config);
+    if (!finalValidation.valid) {
+      console.log(chalk.red("\n✗ Config validation failed. emily.config.json was not written.\n"));
+      finalValidation.errors.forEach(function (error) {
+        console.log(chalk.red("  - " + error));
+      });
+      process.exit(1);
+    }
+
+    const configPath = path.join(process.cwd(), "emily.config.json");
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
 
     console.log("");

package/src/test/e2e.test.js

@@ -0,0 +1,332 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const TOTAL_RUNS = 60;
+const FONT_KEYS = ['system', 'inter', 'lexend', 'georgia', 'dm-sans', 'nunito', 'atkinson', 'mono'];
+const BUILD_MODULE_PATH = path.resolve(__dirname, '../index.js');
+
+function readBaseConfig() {
+  const configPath = path.join(__dirname, '../../emily.config.json');
+  return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function randomInt(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+function randomChoice(values) {
+  return values[randomInt(0, values.length - 1)];
+}
+
+function createDeepObject(depth) {
+  let root = {};
+  let cursor = root;
+  for (let i = 0; i < depth; i += 1) {
+    cursor['layer' + i] = {};
+    cursor = cursor['layer' + i];
+  }
+  cursor.value = 'deep-value';
+  return root;
+}
+
+function createCircularObject(baseConfig) {
+  const config = clone(baseConfig);
+  const circular = { label: 'circular' };
+  circular.self = circular;
+  config.attackVector = circular;
+  return config;
+}
+
+function ensureBaselineShape(config) {
+  if (!config || typeof config !== 'object') {
+    return config;
+  }
+
+  config.output = {
+    css: 'dist/emily.min.css',
+    fullCss: 'dist/emily.css',
+  };
+  return config;
+}
+
+function withConfigMutation(name, mutate) {
+  return {
+    name,
+    create(baseConfig) {
+      const config = ensureBaselineShape(clone(baseConfig));
+      mutate(config);
+      return { type: 'config', payload: config };
+    },
+  };
+}
+
+function withRawJson(name, payload) {
+  return {
+    name,
+    create() {
+      return { type: 'raw', payload };
+    },
+  };
+}
+
+const ABUSE_CASES = [
+  withConfigMutation('colour-8-digit-hex', (config) => { config.colours.brand = '#FF0000FF'; }),
+  withConfigMutation('colour-3-digit-hex', (config) => { config.colours.brand = '#F00'; }),
+  withConfigMutation('colour-invalid-hex', (config) => { config.colours.brand = '#GGGGGG'; }),
+  withConfigMutation('colour-named', (config) => { config.colours.brand = 'red'; }),
+  withConfigMutation('colour-null', (config) => { config.colours.brand = null; }),
+  withConfigMutation('colour-empty', (config) => { config.colours.brand = ''; }),
+  withConfigMutation('colour-number', (config) => { config.colours.brand = 123456; }),
+  withConfigMutation('colour-xss-payload', (config) => { config.colours.brand = '<script>alert("hi")</script>'; }),
+
+  withConfigMutation('spacing-negative-px', (config) => { config.spacing.scale['4'] = '-10px'; }),
+  withConfigMutation('spacing-negative-rem', (config) => { config.spacing.scale['4'] = '-1rem'; }),
+  withConfigMutation('spacing-huge-rem', (config) => { config.spacing.scale['4'] = '99999rem'; }),
+  withConfigMutation('spacing-huge-px', (config) => { config.spacing.scale['4'] = '1000000px'; }),
+  withConfigMutation('spacing-invalid-no-unit', (config) => { config.spacing.scale['4'] = '10'; }),
+  withConfigMutation('spacing-invalid-unit', (config) => { config.spacing.scale['4'] = '10xx'; }),
+  withConfigMutation('spacing-invalid-whitespace-unit', (config) => { config.spacing.scale['4'] = '10 rem'; }),
+  withConfigMutation('spacing-null-value', (config) => { config.spacing.scale['4'] = null; }),
+  withConfigMutation('spacing-nonnumeric', (config) => { config.spacing.scale['4'] = 'abc'; }),
+  withConfigMutation('spacing-infinity', (config) => { config.spacing.scale['4'] = 'infinity'; }),
+  withConfigMutation('spacing-descending-scale', (config) => {
+    config.spacing.scale = {
+      '10': '2.5rem',
+      '8': '2rem',
+      '6': '1.5rem',
+      '4': '1rem',
+      '2': '0.5rem',
+      '0': '0px',
+    };
+  }),
+
+  withConfigMutation('font-nonexistent', (config) => { config.fontFamily = { heading: 'banana-sans', body: 'foo' }; }),
+  withConfigMutation('font-null', (config) => { config.fontFamily = null; }),
+  withConfigMutation('font-empty-string', (config) => { config.fontFamily = ''; }),
+  withConfigMutation('font-number', (config) => { config.fontFamily = 42; }),
+  withConfigMutation('font-array', (config) => { config.fontFamily = ['inter', 'lexend']; }),
+  withConfigMutation('font-object-weird-types', (config) => { config.fontFamily = { heading: {}, body: [] }; }),
+  withConfigMutation('font-unicode-edge', (config) => { config.fontFamily = { heading: '\uD83D\uDCA5\u200D\uFE0F', body: '\u2066\u2067\u2069' }; }),
+  withConfigMutation('font-very-long-string', (config) => {
+    const long = 'x'.repeat(10000);
+    config.fontFamily = { heading: long, body: long };
+  }),
+
+  withConfigMutation('missing-colours', (config) => { delete config.colours; }),
+  withConfigMutation('missing-spacing', (config) => { delete config.spacing; }),
+  withConfigMutation('wrong-type-colours-string', (config) => { config.colours = 'not-an-object'; }),
+  withConfigMutation('wrong-type-spacing-string', (config) => { config.spacing = 'not-an-object'; }),
+  withConfigMutation('wrong-type-transitions-string', (config) => { config.transitions = 'not-an-object'; }),
+  withConfigMutation('unknown-extra-fields', (config) => {
+    config.__unknown = true;
+    config.notExpected = { nested: [1, 2, 3] };
+  }),
+  withConfigMutation('deeply-nested-object', (config) => {
+    config.veryDeep = createDeepObject(300);
+  }),
+  {
+    name: 'circular-reference',
+    create(baseConfig) {
+      return { type: 'config', payload: createCircularObject(baseConfig) };
+    },
+  },
+
+  withConfigMutation('transition-negative-fast', (config) => { config.transitions.fast = '-100ms'; }),
+  withConfigMutation('transition-negative-base', (config) => { config.transitions.base = '-200ms'; }),
+  withConfigMutation('transition-negative-slow', (config) => { config.transitions.slow = '-300ms'; }),
+  withConfigMutation('transition-nonnumeric-fast', (config) => { config.transitions.fast = 'abc'; }),
+  withConfigMutation('transition-null-base', (config) => { config.transitions.base = null; }),
+  withConfigMutation('transition-order-invalid', (config) => {
+    config.transitions.fast = '300ms';
+    config.transitions.base = '200ms';
+    config.transitions.slow = '100ms';
+  }),
+  withConfigMutation('transition-number-types', (config) => {
+    config.transitions.fast = 100;
+    config.transitions.base = 200;
+    config.transitions.slow = 300;
+  }),
+  withConfigMutation('transition-timing-malicious', (config) => {
+    config.transitions.timing = 'cubic-bezier(0.4, 0, 0.2, 1));background:url(javascript:alert(1))/*';
+  }),
+
+  withRawJson('top-level-null', 'null'),
+  withRawJson('top-level-string', '"oops"'),
+  withRawJson('top-level-array', '["bad", "config"]'),
+  withRawJson('invalid-json-syntax', '{"colours": {"brand": "#FF0000",}}'),
+
+  withConfigMutation('spacing-scale-missing', (config) => { delete config.spacing.scale; }),
+  withConfigMutation('spacing-scale-null', (config) => { config.spacing.scale = null; }),
+  withConfigMutation('spacing-scale-array', (config) => { config.spacing.scale = ['1rem', '2rem']; }),
+  withConfigMutation('manifest-wrong-type', (config) => { config.manifest = 'yes'; }),
+  withConfigMutation('output-wrong-type', (config) => { config.output = 'dist/emily.css'; }),
+  withConfigMutation('breakpoints-wrong-type', (config) => { config.breakpoints = 'sm,md,lg'; }),
+  withConfigMutation('typography-null', (config) => { config.typography = null; }),
+  withConfigMutation('typography-fontsizes-string', (config) => { config.typography.fontSizes = '16px'; }),
+  withConfigMutation('typography-fontweights-number', (config) => { config.typography.fontWeights = 700; }),
+  withConfigMutation('colours-empty-object', (config) => { config.colours = {}; }),
+  withConfigMutation('colours-undefined-via-delete', (config) => { delete config.colours.brand; }),
+  withConfigMutation('spacing-proto-pollution-shape', (config) => {
+    config.spacing.scale = {
+      '__proto__': { polluted: true },
+      '4': '1rem',
+      '8': '2rem',
+      '0': '0px',
+    };
+  }),
+];
+
+function writeConfigFile(tempDir, caseDef, baseConfig) {
+  const generated = caseDef.create(baseConfig);
+  const configPath = path.join(tempDir, 'emily.config.json');
+
+  if (generated.type === 'raw') {
+    fs.writeFileSync(configPath, generated.payload);
+    return;
+  }
+
+  assert.strictEqual(generated.type, 'config', `Unknown generated config type: ${generated.type}`);
+  fs.writeFileSync(configPath, JSON.stringify(generated.payload, null, 2));
+}
+
+function runBuildInSubprocess(tempDir) {
+  const runner = [
+    'const { buildFullFramework } = require(' + JSON.stringify(BUILD_MODULE_PATH) + ');',
+    'try {',
+    '  buildFullFramework();',
+    '  process.exit(0);',
+    '} catch (error) {',
+    '  const message = error && error.message ? error.message : String(error);',
+    '  console.error(message);',
+    '  process.exit(2);',
+    '}',
+  ].join('\n');
+
+  return spawnSync(process.execPath, ['-e', runner], {
+    cwd: tempDir,
+    encoding: 'utf8',
+  });
+}
+
+function assertFailureLooksClear(output, caseName) {
+  const trimmed = output.trim();
+  assert.ok(trimmed.length >= 8, `Case "${caseName}" failed but gave no clear error message`);
+  assert.ok(trimmed !== '[object Object]', `Case "${caseName}" returned an unhelpful object error`);
+}
+
+function formatErrorSnippet(message) {
+  return String(message || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 100);
+}
+
+function assertSuccessLooksSensible(tempDir, caseName) {
+  const cssPath = path.join(tempDir, 'dist', 'emily.css');
+  assert.ok(fs.existsSync(cssPath), `Case "${caseName}" succeeded but did not output dist/emily.css`);
+
+  const cssContent = fs.readFileSync(cssPath, 'utf8');
+  assert.ok(cssContent.trim().length > 0, `Case "${caseName}" succeeded but CSS output was empty`);
+
+  const manifestPath = path.join(tempDir, 'dist', 'emily.manifest.json');
+  if (fs.existsSync(manifestPath)) {
+    const raw = fs.readFileSync(manifestPath, 'utf8');
+    assert.doesNotThrow(() => JSON.parse(raw), `Case "${caseName}" wrote invalid manifest JSON`);
+  }
+}
+
+function run() {
+  const baseConfig = readBaseConfig();
+  const initialCwd = process.cwd();
+  const createdTempDirs = [];
+  let handledFailures = 0;
+  let gracefulSuccesses = 0;
+  let crashes = 0;
+  const gracefulSuccessCases = [];
+  const handledFailureCases = [];
+
+  for (let i = 0; i < TOTAL_RUNS; i += 1) {
+    const runLabel = `[${i + 1}/${TOTAL_RUNS}]`;
+    const caseDef = randomChoice(ABUSE_CASES);
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'emily-chaos-'));
+    createdTempDirs.push(tempDir);
+
+    try {
+      try {
+        writeConfigFile(tempDir, caseDef, baseConfig);
+      } catch (error) {
+        const message = error && error.message ? error.message : String(error);
+        assertFailureLooksClear(message, caseDef.name);
+        const snippet = formatErrorSnippet(message);
+        console.log(`${runLabel} ${caseDef.name} ... FAIL (${snippet})`);
+        handledFailures += 1;
+        handledFailureCases.push({ name: caseDef.name, error: snippet });
+        continue;
+      }
+
+      const result = runBuildInSubprocess(tempDir);
+      const output = (result.stdout || '') + '\n' + (result.stderr || '');
+
+      if (result.status === 0) {
+        assertSuccessLooksSensible(tempDir, caseDef.name);
+        console.log(`${runLabel} ${caseDef.name} ... OK (graceful success)`);
+        gracefulSuccesses += 1;
+        gracefulSuccessCases.push(caseDef.name);
+      } else if (result.status === 1 || result.status === 2) {
+        assertFailureLooksClear(output, caseDef.name);
+        const snippet = formatErrorSnippet(output);
+        console.log(`${runLabel} ${caseDef.name} ... FAIL (${snippet})`);
+        handledFailures += 1;
+        handledFailureCases.push({ name: caseDef.name, error: snippet });
+      } else {
+        crashes += 1;
+        const snippet = formatErrorSnippet(output || `exit ${result.status}`);
+        console.log(`${runLabel} ${caseDef.name} ... CRASH (${snippet})`);
+        throw new Error(
+          `Case "${caseDef.name}" crashed (exit ${result.status}). Output:\n${output.trim() || '(no output)'}`,
+        );
+      }
+    } catch (error) {
+      throw new Error(`Chaos run ${i + 1}/${TOTAL_RUNS} failed for case "${caseDef.name}": ${error.message}`);
+    } finally {
+      process.chdir(initialCwd);
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+
+  const leftoverTempDirs = createdTempDirs.filter((tempDir) => fs.existsSync(tempDir));
+  assert.strictEqual(leftoverTempDirs.length, 0, `Temp directory cleanup failed for ${leftoverTempDirs.length} case(s)`);
+  assert.ok(handledFailures + gracefulSuccesses >= 50, 'Expected at least 50 chaos runs');
+  assert.strictEqual(crashes, 0, `Detected ${crashes} unhandled crash(es) during chaos testing`);
+
+  console.log('\nResults:');
+  console.log(`  Graceful successes (${gracefulSuccesses}): ${gracefulSuccessCases.join(', ') || '(none)'}`);
+  console.log(`  Handled failures (${handledFailures}):`);
+  if (handledFailureCases.length === 0) {
+    console.log('  - (none)');
+  } else {
+    handledFailureCases.forEach((entry) => {
+      console.log(`  - ${entry.name}: ${entry.error}`);
+    });
+  }
+
+  console.log(
+    `✓ Chaos testing passed (50+ abuse cases, 0 crashes) [runs=${TOTAL_RUNS}, handled-failures=${handledFailures}, graceful-successes=${gracefulSuccesses}]`,
+  );
+}
+
+try {
+  run();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/src/validate.js

@@ -0,0 +1,227 @@
+'use strict';
+
+const ALLOWED_FONT_FAMILIES = [
+  'system',
+  'inter',
+  'lexend',
+  'georgia',
+  'dm-sans',
+  'nunito',
+  'atkinson',
+  'mono',
+];
+
+const ALLOWED_FONT_FAMILY_SET = new Set(ALLOWED_FONT_FAMILIES);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateHexColour(value) {
+  if (typeof value !== 'string') {
+    return { valid: false, reason: 'must be a string in #RRGGBB format' };
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return { valid: false, reason: 'must be a 6-digit hex like #FF0000 (value is empty)' };
+  }
+
+  if (!trimmed.startsWith('#')) {
+    return { valid: false, reason: 'must include # symbol (example: #FF0000)' };
+  }
+
+  if (!/^#[0-9A-Fa-f]{6}$/.test(trimmed)) {
+    return { valid: false, reason: 'must be #RRGGBB format' };
+  }
+
+  return { valid: true };
+}
+
+function validateSpacingValue(value) {
+  if (typeof value !== 'string') {
+    return { valid: false, reason: 'must be a string CSS length like 1rem or 10px' };
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return { valid: false, reason: 'must be a CSS length like 1rem or 10px (value is empty)' };
+  }
+
+  if (/\s/.test(trimmed)) {
+    return { valid: false, reason: 'must not contain spaces (use 10px, not 10 px)' };
+  }
+
+  if (trimmed.startsWith('-')) {
+    return { valid: false, reason: 'must not be negative (e.g. -1rem is not allowed)' };
+  }
+
+  const match = /^(\d+(?:\.\d+)?)(rem|px)$/i.exec(trimmed);
+  if (!match) {
+    return { valid: false, reason: 'must be numeric and use rem or px units (e.g. 1rem, 10px)' };
+  }
+
+  const numericPart = Number.parseFloat(match[1]);
+  const unit = match[2].toLowerCase();
+
+  if (!Number.isFinite(numericPart)) {
+    return { valid: false, reason: 'must be a finite numeric value' };
+  }
+
+  if (unit === 'rem' && numericPart > 9999) {
+    return { valid: false, reason: 'rem value is too large (max 9999rem)' };
+  }
+
+  if (unit === 'px' && numericPart > 99999) {
+    return { valid: false, reason: 'px value is too large (max 99999px)' };
+  }
+
+  return { valid: true };
+}
+
+function validateFontFamily(value) {
+  if (typeof value !== 'string') {
+    return { valid: false, reason: 'must be a string font key' };
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return { valid: false, reason: 'must not be empty' };
+  }
+
+  if (!ALLOWED_FONT_FAMILY_SET.has(trimmed)) {
+    return {
+      valid: false,
+      reason: `must be one of: ${ALLOWED_FONT_FAMILIES.join(', ')}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+function validateConfigShape(config) {
+  const errors = [];
+
+  if (!isPlainObject(config)) {
+    return {
+      valid: false,
+      errors: ['config must be an object (not null, array, or string)'],
+    };
+  }
+
+  const requiredFields = ['colours', 'spacing', 'fontFamily', 'output'];
+  requiredFields.forEach((field) => {
+    if (!(field in config)) {
+      errors.push(`missing required field: ${field}`);
+    }
+  });
+
+  if ('colours' in config) {
+    if (!isPlainObject(config.colours)) {
+      errors.push('colours must be an object of #RRGGBB values');
+    } else {
+      Object.entries(config.colours).forEach(([name, value]) => {
+        const result = validateHexColour(value);
+        if (!result.valid) {
+          errors.push(`colours.${name} ${result.reason}`);
+        }
+      });
+    }
+  }
+
+  if ('spacing' in config) {
+    if (!isPlainObject(config.spacing)) {
+      errors.push('spacing must be an object');
+    } else if (!('scale' in config.spacing)) {
+      errors.push('spacing must include a scale key');
+    } else if (!isPlainObject(config.spacing.scale)) {
+      errors.push('spacing.scale must be an object of spacing values');
+    } else {
+      const spacingKeys = Object.keys(config.spacing.scale);
+      if (spacingKeys.length === 0) {
+        errors.push('spacing.scale must not be empty');
+      }
+
+      spacingKeys.forEach((key) => {
+        if (!/^(\d+(\.\d+)?|px)$/.test(key)) {
+          errors.push(`spacing.scale key "${key}" must be numeric (or "px" for legacy support)`);
+        }
+
+        const result = validateSpacingValue(config.spacing.scale[key]);
+        if (!result.valid) {
+          errors.push(`spacing.scale.${key} ${result.reason}`);
+        }
+      });
+    }
+  }
+
+  if ('fontFamily' in config) {
+    if (!isPlainObject(config.fontFamily)) {
+      errors.push('fontFamily must be an object with heading and body');
+    } else {
+      if (!('heading' in config.fontFamily)) {
+        errors.push('fontFamily.heading is required');
+      } else {
+        const headingValidation = validateFontFamily(config.fontFamily.heading);
+        if (!headingValidation.valid) {
+          errors.push(`fontFamily.heading ${headingValidation.reason}`);
+        }
+      }
+
+      if (!('body' in config.fontFamily)) {
+        errors.push('fontFamily.body is required');
+      } else {
+        const bodyValidation = validateFontFamily(config.fontFamily.body);
+        if (!bodyValidation.valid) {
+          errors.push(`fontFamily.body ${bodyValidation.reason}`);
+        }
+      }
+    }
+  }
+
+  if ('output' in config) {
+    if (!isPlainObject(config.output)) {
+      errors.push('output must be an object');
+    } else {
+      if (typeof config.output.css !== 'string' || !config.output.css.trim()) {
+        errors.push('output.css must be a non-empty string');
+      }
+
+      if (typeof config.output.fullCss !== 'string' || !config.output.fullCss.trim()) {
+        errors.push('output.fullCss must be a non-empty string');
+      }
+    }
+  }
+
+  if ('manifest' in config) {
+    if (typeof config.manifest !== 'boolean' && !isPlainObject(config.manifest)) {
+      errors.push('manifest must be a boolean or an object');
+    }
+
+    if (isPlainObject(config.manifest)) {
+      if ('enabled' in config.manifest && typeof config.manifest.enabled !== 'boolean') {
+        errors.push('manifest.enabled must be a boolean');
+      }
+
+      if ('output' in config.manifest) {
+        if (typeof config.manifest.output !== 'string' || !config.manifest.output.trim()) {
+          errors.push('manifest.output must be a non-empty string when provided');
+        }
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+
+  return { valid: true, errors: [] };
+}
+
+module.exports = {
+  ALLOWED_FONT_FAMILIES,
+  validateHexColour,
+  validateSpacingValue,
+  validateFontFamily,
+  validateConfigShape,
+};

package/src/validateConfig.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { validateConfigShape } = require('./validate');
+
+function validateConfigOrExit() {
+  const configPath = path.join(process.cwd(), 'emily.config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error('Invalid EmilyCSS config: emily.config.json not found.');
+    process.exit(1);
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (error) {
+    console.error('Invalid EmilyCSS config: emily.config.json is not valid JSON.');
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  const result = validateConfigShape(config);
+  if (!result.valid) {
+    console.error('Invalid EmilyCSS config:');
+    result.errors.forEach((error) => {
+      console.error('- ' + error);
+    });
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  validateConfigOrExit,
+};