@avandar/acclimate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Avandar Labs
+
+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,289 @@
+# Acclimate
+
+A lightweight TypeScript framework for building type-safe command line
+interfaces.
+
+This library is not complete and is still missing a lot of functionality.
+We do not recommend this library be used in production.
+
+See the To Do section at the end for what is still missing.
+
+## Installation
+
+```bash
+npm install acclimate
+```
+
+## Quick start
+
+```ts
+import { Acclimate } from "acclimate";
+
+const cli = Acclimate.createCLI("demo-cli")
+  .description("A tiny demo CLI")
+  .action(() => {
+    console.log("Hello, world!");
+  });
+
+Acclimate.run(cli);
+```
+
+## API
+
+Public exports from `acclimate`:
+
+- `Acclimate`
+
+### `Acclimate`
+
+#### `Acclimate.createCLI(name)`
+
+Create a new CLI instance.
+
+```ts
+Acclimate.createCLI(name: string): IAcclimateCLI
+```
+
+#### `Acclimate.run(cli)`
+
+Run a CLI instance using `process.argv.slice(2)`.
+
+```ts
+Acclimate.run(cli: IAcclimateCLI): void
+```
+
+### `IAcclimateCLI` (CLI builder)
+
+`createCLI()` returns an immutable builder. Each method returns a new CLI
+instance with updated configuration.
+
+#### `cli.description(description)`
+
+```ts
+cli.description(description: string): IAcclimateCLI
+```
+
+#### `cli.action(action)`
+
+Set the function executed when the CLI matches (after parsing).
+
+```ts
+cli.action(
+  action: (args: FullCLIArgValues<...>) => void,
+): IAcclimateCLI
+```
+
+#### `cli.addPositionalArg(param)`
+
+Add a positional argument. Positional args are parsed in order.
+
+```ts
+cli.addPositionalArg(param: CLIPositionalParam): IAcclimateCLI
+```
+
+#### `cli.addOption(param)`
+
+Add an option local to this CLI level.
+
+```ts
+cli.addOption(param: CLIOptionParam): IAcclimateCLI
+```
+
+#### `cli.addGlobalOption(param)`
+
+Add an option that is available to this CLI and all sub-commands.
+
+```ts
+cli.addGlobalOption(param: CLIOptionParam): IAcclimateCLI
+```
+
+#### `cli.addCommand(commandName, commandCLI)`
+
+Add a sub-command (a nested CLI). If the first positional token matches a
+command name, parsing continues using that command's CLI.
+
+```ts
+cli.addCommand(
+  commandName: string,
+  commandCLI: IAcclimateCLI,
+): IAcclimateCLI
+```
+
+#### `cli.getCommandCLI(commandName)`
+
+Get a command CLI by name (throws if missing).
+
+```ts
+cli.getCommandCLI(commandName: string): IAcclimateCLI
+```
+
+### Param config types
+
+Acclimate uses config objects to describe positional args and options.
+
+- **Positional args**: `CLIPositionalParam`
+  - **name**: `string` (prefer `camelCase` to match runtime parsing)
+  - **type**: `"string" | "number" | "boolean"`
+  - **required**: `boolean`
+  - **description?**: `string`
+  - **defaultValue?**: depends on `type`
+  - **choices?**: allowed values list
+  - **parser?**: `(value: string) => value`
+  - **validator?**: `(value) => true | string`
+
+- **Options**: `CLIOptionParam`
+  - **name**: `--${string}` (example: `--dry-run`)
+  - **aliases?**: `readonly ("--x" | "-x")[]`
+  - **required**: `boolean`
+  - Same `type`, `defaultValue`, `choices`, `parser`, `validator` fields as a
+    positional arg
+
+### Parsing behavior (current)
+
+- **Positional args**: validated and parsed in order; extra positional args
+  throw an error.
+- **Options**: parsing starts at the first token that begins with `-`. Each
+  option consumes tokens until the next option; its raw value is the consumed
+  tokens joined with spaces.
+- **Option keys in `action(args)`**: option names are camel-cased, so
+  `--dry-run` becomes `dryRun`.
+- **Boolean flags**: `--flag` with no value parses as `true` (only the
+  literal string `false` parses as `false`).
+- **Errors**: missing required args/options (and invalid values) throw
+  `CLIError`.
+
+## Prerequisites
+
+- Node.js **18+**
+- npm (bundled with Node)
+
+## Project Layout
+
+- `src/` — framework source code.
+- `examples/` — small usage samples; `basic.ts` is runnable via `npm run demo`.
+- `tests/` — Vitest suite.
+- `dist/` — build output generated by `tsup`.
+
+## Setup
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+## Common Scripts
+
+- `npm run dev` — build in watch mode with tsup.
+- `npm run build` — produce CJS/ESM bundles and type declarations in `dist/`.
+- `npm run demo` — execute the `examples/basic.ts` sample with tsx.
+- `npm test` — run the Vitest suite once.
+- `npm run test:watch` — run tests in watch mode.
+- `npm run lint` / `npm run lint:fix` — check or auto-fix with ESLint.
+- `npm run format` / `npm run format:fix` — check or write Prettier
+  formatting.
+- `npm run type` - check typescript types
+
+## Running & Testing
+
+1. Start a build (optional during development):
+
+```bash
+npm run dev
+```
+
+1. Run the sample CLI:
+
+```bash
+npm run demo
+```
+
+1. Execute tests:
+
+```bash
+npm test
+```
+
+The `prepare` script runs `npm run build`, so the package will compile
+automatically when installed from a git dependency.
+
+## Examples
+
+### Hello world
+
+Matches `examples/basic.ts`.
+
+```ts
+import { Acclimate } from "acclimate";
+
+const cli = Acclimate.createCLI("demo-cli").action(() => {
+  console.log("Hello, world!");
+});
+
+Acclimate.run(cli);
+```
+
+### Positional args + options
+
+```ts
+import { Acclimate } from "acclimate";
+
+const cli = Acclimate.createCLI("greet")
+  .addPositionalArg({
+    name: "name",
+    type: "string",
+    required: true,
+    description: "Who to greet",
+  })
+  .addOption({
+    name: "--shout",
+    type: "boolean",
+    required: false,
+    aliases: ["-s"] as const,
+    description: "Uppercase the output",
+    defaultValue: false,
+  })
+  .action(({ name, shout }) => {
+    const message = `Hello, ${name}!`;
+    console.log(shout ? message.toUpperCase() : message);
+  });
+
+Acclimate.run(cli);
+```
+
+### Sub-commands + global options
+
+```ts
+import { Acclimate } from "acclimate";
+
+const initCmd = Acclimate.createCLI("init")
+  .description("Initialize a project")
+  .action(({ verbose }) => {
+    console.log(`init (verbose=${verbose})`);
+  });
+
+const root = Acclimate.createCLI("acme")
+  .addGlobalOption({
+    name: "--verbose",
+    type: "boolean",
+    required: false,
+    aliases: ["-v"] as const,
+    defaultValue: false,
+  })
+  .addCommand("init", initCmd);
+
+Acclimate.run(root);
+```
+
+## To do
+
+- [ ] Add semantic arguments: e.g. email (which has a default validator)
+- [ ] Add default `help` command and `--help` option. This should show the CLI
+      description and all param documentation.
+- [ ] Make the `description` actually get printed.
+- [ ] Show all CLI param descriptions if command is run with no arguments or if
+      there is a param-related error.
+- [ ] Add helper functions to log to stdout in different colors
+- [ ] Add logic for `askIfEmpty` to enter an interactive mode to receive inputs
+      for different params.
+- [ ] Add an option to only `askIfEmptyAndRequired`.

