@adamlui/scss-to-css 2.2.1 → 2.3.0

package/README.md

@@ -33,8 +33,8 @@
     <img height=31 src="https://img.shields.io/npm/dm/%40adamlui%2Fscss-to-css?logo=npm&color=af68ff&logoColor=white&labelColor=464646&style=for-the-badge"></a>
 <a href="#%EF%B8%8F-mit-license">
     <img height=31 src="https://img.shields.io/badge/License-MIT-orange.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
-<a href="https://github.com/adamlui/js-utils/releases/tag/scss-to-css-2.2.1">
-    <img height=31 src="https://img.shields.io/badge/Latest_Build-2.2.1-44cc11.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://github.com/adamlui/js-utils/releases/tag/scss-to-css-2.3.0">
+    <img height=31 src="https://img.shields.io/badge/Latest_Build-2.3.0-44cc11.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
 <a href="https://www.npmjs.com/package/@adamlui/scss-to-css?activeTab=code">
     <img height=31 src="https://img.shields.io/npm/unpacked-size/%40adamlui%2Fscss-to-css?style=for-the-badge&logo=ebox&logoColor=white&color=blue&labelColor=464646"></a>
 <a href="https://sonarcloud.io/component_measures?metric=new_vulnerabilities&id=adamlui_scss-to-css:src/scss-to-css.js">
@@ -170,6 +170,8 @@ Commands:
  -i, --init                  Create config file (in project root).
  -h, --help                  Display help screen.
  -v, --version               Show version number.
