@magic/cli 0.0.46 → 0.0.47

package/src/parse/required.js

@@ -0,0 +1,56 @@
+import is from '@magic/types'
+
+/**
+ * @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
+ */
+
+/**
+ * @typedef {object} ParseRequiredArgs
+ * @property {ParsedCLI} [parsed]
+ * @property {object} [props]
+ * @property {Array<string|string[]> | string} [props.required]
+ */
+
+/**
+ * Validates that required CLI arguments exist.
+ *
+ * @param {ParseRequiredArgs} args
+ * @returns {Array<string|string[]>} - List of missing required arguments.
+ */
+export const parseRequired = (args = {}) => {
+  const { parsed, props } = args
+
+  if (is.empty(props?.required)) {
+    return []
+  }
+
+  /** @type {string[]} */
+  const errors = []
+
+  if (is.string(props?.required)) {
+    props.required = [props.required]
+  }
+
+  props?.required?.forEach(req => {
+    if (is.array(req)) {
+      const some = req.some(a => parsed?.argv[a])
+
+      if (!some) {
+        errors.push(...req)
+      }
+    } else {
+      const opt = parsed?.argv[req]
+
+      if (is.empty(opt)) {
+        errors.push(req)
+      }
+    }
+  })
+
+  return errors
+}

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

@@ -1,6 +1,14 @@
 import is from '@magic/types'
 import readline from 'readline'