package/dist/index.cjs

@@ -0,0 +1,381 @@
+'use strict';
+
+var changeCase = require('change-case');
+var tsPattern = require('ts-pattern');
+
+// src/CLIError.ts
+var CLIError = class _CLIError extends Error {
+  static invalidCLIParamValue(options) {
+    return new _CLIError({
+      message: options.message ?? `Invalid value for CLI param "${options.paramName}"`,
+      code: "invalid_cli_param_value",
+      details: { paramName: options.paramName, paramValue: options.paramValue }
+    });
+  }
+  static missingRequiredOption(options) {
+    return new _CLIError({
+      message: options.message ?? `Required option "${options.optionName}" is missing`,
+      code: "missing_required_option",
+      details: { optionName: options.optionName }
+    });
+  }
+  static missingRequiredPositionalArg(options) {
+    return new _CLIError({
+      message: options.message ?? `Required positional argument "${options.positionalArgName}" is missing`,
+      code: "missing_required_positional_arg",
+      details: { positionalArgName: options.positionalArgName }
+    });
+  }
+  static unknownOption(options) {
+    return new _CLIError({
+      message: options.message ?? `Option "${options.optionName}" not found`,
+      code: "unknown_option",
+      details: { optionName: options.optionName }
+    });
+  }
+  static tooManyPositionalArgs(options) {
+    return new _CLIError({
+      message: options.message ?? "Too many positional arguments provided.",
+      code: "too_many_positional_args",
+      details: { count: options.count }
+    });
+  }
+  static invalidPositionalArgConfig(options) {
+    return new _CLIError({
+      message: options.message ?? `Positional argument configuration for "${options.positionalArgName}" is invalid`,
+      code: "invalid_positional_arg_config",
+      details: { positionalArgName: options.positionalArgName }
+    });
+  }
+  static unknownCommand(options) {
+    return new _CLIError({
+      message: options.message ?? `Command "${options.commandName}" not found`,
+      code: "unknown_command",
+      details: { commandName: options.commandName }
+    });
+  }
+  static alreadyRun(options = {}) {
+    return new _CLIError({
+      message: options.message ?? "CLI has already been run",
+      code: "already_run",
+      details: void 0
+    });
+  }
+  constructor(options) {
+    super(`\u274C ${options.message}`);
+  }
+};
+
+// src/AcclimateCLI/AcclimateCLI.ts
+function AcclimateCLI(state) {
+  return {
+    state,
+    action: (action) => {
+      return AcclimateCLI({
+        ...state,
+        action
+      });
+    },
+    description: (description) => {
+      return AcclimateCLI({
+        ...state,
+        description
+      });
+    },
+    addPositionalArg: (param) => {
+      if (param.required && state.positionalArgs.some((p) => {
+        return !p.required;
+      })) {
+        throw CLIError.invalidPositionalArgConfig({
+          positionalArgName: param.name,
+          message: "Required positional arguments must be before optional positional arguments"
+        });
+      }
+      return AcclimateCLI({
+        ...state,
+        positionalArgs: [
+          ...state.positionalArgs,
+          { ...param, required: param.required ?? true }
+        ]
+      });
+    },
+    addGlobalOption: (param) => {
+      const newAliases = (param.aliases ?? []).reduce(
+        (acc, alias) => {
+          acc[alias] = param.name;
+          return acc;
+        },
+        {}
+      );
+      return AcclimateCLI({
+        ...state,
+        aliases: { ...state.aliases, ...newAliases },
+        globalOptionArgs: {
+          ...state.globalOptionArgs,
+          [param.name]: param
+        }
+      });
+    },
+    addOption: (param) => {
+      const newAliases = (param.aliases ?? []).reduce(
+        (acc, alias) => {
+          acc[alias] = param.name;
+          return acc;
+        },
+        {}
+      );
+      return AcclimateCLI({
+        ...state,
+        aliases: { ...state.aliases, ...newAliases },
+        optionArgs: { ...state.optionArgs, [param.name]: param }
+      });
+    },
+    addCommand: (commandName, cli) => {
+      return AcclimateCLI({
+        ...state,
+        commands: {
+          ...state.commands,
+          [commandName]: cli
+        }
+      });
+    },
+    getCommandCLI: (commandName) => {
+      const cmd = state.commands[commandName];
+      if (!cmd) {
+        throw CLIError.unknownCommand({
+          commandName,
+          message: `Command "${commandName}" not found`
+        });
+      }
+      return cmd;
+    }
+  };
+}
+
+// src/AcclimateCLI/createCLI/defaultCLIState.ts
+var defaultCLIState = {
+  aliases: {},
+  description: void 0,
+  commands: {},
+  positionalArgs: [],
+  optionArgs: {},
+  globalOptionArgs: {},
+  action: () => {
+  }
+};
+
+// src/AcclimateCLI/createCLI/createCLI.ts
+function createCLI(name) {
+  return AcclimateCLI({ ...defaultCLIState, name });
+}
+function _isValidFullOptionName(name) {
+  return name.startsWith("--");
+}
+function _isValidOptionAlias(name) {
+  return name.startsWith("-");
+}
+function isEmptyObject(obj) {
+  return Object.keys(obj).length === 0;
+}
+function _validateParsedValue(options) {
+  const { parsedValue, paramConfig } = options;
+  if (paramConfig.validator) {
+    const validator = paramConfig.validator;
+    const validationResult = validator(parsedValue);
+    if (validationResult === true) {
+      return parsedValue;
+    }
+    throw CLIError.invalidCLIParamValue({
+      paramName: paramConfig.name,
+      paramValue: parsedValue,
+      message: typeof validationResult === "string" ? validationResult : void 0
+    });
+  }
+  return parsedValue;
+}
+function _parseAndValidateValue(options) {
+  const { inputValue, defaultValue, paramConfig } = options;
+  if (inputValue === void 0) {
+    if (defaultValue === void 0) {
+      if (_isValidFullOptionName(paramConfig.name)) {
+        throw CLIError.missingRequiredOption({
+          optionName: paramConfig.name
+        });
+      } else {
+        throw CLIError.missingRequiredPositionalArg({
+          positionalArgName: paramConfig.name
+        });
+      }
+    }
+    return _validateParsedValue({
+      parsedValue: defaultValue,
+      paramConfig
+    });
+  }
+  const parsedValue = paramConfig.parser ? paramConfig.parser(inputValue) : tsPattern.match(paramConfig.type).with("boolean", () => {
+    return inputValue === "false" ? false : true;
+  }).with("number", () => {
+    return Number.parseInt(inputValue, 10);
+  }).with("string", () => {
+    return inputValue;
+  }).exhaustive(() => {
+    return inputValue;
+  });
+  return _validateParsedValue({
+    parsedValue,
+    paramConfig
+  });
+}
+function _replaceAliases({
+  aliasedOptionArgs,
+  cli
+}) {
+  const aliasMap = cli.state.aliases;
+  return Object.entries(aliasedOptionArgs).reduce(
+    (acc, [aliasKey, value]) => {
+      const alias = aliasKey;
+      const optionName = aliasMap[alias] ?? alias;
+      acc[optionName] = value;
+      return acc;
+    },
+    {}
+  );
+}
+function _runCLIHelper(options) {
+  const { rawGlobalOptionArgs, rawOptionArgs, rawPositionalArgs, cli } = {
+    ...options,
+    rawGlobalOptionArgs: _replaceAliases({
+      aliasedOptionArgs: options.rawGlobalOptionArgs,
+      cli: options.cli
+    }),
+    rawOptionArgs: _replaceAliases({
+      aliasedOptionArgs: options.rawOptionArgs,
+      // TODO(jpsyx): fix that this does not have the CLI may not have all
+      cli: options.cli
+    })
+  };
+  const firstArg = rawPositionalArgs[0];
+  if (firstArg && !isEmptyObject(cli.state.commands) && cli.state.commands[firstArg]) {
+    const commandCLI = Object.values(
+      cli.state.globalOptionArgs
+    ).reduce(
+      (newCmd, argConfig) => {
+        return newCmd.addGlobalOption(argConfig);
+      },
+      cli.getCommandCLI(firstArg)
+    );
+    return _runCLIHelper({
+      rawPositionalArgs: rawPositionalArgs.slice(1),
+      rawOptionArgs,
+      rawGlobalOptionArgs,
+      cli: commandCLI
+    });
+  }
+  if (rawPositionalArgs.length > cli.state.positionalArgs.length) {
+    throw CLIError.tooManyPositionalArgs({
+      count: rawPositionalArgs.length
+    });
+  }
+  const parsedPositionalArgs = cli.state.positionalArgs.reduce(
+    (acc, argConfig, idx) => {
+      const rawVal = rawPositionalArgs[idx];
+      if (argConfig.required && rawVal === void 0) {
+        throw CLIError.missingRequiredPositionalArg({
+          positionalArgName: argConfig.name
+        });
+      }
+      acc[argConfig.name] = _parseAndValidateValue({
+        inputValue: rawVal,
+        defaultValue: argConfig.defaultValue,
+        paramConfig: argConfig
+      });
+      return acc;
+    },
+    {}
+  );
+  const parsedOptionArgs = Object.values(
+    cli.state.optionArgs
+  ).reduce(
+    (acc, argConfig) => {
+      const rawVal = rawOptionArgs[argConfig.name];
+      if (argConfig.required && rawVal === void 0) {
+        throw CLIError.missingRequiredOption({
+          optionName: argConfig.name
+        });
+      }
+      acc[changeCase.camelCase(argConfig.name)] = _parseAndValidateValue({
+        inputValue: rawVal,
+        defaultValue: argConfig.defaultValue,
+        paramConfig: argConfig
+      });
+      return acc;
+    },
+    {}
+  );
+  const parsedGlobalOptionArgs = Object.values(
+    cli.state.globalOptionArgs
+  ).reduce(
+    (acc, argConfig) => {
+      const rawVal = rawGlobalOptionArgs[argConfig.name];
+      if (argConfig.required && rawVal === void 0) {
+        throw CLIError.missingRequiredOption({
+          optionName: argConfig.name
+        });
+      }
+      acc[changeCase.camelCase(argConfig.name)] = _parseAndValidateValue({
+        inputValue: rawVal,
+        defaultValue: argConfig.defaultValue,
+        paramConfig: argConfig
+      });
+      return acc;
+    },
+    {}
+  );
+  cli.state.action({
+    ...parsedPositionalArgs,
+    ...parsedOptionArgs,
+    ...parsedGlobalOptionArgs
+  });
+}
+function runCLI(options) {
+  const { input, cli } = options;
+  const firstOptionIdx = input.findIndex((token) => {
+    return token.startsWith("-");
+  });
+  const [rawPositionalArgs, rest] = firstOptionIdx === -1 ? [input, []] : [input.slice(0, firstOptionIdx), input.slice(firstOptionIdx)];
+  const rawOptionArgs = {};
+  const rawGlobalOptionArgs = {};
+  let currentAlias;
+  let currentVals = [];
+  const { aliases, globalOptionArgs } = cli.state;
+  for (const argVal of rest.concat("-")) {
+    if (_isValidOptionAlias(argVal)) {
+      if (currentAlias) {
+        const rawValue = currentVals.join(" ");
+        const optionName = aliases[currentAlias] ?? currentAlias;
+        if (_isValidFullOptionName(optionName) && !isEmptyObject(globalOptionArgs) && globalOptionArgs[optionName]) {
+          rawGlobalOptionArgs[optionName] = rawValue;
+        } else {
+          rawOptionArgs[optionName] = rawValue;
+        }
+      }
+      currentAlias = argVal;
+      currentVals = [];
+    } else {
+      currentVals.push(argVal);
+    }
+  }
+  _runCLIHelper({ rawPositionalArgs, rawOptionArgs, rawGlobalOptionArgs, cli });
+}
+
+// src/Acclimate.ts
+var Acclimate = {
+  createCLI,
+  run: (cli) => {
+    runCLI({ cli, input: process.argv.slice(2) });
+  }
+};
+
+exports.Acclimate = Acclimate;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map