awesome-slash 2.4.3 → 2.5.0

package/lib/types/README.md

@@ -0,0 +1,292 @@
+# Plugin Interface Type Definitions
+
+TypeScript type definitions for Claude Code plugin components.
+
+## Overview
+
+This directory contains the canonical type definitions for all plugin components:
+
+- **Plugin Manifest** (`plugin.json`) - Plugin metadata and configuration
+- **Command Frontmatter** - YAML metadata for slash commands
+- **Agent Frontmatter** - YAML metadata for specialized agents
+- **Skill Frontmatter** - YAML metadata for user-invocable skills
+- **Hook Frontmatter** - YAML metadata for lifecycle hooks
+
+## Usage
+
+### TypeScript Projects
+
+```typescript
+import {
+  PluginManifest,
+  CommandFrontmatter,
+  AgentFrontmatter,
+  SkillFrontmatter,
+  HookFrontmatter,
+  validatePluginManifest,
+  validateCommandFrontmatter
+} from './lib/types';
+
+// Validate a plugin manifest
+const manifest: PluginManifest = {
+  name: "my-plugin",
+  version: "1.0.0",
+  description: "My awesome plugin",
+  author: {
+    name: "John Doe"
+  },
+  license: "MIT"
+};
+
+validatePluginManifest(manifest); // Throws if invalid
+```
+
+### JavaScript Projects (JSDoc)
+
+```javascript
+/**
+ * @typedef {import('./lib/types').PluginManifest} PluginManifest
+ * @typedef {import('./lib/types').CommandFrontmatter} CommandFrontmatter
+ */
+
+/**
+ * Load and validate plugin manifest
+ * @param {string} path - Path to plugin.json
+ * @returns {PluginManifest} Validated manifest
+ */
+function loadPluginManifest(path) {
+  const manifest = JSON.parse(fs.readFileSync(path, 'utf8'));
+  const { validatePluginManifest } = require('./lib/types/plugin-manifest');
+  validatePluginManifest(manifest);
+  return manifest;
+}
+```
+
+## Type Definitions
+
+### PluginManifest
+
+Defines the structure of `plugin.json`:
+
+```typescript
+interface PluginManifest {
+  name: string;                    // Unique identifier (kebab-case)
+  version: string;                 // Semantic version (X.Y.Z)
+  description: string;             // Short description
+  author: PluginAuthor;            // Author info
+  homepage?: string;               // Plugin homepage URL
+  repository?: string;             // Repository URL
+  license: string;                 // SPDX license identifier
+  keywords?: string[];             // Search keywords
+  minClaudeVersion?: string;       // Minimum Claude Code version
+  dependencies?: {                 // Plugin dependencies
+    [pluginName: string]: string;
+  };
+  config?: {                       // Plugin configuration
+    [key: string]: unknown;
+  };
+}
+```
+
+### CommandFrontmatter
+
+Defines YAML frontmatter for commands:
+
+```yaml
+---
+command: my-command
+description: Do something awesome
+argument-hint: "[options]"
+model: sonnet
+requiresGit: true
+tags:
+  - utility
+  - automation
+---
+```
+
+```typescript
+interface CommandFrontmatter {
+  command: string;                 // Command name
+  description: string;             // Short description
+  'argument-hint'?: string;        // Autocomplete hint
+  usage?: string[];                // Usage examples
+  arguments?: CommandArgument[];   // Argument definitions
+  aliases?: string[];              // Alternative names
+  category?: string;               // Command category
+  requiresGit?: boolean;           // Requires git repo
+  requiresNetwork?: boolean;       // Requires network
+  model?: 'sonnet' | 'opus' | 'haiku';
+  maxTurns?: number;               // Max conversation turns
+  tags?: string[];                 // Tags for search
+}
+```
+
+### AgentFrontmatter
+
+Defines YAML frontmatter for agents:
+
+```yaml
+---
+agent: my-agent
+description: Specialized agent for X
+tools:
+  - Read
+  - Grep
+  - Glob
+model: opus
+color: blue
+maxTurns: 10
+---
+```
+
+```typescript
+interface AgentFrontmatter {
+  agent: string;                   // Agent identifier
+  description: string;             // Purpose description
+  tools?: AgentTool[];             // Available tools
+  model?: 'sonnet' | 'opus' | 'haiku';
+  maxTurns?: number;               // Max turns
+  color?: AgentColor;              // UI color
+  canRunInBackground?: boolean;    // Background support
+  requiresApproval?: boolean;      // User approval needed
+  category?: string;               // Agent category
+  tags?: string[];                 // Tags for search
+  'when-to-use'?: string[];        // Triggering conditions
+  examples?: string[];             // Usage examples
+}
+```
+
+### SkillFrontmatter
+
+Defines YAML frontmatter for skills:
+
+```yaml
+---
+skill: my-skill
+description: User-invocable skill
+model: sonnet
+when-to-use:
+  - "User says /my-skill"
+  - "Task requires X functionality"
+---
+```
+
+```typescript
+interface SkillFrontmatter {
+  skill: string;                   // Skill identifier
+  description: string;             // Purpose description
+  category?: string;               // Skill category
+  'when-to-use'?: string[];        // Triggering conditions
+  examples?: string[];             // Usage examples
+  model?: 'sonnet' | 'opus' | 'haiku';
+  requiresApproval?: boolean;      // User approval needed
+  tags?: string[];                 // Tags for search
+  related?: string[];              // Related components
+}
+```
+
+### HookFrontmatter
+
+Defines YAML frontmatter for hooks:
+
+```yaml
+---
+hook: my-hook
+event: SubagentStop
+description: Triggered when agent stops
+priority: 10
+enabled: true
+---
+```
+
+```typescript
+interface HookFrontmatter {
+  hook: string;                    // Hook identifier
+  event: HookEvent;                // Trigger event
+  description: string;             // Purpose description
+  tool?: string;                   // Tool name (for PreToolUse/PostToolUse)
+  priority?: number;               // Execution priority
+  enabled?: boolean;               // Enabled by default
+  category?: string;               // Hook category
+  tags?: string[];                 // Tags for search
+  related?: string[];              // Related hooks
+}
+```
+
+## Validation
+
+All frontmatter types include validation functions:
+
+```typescript
+import {
+  validatePluginManifest,
+  validateCommandFrontmatter,
+  validateAgentFrontmatter,
+  validateSkillFrontmatter,
+  validateHookFrontmatter
+} from './lib/types';
+
+// Throws Error if invalid
+validatePluginManifest(manifest);
+validateCommandFrontmatter(frontmatter);
+validateAgentFrontmatter(frontmatter);
+validateSkillFrontmatter(frontmatter);
+validateHookFrontmatter(frontmatter);
+```
+
+## Type Guards
+
+Use type guards for runtime checking:
+
+```typescript
+import { isPluginManifest, isCommandFrontmatter } from './lib/types';
+
+if (isPluginManifest(obj)) {
+  // obj is PluginManifest
+  console.log(obj.name);
+}
+
+if (isCommandFrontmatter(obj)) {
+  // obj is CommandFrontmatter
+  console.log(obj.command);
+}
+```
+
+## Plugin Structure
+
+Standard plugin directory structure:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin manifest
+├── commands/                # Slash commands
+│   └── my-command.md
+├── agents/                  # Specialized agents
+│   └── my-agent.md
+├── skills/                  # User-invocable skills
+│   └── my-skill.md
+├── hooks/                   # Lifecycle hooks
+│   └── my-hook.md
+├── lib/                     # Shared libraries
+│   ├── platform/
+│   ├── patterns/
+│   └── utils/
+└── tests/                   # Tests
+```
+
+## Contributing
+
+When adding new plugin component types:
+
+1. Create a new `.d.ts` file in this directory
+2. Define the interface with JSDoc comments
+3. Add type guard function (`is*`)
+4. Add validation function (`validate*`)
+5. Export from `index.d.ts`
+6. Update this README
+
+## License
+
+MIT © Avi Fenesh

package/lib/types/agent-frontmatter.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Agent Frontmatter Type Definitions
+ * Defines the structure of YAML frontmatter in agent markdown files
+ *
+ * @module lib/types/agent-frontmatter
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Tool permission for agent
+ */
+export type AgentTool =
+  | 'Bash'
+  | 'Bash(git:*)'
+  | 'Bash(gh:*)'
+  | 'Bash(npm:*)'
+  | 'Bash(node:*)'
+  | 'Bash(deployment:*)'
+  | 'Read'
+  | 'Write'
+  | 'Edit'
+  | 'Glob'
+  | 'Grep'
+  | 'Task'
+  | 'LSP'
+  | 'EnterPlanMode'
+  | 'ExitPlanMode'
+  | 'AskUserQuestion'
+  | 'TodoWrite'
+  | 'WebFetch'
+  | 'WebSearch'
+  | string; // Allow custom tools
+
+/**
+ * Agent color for UI identification
+ */
+export type AgentColor =
+  | 'blue'
+  | 'green'
+  | 'purple'
+  | 'orange'
+  | 'red'
+  | 'yellow'
+  | 'pink'
+  | 'cyan';
+
+/**
+ * Agent frontmatter structure
+ * YAML metadata at the top of agent markdown files
+ */
+export interface AgentFrontmatter {
+  /** Agent unique identifier (kebab-case) */
+  agent: string;
+
+  /** Short description of agent purpose */
+  description: string;
+
+  /** Tools the agent has access to */
+  tools?: AgentTool[];
+
+  /** Preferred model for this agent (sonnet, opus, haiku) */
+  model?: 'sonnet' | 'opus' | 'haiku';
+
+  /** Maximum number of turns before stopping */
+  maxTurns?: number;
+
+  /** UI color for agent identification */
+  color?: AgentColor;
+
+  /** Whether agent can run in background */
+  canRunInBackground?: boolean;
+
+  /** Whether agent requires user approval before running */
+  requiresApproval?: boolean;
+
+  /** Agent category for organization */
+  category?: string;
+
+  /** Tags for searchability */
+  tags?: string[];
+
+  /** When this agent should be used (triggering conditions) */
+  'when-to-use'?: string[];
+
+  /** Example usage scenarios */
+  examples?: string[];
+}
+
+/**
+ * Type guard to check if an object is valid AgentFrontmatter
+ */
+export function isAgentFrontmatter(obj: unknown): obj is AgentFrontmatter {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const fm = obj as Partial<AgentFrontmatter>;
+
+  return (
+    typeof fm.agent === 'string' &&
+    fm.agent.length > 0 &&
+    typeof fm.description === 'string' &&
+    fm.description.length > 0
+  );
+}
+
+/**
+ * Validates agent frontmatter
+ * @throws {Error} If frontmatter is invalid
+ */
+export function validateAgentFrontmatter(
+  frontmatter: unknown
+): asserts frontmatter is AgentFrontmatter {
+  if (!isAgentFrontmatter(frontmatter)) {
+    throw new Error('Invalid agent frontmatter: missing required fields');
+  }
+
+  // Additional validations
+  if (frontmatter.tools && !Array.isArray(frontmatter.tools)) {
+    throw new Error('Invalid agent frontmatter: tools must be an array');
+  }
+
+  if (frontmatter.model && !['sonnet', 'opus', 'haiku'].includes(frontmatter.model)) {
+    throw new Error('Invalid agent frontmatter: model must be sonnet, opus, or haiku');
+  }
+
+  if (frontmatter.maxTurns !== undefined &&
+      (typeof frontmatter.maxTurns !== 'number' || frontmatter.maxTurns < 1)) {
+    throw new Error('Invalid agent frontmatter: maxTurns must be a positive number');
+  }
+
+  const validColors: AgentColor[] = ['blue', 'green', 'purple', 'orange', 'red', 'yellow', 'pink', 'cyan'];
+  if (frontmatter.color && !validColors.includes(frontmatter.color)) {
+    throw new Error(`Invalid agent frontmatter: color must be one of ${validColors.join(', ')}`);
+  }
+}

package/lib/types/command-frontmatter.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Command Frontmatter Type Definitions
+ * Defines the structure of YAML frontmatter in command markdown files
+ *
+ * @module lib/types/command-frontmatter
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Command argument definition
+ */
+export interface CommandArgument {
+  /** Argument name */
+  name: string;
+  /** Argument description */
+  description: string;
+  /** Whether argument is required */
+  required?: boolean;
+  /** Default value if not provided */
+  default?: string | number | boolean;
+  /** Allowed values (enum) */
+  enum?: string[];
+}
+
+/**
+ * Command frontmatter structure
+ * YAML metadata at the top of command markdown files
+ */
+export interface CommandFrontmatter {
+  /** Command name (should match filename without extension) */
+  command: string;
+
+  /** Short description shown in help */
+  description: string;
+
+  /** Argument hint shown in autocomplete (e.g., "[options]", "<file>") */
+  'argument-hint'?: string;
+
+  /** Detailed usage examples */
+  usage?: string[];
+
+  /** Command arguments definition */
+  arguments?: CommandArgument[];
+
+  /** Command aliases (alternative names) */
+  aliases?: string[];
+
+  /** Command category for grouping */
+  category?: string;
+
+  /** Whether command requires git repository */
+  requiresGit?: boolean;
+
+  /** Whether command requires network access */
+  requiresNetwork?: boolean;
+
+  /** Preferred model for this command (sonnet, opus, haiku) */
+  model?: 'sonnet' | 'opus' | 'haiku';
+
+  /** Maximum number of turns for multi-turn commands */
+  maxTurns?: number;
+
+  /** Tags for searchability */
+  tags?: string[];
+}
+
+/**
+ * Type guard to check if an object is valid CommandFrontmatter
+ */
+export function isCommandFrontmatter(obj: unknown): obj is CommandFrontmatter {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const fm = obj as Partial<CommandFrontmatter>;
+
+  return (
+    typeof fm.command === 'string' &&
+    fm.command.length > 0 &&
+    typeof fm.description === 'string' &&
+    fm.description.length > 0
+  );
+}
+
+/**
+ * Validates command frontmatter
+ * @throws {Error} If frontmatter is invalid
+ */
+export function validateCommandFrontmatter(
+  frontmatter: unknown
+): asserts frontmatter is CommandFrontmatter {
+  if (!isCommandFrontmatter(frontmatter)) {
+    throw new Error('Invalid command frontmatter: missing required fields');
+  }
+
+  // Additional validations
+  if (frontmatter.arguments && !Array.isArray(frontmatter.arguments)) {
+    throw new Error('Invalid command frontmatter: arguments must be an array');
+  }
+
+  if (frontmatter.model && !['sonnet', 'opus', 'haiku'].includes(frontmatter.model)) {
+    throw new Error('Invalid command frontmatter: model must be sonnet, opus, or haiku');
+  }
+
+  if (frontmatter.maxTurns !== undefined &&
+      (typeof frontmatter.maxTurns !== 'number' || frontmatter.maxTurns < 1)) {
+    throw new Error('Invalid command frontmatter: maxTurns must be a positive number');
+  }
+}

package/lib/types/hook-frontmatter.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Hook Frontmatter Type Definitions
+ * Defines the structure of YAML frontmatter in hook markdown files
+ *
+ * @module lib/types/hook-frontmatter
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Hook event types
+ */
+export type HookEvent =
+  | 'PreToolUse'
+  | 'PostToolUse'
+  | 'Stop'
+  | 'SubagentStop'
+  | 'SessionStart'
+  | 'SessionEnd'
+  | 'UserPromptSubmit'
+  | 'PreCompact'
+  | 'Notification';
+
+/**
+ * Hook frontmatter structure
+ * YAML metadata at the top of hook markdown files
+ */
+export interface HookFrontmatter {
+  /** Hook unique identifier (kebab-case) */
+  hook: string;
+
+  /** Event that triggers this hook */
+  event: HookEvent;
+
+  /** Short description of hook purpose */
+  description: string;
+
+  /** Tool name this hook applies to (for PreToolUse/PostToolUse) */
+  tool?: string;
+
+  /** Hook priority (higher = runs first, default: 0) */
+  priority?: number;
+
+  /** Whether hook is enabled by default */
+  enabled?: boolean;
+
+  /** Hook category for organization */
+  category?: string;
+
+  /** Tags for searchability */
+  tags?: string[];
+
+  /** Related hooks */
+  related?: string[];
+}
+
+/**
+ * Type guard to check if an object is valid HookFrontmatter
+ */
+export function isHookFrontmatter(obj: unknown): obj is HookFrontmatter {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const fm = obj as Partial<HookFrontmatter>;
+
+  const validEvents: HookEvent[] = [
+    'PreToolUse',
+    'PostToolUse',
+    'Stop',
+    'SubagentStop',
+    'SessionStart',
+    'SessionEnd',
+    'UserPromptSubmit',
+    'PreCompact',
+    'Notification'
+  ];
+
+  return (
+    typeof fm.hook === 'string' &&
+    fm.hook.length > 0 &&
+    typeof fm.event === 'string' &&
+    validEvents.includes(fm.event as HookEvent) &&
+    typeof fm.description === 'string' &&
+    fm.description.length > 0
+  );
+}
+
+/**
+ * Validates hook frontmatter
+ * @throws {Error} If frontmatter is invalid
+ */
+export function validateHookFrontmatter(
+  frontmatter: unknown
+): asserts frontmatter is HookFrontmatter {
+  if (!isHookFrontmatter(frontmatter)) {
+    throw new Error('Invalid hook frontmatter: missing required fields or invalid event type');
+  }
+
+  // Tool-specific hooks must specify tool
+  if ((frontmatter.event === 'PreToolUse' || frontmatter.event === 'PostToolUse') &&
+      !frontmatter.tool) {
+    throw new Error('Invalid hook frontmatter: PreToolUse and PostToolUse hooks must specify tool');
+  }
+
+  if (frontmatter.priority !== undefined &&
+      (typeof frontmatter.priority !== 'number' || !Number.isInteger(frontmatter.priority))) {
+    throw new Error('Invalid hook frontmatter: priority must be an integer');
+  }
+
+  if (frontmatter.tags && !Array.isArray(frontmatter.tags)) {
+    throw new Error('Invalid hook frontmatter: tags must be an array');
+  }
+
+  if (frontmatter.related && !Array.isArray(frontmatter.related)) {
+    throw new Error('Invalid hook frontmatter: related must be an array');
+  }
+}