fix, feat, doc: massive build system refactorion, bug fixes and apex documentation (#19)

packages/cli/README.md

@@ -0,0 +1,105 @@
+# @ermnvldmr/cli
+
+An extensible, configuration-driven CLI toolkit designed specifically for the ermnvldmr monorepo. 
+
+## Overview
+
+The `@ermnvldmr/cli` package provides a unified way to declare, manage, and execute scripts across different packages and services in the monorepo. Instead of cluttering `package.json` with complex bash scripts or maintaining ad-hoc Node.js script files, developers can define their package's commands in a strongly-typed `.config/cli.ts` file.
+
+Under the hood, it uses [Commander.js](https://github.com/tj/commander.js) for argument parsing and [JITI](https://github.com/unjs/jiti) for seamless, dynamic TypeScript execution.
+
+## Features
+
+- **Centralized Configuration:** Define all commands in a single `.config/cli.ts` file per package.
+- **Type-Safe Builders:** Use `bashCommand` and `nodeCommand` builders to get strict TypeScript inference.
+- **Bash & Node Support:** Easily execute shell scripts (via `execa`) or arbitrary asynchronous Node.js functions.
+- **Commander Integration:** Automatically registers commands, descriptions, and arguments into a robust CLI interface.
+
+## Installation
+
+This package is intended to be used as a development dependency within the monorepo's workspace packages.
+
+```bash
+pnpm add -D @ermnvldmr/cli --workspace
+```
+
+## Usage
+
+### 1. Create a Configuration File
+
+Create a `.config/cli.ts` file in the root of your package/service (e.g., `packages/ui/.config/cli.ts`).
+
+```typescript
+import { defineCli, bashCommand, nodeCommand } from '@ermnvldmr/cli';
+
+export default defineCli({
+  commands: [
+    bashCommand({
+      name: 'hello',
+      description: 'Prints a hello message via bash',
+      script: 'echo "Hello from Bash!"'
+    }),
+    
+    nodeCommand({
+      name: 'build:custom',
+      description: 'Runs a custom node build step',
+      options: [
+        {
+          flags: '--minify',
+          description: 'Enable minification',
+          defaultValue: false
+        }
+      ],
+      action: async (options) => {
+        console.log('Building with node...');
+        if (options.minify) {
+          console.log('Minification enabled!');
+        }
+      }
+    })
+  ]
+});
+```
+
+### 2. Run the CLI
+
+You can invoke the CLI directly using `pnpm exec` from the package directory:
+
+```bash
+pnpm exec ermnvldmr-cli hello
+pnpm exec ermnvldmr-cli build:custom --minify
+```
+
+Alternatively, you can wire it into your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "cli": "ermnvldmr-cli",
+    "hello": "ermnvldmr-cli hello"
+  }
+}
+```
+
+## API Reference
+
+### `defineCli(config: CliConfig)`
+
+An identity helper function that provides strict TypeScript type-inference for your configuration object. It returns the configuration unmodified.
+
+### `bashCommand(config: Omit<BashCommandConfig, 'type'>)`
+
+A builder function for defining shell commands. 
+- **`script`**: The exact bash string to execute. It will be executed using `execa` with `shell: true` and `stdio: 'inherit'`.
+
+### `nodeCommand(config: Omit<NodeCommandConfig, 'type'>)`
+
+A builder function for defining arbitrary JavaScript/TypeScript actions.
+- **`action`**: An asynchronous function `(options: Record<string, unknown>) => Promise<void> | void` that executes when the command is invoked.
+
+## Development
+
+This package adheres to the global monorepo standards outlined in `GEMINI.md`:
+- **Strict TypeScript**: No `any` types are permitted.
+- **TSDoc**: All exported members must include comprehensive TSDoc comments.
+- **TDD**: Modifications and new builders should be accompanied by Vitest unit tests.