@tkeron/commands 0.3.1 → 0.4.0

package/.github/workflows/npm_deploy.yml

@@ -4,21 +4,27 @@ on:
     branches:
       - main
 
+permissions:
+  id-token: write
+  contents: read
+
 jobs:
   build-test-publish:
     runs-on: ubuntu-latest
+
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4.0.3
+
+      - uses: actions/setup-node@v4
         with:
-          node-version: 20.x
-          registry-url: "https://registry.npmjs.org/"
+          node-version: 22.x
+          registry-url: "https://registry.npmjs.org"
 
       - uses: oven-sh/setup-bun@v2
 
-      - run: |
-          bun i
-          bun test
-          npm publish --access public
+      - run: bun i
+      - run: bun test
+
+      - run: npm publish --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/changelog.md

@@ -1,3 +1,19 @@
+# v0.4.0
+
+- add standard CLI syntax support (`--flag`, `-f`, `--opt value`, `--opt=value`)
+- add typed option definitions (`OptionDefinition`) with `boolean`, `string`, `number` types
+- add `addFlag()`, `addStringOption()`, `addNumberOption()` builder methods
+- add argument parser (`parseArgs`) with auto-detection of legacy/standard/mixed syntax
+- add default values via `applyDefaults()`
+- add option validation (`validateOptions`) with required, type, and allowed values checks
+- add combined short flags support (`-vw`)
+- add negated flags (`--no-verbose`)
+- add double-dash separator (`--`) to stop parsing
+- add option aliases support
+- maintain full backward compatibility with legacy `key=value` syntax
+- refactor `getStart` to use new parsing pipeline
+- update help text generation for typed options
+
 # v0.3.0
 
 - migrate project to bun

package/examples/example.ts

@@ -0,0 +1,116 @@
+import { getCommands } from "../src/index.js";
+import type { Commands } from "../src/types.js";
+
+const commands = getCommands("test program", "0.0.14")
+  .addCommand("com1")
+  .addAlias("c1")
+  .addOption("opt1")
+  .addOption("opt2")
+  .addDescription("command 001 test...")
+  .addPositionedArgument("pos0")
+  .addPositionedArgument("pos1")
+  .setCallback(console.log)
+
+  .commands()
+
+  .addCommand("com2")
+  .addAlias("c2")
+  .addAlias("a2")
+  .addOption("opt1")
+  .addDescription("command 002 test...")
+  .setCallback(console.log)
+
+  .commands()
+
+  .addCommand("com3")
+  .addAlias("c3")
+  .addOption("opt1")
+  .addOption("opt2", "exOpt2...")
+  .addOption("opt3")
+  .addDescription("command 003 test...")
+  .addPositionedArgument("pos0")
+  .addPositionedArgument("pos1")
+  .addPositionedArgument("pos3")
+  .setCallback(console.log)
+
+  .commands()
+
+  .addHeaderText("header...\n\n")
+  .addFooterText("\n\nFooter...");
+
+commands.start([
+  "",
+  "",
+  ..."com1 pos0value  opt1=qw111erty pos1value opt2=as222d  asdasd"
+    .replace(/\s+/g, " ")
+    .split(" "),
+]);
+
+commands.start([
+  "",
+  "",
+  ..."a2 pos0value  opt1=qw111erty pos1value opt2=as222d  asdasd"
+    .replace(/\s+/g, " ")
+    .split(" "),
+]);
+
+commands.start([
+  "",
+  "",
+  ..."c3 pos0value  opt1=qw111erty pos1value opt2=as222d  asdasd"
+    .replace(/\s+/g, " ")
+    .split(" "),
+]);
+
+const standardCommands = getCommands("myapp", "1.0.0")
+  .addCommand("build")
+  .addAlias("b")
+  .addDescription("Build project")
+  .addFlag("verbose", "v", "Verbose output")
+  .addFlag("watch", "w", "Watch mode")
+  .addStringOption("output", "o", "Output directory", { default: "./dist" })
+  .addPositionedArgument("source")
+  .setCallback(console.log)
+
+  .commands()
+
+  .addCommand("serve")
+  .addAlias("s")
+  .addDescription("Start dev server")
+  .addNumberOption("port", "p", "Port number", { default: 3000 })
+  .addStringOption("host", "h", "Host", { default: "localhost" })
+  .addFlag("open", "o", "Open browser")
+  .setCallback(console.log)
+
+  .commands()
+
+  .addCommand("test")
+  .addAlias("t")
+  .addDescription("Run tests")
+  .addStringOption("filter", "f", "Test filter")
+  .addFlag("coverage", "c", "Coverage report")
+  .addNumberOption("timeout", undefined, "Timeout in ms", { default: 5000 })
+  .setCallback(console.log)
+
+  .commands()
+
+  .addHeaderText("MyApp CLI v1.0.0\n")
+  .addFooterText("\nFor more info: https://example.com");
+
+standardCommands.start(["", "", "build", "src", "--verbose", "-o", "build"]);
+
+standardCommands.start(["", "", "serve", "-p", "8080", "--open"]);
+
+standardCommands.start(["", "", "test", "--filter", "unit", "--coverage"]);
+
+standardCommands.start(["", "", "b", "-vw"]);
+
+standardCommands.start(["", "", "build", "src", "--verbose", "extra=legacy"]);
+
+declare global {
+  var commands: Commands;
+  var standardCommands: Commands;
+}
+
+globalThis.commands = commands;
+globalThis.standardCommands = standardCommands;

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@tkeron/commands",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "library for handling command line arguments",
   "main": "src/index.ts",
   "module": "src/index.ts",
   "type": "module",
   "author": "tkeron",
   "license": "MIT",
