@massimo-cassandro/minimo 1.8.4 → 1.9.1

package/README.md

@@ -20,8 +20,15 @@ For a complete install of all required webpack modules, use the install script a
 ```bash
 zsh ./node_modules/@massimo-cassandro/minimo/webpack-setup/starter-install.sh
 ```
+---
 
+## Dev Tools
 
----
+The [`dev-tools`](./dev-tools/README.md) directory contains a set of standalone Node.js CLI utilities for managing a web project — updating dependencies, bumping the version and changelog, and generating/optimizing SVG icons and favicons. They are published as part of the `minimo` package and exposed via the `bin` entries in `package.json` (`update-version`, `upd@m`, `svgIconsTools`, `create-favicons`); see the [Dev Tools README](./dev-tools/README.md) for the full list and usage.
+
+
+## Docs & Demo
+
+[Docs](docs)
 
-[Docs](docs) | [Demo](demo-build)
+[Demo](demo-build)

package/dev-tools/README.md

@@ -0,0 +1,31 @@
+# Dev tools
+
+A collection of standalone Node.js CLI utilities to help manage a web project's day-to-day chores (dependency updates, versioning/changelog, icon and favicon generation). Each tool lives in its own subfolder, works independently of the others and of the `minimo` package itself, and is documented in its own README — this page only gives a quick overview.
+
+* [update-version](./update-version/README.md) — bumps the version in `package.json` and appends an entry to `changelog.md`
+* [Svg Icons Tools](./svg-icons-tools/README.md) — optimizes SVG icons and combines/converts them into symbols, JSX, or SCSS variables
+* [Create favicons](./create-favicons/README.md) — generates the full favicon set (SVG, PNG, ICO, webmanifest, HTML snippet) from a source image
+* [upd@m](./upd@m/README.md) — updates all `@massimo-cassandro/*` packages installed in `node_modules`
+
+
+## Usage of SVG adn favicons tools
+
+```bash
+## SVG Icons Tools
+npx svgIconsTools --config ./path/to/svg-icons-tools.config.mjs
+
+# create favicons
+npx create-favicons init
+npx create-favicons [--dir=./path/to/dir]
+```
+
+## Adding frequently used tools in the script section of the `package.json` file:
+
+```json
+{
+  "scripts": {
+    "update-version": "npx update-version # optional: --config=./dev-utilities.config.mjs",
+    "upd@m": "npx upd@m"
+  }
+}
+```

package/dev-tools/create-favicons/README.md

