build-cli-plugin

Build a CLI Plugin

Add a new plugin or adapter to a CLI tool's pluggable architecture using the abstract base class pattern.

When to Use

• Adding support for a new target framework to a CLI installer
• Building a plugin system for a multi-target command-line tool
• Extending an existing adapter architecture with a new strategy variant
• Porting content delivery to a framework that uses a different file layout

Inputs

• Required: Framework or target the plugin supports (name, config paths, conventions)
• Required: Path to the base class or plugin contract
• Required: Installation strategy: symlink, copy, file-per-item, or append-to-file
• Optional: Content types the plugin handles (e.g., skills only, skills + agents, full support)
• Optional: Scope support (project-level, global, both)

Procedure

Step 1: Define the Contract

The base class establishes the interface all plugins must implement:

export class FrameworkAdapter {
  static id = 'base';            // Unique identifier
  static displayName = 'Base';   // Human-readable name
  static strategy = 'symlink';   // Installation strategy
  static contentTypes = ['skill']; // What this adapter handles

  async detect(projectDir) { return false; }
  getTargetPath(projectDir, scope) { throw new Error('Not implemented'); }
  async install(item, projectDir, scope, options) { throw new Error('Not implemented'); }
  async uninstall(item, projectDir, scope, options) { throw new Error('Not implemented'); }
  async listInstalled(projectDir, scope) { return []; }
  async audit(projectDir, scope) { return { framework: this.constructor.displayName, ok: [], warnings: [], errors: [] }; }
  supports(contentType) { return this.constructor.contentTypes.includes(contentType); }
}

Static fields define the plugin's identity and capabilities:

• id: Used in --framework <id> option and result reporting
• displayName: Shown in human-readable output
• strategy: Determines how content reaches the target
• contentTypes: Filters which items this adapter receives