cleye 2.4.0 → 2.6.0

package/README.md

@@ -342,6 +342,36 @@ const argv = cli({
 argv.flags.size // => "large" ("small" | "medium" | "large")
 ```
 
+#### Composable type helpers
+
+`cleye/formats` is a tree-shakable subpath that ships ready-made type-function helpers for common flag shapes. Import only what you need.
+
+```ts
+import {
+    oneOf, commaList, integer, float, range, url
+} from 'cleye/formats'
+
+cli({
+    flags: {
+        format: { type: oneOf('json', 'yaml', 'csv') }, // => 'json' | 'yaml' | 'csv'
+        tags: { type: commaList(String) }, // => string[]
+        port: { type: range(1024, 65_535) }, // => number, validated in range
+        count: { type: integer() }, // => number (integer only)
+        ratio: { type: float() }, // => number (finite float)
+        apiUrl: { type: url() } // => URL object
+    }
+})
+```
+
+| Helper | Return type | Description |
+|--------|-------------|-------------|
+| `oneOf(...values)` | Union of the given string literals | Throws if the value is not in the list. |
+| `commaList(itemType)` | `T[]` | Splits on `,`, trims whitespace, maps each item through `itemType`. |
+| `integer()` | `number` | Parses a base-10 integer. Throws on floats or non-numeric input. |
+| `float()` | `number` | Parses a finite float. Throws on non-finite or non-numeric input. |
+| `range(min, max)` | `(input: string) => number` | Returns a parser that validates the input parses to a number in `[min, max]`. |
+| `url()` | `URL` | Parses with `new URL()`. Returns a `URL` object so callers get `.host`, `.pathname`, etc. |
+
 #### Default flags
 By default, _Cleye_ will try to handle the `--help, -h` and `--version` flags.
 
@@ -366,6 +396,18 @@ $ my-script --version
 
 The version is also shown in the help documentation. To opt out of handling `--version` while still showing the version in `--help`, pass the version into `help.version`.
 
+> [!TIP]
+> Import `name`, `version`, and `description` directly from `package.json` to avoid keeping them in sync manually:
+> ```ts
+> import { name, version, description } from './package.json' with { type: 'json' }
+>
+> cli({
+>     name,
+>     version,
+>     help: { description }
+> })
+> ```
+
 #### Strict flags
 To reject unknown flags with an error, enable `strictFlags`:
 

package/dist/formats.cjs

@@ -0,0 +1 @@
+"use strict";var i=Object.defineProperty;var n=(r,e)=>i(r,"name",{value:e,configurable:!0});const s=n((...r)=>e=>{if(!r.includes(e))throw new Error(`Expected one of: ${r.join(", ")} (got: ${JSON.stringify(e)})`);return e},"oneOf"),c=n(r=>e=>e===""?[]:e.split(",").flatMap(o=>{const t=o.trim();return t===""?[]:[r(t)]}),"commaList"),f=n(()=>r=>{const e=Number(r);if(!Number.isInteger(e))throw new TypeError(`Expected an integer (got: ${JSON.stringify(r)})`);return e},"integer"),a=n(()=>r=>{const e=Number(r);if(!Number.isFinite(e))throw new TypeError(`Expected a finite number (got: ${JSON.stringify(r)})`);return e},"float"),g=n((r,e)=>o=>{const t=Number(o);if(!Number.isFinite(t))throw new TypeError(`Expected a number (got: ${JSON.stringify(o)})`);if(t<r||t>e)throw new Error(`Expected a number between ${r} and ${e} (got: ${t})`);return t},"range"),u=n(()=>r=>{try{return new URL(r)}catch{throw new Error(`Expected a valid URL (got: ${JSON.stringify(r)})`)}},"url");exports.commaList=c,exports.float=a,exports.integer=f,exports.oneOf=s,exports.range=g,exports.url=u;

package/dist/formats.d.cts

@@ -0,0 +1,8 @@
+declare const oneOf: <T extends string>(...values: T[]) => (input: string) => T;
+declare const commaList: <T>(itemType: (value: string) => T) => (input: string) => T[];
+declare const integer: () => (input: string) => number;
+declare const float: () => (input: string) => number;
+declare const range: (min: number, max: number) => (input: string) => number;
+declare const url: () => (input: string) => URL;
+
+export { commaList, float, integer, oneOf, range, url };

package/dist/formats.d.mts

@@ -0,0 +1,8 @@
+declare const oneOf: <T extends string>(...values: T[]) => (input: string) => T;
+declare const commaList: <T>(itemType: (value: string) => T) => (input: string) => T[];
+declare const integer: () => (input: string) => number;
+declare const float: () => (input: string) => number;
+declare const range: (min: number, max: number) => (input: string) => number;
+declare const url: () => (input: string) => URL;
+
+export { commaList, float, integer, oneOf, range, url };

package/dist/formats.mjs

@@ -0,0 +1 @@
+var i=Object.defineProperty;var n=(r,e)=>i(r,"name",{value:e,configurable:!0});const c=n((...r)=>e=>{if(!r.includes(e))throw new Error(`Expected one of: ${r.join(", ")} (got: ${JSON.stringify(e)})`);return e},"oneOf"),s=n(r=>e=>e===""?[]:e.split(",").flatMap(o=>{const t=o.trim();return t===""?[]:[r(t)]}),"commaList"),f=n(()=>r=>{const e=Number(r);if(!Number.isInteger(e))throw new TypeError(`Expected an integer (got: ${JSON.stringify(r)})`);return e},"integer"),g=n(()=>r=>{const e=Number(r);if(!Number.isFinite(e))throw new TypeError(`Expected a finite number (got: ${JSON.stringify(r)})`);return e},"float"),a=n((r,e)=>o=>{const t=Number(o);if(!Number.isFinite(t))throw new TypeError(`Expected a number (got: ${JSON.stringify(o)})`);if(t<r||t>e)throw new Error(`Expected a number between ${r} and ${e} (got: ${t})`);return t},"range"),u=n(()=>r=>{try{return new URL(r)}catch{throw new Error(`Expected a valid URL (got: ${JSON.stringify(r)})`)}},"url");export{s as commaList,g as float,f as integer,c as oneOf,a as range,u as url};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleye",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "The intuitive CLI development tool",
   "keywords": [
     "cli",
@@ -19,20 +19,34 @@
     "email": "hiroki.osame@gmail.com"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
   "exports": {
-    "require": {
-      "types": "./dist/index.d.cts",
-      "default": "./dist/index.cjs"
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
     },
-    "import": {
-      "types": "./dist/index.d.mts",
-      "default": "./dist/index.mjs"
+    "./formats": {
+      "require": {
+        "types": "./dist/formats.d.cts",
+        "default": "./dist/formats.cjs"
+      },
+      "import": {
+        "types": "./dist/formats.d.mts",
+        "default": "./dist/formats.mjs"
+      }
     }
   },
   "imports": {
@@ -40,6 +54,11 @@
       "types": "./src/index.ts",
       "development": "./src/index.ts",
       "default": "./dist/index.mjs"
+    },
+    "#cleye/formats": {
+      "types": "./src/formats.ts",
+      "development": "./src/formats.ts",
+      "default": "./dist/formats.mjs"
     }
   },
   "dependencies": {

package/skills/cleye/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: cleye
+description: cleye CLI development tool — argv parsing with typed parameters, flags, commands, and auto-generated help. Use when building Node.js CLI scripts with cleye or when the user imports `cli` or `command` from `cleye`.
+---
+
+# cleye
+
+## Quick Patterns
+
+| Task | Pattern |
+|------|---------|
+| Basic CLI | `cli({ name, parameters, flags })` |
+| Named command | `command({ name, parameters, flags }, callback)` |
+| Register commands | `cli({ commands: [cmd1, cmd2] })` |
+| Async callback | `await cli({ ... }, async (argv) => { ... })` |
+| Raw argv | `cli({ ... }, callback, process.argv.slice(2))` |
+
+## Parameters
+
+Positional arguments mapped to named properties on `argv._`.
+
+| Format | Description |
+|--------|-------------|
+| `<name>` | Required |
+| `[name]` | Optional |
+| `<name...>` | Required spread (1+) |
+| `[name...]` | Optional spread (0+) |
+| `--` | End-of-flags separator |
+
+```ts
+const argv = cli({
+    parameters: ['<required>', '[optional]', '[rest...]']
+})
+argv._.required // string
+argv._.optional // string | undefined
+argv._.rest // string[]
+argv._['--'] // string[] — everything after --
+```
+
+Multi-word names use camelCase on `argv._`: `'<first name>'` → `argv._.firstName`.
+
+## Flags
+
+```ts
+const argv = cli({
+    flags: {
+        verbose: Boolean, // shorthand
+        output: {
+            type: String,
+            alias: 'o',
+            default: 'dist',
+            description: 'Output directory',
+            placeholder: '<path>'
+        },
+        count: {
+            type: [Number], // array: -n 1 -n 2
+            alias: 'n'
+        }
+    }
+})
+
+argv.flags.verbose // boolean | undefined
+argv.flags.output // string
+argv.flags.count // number[]
+```
+
+Flag name is camelCase; parsed from kebab-case CLI input (`--output-dir` → `outputDir`).
+
+**Delimiters** — `=`, `:`, and `.` all work as value separators:
+
+```sh
+--flag=value   --flag:value   --flag.value
+```
+
+Use `:` when the value itself contains `=` (e.g. `--define:KEY=VALUE`).
+
+**Counting flags** — use `[Boolean]` and check `.length`:
+
+```ts
+cli({
+    flags: {
+        verbose: {
+            type: [Boolean],
+            alias: 'v'
+        }
+    }
+})
+// -vvv → argv.flags.verbose.length === 3
+```
+
+**Optional value** — custom type returns `true` when no value is given:
+
+```ts
+const OptionalString = (value: string) => value || true
+cli({ flags: { tag: OptionalString } })
+// --tag        → true
+// --tag beta   → 'beta'
+```
+
+## Boolean Flag Negation
+
+By default, set a boolean flag to `false` using the `=` operator:
+
+```sh
+--verbose=false   # → false
+--verbose false   # → true (false treated as separate argument)
+```
+
+To also support the `--no-<flag>` convention, enable `booleanFlagNegation` (additive — `=false` still works):
+
+```ts
+cli({
+    flags: { verbose: Boolean },
+    booleanFlagNegation: true
+})
+// --no-verbose     → false
+// --verbose=false  → false (still works)
+// Last-wins: --verbose --no-verbose → false
+```
+
+Commands inherit `booleanFlagNegation` from the parent `cli()` but can override it.
+
+## Strict Flags
+
+```ts
+cli({
+    flags: { foo: Boolean },
+    strictFlags: true
+})
+// --baz → Error: Unknown flag: --baz. (Did you mean --foo?)
+```
+
+Commands inherit `strictFlags` but can override it.
+
+## Commands
+
+```ts
+// install-command.ts
+export const installCommand = command({
+    name: 'install',
+    alias: ['i', 'add'],
+    parameters: ['<package name>'],
+    flags: { saveDev: Boolean }
+}, (argv) => {
+    argv._.packageName // string
+    argv.flags.saveDev // boolean | undefined
+})
+
+// main.ts
+cli({
+    name: 'npm',
+    version: '1.0.0',
+    commands: [installCommand]
+})
+```
+
+When a command is matched, `argv.command` narrows the type for type-safe branching.
+
+## Help & Version
+
+```ts
+cli({
+    name: 'my-script',
+    version: '1.2.3', // enables --version; also shown in --help
+    help: {
+        description: 'Does things',
+        usage: 'my-script [flags] <file>',
+        examples: ['my-script foo.txt', 'my-script --output=dist foo.txt'],
+        version: '1.2.3' // show version in --help without handling --version
+    }
+})
+// help: false  — disables --help handling; call argv.showHelp() manually
+```
+
+Tip: import `name`, `version`, and `description` from `package.json` to avoid keeping them in sync manually:
+
+```ts
+import { name, version, description } from './package.json' with { type: 'json' }
+
+cli({
+    name,
+    version,
+    help: { description }
+})
+```
+
+## Custom Flag Types
+
+Any function `(value: string) => T` works as a flag type — the return type is inferred.
+
+```ts
+// Validation + narrowing
+const Port = (value: string) => {
+    const n = Number(value)
+    if (!Number.isInteger(n) || n < 1 || n > 65_535) { throw new Error(`Invalid port: ${value}`) }
+    return n
+}
+// argv.flags.port → number
+
+// Enum
+const sizes = ['small', 'medium', 'large'] as const
+const Size = (v: string) => {
+    if (!(sizes as readonly string[]).includes(v)) { throw new Error(`Expected: ${sizes.join(', ')}`) }
+    return v as typeof sizes[number]
+}
+// argv.flags.size → 'small' | 'medium' | 'large'
+
+// Comma-separated list
+const List = (v: string) => v.split(',')
+// --tags a,b,c → argv.flags.tags === ['a', 'b', 'c']
+
+// Inline JSON
+cli({ flags: { data: JSON.parse } })
+// --data '{"key":1}' → argv.flags.data === { key: 1 }
+
+// Dot-nested object (combine with . delimiter)
+const Env = (v: string): Record<string, string | true> => {
+    const [k, value] = v.split('=')
+    return { [k]: value ?? true }
+}
+cli({ flags: { env: [Env] } })
+// --env.TOKEN=abc --env.CI → merge to { TOKEN: 'abc', CI: true }
+```
+
+## Type Helpers (`cleye/formats`)
+
+`cleye/formats` ships composable, tree-shakable type-function helpers. Import only what you need.
+
+```ts
+import {
+    oneOf, commaList, integer, float, range, url
+} from 'cleye/formats'
+```
+
+- `oneOf('a', 'b', 'c')` — infers `'a' | 'b' | 'c'`; throws if the value is not in the list.
+- `commaList(itemType)` — splits `"a,b,c"` → `T[]`; trims whitespace; composes with other helpers (e.g. `commaList(integer())`).
+- `integer()` — base-10 integer; throws on floats/non-numeric.
+- `float()` — finite float; throws on `Infinity`/non-numeric.
+- `range(min, max)` — returns `(input: string) => number`; validates input parses to a number in `[min, max]`.
+- `url()` — parses with `new URL()`; returns a `URL` object (not a string).
+
+## Help Customization
+
+```ts
+cli({
+    help: {
+        render(nodes, renderers) {
+            nodes.push('\nDocs: https://example.com')
+            renderers.flagOperator = () => '=' // --flag=<value>
+            return renderers.render(nodes)
+        }
+    }
+})
+```
+
+Default renderers: `/src/render-help/renderers.ts`.
+
+## ignoreArgv
+
+```ts
+cli({
+    ignoreArgv(type, flagOrArgv, value) {
+        if (type === 'unknown-flag') { return true } // silently skip unknown flags
+    }
+})
+```
+
+`type`: `'known-flag' | 'unknown-flag' | 'argument'`
+
+## Return Type
+
+```ts
+type ParsedArgv = {
+    _: string[] & Parameters
+    flags: { [name: string]: InferredType }
+    unknownFlags: { [name: string]: (string | boolean)[] }
+    showVersion: () => void
+    showHelp: (options?: HelpOptions) => void
+}
+```
+
+## TypeScript Exports
+
+```ts
+import type { Flags, Renderers, TypeFlag } from 'cleye'
+```
+
+| Type | Use |
+|------|-----|
+| `Flags` | Type for the `flags` option object |
+| `Renderers` | Help renderer class type for `help.render` customization |
+| `TypeFlag` | Re-export from `type-flag` for portable type declarations |