@@ -0,0 +1,101 @@
+# Create favicons
+
+Create favicon files as described in [How to Favicon in 2024](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs).
+
+The files to be processed must be in SVG format, while the generated files are in SVG (favicon), PNG (apple-touch-icon and other Android files), and ICO (another favicon for compatibility with older browsers). The `manifest.webmanifest` files are also generated, along with an optional HTML snippet with `link` tags for inserting the generated elements.
+
+Images are generated with [Sharp](https://sharp.pixelplumbing.com/), [SVGO](https://github.com/svg/svgo), and [sharp-ico](https://github.com/ssnangua/sharp-ico).
+
+## Installation
+
+```bash
+npm i -D @massimo-cassandro/create-favicons
+```
+
+## Creating template config files (see below)
+
+```bash
+npx create-favicons init
+```
+
+## Usage
+
+```bash
+npx create-favicons [--dir=./path/to/dir]
+```
+
+The script normally runs in the current directory, but using the optional `--dir` parameter,
+you can specify an alternative directory (path relative to the execution directory).
+
+The script first searches the working directory for the `create-favicons-cfg.mjs` file, which contains an object
+with all the necessary parameters (see below).
+
+If it's missing, it searches for the `favicon-src.svg` file to use as the source for all images, assuming the default values ​​(see below) for all other parameters.
+
+Among others, you can specify the `small_src_img` parameter if you need to specify an image optimized for small dimensions (32px).
+
+The best format for source files is SVG, or alternatively PNG.
+
+If both files are missing, an error is returned.
+
+The default parameters are listed in detail in the file `src/create-favicons/src/default-params.mjs`,
+and can be customized in the configuration file, which must have this form:
+
+```javascript
+// file create-favicons-cfg.mjs
+const params = [{ /* ... */ }];
+
+export default params;
+```
+
+`params` can be an object or an array. In the latter case, each element of the array corresponds to a different set of favicons.
+
+To create a sample cfg file **in the current directory** (with all default values ​​and their descriptions),
+use the command:
+
+```bash
+npx create-favicons init
+```
+
+## Remote Use
+
+The commands can also be run without first installing the package:
+
+```
+npx --package=@massimo-cassandro/dev-utilities create-favicons init
+npx --package=@massimo-cassandro/dev-utilities create-favicons [--dir=...]
+```
+
+## Execution
+
+The script produces the various png and svg images, the `manifest.webmanifest` file, and an HTML snippet (or in the language specified in the `snippet_language` parameter).
+All images are optimized with [SVGO](https://github.com/svg/svgo) and [imagemin](https://github.com/imagemin/imagemin).
+
+All files are saved in the directory specified in `output_dir` (default: current directory).
+
+Optionally, the snippet file can be saved in a different directory (`snippet_path`) or you can choose not to create it,
+by setting the `snippet_name` value to `null`.
+
+In the configuration file, you can also set the `webmanifest_extra` parameter, which allows you to add additional entries to the *manifest* file.
+For more info: <https://developer.mozilla.org/en-US/docs/Web/Manifest>
+
+Files generated:
+
+```html
+<link rel="icon" href="/favicon.ico" sizes="any"> <!-- 32×32 + 16x16 -->
+<link rel="icon" href="/icon.svg" type="image/svg+xml">
+<link rel="apple-touch-icon" href="/apple-touch-icon.png"> <!-- 180×180 -->
+<link rel="manifest" href="/manifest.webmanifest">
+```
+
+```javascript
+// manifest.webmanifest
+{ 
+  "icons": [ 
+    { "src": "/icon-192.png", "type": "image/png", "sizes": "192x192" },
+    { "src": "/icon-512.png", "type": "image/png", "sizes": "512x512" }
+  ]
+}
+```
+
+See also demo files

package/dev-tools/create-favicons/index.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+/* eslint-disable no-console */
+/* eslint-env node */
+
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { log } from './src/print-frame.mjs';
+
+import { parseParams } from './src/parse-params.mjs';
+import { default_params } from './src/default-params.mjs';
+import { createFavicons } from './src/create-favicons.mjs';
+import { init } from './src/init.mjs';
+
+// nome del file di configurazione, se utilizzato
+const config_filename = 'create-favicons-cfg.mjs';
+
+try {
+
+  // init: creazione file cfg base
+  if(process.argv.indexOf('init') !== -1) {
+
+    init();
+
+  } else {
+
+    let work_dir;
+    const dir_param_idx = process.argv.findIndex(el => /^--dir/.test(el) );
+
+    if(dir_param_idx !== -1) {
+      [, work_dir] = process.argv[dir_param_idx].split('=');
+
+    } else {
+      work_dir = './';
+    }
+
+    work_dir = path.resolve(process.cwd(), work_dir) ;
+
+
+    if(fs.existsSync(path.resolve(work_dir, config_filename))) {
+
+      import(path.resolve(work_dir, config_filename))
+        .then((config_params) => {
+
+          const imported_params = [...(Array.isArray(config_params.default)? config_params.default : [config_params.default])];
+
+          imported_params.forEach(params_item => {
+            createFavicons(parseParams(params_item, work_dir));
+          });
+
+        });
+
+    } else if(default_params.src_img && fs.existsSync(path.resolve(work_dir, default_params.src_img))) {
+
+      createFavicons(parseParams(null, work_dir));
+
+    } else {
+
+      throw new Error( `'${config_filename}' e '${default_params.src_img}' non presenti`);
+    }
+
+  }
+
+
+
+} catch(err) {
+  log('bgRed', `\n ${err} \n`, 'error');
+}

package/dev-tools/create-favicons/src/create-favicons.mjs

@@ -0,0 +1,37 @@
+/* eslint-disable no-console */
+
+// import * as fs from 'fs';
+// import * as path from 'path';
+import { log } from './print-frame.mjs';
+
+import { createIco } from './create-ico.mjs';
+import { createPng } from './create-png.mjs';
+import { createSvg } from './create-svg.mjs';
+import { createWebmanifest } from './create-webmanifest.mjs';
+import { createSnippet } from './create-snippet.mjs';
+import { printResult } from './print-result.mjs';
+
+
+export async function createFavicons(params) {
+
+  try {
+
+    log('green', 'Creating favicons...');
+
+    await Promise.all([
+      await createSvg(params),
+      await createPng(params),
+      await createIco(params),
+      await createWebmanifest(params), // after create png
+      await createSnippet(params),
+    ])
+      .then(result => {
+        printResult(params);
+
+      })
+
+  } catch(err) {
+    log('bgRed', ` ${err} `, 'error');
+  }
+
+}

package/dev-tools/create-favicons/src/create-ico.OLD.mjs

@@ -0,0 +1,32 @@
+import * as fs from 'fs';
+import sharp from 'sharp';
+import toIco from 'to-ico';
+
+
+// https://github.com/kevva/to-ico
+// alternativa: https://github.com/steambap/png-to-ico
+
+// const ico_source = fs.readFileSync(`${output_dir}/apple-touch-icon.png`);
+
+export async function createIco(params) {
+
+  await sharp(params.small_src_img?? params.src_img)
+    // .png()
+    // .then(info => console.log(info))
+    .toBuffer()
+    .then(bufferData => {
+
+      toIco([bufferData], {
+        sizes: [16, 32],
+        resize: true
+      }).then( async result => {
+        await fs.promises.writeFile(`${params.output_dir}/favicon.ico`, result, {
+            encoding: "utf8",
+            flag: "w",
+            mode: 0o666
+        });
+      });
+
+    })
+    .catch(err => { throw new Error( err + ' (createIco)'); });
+}

package/dev-tools/create-favicons/src/create-ico.mjs

@@ -0,0 +1,18 @@
+import sharp from 'sharp';
+import ico from 'sharp-ico';
+
+// https://github.com/ssnangua/sharp-ico
+
+export async function createIco(params) {
+
+  await ico.sharpsToIco(
+    [sharp(params.small_src_img?? params.src_img)],
+    `${params.output_dir}/favicon.ico`,
+    {
+      sizes: [16, 32],
+      // sizes: "default", // equal to [256, 128, 64, 48, 32, 24, 16]
+      resizeOptions: {}, // sharp resize optinos
+    }
+  );
+
+}

package/dev-tools/create-favicons/src/create-png.mjs

@@ -0,0 +1,21 @@
+import sharp from 'sharp';
+
+export async function createPng(params) {
+
+  // https://sharp.pixelplumbing.com/api-constructor
+  // https://sharp.pixelplumbing.com/api-output#png
+  await Promise.all([
+    ['apple-touch-icon.png', 180],
+    ['icon-192.png', 192],
+    ['icon-512.png', 512]
+  ].map(file => {
+    sharp(params.src_img)
+      .resize({ width: file[1], fit: 'inside' })
+      .png(params.png_parameters)
+      .toFile(`${params.output_dir}/${file[0]}`)
+
+  }))
+    .catch(err => { throw new Error( err ); });
+
+
+}

package/dev-tools/create-favicons/src/create-snippet.mjs

@@ -0,0 +1,64 @@
+import * as fs from 'fs';
+
+export async function createSnippet(params) {
+
+
+  if(params.create_snippet) {
+
+    let snippet_content;
+
+    if (params.snippet_language === 'ejs') {
+
+      snippet_content = '<link rel="icon" href="<%= require(\'./favicon.ico\') %>" sizes="32x32"/>\n' +
+        '<link rel="icon" href="<%= require(\'./favicon.svg\') %>" type="image/svg+xml"/>\n' +
+        '<link rel="apple-touch-icon" href="<%= require(\'./apple-touch-icon.png\') %>"/>\n' +
+        '<link rel="manifest" href="./manifest.webmanifest"/>';
+
+        //'\n<!-- <link rel="manifest" href="<%= require(\'./manifest.webmanifest.ejs\')() %>"/> -->';
+
+    } else {
+
+      const cache_buster = params.add_cache_buster? `?_=${Date.now()}` : '',
+        create_href = nome_file => params.href_template.replace('%_file_name_%', nome_file)
+          .replace('%_cache_buster_%', cache_buster);
+
+
+      snippet_content = `<link rel="icon" href="${create_href('favicon.ico')}" sizes="32x32"/>\n` +
+        `<link rel="icon" href="${create_href('favicon.svg')}" type="image/svg+xml"/>\n` +
+        `<link rel="apple-touch-icon" href="${create_href('apple-touch-icon.png')}"/>\n` +
+        `<link rel="manifest" href="${create_href('manifest.webmanifest')}"/>`;
+
+      if (params.snippet_language === 'pug') {
+        snippet_content = snippet_content.replace(/<link (.*?)\/?>/g, 'link($1)');
+      }
+
+    }
+
+    snippet_content = params.snippet_template.replace('%_link_tags_%', snippet_content);
+
+    if (params.snippet_target_file) {
+
+      if (fs.existsSync(params.snippet_target_file)) {
+        const targetFileContent = fs.readFileSync(params.snippet_target_file, 'utf8'),
+          regexp = /<!-- ?favicon-snippet-start ?-->(.*?)<!-- ?favicon-snippet-end ?-->/mis;
+
+        fs.promises.writeFile(params.snippet_target_file,
+          targetFileContent.replace(regexp,
+            `<!-- favicon-snippet-start -->\n${snippet_content}\n<!-- favicon-snippet-end -->`
+          )
+        );
+
+      } else {
+        throw new Error( `Il file '${params.snippet_target_file}' non esiste` );
+      }
+
+    } else {
+
+      fs.promises.writeFile(
+        `${params.snippet_path}/${params.snippet_name}`,
+        snippet_content
+      );
+
+    }
+  }
+}

package/dev-tools/create-favicons/src/create-svg.mjs

@@ -0,0 +1,15 @@
+import { optimize } from 'svgo';
+import * as fs from 'fs/promises';
+
+export async function createSvg(params) {
+
+  // TODO add extra config ???
+  await fs.readFile(params.small_src_img?? params.src_img, { encoding: 'utf8' })
+    .then(svgString => {
+
+      const svg_result = optimize(svgString, { multipass: true});
+
+      fs.writeFile(`${params.output_dir}/favicon.svg`, svg_result.data);
+
+    });
+}

package/dev-tools/create-favicons/src/create-webmanifest.mjs

@@ -0,0 +1,64 @@
+// web manifest
+
+// import * as fs from 'fs/promises';
+import * as fs from 'fs';
+import { createHash } from 'node:crypto'
+
+
+async function getHash(path) {
+
+  const fileHash = await new Promise((resolve, reject) => {
+    const hash = createHash('sha256');
+    const rs = fs.createReadStream(path);
+    rs.on('error', reject);
+    rs.on('data', chunk => hash.update(chunk));
+    rs.on('end', () => resolve(hash.digest('hex')));
+  })
+
+  return fileHash;
+}
+
+export async function createWebmanifest(params) {
+
+  const sizes = [192, 512];
+
+  let files = {};
+  for await (const size of sizes) {
+
+    if(params.snippet_language === 'ejs') {
+      files[size] = `<%= require('./icon-${size}.png') %>`;
+
+    } else if(params.webmanifest_add_hash_to_files) {
+      const hashValue = await getHash(`${params.output_dir}/icon-${size}.png`);
+      files[size] = `./icon-${size}.png?_=${hashValue}`;
+
+    } else {
+      files[size] = `./icon-${size}.png`;
+    }
+
+  }
+
+  const manifest = {
+    icons: sizes.map( size => {
+
+      return {
+        src: files[size],
+        type: 'image/png',
+        sizes: `${size}x${size}`
+      };
+    }),
+    ...(params.webmanifest_extra?? {})
+  };
+
+  // await fs.writeFile(`${params.output_dir}/manifest.webmanifest`, JSON.stringify(manifest, null, ' '));
+
+  await fs.writeFile(
+    `${params.output_dir}/${params.manifest_file_name}`,
+    JSON.stringify(manifest, null, ' '),
+    (err) => {
+      if (err) {throw err}
+      // console.log('The file has been saved!');
+    }
+  );
+
+}

package/dev-tools/create-favicons/src/default-params.mjs

@@ -0,0 +1,91 @@
+export const default_params = {
+
+  // delimitazione porzione da copiare nel file init
+  /*** INIT START ***/
+
+  // tutti i percorsi sono relativi alla dir di lavoro
+
+  // immagine sorgente SVG o PNG 512x512
+  src_img: 'favicon-src.svg',
+
+  // sorgente opzionale per immagini piccole (32px)
+  small_src_img: null,
+
+  // directory output (percorso relativo alla dir di lavoro)
+  // se la dir non esiste, viene creata
+  output_dir: './output',
+
+
+  // WEBMANIFEST
+  //****************************************************************************
+  // chiavi aggiuntive per webmanifest, normalmente non necessarie per il browser
+  // vedi https://developer.mozilla.org/en-US/docs/Web/Manifest
+  // esempio:
+  // webmanifest_extra: {
+  //   name: "my Application",
+  //   short_name: "my app",
+  //   background_color: "#ffffff",
+  //   theme_color: "#ffffff",
+  //   display: "fullscreen"
+  // }
+  webmanifest_extra: null,
+
+  // if true, all files linked in manifest will end with
+  // '?_=[hash]'
+  webmanifest_add_hash_to_files: true,
+
+
+  // SNIPPET
+  //****************************************************************************
+
+  // nome del file snippet, compresa l'estensione
+  // se questo parametro è null e anche `snippet_target_file` lo è, lo snippet non viene generato
+  // se il linguaggio è ejs il nome è sempre 'favicons.incl.ejs' e snippet_name viene ignorato
+  snippet_name: 'favicon.html',
+
+  // path (relativo a questo file) in cui salvare lo snippet
+  // se null, viene utilizzato lo stesso percorso indicato in `output_dir`
+  // se la dir non esiste, viene creata
+  snippet_path: null,
+
+  // path del file in cui scrivere le righe dello snippet
+  // questa impostazione è alternativa alle due precedenti e, se presente, queste
+  // ultime vengono ignorate.
+  // Per utilizzarla, le va assegnato il percorso del file (già esistente) nel quale
+  // scrivere le righe delle snippet.
+  // Il file deve contenere dei segnaposti per contrassegnare lo spazio entro il quale
+  // scrivere lo snippets
+  // <!-- favicon-snippet-start --><!-- favicon-snippet-end -->
+  snippet_target_file: null,
+
+  // linguaggio da utilizzare per la sintassi dello snippet html
+  // html, pug, ejs
+  snippet_language: 'ejs',
+
+  // template per la costruzione dello snippet.
+  // si tratta di una stringa (anche su più righe) in cui deve essere presente
+  // '%_link_tags_%', che verrà sostituito con i tag links dei vari file
+  snippet_template: '%_link_tags_%',
+
+  // template per la costruzione di ogni singolo attributo `href` dei tag link.
+  // deve contenere la stringa '%_file_name_%', che conterrà il nome del file,
+  // e la stringa '%_cache_buster_%' (se attivata)', che conterrà `?_=xxxx`, dove
+  // 'xxxx' rappresenta il timestamp generato per annullare la cache.
+  // Va scritto tenendo conto del linguaggio utilizzato.
+  href_template: '/%_file_name_%%_cache_buster_%',
+
+  // se true aggiunge allo snippet una query string per ovviare ad eventuali
+  // problemi di caching del browser
+  add_cache_buster: false,
+
+  //****************************************************************************
+
+  // SHARP PNG PARAMETERS
+  // parametri per i file PNG
+  // vedi https://sharp.pixelplumbing.com/api-output#png
+  png_parameters: {compressionLevel: 5, quality: 60, palette: true}
+
+
+  /*** INIT END ***/
+
+};

package/dev-tools/create-favicons/src/init.mjs

@@ -0,0 +1,52 @@
+/* eslint-env node */
+
+import { URL } from 'url';
+import * as fs from 'fs';
+
+
+import { printFrame } from './print-frame.mjs';
+import { remove_homedir_string } from './remove-homedir-string.mjs';
+
+export function init() {
+  // const __filename = new URL('', import.meta.url).pathname;
+  // Will contain trailing slash
+  const src_dir = new URL('.', import.meta.url).pathname,
+    cfg_sample_file = process.cwd() + '/create-favicons-cfg.mjs';
+
+  if(fs.existsSync(cfg_sample_file)) {
+    throw `${cfg_sample_file} già presente`;
+  }
+
+
+  let default_params = fs.readFileSync(src_dir + './default-params.mjs', 'UTF8');
+
+  const start_string = '/*** INIT START ***/',
+    end_string = '/*** INIT END ***/',
+    init_start_text = fs.readFileSync(src_dir +'./init-start-text.txt', 'utf8');
+
+
+
+  default_params = default_params.substring(
+    default_params.indexOf(start_string) + start_string.length, //from
+    default_params.indexOf(end_string)
+  );
+
+  fs.writeFileSync(
+    cfg_sample_file,
+    init_start_text.trim() + '\n\n' +
+    'const params = [{\n' +
+    default_params +
+    '\n}];\n\n' +
+    'export default params;'
+  );
+
+  printFrame({
+    strings: [
+      {string: '** CREATE-FAVICONS **', color: 'yellow', bold: true,},
+      {string: 'File di configurazione di generato:', color: 'green'},
+      {string: remove_homedir_string(cfg_sample_file), color: 'bgGreen'},
+    ],
+    frameColor: 'green',
+    frameType: 'double'
+  });
+}

package/dev-tools/create-favicons/src/parse-params.mjs

@@ -0,0 +1,61 @@
+import { default_params } from './default-params.mjs';
+import * as path from 'path';
+import * as fs from 'fs';
+
+export function parseParams(config_params = null, work_dir = process.cwd()) {
+
+  try {
+
+    const params = {...default_params, ...(config_params??{})}
+    params.work_dir = work_dir;
+    params.manifest_file_name = 'manifest.webmanifest';
+
+    // ejs overrides
+    if(params.snippet_language === 'ejs') {
+      params.manifest_file_name = 'manifest.webmanifest.ejs';
+      params.webmanifest_add_hash_to_files = false;
+      params.create_snippet = true;
+      params.snippet_name = 'favicons.incl.ejs';
+      params.snippet_target_file = null;
+      params.snippet_path = params.output_dir;
+      params.add_cache_buster = false
+
+    }
+    [
+      'src_img',
+      'small_src_img',
+      'snippet_path',
+      'snippet_target_file',
+      'output_dir'
+    ].forEach(item =>
+      params[item] = params[item]? path.resolve(params.work_dir, params[item]) : null
+    );
+
+    // creazione dir output se non esiste
+    if (!fs.existsSync(params.output_dir)){
+      fs.mkdirSync(params.output_dir);
+    }
+
+    // definizione snippet_path e creazione dir se necessario
+    params.create_snippet = params.snippet_name || params.snippet_target_file;
+
+    if(params.create_snippet) {
+
+      params.snippet_path = params.snippet_path?? params.output_dir;
+
+      if (!params.snippet_target_file && !fs.existsSync(params.snippet_path )){
+        fs.mkdirSync(params.snippet_path );
+      }
+
+      params.snippet_language = params.snippet_language.toLowerCase();
+    }
+
+
+
+    return params;
+
+  } catch(e) {
+    console.error( e ); // eslint-disable-line
+  }
+
+}