@madgex/fert 7.0.13 → 7.1.0

package/bin/cli.js

@@ -10,6 +10,7 @@ import { printBanner } from './utils/index.js';
 import { serviceCommandBootstrap } from './commands/_service-command-bootstrap.js';
 import { configsCommand } from './commands/configs.js';
 import { initCommand } from './commands/init.js';
+import { validateCommand } from './commands/validate.js';
 
 const cli = cac('fert');
 
@@ -56,6 +57,8 @@ const run = () => {
     .option('--cpid <cpid>', 'Specify the clientPropertyId to use in the new project')
     .action((...args) => initCommand(...args));
 
+  cli.command('validate', 'Validate branding project for common issues').action((...args) => validateCommand(...args));
+
   cli.option('--no-cache', 'Do not use cache');
   cli.option('--purge-cache', 'Purge all caches');
   cli.help();

package/bin/commands/build.js

@@ -6,6 +6,10 @@ import { bundleEntry } from './build-tasks/bundle-entry.js';
 import { buildCssFromTokens } from './build-tasks/build-tokens.js';
 import { buildExternalAssets } from './build-tasks/build-external-assets.js';
 import { validateLocalConfigs } from '../utils/configs.js';
+import { runValidators, reportResults } from '../utils/validation-helpers.js';
+import * as brandJsonValidator from '../validators/brand-json-validator.js';
+
+const validators = [brandJsonValidator];
 
 export { bundleEntry, buildExternalAssets };
 
@@ -22,6 +26,15 @@ export async function build(options = {}) {
     clientPropertyId: fertConfig.clientPropertyId,
   });
 