+  "scripts": {
+    "test": "bun test --concurrent"
+  },
   "devDependencies": {
-    "@types/bun": "^1.3.1"
+    "@types/bun": "^1.3.9"
   },
   "peerDependencies": {
     "typescript": "^5.9.3"
@@ -19,6 +22,9 @@
     "command-line",
     "arguments"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "url": "git@github.com:tkeron/commands.git"
   }

package/readme.md

@@ -1,3 +1,120 @@
-# Tkeron Commands
+# @tkeron/commands
 
-        Simple package to evaluate cli arguments, with minimun dependencies.
+Zero-dependency CLI command parser and router for Bun/Node.js.
+
+## Install
+
+```bash
+bun add @tkeron/commands
+```
+
+## Quick Start
+
+```typescript
+import { getCommands } from "@tkeron/commands";
+
+const cli = getCommands("myapp", "1.0.0")
+  .addCommand("build")
+  .addAlias("b")
+  .addDescription("Build the project")
+  .addFlag("verbose", "v", "Enable verbose output")
+  .addStringOption("output", "o", "Output directory", { default: "./dist" })
+  .addPositionedArgument("source")
+  .setCallback(console.log)
+
+  .commands()
+
+  .addCommand("serve")
+  .addAlias("s")
+  .addDescription("Start dev server")
+  .addNumberOption("port", "p", "Port number", { default: 3000 })
+  .addFlag("open", "o", "Open browser")
+  .setCallback(console.log)
+
+  .commands()
+
+  .addHeaderText("MyApp v1.0.0\n")
+  .addFooterText("\nDocs: https://example.com");
+
+cli.start();
+```
+
+Usage:
+
+```bash
+myapp build src --verbose -o dist
+myapp serve -p 8080 --open
+myapp help
+myapp version
+```
+
+## API
+
+### `getCommands(programName, version)`
+
+Creates a new `Commands` instance.
+
+### Commands
+
+| Method                 | Description                                       |
+| ---------------------- | ------------------------------------------------- |
+| `.addCommand(name)`    | Add a command, returns `CommandFactory`           |
+| `.addHeaderText(text)` | Set help header text                              |
+| `.addFooterText(text)` | Set help footer text                              |
+| `.start(argv?)`        | Parse and execute. Uses `process.argv` by default |
+
+### CommandFactory (chaining)
+
+| Method                                                      | Description                               |
+| ----------------------------------------------------------- | ----------------------------------------- |
+| `.addAlias(alias)`                                          | Add command alias                         |
+| `.addDescription(text)`                                     | Set command description                   |
+| `.addFlag(name, shortFlag?, description?)`                  | Add boolean flag (`--verbose`, `-v`)      |
+| `.addStringOption(name, shortFlag?, description?, config?)` | Add string option                         |
+| `.addNumberOption(name, shortFlag?, description?, config?)` | Add number option                         |
+| `.addOption(name, example?)`                                | Add legacy `key=value` option             |
+| `.addPositionedArgument(name)`                              | Add positional argument                   |
+| `.setCallback(fn)`                                          | Set command handler                       |
+| `.commands()`                                               | Return to `Commands` to add more commands |
+
+### Option Config
+
+`addStringOption` and `addNumberOption` accept an optional config object:
+
+```typescript
+{
+  default?: string | number | boolean;
+  required?: boolean;
+  aliases?: string[];
+  allowedValues?: (string | number)[];
+  valueName?: string;
+}
+```
+
+## Syntax Support
+
+Both syntaxes work and can be mixed:
+
+**Standard** (new):
+
+```bash
+myapp build --verbose --output dist
+myapp build -v -o dist
+myapp build -vw              # combined short flags
+myapp build --no-verbose     # negated flags
+myapp build -- --not-parsed  # stop parsing after --
+```
+
+**Legacy** (backward compatible):
+
+```bash
+myapp build output=dist format=json
+```
+
+## Built-in Commands
+
+`help` and `version` are added automatically.
+
+## License
+
+MIT