+     --stats                 Show npm stats.
+     --debug [targetKey]     Show debug logs.
 ```
 
 #

package/dist/cli/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+(async () => {
+    'use strict'
+
+    globalThis.env = {
+        args: process.argv.slice(2),
+        modes: { dev: /[\\/]src(?:[\\/]|$)/i.test(__dirname) },
+        paths: { lib: './lib' }
+    }
+    env.modes.debug = env.args.some(arg => /^--?(?:V|debug(?:[-_]?mode)?)$/.test(arg))
+
+    // Import LIBS
+    globalThis.log = require(`${env.paths.lib}/log`)
+    const compile = require(`${env.paths.lib}/compile`),
+        { findSCSS } = require('../scss-to-css'),
+          fs = require('fs'),
+          init = require(`${env.paths.lib}/init`),
+          path = require('path')
+
+    await init.cli()
+
+    // Exec CMD arg if passed
+    if (cli.config.init) return init.configFile()
+    else if (cli.config.help) return log.help()
+    else if (cli.config.version) return log.version()
+    else if (cli.config.stats) return log.stats()
+
+    // Init I/O args
+    const [inputArg = '', outputArg = ''] = // default to empty strings for error-less handling
+        env.args // exclude executable and script paths
+            .filter(arg => !arg.startsWith('-')) // exclude flags
+            .map(arg => arg.replace(/^\/*/, '')) // clean leading slashes to avoid parsing system root
+
+    // Validate input arg (output arg can be anything)
+    let inputPath = path.resolve(process.cwd(), inputArg)
+    if (inputArg && !fs.existsSync(inputPath)) {
+        const scssInputPath = inputPath + '.scss' // append '.scss' in case ommitted from intended filename
+        if (!fs.existsSync(scssInputPath)) {
+            log.error(`${cli.msgs.error_firstArgNotExist}.\n${inputPath} ${cli.msgs.error_doesNotExist}.`)
+            log.success(`${cli.msgs.info_exampleValidCmd}: \n» scss-to-css . output.min.css`)
+            log.helpDocsCmdsDocsURL()
+            process.exit(1)
+        } else inputPath = scssInputPath
+    }
+
+    // Find all eligible source files or arg-passed file
+    log.break()
+    const srcFiles = /s[ac]ss$/.test(inputPath) && !fs.statSync(inputPath).isDirectory() ? [inputPath]
+        : findSCSS(inputPath, {
+            recursive: !cli.config.noRecursion,
+            verbose: !cli.config.quietMode,
+            ignores: cli.config.ignores
+        })
+
+    // Print/compile files
+    if (env.modes.debug || cli.config.dryRun) {
+        if (srcFiles.length) {
+            log.info(`${cli.msgs.info_scssFilesToBeCompiled}:`)
+            srcFiles.forEach(file => log.dim(file))
+        } else // no files found
+            log.info(`${cli.msgs.info_noSCSSfilesWillBeCompiled}.`)
+    } else
+        compile.scss({ srcFiles, inputPath, inputArg, outputArg })
+
+})()

package/dist/cli/lib/color.js

@@ -0,0 +1,31 @@
+const color = module.exports = {
+    nc: '\x1b[0m',
+    hex: {
+        br: '#ff0000',  by: '#ffff00',  bo: '#ffa500',   bg: '#00ff00',
+        bw: '#ffffff', gry: '#808080', blk: '#000000', tlBG: '#008080'
+    },
+    schemes: {
+        get default() {
+            return [
+                '#00e5bc', '#18c8ae', '#30ac9f', '#488f91', '#607383',
+                '#775674', '#8f3966', '#a71d57', '#bf0049', '#9a1b5e'
+            ].map(color.hexToANSI)
+        },
+        get rainbow() {
+            return [
+                '#e41a1c', '#ff7f00', '#ffff33', '#4daf4a', '#377eb8',
+                '#984ea3', '#f781bf', '#999999', '#a65628', '#d95f02'
+            ].map(color.hexToANSI)
+        }
+    },
+
+    hexToANSI(hex) {
+        const r = parseInt(hex.slice(1,3), 16),
+              g = parseInt(hex.slice(3,5), 16),
+              b = parseInt(hex.slice(5,7), 16)
+        return `\x1b[38;2;${r};${g};${b}m`
+    }
+}
+
+for (const hexKey of Object.keys(color.hex)) // add color[hexKey] getters that return ANSI
+    Object.defineProperty(color, hexKey, { get: () => color.hexToANSI(color.hex[hexKey]) })

package/dist/cli/lib/compile.js

@@ -0,0 +1,91 @@
+module.exports = {
+    scss({ srcFiles, inputPath, inputArg, outputArg }) {
+        const { compile } = require('../../scss-to-css'),
+                fs = require('fs'),
+                path = require('path')
+
+        // Build array of compilation data
+        const failedPaths = [] ; let compileData = []
+        if (!cli.config.relativeOutput && fs.statSync(inputPath).isDirectory()) {
+            const compileResult = compile(inputPath, {
+                verbose: false,
+                minify: !cli.config.noMinify,
+                comment: cli.config.comment,
+                relativeOutput: false,
+                recursive: !cli.config.noRecursion,
+                dotFolders: cli.config.includeDotFolders,
+                sourceMaps: !cli.config.noSourceMaps,
+                ignores: cli.config.ignores
+            })
+            if (compileResult) {
+                if (compileResult.error) failedPaths.push(inputPath)
+                else compileData = [].concat(compileResult)
+            }
+        } else compileData = srcFiles.map(scssPath => {
+            const compileResult = compile(scssPath, {
+                verbose: !cli.config.quietMode,
+                minify: !cli.config.noMinify,
+                sourceMaps: !cli.config.noSourceMaps,
+                comment: cli.config.comment
+            })
+            if (compileResult.error) failedPaths.push(scssPath)
+            return compileResult
+        }).filter(compileResult => !compileResult.error)
+
+        // Print compilation summary
+        if (!cli.config.quietMode) {
+            const compiledCnt = compileData.length,
+                  cssCntSuffix = compiledCnt == 1 ? '' : 's'
+            if (compiledCnt) {
+                log.success(`${cli.msgs.info_compilationComplete}!`)
+                log.data(`${compiledCnt} CSS ${cli.msgs.info_file}${cssCntSuffix}${
+                    !cli.config.noSourceMaps ? ` + ${compiledCnt} ${cli.msgs.info_srcMap}${cssCntSuffix}`
+                        : '' } ${cli.msgs.info_generated}.`
+                )
+            } else
+                console.info(`${cli.msgs.info_noSCSSfilesProcessed}.`)
+            if (failedPaths.length) {
+                log.error(`${failedPaths.length} ${cli.msgs.info_file}${ failedPaths.length == 1 ? '' : 's' }`,
+                    `${cli.msgs.info_failedToCompile}:`)
+                failedPaths.forEach(path => log.ifNotQuiet(path))
+            }
+        }
+        if (!compileData?.length) return
+
+        // Copy single result code to clipboard if --copy passed
+        if (cli.config.copy && compileData?.length == 1) {
+            log.data(compileData[0].code)
+            log.ifNotQuiet(`\n${cli.msgs.info_copyingToClip}...`)
+            require('node-clipboardy').writeSync(compileData[0].code)
+
+        } else { // write array data to files
+            log.ifNotQuiet(`${cli.msgs.info_writing}${ compileData?.length > 1 ? 's' : '' }...`)
+            compileData?.forEach(({ code, srcMap, srcPath, relPath }) => {
+                let outputDir, outputFilename
+                if (!cli.config.relativeOutput && relPath) { // preserve folder structure
+                    const outputPath = path.resolve(process.cwd(), outputArg || 'css'),
+                          relativeDir = path.dirname(relPath)
+                    outputDir = relativeDir != '.' ? path.join(outputPath, relativeDir) : outputPath
+                    outputFilename =
+                        `${path.basename(srcPath, path.extname(srcPath))}${ cli.config.noMinify ? '' : '.min' }.css`
+                } else {
+                    outputDir = path.join(
+                        path.dirname(srcPath), // path of file to be minified
+                        outputArg.endsWith('.css') ? path.dirname(outputArg) // or path from file output arg
+                            : outputArg || 'css' // or path from folder outputArg or css/ if no outputArg passed
+                    )
+                    outputFilename = `${
+                        outputArg.endsWith('.css') && /s[ac]ss$/.test(inputArg)
+                            ? path.basename(outputArg).replace(/(\.min)?\.css$/, '')
+                                : path.basename(srcPath, path.extname(srcPath))
+                    }.min.css`
+                }                const outputPath = path.join(outputDir, outputFilename)
+                fs.mkdirSync(outputDir, { recursive: true })
+                fs.writeFileSync(outputPath, code, 'utf8')
+                log.ifNotQuiet(`  ${log.colors.bg}✓${log.colors.nc} ${path.relative(process.cwd(), outputPath)}`)
+                if (!cli.config.noSourceMaps) fs.writeFileSync(`${outputPath}.map`, JSON.stringify(srcMap), 'utf8')
+                log.ifNotQuiet(`  ${log.colors.bg}✓${log.colors.nc} ${path.relative(process.cwd(), outputPath)}.map`)
+            })
+        }
+    }
+}

package/dist/cli/lib/data.js

@@ -0,0 +1,30 @@
+module.exports = {
+
+    atomicWrite(filePath, data, encoding = 'utf8') { // to prevent TOCTOU
+        const fs = require('fs'),
+              path = require('path'),
+              tmpPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp`)
+        fs.writeFileSync(tmpPath, data, encoding) ; fs.renameSync(tmpPath, filePath)
+    },
+
+    fetch(url) { // to support Node.js < v21
+        return typeof fetch == 'undefined' ? new Promise((resolve, reject) => { // using https?.get()
+            const protocol = url.match(/^([^:]+):\/\//)[1]
+            if (!/^https?$/.test(protocol))
+                reject(new Error(`${cli.msgs.error_invalidURL}.`))
+            require(protocol).get(url, resp => {
+                let rawData = ''
+                resp.on('data', chunk => rawData += chunk)
+                resp.on('end', () => resolve({ json: () => JSON.parse(rawData), text: () => rawData }))
+            }).on('error', reject)
+        }) : fetch(url) // using Node.js fetch()
+    },
+
+    flatten(json, { key = 'message' } = {}) { // eliminate need to ref nested keys
+        const flatObj = {}
+        for (const jsonKey in json) flatObj[jsonKey] =
+            typeof json[jsonKey] == 'object' && key in json[jsonKey] ? json[jsonKey][key]
+                                                                     : json[jsonKey]
+        return flatObj
+    }
+}

