@stoneforge/smithy 0.1.0

package/dist/services/plugin-executor.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Plugin Executor Service
+ *
+ * This service executes plugins for stewards. Plugins enable custom automated
+ * maintenance tasks via playbooks, scripts, or commands.
+ *
+ * TB-O23a: Plugin System for Stewards
+ *
+ * @module
+ */
+import type { PlaybookId, Timestamp } from '@stoneforge/core';
+import type { QuarryAPI } from '@stoneforge/quarry';
+/**
+ * Plugin type discriminator
+ */
+export type PluginType = 'playbook' | 'script' | 'command';
+/**
+ * All valid plugin type values
+ */
+export declare const PluginTypeValues: readonly ["playbook", "script", "command"];
+/**
+ * Type guard for plugin type
+ */
+export declare function isPluginType(value: unknown): value is PluginType;
+/**
+ * Base plugin configuration shared by all plugin types
+ */
+interface BasePlugin {
+    /** Unique name for this plugin within the steward */
+    readonly name: string;
+    /** Optional description of what this plugin does */
+    readonly description?: string;
+    /** Execution timeout in milliseconds (default: 5 minutes) */
+    readonly timeout?: number;
+    /** Whether to run this plugin on steward startup (default: false) */
+    readonly runOnStartup?: boolean;
+    /** Whether to continue executing subsequent plugins if this one fails (default: true) */
+    readonly continueOnError?: boolean;
+    /** Optional tags for categorizing plugins */
+    readonly tags?: readonly string[];
+}
+/**
+ * Plugin that executes a playbook
+ */
+export interface PlaybookPlugin extends BasePlugin {
+    readonly type: 'playbook';
+    /** The playbook ID to execute */
+    readonly playbookId: PlaybookId;
+    /** Variables to pass to the playbook */
+    readonly variables?: Record<string, string>;
+}
+/**
+ * Plugin that executes a script file
+ */
+export interface ScriptPlugin extends BasePlugin {
+    readonly type: 'script';
+    /** Path to the script (relative to workspace root or absolute) */
+    readonly path: string;
+    /** Arguments to pass to the script */
+    readonly args?: readonly string[];
+    /** Environment variables to set */
+    readonly env?: Record<string, string>;
+    /** Working directory (default: workspace root) */
+    readonly cwd?: string;
+}
+/**
+ * Plugin that executes a CLI command
+ */
+export interface CommandPlugin extends BasePlugin {
+    readonly type: 'command';
+    /** The command to execute (passed to shell) */
+    readonly command: string;
+    /** Working directory (default: workspace root) */
+    readonly cwd?: string;
+    /** Environment variables to set */
+    readonly env?: Record<string, string>;
+}
+/**
+ * Union type for all plugin configurations
+ */
+export type StewardPlugin = PlaybookPlugin | ScriptPlugin | CommandPlugin;
+/**
+ * Type guard for PlaybookPlugin
+ */
+export declare function isPlaybookPlugin(plugin: StewardPlugin): plugin is PlaybookPlugin;
+/**
+ * Type guard for ScriptPlugin
+ */
+export declare function isScriptPlugin(plugin: StewardPlugin): plugin is ScriptPlugin;
+/**
+ * Type guard for CommandPlugin
+ */
+export declare function isCommandPlugin(plugin: StewardPlugin): plugin is CommandPlugin;
+/**
+ * Validates that a value is a valid StewardPlugin
+ */
+export declare function isValidPlugin(value: unknown): value is StewardPlugin;
+/**
+ * Result of executing a single plugin
+ */
+export interface PluginExecutionResult {
+    /** Plugin name */
+    readonly pluginName: string;
+    /** Plugin type */
+    readonly pluginType: PluginType;
+    /** Whether execution succeeded */
+    readonly success: boolean;
+    /** Error message if failed */
+    readonly error?: string;
+    /** Standard output from execution */
+    readonly stdout?: string;
+    /** Standard error from execution */
+    readonly stderr?: string;
+    /** Exit code (for script/command plugins) */
+    readonly exitCode?: number;
+    /** Duration of execution in milliseconds */
+    readonly durationMs: number;
+    /** Items processed (if applicable) */
+    readonly itemsProcessed?: number;
+    /** Timestamp when execution started */
+    readonly startedAt: Timestamp;
+    /** Timestamp when execution completed */
+    readonly completedAt: Timestamp;
+}
+/**
+ * Result of executing multiple plugins
+ */
+export interface BatchPluginExecutionResult {
+    /** Total number of plugins */
+    readonly total: number;
+    /** Number of successful executions */
+    readonly succeeded: number;
+    /** Number of failed executions */
+    readonly failed: number;
+    /** Number of skipped executions */
+    readonly skipped: number;
+    /** Individual plugin results */
+    readonly results: readonly PluginExecutionResult[];
+    /** Total duration in milliseconds */
+    readonly durationMs: number;
+    /** Whether all plugins succeeded */
+    readonly allSucceeded: boolean;
+}
+/**
+ * Options for executing plugins
+ */
+export interface PluginExecutionOptions {
+    /** Working directory for script/command plugins */
+    readonly workspaceRoot?: string;
+    /** Default timeout in milliseconds (default: 5 minutes) */
+    readonly defaultTimeout?: number;
+    /** Additional environment variables */
+    readonly env?: Record<string, string>;
+    /** Context data passed to playbook plugins */
+    readonly context?: Record<string, unknown>;
+    /** Whether to stop on first error (default: false) */
+    readonly stopOnError?: boolean;
+}
+/**
+ * Built-in plugin: Garbage collect ephemeral workflows
+ */
+export declare const GcEphemeralTasksPlugin: CommandPlugin;
+/**
+ * Built-in plugin: Cleanup stale worktrees
+ */
+export declare const CleanupStaleWorktreesPlugin: CommandPlugin;
+/**
+ * Built-in plugin: Garbage collect ephemeral workflows
+ */
+export declare const GcEphemeralWorkflowsPlugin: CommandPlugin;
+/**
+ * Built-in plugin: Health check agents
+ * This is a placeholder - actual implementation would query agent statuses
+ */
+export declare const HealthCheckAgentsPlugin: CommandPlugin;
+/**
+ * All built-in plugins
+ */
+export declare const BuiltInPlugins: Record<string, StewardPlugin>;
+/**
+ * Get a built-in plugin by name
+ */
+export declare function getBuiltInPlugin(name: string): StewardPlugin | undefined;
+/**
+ * List all built-in plugin names
+ */
+export declare function listBuiltInPlugins(): string[];
+/**
+ * Plugin Executor service interface
+ */
+export interface PluginExecutor {
+    /**
+     * Executes a single plugin
+     */
+    execute(plugin: StewardPlugin, options?: PluginExecutionOptions): Promise<PluginExecutionResult>;
+    /**
+     * Executes multiple plugins in sequence
+     */
+    executeBatch(plugins: readonly StewardPlugin[], options?: PluginExecutionOptions): Promise<BatchPluginExecutionResult>;
+    /**
+     * Validates a plugin configuration
+     */
+    validate(plugin: StewardPlugin): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Gets a built-in plugin by name
+     */
+    getBuiltIn(name: string): StewardPlugin | undefined;
+    /**
+     * Lists all built-in plugins
+     */
+    listBuiltIns(): string[];
+}
+/**
+ * Implementation of the Plugin Executor service
+ */
+export declare class PluginExecutorImpl implements PluginExecutor {
+    private readonly api?;
+    private readonly defaultWorkspaceRoot;
+    constructor(options?: {
+        api?: QuarryAPI;
+        workspaceRoot?: string;
+    });
+    execute(plugin: StewardPlugin, options?: PluginExecutionOptions): Promise<PluginExecutionResult>;
+    executeBatch(plugins: readonly StewardPlugin[], options?: PluginExecutionOptions): Promise<BatchPluginExecutionResult>;
+    validate(plugin: StewardPlugin): {
+        valid: boolean;
+        errors: string[];
+    };
+    getBuiltIn(name: string): StewardPlugin | undefined;
+    listBuiltIns(): string[];
+    private executePlaybook;
+    private executeScript;
+    private executeCommand;
+    private runShellCommand;
+}
+/**
+ * Creates a PluginExecutor instance
+ */
+export declare function createPluginExecutor(options?: {
+    api?: QuarryAPI;
+    workspaceRoot?: string;
+}): PluginExecutor;
+export {};
+//# sourceMappingURL=plugin-executor.d.ts.map

package/dist/services/plugin-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-executor.d.ts","sourceRoot":"","sources":["../../src/services/plugin-executor.ts"],"names":[],"mappings":"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"}