agentsys 5.0.0

package/plugins/perf/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/plugins/perf/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');
+  }
+}

package/plugins/perf/lib/types/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Plugin Interface Type Definitions
+ * Centralized type definitions for all plugin components
+ *
+ * @module lib/types
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+// Re-export all types
+export * from './plugin-manifest';
+export * from './command-frontmatter';
+export * from './agent-frontmatter';
+export * from './skill-frontmatter';
+export * from './hook-frontmatter';
+
+/**
+ * Plugin component types union
+ */
+export type PluginComponentType = 'command' | 'agent' | 'skill' | 'hook';
+
+/**
+ * Plugin directory structure
+ */
+export interface PluginStructure {
+  /** Plugin root directory */
+  root: string;
+
+  /** Plugin manifest (plugin.json) */
+  manifest: string;
+
+  /** Commands directory */
+  commands?: string;
+
+  /** Agents directory */
+  agents?: string;
+
+  /** Skills directory */
+  skills?: string;
+
+  /** Hooks directory */
+  hooks?: string;
+
+  /** Shared library directory */
+  lib?: string;
+
+  /** Tests directory */
+  tests?: string;
+}
+
+/**
+ * Plugin validation result
+ */
+export interface PluginValidationResult {
+  /** Whether plugin is valid */
+  valid: boolean;
+
+  /** Validation errors (if any) */
+  errors: string[];
+
+  /** Validation warnings (if any) */
+  warnings: string[];
+
+  /** Detected components */
+  components: {
+    commands: number;
+    agents: number;
+    skills: number;
+    hooks: number;
+  };
+}
+
+/**
+ * Standard plugin directory structure
+ */
+export const PLUGIN_STRUCTURE: Readonly<Record<string, string>> = {
+  MANIFEST: '.claude-plugin/plugin.json',
+  COMMANDS: 'commands',
+  AGENTS: 'agents',
+  SKILLS: 'skills',
+  HOOKS: 'hooks',
+  LIB: 'lib',
+  TESTS: 'tests'
+} as const;