package/dist/cli/lib/init.js

@@ -0,0 +1,49 @@
+const language = require('./language'),
+      settings = require('./settings')
+
+const dataPath = `../../${ env.modes.dev ? '../' : 'data/' }`
+
+module.exports = {
+
+    async cli() {
+        Object.assign(globalThis.cli ??= {}, require(`${dataPath}package-data.json`))
+        cli.msgs = await language.getMsgs('en')
+        cli.msgs = await language.getMsgs(cli.lang = settings.load('uiLang') || (
+            env.modes.debug ? language.generateRandomLang({ excludes: ['en'] }) : language.getSysLang() ))
+        cli.urls.cliDocs = `${cli.urls.docs}/#-command-line-usage`
+        if (!cli.lang.startsWith('en')) { // localize cli.urls.cliDocs
+            cli.docLocale = cli.lang.replace('_', '-').toLowerCase()
+            cli.docLocales ??= await language.getDocLocales()
+            if (cli.docLocales?.includes(cli.docLocale))
+                log.debug(cli.urls.cliDocs = `${cli.urls.docs}/${cli.docLocale}#readme`)
+        }
+        settings.load() // all keys to cli.config
+    },
+
+    async configFile(filename = settings.configFilename) {
+        const fs = require('fs'),
+              path = require('path'),
+              paths = { target: path.resolve(process.cwd(), filename) }
+
+        if (fs.existsSync(paths.target)) // use existing config file
+            return log.warn(`${cli.msgs.warn_configFileExists}:`, paths.target)
+        if (fs.existsSync(paths.src = path.resolve(__dirname, `${dataPath}${filename}`)))
+            fs.copyFileSync(paths.src, paths.target) // use found template
+
+        else { // use jsDelivr copy
+            const jsdURL = `${require('./jsdelivr').pkgVerURL()}/${filename}/`
+            log.data(`${cli.msgs.info_fetchingRemoteConfigFrom} ${jsdURL}...`)
+            try {
+                const data = require('./data'),
+                      resp = await data.fetch(jsdURL)
+                if (resp.ok) data.atomicWrite(paths.target, await resp.text())
+                else return log.warn(`${cli.msgs.warn_remoteConfigNotFound}: ${jsdURL} (${resp.status})`)
+            } catch (err) {
+                return log.warn(`${cli.msgs.warn_remoteConfigFailed}: ${jsdURL} ${err.message}`) }
+        }
+
+        log.success(`${cli.msgs.info_configFileCreated}: ${paths.target}\n`)
+        log.tip(`${cli.msgs.tip_editToSetDefaults}.`)
+        log.tip(`${cli.msgs.tip_cliArgsPrioritized}.`)
+    }
+}

