@dyyz1993/xcli-core

A powerful, domain-agnostic framework for building plugin-based CLI applications.

Overview

@dyyz1993/xcli-core is a comprehensive CLI framework that provides:

• Plugin System — Extensible plugin architecture with jiti-powered TypeScript loading
• Command Registration — Zod-powered parameter validation and command registration
• Scope Management — Hierarchical scope system for command execution context
• Session Management — Built-in session handling with persistence
• Daemon Mode — Long-running background processes with worker pools
• WebSocket Support — Real-time communication via WebSocket server/client
• Output Formatting — Unified output in text, JSON, or YAML formats
• Scaffolding — Template-based project and plugin generation
• Configuration Management — RC file configuration with environment variable support

Installation

npm install @dyyz1993/xcli-core

Requires Node.js >= 18.0.0.

Core Concepts

1. Core Framework

The Core class is the entry point for your CLI application:

import { Core } from '@dyyz1993/xcli-core';

const core = new Core({
  name: 'mycli',
  version: '1.0.0',
  description: 'My CLI tool',
});

core.start();

2. Plugin System

Create plugins with TypeScript support:

import type { XCLIAPI } from '@dyyz1993/xcli-core';
import { z } from 'zod';

export default function (xcli: XCLIAPI): void {
  const site = xcli.createSite({
    name: 'my-plugin',
    url: 'https://example.com',
  });

  site.command('hello', {
    description: 'Say hello',
    parameters: z.object({
      name: z.string().default('World'),
    }),
    handler: async (params, ctx) => {
      return {
        ok: true,
        message: `Hello, ${params.name}!`,
      };
    },
  });
}

3. Scope Management

Define hierarchical scopes for command execution:

import { ScopeRegistry } from '@dyyz1993/xcli-core';

const scopeRegistry = new ScopeRegistry([
  { name: 'project', order: 0 },
  { name: 'browser', order: 1 },
  { name: 'page', order: 2 },
  { name: 'element', order: 3 },
]);

4. Session Management

Built-in session handling with persistence:

import { createSessionMeta, sessions, clearAllSessions } from '@dyyz1993/xcli-core';

// Create session
const meta = createSessionMeta('default', { url: 'https://example.com' });
sessions.set('default', meta);

// List sessions
const allSessions = listSessions();

// Clear all sessions
clearAllSessions();

5. Daemon Mode

Run background processes with worker management:

import { startDaemon, isDaemonRunning, getDaemonStatus } from '@dyyz1993/xcli-core';

// Start daemon
await startDaemon({
  port: 9222,
  workerCount: 3,
});

// Check status
if (isDaemonRunning()) {
  const status = getDaemonStatus();
  console.log('Daemon is running:', status);
}

// Stop daemon
await stopDaemon();

6. WebSocket Support

Real-time communication for interactive features:

import { WSServer } from '@dyyz1993/xcli-core';

const server = new WSServer({
  port: 9223,
  onMessage: (ws, message) => {
    console.log('Received:', message);
  },
});

await server.start();

7. Output Formatting

Unified output in multiple formats:

import { outputFormatter } from '@dyyz1993/xcli-core';

// Format as text
const text = outputFormatter.format({ ok: true, data: 'hello' }, 'text');

// Format as JSON
const json = outputFormatter.format({ ok: true, data: 'hello' }, 'json');

// Format as YAML
const yaml = outputFormatter.format({ ok: true, data: 'hello' }, 'yaml');

8. Scaffolding

Generate projects and plugins from templates:

import { ScaffoldEngine } from '@dyyz1993/xcli-core';

const engine = new ScaffoldEngine();

await engine.generate({
  template: MINIMAL_PLUGIN_TEMPLATE,
  targetDir: './my-plugin',
  variables: {
    projectName: 'my-plugin',
  },
});

Documentation

• Architecture — Framework architecture overview
• Session Management — Session system guide
• Daemon Management — Daemon system guide
• Plugin System — Plugin development guide
• WebSocket Integration — WebSocket server/client guide

API Reference

See the API Reference section below for detailed API documentation.

Use Cases

CLI Tools

Build command-line tools with rich features:

import { Core } from '@dyyz1993/xcli-core';

const core = new Core({
  name: 'mycli',
  version: '1.0.0',
});

core.command('build', {
  description: 'Build the project',
  scope: 'project',
  handler: async () => {
    // Build logic
  },
});

core.start();

Web Scrapers

Create extensible web scrapers:

export default function (xcli: XCLIAPI): void {
  const site = xcli.createSite({
    name: 'scraper',
    url: 'https://example.com',
  });

  site.command('scrape', {
    description: 'Scrape data',
    handler: async (params, ctx) => {
      // Scraping logic
    },
  });
}

