goke 6.5.0 → 6.5.1

package/README.md

@@ -25,6 +25,14 @@
 npm install goke
 ```
 
+## Install skill for AI agents
+
+```bash
+npx -y skills add remorses/goke
+```
+
+This installs the repository skill for AI coding agents. In this repo the shipped skill lives at `skills/goke/SKILL.md`.
+
 ## Usage
 
 ### Simple Parsing
@@ -390,6 +398,22 @@ cli
 
 Prefer injected `fs` for CLI storage instead of importing `node:fs/promises` directly inside actions. That keeps the command portable to JustBash and easier to test.
 
+### Path handling
+
+Use relative paths with injected `fs` for routine CLI storage paths. When a helper needs to resolve from the current directory, pass injected `process.cwd` into that helper and resolve from there.
+
+```ts
+await fs.mkdir('.mycli', { recursive: true })
+await fs.writeFile('.mycli/auth.json', json, 'utf8')
+console.log('running from', process.cwd)
+```
+
+Why this works:
+
+- In normal Node.js runs, relative paths resolve against the host cwd.
+- In JustBash runs, the same relative paths resolve against the sandbox cwd.
+- `process.cwd` mirrors that runtime-specific cwd in both environments.
+
 `goke` also exports the runtime types, so helper functions can use dependency injection without reaching for globals:
 
 ```ts
@@ -810,6 +834,78 @@ await bash.exec('parent child commandwithspaces --name Tommy')
 
 Prefer the injected `{ fs, console, process }` helpers in command implementations so the same command code works cleanly both in the regular CLI runtime and through the JustBash bridge. The injected `fs` defaults to Node `fs/promises`, and `process.cwd` / `process.env` / `process.stdin` reflect host values in Node but sandbox values inside `createJustBashCommand()`.
 
+### Test with real JustBash
+
+When a command reads or writes files, test it through real `just-bash` using the existing app CLI. Do not define the CLI inside the test body.
+
+```ts
+import { describe, expect, test } from 'vitest'
+import { Bash, InMemoryFs } from 'just-bash'
+import { cli } from '../src/cli'
+
+describe('login command', () => {
+  test('writes auth state through the sandbox fs', async () => {
+    const virtualFs = new InMemoryFs()
+    await virtualFs.mkdir('/project', { recursive: true })
+
+    const bash = new Bash({
+      fs: virtualFs,
+      cwd: '/project',
+      customCommands: [await cli.createJustBashCommand()],
+    })
+
+    const result = await bash.exec('parent login --token Tommy')
+
+    expect(result.stdout).toBe('saved credentials\n')
+    expect(await virtualFs.readFile('/project/.mycli/auth.json', 'utf8')).toBe(
+      '{"token":"Tommy","cwd":"/project"}',
+    )
+  })
+})
+```
+
+This is the recommended compatibility test whenever a CLI touches storage: run the same CLI once in normal tests and once through real `just-bash`.
+
+### Exposing your CLI as a skill
+
+If you build a CLI with goke, keep the skill minimal and point agents to the CLI help output. Put detailed usage in the CLI code and README, not in a duplicated skill file.
+
+````markdown
+<!-- skills/acme/SKILL.md -->
+---
+name: acme
+description: >
+  acme is a deployment CLI. Always run `acme --help` before using it
+  to discover available commands, options, and usage examples.
+---
+
+# acme
+
+Always run `acme --help` before using this CLI.
+For subcommand details: `acme <command> --help`
+````
+
+## Contributor Notes
+
+### Rules
+
+1. Use schema-based options for typed values.
+2. Do not repeat defaults in `.describe(...)` when using `.default()`.
+3. Do not manually type action callback arguments; let goke infer them.
+4. Prefer injected `{ fs, console, process }` over global `console`, `process.exit`, or direct `node:fs/promises` imports.
+5. Use implicit cwd with injected `fs` for CLI storage. When a helper needs current-cwd semantics, pass `process.cwd` from the injected context into that helper.
+6. Define the CLI in app code and import that same CLI in tests; do not construct a separate CLI inside compatibility tests.
+
+### Version
+
+Import `package.json` and use its version field so the CLI stays in sync automatically:
+
+```ts
+import pkg from './package.json' with { type: 'json' }
+
+cli.version(pkg.version)
+```
+
 ## References
 
 ### CLI Instance
@@ -867,6 +963,26 @@ Register a middleware function that runs before the matched command action. Midd
 
 Print the help message to stdout.
 
+#### cli.clone(options?)
+
+- Type: `(options?: GokeOptions) => Goke`
+
+Create a deep copy of the CLI instance with all commands, options, middleware, and event listeners. Override any `GokeOptions` (stdout, stderr, cwd, env, fs, argv, columns, exit) in the clone without affecting the original. Primarily useful in tests to run multiple isolated parses from the same CLI definition:
+
+```ts
+const cli = goke('mycli')
+cli.command('build', 'Build project').action((options, { console }) => {
+  console.log('building')
+})
+cli.help()
+
+// In tests: override streams without touching the original CLI
+const stdout = { write: vi.fn<(data: string) => void>() }
+const isolated = cli.clone({ stdout })
+isolated.parse(['node', 'mycli', 'build'])
+expect(stdout.write).toHaveBeenCalledWith('building\n')
+```
+
 #### cli.helpText()
 
 - Type: `() => string`
