@alcyone-labs/arg-parser 2.3.0 → 2.4.0

package/README.md

@@ -1,12 +1,13 @@
 # ArgParser - Type-Safe Command Line Argument Parser
 
-A modern, type-safe command line argument parser with built-in MCP (Model Context Protocol) integration and automatic Claude Desktop Extension (DXT) generation.
+A modern, type-safe command line argument parser with built-in MCP (Model Context Protocol) integration, real-time MCP Resources, and automatic Claude Desktop Extension (DXT) generation.
 
 ## Table of Contents
 
 - [Features Overview](#features-overview)
 - [Installation](#installation)
 - [Quick Start: The Unified `addTool` API](#quick-start-the-unified-addtool-api)
+  - [MCP Tool Name Constraints](#mcp-tool-name-constraints)
 - [How to Run It](#how-to-run-it)
   - [Setting Up System-Wide CLI Access](#setting-up-system-wide-cli-access)
 - [Parsing Command-Line Arguments](#parsing-command-line-arguments)
@@ -20,6 +21,87 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
 - [Core Concepts](#core-concepts)
   - [Defining Flags](#defining-flags)
   - [Type Handling and Validation](#type-handling-and-validation)
+    - [Supported Type Formats](#supported-type-formats)
+    - [Runtime Type Validation](#runtime-type-validation)
+    - [Automatic Type Processing](#automatic-type-processing)
+    - [Async Custom Parser Support](#async-custom-parser-support)
+    - [Type Conversion Examples](#type-conversion-examples)
+  - [Hierarchical CLIs (Sub-Commands)](#hierarchical-clis-sub-commands)
+    - [MCP Exposure Control](#mcp-exposure-control)
+  - [Flag Inheritance (`inheritParentFlags`)](#flag-inheritance-inheritparentflags)
+- [MCP & Claude Desktop Integration](#mcp--claude-desktop-integration)
+  - [Output Schema Support](#output-schema-support)
+    - [Basic Usage](#basic-usage)
+    - [Predefined Schema Patterns](#predefined-schema-patterns)
+    - [Custom Zod Schemas](#custom-zod-schemas)
+    - [MCP Version Compatibility](#mcp-version-compatibility)
+    - [Automatic Error Handling](#automatic-error-handling)
+  - [Writing Effective MCP Tool Descriptions](#writing-effective-mcp-tool-descriptions)
+    - [Best Practices for Tool Descriptions](#best-practices-for-tool-descriptions)
+    - [Complete Example: Well-Documented Tool](#complete-example-well-documented-tool)
+    - [Parameter Description Guidelines](#parameter-description-guidelines)
+    - [Common Pitfalls to Avoid](#common-pitfalls-to-avoid)
+  - [Automatic MCP Server Mode (`--s-mcp-serve`)](#automatic-mcp-server-mode---s-mcp-serve)
+  - [MCP Transports](#mcp-transports)
+  - [MCP Logging Configuration](#mcp-logging-configuration)
+    - [Enhanced Logging (Recommended)](#enhanced-logging-recommended)
+    - [Simple Logging Configuration](#simple-logging-configuration)
+    - [Configuration Priority](#configuration-priority)
+    - [Configuration Merging](#configuration-merging)
+    - [Path Resolution Options](#path-resolution-options)
+  - [MCP Resources - Real-Time Data Feeds](#mcp-resources---real-time-data-feeds)
+    - [Basic Resource Setup](#basic-resource-setup)
+    - [URI Templates with Dynamic Parameters](#uri-templates-with-dynamic-parameters)
+    - [MCP Subscription Lifecycle](#mcp-subscription-lifecycle)
+    - [Usage Examples](#usage-examples)
+    - [Design Patterns](#design-patterns)
+  - [Automatic Console Safety](#automatic-console-safety)
+  - [Generating DXT Packages (`--s-build-dxt`)](#generating-dxt-packages---s-build-dxt)
+  - [Logo Configuration](#logo-configuration)
+    - [Supported Logo Sources](#supported-logo-sources)
+  - [Including Additional Files in DXT Packages](#including-additional-files-in-dxt-packages)
+    - [Include Options](#include-options)
+  - [How DXT Generation Works](#how-dxt-generation-works)
+  - [DXT Bundling Strategies](#dxt-bundling-strategies)
+    - [Standard Approach (Recommended for Most Projects)](#standard-approach-recommended-for-most-projects)
+    - [Native Dependencies Approach](#native-dependencies-approach)
+  - [Typical Errors](#typical-errors)
+- [System Flags & Configuration](#system-flags--configuration)
+- [Changelog](#changelog)
+  - [v2.4.0](#v240)
+  - [v2.3.0](#v230)
+  - [v2.2.1](#v221)
+  - [v2.2.0](#v220)
+  - [v2.1.1](#v211)
+  - [v2.1.0](#v210)
+  - [v2.0.0](#v200)
+  - [v1.3.0](#v130)
+  - [v1.2.0](#v120)
+  - [v1.1.0](#v110)
+- [Backlog](#backlog)
+  - [(known) Bugs / DX improvement points](#known-bugs--dx-improvement-points)
+
+- [Features Overview](#features-overview)
+- [Installation](#installation)
+- [Quick Start: The Unified `addTool` API](#quick-start-the-unified-addtool-api)
+- [How to Run It](#how-to-run-it)
+  - [Setting Up System-Wide CLI Access](#setting-up-system-wide-cli-access)
+- [Parsing Command-Line Arguments](#parsing-command-line-arguments)
+  - [Automatic Argument Detection](#automatic-argument-detection)
+  - [Cannonical Usage Pattern](#cannonical-usage-pattern)
+  - [Top-level await](#top-level-await)
+  - [Promise-based parsing](#promise-based-parsing)
+- [Migrating from v1.x to the v2.0 `addTool` API](#migrating-from-v1x-to-the-v20-addtool-api)
+  - [Before v2.0: Separate Definitions](#before-v20-separate-definitions)
+  - [After v2.0: The Unified `addTool()` Method](#after-v20-the-unified-addtool-method)
+- [Core Concepts](#core-concepts)
+  - [Defining Flags](#defining-flags)
+  - [Type Handling and Validation](#type-handling-and-validation)
+    - [Supported Type Formats](#supported-type-formats)
+    - [Runtime Type Validation](#runtime-type-validation)
+    - [Automatic Type Processing](#automatic-type-processing)
+    - [Async Custom Parser Support](#async-custom-parser-support)
+    - [Type Conversion Examples](#type-conversion-examples)
   - [Hierarchical CLIs (Sub-Commands)](#hierarchical-clis-sub-commands)
     - [MCP Exposure Control](#mcp-exposure-control)
   - [Flag Inheritance (`inheritParentFlags`)](#flag-inheritance-inheritparentflags)
@@ -38,12 +120,16 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
   - [Automatic MCP Server Mode (`--s-mcp-serve`)](#automatic-mcp-server-mode---s-mcp-serve)
   - [MCP Transports](#mcp-transports)
   - [MCP Log Path Configuration](#mcp-log-path-configuration)
+  - [MCP Resources - Real-Time Data Feeds](#mcp-resources---real-time-data-feeds) ⭐
   - [Automatic Console Safety](#automatic-console-safety)
   - [Generating DXT Packages (`--s-build-dxt`)](#generating-dxt-packages---s-build-dxt)
   - [Logo Configuration](#logo-configuration)
     - [Supported Logo Sources](#supported-logo-sources)
   - [How DXT Generation Works](#how-dxt-generation-works)
   - [DXT Bundling Strategies](#dxt-bundling-strategies)
+    - [Standard Approach (Recommended for Most Projects)](#standard-approach-recommended-for-most-projects)
+    - [Native Dependencies Approach](#native-dependencies-approach)
+- [Typical Errors](#typical-errors)
 - [System Flags & Configuration](#system-flags--configuration)
 - [Changelog](#changelog)
   - [v2.3.0](#v230)
@@ -63,6 +149,7 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
 - **Unified Tool Architecture**: Define tools once with `addTool()` and they automatically function as both CLI subcommands and MCP tools.
 - **Type-safe flag definitions** with full TypeScript support and autocompletion.
 - **Automatic MCP Integration**: Transform any CLI into a compliant MCP server with a single command (`--s-mcp-serve`).
+- **MCP Resources with Real-Time Feeds** ⭐: Create subscription-based data feeds with URI templates for live notifications to AI assistants.
 - **Console Safe**: `console.log` and other methods
   are automatically handled in MCP mode to prevent protocol contamination, requiring no changes to your code.
 - **DXT Package Generation**: Generate complete, ready-to-install Claude Desktop Extension (`.dxt`) packages with the `--s-build-dxt` command and `--s-with-node-modules` for platform-dependent builds.
@@ -157,6 +244,35 @@ main();
 export default cli;
 ```
 
+### MCP Tool Name Constraints
+
+When using `.addTool()` or `.addMcpTool()`, tool names are automatically sanitized for MCP compatibility. MCP tool names must follow the pattern `^[a-zA-Z0-9_-]{1,64}$` (only alphanumeric characters, underscores, and hyphens, with a maximum length of 64 characters).
+
+```typescript
+// These names will be automatically sanitized:
+cli.addTool({
+  name: "test.tool", // → "test_tool"
+  // ... rest of config
+});
+
+cli.addTool({
+  name: "my@tool", // → "my_tool"
+  // ... rest of config
+});
+
+cli.addTool({
+  name: "tool with spaces", // → "tool_with_spaces"
+  // ... rest of config
+});
+
+cli.addTool({
+  name: "very-long-tool-name-that-exceeds-the-64-character-limit-for-mcp", // → truncated to 64 chars
+  // ... rest of config
+});
+```
+
+The library will warn you when tool names are sanitized, but your tools will continue to work normally. For CLI usage, the original name is preserved as the subcommand name.
+
 ## How to Run It
 
 ```bash
@@ -288,7 +404,7 @@ const cli = ArgParser.withMcp({
   handler: async (ctx) => ({ success: true, data: ctx.args }),
 });
 
-// NEW: Call parse() without arguments
+// You can call parse() without arguments
 // Automatically detects Node.js environment and uses process.argv.slice(2)
 async function main() {
   try {
@@ -981,13 +1097,19 @@ my-cli-app --s-mcp-serve --s-mcp-transport sse --s-mcp-port 3001
 # Configure custom log file path for MCP server logs
 my-cli-app --s-mcp-serve --s-mcp-log-path ./custom-logs/mcp-server.log
 
-# Or configure log path programmatically in withMcp()
+# Or configure logging programmatically in withMcp()
 const cli = ArgParser.withMcp({
   appName: 'My CLI App',
   appCommandName: 'my-cli-app',
   mcp: {
     serverInfo: { name: 'my-server', version: '1.0.0' },
-    logPath: './my-logs/mcp-server.log'  // Programmatic log path
+    // NEW: Improved logging with level control
+    log: {
+      level: 'info',        // Captures info, warn, error
+      logToFile: './my-logs/mcp-server.log',
+      prefix: 'MyApp'
+    }
+    // LEGACY: logPath: './my-logs/mcp-server.log'  // Still works
   }
 });
 ```
@@ -1009,20 +1131,30 @@ my-tool --s-mcp-serve --s-mcp-transport sse --s-mcp-port 3000 --s-mcp-host 0.0.0
 # Custom log path via CLI flag (logs to specified file instead of ./logs/mcp.log)
 my-tool --s-mcp-serve --s-mcp-log-path /var/log/my-mcp-server.log
 
-# Custom log path via programmatic configuration
+# Improved logging via programmatic configuration
 const parser = ArgParser.withMcp({
   mcp: {
     serverInfo: { name: 'my-tool', version: '1.0.0' },
-    logPath: '/var/log/my-mcp-server.log'
+    log: {
+      level: 'debug',       // Capture all log levels
+      logToFile: '/var/log/my-mcp-server.log',
+      prefix: 'MyTool'
+    }
+    // LEGACY: logPath: '/var/log/my-mcp-server.log'  // Still works
   }
 });
 
-# Multiple transports and custom log path (configured via --s-mcp-serve system flag)
+# Multiple transports and improved logging (configured via --s-mcp-serve system flag)
 const cli = ArgParser.withMcp({
   appName: 'multi-tool',
   appCommandName: 'multi-tool',
   mcp: {
-    logPath: './logs/multi-tool-mcp.log',  // Custom log path
+    // NEW: improved logging configuration
+    log: {
+      level: 'info',
+      logToFile: './logs/multi-tool-mcp.log',
+      prefix: 'MultiTool'
+    },
     serverInfo: {
       name: 'multi-tool-mcp',
       version: '1.0.0'
@@ -1038,13 +1170,91 @@ const cli = ArgParser.withMcp({
 });
 ```
 
-### MCP Log Path Configuration
+### MCP Logging Configuration
+
+MCP server logging can be configured with McpLoggerOptions options using `@alcyone-labs/simple-mcp-logger`. You can control log levels, output destinations, and more.
+
+#### Enhanced Logging (Recommended)
+
+Use the new `log` property for comprehensive logging control:
+
+```typescript
+const parser = ArgParser.withMcp({
+  appName: "My MCP Server",
+  appCommandName: "my-mcp-server",
+  mcp: {
+    serverInfo: { name: "my-server", version: "1.0.0" },
+    log: {
+      level: "debug", // Captures debug, info, warn, error
+      logToFile: "./logs/comprehensive.log",
+      prefix: "MyServer",
+      mcpMode: true, // MCP compliant (default)
+    },
+  },
+});
+```
+
+**Available log levels**: `"debug"` | `"info"` | `"warn"` | `"error"` | `"silent"`
+
+**Type Safety**: The `McpLoggerOptions` type is provided for full TypeScript support and matches the interface from `@alcyone-labs/simple-mcp-logger`.
+
+#### Simple Logging Configuration
+
+For basic use cases, you can use a simple string path:
+
+```typescript
+const parser = ArgParser.withMcp({
+  mcp: {
+    serverInfo: { name: "my-server", version: "1.0.0" },
+    log: "./logs/simple.log", // Simple string path
+  },
+});
+```
+
+#### Configuration Priority
 
-MCP server logs can be configured through multiple methods with the following priority order:
+Logging configuration follows this priority order:
 
 1. **CLI Flag (Highest Priority)**: `--s-mcp-log-path <path>`
-2. **Programmatic Configuration**: `mcp.logPath` in `withMcp()`
-3. **Default Path (Fallback)**: `./logs/mcp.log`
+2. **Merging**: When both `mcp.log` and `mcp.logPath` are present:
+   - `mcp.log` provides logger options (level, prefix, mcpMode)
+   - `mcp.logPath` provides flexible path resolution (relativeTo, basePath)
+   - Path resolution: `mcp.logPath` > `mcp.log.logToFile`
+3. **Log Config Only**: `mcp.log` object or string in `withMcp()`
+4. **Legacy Log Path Only**: `mcp.logPath` in `withMcp()`
+5. **Default Path (Fallback)**: `./logs/mcp.log`
+
+#### Configuration Merging
+
+When both `log` and `logPath` are specified:
+
+```typescript
+const parser = ArgParser.withMcp({
+  mcp: {
+    serverInfo: { name: "my-server", version: "1.0.0" },
+    // log provides logger options (level, prefix, mcpMode)
+    log: {
+      level: "debug",
+      prefix: "MyServer",
+      mcpMode: true,
+      // logToFile can be omitted when using logPath
+    },
+    // logPath provides flexible path resolution
+    logPath: {
+      path: "./logs/app.log",
+      relativeTo: "entry", // "entry" | "cwd" | "absolute"
+      basePath: "/custom/base", // Optional custom base path
+    },
+  },
+});
+```
+
+**Merging behavior:**
+
+- `log` provides logger configuration (level, prefix, mcpMode)
+- `logPath` provides flexible path resolution with `relativeTo` options
+- If both specify a file path, `logPath` takes precedence for path resolution
+- This preserves the powerful `LogPath` features while using `McpLoggerOptions` for logger settings
 
 #### Path Resolution Options
 
@@ -1063,7 +1273,7 @@ const parser = ArgParser.withMcp({
   },
 });
 
-// Object configuration for advanced use cases
+// Object configuration for more granular use cases
 const parser = ArgParser.withMcp({
   // ... other config
   mcp: {
@@ -1082,6 +1292,143 @@ const parser = ArgParser.withMcp({
 
 The CLI flag always takes precedence, allowing users to override the developer's programmatic configuration when needed. By default, relative paths resolve relative to the application's entry point, making logs predictably located near DXT packages.
 
+### MCP Resources - Real-Time Data Feeds
+
+MCP Resources enable your CLI tools to provide **real-time, subscription-based data feeds** to AI assistants. Unlike tools (which are called once), resources can be subscribed to and provide live updates when data changes.
+
+**Key Benefits:**
+
+- **Real-time notifications**: AI assistants get notified when your data changes
+- **Flexible URI templates**: Support dynamic parameters like `data://alerts/aged/gte:{threshold}`
+- **Standard MCP pattern**: Full subscription lifecycle support
+- **Zero CLI impact**: Resources only work in MCP mode, CLI usage unchanged
+
+#### Basic Resource Setup
+
+```typescript
+const parser = ArgParser.withMcp({
+  appName: "Data Monitor",
+  appCommandName: "data-monitor",
+  mcp: {
+    serverInfo: { name: "data-monitor", version: "1.0.0" },
+  },
+}).addMcpResource({
+  name: "recent-data",
+  uriTemplate: "data://recent",
+  title: "Recent Data",
+  description: "Get the most recent data entries",
+  mimeType: "application/json",
+  handler: async (uri) => {
+    const recentData = await getRecentData();
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: JSON.stringify(recentData, null, 2),
+          mimeType: "application/json",
+        },
+      ],
+    };
+  },
+});
+```
+
+#### URI Templates with Dynamic Parameters
+
+Create flexible resources that accept parameters:
+
+```typescript
+.addMcpResource({
+  name: "aged-data-alert",
+  uriTemplate: "data://alerts/aged/gte:{threshold}",
+  title: "Aged Data Alert",
+  description: "Monitor data that has aged past a threshold (in milliseconds)",
+  handler: async (uri, { threshold }) => {
+    const thresholdMs = parseInt(threshold);
+    const agedData = await getDataOlderThan(new Date(Date.now() - thresholdMs));
+
+    return {
+      contents: [{
+        uri: uri.href,
+        text: JSON.stringify({
+          threshold_ms: thresholdMs,
+          query_time: new Date().toISOString(),
+          aged_data: agedData,
+          count: agedData.length
+        }, null, 2),
+        mimeType: "application/json"
+      }]
+    };
+  }
+});
+```
+
+#### MCP Subscription Lifecycle
+
+Resources support the full MCP subscription pattern:
+
+1. **Client subscribes**: `resources/subscribe` → `"data://alerts/aged/gte:10000"`
+2. **Server monitors**: Your application detects data changes
+3. **Server notifies**: `notifications/resources/updated` sent to subscribed clients
+4. **Client reads fresh data**: `resources/read` → `"data://alerts/aged/gte:10000"`
+5. **Client unsubscribes**: `resources/unsubscribe` when done
+
+#### Usage Examples
+
+**AI Assistant Integration:**
+
+```typescript
+// AI assistant can subscribe to real-time data
+await client.request("resources/subscribe", {
+  uri: "data://alerts/aged/gte:60000", // 1 minute threshold
+});
+
+// Handle notifications
+client.on("notifications/resources/updated", async (notification) => {
+  const response = await client.request("resources/read", {
+    uri: notification.uri,
+  });
+  console.log("Fresh data:", JSON.parse(response.contents[0].text));
+});
+```
+
+**Command Line Testing:**
+
+```bash
+# Start MCP server
+data-monitor --s-mcp-serve
+
+# Test resource (in another terminal)
+echo '{"jsonrpc":"2.0","id":1,"method":"resources/read","params":{"uri":"data://alerts/aged/gte:10000"}}' | data-monitor --s-mcp-serve
+```
+
+#### Design Patterns
+
+**Static Resources**: Use simple URIs for data that changes content but not structure
+
+```typescript
+uriTemplate: "logs://recent"; // Always available, content updates
+uriTemplate: "status://system"; // System status, updates in real-time
+```
+
+**Parameterized Resources**: Use URI templates for flexible filtering
+
+```typescript
+uriTemplate: "data://type/{type}"; // Filter by type
+uriTemplate: "alerts/{severity}/gte:{age}"; // Multiple parameters
+uriTemplate: "search/{query}/limit:{count}"; // Search with limits
+```
+
+**Time-Based Resources**: Perfect for monitoring and alerting
+
+```typescript
+uriTemplate: "events/since:{timestamp}"; // Events since timestamp
+uriTemplate: "metrics/aged/gte:{threshold}"; // Metrics past threshold
+uriTemplate: "logs/errors/last:{duration}"; // Recent errors
+```
+
+> **💡 Pro Tip**: Resources are perfect for monitoring, alerting, and real-time data feeds. They complement tools (one-time actions) by providing continuous data streams that AI assistants can subscribe to.
+
 ### Automatic Console Safety
 
 A major challenge in MCP is preventing `console.log` from corrupting the JSON-RPC communication over `STDOUT`. ArgParser solves this automatically.
@@ -1164,6 +1511,62 @@ logo: "https://example.com/logo.png"; // Downloaded automatically
 logo: "https://cdn.example.com/icon.svg";
 ```
 
+### Including Additional Files in DXT Packages
+
+You can include additional files and directories in your DXT package using the `dxt.include` configuration. This is useful for bundling database migrations, configuration files, assets, or any other files your MCP server needs at runtime.
+
+```typescript
+const cli = ArgParser.withMcp({
+  appName: "My CLI",
+  appCommandName: "mycli",
+  mcp: {
+    serverInfo: {
+      name: "my-mcp-server",
+      version: "1.0.0",
+      description: "My CLI as an MCP server",
+    },
+    dxt: {
+      include: [
+        "migrations", // Copy entire migrations folder
+        "config/production.json", // Copy specific file
+        { from: "assets/logo.png", to: "logo.png" }, // Copy and rename file
+        { from: "scripts", to: "bin" }, // Copy folder with new name
+      ],
+    },
+  },
+});
+```
+
+#### Include Options
+
+**Simple string paths** - Copy files/directories to the same relative location:
+
+```typescript
+include: [
+  "migrations", // Copies ./migrations/ to dxt/migrations/
+  "config/default.json", // Copies ./config/default.json to dxt/config/default.json
+];
+```
+
+**Object mapping** - Copy with custom destination paths:
+
+```typescript
+include: [
+  { from: "config/prod.json", to: "config.json" }, // Rename during copy
+  { from: "database/schema", to: "db/schema" }, // Copy to different path
+];
+```
+
+**Path Resolution**: All paths in the `from` field are resolved relative to your project root (where `package.json` and `tsconfig.json` are located).
+
+**Example Use Cases**:
+
+- Database migration files for initialization
+- Configuration templates or defaults
+- Static assets like images or documents
+- Scripts or utilities needed at runtime
+- Documentation or help files
+
 ### How DXT Generation Works
 
 When you run `--s-build-dxt`, ArgParser performs several steps to create a self-contained, autonomous package:
@@ -1284,6 +1687,22 @@ ArgParser includes built-in `--s-*` flags for development, debugging, and config
 
 ## Changelog
 
+### v2.4.0
+
+**Feat**
+
+- MCP client now supports initialization during the client 'initialize' call, which allows to do certain things such as establishing database connection or even running migrations
+- MCP client now sanitizes the method names to ensure spec-compliants MCP behavior, names that collision will be logged
+- There were some use-cases where the DXT bundling failed, this new release addresses all of them, namely:
+  1. Output structure will match that of the input so relative files (for example DB migrations) will work
+  2.
+- DXT bundling now supports including resources via options: `{dxt: {include: ['TSDown blob-like paths']}`
+- Logger was improved to support log level via `options:{ log: {} }` so you can set it to level: 'debug' and the MCP log will contain 100% of the console output, logPath setting was not impacted
+
+**Fixes and Changes**
+
+- Zod has been upgraded to V4 and no issue was identified (but @modelcontextprotocol/sdk had to be upgraded to V4 as well, which was more challenging).
+
 ### v2.3.0
 
 The DXT bundling is working pretty well now, and we have had a lot of success building, bundling and running various extensions. If you see issues, feel free to open an Issue on GitHub with details, or ask about it on [Alcyone Labs' Discord](https://discord.gg/rRHhpz5nS5)
@@ -1367,11 +1786,11 @@ Make sure to clearly identify if you need to include the node_modules or not. In
 - [x] Make it possible to pass a `--s-save-to-env /path/to/file` parameter that saves all the parameters to a file (works with Bash-style .env, JSON, YAML, TOML)
 - [x] Make it possible to pass a `--s-with-env /path/to/file` parameter that loads all the parameters from a file (works with Bash-style .env, JSON, YAML, TOML)
 - [x] Add support for async type function to enable more flexibility
+- [x] Upgrade to Zod/V4 (V4 does not support functions well, this will take more time, not a priority)
 - [ ] Add System flags to args.systemArgs
 - [ ] Improve flag options collision prevention
 - [ ] Add support for locales / translations
 - [ ] (potentially) add support for fully typed parsed output, this has proven very challenging
-- [ ] Upgrade to Zod/V4 (V4 does not support functions well, this will take more time, not a priority)
 
 ### (known) Bugs / DX improvement points