package/dist/cli/lib/jsdelivr.js

@@ -0,0 +1,10 @@
+module.exports = {
+
+    pkgVerURL(version) {
+        version ||= cli.version ||= require('./pkg').getVer('local') || 'none'
+        const verTag = !/^\d+\.\d+\.\d+$/.test(version) ? 'latest' : `v${version}`
+        return `${cli.urls.jsdelivr}@${verTag}`
+    },
+
+    commitURL(hash = 'latest') { return `${cli.urls.jsdelivr}@${hash}` }
+}

package/dist/cli/lib/language.js

@@ -0,0 +1,106 @@
+const data = require('./data')
+
+module.exports = {
+
+    formatCode(langCode) { // to match locale dir name
+        return langCode.replace(
+            /([a-z]{2,8})[-_]([a-z]{2})/i, (_, lang, region) =>`${lang.toLowerCase()}_${region.toUpperCase()}`) },
+
+    generateRandomLang({ includes = [], excludes = [] } = {}) {
+        const fs = require('fs'),
+              path = require('path')
+
+        let locales = includes.length ? includes : (() => {
+
+            // Read cache if found
+            const cacheDir = path.join(__dirname, '..', '.cache'),
+                  localeCache = path.join(cacheDir, 'locales.json')
+            if (fs.existsSync(localeCache))
+                try { return JSON.parse(fs.readFileSync(localeCache, 'utf8')) } catch (err) {}
+
+            // Discover pkg _locales
+            const localesDir = path.resolve(process.cwd(), '_locales')
+            if (!fs.existsSync(localesDir)) return ['en']
+            const locales = fs.readdirSync(localesDir, { withFileTypes: true })
+                .filter(entry => entry.isDirectory()).map(entry => entry.name)
+                .filter(name => /^\w{2}[-_]?\w{0,2}$/.test(name))
+
+            // Cache result
+            fs.mkdirSync(cacheDir, { recursive: true })
+            data.atomicWrite(localeCache, JSON.stringify(locales, null, 2))
+
+            return locales
+        })()
+
+        // Filter out excludes
+        const excludeSet = new Set(excludes)
+        locales = locales.filter(locale => !excludeSet.has(locale))
+
+        // Get random language
+        let randomLang = 'en'
+        if (locales.length)
+            randomLang = locales[Math.floor(Math.random() * locales.length)]
+        log.debug(`Random language: ${randomLang}`)
+
+        return randomLang
+    },
+
+    async getDocLocales() {
+        cli.version ||= require('./pkg').getVer('local') || 'none'
+        const jsdURL = `${require('./jsdelivr').pkgVerURL()}/docs/`,
+              locales = []
+        try {
+            const respText = await (await data.fetch(jsdURL)).text(),
+                  reLocale = /href=".*\/docs\/([^/]+)\/"/g
+            let match ; while ((match = reLocale.exec(respText))) locales.push(match[1]) // store locale dir names
+        } catch (err) {
+            log.warn(`${cli.msgs.warn_docLocalesFetchFailed}:`, err.message)
+        }
+        return locales
+    },
+
+    async getMsgs(langCode = 'en') {
+        langCode = module.exports.formatCode(langCode)
+        if (env.msgs && langCode == cli.lang) return env.msgs // don't re-fetch same msgs
+
+        let msgs = data.flatten( // local ones
+            require(`../../${ env.modes.dev ? '../_locales/en/' : 'data/' }messages.json`))
+
+        if (!langCode.startsWith('en')) { // fetch non-English msgs from jsDelivr
+            const msgHostURL = `${require('./jsdelivr').commitURL(cli.commitHashes.locales)}/_locales/`
+            let msgHref = `${msgHostURL}${langCode}/messages.json`, msgFetchesTried = 0
+            while (msgFetchesTried < 3)
+                try { // fetch remote msgs
+                    msgs = data.flatten(await (await data.fetch(msgHref)).json())
+                    break
+                } catch (err) { // retry up to 2X (region-stripped + EN)
+                    msgFetchesTried++ ; if (msgFetchesTried >= 3) break
+                    log.debug(msgHref = langCode.includes('-') && msgFetchesTried == 1 ?
+                        msgHref.replace(/([^_]*)_[^/]*(\/.*)/, '$1$2') // strip region before retrying
+                            : `${msgHostURL}en/messages.json` // else use EN msgs
+                    )
+                }
+        }
+
+        return msgs
+    },
+
+    getSysLang() {
+        try {
+            if (process.platform == 'win32')
+                return require('child_process').execSync(
+                    '(Get-Culture).TwoLetterISOLanguageName', { shell: 'powershell', encoding: 'utf-8' }
+                ).trim()
+            else { // macOS/Linux
+                const pe = process.env
+                return (pe.LANG || pe.LANGUAGE || pe.LC_ALL || pe.LC_MESSAGES || pe.LC_NAME)
+                    .split('.')[0] // strip encoding e.g. .UTF-8
+            }
+        } catch (err) {
+            log.error(`${cli.msgs.error_failedToFetchSysLang}:`, err.message)
+            return 'en'
+        }
+    },
+
+    validateLangCode(code) { return typeof code != 'string' ? false : /^[a-z]{2,8}(?:[-_][a-z]{2,3})?$/i.test(code) }
+}

