@madgex/fert 1.3.0

package/.eslintignore

@@ -0,0 +1,8 @@
+dist
+temp
+**/dist
+*.json
+**/*.json
+!.eslintrc.js
+node_modules
+repo-templates

package/.eslintrc.js

@@ -0,0 +1,15 @@
+module.exports = {
+  env: {
+    node: true,
+    es6: true,
+  },
+  plugins: ['prettier'],
+  extends: ['eslint:recommended', 'plugin:prettier/recommended'],
+  parserOptions: {
+    requireConfigFile: false,
+    ecmaVersion: 'latest',
+  },
+  rules: {
+    'prettier/prettier': 'error',
+  },
+};

package/.github/workflows/commits.yml

@@ -0,0 +1,14 @@
+name: Conventional Commit Checker
+
+on:
+  pull_request:
+    branches: [master]
+    types: [opened, edited, synchronize]
+
+jobs:
+  check-for-cc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: check-for-cc
+        id: check-for-cc
+        uses: agenthunt/conventional-commit-checker-action@v1.0.0

package/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+on:
+  workflow_run:
+    workflows: ['tests']
+    branches: [master]
+    types:
+      - completed
+  push:
+    branches:
+      - master
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v1
+      - name: Setup Node.js
+        uses: actions/setup-node@v2
+        with:
+          cache: npm
+          node-version: 14
+      - name: Install dependencies
+        run: npm ci
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.husky/commit-msg

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname "$0")/_/husky.sh"
+
+npx --no -- commitlint --edit "${1}"

package/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run lint-staged

package/.prettierignore

@@ -0,0 +1,2 @@
+node_modules
+.vscode

package/.prettierrc.js

@@ -0,0 +1,8 @@
+module.exports = {
+  semi: true,
+  tabWidth: 2,
+  singleQuote: true,
+  printWidth: 80,
+  trailingComma: 'es5',
+  endOfLine: 'auto'
+};

package/README.md

@@ -0,0 +1,232 @@
+# FERT - proposed approach/readme
+
+Madgex brand tooling for anyone.
+
+> **F**ront-**e**nd **R**ollout **T**ool – Tooling to help scaffold, develop and deploy Madgex client branding
+
+# Why FERT
+
+The Madgex job board brands all have a custom headers, footers and their associated JavaScript & CSS. In the past we've struggled with finding an easy local development & roll-out setup. Fert is an attempt to address that.
+
+## Requirements
+
+* To be a one-stop shop for:
+  
+  * Scaffolding a new project
+  
+  * A dev server to allow easy brand development
+  
+  * Builds distributable assets
+
+* Must be able to install via [NPM](https://www.npmjs.com/) or internal registry
+
+* Must work cross-platform (Windows and *nix)
+
+## A human-first design
+
+To empower & serve its users, we should design this CLI with the users in mind. Ensuring it feels as familiar as possible, following established patterns and is has the following:
+
+* Easy to learn commands from a inbuilt help screen
+
+* Easy to read/understand error messages
+
+* Empathy in the error messages – can some helpful context be provided with the error to assist the user remedy the issue?
+
+# Under the hood
+
+* [Hapi](https://hapi.dev/) is used for the local dev server
+
+* [Vite](https://vitejs.dev/) for HMR, serves the JS entry & bundles assets for production
+
+* [Style Dictionary](https://amzn.github.io/style-dictionary/#/README) is used to transform Design Tokens into various outputs, inc. JSON, CSS Custom Properties and SCSS variables. The output is built into `public/tokens/`
+
+* Chokidar is used to watch for changes in the `templates` and `public/tokens` directories and either refresh the browser page or build a new set of tokens respectively.
+
+
+
+# Configuration
+
+There are **three required files** in the root of the branding repo:
+
+`brand.json` [required] – a JSON file that supplies the base branding tokens. These values will be merged with the Design System tokens & a full set of branding tokens will be created.
+
+e.g.
+
+```json
+{
+  "color": {
+    "brand": {
+      "1": {
+        "base": { "value": "#005689" }
+      }
+    }
+  },
+  // more branding tokens applied here...
+}
+```
+
+`fert.config.js` [required] – a configuration file in the root of the branding repo specifying the following config to both the Fert dev server and the production asset build:
+
+| Option                      |                                                                                                                                            |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `clientPropertyId` <String> | The `clientPropertyId` associated with the branding repo (required)                                                                        |
+| `entry` <String>            | The JavaScript entry file. Any assets (CSS/SCSS/SVGs) included will be processed and be part of the output. Defaults to `['src/index.js']` |
+
+The `entry` will be used by Vite to create production bundles.
+
+e.g.
+
+```js
+module.exports = {
+  clientPropertyId: "ff6102ff-0f4b-43d1-a2c7-83b835b8dee5",
+  entry: "./src/index.js",
+};
+```
+
+`jenkinsfile` - A jenkins file containing the pipeline which will build and send the assets to S3. Every push to the repo will trigger a jenkins build automatically. Changes on **master** will trigger a build and send assets to the **production** bucket. Any other branches will send the assets to the jb.dev bucket.
+
+# CLI commands
+
+The CLI will support 3 main commands: dev server (default command), scaffolding a new project and building production assets.
+
+* [Dev server](#dev-server)
+
+* [Scaffold](#scaffold)
+
+* [Build](#build)
+
+* [Publish](#publish)
+
+## Dev server
+
+`fert`
+
+Start the Fert dev server in the current directory.
+
+**Usage**
+
+`fert [root]`
+
+**Outline of implementation**
+
+A fast, minimal development server that allows the developer to see the header/footer templates and branding (Design System tokens) specified in the local repo applied to a Design System-based HTML page.
+
+The server will be a hapi server, importing the header/footer micro front-end server(s) as dependencies, running all together to render the page.
+
+Changes to the local tokens will cause the DS tokens to be rebuilt.
+
+Changes to the local `fert.config.js` will be reflected in the dev servers environment.
+
+Changes to any local file will be reflected in the developers browser without having to manually refresh.
+
+## Scaffold
+
+`fert init`
+
+When faced with an empty branding repo, this will help the user get started with the boilerplate branding project template
+
+**Usage**
+
+`fert init [root]`
+
+**Options**
+
+| Option    |                                                                       |
+| --------- | --------------------------------------------------------------------- |
+| `--template <template>` | Specify the template you wish to use when scaffolding |
+| `--cpid <cpid>` | Specify the clientPropertyId to use in the new project |
+
+**Outline of implementation**
+
+The init command will clone a well-maintained boilerplate repo into the target directory. It may be good to use a tool like [`degit`](https://www.npmjs.com/package/degit) for faster cloning & not confusing git with nested, hidden `.git` directories.
+
+The `--force` option would destructively reset the branding repo to a common baseline, resetting the content.
+
+The source boilerplate repo: https://github.com/wiley/madgex-00000000-0000-0000-0000-000000000000
+The `init` command is intended for an automation tool which will create a new branding repo, run this command and commit the new files.
+
+## Build
+
+`fert build`
+
+Process CSS/JS assets specified in `fert.config.js` and copy static assets, including templates for distribution.
+
+**Usage**
+
+`fert build [root] --only [tokens | assets]`
+
+| Option            |                                                                                                            |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| `--only [task]`   | Specify a single part of the build process to run (`string` \| `tokens` \| `assets`)                       |
+| `--config <path>` | Override the internal default Vite config & provide a custom `vite.config.js` file to use to build assets. |
+
+**Outline of implementation**
+
+Using Vite, the `entry` in the `fert.config.js` file is processed and bundled to the `dist` directory.
+
+Templates are copied to `dist`.
+
+Public assets are copied to `dist`.
+
+The resulting `dist` directory is uploaded wholesale to the `assets-store-api` for use in production.
+
+Templates & CSS may be processed using the [CSS Modules](https://github.com/css-modules/css-modules) system to encapsulate header/footer styles & prevent bleed into the rest of the page.
+
+## Publish
+
+`fert publish`
+
+**Usage**
+
+`fert publish [root] --target [target]`
+
+| Option     |                                                                              |
+| ---------- | ---------------------------------------------------------------------------- |
+| `--target` | Where to publish the `dist` directory assets.<br/>`dev` \| `prod` (`string`) |
+
+Send all files and directories created in the `dist` directory to either development or production versions of the Asset Store API. Files uploaded to the Asset Store API are available via a CloudFront-based CDN.
+
+**Outline of implementation**
+
+Index all the files and their paths in the `dist` directory, and using a recursive function upload each item (destructively) to the Asset Store API.
+
+The Asset Store API uses a multi-part form upload to PUT files in the client directory. Upload paths are respected, directories are created on the fly.
+
+
+
+# CI/CD
+
+It's intended that the branding repos have their own build/deploy pipeline. Each change that's merged to `master` will trigger a build (`npm run build` as a common entry point) and the resulting output directory (`dist`) is pushed up to the `asset-store-api` for use in production.
+
+## `npm scripts`
+
+Here are the default npm scripts in a Fert-scaffolded project.
+
+```json
+{
+  "scripts": {
+    "dev": "fert", // start dev server
+    "build": "fert build" // build assets for production
+  }
+}
+```
+
+Its expected that a Jenkins pipeline will run `fert publish` to send all built assets to the Asset Store API.
+
+
+
+# @madgex/boilerplate-utils
+
+A collection of utilities for use in branding projects, e.g.
+
+* Hamburger nav HTML/CSS/JS
+
+* common SCSS
+
+* SVGs
+
+* templates/macros
+
+If needed, this package can be `npm install`ed in the branding project & consumed from the JS/SCSS.
+
+Templates/macros will have to be copied into the branding repo as they won't be visible/available to the server rendering the template.

package/bin/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const chalk = require('chalk');
+const cli = require('cac')('fert');
+const { VERSION } = require('../constants');
+const { printBanner } = require('./utils/index.js');
+
+const run = () => {
+  printBanner();
+
+  cli
+    .command(
+      '[root]',
+      'Start layout server. Can supply a branding directory if running FERT standalone'
+    )
+    .alias('dev')
+    .option('--open', 'Automatically open the dev server in your browser')
+    .option('--host [host]', '[string] specify hostname')
+    .option('--port <port>', '[number] specify port')
+    .action((...args) => require('./commands/dev-server')(...args));
+
+  cli
+    .command(
+      'build [root]',
+      'Build project. Can supply a branding directory if running FERT standalone'
+    )
+    .option('--only <task>', `Only run part of the build [ 'assets', 'tokens']`)
+    .option('--config [dir]', 'Use custom rollup config file')
+    .action((...args) => require('./commands/build.js')(...args));
+
+  cli
+    .command('publish [root]', 'Publish project to S3')
+    .option('--target <env>', 'Environment to publish to, "dev" or "prod"')
+    .action((...args) => require('./commands/publish')(...args));
+
+  cli
+    .command('init [root]', 'Create a new branding project')
+    .option('--template <template>', 'Template to use when scaffolding project')
+    .option(
+      '--cpid <cpid>',
+      'Specify the clientPropertyId to use in the new project'
+    )
+    .action((...args) => require('./commands/init')(...args));
+
+  cli.help();
+  cli.version(VERSION);
+  cli.parse();
+
+  // checks for available update
+  const pkg = JSON.parse(fs.readFileSync(__dirname + '/../package.json'));
+
+  if (pkg.version.indexOf('0.0.0') !== 0) {
+    require('simple-update-notifier')({ pkg });
+  }
+};
+
+try {
+  run();
+} catch (error) {
+  if (error.name === 'CACError') {
+    console.error(chalk`\n{red ${error.message}}`);
+  } else {
+    console.error(error);
+  }
+
+  process.exit(1);
+}

package/bin/commands/build-tasks/build-external-assets.js

@@ -0,0 +1,16 @@
+const Path = require('path');
+const fs = require('fs/promises');
+const { log } = require('../../utils');
+
+module.exports = async function buildExternalAssets(fertConfig) {
+  const { externalAssets, workingDir } = fertConfig;
+  const destination = Path.join(workingDir, `/dist/external-assets.json`);
+
+  try {
+    await fs.writeFile(destination, JSON.stringify(externalAssets, null, 2));
+    log.success('External assets file created');
+  } catch (err) {
+    log.error(err);
+    throw err;
+  }
+};

package/bin/commands/build-tasks/build-tokens.js

@@ -0,0 +1,119 @@
+const StyleDictionaryPackage = require('style-dictionary');
+const Path = require('path');
+const fs = require('fs/promises');
+const {
+  registerTransforms,
+} = require('@madgex/design-system/tasks/registerTransforms');
+const colorTransforms = require('@madgex/design-system/tasks/colorTransforms');
+const { ensureTrailingSlash, log, exists } = require('../../utils');
+const { TMP_DIR } = require('../../../constants');
+
+const dsTokensPath = Path.dirname(
+  require.resolve('@madgex/design-system/src/tokens/_config.js')
+);
+
+// eslint-disable-next-line no-unused-vars
+const createTempBrandFile = async (dir = './') => {
+  // Generate unique name to bust style dict cache
+  const timestamp = Date.now();
+  const tmpBrandFile = Path.join(TMP_DIR, `/fert/brand-${timestamp}.json`);
+  const dirPath = Path.dirname(tmpBrandFile);
+
+  if (!(await exists(dirPath))) {
+    await fs.mkdir(dirPath, { recursive: true });
+  }
+
+  return tmpBrandFile;
+};
+
+// Style Dictionary is noisy and annoying, this suppresses its output
+async function runSilently(fn) {
+  const originalLog = console.log;
+  console.log = () => {};
+  await fn();
+  console.log = originalLog;
+}
+
+module.exports = async function buildCssFromTokens(srcTokensPath, buildPath) {
+  srcTokensPath = ensureTrailingSlash(Path.resolve(srcTokensPath));
+  buildPath = ensureTrailingSlash(Path.resolve(buildPath));
+
+  const brandFile = Path.join(srcTokensPath, 'brand.json');
+
+  if (!(await exists(buildPath))) {
+    await fs.mkdir(buildPath, { recursive: true });
+  }
+
+  // Fetch the file so we can transform the colours in style dictionary
+  const brandObj = JSON.parse(
+    await fs.readFile(brandFile, { encoding: 'utf8' })
+  );
+  const tmpBrandFile = await createTempBrandFile(srcTokensPath);
+
+  await fs.writeFile(
+    Path.join(tmpBrandFile),
+    JSON.stringify(colorTransforms(brandObj))
+  );
+
+  // TODO - Investigate whether we can retrieve from DS instead of redefining
+  // e.g. const { registerTransforms } = require('@madgex/design-system/tasks/registerTransforms');
+  const transforms = [
+    'attribute/cti',
+    'name/cti/kebab',
+    'color/css',
+    'css/rawData',
+  ];
+  const prefix = 'mds';
+
+  // TODO - Investigate whether we can retrieve from DS instead of redefining
+  const styleDictionaryConfig = {
+    include: [Path.join(dsTokensPath, '*.json')],
+    source: [tmpBrandFile],
+    platforms: {
+      'scss-variables': {
+        transforms,
+        prefix,
+        buildPath: Path.join(buildPath, 'scss/'),
+        files: [
+          {
+            destination: 'index.scss',
+            format: 'scss/map-deep',
+          },
+        ],
+      },
+      'css-variables': {
+        transforms,
+        prefix,
+        buildPath: Path.join(buildPath, 'css-vars/'),
+        files: [
+          {
+            destination: `variables.css`,
+            format: 'css/variables',
+          },
+        ],
+      },
+      'json-variables': {
+        transforms,
+        prefix,
+        buildPath: Path.join(buildPath, 'json/'),
+        files: [
+          {
+            destination: `variables.json`,
+            format: 'json/nested',
+          },
+        ],
+      },
+    },
+  };
+
+  // Use StyleDictionary to build a tokens SCSS file
+  const StyleDictionary = StyleDictionaryPackage.extend(styleDictionaryConfig);
+
+  await registerTransforms(StyleDictionary);
+  await runSilently(StyleDictionary.buildAllPlatforms.bind(StyleDictionary));
+
+  // clean-up temp SD file
+  await fs.unlink(tmpBrandFile);
+
+  log.success('Token build complete.');
+};

package/bin/commands/build-tasks/bundle-ds-css.js

@@ -0,0 +1,74 @@
+const path = require('node:path');
+const fsp = require('node:fs/promises');
+const _ = require('lodash');
+const vite = require('vite');
+const chalk = require('chalk');
+
+// TODO: delete me when DS is driven by CSS Custom Ppoperties
+
+module.exports = async (viteConfig) => {
+  const dsBundledViteConfig = { ...viteConfig };
+
+  // create ds-bundled vite build in-memory
+  _.merge(dsBundledViteConfig, {
+    logLevel: 'silent',
+    build: {
+      write: false,
+      rollupOptions: {
+        output: {
+          assetFileNames: 'assets/[name]-ds-[hash].[ext]',
+        },
+      },
+    },
+    css: {
+      preprocessorOptions: {
+        scss: {
+          additionalData: `
+          @import "../../public/tokens/scss/index.scss";
+          @import "@madgex/design-system/src/scss/import.scss";
+          `, // all scss processed files gets this injected at the top
+        },
+      },
+    },
+  });
+
+  const dsBuild = await vite.build(dsBundledViteConfig);
+  const { output: files } = Array.isArray(dsBuild) ? dsBuild[0] : dsBuild;
+
+  // write just the CSS file to disk
+  for (const file of files) {
+    if (file.name !== 'style.css') {
+      continue;
+    }
+    const cssFileContent = file.source;
+    await fsp.writeFile(
+      path.resolve('dist', file.fileName),
+      cssFileContent,
+      'utf8'
+    );
+
+    // read the manifest.json
+    const manifestPath = path.resolve('dist', 'manifest.json');
+    const manifestStr = await fsp.readFile(manifestPath);
+    const manifest = JSON.parse(manifestStr);
+
+    // add entry to manifest.json
+    const dsEntryName = file.name
+      .split('.')
+      .map((part, i) => (i === 0 ? `${part}-ds` : part))
+      .join('.');
+    manifest[dsEntryName] = { ...manifest[file.name] };
+    manifest[dsEntryName].file = file.fileName;
+
+    // write new manifest
+    await fsp.writeFile(
+      manifestPath,
+      JSON.stringify(manifest, null, 2),
+      'utf8'
+    );
+
+    console.log(
+      `\nUpdated build & manifest with DS-bundled CSS file: ${chalk.magenta(file.fileName)}\n` // prettier-ignore
+    );
+  }
+};

package/bin/commands/build-tasks/bundle-entry.js

@@ -0,0 +1,43 @@
+const path = require('path');
+const _ = require('lodash');
+const vite = require('vite');
+const updateBuildWithBundledDsCSS = require('./bundle-ds-css');
+const buildExternalAssets = require('./build-external-assets');
+const { log } = require('../../utils');
+
+module.exports = async (fertConfig, options = {}) => {
+  let dynamicOptions = {};
+  let viteConfig = {};
+
+  if (options.config) {
+    viteConfig = require(path.resolve(fertConfig.workingDir, options.config));
+  } else {
+    viteConfig = require(path.resolve(__dirname, '../../../vite.config.js'));
+  }
+
+  dynamicOptions = {
+    root: path.resolve(fertConfig.workingDir),
+    base: '/_/jobseekers-frontend/',
+    build: {
+      cssCodeSplit: false, // important: to get a single, style.css file output
+      outDir: path.resolve(fertConfig.workingDir, 'dist'),
+      rollupOptions: {
+        input: path.resolve(
+          fertConfig.workingDir,
+          fertConfig.entry || './src/index.js'
+        ),
+      },
+    },
+  };
+
+  _.merge(viteConfig, dynamicOptions);
+
+  await vite.build(viteConfig);
+
+  // second build - this time with the DS included in the CSS bundle
+  await updateBuildWithBundledDsCSS(viteConfig);
+
+  await buildExternalAssets(fertConfig);
+
+  log.success('Assets built.');
+};