npm - goke - Versions diffs - 6.5.0 → 6.5.2 - Mend

goke 6.5.0 → 6.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md +176 -9
package/dist/__test__/readme-examples.test.d.ts +5 -0
package/dist/__test__/readme-examples.test.d.ts.map +1 -0
package/dist/__test__/readme-examples.test.js +169 -0
package/dist/__test__/types.test-d.js +238 -1
package/dist/goke.d.ts +105 -16
package/dist/goke.d.ts.map +1 -1
package/dist/goke.js +22 -2
package/dist/picocolors.d.ts +55 -0
package/dist/picocolors.d.ts.map +1 -0
package/dist/picocolors.js +78 -0
package/dist/runtime-node.js +2 -2
package/package.json +3 -5
package/src/__test__/readme-examples.test.ts +225 -0
package/src/__test__/types.test-d.ts +262 -1
package/src/goke.ts +149 -16
package/src/picocolors.ts +140 -0
package/src/runtime-node.ts +2 -2

package/src/goke.ts CHANGED Viewed

@@ -10,7 +10,7 @@
  * - Utility functions: string helpers, bracket parsing, dot-prop access
  */
-import pc from 'picocolors'
+import pc from './picocolors.js'
 import mri from "./mri.js"
 import { GokeError, coerceBySchema, extractJsonSchema, extractSchemaMetadata, isStandardSchema } from "./coerce.js"
 import type { StandardJSONSchemaV1 } from "./coerce.js"
@@ -348,6 +348,92 @@ type OptionEntry<RawName extends string, Schema> =
     ? { [K in ExtractOptionName<RawName>]?: InferSchemaOutput<Schema> }
     : { [K in ExtractOptionName<RawName>]: InferSchemaOutput<Schema> }