-
+/**
+ * Prompts the user for input or confirmation.
+ * @param {string|string[]} [msg=''] - Message to display in the prompt.
+ * @param {object} [options={}] - Prompt options.
+ * @param {boolean} [options.yesNo=false] - Whether to treat the input as a yes/no confirmation.
+ * @param {boolean} [options.yesDefault=false] - If true, defaults to "yes" on empty input.
+ * @param {NodeJS.Process} [options.std=process] - Standard input/output streams.
+ * @returns {Promise<string|boolean>} Resolves with the user input (string) or boolean for yes/no prompts.
+ */
 export const prompt = (msg = '', options = {}) =>
   new Promise((resolve, reject) => {
     const { yesNo = false, std = process, yesDefault = false } = options
@@ -36,7 +44,8 @@ export const prompt = (msg = '', options = {}) =>
     rl.on('line', line => {
       if (yesNo) {
         const trimmed = line.trim().toLowerCase()
-        line = trimmed === 'y' || trimmed === 'yes' || yesDefault
+        resolve(trimmed === 'y' || trimmed === 'yes' || yesDefault)
+        return
       }
 
       resolve(line)

package/src/spawn.js

@@ -0,0 +1,20 @@
+import child_process from 'child_process'
+
+/**
+ * Spawns a new process.
+ * @param {string} cmd - Command to run.
+ * @param {string[]} [args=[]] - Arguments for the command.
+ * @param {import('child_process').SpawnOptions} [opt={}] - Spawn options.
+ * @returns {import('child_process').ChildProcess} The spawned process.
+ */
+export const spawn = (cmd, args = [], opt = {}) => {
+  /** @type {import('child_process').SpawnOptions} */
+  const opts = {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: 'inherit',
+    ...opt,
+  }
+
+  return child_process.spawn(cmd, args, opts)
+}

package/types/exec.d.ts

@@ -0,0 +1,6 @@
+export function exec(
+  cmd: string,
+  options?: {
+    stderrToStdout?: boolean | undefined
+  },
+): Promise<string>

package/types/execFile.d.ts

@@ -0,0 +1,5 @@
+export function execFile(
+  p: string,
+  args?: string[],
+  opts?: import('child_process').ExecFileOptions,
+): Promise<string | Buffer>

package/types/help/argToHelp.d.ts

@@ -0,0 +1,5 @@
+export function argToHelp(
+  arr: (string | string[])[],
+  help?: Record<string, string>,
+  defaults?: Record<string, any>,
+): string

package/types/help/envToHelp.d.ts

@@ -0,0 +1 @@
+export function envToHelp(env: Array<[string[], string, string]>): string

package/types/help/findLongestString.d.ts

@@ -0,0 +1 @@
+export function findLongestString(arr: Array<string | string[]>): string

package/types/help/index.d.ts

@@ -0,0 +1,67 @@
+export function maybeHelp(args: CLIArgs): string | false
+export type ParsedCLI = {
+  /**
+   * - Parsed CLI flags or arguments.
+   */
+  args?: Record<string, any> | undefined
+  /**
+   * - Parsed subcommands.
+   */
+  commands?: Record<string, any> | undefined
+  /**
+   * - Validation errors or missing required args.
+   */
+  errors?: (string | string[])[] | undefined
+}
+export type CLIHelpMeta = {
+  /**
+   * - CLI name shown in the help header.
+   */
+  name?: string | undefined
+  /**
+   * - General help text or description.
+   */
+  text?: string | undefined
+  /**
+   * - Example usage text or lines.
+   */
+  example?: string | string[] | undefined
+  /**
+   * - Help text for commands.
+   */
+  commands?: Record<string, string> | undefined
+  /**
+   * - Help text for options/flags.
+   */
+  options?: Record<string, string> | undefined
+  /**
+   * - Help text for environment variables.
+   */
+  env?: Record<string, string> | undefined
+}
+export type CLIArgs = {
+  /**
+   * - Parsed CLI data (from argument parser).
+   */
+  parsed?: ParsedCLI | undefined
+  /**
+   * - CLI commands or argument definitions.
+   */
+  commands?: (string | string[])[] | undefined
+  /**
+   * - CLI option/flag definitions.
+   */
+  options?: (string | string[])[] | undefined
+  /**
+   * - Environment variable mappings.
+   */
+  env?: [string[], string, string][] | undefined
+  /**
+   * - Default values for options or flags.
+   */
+  default?: Record<string, any> | undefined
+  /**
+   * - Help configuration or raw string help text.
+   */
+  help?: CLIHelpMeta | undefined
+}

package/types/index.d.ts

@@ -0,0 +1,36 @@
+export function cli(args?: { options?: (string | string[])[] | undefined }): object
+export namespace cli {
+  export { spawner as spawn }
+  export { execute as exec }
+  export { promptUser as prompt }
+  export { executeFile as execFile }
+}
+export const spawn: (
+  cmd: string,
+  args?: string[],
+  opt?: import('child_process').SpawnOptions,
+) => import('child_process').ChildProcess
+export const exec: (
+  cmd: string,
+  options?: {
+    stderrToStdout?: boolean | undefined
+  },
+) => Promise<string>
+export const prompt: (
+  msg?: string | string[],
+  options?: {
+    yesNo?: boolean | undefined
+    yesDefault?: boolean | undefined
+    std?: NodeJS.Process | undefined
+  },
+) => Promise<string | boolean>
+export const execFile: (
+  p: string,
+  args?: string[],
+  opts?: import('child_process').ExecFileOptions,
+) => Promise<string | Buffer>
+export default cli
+import { spawn as spawner } from './spawn.js'
+import { exec as execute } from './exec.js'
+import { prompt as promptUser } from './prompt.js'
+import { execFile as executeFile } from './execFile.js'

package/types/parse/argv.d.ts

@@ -0,0 +1,35 @@
+export function parseArgv(props?: ParseArgvProps): ParseArgvResult
+export type Option = string | string[]
+export type ArgMap = Record<string, string | string[]>
+export type ParseArgvProps = {
+  /**
+   * - CLI option names or aliases.
+   */
+  options?: Option[] | undefined
+  /**
+   * - Arguments to prepend to process.argv.
+   */
+  prepend?: string[] | ArgMap | undefined
+  /**
+   * - Arguments to append to process.argv.
+   */
+  append?: string[] | ArgMap | undefined
+  /**
+   * - Default values for options.
+   */
+  default?: ArgMap | undefined
+  /**
+   * - If true, do not modify process.argv.
+   */
+  pure?: boolean | undefined
+}
+export type ParseArgvResult = {
+  /**
+   * - Raw argument key/value map.
+   */
+  argv: Record<string, string[]>
+  /**
+   * - Camel-cased argument key/value map.
+   */
+  args: Record<string, string[]>
+}

package/types/parse/clean.d.ts

@@ -0,0 +1,14 @@
+export function clean(
+  cli: import('./index.js').ParsedCLI,
+  props?: CleanProps,
+): import('./index.js').ParsedCLI
+export type CleanProps = {
+  /**
+   * - List of single-value argument keys to clean.
+   */
+  single?: string[] | undefined
+  /**
+   * - Default values for arguments.
+   */
+  default?: Record<string, any> | undefined
+}

package/types/parse/commands.d.ts

@@ -0,0 +1,11 @@
+export function parseCommands(props?: ParseCommandsProps): Record<string, boolean>
+export type ParseCommandsProps = {
+  /**
+   * - Commands or alias arrays to check.
+   */
+  commands?: (string | string[])[] | undefined
+  /**
+   * - If true, do not modify process.argv.
+   */
+  pure?: boolean | undefined
+}

package/types/parse/env.d.ts

@@ -0,0 +1,15 @@
+export function parseEnv({ env, pure }: ParseEnvProps): Record<string, string>
+/**
+ * Tuple of: [CLI switches], environment variable name, value].
+ */
+export type EnvTuple = [string | string[], string, string]
+export type ParseEnvProps = {
+  /**
+   * - Environment variables to parse.
+   */
+  env: EnvTuple[]
+  /**
+   * - If true, do not modify process.env.
+   */
+  pure?: boolean | undefined
+}

package/types/parse/index.d.ts

@@ -0,0 +1,22 @@
+export function parse(props: ParseProps): ParsedCLI
+export type ParseProps = {
+  options?: (string | string[])[] | undefined
+  prepend?: any[] | Record<string, any> | undefined
+  append?: any[] | Record<string, any> | undefined
+  default?: Record<string, any> | undefined
+  pure?: boolean | undefined
+  pureEnv?: boolean | undefined
+  pureArgv?: boolean | undefined
+  pureCommands?: boolean | undefined
+  commands?: (string | string[])[] | undefined
+  env?: [string[], string, string][] | undefined
+  required?: (string | string[])[] | undefined
+  help?: object | undefined
+}
+export type ParsedCLI = {
+  env: Record<string, string>
+  argv: Record<string, any>
+  args: Record<string, any>
+  commands: Record<string, boolean>
+  errors: Array<string | string[]>
+}

package/types/parse/required.d.ts

@@ -0,0 +1,16 @@
+export function parseRequired(args?: ParseRequiredArgs): Array<string | string[]>
+export type ParsedCLI = {
+  env: Record<string, string>
+  argv: Record<string, any>
+  args: Record<string, any>
+  commands: Record<string, boolean>
+  errors: Array<string | string[]>
+}
+export type ParseRequiredArgs = {
+  parsed?: ParsedCLI | undefined
+  props?:
+    | {
+        required?: string | (string | string[])[] | undefined
+      }
+    | undefined
+}

package/types/prompt.d.ts

@@ -0,0 +1,8 @@
+export function prompt(
+  msg?: string | string[],
+  options?: {
+    yesNo?: boolean | undefined
+    yesDefault?: boolean | undefined
+    std?: NodeJS.Process | undefined
+  },
+): Promise<string | boolean>

package/types/spawn.d.ts

@@ -0,0 +1,5 @@
+export function spawn(
+  cmd: string,
+  args?: string[],
+  opt?: import('child_process').SpawnOptions,
+): import('child_process').ChildProcess

package/src/help/findLongestString.mjs

@@ -1,15 +0,0 @@
-import deep from '@magic/deep'
-
-export const findLongestString = arr => {
-  arr = deep.flatten(arr)
-
-  const sorted = arr.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.mjs

@@ -1,64 +0,0 @@
-import log from '@magic/log'
-import is from '@magic/types'
-
-import { envToHelp } from './envToHelp.mjs'
-import { argToHelp } from './argToHelp.mjs'
-
-export const maybeHelp = args => {
-  const { parsed } = args
-  const hasCommands = args.commands && Object.entries(args.commands).length > 0
-  const showCommandHelp = hasCommands && 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, help.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/parse/argv.mjs

@@ -1,118 +0,0 @@
-import is from '@magic/types'
-import cases from '@magic/cases'
-
-export const parseArgv = ({
-  options = [],
-  prepend = {},
-  append = {},
-  default: def = {},
-  pure = false,
-}) => {
-  let lastArg
-  const argv = {}
-  // map over argv, find arguments and values.
-  // arguments are all strings starting with a -,
-  // values are all strings between strings starting with a -.
-  process.argv.forEach((arg, i) => {
-    if (i <= 1) {
-      return arg
-    }
-
-    if (arg.startsWith('-')) {
-      // this is a key
-      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] = []
-        if (!pure) {
-          process.argv[i] = lastArg
-        }
-      }
-    } else {
-      // this is a value
-      if (lastArg) {
-        argv[lastArg].push(arg)
-      }
-    }
-  })
-
-  const [argv1, argv2, ...argvRest] = process.argv
-
-  const entries = Object.entries(def)
-
-  if (entries.length) {
-    entries.forEach(([k, v]) => {
-      if (is.empty(argv[k])) {
-        argv[k] = v
-
-        argvRest.push(k)
-        if (!is.array(v)) {
-          v = [v]
-        }
-        v.forEach(vv => argvRest.push(vv))
-      }
-    })
-  }
-
-  let argvPrepend = []
-  if (!is.array(prepend)) {
-    argvPrepend.push(prepend)
-  } else if (prepend.length) {
-    Object.entries(prepend).forEach(([k, v]) => {
-      argv[k] = v
-
-      argvPrepend.push(k)
-      if (!is.array(v)) {
-        argvPrepend.push(v)
-      } else {
-        argvPrepend = [...argvPrepend, ...v]
-      }
-    })
-  }
-
-  let argvAppend = []
-  if (!is.array(append)) {
-    argvAppend.push(append)
-  } else if (append.length) {
-    Object.entries(append)
-      .forEach(([k, v]) => {
-        argv[k] = v
-
-        argvAppend.push(k)
-        if (!is.array(v)) {
-          argvAppend.push(v)
-        } else {
-          argvAppend = [...argvAppend, ...v]
-        }
-      })
-      .filter(a => a)
-  }
-
-  if (!pure) {
-    const argvArgs = [argv1, argv2, ...argvAppend, ...argvRest, ...argvPrepend].filter(
-      a => a && a.length > 0,
-    )
-
-    process.argv = argvArgs
-  }
-
-  const args = {}
-
-  Object.entries(argv).map(([k, v]) => {
-    args[cases.camel(k)] = v
-  })
-
-  return {
-    argv,
-    args,
-  }
-}

package/src/parse/env.mjs

@@ -1,22 +0,0 @@
-import is from '@magic/types'
-
-export const parseEnv = ({ env = [], pure = false }) => {
-  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

@@ -1,29 +0,0 @@
-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'
-
-export const parse = props => {
-  const { pure = false } = props
-
-  const { pureEnv = pure, pureArgv = pure, pureCommands = pure } = props
-
-  const env = parseEnv({ ...props, pure: pureEnv })
-  const { argv, args } = parseArgv({ ...props, pure: pureArgv })
-  const commands = parseCommands({ ...props, pure: pureCommands })
-
-  const cli = {
-    env,
-    argv,
-    args,
-    commands,
-    errors: [],
-  }
-
-  const parsed = clean(cli, props)
-
-  parsed.errors = parseRequired({ props, parsed })
-
-  return parsed
-}

package/src/parse/required.mjs

@@ -1,32 +0,0 @@
-import is from '@magic/types'
-
-export const parseRequired = (args = {}) => {
-  const {
-    parsed,
-    props: { required },
-  } = args
-
-  if (is.empty(required)) {
-    return []
-  }
-
-  const errors = []
-
-  required.forEach(req => {
-    if (is.array(req)) {
-      const some = req.some(a => parsed.argv[a])
-
-      if (!some) {
-        errors.push(req)
-      }
-    } else {
-      const opt = parsed.argv[req]
-
-      if (is.empty(opt)) {
-        errors.push(req)
-      }
-    }
-  })
-
-  return errors
-}

package/src/spawn.mjs

@@ -1,12 +0,0 @@
-import child_process from 'child_process'
-
-export const spawn = (cmd, args = [], opt = {}) => {
-  const opts = {
-    cwd: process.cwd(),
-    env: process.env,
-    stdio: 'inherit',
-    ...opt,
-  }
-
-  return child_process.spawn(cmd, args, opts)
-}