@alcyone-labs/arg-parser v3.0.0

A robust, type-safe CLI argument parser with plugin support.

[!IMPORTANT] ArgParser v3 is a breaking release. If you're upgrading from v2.x, start with the v2 → v3 migration guide.

🔄 Upgrading from v2.x

If you're coming from v2, this is the fastest migration path:

1. Keep @alcyone-labs/arg-parser for core parsing, then install the extra packages you actually use (@alcyone-labs/arg-parser-mcp, @alcyone-labs/arg-parser-dxt, @alcyone-labs/arg-parser-tui).
2. Replace built-in v2 MCP/DXT/TUI usage with the v3 plugin pattern via .use(...).
3. Update addMcpSubCommand() calls to mcpPlugin(...) from @alcyone-labs/arg-parser-mcp.
4. Move feature-specific imports to their new packages, such as createTuiApp from @alcyone-labs/arg-parser-tui.

🚀 What's New in v3.0.0

ArgParser v3.0.0 introduces a plugin-based architecture! The monolithic package has been split into focused packages:

Package	Purpose	Size
@alcyone-labs/arg-parser	Core CLI parsing	~50KB
@alcyone-labs/arg-parser-mcp	MCP server functionality	+150KB
@alcyone-labs/arg-parser-dxt	DXT package generation	+100KB
@alcyone-labs/arg-parser-tui	Terminal UI (OpenTUI)	+200KB

Benefits:

• ✅ Smaller installs - only include what you need
• ✅ Faster builds - no unused dependencies
• ✅ Better separation of concerns
• ✅ Independent versioning per feature

📦 Installation

Core Only (CLI parsing)

npm install @alcyone-labs/arg-parser

With MCP Support

npm install @alcyone-labs/arg-parser @alcyone-labs/arg-parser-mcp

With MCP + DXT

npm install @alcyone-labs/arg-parser @alcyone-labs/arg-parser-mcp @alcyone-labs/arg-parser-dxt

With TUI

npm install @alcyone-labs/arg-parser @alcyone-labs/arg-parser-tui @opentui/core @opentui/solid

📝 Quick Start

Basic CLI

import { ArgParser } from '@alcyone-labs/arg-parser';

const parser = new ArgParser({
  appName: 'my-cli',
  handler: async (ctx) => {
    console.log('Hello', ctx.args.name);
  }
});

await parser.parse();

With MCP Plugin

import { ArgParser } from '@alcyone-labs/arg-parser';
import { mcpPlugin } from '@alcyone-labs/arg-parser-mcp';

const parser = new ArgParser({
  appName: 'my-mcp-server',
  handler: async (ctx) => ({ result: 'success' })
})
  .use(mcpPlugin({
    serverInfo: {
      name: 'my-server',
      version: '1.0.0',
      description: 'My MCP server'
    }
  }));

await parser.parse();

With DXT Plugin

import { dxtPlugin } from '@alcyone-labs/arg-parser-dxt';

const parser = new ArgParser({...})
  .use(mcpPlugin({...}))
  .use(dxtPlugin({
    outputDir: './dist/dxt',
    include: ['assets', 'config.json']
  }));

// Build DXT package with: --s-build-dxt

With TUI Plugin

import { tuiPlugin, createTuiApp } from '@alcyone-labs/arg-parser-tui';

const parser = new ArgParser({
  handler: async (ctx) => {
    await createTuiApp(
      () => <text>Hello TUI!</text>,
      { theme: 'dark' }
    );
  }
})
  .use(tuiPlugin({ theme: 'dark' }));

🔌 Plugin System

ArgParser v3.0.0 uses a plugin architecture:

import { ArgParser, type IArgParserPlugin } from '@alcyone-labs/arg-parser';

const myPlugin = (options: any): IArgParserPlugin => ({
  name: 'my-plugin',
  version: '1.0.0',
  install(parser) {
    // Extend parser with custom functionality
    (parser as any).myMethod = () => {
      // Implementation
    };
  }
});

const parser = new ArgParser({...})
  .use(myPlugin({...}));

📚 Documentation

• Migration Guide v2 → v3
• Plugin Architecture Plan
• Core Package README
• MCP Package README
• DXT Package README
• TUI Package README

🔄 Migration from v2.x

See the Migration Guide for detailed instructions.

Quick summary:

1. Install the plugins you need
2. Replace addMcpSubCommand() with .use(mcpPlugin())
3. Add .use(dxtPlugin()) for DXT support
4. Add .use(tuiPlugin()) for TUI support

🛠️ Development

This is a monorepo using pnpm workspaces:

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Test all packages
pnpm test

# Build specific package
pnpm build:core
pnpm build:mcp
pnpm build:dxt
pnpm build:tui

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit PRs.