package/dist/cli/lib/log.js

@@ -0,0 +1,174 @@
+const colors = require('./color'),
+    { getDownloads, getVer } = require('./pkg'),
+      string = require('./string')
+
+const nextMajVer = require('../../../package.json').version.replace(/^(\d+)\..*/, (_, major) => `${ +major +1 }.0.0`)
+
+module.exports = {
+    colors,
+
+    configURL() { this.info(`${cli.msgs.info_exampleValidConfigFile}: ${cli.urls.config}`) },
+    configURLandExit(...args) { this.error(...args); this.configURL(); process.exit(1) },
+    data(msg) { console.log(`\n${colors.bw}${msg}${colors.nc}`) },
+    dim(msg) { console.log(`${colors.gry}${msg}${colors.nc}`) },
+    error(...args) { console.error(`\n${colors.br}ERROR:`, ...args, colors.nc) },
+    errorAndExit(...args) { this.error(...args); this.helpDocsCmdsDocsURL(); process.exit(1) },
+    ifNotQuiet(msg) { if (!cli.config.quietMode) this.info(msg) },
+    info(msg) { console.info(`\n${colors.schemes.default[0]}${msg}${colors.nc}`) },
+    break() { console.log() },
+    tip(msg) { console.info(`${colors.by}TIP: ${msg}${colors.nc}`) },
+    success(msg) { console.log(`\n${colors.bg}${msg}${colors.nc}`) },
+    warn(...args) { console.warn(`\n${colors.bo}WARNING:`, ...args, colors.nc) },
+
+    argDoesNothing(arg) {
+        this.warn(`${cli.msgs.warn_option} ${arg} ${cli.msgs.warn_noLongerHasAnyEffect} ${
+                     cli.msgs.warn_andWillBeRemoved} @ v${nextMajVer}`)
+    },
+
+    configKeyReplacedBy(oldKey, newKey, oldVal) {
+        if (!this[`${oldKey}Warned`]) {
+            this.warn(
+                `${cli.msgs.info_configFile} ${cli.msgs.warn_option.toLowerCase()} '${oldKey}: ${oldVal}' ${
+                   cli.msgs.warn_hasBeenReplacedBy} '${
+                       newKey}: ${ isNegKey(oldKey) != isNegKey(newKey) ? !oldVal : oldVal }' ${
+                   cli.msgs.warn_andWillBeRemoved} @ v${nextMajVer}`
+            )
+            this[`${oldKey}Warned`] = true
+            function isNegKey(key) { return /^(?:no|disable|exclude)[A-Z]/.test(key) }
+        }
+    },
+
+    debug(msg) {
+        if (!env.modes.debug) return
+        this.argIdx ??= env.args.findIndex(arg => /^--?(?:V|debug(?:[-_]?mode)?)$/.test(arg))
+        if (this.argIdx +1 < env.args.length && !env.args[this.argIdx +1].startsWith('-')) // use --debug [targetKey]
+            this.key ??= env.args[this.argIdx +1].replace('-', '_')
+        if (this.key)
+            this.val = cli.config[this.key] || `cli.config key "${this.key}" ${cli.msgs.warn_notFound.toLowerCase()}`
+        else
+            this.val = cli.config
+        msg += `\n${colors.gry}${JSON.stringify(this.val)}${colors.nc}`
+        console.debug(`\n${colors.by}DEBUG:`, msg, colors.nc)
+    },
+
+    help(includeSections = ['header', 'usage', 'pathArgs', 'flags', 'params', 'cmds']) {
+        cli.prefix = `${this.colors.tlBG}${this.colors.blk} ${cli.name.replace(/^@[^/]+\//, '')} ${this.colors.nc} `
+        const helpSections = {
+            header: [
+                `\n├ ${cli.prefix}${cli.msgs.pkg_copyright}.`,
+                `${cli.prefix}${cli.msgs.prefix_source}: ${cli.urls.src}`
+            ],
+            usage: [
+                `\n${this.colors.bw}o ${cli.msgs.helpSection_usage}:${this.colors.nc}`,
+                ` ${this.colors.bw}» ${this.colors.bg}${cli.cmdFormat}${this.colors.nc}`
+            ],
+            pathArgs: [
+                `\n${this.colors.bw}o ${cli.msgs.helpSection_pathArgs}:${this.colors.nc}`,
+                ` [inputPath]                             ${cli.msgs.inputPathDesc_main}, ${
+                                                            cli.msgs.inputPathDesc_extra}.`,
+                ` [outputPath]                            ${cli.msgs.outputPathDesc_main}, ${
+                                                            cli.msgs.outputPathDesc_extra}`
+            ],
+            flags: [
+                `\n${this.colors.bw}o ${cli.msgs.helpSection_flags}:${this.colors.nc}`,
+                ` -n, --dry-run                           ${cli.msgs.optionDesc_dryRun}.`,
+                ` -d, --include-dotfolders                ${cli.msgs.optionDesc_dotfolders}.`,
+                ` -S, --no-source-maps                    ${cli.msgs.optionDesc_noSourceMaps}.`,
+                ` -M, --no-minify                         ${cli.msgs.optionDesc_noMinify}.`,
+                ` -R, --no-recursion                      ${cli.msgs.optionDesc_noRecursion}.`,
+                ` -r, --relative-output                   ${cli.msgs.optionDesc_relativeOutput}.`,
+                ` -c, --copy                              ${cli.msgs.optionDesc_copy}.`,
+                ` -q, --quiet                             ${cli.msgs.optionDesc_quiet}.`
+            ],
+            params: [
+                `\n${this.colors.bw}o ${cli.msgs.helpSection_params}:${this.colors.nc}`,
+                `--ignores="dir/,file1.scss,file2.sass"   ${cli.msgs.optionDesc_ignores}.`,
+                `--comment="comment"                      ${cli.msgs.optionDesc_commentMain}. ${
+                                                            cli.msgs.optionDesc_commentExtra}.`,
+                ` --ui-lang="code"                        ${cli.msgs.optionDesc_uiLang}.`,
+                ` --config="path/to/file"                 ${cli.msgs.optionDesc_config}.`
+            ],
+            cmds: [
+                `\n${this.colors.bw}o ${cli.msgs.helpSection_cmds}:${this.colors.nc}`,
+                ` -i, --init                              ${cli.msgs.optionDesc_init}.`,
+                ` -h, --help                              ${cli.msgs.optionDesc_help}.`,
+                ` -v, --version                           ${cli.msgs.optionDesc_version}.`,
+                ` -v, --stats                             ${cli.msgs.optionDesc_stats}.`,
+                ` -V, --debug                             ${cli.msgs.optionDesc_debug}.`
+            ]
+        }
+        includeSections.forEach(section => // print valid arg elems
+            helpSections[section]?.forEach(line => printHelpMsg(line, /header|usage/.test(section) ? 1 : 41)))
+        console.info(`\n${cli.msgs.info_moreHelp}, ${
+            cli.msgs.info_visit}: ${this.colors.bw}${cli.urls.cliDocs}${this.colors.nc}`)
+
+        function printHelpMsg(msg, indent) { // wrap msg + indent 2nd+ lines
+            const terminalWidth = process.stdout.columns || 80,
+                  words = msg.match(/\S+|\s+/g),
+                  lines = [], prefix = '| '
+
+            // Split msg into lines of appropriate lengths
+            let currentLine = ''
+            words.forEach(word => {
+                const lineLength = terminalWidth -( !lines.length ? 0 : indent )
+                if (currentLine.length + prefix.length + word.length > lineLength) { // cap/store it
+                    lines.push(!lines.length ? currentLine : currentLine.trimStart())
+                    currentLine = ''
+                }
+                currentLine += word
+            })
+            lines.push(!lines.length ? currentLine : currentLine.trimStart())
+
+            // Print formatted msg
+            lines.forEach((line, idx) => console.info(prefix +(
+                idx == 0 ? line // print 1st line unindented
+                    : ' '.repeat(indent) + line // print subsequent lines indented
+            )))
+        }
+    },
+
+    helpDocsCmdsDocsURL() {
+        console.info(`\n${
+            cli.msgs.info_moreHelp}, ${cli.msgs.info_type} ${
+                colors.bw}${cli.name.split('/')[1]} --<docs|help>${colors.nc} ${
+                cli.msgs.info_or} ${cli.msgs.info_visit}\n${colors.by}${cli.urls.docs}${colors.nc}`
+        )
+    },
+
+    initCmd(invalidKey) {
+        if (invalidKey)
+            this.warn(
+                `${cli.msgs.error_invalidKey} '${invalidKey}' ${cli.msgs.error_foundIn}\n`
+                + `${log.colors.gry}${cli.configPath}`
+            )
+        if (!this.initTipped) {
+            this.break()
+            this.tip(`${
+                string.toTitleCase(cli.msgs.info_type)} '${cli.name} init' ${
+                    cli.msgs.info_toCreateDefaultConfig}`
+            )
+            this.initTipped = true
+        }
+    },
+
+    invalidConfigKey(key) { if (!this[`${key}Tipped`]) { this.initCmd(key) ; this[`${key}Tipped`] = true } },
+
+    async stats(pkgName = cli.name, options = { ecosystem: 'npm', maxDays: 8, maxVers: 5, scheme: 'default' }) {
+        const pkgStats = await getDownloads(pkgName, options),
+              schemeData = colors.schemes[options.scheme]
+        if (!schemeData) return this.error(`Scheme '${options.scheme}' not found!`)
+        const colorMap = Object.fromEntries(schemeData.map((hex, idx) => [`c${idx}`, hex])),
+              statsTable = new (require('console-table-printer').Table)({ colorMap })
+        pkgStats.forEach((row, idx) => // build colored rows
+            statsTable.addRow(row, { color: `c${Math.floor(idx / pkgStats.length * schemeData.length)}` }))
+        statsTable.printTable()
+    },
+
+    version() {
+        this.info(cli.name)
+        this.data(`${
+            cli.msgs.prefix_globalVer}: ${ getVer('global') || 'none' }\n${
+            cli.msgs.prefix_localVer }: ${ getVer('local')  || 'none' }`
+        )
+    }
+}

