@magic/cli 0.0.46 → 0.0.48

package/README.md

@@ -90,7 +90,7 @@ _those issues might get addressed in the future._
 first, define the cli file
 
 ```javascript
-// ./bin.mjs
+// ./bin.js
 import { cli } from '@magic/cli'
 
 const res = cli({
@@ -120,7 +120,7 @@ argv mappings handle options and option aliases
 using the cli file above
 
 ```bash
-./bin.mjs -f1 arg1 arg2 -f2
+./bin.js -f1 arg1 arg2 -f2
 ```
 
 resulting process.argv:
@@ -128,7 +128,7 @@ resulting process.argv:
 ```javascript
 process.argv = [
   '/path/to/bin/node',
-  '/path/to/bin.mjs',
+  '/path/to/bin.js',
   'cmd1',
   '--flag1'
   'arg1',
@@ -169,7 +169,7 @@ cli commands will be handled too.
 #### <a name="help-simple"></a>simple help message
 
 ```javascript
-// ./bin.mjs
+// ./bin.js
 
 import cli from '@magic/cli'
 
@@ -183,10 +183,10 @@ const args = {
 const argv = cli(args)
 ```
 
-then run ./bin.mjs without arguments
+then run ./bin.js without arguments
 
 ```bash
-./bin.mjs
+./bin.js
 
 // help output
 `
@@ -552,6 +552,16 @@ update dependencies
 - cli.exec allows stderrToStdout redirect config option
 - update dependencies
 
-##### 0.0.47 - unreleased
+##### 0.0.47
+
+- rename .mjs to js
+- add more tests
+- update dependencies
+
+##### 0.0.48
+
+- types changed to allow correct props when calling /src/index.js cli function
+
+##### 0.0.49 - unreleased
 
 - ...

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "@magic/cli",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "homepage": "https://magic.github.io/cli",
   "description": "declarative command line interfaces with aliasing, commands and environment sanitization",
   "scripts": {
     "start": "t -p",
     "format": "f -w --exclude docs",
     "test": "t --exclude docs example config.js",
-    "build": "NODE_ENV=production magic build",
+    "build": "tsc && npm run format",
+    "prepublishOnly": "npm run test && npm run build",
+    "build:docs": "NODE_ENV=production magic build",
     "prod": "NODE_ENV=production magic build serve",
     "dev": "magic dev",
     "calls": "calls"
   },
-  "main": "src/index.mjs",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
   "type": "module",
   "files": [
-    "src"
+    "src",
+    "types"
   ],
   "engines": {
     "node": ">=14.15.4"
@@ -32,11 +36,11 @@
     "declarative"
   ],
   "dependencies": {
-    "@magic/cases": "0.0.9",
-    "@magic/deep": "0.1.16",
-    "@magic/error": "0.0.17",
-    "@magic/log": "0.1.18",
-    "@magic/types": "0.1.23"
+    "@magic/cases": "0.0.10",
+    "@magic/deep": "0.1.18",
+    "@magic/error": "0.0.20",
+    "@magic/log": "0.1.20",
+    "@magic/types": "0.1.28"
   },
   "devDependencies": {
     "@magic-modules/git-badges": "0.0.12",
@@ -44,9 +48,10 @@
     "@magic-modules/no-spy": "0.0.9",
     "@magic-modules/pre": "0.0.12",
     "@magic-themes/docs": "0.0.15",
-    "@magic/core": "0.0.153",
-    "@magic/format": "0.0.51",
-    "@magic/test": "0.2.17"
+    "@magic/core": "0.0.156",
+    "@magic/format": "0.0.68",
+    "@magic/test": "0.2.20",
+    "typescript": "5.9.3"
   },
   "author": "Wizards & Witches",
   "license": "AGPL-3.0",

package/src/{exec.mjs → exec.js}

@@ -4,6 +4,13 @@ import error from '@magic/error'
 
 const libName = '@magic/cli.exec'
 
+/**
+ * Executes a shell command using child_process.exec
+ * @param {string} cmd - The shell command to execute.
+ * @param {object} [options={}] - Execution options.
+ * @param {boolean} [options.stderrToStdout=false] - If true, resolves stderr as stdout instead of rejecting.
+ * @returns {Promise<string>} Resolves with stdout or stderr (if stderrToStdout = true), rejects with Error.
+ */
 export const exec = (cmd, options = {}) =>
   new Promise((resolve, reject) => {
     const { stderrToStdout, ...opts } = options

package/src/{execFile.mjs → execFile.js}

@@ -4,6 +4,13 @@ import error from '@magic/error'
 
 const libName = '@magic/cli.execFile'
 
+/**
+ * Executes a file using child_process.execFile
+ * @param {string} p - Path to the executable file.
+ * @param {string[]} [args=[]] - Arguments to pass to the executable.
+ * @param {import('child_process').ExecFileOptions} [opts={}] - Execution options.
+ * @returns {Promise<string | Buffer>} Resolves with stdout, rejects with Error.
+ */
 export const execFile = (p, args = [], opts = {}) =>
   new Promise((resolve, reject) => {
     child_process.execFile(
@@ -17,7 +24,7 @@ export const execFile = (p, args = [], opts = {}) =>
           return
         }
         if (stderr) {
-          const e = error(new Error(`${libName}: ${cmd} error: ${stderr}`), 'E_EXECFILE_STDERR')
+          const e = error(new Error(`${libName}: error: ${stderr}`), 'E_EXECFILE_STDERR')
           reject(e)
           return
         }

package/src/help/{argToHelp.mjs → argToHelp.js}

@@ -2,10 +2,19 @@ import is from '@magic/types'
 import log from '@magic/log'
 import error from '@magic/error'
 
-import { findLongestString } from './findLongestString.mjs'
+import { findLongestString } from './findLongestString.js'
 
 const lib = '@magic/cli.help.argToHelp'
 
+/**
+ * Converts an array of CLI argument definitions into a formatted help string.
+ *
+ * @param {(string | string[])[]} arr - Array of argument names or alias arrays.
+ * @param {Record<string, string>} [help={}] - Optional help descriptions keyed by argument name.
+ * @param {Record<string, any>} [defaults={}] - Default values for each argument.
+ * @returns {string} A formatted help text block.
+ * @throws {Error} If `arr` is not a valid array.
+ */
 export const argToHelp = (arr, help = {}, defaults = {}) => {
   if (!is.array(arr)) {
     throw error(
@@ -19,6 +28,7 @@ export const argToHelp = (arr, help = {}, defaults = {}) => {
   return arr
     .map(opt => {
       let name = opt
+      /** @type {string[]} */
       let aliases = []
       if (is.array(name)) {
         const [n, ...al] = opt

package/src/help/{envToHelp.mjs → envToHelp.js}

@@ -1,8 +1,20 @@
 import log from '@magic/log'
 
-import { findLongestString } from './findLongestString.mjs'
+import { findLongestString } from './findLongestString.js'
+import is from '@magic/types'
 
+/**
+ * Converts an array of environment variable definitions into formatted help text.
+ *
+ * @param {Array<[string[], string, string]>} env - Array of tuples:
+ *   [command aliases, variable name, value description].
+ * @returns {string} A formatted help text block for environment variables.
+ */
 export const envToHelp = env => {
+  if (!env || !is.array(env)) {
+    return ''
+  }
+
   const envStrings = env.map(env => env[0])
 
   const longest = findLongestString(envStrings)

package/src/help/findLongestString.js

@@ -0,0 +1,19 @@
+import deep from '@magic/deep'
+
+/**
+ * Finds the longest string within a (possibly nested) array.
+ *
+ * @param {Array<string | string[]>} arr - Array that may contain strings or nested arrays of strings.
+ * @returns {string} The longest string found in the array.
+ */
+export const findLongestString = arr => {
+  const sorted = arr.flat(200).sort((a, b) => {
+    if (a.length !== b.length) {
+      return b.length - a.length
+    }
+
+    return a > b ? 1 : -1
+  })
+
+  return sorted[0]
+}

package/src/help/index.js

@@ -0,0 +1,100 @@
+import log from '@magic/log'
+import is from '@magic/types'
+
+import { envToHelp } from './envToHelp.js'
+import { argToHelp } from './argToHelp.js'
+
+/**
+ * @typedef {object} ParsedCLI
+ * @property {Record<string, any>} [args] - Parsed CLI flags or arguments.
+ * @property {Record<string, any>} [commands] - Parsed subcommands.
+ * @property {Array<string|string[]>} [errors] - Validation errors or missing required args.
+ */
+
+/**
+ * @typedef {object} CLIHelpMeta
+ * @property {string} [name] - CLI name shown in the help header.
+ * @property {string} [text] - General help text or description.
+ * @property {string|string[]} [example] - Example usage text or lines.
+ * @property {Record<string, string>} [commands] - Help text for commands.
+ * @property {Record<string, string>} [options] - Help text for options/flags.
+ * @property {Record<string, string>} [env] - Help text for environment variables.
+ */
+
+/**
+ * @typedef {object} CLIArgs
+ * @property {ParsedCLI} [parsed] - Parsed CLI data (from argument parser).
+ * @property {Array<(string|string[])>} [commands] - CLI commands or argument definitions.
+ * @property {Array<(string|string[])>} [options] - CLI option/flag definitions.
+ * @property {Array<[string[], string, string]>} [env] - Environment variable mappings.
+ * @property {Record<string, any>} [default] - Default values for options or flags.
+ * @property {CLIHelpMeta} [help] - Help configuration or raw string help text.
+ */
+
+/**
+ * Builds and returns formatted help text for a CLI command.
+ * Returns `false` if help is not requested and no errors occurred.
+ *
+ * @param {CLIArgs} args - The CLI arguments/config object.
+ * @returns {string|false} The generated help text or `false` if not shown.
+ */
+export const maybeHelp = args => {
+  const { parsed = {} } = args
+
+  const hasCommands = args.commands && Object.entries(args.commands).length > 0
+  const showCommandHelp =
+    hasCommands && parsed.commands && Object.keys(parsed.commands).length === 0
+
+  const helpRequested = parsed.args?.help
+
+  const showHelp = showCommandHelp || helpRequested || !is.empty(parsed.errors)
+
+  if (!showHelp) {
+    return false
+  }
+
+  // add help text inspection here
+  const { commands = [], default: defaults = [], options = [], env = [], help = {} } = args
+
+  const commandHelp = argToHelp(commands, help.commands)
+  const optionHelp = argToHelp(options, help.options, defaults)
+  const envHelp = envToHelp(env)
+
+  const name = help.name || '@magic/cli wrapped cli.'
+  const header = is.string(help) ? help : help.text
+
+  const exampleArray = is.string(help.example) ? help.example.split('\n') : help.example || []
+
+  const exampleText = exampleArray
+    .map(a => {
+      if (a.trim().startsWith('#')) {
+        return log.color('green', a)
+      } else {
+        return a.trim()
+      }
+    })
+    .join('\n')
+
+  const helpArray = [
+    log.paint('green', name),
+    '\n',
+    header && `\n${log.paint('grey', header)}\n\n`,
+    commands.length && `${log.paint('grey', 'commands')}:\n${commandHelp}\n\n`,
+    options.length && `${log.paint('grey', 'flags')}:\n${optionHelp}\n\n`,
+    env.length && `${log.paint('grey', 'environment switches')}:\n${envHelp}\n\n`,
+    'examples:\n',
+    exampleText,
+  ]
+
+  const errors = parsed.errors
+    ?.map(e => `${log.paint('red', 'Error:')} ${is.arr(e) ? e.join(' or ') : e} is required`)
+    .filter(a => a)
+    .join('\n')
+
+  const errorMsg = `\n${errors}`
+  if (errors?.length) {
+    helpArray.push(errorMsg)
+  }
+
+  return helpArray.filter(a => a).join('')
+}

package/src/index.js

@@ -0,0 +1,75 @@
+import log from '@magic/log'
+
+import { maybeHelp } from './help/index.js'
+import { parse } from './parse/index.js'
+
+import { exec as execute } from './exec.js'
+import { execFile as executeFile } from './execFile.js'
+import { spawn as spawner } from './spawn.js'
+import { prompt as promptUser } from './prompt.js'
+
+/**
+ * @typedef {object} ParseProps
+ * @property {Array<string|string[]>} [options]
+ * @property {Record<string, any>|Array<any>} [prepend]
+ * @property {Record<string, any>|Array<any>} [append]
+ * @property {Record<string, any>} [default]
+ * @property {boolean} [pure]
+ * @property {boolean} [pureEnv]
+ * @property {boolean} [pureArgv]
+ * @property {boolean} [pureCommands]
+ * @property {Array<string|string[]>} [commands]
+ * @property {Array<[string[], string, string]>} [env]
+ * @property {Array<string|string[]>} [required]
+ * @property {object} [help]
+ */
+
+/**
+ * @typedef {object} ParsedCLI
+ * @property {Record<string, string>} env
+ * @property {Record<string, any>} argv
+ * @property {Record<string, any>} args
+ * @property {Record<string, boolean>} commands
+ * @property {Array<string|string[]>} errors
+ */
+
+/**
+ * Main CLI entry point
+ * @param {ParseProps} args - CLI configuration object.
+ * @returns {ParsedCLI}
+ */
+export const cli = (args = {}) => {
+  const { options = [] } = args
+
+  const hasHelpOption = options.some(option => option.includes('--help'))
+  if (!hasHelpOption) {
+    options.push(['--help', '-h'])
+  }
+
+  args.options = options
+
+  const parsed = parse(args)
+
+  const helpText = maybeHelp({ ...args, parsed })
+
+  if (helpText) {
+    log(helpText)
+    process.exit()
+  }
+
+  return parsed
+}
+
+export const spawn = spawner
+cli.spawn = spawner
+
+export const exec = execute
+cli.exec = execute
+
+export const prompt = promptUser
+cli.prompt = promptUser
+
+export const execFile = executeFile
+cli.execFile = executeFile
+
+export default cli

package/src/parse/argv.js

@@ -0,0 +1,125 @@
+import is from '@magic/types'
+import cases from '@magic/cases'
+
+/**
+ * @typedef {string | string[]} Option
+ */
+
+/**
+ * @typedef {Record<string, string | string[]>} ArgMap
+ */
+
+/**
+ * @typedef {object} ParseArgvProps
+ * @property {Option[]} [options] - CLI option names or aliases.
+ * @property {ArgMap | string[]} [prepend] - Arguments to prepend to process.argv.
+ * @property {ArgMap | string[]} [append] - Arguments to append to process.argv.
+ * @property {ArgMap} [default] - Default values for options.
+ * @property {boolean} [pure=false] - If true, do not modify process.argv.
+ */
+
+/**
+ * @typedef {object} ParseArgvResult
+ * @property {Record<string, string[]>} argv - Raw argument key/value map.
+ * @property {Record<string, string[]>} args - Camel-cased argument key/value map.
+ */
+
+/**
+ * Parses process.argv according to provided options, defaults, prepend/append arguments.
+ *
+ * @param {ParseArgvProps} props
+ * @returns {ParseArgvResult}
+ */
+export const parseArgv = (props = {}) => {
+  const { options = [], prepend = {}, append = {}, default: def = {}, pure = false } = props || {}
+
+  /** @type {string|undefined} */
+  let lastArg
+
+  /** @type {Record<string, string[]>} */
+  const argv = {}
+
+  const argvCopy = process.argv.slice()
+
+  // Handle prepend args first
+  if (prepend) {
+    if (is.array(prepend)) {
+      argvCopy.splice(2, 0, ...prepend.map(String))
+    } else {
+      Object.entries(prepend).forEach(([k, v]) => {
+        argv[k] = is.array(v) ? v.map(String) : [String(v)]
+        argvCopy.splice(2, 0, k, ...(is.array(v) ? v.map(String) : [String(v)]))
+      })
+    }
+  }
+
+  // Append arguments will be added after existing args
+  if (append) {
+    if (is.array(append)) {
+      argvCopy.push(...append.map(String))
+    } else {
+      Object.entries(append).forEach(([k, v]) => {
+        argv[k] = is.array(v) ? v.map(String) : [String(v)]
+        argvCopy.push(k, ...(is.array(v) ? v.map(String) : [String(v)]))
+      })
+    }
+  }
+
+  // Parsing loop
+  argvCopy.forEach((arg, i) => {
+    if (i <= 1) return
+
+    if (arg.startsWith('-')) {
+      /** @type {string} */
+      let argvArg = ''
+      options.forEach(option => {
+        if (is.array(option)) {
+          if (option.some(opt => opt === arg)) {
+            argvArg = option[0]
+          }
+        } else if (option === arg) {
+          argvArg = option
+        }
+      })
+
+      if (argvArg) {
+        lastArg = argvArg
+        argv[lastArg] = argv[lastArg] || []
+        if (!pure) argvCopy[i] = lastArg
+      }
+    } else {
+      if (lastArg) argv[lastArg].push(arg)
+    }
+  })
+
+  const [argv1, argv2, ...argvRest] = argvCopy
+
+  const entries = Object.entries(def)
+
+  if (entries.length) {
+    entries.forEach(([k, v]) => {
+      if (!argv[k] || argv[k].length === 0) {
+        argv[k] = is.array(v) ? v.map(String) : [String(v)]
+        argvRest.push(k)
+        if (!is.array(v)) v = [v]
+        v.forEach(vv => argvRest.push(String(vv)))
+      }
+    })
+  }
+
+  if (!pure) {
+    process.argv = [argv1, argv2, ...argvRest]
+  }
+
+  /** @type {Record<string, string[]>} */
+  const args = {}
+
+  Object.entries(argv).forEach(([k, v]) => {
+    args[cases.camel(k)] = v
+  })
+
+  return {
+    argv,
+    args,
+  }
+}

package/src/parse/{clean.mjs → clean.js}

@@ -1,12 +1,25 @@
 import is from '@magic/types'
 import cases from '@magic/cases'
 
+/**
+ * @typedef {object} CleanProps
+ * @property {string[]} [single] - List of single-value argument keys to clean.
+ * @property {Record<string, any>} [default] - Default values for arguments.
+ */
+
+/**
+ * Cleans CLI parsed arguments for single-value keys, applying defaults.
+ *
+ * @param {import('../index.js').ParsedCLI} cli
+ * @param {CleanProps} [props={}]
+ * @returns {import('../index.js').ParsedCLI}
+ */
 export const clean = (cli, props = {}) => {
   if (is.empty(props.single)) {
     return cli
   }
 
-  props.single.map(s => {
+  props.single?.map(s => {
     const c = cases.camel(s)
     const def = props.default && (props.default[s] || props.default[c])
 

package/src/parse/{commands.mjs → commands.js}

@@ -1,6 +1,18 @@
 import log from '@magic/log'
 import is from '@magic/types'
 
+/**
+ * @typedef {object} ParseCommandsProps
+ * @property {Array<string|string[]>} [commands] - Commands or alias arrays to check.
+ * @property {boolean} [pure=false] - If true, do not modify process.argv.
+ */
+
+/**
+ * Parses CLI commands from process.argv.
+ *
+ * @param {ParseCommandsProps} props
+ * @returns {Record<string, boolean>} - Commands found in argv keyed by name.
+ */
 export const parseCommands = (props = {}) => {
   const { commands = [], pure = false } = props
   const { argv } = process
@@ -38,7 +50,7 @@ export const parseCommands = (props = {}) => {
         }
 
         if (idx > -1) {
-          if (!pure) {
+          if (!pure && !is.undefined(key)) {
             argv[idx] = key
           }
 
@@ -47,7 +59,7 @@ export const parseCommands = (props = {}) => {
           return [key, true]
         }
       })
-      .filter(a => a),
+      .filter(a => !is.undefined(a)),
   )
 
   return cmds

package/src/parse/env.js

@@ -0,0 +1,37 @@
+import is from '@magic/types'
+/**
+ * @typedef {[string|string[], string, string]} EnvTuple
+ *   Tuple of: [CLI switches], environment variable name, value].
+ *
+ * @typedef {object} ParseEnvProps
+ * @property {EnvTuple[]} env - Environment variables to parse.
+ * @property {boolean} [pure=false] - If true, do not modify process.env.
+ */
+
+/**
+ * Parses environment switches from process.argv.
+ *
+ * @param {ParseEnvProps} props
+ * @returns {Record<string, string>} - Environment variables set.
+ */
+export const parseEnv = ({ env = [], pure = false }) => {
+  /** @type {Record<string, string>} */
+  const environment = {}
+
+  // set env depending on env switches
+  env
+    .filter(([argv]) => {
+      if (!is.array(argv)) {
+        argv = [argv]
+      }
+      return argv.some(a => process.argv.includes(a))
+    })
+    .map(([_, key, val]) => {
+      environment[key] = val
+      if (!pure) {
+        process.env[key] = val
+      }
+    })
+
+  return environment
+}

package/src/parse/{index.mjs → index.js}

@@ -1,15 +1,21 @@
-import { parseEnv } from './env.mjs'
-import { parseArgv } from './argv.mjs'
-import { parseCommands } from './commands.mjs'
-import { parseRequired } from './required.mjs'
-import { clean } from './clean.mjs'
+import { parseEnv } from './env.js'
+import { parseArgv } from './argv.js'
+import { parseCommands } from './commands.js'
+import { parseRequired } from './required.js'
+import { clean } from './clean.js'
 
+/**
+ * Parses CLI arguments, commands, environment variables, and required options.
+ *
+ * @param {import('../index.js').ParseProps} props
+ * @returns {import('../index.js').ParsedCLI}
+ */
 export const parse = props => {
   const { pure = false } = props
 
   const { pureEnv = pure, pureArgv = pure, pureCommands = pure } = props
 
-  const env = parseEnv({ ...props, pure: pureEnv })
+  const env = parseEnv({ env: props.env || [], pure: pureEnv })
   const { argv, args } = parseArgv({ ...props, pure: pureArgv })
   const commands = parseCommands({ ...props, pure: pureCommands })