package/plugins/perf/lib/types/plugin-manifest.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Plugin Manifest Type Definitions
+ * Defines the structure of plugin.json files
+ *
+ * @module lib/types/plugin-manifest
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Author information for plugin manifest
+ */
+export interface PluginAuthor {
+  /** Author's full name */
+  name: string;
+  /** Author's email address (optional) */
+  email?: string;
+  /** Author's website or GitHub profile URL (optional) */
+  url?: string;
+}
+
+/**
+ * Plugin manifest structure
+ * Required fields for all Claude Code plugins
+ */
+export interface PluginManifest {
+  /** Unique plugin identifier (kebab-case, lowercase) */
+  name: string;
+
+  /** Semantic version (MAJOR.MINOR.PATCH) */
+  version: string;
+
+  /** Short description of plugin functionality */
+  description: string;
+
+  /** Author information */
+  author: PluginAuthor;
+
+  /** Plugin homepage URL (optional) */
+  homepage?: string;
+
+  /** Repository URL (optional) */
+  repository?: string;
+
+  /** License identifier (SPDX format, e.g., "MIT", "Apache-2.0") */
+  license: string;
+
+  /** Search keywords for discoverability (optional) */
+  keywords?: string[];
+
+  /** Minimum Claude Code version required (optional) */
+  minClaudeVersion?: string;
+
+  /** Plugin dependencies (optional) */
+  dependencies?: {
+    [pluginName: string]: string; // version constraint
+  };
+
+  /** Plugin configuration schema (optional) */
+  config?: {
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Type guard to check if an object is a valid PluginManifest
+ */
+export function isPluginManifest(obj: unknown): obj is PluginManifest {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const manifest = obj as Partial<PluginManifest>;
+
+  return (
+    typeof manifest.name === 'string' &&
+    /^[a-z0-9-]+$/.test(manifest.name) &&
+    typeof manifest.version === 'string' &&
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/.test(manifest.version) &&
+    typeof manifest.description === 'string' &&
+    typeof manifest.author === 'object' &&
+    manifest.author !== null &&
+    typeof manifest.author.name === 'string' &&
+    typeof manifest.license === 'string'
+  );
+}
+
+/**
+ * Validates a plugin manifest against the schema
+ * @throws {Error} If manifest is invalid
+ */
+export function validatePluginManifest(manifest: unknown): asserts manifest is PluginManifest {
+  if (!isPluginManifest(manifest)) {
+    throw new Error('Invalid plugin manifest: missing required fields or invalid format');
+  }
+
+  // Additional validations
+  if (manifest.keywords && !Array.isArray(manifest.keywords)) {
+    throw new Error('Invalid plugin manifest: keywords must be an array');
+  }
+
+  if (manifest.dependencies && typeof manifest.dependencies !== 'object') {
+    throw new Error('Invalid plugin manifest: dependencies must be an object');
+  }
+}

package/plugins/perf/lib/types/skill-frontmatter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Skill Frontmatter Type Definitions
+ * Defines the structure of YAML frontmatter in skill markdown files
+ *
+ * @module lib/types/skill-frontmatter
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Skill frontmatter structure
+ * YAML metadata at the top of skill markdown files
+ */
+export interface SkillFrontmatter {
+  /** Skill unique identifier (kebab-case) */
+  skill: string;
+
+  /** Short description of skill purpose */
+  description: string;
+
+  /** Skill category for organization */
+  category?: string;
+
+  /** When this skill should be invoked (triggering conditions) */
+  'when-to-use'?: string[];
+
+  /** Example usage scenarios */
+  examples?: string[];
+
+  /** Preferred model for this skill (sonnet, opus, haiku) */
+  model?: 'sonnet' | 'opus' | 'haiku';
+
+  /** Whether skill requires user approval before running */
+  requiresApproval?: boolean;
+
+  /** Tags for searchability */
+  tags?: string[];
+
+  /** Related commands or skills */
+  related?: string[];
+}
+
+/**
+ * Type guard to check if an object is valid SkillFrontmatter
+ */
+export function isSkillFrontmatter(obj: unknown): obj is SkillFrontmatter {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const fm = obj as Partial<SkillFrontmatter>;
+
+  return (
+    typeof fm.skill === 'string' &&
+    fm.skill.length > 0 &&
+    typeof fm.description === 'string' &&
+    fm.description.length > 0
+  );
+}
+
+/**
+ * Validates skill frontmatter
+ * @throws {Error} If frontmatter is invalid
+ */
+export function validateSkillFrontmatter(
+  frontmatter: unknown
+): asserts frontmatter is SkillFrontmatter {
+  if (!isSkillFrontmatter(frontmatter)) {
+    throw new Error('Invalid skill frontmatter: missing required fields');
+  }
+
+  // Additional validations
+  if (frontmatter.model && !['sonnet', 'opus', 'haiku'].includes(frontmatter.model)) {
+    throw new Error('Invalid skill frontmatter: model must be sonnet, opus, or haiku');
+  }
+
+  if (frontmatter['when-to-use'] && !Array.isArray(frontmatter['when-to-use'])) {
+    throw new Error('Invalid skill frontmatter: when-to-use must be an array');
+  }
+
+  if (frontmatter.examples && !Array.isArray(frontmatter.examples)) {
+    throw new Error('Invalid skill frontmatter: examples must be an array');
+  }
+
+  if (frontmatter.tags && !Array.isArray(frontmatter.tags)) {
+    throw new Error('Invalid skill frontmatter: tags must be an array');
+  }
+
+  if (frontmatter.related && !Array.isArray(frontmatter.related)) {
+    throw new Error('Invalid skill frontmatter: related must be an array');
+  }
+}

package/plugins/perf/lib/utils/atomic-write.js

@@ -0,0 +1,94 @@
+/**
+ * Atomic File Write Utility
+ *
+ * Provides crash-safe file writes using the write-to-temp-then-rename pattern.
+ * Prevents data corruption from partial writes during concurrent operations.
+ *
+ * @module utils/atomic-write
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * Generate a unique temporary filename
+ * @param {string} targetPath - Target file path
+ * @returns {string} Temporary file path
+ */
+function getTempPath(targetPath) {
+  const dir = path.dirname(targetPath);
+  const basename = path.basename(targetPath);
+  const randomSuffix = crypto.randomBytes(6).toString('hex');
+  return path.join(dir, `.${basename}.${randomSuffix}.tmp`);
+}
+
+/**
+ * Write file atomically using write-to-temp-then-rename pattern
+ *
+ * This ensures:
+ * - File is never partially written (atomic rename)
+ * - Concurrent reads see either old or new content, never partial
+ * - Crash-safe: interrupted writes don't corrupt existing file
+ *
+ * @param {string} filePath - Target file path
+ * @param {string} content - Content to write
+ * @param {Object} options - Options
+ * @param {string} options.encoding - File encoding (default: 'utf8')
+ * @param {number} options.mode - File mode (default: 0o644)
+ * @returns {boolean} True on success
+ * @throws {Error} On write or rename failure
+ */
+function writeFileAtomic(filePath, content, options = {}) {
+  const { encoding = 'utf8', mode = 0o644 } = options;
+
+  // Ensure directory exists
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tempPath = getTempPath(filePath);
+
+  try {
+    // Write to temp file
+    fs.writeFileSync(tempPath, content, { encoding, mode });
+
+    // Atomic rename (overwrites existing file)
+    fs.renameSync(tempPath, filePath);
+
+    return true;
+  } catch (error) {
+    // Cleanup temp file on failure
+    try {
+      if (fs.existsSync(tempPath)) {
+        fs.unlinkSync(tempPath);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw error;
+  }
+}
+
+/**
+ * Write JSON file atomically
+ *
+ * @param {string} filePath - Target file path
+ * @param {*} data - Data to serialize as JSON
+ * @param {Object} options - Options
+ * @param {number} options.indent - JSON indentation (default: 2)
+ * @param {string} options.encoding - File encoding (default: 'utf8')
+ * @returns {boolean} True on success
+ */
+function writeJsonAtomic(filePath, data, options = {}) {
+  const { indent = 2, ...writeOptions } = options;
+  const content = JSON.stringify(data, null, indent);
+  return writeFileAtomic(filePath, content, writeOptions);
+}
+
+module.exports = {
+  writeFileAtomic,
+  writeJsonAtomic,
+  getTempPath
+};