+/**
+ * Infer the raw runtime value shape for an option declared without a schema.
+ *
+ * Required value options (`--port <port>`) always reach actions as strings.
+ * Optional value options (`--host [host]`) can be strings, the sentinel
+ * boolean `true` when passed without a value, or `undefined` when omitted.
+ * Plain flags (`--verbose`) are booleans.
+ */
+type UntypedOptionValue<RawName extends string> =
+  RawName extends `${string}<${string}>` ? string :
+  RawName extends `${string}[${string}]` ? string | boolean | undefined :
+  boolean | undefined
+/**
+ * Build the option type entry for a `.option()` call that uses a plain
+ * description (no schema).
+ */
+type UntypedOptionEntry<RawName extends string> =
+  RawName extends `${string}<${string}>`
+    ? { [K in ExtractOptionName<RawName>]: UntypedOptionValue<RawName> }
+    : { [K in ExtractOptionName<RawName>]?: UntypedOptionValue<RawName> }
+/**
+ * Tokenize a command raw name by splitting on whitespace.
+ * "mcp getNodeXml <id>" → ["mcp", "getNodeXml", "<id>"]
+ * "" → []
+ */
+type TokenizeName<S extends string, Acc extends readonly string[] = []> =
+  S extends `${infer Head} ${infer Rest}`
+    ? TokenizeName<Rest, [...Acc, Head]>
+    : S extends ''
+      ? Acc
+      : [...Acc, S]
+/**
+ * Given a single token, return the corresponding positional arg type or
+ * `never` if the token is not a bracketed arg.
+ *
+ * `<id>`       → string          (required)
+ * `[id]`       → string | undefined (optional)
+ * `<...files>` → string[]        (variadic required)
+ * `[...files]` → string[]        (variadic optional)
+ * Anything else → never (filtered out by ExtractCommandArgs)
+ */
+type TokenToArgType<T extends string> =
+  T extends `<...${string}>` ? string[] :
+  T extends `[...${string}]` ? string[] :
+  T extends `<${string}>` ? string :
+  T extends `[${string}]` ? string | undefined :
+  never
+/**
+ * Filter a tokenized command raw name down to the positional arg tokens
+ * and map each to its inferred type.
+ */
+type ExtractCommandArgs<T extends readonly string[]> =
+  T extends readonly [infer Head extends string, ...infer Tail extends string[]]
+    ? [TokenToArgType<Head>] extends [never]
+      ? ExtractCommandArgs<Tail>
+      : [TokenToArgType<Head>, ...ExtractCommandArgs<Tail>]
+    : []
+/**
+ * Extract the tuple of positional arg types from a command raw name.
+ *
+ * "mcp getNodeXml <id>"    → [string]
+ * "convert <input> <output>" → [string, string]
+ * "run [script]"           → [string | undefined]
+ * "exec [...args]"         → [string[]]
+ * "deploy"                 → []
+ */
+type ExtractPositionalArgs<RawName extends string> =
+  ExtractCommandArgs<TokenizeName<RawName>>
+/**
+ * Build the full argument tuple passed to a command's action callback.
+ *
+ * Format: [...positionalArgs, options, executionContext]
+ *
+ * This matches the runtime behavior in Goke.runMatchedCommand(): the action
+ * is called with positional args from the parsed command, then the parsed
+ * options object, then the injected GokeExecutionContext.
+ */
+type ActionArgs<RawName extends string, Opts> =
+  [...ExtractPositionalArgs<RawName>, Opts, GokeExecutionContext]
 interface CommandArg {
   required: boolean
   value: string
@@ -368,7 +454,7 @@ type HelpCallback = (sections: HelpSection[]) => void | HelpSection[]
 type CommandExample = ((bin: string) => string) | string
-class Command {
+class Command<RawName extends string = string, Opts = {}> {
   options: Option[]
   aliasNames: string[]
   /* Parsed command name */
@@ -383,7 +469,7 @@ class Command {
   _hidden?: boolean
   constructor(
-    public rawName: string,
+    public rawName: RawName,
     public description: string,
     public config: CommandConfig = {},
     public cli: Goke<any>
@@ -426,7 +512,9 @@ class Command {
    *
    * The second argument is either a description string or a StandardJSONSchemaV1
    * schema. When a schema is provided, description and default are extracted from
-   * the JSON Schema automatically.
+   * the JSON Schema automatically, and the option's type is tracked on the
+   * Command's `Opts` type parameter so that subsequent `.action()` callbacks
+   * receive a fully-typed options object.
    *
    * @example
    * ```ts
@@ -438,10 +526,16 @@ class Command {
    * ```
    */
   option<
-    RawName extends string,
+    OptionRawName extends string,
     S extends StandardJSONSchemaV1
-  >(rawName: RawName, schema: S): Command & { __opts: OptionEntry<RawName, S> }
-  option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): this
+  >(
+    rawName: OptionRawName,
+    schema: S,
+  ): Command<RawName, Opts & OptionEntry<OptionRawName, S>>
+  option<OptionRawName extends string>(
+    rawName: OptionRawName,
+    description?: string,
+  ): Command<RawName, Opts & UntypedOptionEntry<OptionRawName>>
   option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): any {
     const option = new Option(rawName, descriptionOrSchema)
     this.options.push(option)
@@ -458,7 +552,24 @@ class Command {
     return this
   }
-  action(callback: (...args: any[]) => any) {
+  /**
+   * Register the action callback that runs when this command is matched.
+   *
+   * The callback receives positional args extracted from the command's raw name,
+   * followed by the parsed options object and the injected GokeExecutionContext.
+   *
+   * Positional arg types are inferred from the raw name at the type level:
+   *   `command('convert <input> <output>')` → `(input: string, output: string, options, ctx)`
+   *   `command('run [script]')`              → `(script: string | undefined, options, ctx)`
+   *   `command('exec [...args]')`            → `(args: string[], options, ctx)`
+   *
+   * The options object is typed according to every `.option()` call chained
+   * on this command, plus any global options declared on the parent Goke
+   * instance before `.command()` was called.
+   */
+  action(
+    callback: (...args: ActionArgs<RawName, Opts>) => unknown | Promise<unknown>,
+  ): this {
     this.commandAction = callback
     return this
   }
@@ -919,14 +1030,14 @@ interface ParsedArgv {
   }
 }
-class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
+class Goke<Opts = {}> extends EventEmitter {
   /** The program name to display in help and version message */
   name: string
-  commands: Command[]
+  commands: Command<any, any>[]
   /** Middleware functions that run before the matched command action, in registration order */
   middlewares: Array<{ action: (options: any, context: GokeExecutionContext) => void | Promise<void> }>
   globalCommand: GlobalCommand
-  matchedCommand?: Command
+  matchedCommand?: Command<any, any>
   matchedCommandName?: string
   /**
    * Raw CLI arguments
@@ -1056,10 +1167,24 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
   }
   /**
-   * Add a sub-command
+   * Add a sub-command.
+   *
+   * The returned Command is parameterized by the literal `rawName` (so positional
+   * args can be inferred at the type level) and by this Goke's accumulated global
+   * `Opts` (so global options declared before `.command()` are visible inside
+   * `.action()` callbacks alongside the command's own options).
    */
-  command(rawName: string, description?: string, config?: CommandConfig) {
-    const command = new Command(rawName, description || '', config, this)
+  command<CommandRawName extends string>(
+    rawName: CommandRawName,
+    description?: string,
+    config?: CommandConfig,
+  ): Command<CommandRawName, Opts> {
+    const command = new Command<CommandRawName, Opts>(
+      rawName,
+      description || '',
+      config,
+      this,
+    )
     command.globalCommand = this.globalCommand
     this.commands.push(command)
     return command
@@ -1071,13 +1196,21 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
    * Which is also applied to sub-commands.
    *
    * When a StandardJSONSchemaV1 schema is provided, the return type is narrowed
-   * to include the inferred option type — enabling type-safe `.use()` callbacks.
+   * to include the inferred option type — enabling type-safe `.use()` callbacks
+   * and typed `options` params inside command `.action()` handlers.
+   *
+   * When a plain description string is provided, the option is still tracked on
+   * the Goke's `Opts` type, but with a loose `string | boolean | undefined` value
+   * type (since no coercion schema is available).
    */
   option<
     RawName extends string,
     S extends StandardJSONSchemaV1
   >(rawName: RawName, schema: S): Goke<Opts & OptionEntry<RawName, S>>
-  option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): this
+  option<RawName extends string>(
+    rawName: RawName,
+    description?: string,
+  ): Goke<Opts & UntypedOptionEntry<RawName>>
   option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): any {
     const option = new Option(rawName, descriptionOrSchema)
     this.globalCommand.options.push(option)

package/src/picocolors.ts ADDED Viewed

@@ -0,0 +1,140 @@
+/**
+ * Vendored from picocolors by Alexey Raspopov (MIT license).
+ * Source: https://github.com/alexeyraspopov/picocolors/blob/main/picocolors.js
+ */
+import { process } from '#runtime'
+type Formatter = (input: unknown) => string
+interface PicoColors {
+  isColorSupported: boolean
+  reset: Formatter
+  bold: Formatter
+  dim: Formatter
+  italic: Formatter
+  underline: Formatter
+  inverse: Formatter
+  hidden: Formatter
+  strikethrough: Formatter
+  black: Formatter
+  red: Formatter
+  green: Formatter
+  yellow: Formatter
+  blue: Formatter
+  magenta: Formatter
+  cyan: Formatter
+  white: Formatter
+  gray: Formatter
+  bgBlack: Formatter
+  bgRed: Formatter
+  bgGreen: Formatter
+  bgYellow: Formatter
+  bgBlue: Formatter
+  bgMagenta: Formatter
+  bgCyan: Formatter
+  bgWhite: Formatter
+  blackBright: Formatter
+  redBright: Formatter
+  greenBright: Formatter
+  yellowBright: Formatter
+  blueBright: Formatter
+  magentaBright: Formatter
+  cyanBright: Formatter
+  whiteBright: Formatter
+  bgBlackBright: Formatter
+  bgRedBright: Formatter
+  bgGreenBright: Formatter
+  bgYellowBright: Formatter
+  bgBlueBright: Formatter
+  bgMagentaBright: Formatter
+  bgCyanBright: Formatter
+  bgWhiteBright: Formatter
+}
+const argv = process.argv || []
+const env = process.env || {}
+const isColorSupported =
+  !(!!env.NO_COLOR || argv.includes('--no-color'))
+  && (
+    !!env.FORCE_COLOR
+    || argv.includes('--color')
+    || process.platform === 'win32'
+    || (process.stdout.isTTY && env.TERM !== 'dumb')
+    || !!env.CI
+  )
+const replaceClose = (string: string, close: string, replace: string, index: number) => {
+  let result = ''
+  let cursor = 0
+  do {
+    result += string.substring(cursor, index) + replace
+    cursor = index + close.length
+    index = string.indexOf(close, cursor)
+  } while (~index)
+  return result + string.substring(cursor)
+}
+const formatter = (open: string, close: string, replace = open): Formatter =>
+  (input) => {
+    const string = String(input)
+    const index = string.indexOf(close, open.length)
+    return ~index ? open + replaceClose(string, close, replace, index) + close : open + string + close
+  }
+const createColors = (enabled = isColorSupported): PicoColors => {
+  const f = enabled ? formatter : () => String
+  return {
+    isColorSupported: enabled,
+    reset: f('\x1b[0m', '\x1b[0m'),
+    bold: f('\x1b[1m', '\x1b[22m', '\x1b[22m\x1b[1m'),
+    dim: f('\x1b[2m', '\x1b[22m', '\x1b[22m\x1b[2m'),
+    italic: f('\x1b[3m', '\x1b[23m'),
+    underline: f('\x1b[4m', '\x1b[24m'),
+    inverse: f('\x1b[7m', '\x1b[27m'),
+    hidden: f('\x1b[8m', '\x1b[28m'),
+    strikethrough: f('\x1b[9m', '\x1b[29m'),
+    black: f('\x1b[30m', '\x1b[39m'),
+    red: f('\x1b[31m', '\x1b[39m'),
+    green: f('\x1b[32m', '\x1b[39m'),
+    yellow: f('\x1b[33m', '\x1b[39m'),
+    blue: f('\x1b[34m', '\x1b[39m'),
+    magenta: f('\x1b[35m', '\x1b[39m'),
+    cyan: f('\x1b[36m', '\x1b[39m'),
+    white: f('\x1b[37m', '\x1b[39m'),
+    gray: f('\x1b[90m', '\x1b[39m'),
+    bgBlack: f('\x1b[40m', '\x1b[49m'),
+    bgRed: f('\x1b[41m', '\x1b[49m'),
+    bgGreen: f('\x1b[42m', '\x1b[49m'),
+    bgYellow: f('\x1b[43m', '\x1b[49m'),
+    bgBlue: f('\x1b[44m', '\x1b[49m'),
+    bgMagenta: f('\x1b[45m', '\x1b[49m'),
+    bgCyan: f('\x1b[46m', '\x1b[49m'),
+    bgWhite: f('\x1b[47m', '\x1b[49m'),
+    blackBright: f('\x1b[90m', '\x1b[39m'),
+    redBright: f('\x1b[91m', '\x1b[39m'),
+    greenBright: f('\x1b[92m', '\x1b[39m'),
+    yellowBright: f('\x1b[93m', '\x1b[39m'),
+    blueBright: f('\x1b[94m', '\x1b[39m'),
+    magentaBright: f('\x1b[95m', '\x1b[39m'),
+    cyanBright: f('\x1b[96m', '\x1b[39m'),
+    whiteBright: f('\x1b[97m', '\x1b[39m'),
+    bgBlackBright: f('\x1b[100m', '\x1b[49m'),
+    bgRedBright: f('\x1b[101m', '\x1b[49m'),
+    bgGreenBright: f('\x1b[102m', '\x1b[49m'),
+    bgYellowBright: f('\x1b[103m', '\x1b[49m'),
+    bgBlueBright: f('\x1b[104m', '\x1b[49m'),
+    bgMagentaBright: f('\x1b[105m', '\x1b[49m'),
+    bgCyanBright: f('\x1b[106m', '\x1b[49m'),
+    bgWhiteBright: f('\x1b[107m', '\x1b[49m'),
+  }
+}
+const pc = createColors()
+export { createColors }
+export type { PicoColors }
+export default pc

package/src/runtime-node.ts CHANGED Viewed

@@ -12,7 +12,7 @@ const fs: GokeFs = nodeFs
 function openInBrowser(url: string): void {
   if (!process.stdout.isTTY) {
-    process.stderr.write(url + '\n')
+    process.stdout.write(url + '\n')
     return
   }
@@ -25,7 +25,7 @@ function openInBrowser(url: string): void {
       execSync(`xdg-open ${JSON.stringify(url)}`, { stdio: 'ignore' })
     }
   } catch {
-    process.stderr.write(url + '\n')
+    process.stdout.write(url + '\n')
   }
 }