Developer Tools

Build developer utilities:

import { Core, startDaemon } from '@dyyz1993/xcli-core';

const core = new Core({
  name: 'devtool',
  version: '1.0.0',
});

// Start background daemon
core.addBuiltin('daemon', {
  description: 'Manage daemon',
  handler: async (args) => {
    if (args.command === 'start') {
      await startDaemon();
    }
  },
});

core.start();

Related Projects

• @dyyz1993/xpage — Browser automation engine
• @dyyz1993/xbrowser — Browser automation CLI (built on xcli-core)
• create-xcli — Project scaffolding tool

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Lint
npm run lint

License

MIT

Support

• Issues: GitHub Issues
• Documentation: Full Docs

API Reference

Core Classes

Core

Main framework class.

class Core {
  constructor(config: CoreConfig);
  start(): void;
  command(name: string, definition: CommandDefinition): void;
  builtin(name: string, handler: BuiltinHandler): void;
  // ...
}

PluginLoader

Load and manage plugins.

class PluginLoader {
  loadPlugin(pluginPath: string): PluginInstance;
  scanAndLoad(dirs: string[]): PluginInstance[];
  reloadPlugin(pluginId: string): void;
  // ...
}

SessionManager

Manage sessions.

class SessionManager {
  createSession(id: string, meta: SessionMeta): void;
  getSession(id: string): SessionMeta | undefined;
  removeSession(id: string): void;
  listSessions(): SessionMeta[];
  // ...
}

Daemon Classes

DaemonManager

Manage daemon processes.

class DaemonManager {
  start(config: DaemonConfig): Promise<void>;
  stop(): Promise<void>;
  isRunning(): boolean;
  getStatus(): DaemonStatus;
  // ...
}

WorkerManager

Manage worker processes.

class WorkerManager {
  start(config: WorkerManagerConfig): Promise<void>;
  stop(): Promise<void>;
  execute(command: string, args: CommandArgs): Promise<CommandResult>;
  // ...
}

WSServer

WebSocket server.

class WSServer {
  constructor(config: WSServerConfig);
  start(): Promise<void>;
  stop(): Promise<void>;
  broadcast(message: WSMessage): void;
  // ...
}

WSClient

WebSocket client.

class WSClient {
  constructor(config: WSClientConfig);
  connect(): Promise<void>;
  send(message: WSMessage): void;
  on(event: 'message' | 'open' | 'close' | 'error', callback: Callback): void;
  // ...
}

Output Classes

OutputFormatter

Format command results.

class OutputFormatter {
  format(result: CommandResult, mode: OutputMode): string;
  formatJSON(result: CommandResult): string;
  formatYAML(result: CommandResult): string;
  formatText(result: CommandResult): string;
  // ...
}

HelpGenerator

Generate help text.

class HelpGenerator {
  generate(options: HelpOptions): string;
  generateCommandHelp(command: CommandEntry): string;
  generatePluginHelp(plugin: PluginInstance): string;
  // ...
}

Scaffolding Classes

ScaffoldEngine

Generate from templates.

class ScaffoldEngine {
  generate(options: ScaffoldOptions): Promise<ScaffoldResult>;
  loadTemplate(name: string): ScaffoldTemplate;
  registerTemplate(name: string, template: ScaffoldTemplate): void;
  // ...
}

Utility Functions

Configuration

loadConfig(): RcConfig;
saveConfig(config: RcConfig): void;
getConfigValue(key: string): unknown;
setConfigValue(key: string, value: void): void;
getEffectiveValue(key: string): unknown;

Argument Parsing

parseArgs(args: string[]): ParsedArgs;
mergeArgsWithDefaults(args: ParsedArgs, defaults: Record<string, unknown>): ParsedArgs;
resolveShortOptions(args: string[]): string[];

Validation

validateArgs(schema: ZodType, args: Record<string, unknown>): ValidationResult;
buildInputSchema(params: ZodType): Record<string, unknown>;

Types

Core Config

interface CoreConfig {
  name: string;
  version: string;
  description?: string;
  defaultScope?: string;
}

Command Entry

interface CommandEntry {
  name: string;
  description: string;
  scope: CommandScope;
  parameters?: ZodType;
  handler: CommandHandler;
  examples?: Example[];
}

Command Context

interface CommandContext {
  sessionId?: string;
  storage: StorageContext;
  output: OutputContext;
  metadata?: Record<string, unknown>;
}

Plugin Instance

interface PluginInstance {
  id: string;
  name: string;
  commands: CommandEntry[];
  setup: (api: XCLIAPI) => void;
}

For complete type definitions, see the TypeScript definitions in the package.