@alcyone-labs/arg-parser 2.14.1 → 3.0.0-beta.1

package/README.md

@@ -1,153 +1,46 @@
-# ArgParser - Type-Safe Command Line Argument Parser
+# @alcyone-labs/arg-parser v3.0.0
 
-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)
-- [Documentation](#documentation)
-- [How to Run It](#how-to-run-it)
-- [OpenTUI: Reactive Rich Terminal Interfaces](#opentui-reactive-rich-terminal-interfaces)
-- [System Flags & Configuration](#system-flags--configuration)
-- [Links](#links)
-
-## Features Overview
-
-- **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.
-- **DXT Package Generation**: Generate complete, ready-to-install Claude Desktop Extension (`.dxt`) packages.
-- **Hierarchical Sub-commands**: Create complex, nested sub-command structures with flag inheritance.
-- **Configuration Management**: Easily load (`--s-with-env`) and save (`--s-save-to-env`) configurations.
-- **OpenTUI Framework** ⭐: A reactive TUI engine built on SolidJS with mouse support and themes.
+A robust, type-safe CLI argument parser with plugin support.
 
 ## Installation
 
 ```bash
-# Using PNPM (recommended)
-pnpm add @alcyone-labs/arg-parser
+npm install @alcyone-labs/arg-parser
 ```
 
-## Quick Start: The Unified `addTool` API
-
-The modern way to build with ArgParser is using the `.addTool()` method.
+## Quick Start
 
 ```typescript
-import { z } from "zod";
-import { ArgParser } from "@alcyone-labs/arg-parser";
+import { ArgParser } from '@alcyone-labs/arg-parser';
 
-const cli = ArgParser.withMcp({
-  appName: "My Awesome CLI",
-  appCommandName: "mycli",
-  description: "A tool that works in both CLI and MCP mode",
-  mcp: {
-    serverInfo: { name: "my-awesome-mcp-server", version: "1.0.0" },
-  },
-}).addTool({
-  name: "greet",
-  description: "A tool to greet someone",
-  flags: [{ name: "name", type: "string", mandatory: true, options: ["--name"] }],
+const parser = new ArgParser({
+  appName: 'my-cli',
   handler: async (ctx) => {
-    console.log(`Hey ${ctx.args.name}!`);
-    return { success: true, greeting: `Hey ${ctx.args.name}!` };
-  },
+    console.log('Hello', ctx.args.name);
+  }
 });
 
-await cli.parse();
-```
-
-## Documentation
-
-For detailed information, please refer to the following guides:
-
-- 📖 **[Core Concepts](./docs/CORE_CONCEPTS.md)**: Flag definitions, type handling, validation, and positional arguments.
-- 🤖 **[MCP & Claude Desktop Integration](./docs/MCP.md)**: Full guide on MCP servers, DXT bundling, and Claude integration.
-- 🖥️ **[OpenTUI Reference](./docs/TUI.md)**: Building rich terminal interfaces with SolidJS.
-- 📂 **[Working Directory Management](./docs/WORKING_DIRECTORY.md)**: Handling PWD and monorepos.
-- 🚀 **[Migration Guide (v1 to v2)](./docs/MIGRATION_V2.md)**: Moving to the unified `addTool` API.
-
-## How to Run It
-
-```bash
-# 1. As a standard CLI subcommand
-mycli greet --name Jane
-
-# 2. As an MCP server
-mycli --s-mcp-serve
-
-# 3. Generate a DXT package
-mycli --s-build-dxt ./my-dxt-package
+await parser.parse();
 ```
 
-## OpenTUI: Reactive Rich Terminal Interfaces
-
-ArgParser includes **OpenTUI v2**, a reactive TUI framework built on SolidJS.
-
-> 📖 **Full Documentation**: [docs/TUI.md](./docs/TUI.md) | [Component Reference](./docs/TUI_COMPONENTS.md)
+## Plugin System
 
-### Runtime Requirements
-
-> ⚠️ **Important**: OpenTUI requires **Bun** to run, not Node.js.
-
-When building TUI applications with OpenTUI, ensure your project uses Bun:
-
-```bash
-# Install dependencies with Bun
-bun install
-
-# Run your TUI application with Bun
-bun run src/index.ts
-```
-
-Node.js does not support OpenTUI's terminal rendering capabilities. Most CI environments and remote containers use Node.js by default - configure them to use Bun instead.
-
-### Quick TUI Example
+ArgParser v3.0.0 introduces a plugin architecture. Install plugins to add functionality:
 
 ```typescript
-import { createTuiApp } from "@alcyone-labs/arg-parser/tui";
-import { TuiProvider } from "@alcyone-labs/arg-parser/tui";
+import { ArgParser } from '@alcyone-labs/arg-parser';
+import { mcpPlugin } from '@alcyone-labs/arg-parser-mcp';
 
-function App() {
-  return (
-    <box border padding={2}>
-      <text>Hello from OpenTUI!</text>
-    </box>
-  );
-}
-
-createTuiApp(() => (
-  <TuiProvider theme="dark">
-    <App />
-  </TuiProvider>
-));
+const parser = new ArgParser({...})
+  .use(mcpPlugin({ serverInfo: { name: 'my-server', version: '1.0.0' } }));
 ```
 
-### Peer Dependencies
-
-When using OpenTUI features, install the peer dependencies:
-
-```bash
-bun add @opentui/core @opentui/solid solid-js
-```
-
-## System Flags & Configuration
-
-ArgParser includes built-in `--s-*` flags for development and debugging.
+### Available Plugins
 
-| Flag                     | Description                                              |
-| ------------------------ | -------------------------------------------------------- |
-| `--s-mcp-serve`          | Starts the application in MCP server mode.               |
-| `--s-build-dxt [dir]`    | Generates a DXT package for Claude Desktop.              |
-| `--s-with-env <file>`    | Loads configuration from a file (`.env`, `.json`, etc.). |
-| `--s-save-to-env <file>` | Saves current arguments to a configuration file.         |
-| `--s-debug`              | Prints a detailed log of the argument parsing process.   |
+- `@alcyone-labs/arg-parser-mcp` - MCP server functionality
+- `@alcyone-labs/arg-parser-dxt` - DXT package generation
+- `@alcyone-labs/arg-parser-tui` - Terminal UI with OpenTUI
 
-## Links
+## Migration from v2.x
 
-- 📜 **[Changelog](./CHANGELOG.md)**
-- 📋 **[Backlog](./BACKLOG.md)**
-- 💬 **[Discord Support](https://discord.gg/rRHhpz5nS5)**
+See the [Migration Guide](../../docs/MIGRATION_V3.md) for details on upgrading from v2.x to v3.0.0.

package/dist/config/plugins/index.d.ts

@@ -1,5 +1,37 @@
-export { type IConfigPlugin, ConfigPlugin, JsonConfigPlugin, EnvConfigPlugin, } from "./ConfigPlugin";
-export { ConfigPluginRegistry, globalConfigPluginRegistry, enableOptionalConfigPlugins, enableOptionalConfigPluginsAsync, enableConfigPlugins, } from "./ConfigPluginRegistry";
-export { TomlConfigPlugin, createTomlPlugin, createTomlPluginAsync } from "./TomlConfigPlugin";
-export { YamlConfigPlugin, createYamlPlugin, createYamlPluginAsync } from "./YamlConfigPlugin";
+/**
+ * Configuration plugin system
+ *
+ * Provides extensible configuration loading from various sources
+ * like JSON files, environment variables, YAML, and TOML.
+ */
+export interface IConfigPlugin {
+    name: string;
+    canLoad(source: string): boolean;
+    load(source: string): Promise<Record<string, any>> | Record<string, any>;
+}
+export declare abstract class ConfigPlugin implements IConfigPlugin {
+    abstract name: string;
+    abstract canLoad(source: string): boolean;
+    abstract load(source: string): Promise<Record<string, any>> | Record<string, any>;
+}
+export declare class JsonConfigPlugin extends ConfigPlugin {
+    name: string;
+    canLoad(source: string): boolean;
+    load(source: string): Record<string, any>;
+}
+export declare class EnvConfigPlugin extends ConfigPlugin {
+    name: string;
+    canLoad(source: string): boolean;
+    load(_source: string): Record<string, any>;
+}
+export declare class ConfigPluginRegistry {
+    private plugins;
+    register(plugin: IConfigPlugin): void;
+    get(name: string): IConfigPlugin | undefined;
+    findForSource(source: string): IConfigPlugin | undefined;
+}
+export declare const globalConfigPluginRegistry: ConfigPluginRegistry;
+export declare function enableOptionalConfigPlugins(): Promise<void>;
+export declare function enableOptionalConfigPluginsAsync(): Promise<void>;
+export declare function enableConfigPlugins(): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/config/plugins/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/plugins/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,YAAY,EACZ,gBAAgB,EAChB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC1E;AAGD,8BAAsB,YAAa,YAAW,aAAa;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IACzC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAClF;AAGD,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,IAAI,SAAU;IAEd,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIhC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAK1C;AAGD,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,IAAI,SAAS;IAEb,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIhC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAI3C;AAGD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAyC;IAExD,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAIrC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI5C,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;CAQzD;AAGD,eAAO,MAAM,0BAA0B,sBAA6B,CAAC;AAOrE,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAEjE;AAED,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}