@cloud-copilot/cli 0.1.1

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cloud Copilot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# CLI
+
+Utilities for standardizing working CLIs in Typescript.
+
+- Standardizes the way subcommands, arguments, and operands are parsed and validated
+- Includes "fuzzy matching" of subcommands and arguments, so users can provide partial names if they match only one subcommand or argument
+- Allows users to default arguments with environment variables
+- Automatically generates a help text for the user
+- Provides a type safe response of the parsed arguments
+- Has zero dependencies
+
+I wrote this because I'm building several CLI applications and want to have a standard parsing of arguments that users can rely on across all of them.
+
+I was inspired by https://github.com/lirantal/nodejs-cli-apps-best-practices and https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html to follow best practices for accepting arguments and environment variables while keeping my scope extremely limited and having no dependencies.
+
+## Example
+
+```typescript
+import {parseCliArguments} from '@cloud-copilot/cli';
+
+const parsedArguments = const parsed2 = parseArguments(
+  'my-command',
+  // optional subcommands
+  init: {
+    description: 'Initialize the project',
+    // Subcommand Specific Arguments
+    options: {
+      s3: {
+        description: 'Use S3 as the storage',
+        character: 's',
+        values: 'none'
+      },
+      language: {
+        description: 'The language to use',
+        values: 'single',
+        type: 'enum',
+        validValues: ['typescript', 'javascript']
+      }
+    }
+  },
+  download: {
+    description: 'Download a file',
+    // Subcommand Specific Arguments
+    options: {
+      url: {
+        description: 'The URL to download from',
+        values: 'single',
+        type: 'string'
+      }
+    }
+  },
+  // Global Arguments
+  {
+    regions: { type: 'string', values: 'multiple', description: 'Regions to deploy to' },
+    account: { type: 'string', values: 'single', description: 'AWS account to deploy to' },
+    ssl: { values: 'none', description: 'Enable SSL', character: 's', default: false },
+    port: { type: 'number', values: 'single', description: 'Port to use' },
+    points: { type: 'number', values: 'multiple', description: 'Data points' }
+  },
+  {}
+)
+```
+
+This will automatically pull in the arguments from the command line and validate them. If any arguments are not valid, it will throw an error with the message of what is wrong. If all arguments and subcommands are valid, it will return an object with a type safe response.
+
+```typescript
+parsedArguments.command // string | undefined
+parsedArguments.args.regions // string[]
+parsedArguments.args.account // string | undefined
+parsedArguments.args.ssl // boolean
+parsedArguments.args.port // number | undefined
+parsedArguments.args.points // number[]
+
+parsedArguments.anyValues // boolean, whether any values were provided on the CLI
+
+if (parsedArguments.command === 'init') {
+  // Type Checked command specific arguments
+  parsedArguments.args.s3 // boolean
+}
+```
+
+If the user provides `--help` a help message will be printed out with the available subcommands and arguments.
+
+## Installation
+
+```bash
+npm install @cloud-copilot/cli
+```
+
+## Parsing CLI Input
+
+Arguments are parsed into three things:
+
+```bash
+my-command [subcommand] [arguments] [--] [operands]
+```
+
+- The subcommand which is the first argument and is optional based on your configuration
+- The arguments that start with `--` (or optionally `-` for boolean flags) in the CLI
+- The operands, which are the remaining values after the arguments. If provided, all arguments after the literal `  --  ` are considered operands.
+
+### Parsing subcommands
+
+If you provide a list of subcommands, the first argument will be parsed as a subcommand if it does not start with a `-`. If the subcommand is not provided, it will be `undefined`.
+
+Partial matching will be used. If only one subcommand matches the string from the user input, the subcommand it matches will be returned. If more than one subcommand matches, an error will be thrown. If the string provided does not match any subcommand, an error will be thrown.
+
+### Parsing Arguments
+
+Arguments are parsed from the CLI input. They are generally parsed as `--name value` or `--name value1 value2 value3`. If the argument is a boolean flag, it can be provided as `--name` or `-n`. Arguments are case insensitive.
+
+#### Boolean Arguments
+
+Boolean values can be provided as `--name` or `-n`. If the argument is a boolean, the value will be `true` if the argument is provided and `false` if it is not. If an argument is passed to a boolean argument, an error will be thrown.
+
+Multiple single character boolean flags can be combined into a single argument. For example, `-abc` is equivalent to `-a -b -c`.
+
+#### String or Number Arguments
+
+String or number arguments can be provided as `--name value` or `--name value1 value2 value3`. If the argument is a single value, it will be parsed as a single value. If the argument is multiple values, it will be parsed as an array of strings or numbers.
+
+String or number arguments will throw an error if:
+
+- The flag is specified an no values are provided
+- The argument accepts only one value and multiple values are provided
+- The argument is a number and a non-number value is provided
+
+#### Enum Arguments
+
+Enum arguments can be provided as `--name value1 value2`. The values must be one of the values provided in the `values` field of the argument configuration. The values are returned as a string or a string array.
+
+Enum arguments will throw an error if:
+
+- The flag is specified an no values are provided
+- The argument accepts only one value and multiple values are provided
+- Any of the arguments provided are not in the list of allowed values.
+
+If the value is not one of the values provided, an error will be thrown.
+
+If a string or number argument is provided with no values an error will be thrown.
+
+### Operands
+
+Operands are the remaining values after the arguments.
+If there are no arguments, all strings after the subcommand (if any) are considered operands.
+If the last argument is a boolean all strings after the boolean are considered operands.
+If the last argument is a single value all the strings after the value for the argument are considered operands.
+If the last argument is multiple values, use `  --  ` to separate the arguments from the operands.
+
+### Environment Variables
+
+If an `environmentPrefix` is specified in `additionalArgs`, the library will look for environment variables that start with the prefix and use them as defaults for the arguments. For example, if the prefix is `MY_APP`, the library will look for environment variables like `MY_APP_REGIONS`, `MY_APP_ACCOUNT`, etc. These variables will be validated just like the CLI arguments. Any values provided on the CLI will override the environment variables.
+
+## Printing Help
+
+If the user provides `--help` as an argument the library will print out a help message with the available subcommands and arguments. This can also be done manually with the function `printHelpContents` which accepts the same arguments as `parseCliArguments`.
+
+```typescript
+//Given this config
+parseCliArguments(
+  'my-command',
+  // optional commands
+  [
+    { name: 'init', description: 'Initialize my environment' },
+    {
+      name: 'execute',
+      description: 'Run the download'
+    }
+  ],
+  {
+    expandAsterisk: {
+      character: 'e',
+      description: 'Expand a single wildcard asterisk (*) to all possible values',
+      values: 'none'
+    },
+    invalidActionBehavior: {
+      description: 'Behavior when an invalid action is encountered, defaults to remove',
+      validValues: ['remove', 'error', 'include'],
+      type: 'enum',
+      values: 'single'
+    },
+    readWaitMs: {
+      description: 'Milliseconds to wait between read operations',
+      type: 'number',
+      values: 'single'
+    }
+  },
+  {
+    operandsName: 'action'
+  }
+)
+```
+
+````
+
+```bash
+$ my-command --help
+Usage: my-command [command] [options] [flags] [--] [action1] [action2]
+Commands:
+  init   : Initialize my environment
+  execute: Run the download
+Options:
+  --expand-asterisk:         (-e) Expand a single wildcard asterisk (*) to all possible values.
+  --invalid-action-behavior:      Behavior when an invalid action is encountered, defaults to remove. Must
+                                  be one of: remove, error, include.
+  --read-wait-ms:                 Milliseconds to wait between read operations. One number required
+  --help:                         Print this help message and exit
+````
+
+## API
+
+`parseCliArguments` and `printHelpContents` are the two main functions for arguments and help text. They take the same arguments.
+
+- `commandName` - The name of the command. This is used in the help text.
+- `subcommands` - An object or sub commands that can be provided. The key is the name of the subcommand and the value is the configuration. Can be an empty object `{}`.
+  - `description` - The description of the subcommand. This is used in the help text.
+  - `options` - An object of argument definitions. The key is the name of the argument that will be returned in your results and the value is the configuration. Option objects are the same as described in `cliOptions`
+- `cliOptions` - An object of argument definitions. The key is the name of the argument that will be returned in your results and the value is the configuration. One of
+
+  - Standard Argument:
+
+    - `values` - The number of values the argument accepts. Can be `single` or `multiple`.
+    - `type` - The type of the argument. Can be `string` or `number`.
+    - `description` - The description of the argument. This is used in the help text.
+
+  - Enum Argument:
+
+    - `values` - The number of values the argument accepts. Can be `single` or `multiple`.
+    - `type` - The type of the argument. Must be `enum`.
+    - `validValues` - An array of valid values for the argument.
+    - `description` - The description of the argument. This is used in the help text.
+
+  - Boolean Argument:
+
+    - `character` - The single character flag for the argument.
+    - `values` - The number of values the argument accepts. Must be `none`.
+    - `description` - The description of the argument. This is used in the help text.
+
+- `additionalArgs` - An object of additional arguments. This can include:
+
+  - `version` - The version of the command. If this is provided the argument `--version` will print out the version and exit.
+  - `args` - Override the string array or arguments to parse, by default it will use `process.argv.slice(2)`.
+  - `env` - Override the environment variables to use, by default it will use `process.env`.
+  - `envPrefix` - A prefix to use for environment variables. If provided, the library will look for environment variables that start with the prefix and use them as defaults for the arguments. For example, if the prefix is `MY_APP`, the library will look for environment variables like `MY_APP_REGIONS`, `MY_APP_ACCOUNT`, etc. These variables will be validated just like the CLI arguments. Any values provided on the CLI will override the environment variables.
+  - `operandsName` - The name of the operands. This is used in the help text. By default, this is `operand`.
+  - `requireSubcommand` - If true, a subcommand is required. By default, this is false.
+
+## Reading from stdin
+
+The function `readStdin` can be used to read from stdin. It returns a promise that resolves with the string read from stdin.
+
+```typescript
+import { readStdin } from '@cloud-copilot/cli'
+
+const stdin = await readStdin(undefined)
+```
+
+It optionally takes a read timeout in milliseconds to wait to receive the first byte before it assumes there is no input. This is useful if for instance your CLI is being piped input from another process that may more than a few seconds, such as a `curl` command to an API.

package/dist/cjs/cli.d.ts

@@ -0,0 +1,140 @@
+/**
+ * A boolean argument that has no values.
+ */
+export type BooleanArgument = {
+    /**
+     * The single character flag for the argument.
+     */
+    character: string;
+    /**
+     * Must be 'none' for a boolean argument.
+     */
+    values: 'none';
+    /**
+     * The description of the argument.
+     */
+    description: string;
+};
+/**
+ * A standard argument that has one or more values.
+ */
+export type StandardArgument = {
+    /**
+     * Whether the argument accepts single or multiple values.
+     */
+    values: 'single' | 'multiple';
+    /**
+     * The type of the values accepted.
+     */
+    type: 'string' | 'number';
+    /**
+     * The description of the argument.
+     */
+    description: string;
+};
+export type EnumArgument = {
+    /**
+     * Whether the argument accepts single or multiple values.
+     */
+    values: 'single' | 'multiple';
+    /**
+     * Must be 'enum' for an enum argument.
+     */
+    type: 'enum';
+    /**
+     * The valid values for the argument.
+     */
+    validValues: string[];
+    /**
+     * The description of the argument.
+     */
+    description: string;
+};
+/**
+ * A CLI argument that can be accepted for a command.
+ */
+export type CliArgument = BooleanArgument | StandardArgument | EnumArgument;
+export type Command = {
+    description: string;
+    options: Record<string, CliArgument>;
+};
+export type OptionConfig = {
+    type: 'string' | 'number' | 'boolean';
+    values: 'single' | 'multiple';
+    description: string;
+    character?: string;
+};
+/**
+ * A map of CLI argument keys to their configuration.
+ */
+export type Config<T extends Record<string, CliArgument>> = T;
+/**
+ * Create a type safe configuration for CLI arguments.
+ *
+ * @param config the configuration for the CLI arguments.
+ * @returns the configuration object.
+ */
+export declare function createConfig<T extends Record<string, CliArgument>>(config: T): T;
+type ParsedArgs<T extends Record<string, CliArgument>> = {
+    [K in keyof T as K]: T[K] extends {
+        type: 'string';
+    } ? T[K]['values'] extends 'single' ? string | undefined : string[] : T[K] extends {
+        type: 'number';
+    } ? T[K]['values'] extends 'single' ? number | undefined : number[] : T[K] extends {
+        type: 'boolean';
+    } ? boolean : never;
+};
+/**
+ * Additional arguments that can be used to configure the CLI parser.
+ */
+export interface AdditionalCliArguments {
+    /**
+     * The version of the CLI command. If provided, the CLI provides a --version flag that prints the version and exits.
+     */
+    version?: string;
+    /**
+     * The argument string from the CLI. If not provided, the process.argv.slice(2) is used.
+     */
+    args?: string[];
+    /**
+     * The environment variables to use for parsing. If not provided, process.env is used.
+     */
+    env?: Record<string, string>;
+    /**
+     * The prefix to use for environment variables. If provided, the CLI will look for environment variables with the prefix followed by an underscore.
+     */
+    envPrefix?: string;
+    /**
+     * The name of the operands to display in the help message. Defaults to "operands".
+     */
+    operandsName?: string;
+    /**
+     * Whether a subcommand is required. If true, the CLI will exit with an error if no subcommand is provided.
+     */
+    requireSubcommand?: boolean;
+    /**
+     * If there are zero arguments, show the help message. Defaults to false.
+     */
+    showHelpIfNoArgs?: boolean;
+}
+export type SelectedCommandWithArgs<C extends Record<string, Command>, O extends Record<string, CliArgument>> = {
+    [K in keyof C]: {
+        command: K | undefined;
+        args: ParsedArgs<C[K]['options']> & ParsedArgs<O>;
+        operands: string[];
+        anyValues: boolean;
+    };
+}[keyof C];
+/**
+ * Parse CLI Arguments and return the parsed typesafe results.
+ *
+ * @param command the name of the command arguments are being parsed for.
+ * @param subcommands the list of subcommands that can be used, if any.
+ * @param cliOptions the configuration options for the CLI command.
+ * @param additionalArgs additional arguments to be used for parsing and displaying help.
+ * @returns the parsed arguments, operands, and subcommand if applicable.
+ */
+export declare function parseCliArguments<O extends Record<string, CliArgument>, C extends Record<string, Command>>(command: string, subcommands: C, cliOptions: Config<O>, additionalArgs?: AdditionalCliArguments): SelectedCommandWithArgs<C, O>;
+export declare function printHelpContents<O extends Record<string, CliArgument>, C extends Record<string, Command>>(command: string, subcommands: C, cliOptions: O, additionalArgs?: AdditionalCliArguments, selectedSubcommand?: string | undefined): void;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cjs/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}