package/dist/cli/lib/pkg.js

@@ -0,0 +1,78 @@
+const data = require('./data')
+
+const endpoints = {
+    npmjsDLs: 'https://api.npmjs.org/downloads',
+    pepyProjects: 'https://pepy.tech/projects'
+}
+
+module.exports = {
+
+    async getDownloads(
+          pkgName, // e.g. some-npm-pkg, npm:@adamlui/minify.js, pypi:translate-messages
+        { ecosystem = 'npm', maxDays = 10, maxVers = 10 } = {}
+    ) {
+        if (pkgName.includes(':')) [ecosystem, pkgName] = pkgName.split(':')
+
+        if (/npm|node/i.test(ecosystem)) { // fetch from endpoints.npmjsDLs
+            function formatDate(date) { return date.toISOString().split('T')[0] }
+            const dates = { end: new Date(), start: new Date() }
+            dates.start.setMonth(dates.end.getMonth() -3)
+            const npmjsURL = `${endpoints.npmjsDLs}/range/${formatDate(dates.start)}:${formatDate(dates.end)}/${pkgName}`
+            log.info(`Fetching npm stats for ${pkgName}${
+                env.modes.debug ? ` from\n${log.colors.bw}${npmjsURL}` : '' }...\n`)
+            return (await (await data.fetch(npmjsURL)).json()).downloads // { downloads: [{ day, downloads }] }
+                .sort((a, b) => new Date(b.day) - new Date(a.day)) // new ⇅ old
+                .slice(0, maxDays) // cap rows
+                .map(({ day: date, downloads }) => ({ date, downloads }))
+
+        } else if (/^py/i.test(ecosystem)) { // fetch from endpoints.pepyProjects
+            let rows = []
+            const pepyURL = `${endpoints.pepyProjects}/${pkgName}`
+            log.info(`Fetching PyPI/mirror stats for ${pkgName}${
+                env.modes.debug ? ` from\n${log.colors.bw}${pepyURL}` : '' }...\n`)
+            const respText = await (await data.fetch(pepyURL)).text(),
+                  rePush = /self\.__next_f\.push\(\[\d+,\s*"((?:\\.|[^"\\])*)"\]\)/g
+            let downloads = {}, match
+            while ((match = rePush.exec(respText))) {
+                try { // extract project.downloads
+                    const inner = JSON.parse(`"${match[1]}"`),
+                          data = JSON.parse(inner.substring(inner.indexOf(':') +1))
+                    if (data[3]?.project) downloads = data[3].project.downloads
+                } catch (err) {}
+            }
+            rows = Object.entries(downloads)
+                .sort(([a], [b]) => new Date(b) - new Date(a)) // new ⇅ old
+                .slice(0, maxDays) // cap rows
+                .map(([date, data]) => ({ date, ...data }))
+            const activeVers = new Set()
+            rows.forEach(row => Object.keys(row).forEach(key => {
+                if (key != 'date' && row[key] > 0) activeVers.add(key) }))
+            const finalVers = [...activeVers]
+                .sort((a, b) => b.localeCompare(a, undefined, { numeric: true })) // new ⇆ old
+                .slice(0, maxVers) // cap columns
+            return rows.map(row => {
+                const result = { date: row.date }
+                finalVers.forEach(ver => result[ver] = row[ver] || 0)
+                return result
+            })
+
+        } else return log.debug(`${ecosystem} not supported.`)
+    },
+
+    getVer(type = 'any') { // or <'global'|'local'>
+        let pkgVer
+        if (type != 'global')
+            try { // get local ver
+                const localManifestPath = require('path').resolve(
+                    process.cwd(), 'node_modules', cli.name, 'package.json')
+                pkgVer = require(localManifestPath).version
+            } catch (err) { log.debug(`${cli.msgs.error_readingLocalPkgVer}: ${err.message}`) }
+        if (type == 'global' || type == 'all' && !pkgVer)
+            try { // get global ver
+                pkgVer = require('child_process').execSync(
+                    `npm view ${JSON.stringify(cli.name)} version`
+                ).toString().trim()
+            } catch (err) { log.debug(`${cli.msgs.error_failedToFetchGlobalVer}: ${err.message}`) }
+        return pkgVer
+    }
+}