+  const validationResults = await runValidators(validators, {
+    rootDir: fertConfig.rootDir,
+    options,
+  });
+  const validationExitCode = reportResults(validationResults, fertConfig.rootDir);
+  if (validationExitCode !== 0) {
+    throw new Error('Build aborted due to validation errors');
+  }
+
   if (!options.only) {
     await rimraf(path.resolve(fertConfig.workingDir, 'dist'));
     await buildTokens(fertConfig, options);

package/bin/commands/dev-server.js

@@ -6,9 +6,11 @@ import open from 'open';
 import chokidar from 'chokidar5';
 import { resolveConfig, findFertConfigDir } from '../utils/index.js';
 import { validateLocalConfigs } from '../utils/configs.js';
+import { runValidators, reportResults } from '../utils/validation-helpers.js';
 import { devServer } from '../../server/server.js';
 import { buildTokens, buildExternalAssets } from './build.js';
 import { BRAND_JSON_FILENAME, FERT_CONFIG_FILENAME, FERT_SERVICE_CONFIG_FILENAME } from '../../constants.js';
+import * as brandJsonValidator from '../validators/brand-json-validator.js';
 
 export async function createDevServer(options = {}) {
   let fertConfig = await resolveConfig(options);
@@ -43,6 +45,9 @@ export async function createDevServer(options = {}) {
 
   chokidar.watch(brandPath, { ignoreInitial: true }).on('all', async () => {
     await buildTokens(fertConfig);
+
+    const results = await runValidators([brandJsonValidator], { rootDir: fertConfig.rootDir, options });
+    reportResults(results, rootDir);
   });
 
   const configPath = path.resolve(fertConfigDir, FERT_CONFIG_FILENAME);

package/bin/commands/publish-tasks/asset-store-uploader.js

@@ -1,8 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import * as Hoek from '@hapi/hoek';
-import axios from 'axios';
-import FormData from 'form-data';
 import ora from 'ora';
 import chalk from 'chalk';
 import { log } from '../../utils/logging.js';
@@ -27,43 +25,52 @@ export class AssetStoreUploader {
     const label = absoluteUrl.pathname;
 
     log.debug('upload', { file, dest, absoluteUrl });
-
+    // `openAsBlob` returns a "File-backend" Blob, not in memory
+    // eslint-disable-next-line n/no-unsupported-features/node-builtins
+    const fileBackedBlob = await fs.openAsBlob(file);
     const form = new FormData();
-    form.append('data', fs.createReadStream(file));
+    form.append('data', fileBackedBlob, path.basename(file));
     form.append('invalidateCache', 'false'); // opt out as will invalidate whole path (*) at end
     form.append('modifiedById', ASSET_STORE_USER_GUID);
 
     const spinner = ora(`${chalk.yellow('Uploading')}: ${label}`).start();
 
-    return axios
-      .put(absoluteUrl.href, form, {
+    try {
+      const res = await fetch(absoluteUrl.href, {
+        method: 'put',
         headers: {
           apikey: this.apiKey,
-          ...form.getHeaders(),
         },
-      })
-      .then(() => {
-        spinner.succeed(`${label}`);
-      })
-      .catch((err) => {
-        spinner.fail(`Failed to upload '${label}':`, err.message);
-
-        throw err;
+        body: form,
       });
+      if (!res.ok) {
+        const resText = await res.text();
+        throw new Error(`${res.status} - ${resText}`);
+      }
+
+      spinner.succeed(`${label}`);
+    } catch (err) {
+      spinner.fail(`Failed to upload '${label}':`, err.message);
+
+      throw err;
+    }
   }
 
-  async uploadDir(dir, dest = false) {
+  async uploadDir(dir, dryRun = false) {
     Hoek.assert(dir, 'dir missing');
 
     const start = process.hrtime();
-    const files = this._getFilesFromDir(dir);
+    const files = await this._getFilesFromDir(dir);
 
     // Send files consecutively to avoid straining the api
     for (const file of files) {
       const relativeName = path.posix.relative(dir, file);
-      const remotePath = path.posix.dirname(dest || relativeName);
-
-      await this.upload(file, remotePath);
+      const remotePath = path.posix.dirname(relativeName);
+      if (!dryRun) {
+        await this.upload(file, remotePath);
+      } else {
+        log.info('(Dry run) Uploading', file, 'to => ', remotePath);
+      }
     }
 
     const end = process.hrtime(start);
@@ -94,10 +101,13 @@ export class AssetStoreUploader {
       payload.distributionId = distributionId;
     }
 
-    await axios.post(invalidateUrl.href, payload, {
+    await fetch(invalidateUrl.href, {
+      method: 'post',
       headers: {
         apikey: this.apiKey,
+        'Content-Type': 'application/json',
       },
+      body: JSON.stringify(payload),
     });
 
     log.info(
@@ -106,18 +116,13 @@ export class AssetStoreUploader {
       }:\n${JSON.stringify(paths)}\n`,
     );
   }
-  // Returns array of all files in provided directory (recursive)
-  _getFilesFromDir = (dir, files = []) => {
-    fs.readdirSync(dir).forEach((entry) => {
-      const name = path.join(dir, entry);
-
-      if (fs.statSync(name).isDirectory()) {
-        this._getFilesFromDir(name, files);
-      } else {
-        files.push(name);
-      }
-    });
-
-    return files;
-  };
+  /**
+   * Returns array of all files in provided directory (recursive), as absolute paths including filename.
+   */
+  async _getFilesFromDir(dir) {
+    // eslint-disable-next-line n/no-unsupported-features/node-builtins
+    const all = await Array.fromAsync(fs.promises.glob('**/*', { cwd: dir, withFileTypes: true })); // withFileTypes return dirent instead of strings
+    // only files, make sure output is array of absolute file path strings
+    return all.filter((dirent) => dirent.isFile()).map((dirent) => path.resolve(dirent.parentPath, dirent.name));
+  }
 }

package/bin/commands/publish.js

@@ -57,10 +57,10 @@ export async function publish(options) {
   const localDir = path.resolve(fertConfig.workingDir, UPLOAD_DIR);
   const apiKeyParamPath = Hoek.reachTemplate(templateCtx, AWS_PARAM_NAME);
 
-  const apiKey = await getAwsParam(apiKeyParamPath);
-
-  const assetsPath = await getAssetsPath(fertConfig, options.target);
-  const clientCloudFrontDists = await getCloudFrontDistributionsForDomain(assetsPath.hostname, options);
+  const [apiKey, assetsPath] = await Promise.all([
+    getAwsParam(apiKeyParamPath),
+    getAssetsPath(fertConfig, options.target),
+  ]);
 
   log.info(
     `\nPublishing ${chalk.cyan(localDir)} to ${chalk.green.bold(
@@ -76,18 +76,17 @@ export async function publish(options) {
       basePath: remoteBasePath,
     });
 
-    let uploadResult;
-    if (!options.dryRun) {
-      uploadResult = await assetStore.uploadDir(localDir);
-    }
+    const uploadResult = await assetStore.uploadDir(localDir, options.dryRun);
 
     log.success(`Publish complete in ${((uploadResult?.duration || 1) / 1000).toFixed(0)}s\n`);
 
     // invalidate cloudfront cache
-    await assetStore.invalidatePaths([assetStoreInvPath]);
-
-    for (let dist of clientCloudFrontDists) {
-      await assetStore.invalidatePaths([`${assetsPath.pathname}/*`], dist.id);
+    if (!options.dryRun) {
+      await assetStore.invalidatePaths([assetStoreInvPath]);
+      const clientCloudFrontDists = await getCloudFrontDistributionsForDomain(assetsPath.hostname, options);
+      for (let dist of clientCloudFrontDists) {
+        await assetStore.invalidatePaths([`${assetsPath.pathname}/*`], dist.id);
+      }
     }
 
     log.info(`\nNote cloudfront invalidations may take upto ${chalk.yellow('30 seconds')} to complete.\n`);

package/bin/commands/validate.js

@@ -0,0 +1,27 @@
+import { findFertConfigDir } from '../utils/index.js';
+import { runValidators, reportResults } from '../utils/validation-helpers.js';
+import { log } from '../utils/logging.js';
+
+// Register all validators here
+import * as brandJsonValidator from '../validators/brand-json-validator.js';
+
+const validators = [brandJsonValidator];
+
+export async function validateCommand(options) {
+  log.info('Running validations…\n');
+
+  const rootDir = await findFertConfigDir();
+
+  const context = {
+    rootDir,
+    options,
+  };
+
+  const results = await runValidators(validators, context);
+  const exitCode = reportResults(results, rootDir);
+
+  if (exitCode !== 0) {
+    // eslint-disable-next-line n/no-process-exit
+    process.exit(exitCode);
+  }
+}

package/bin/utils/validation-helpers.js

@@ -0,0 +1,87 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import { log } from './logging.js';
+
+export const Severity = Object.freeze({
+  ERROR: 'ERROR',
+  WARNING: 'WARNING',
+});
+
+/**
+ * Creates a validation result entry.
+ */
+export function createResult(severity, message, { filePath, detail } = {}) {
+  return { severity, message, filePath, detail };
+}
+
+/**
+ * Runs an array of validator functions and collects all results.
+ * Each validator receives `context` and must return an array of result objects.
+ */
+export async function runValidators(validators, context) {
+  const results = [];
+
+  for (const validator of validators) {
+    const validatorResults = await validator.validate(context);
+    results.push(...validatorResults);
+  }
+
+  return results;
+}
+
+/**
+ * Prints validation results — errors first, then warnings grouped by file.
+ * Paths are shown relative to rootDir.
+ * Returns 1 if any ERROR results exist, 0 otherwise.
+ */
+export function reportResults(results, rootDir = process.cwd()) {
+  const errors = results.filter((r) => r.severity === Severity.ERROR);
+  const warnings = results.filter((r) => r.severity === Severity.WARNING);
+
+  if (errors.length) {
+    console.log(chalk.red.bold(`\n✖  ${errors.length} error${errors.length === 1 ? '' : 's'}\n`));
+    printGrouped(groupByFile(errors), rootDir, Severity.ERROR);
+  }
+
+  if (warnings.length) {
+    console.log(chalk.yellow.bold(`\n⚠  ${warnings.length} warning${warnings.length === 1 ? '' : 's'}\n`));
+    printGrouped(groupByFile(warnings), rootDir, Severity.WARNING);
+  }
+
+  if (!errors.length && !warnings.length) {
+    log.success('All validations passed');
+  }
+
+  console.log('');
+
+  return errors.length > 0 ? 1 : 0;
+}
+
+function groupByFile(results) {
+  const groups = new Map();
+  for (const result of results) {
+    const key = result.filePath ?? null;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(result);
+  }
+  return groups;
+}
+
+function printGrouped(groups, rootDir, severity) {
+  const color = severity === Severity.ERROR ? chalk.red : chalk.yellow;
+  const symbol = severity === Severity.ERROR ? '✖' : '⚠';
+
+  for (const [filePath, items] of groups) {
+    if (filePath) {
+      console.log(chalk.dim(`  ${path.relative(rootDir, filePath)}`));
+    }
+    for (const item of items) {
+      const indent = filePath ? '    ' : '  ';
+      console.log(color.bold(symbol), `${indent}${item.message}`);
+      if (item.detail) {
+        console.log(chalk.dim(`  ${indent}${item.detail}`));
+      }
+    }
+    console.log('');
+  }
+}

package/bin/validators/brand-json-validator.js

@@ -0,0 +1,160 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { createStyleDictionary } from '@madgex/design-system/style-dictionary';
+// eslint-disable-next-line n/no-extraneous-import
+import { resolveReferences } from 'style-dictionary/utils';
+import { loadServiceConfigFiles } from '../utils/index.js';
+import { Severity, createResult } from '../utils/validation-helpers.js';
+import { BRAND_JSON_FILENAME } from '../../constants.js';
+
+export const name = 'brand-json';
+export const description = 'Validates brand.json overrides against the MDS base token schema';
+
+/**
+ * Recursively extracts all dot-separated token paths from a token object.
+ * Stops at `$value` leaves and skips `$`-prefixed metadata keys.
+ */
+export function extractTokenPaths(obj, prefix = '') {
+  const paths = new Set();
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+
+    const currentPath = prefix ? `${prefix}.${key}` : key;
+
+    if (value && typeof value === 'object' && !('$value' in value)) {
+      const childPaths = extractTokenPaths(value, currentPath);
+      if (childPaths.size > 0) {
+        for (const childPath of childPaths) {
+          paths.add(childPath);
+        }
+      } else {
+        // Empty group — emit the path itself so it can be validated against the schema
+        paths.add(currentPath);
+      }
+    } else {
+      paths.add(currentPath);
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Recursively resolves a token `$value` through any `{references}` to a final scalar.
+ */
+export function resolveToFinalValue(rawValue, tokens) {
+  if (typeof rawValue !== 'string' || !rawValue.includes('{')) return rawValue;
+  const resolved = resolveReferences(rawValue, tokens, { usesDtcg: true});
+  if (resolved) {
+    return resolveToFinalValue(resolved, tokens);
+  }
+  return resolved;
+}
+
+/**
+ * Walks a nested object by dot-separated path and returns the `$value` at that leaf.
+ */
+export function getValueAtPath(obj, dotPath) {
+  let current = obj;
+  for (const part of dotPath.split('.')) {
+    if (!current || typeof current !== 'object') return undefined;
+    current = current[part];
+  }
+  return current?.$value;
+}
+
+/**
+ * Loads all MDS base tokens via StyleDictionary and returns the set of valid
+ * token paths, their resolved values, and the tokens tree for reference resolution.
+ */
+async function loadBaseSchema() {
+  const { styleDictionary, cleanTempFiles } = await createStyleDictionary();
+  const basePaths = new Set();
+  const baseResolvedValues = new Map();
+
+  for (const token of styleDictionary.allTokens) {
+    const tokenPath = token.key.slice(1, -1);
+    basePaths.add(tokenPath);
+    baseResolvedValues.set(tokenPath, resolveToFinalValue(token.$value, styleDictionary.tokens));
+  }
+
+  const baseTokens = styleDictionary.tokens;
+  await cleanTempFiles();
+  return { basePaths, baseResolvedValues, baseTokens };
+}
+
+export async function validate() {
+  const results = [];
+  const { basePaths, baseResolvedValues, baseTokens } = await loadBaseSchema();
+
+  let serviceConfigs;
+  try {
+    serviceConfigs = await loadServiceConfigFiles();
+  } catch {
+    results.push(
+      createResult(Severity.WARNING, 'Could not discover services — skipping brand.json validation', {
+        detail: 'Ensure you are running from a branding repo with a fert.config.js',
+      }),
+    );
+    return results;
+  }
+
+  for (const { dir } of serviceConfigs) {
+    const brandJsonPath = path.join(dir, BRAND_JSON_FILENAME);
+
+    if (!fs.existsSync(brandJsonPath)) {
+      results.push(
+        createResult(Severity.WARNING, `Missing ${BRAND_JSON_FILENAME}`, {
+          filePath: brandJsonPath,
+          detail: 'Each service should have a brand.json for token overrides',
+        }),
+      );
+      continue;
+    }
+
+    let brandData;
+    try {
+      brandData = JSON.parse(fs.readFileSync(brandJsonPath, 'utf-8'));
+    } catch (err) {
+      results.push(
+        createResult(Severity.ERROR, `Invalid JSON in ${BRAND_JSON_FILENAME}`, {
+          filePath: brandJsonPath,
+          detail: err.message,
+        }),
+      );
+      continue;
+    }
+
+    const overridePaths = extractTokenPaths(brandData);
+
+    for (const overridePath of overridePaths) {
+      if (!basePaths.has(overridePath)) {
+        results.push(
+          createResult(Severity.WARNING, `Unknown token path: "${overridePath}"`, {
+            filePath: brandJsonPath,
+            detail: 'This path does not exist in the MDS base schema and will have no effect',
+          }),
+        );
+        continue;
+      }
+
+      const rawOverrideValue = getValueAtPath(brandData, overridePath);
+      if (rawOverrideValue === undefined) continue;
+
+      const resolvedOverride = resolveToFinalValue(rawOverrideValue, baseTokens);
+      const resolvedBase = baseResolvedValues.get(overridePath);
+
+      if (resolvedOverride === resolvedBase) {
+        results.push(
+          createResult(Severity.WARNING, `Redundant override: "${overridePath}"`, {
+            filePath: brandJsonPath,
+            detail: `Value "${String(rawOverrideValue)}" resolves to the same value as the MDS base ("${String(resolvedBase)}")`,
+          }),
+        );
+      }
+    }
+  }
+
+  return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madgex/fert",
-  "version": "7.0.13",
+  "version": "7.1.0",
   "description": "Tool to help build the V6 branding",
   "bin": {
     "fert": "./bin/cli.js"
@@ -24,47 +24,45 @@
   "author": "Madgex",
   "license": "UNLICENSED",
   "dependencies": {
-    "@aws-sdk/client-cloudfront": "3.982.0",
-    "@aws-sdk/client-ssm": "3.982.0",
-    "@hapi/hapi": "21.4.4",
+    "@aws-sdk/client-cloudfront": "3.1017.0",
+    "@aws-sdk/client-ssm": "3.1017.0",
+    "@hapi/hapi": "21.4.7",
     "@hapi/hoek": "11.0.7",
     "@hapi/inert": "7.1.0",
     "@hapi/vision": "7.0.3",
     "@hapipal/toys": "4.0.0",
-    "@madgex/config-api-sdk": "1.13.1",
-    "@madgex/design-system": "13.2.1",
+    "@madgex/config-api-sdk": "1.16.0",
+    "@madgex/design-system": "13.5.1",
     "@private/header-footer-podlet-server": "github:wiley/madgex-header-footer-podlet",
-    "axios": "1.13.2",
     "cac": "6.7.14",
     "chalk": "5.6.2",
     "chokidar5": "npm:chokidar@5.0.0",
     "debug": "4.4.3",
     "dedent": "1.7.1",
     "find-up-simple": "1.0.1",
-    "flat-cache": "6.1.20",
-    "form-data": "4.0.5",
-    "joi": "18.0.2",
+    "flat-cache": "6.1.21",
+    "joi": "18.1.1",
     "nunjucks": "3.2.4",
     "open": "11.0.0",
     "ora": "5.4.1",
     "prompts": "2.4.2",
     "rimraf": "6.1.2",
-    "sass": "1.97.3",
-    "simple-git": "3.30.0",
+    "sass": "1.98.0",
+    "simple-git": "3.33.0",
     "simple-update-notifier": "2.0.0",
     "uuid-validate": "0.0.3",
     "vite": "7.3.1",
     "vite-plugin-static-copy": "3.2.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "20.4.1",
-    "@commitlint/config-conventional": "20.4.1",
-    "@madgex/eslint-config-madgex": "2.3.0",
-    "@madgex/prettier-config-madgex": "2.0.0",
-    "eslint": "9.39.2",
+    "@commitlint/cli": "20.5.0",
+    "@commitlint/config-conventional": "20.5.0",
+    "@madgex/eslint-config-madgex": "3.0.0",
+    "@madgex/prettier-config-madgex": "2.0.1",
+    "eslint": "10.1.0",
     "husky": "9.1.7",
-    "lint-staged": "16.2.7",
-    "msw": "^2.12.8",
+    "lint-staged": "16.4.0",
+    "msw": "^2.12.14",
     "prettier": "3.8.1",
     "semantic-release": "25.0.3"
   },

package/shared/Dockerfile.brandingRepoPublish

@@ -1,4 +1,4 @@
-FROM node:22-alpine
+FROM node:24-alpine
 
 ENV HOME=/app/