package/src/applyDefaults.ts

@@ -0,0 +1,20 @@
+import type { Command, ParsedOptions } from "./types.js";
+
+export const applyDefaults = (
+  parsed: ParsedOptions,
+  command: Command,
+): ParsedOptions => {
+  const result = { ...parsed };
+
+  if (!command.optionDefinitions || command.optionDefinitions.length === 0) {
+    return result;
+  }
+
+  for (const def of command.optionDefinitions) {
+    if (def.default !== undefined && result[def.name] === undefined) {
+      result[def.name] = def.default;
+    }
+  }
+
+  return result;
+};

package/src/getCommandsFuncs.ts

@@ -1,17 +1,18 @@
-import { getStart } from "./getStart";
-import { buildHelpText, getCommandText } from "./textFuncs";
+import { getStart } from "./getStart.js";
+import { buildHelpText, getCommandText } from "./textFuncs.js";
 import type {
   CommandFactory,
   Command,
   Commands,
   CommandsCollection,
   Callback,
-} from "./types";
-export * from "./types";
+  OptionDefinition,
+} from "./types.js";
+export * from "./types.js";
 
 export const getCommands = (
   programName: string = "program",
-  version: string = "0.0.1"
+  version: string = "0.0.1",
 ): Commands => {
   const commandsCollection: CommandsCollection = {};
 
@@ -41,10 +42,13 @@ export const initCommands = (
     name: undefined,
     addAlias: undefined,
     addOption: undefined,
+    addFlag: undefined,
+    addStringOption: undefined,
+    addNumberOption: undefined,
     addPositionedArgument: undefined,
     addDescription: undefined,
     setCallback: undefined,
-  })
+  }),
 ): Commands => {
   if (!commandFactory.commands) commandFactory.commands = () => commands;
   commands.addCommand = getAddCommand(commandsCollection, commandFactory);
@@ -57,15 +61,15 @@ export const initCommands = (
 
 export const initHelpAndVersion = (
   commands: Commands,
-  commandsCollection: CommandsCollection
+  commandsCollection: CommandsCollection,
 ) => {
   const helpCallback = () =>
-    console["log"](buildHelpText(commands, commandsCollection));
+    console.log(buildHelpText(commands, commandsCollection));
   const versionCallback = () =>
-    console["log"](
+    console.log(
       `${commands.headerText || ""}\n${commands.version}\n${
         commands.footerText || ""
-      }\n`
+      }\n`,
     );
 
   commands
@@ -96,6 +100,7 @@ export const getAddCommand =
       options: [],
       optionsExamples: [],
       positionedArguments: [],
+      optionDefinitions: [],
       getHelpLine: undefined,
     });
     commandsCollection[commandName] = command;
@@ -103,17 +108,26 @@ export const getAddCommand =
 
     commandFactory.addAlias = getAddAlias(commandFactory, commandsCollection);
     commandFactory.addOption = getAddOption(commandFactory, commandsCollection);
+    commandFactory.addFlag = getAddFlag(commandFactory, commandsCollection);
+    commandFactory.addStringOption = getAddStringOption(
+      commandFactory,
+      commandsCollection,
+    );
+    commandFactory.addNumberOption = getAddNumberOption(
+      commandFactory,
+      commandsCollection,
+    );
     commandFactory.addDescription = getAddDescription(
       commandFactory,
-      commandsCollection
+      commandsCollection,
     );
     commandFactory.setCallback = getSetCallback(
       commandFactory,
-      commandsCollection
+      commandsCollection,
     );
     commandFactory.addPositionedArgument = getAddPositionedArgument(
       commandFactory,
-      commandsCollection
+      commandsCollection,
     );
 
     return commandFactory;
@@ -121,7 +135,7 @@ export const getAddCommand =
 
 export const getAddAlias = (
   commandFactory: CommandFactory,
-  commandsCollection: CommandsCollection
+  commandsCollection: CommandsCollection,
 ) => {
   return (alias: string) => {
     commandsCollection[commandFactory.name].aliases.push(alias);
@@ -133,22 +147,28 @@ export const getAddAlias = (
 
 export const getAddOption =
   (commandFactory: CommandFactory, commandsCollection: CommandsCollection) =>
-  (option: string, example?: string) => {
-    commandsCollection[commandFactory.name].options.push(option);
-    commandsCollection[commandFactory.name].optionsExamples.push(example || "");
+  (option: string | OptionDefinition, example?: string) => {
+    if (typeof option === "string") {
+      commandsCollection[commandFactory.name].options.push(option);
+      commandsCollection[commandFactory.name].optionsExamples.push(
+        example || "",
+      );
+    } else {
+      commandsCollection[commandFactory.name].optionDefinitions.push(option);
+    }
 
     return commandFactory;
   };
 
 export const getAddPositionedArgument = (
   commandFactory: CommandFactory,
-  commandsCollection: CommandsCollection
+  commandsCollection: CommandsCollection,
 ) => {
   return (arg: string): CommandFactory => {
     const positionedArguments =
       commandsCollection[commandFactory.name].positionedArguments;
 
-    if (!positionedArguments.includes(commandFactory.name)) {
+    if (!positionedArguments.includes(arg)) {
       positionedArguments.push(arg);
     }
 
@@ -158,7 +178,7 @@ export const getAddPositionedArgument = (
 
 export const getSetCallback = (
   commandFactory: CommandFactory,
-  commandsCollection: CommandsCollection
+  commandsCollection: CommandsCollection,
 ) => {
   return (fn: Callback): CommandFactory => {
     commandsCollection[commandFactory.name].callback = fn;
@@ -169,7 +189,7 @@ export const getSetCallback = (
 
 export const getAddDescription = (
   commandFactory: CommandFactory,
-  commandsCollection: CommandsCollection
+  commandsCollection: CommandsCollection,
 ) => {
   return (description: string) => {
     commandsCollection[commandFactory.name].description = description;
@@ -191,6 +211,57 @@ export const getAddFooterText = (commands: Commands) => {
   };
 };
 
+export const getAddFlag =
+  (commandFactory: CommandFactory, commandsCollection: CommandsCollection) =>
+  (name: string, shortFlag?: string, description?: string): CommandFactory => {
+    const def: OptionDefinition = {
+      name,
+      shortFlag,
+      type: "boolean",
+      description: description || "",
+    };
+    commandsCollection[commandFactory.name].optionDefinitions.push(def);
+    return commandFactory;
+  };
+
+export const getAddStringOption =
+  (commandFactory: CommandFactory, commandsCollection: CommandsCollection) =>
+  (
+    name: string,
+    shortFlag?: string,
+    description?: string,
+    config?: Partial<OptionDefinition>,
+  ): CommandFactory => {
+    const def: OptionDefinition = {
+      name,
+      shortFlag,
+      type: "string",
+      description: description || "",
+      ...config,
+    };
+    commandsCollection[commandFactory.name].optionDefinitions.push(def);
+    return commandFactory;
+  };
+
+export const getAddNumberOption =
+  (commandFactory: CommandFactory, commandsCollection: CommandsCollection) =>
+  (
+    name: string,
+    shortFlag?: string,
+    description?: string,
+    config?: Partial<OptionDefinition>,
+  ): CommandFactory => {
+    const def: OptionDefinition = {
+      name,
+      shortFlag,
+      type: "number",
+      description: description || "",
+      ...config,
+    };
+    commandsCollection[commandFactory.name].optionDefinitions.push(def);
+    return commandFactory;
+  };
+
 export const getGetHelpLine =
   (command: Command) =>
   (width: number = 50) => {

package/src/getStart.ts

@@ -1,10 +1,13 @@
-import type { CommandsCollection } from "./types";
+import type { CommandsCollection } from "./types.js";
+import { parseArgs } from "./parseArgs.js";
+import { applyDefaults } from "./applyDefaults.js";
+import { validateOptions } from "./validateOptions.js";
 
 export const getStart =
   (commandsCollection: CommandsCollection) => (argv?: string[]) => {
     if (!argv) argv = process.argv;
     if (!Array.isArray(argv)) throw new Error("no arguments passed");
-    if (argv.length < 2) throw Error("arguments out of range");
+    if (argv.length < 2) throw new Error("arguments out of range");
     argv = argv.slice(2);
     if (argv.length === 0) {
       commandsCollection.help.callback();
@@ -15,39 +18,31 @@ export const getStart =
 
     const command = commandsCollection[commandName];
     if (!command) {
-      console["log"](`command '${commandName}' not found`);
+      console.log(`command '${commandName}' not found`);
       return;
     }
 
-    const options = argv
-      .slice(1)
-      .filter((arg) => /\=/g.test(arg))
-      .map((arg) => arg.split("="))
-      .reduce((p: any, c) => {
-        p[c[0]] = c[1];
+    const parsedResult = parseArgs(argv.slice(1), command);
+    let options = parsedResult.options;
 
-        return p;
-      }, {});
+    options = applyDefaults(options, command);
 
-    const positionedArgsValues = argv
-      .slice(1)
-      .filter((arg) => !/\=/g.test(arg));
-
-    if (positionedArgsValues.length <= command.positionedArguments.length) {
-      positionedArgsValues.forEach(
-        (arg, n) => (options[command.positionedArguments[n]] = arg)
-      );
+    const validation = validateOptions(options, command);
+    if (!validation.valid) {
+      for (const error of validation.errors) {
+        console.log(error);
+      }
+      return;
     }
 
-    if (positionedArgsValues.length > command.positionedArguments.length) {
-      console["log"](
-        `argument${
-          positionedArgsValues.length - command.positionedArguments.length === 1
-            ? ""
-            : "s"
-        } '${positionedArgsValues
-          .slice(command.positionedArguments.length)
-          .join(", ")}' not defined`
+    const positionedOverflow = parsedResult.positional.filter(
+      (arg) =>
+        !command.positionedArguments.some((name) => options[name] === arg),
+    );
+
+    if (positionedOverflow.length > 0) {
+      console.log(
+        `argument${positionedOverflow.length === 1 ? "" : "s"} '${positionedOverflow.join(", ")}' not defined`,
       );
       return;
     }

package/src/index.ts

@@ -1 +1 @@
-export { getCommands } from "./getCommandsFuncs";
+export { getCommands } from "./getCommandsFuncs.js";