@@ -911,6 +1027,21 @@ Command callbacks receive positional args first, then parsed options, then an in
 
 - Type: `() => Command`
 
+#### command.hidden()
+
+- Type: `() => Command`
+
+Hide a command from the help output listing. The command still matches and runs when invoked directly — only the help display is suppressed. Useful for internal, deprecated, or experimental commands you don't want to advertise.
+
+```ts
+cli
+  .command('internal-reset', 'Reset internal state')
+  .hidden()
+  .action((options, { console }) => {
+    console.log('reset done')
+  })
+```
+
 #### command.example(example)
 
 - Type: `(example: CommandExample) => Command`
@@ -919,6 +1050,12 @@ Command callbacks receive positional args first, then parsed options, then an in
 
 - Type: `(text: string) => Command`
 
+#### command.helpText()
+
+- Type: `() => string`
+
+Return the formatted help string for this specific command without printing it. Useful for tests or embedding help text programmatically.
+
 ### Events
 
 Listen to commands:

package/dist/goke.js

@@ -9,7 +9,7 @@
  * - createConsole: factory for console-like objects from output streams
  * - 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 { createJustBashCommand as createJustBashCommandBridge } from './just-bash.js';

package/dist/picocolors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Vendored from picocolors by Alexey Raspopov (MIT license).
+ * Source: https://github.com/alexeyraspopov/picocolors/blob/main/picocolors.js
+ */
+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;
+}
+declare const createColors: (enabled?: boolean) => PicoColors;
+declare const pc: PicoColors;
+export { createColors };
+export type { PicoColors };
+export default pc;
+//# sourceMappingURL=picocolors.d.ts.map

package/dist/picocolors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"picocolors.d.ts","sourceRoot":"","sources":["../src/picocolors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAA;AAE3C,UAAU,UAAU;IAClB,gBAAgB,EAAE,OAAO,CAAA;IACzB,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,SAAS,CAAA;IACf,GAAG,EAAE,SAAS,CAAA;IACd,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,SAAS,CAAA;IACpB,OAAO,EAAE,SAAS,CAAA;IAClB,MAAM,EAAE,SAAS,CAAA;IACjB,aAAa,EAAE,SAAS,CAAA;IACxB,KAAK,EAAE,SAAS,CAAA;IAChB,GAAG,EAAE,SAAS,CAAA;IACd,KAAK,EAAE,SAAS,CAAA;IAChB,MAAM,EAAE,SAAS,CAAA;IACjB,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,SAAS,CAAA;IAClB,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,SAAS,CAAA;IAClB,KAAK,EAAE,SAAS,CAAA;IAChB,OAAO,EAAE,SAAS,CAAA;IAClB,QAAQ,EAAE,SAAS,CAAA;IACnB,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,SAAS,CAAA;IACpB,MAAM,EAAE,SAAS,CAAA;IACjB,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,SAAS,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;IACpB,WAAW,EAAE,SAAS,CAAA;IACtB,YAAY,EAAE,SAAS,CAAA;IACvB,UAAU,EAAE,SAAS,CAAA;IACrB,aAAa,EAAE,SAAS,CAAA;IACxB,UAAU,EAAE,SAAS,CAAA;IACrB,WAAW,EAAE,SAAS,CAAA;IACtB,aAAa,EAAE,SAAS,CAAA;IACxB,WAAW,EAAE,SAAS,CAAA;IACtB,aAAa,EAAE,SAAS,CAAA;IACxB,cAAc,EAAE,SAAS,CAAA;IACzB,YAAY,EAAE,SAAS,CAAA;IACvB,eAAe,EAAE,SAAS,CAAA;IAC1B,YAAY,EAAE,SAAS,CAAA;IACvB,aAAa,EAAE,SAAS,CAAA;CACzB;AAkCD,QAAA,MAAM,YAAY,GAAI,iBAA0B,KAAG,UA+ClD,CAAA;AAED,QAAA,MAAM,EAAE,YAAiB,CAAA;AAEzB,OAAO,EAAE,YAAY,EAAE,CAAA;AACvB,YAAY,EAAE,UAAU,EAAE,CAAA;AAC1B,eAAe,EAAE,CAAA"}

package/dist/picocolors.js

@@ -0,0 +1,78 @@
+/**
+ * Vendored from picocolors by Alexey Raspopov (MIT license).
+ * Source: https://github.com/alexeyraspopov/picocolors/blob/main/picocolors.js
+ */
+import { process } from '#runtime';
+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, close, replace, index) => {
+    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, close, replace = open) => (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) => {
+    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 default pc;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goke",
-  "version": "6.5.0",
+  "version": "6.5.1",
   "type": "module",
   "description": "Simple yet powerful framework for building command-line apps. Inspired by cac.",
   "repository": {
@@ -48,9 +48,7 @@
     "dist",
     "src"
   ],
-  "dependencies": {
-    "picocolors": "^1.1.1"
-  },
+  "dependencies": {},
   "author": "remorses, egoist <0x142857@gmail.com>",
   "license": "MIT",
   "devDependencies": {

package/src/goke.ts

@@ -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"

package/src/picocolors.ts

@@ -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