@nathapp/nax 0.18.1

package/src/plugins/types.ts

@@ -0,0 +1,327 @@
+/**
+ * Plugin System Types
+ *
+ * Defines the plugin interface and extension point types for the nax plugin system.
+ * Plugins export a NaxPlugin object with extension implementations.
+ */
+
+import type { AgentAdapter } from "../agents/types";
+import type { IPromptOptimizer } from "../optimizer/types";
+import type { UserStory } from "../prd/types";
+import type { RoutingStrategy } from "../routing/strategy";
+
+/**
+ * Extension point types that plugins can provide.
+ */
+export type PluginType = "optimizer" | "router" | "agent" | "reviewer" | "context-provider" | "reporter";
+
+/**
+ * A nax plugin module.
+ *
+ * Plugins export a single NaxPlugin object (default or named export).
+ * Each plugin declares which extension points it provides and supplies
+ * the corresponding implementations.
+ *
+ * @example
+ * ```ts
+ * const myPlugin: NaxPlugin = {
+ *   name: "my-security-scanner",
+ *   version: "1.0.0",
+ *   provides: ["reviewer"],
+ *   async setup(config) {
+ *     // Initialize plugin
+ *   },
+ *   async teardown() {
+ *     // Cleanup
+ *   },
+ *   extensions: {
+ *     reviewer: {
+ *       name: "security-scan",
+ *       description: "Scans for security vulnerabilities",
+ *       async check(workdir, changedFiles) {
+ *         // Perform check
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface NaxPlugin {
+  /** Unique plugin name (e.g., "jira-context", "llmlingua-optimizer") */
+  name: string;
+
+  /** Plugin version (semver) */
+  version: string;
+
+  /** Which extension points this plugin provides */
+  provides: PluginType[];
+
+  /**
+   * Called once when plugin is loaded. Use for initialization,
+   * validating config, establishing connections, etc.
+   *
+   * @param config - Plugin-specific config from nax config.json
+   */
+  setup?(config: Record<string, unknown>): Promise<void>;
+
+  /**
+   * Called when the nax run ends (success or failure).
+   * Use for cleanup, closing connections, flushing buffers.
+   */
+  teardown?(): Promise<void>;
+
+  /**
+   * Extension implementations. Only the types listed in `provides`
+   * are required; others are ignored.
+   */
+  extensions: PluginExtensions;
+}
+
+/**
+ * Extension implementations provided by a plugin.
+ * Only extensions matching the plugin's `provides` array are required.
+ */
+export interface PluginExtensions {
+  /** Custom prompt optimizer */
+  optimizer?: IPromptOptimizer;
+
+  /** Custom routing strategy (inserted into the strategy chain) */
+  router?: RoutingStrategy;
+
+  /** Custom agent adapter (e.g., Codex, Gemini, Aider) */
+  agent?: AgentAdapter;
+
+  /** Custom review check (runs alongside built-in typecheck/lint/test) */
+  reviewer?: IReviewPlugin;
+
+  /** Custom context provider (injects external context into prompts) */
+  contextProvider?: IContextProvider;
+
+  /** Custom reporter (receives run events for dashboards, CI, etc.) */
+  reporter?: IReporter;
+}
+
+// ============================================================================
+// Optimizer Extension
+// ============================================================================
+
+/**
+ * Re-export optimizer types from the optimizer module.
+ * Plugin optimizers use the same interface as built-in optimizers.
+ */
+export type {
+  PromptOptimizerInput,
+  PromptOptimizerResult,
+} from "../optimizer/types";
+export type { IPromptOptimizer } from "../optimizer/types";
+
+// ============================================================================
+// Review Extension
+// ============================================================================
+
+/**
+ * Result from a review check.
+ */
+export interface ReviewCheckResult {
+  /** Whether the review check passed */
+  passed: boolean;
+  /** Human-readable output or error messages */
+  output: string;
+  /** Exit code from the check process (if applicable) */
+  exitCode?: number;
+}
+
+/**
+ * Review plugin interface.
+ *
+ * Review plugins run custom checks after agent execution (e.g., security scans,
+ * license checks, performance tests). Failures trigger retry/escalation.
+ *
+ * @example
+ * ```ts
+ * const reviewer: IReviewPlugin = {
+ *   name: "security-scan",
+ *   description: "Scans for security vulnerabilities",
+ *   async check(workdir, changedFiles) {
+ *     const result = await securityScanner.scan(workdir, changedFiles);
+ *     return {
+ *       passed: result.vulnerabilities.length === 0,
+ *       output: result.report
+ *     };
+ *   }
+ * };
+ * ```
+ */
+export interface IReviewPlugin {
+  /** Check name (e.g., "security-scan", "license-check") */
+  name: string;
+
+  /** Human-readable description */
+  description: string;
+
+  /**
+   * Run the review check against the working directory.
+   *
+   * @param workdir - Project root directory
+   * @param changedFiles - Files modified by the agent in this story
+   * @returns Review check result
+   */
+  check(workdir: string, changedFiles: string[]): Promise<ReviewCheckResult>;
+}
+
+// ============================================================================
+// Context Provider Extension
+// ============================================================================
+
+/**
+ * Result from a context provider.
+ */
+export interface ContextProviderResult {
+  /** Markdown content to inject */
+  content: string;
+  /** Token estimate for budget tracking */
+  estimatedTokens: number;
+  /** Section label in the prompt (e.g., "Jira Context") */
+  label: string;
+}
+
+/**
+ * Context provider interface.
+ *
+ * Context providers fetch external data (Jira tickets, Confluence docs,
+ * Linear issues, etc.) and inject it into agent prompts.
+ *
+ * @example
+ * ```ts
+ * const provider: IContextProvider = {
+ *   name: "jira",
+ *   async getContext(story) {
+ *     const ticket = await jiraApi.getTicket(story.tags[0]);
+ *     return {
+ *       content: `## ${ticket.key}\n\n${ticket.description}`,
+ *       estimatedTokens: estimateTokens(ticket.description),
+ *       label: "Jira Context"
+ *     };
+ *   }
+ * };
+ * ```
+ */
+export interface IContextProvider {
+  /** Provider name (e.g., "jira", "linear", "confluence") */
+  name: string;
+
+  /**
+   * Fetch external context relevant to a story.
+   *
+   * @param story - The user story being executed
+   * @returns Markdown content to inject into the agent prompt
+   */
+  getContext(story: UserStory): Promise<ContextProviderResult>;
+}
+
+// ============================================================================
+// Reporter Extension
+// ============================================================================
+
+/**
+ * Event emitted when a run starts.
+ */
+export interface RunStartEvent {
+  runId: string;
+  feature: string;
+  totalStories: number;
+  startTime: string;
+}
+
+/**
+ * Event emitted when a story completes.
+ */
+export interface StoryCompleteEvent {
+  runId: string;
+  storyId: string;
+  status: "completed" | "failed" | "skipped" | "paused";
+  durationMs: number;
+  cost: number;
+  tier: string;
+  testStrategy: string;
+}
+
+/**
+ * Event emitted when a run ends.
+ */
+export interface RunEndEvent {
+  runId: string;
+  totalDurationMs: number;
+  totalCost: number;
+  storySummary: {
+    completed: number;
+    failed: number;
+    skipped: number;
+    paused: number;
+  };
+}
+
+/**
+ * Reporter interface.
+ *
+ * Reporters receive run lifecycle events and can emit them to external
+ * systems (dashboards, Slack, CI, databases, etc.).
+ *
+ * All reporter methods are fire-and-forget — failures are logged but
+ * never block the pipeline.
+ *
+ * @example
+ * ```ts
+ * const reporter: IReporter = {
+ *   name: "telegram",
+ *   async onRunStart(event) {
+ *     await telegram.send(`Started ${event.feature}`);
+ *   },
+ *   async onStoryComplete(event) {
+ *     await telegram.send(`${event.storyId} ${event.status}`);
+ *   },
+ *   async onRunEnd(event) {
+ *     await telegram.send(`Completed ${event.storySummary.completed} stories`);
+ *   }
+ * };
+ * ```
+ */
+export interface IReporter {
+  /** Reporter name */
+  name: string;
+
+  /** Called when a run starts */
+  onRunStart?(event: RunStartEvent): Promise<void>;
+
+  /** Called when a story completes (success or failure) */
+  onStoryComplete?(event: StoryCompleteEvent): Promise<void>;
+
+  /** Called when a run ends */
+  onRunEnd?(event: RunEndEvent): Promise<void>;
+}
+
+// ============================================================================
+// Plugin Config
+// ============================================================================
+
+/**
+ * Plugin configuration entry from nax config.json.
+ *
+ * @example
+ * ```json
+ * {
+ *   "plugins": [
+ *     {
+ *       "module": "./nax/plugins/my-plugin",
+ *       "config": { "apiKey": "secret" }
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export interface PluginConfigEntry {
+  /** Module path or npm package name */
+  module: string;
+  /** Plugin-specific configuration */
+  config?: Record<string, unknown>;
+}

package/src/plugins/validator.ts

@@ -0,0 +1,352 @@
+/**
+ * Plugin Validator
+ *
+ * Runtime type checking for plugin modules.
+ * Validates plugin shape and ensures all required extensions are present.
+ */
+
+import { getLogger } from "../logger";
+import type { NaxPlugin, PluginType } from "./types";
+
+/**
+ * Safely get logger instance, returns null if not initialized
+ */
+function getSafeLogger() {
+  try {
+    return getLogger();
+  } catch {
+    return null;
+  }
+}
+
+const VALID_PLUGIN_TYPES: readonly PluginType[] = [
+  "optimizer",
+  "router",
+  "agent",
+  "reviewer",
+  "context-provider",
+  "reporter",
+] as const;
+
+/**
+ * Validate a plugin module at runtime.
+ *
+ * Returns the plugin if valid, null if invalid (with warning logged).
+ *
+ * @param module - The module to validate (can be any type)
+ * @returns The validated plugin or null
+ */
+export function validatePlugin(module: unknown): NaxPlugin | null {
+  // Must be an object
+  if (typeof module !== "object" || module === null) {
+    getSafeLogger()?.warn("plugins", "Plugin validation failed: module is not an object");
+    return null;
+  }
+
+  const plugin = module as Record<string, unknown>;
+
+  // Validate name
+  if (typeof plugin.name !== "string") {
+    getSafeLogger()?.warn("plugins", "Plugin validation failed: missing or invalid 'name' (must be string)");
+    return null;
+  }
+
+  // Validate version
+  if (typeof plugin.version !== "string") {
+    getSafeLogger()?.warn(
+      "plugins",
+      `Plugin '${plugin.name}' validation failed: missing or invalid 'version' (must be string)`,
+    );
+    return null;
+  }
+
+  // Validate provides
+  if (!Array.isArray(plugin.provides)) {
+    getSafeLogger()?.warn("plugins", `Plugin '${plugin.name}' validation failed: 'provides' must be an array`);
+    return null;
+  }
+
+  if (plugin.provides.length === 0) {
+    getSafeLogger()?.warn("plugins", `Plugin '${plugin.name}' validation failed: 'provides' must not be empty`);
+    return null;
+  }
+
+  for (const type of plugin.provides) {
+    if (!VALID_PLUGIN_TYPES.includes(type as PluginType)) {
+      getSafeLogger()?.warn(
+        "plugins",
+        `Plugin '${plugin.name}' validation failed: invalid plugin type '${type}' in 'provides'`,
+      );
+      return null;
+    }
+  }
+
+  // Validate setup (optional)
+  if ("setup" in plugin && typeof plugin.setup !== "function") {
+    getSafeLogger()?.warn("plugins", `Plugin '${plugin.name}' validation failed: 'setup' must be a function`);
+    return null;
+  }
+
+  // Validate teardown (optional)
+  if ("teardown" in plugin && typeof plugin.teardown !== "function") {
+    getSafeLogger()?.warn("plugins", `Plugin '${plugin.name}' validation failed: 'teardown' must be a function`);
+    return null;
+  }
+
+  // Validate extensions
+  if (typeof plugin.extensions !== "object" || plugin.extensions === null) {
+    getSafeLogger()?.warn("plugins", `Plugin '${plugin.name}' validation failed: 'extensions' must be an object`);
+    return null;
+  }
+
+  const extensions = plugin.extensions as Record<string, unknown>;
+
+  // Validate each extension type in provides
+  for (const type of plugin.provides) {
+    const isValid = validateExtension(plugin.name as string, type as PluginType, extensions);
+    if (!isValid) {
+      return null;
+    }
+  }
+
+  return plugin as unknown as NaxPlugin;
+}
+
+/**
+ * Validate a specific extension type.
+ *
+ * @param pluginName - Plugin name (for error messages)
+ * @param type - Extension type to validate
+ * @param extensions - Extensions object
+ * @returns Whether the extension is valid
+ */
+function validateExtension(pluginName: string, type: PluginType, extensions: Record<string, unknown>): boolean {
+  switch (type) {
+    case "optimizer":
+      return validateOptimizer(pluginName, extensions.optimizer);
+    case "router":
+      return validateRouter(pluginName, extensions.router);
+    case "agent":
+      return validateAgent(pluginName, extensions.agent);
+    case "reviewer":
+      return validateReviewer(pluginName, extensions.reviewer);
+    case "context-provider":
+      return validateContextProvider(pluginName, extensions.contextProvider);
+    case "reporter":
+      return validateReporter(pluginName, extensions.reporter);
+    default:
+      getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: unknown extension type '${type}'`);
+      return false;
+  }
+}
+
+/**
+ * Validate optimizer extension.
+ */
+function validateOptimizer(pluginName: string, optimizer: unknown): boolean {
+  if (typeof optimizer !== "object" || optimizer === null) {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: optimizer extension must be an object`);
+    return false;
+  }
+
+  const opt = optimizer as Record<string, unknown>;
+
+  if (typeof opt.name !== "string") {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: optimizer.name must be a string`);
+    return false;
+  }
+
+  if (typeof opt.optimize !== "function") {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: optimizer.optimize must be a function`);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validate router extension.
+ */
+function validateRouter(pluginName: string, router: unknown): boolean {
+  if (typeof router !== "object" || router === null) {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: router extension must be an object`);
+    return false;
+  }
+
+  const rtr = router as Record<string, unknown>;
+
+  if (typeof rtr.name !== "string") {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: router.name must be a string`);
+    return false;
+  }
+
+  if (typeof rtr.route !== "function") {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: router.route must be a function`);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validate agent extension.
+ */
+function validateAgent(pluginName: string, agent: unknown): boolean {
+  if (typeof agent !== "object" || agent === null) {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: agent extension must be an object`);
+    return false;
+  }
+
+  const agt = agent as Record<string, unknown>;
+
+  const requiredFields = [
+    { name: "name", type: "string" },
+    { name: "displayName", type: "string" },
+    { name: "binary", type: "string" },
+    { name: "capabilities", type: "object" },
+    { name: "isInstalled", type: "function" },
+    { name: "run", type: "function" },
+    { name: "buildCommand", type: "function" },
+    { name: "plan", type: "function" },
+    { name: "decompose", type: "function" },
+  ];
+
+  for (const field of requiredFields) {
+    if (field.type === "object") {
+      if (typeof agt[field.name] !== "object" || agt[field.name] === null) {
+        getSafeLogger()?.warn(
+          "plugins",
+          `Plugin '${pluginName}' validation failed: agent.${field.name} must be an object`,
+        );
+        return false;
+      }
+    } else {
+      // Validate field.type is a valid typeof result before comparison
+      const expectedType = field.type as string;
+
+      // Use explicit type checks instead of dynamic typeof comparison
+      let isValid = false;
+      if (expectedType === "string") {
+        isValid = typeof agt[field.name] === "string";
+      } else if (expectedType === "number") {
+        isValid = typeof agt[field.name] === "number";
+      } else if (expectedType === "boolean") {
+        isValid = typeof agt[field.name] === "boolean";
+      } else if (expectedType === "symbol") {
+        isValid = typeof agt[field.name] === "symbol";
+      } else if (expectedType === "undefined") {
+        isValid = typeof agt[field.name] === "undefined";
+      } else if (expectedType === "function") {
+        isValid = typeof agt[field.name] === "function";
+      } else if (expectedType === "bigint") {
+        isValid = typeof agt[field.name] === "bigint";
+      } else {
+        getSafeLogger()?.warn(
+          "plugins",
+          `Plugin '${pluginName}' validation failed: invalid type constraint '${expectedType}'`,
+        );
+        return false;
+      }
+
+      if (!isValid) {
+        getSafeLogger()?.warn(
+          "plugins",
+          `Plugin '${pluginName}' validation failed: agent.${field.name} must be a ${expectedType}`,
+        );
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Validate reviewer extension.
+ */
+function validateReviewer(pluginName: string, reviewer: unknown): boolean {
+  if (typeof reviewer !== "object" || reviewer === null) {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: reviewer extension must be an object`);
+    return false;
+  }
+
+  const rev = reviewer as Record<string, unknown>;
+
+  if (typeof rev.name !== "string") {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: reviewer.name must be a string`);
+    return false;
+  }
+
+  if (typeof rev.description !== "string") {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: reviewer.description must be a string`);
+    return false;
+  }
+
+  if (typeof rev.check !== "function") {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: reviewer.check must be a function`);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validate context-provider extension.
+ */
+function validateContextProvider(pluginName: string, provider: unknown): boolean {
+  if (typeof provider !== "object" || provider === null) {
+    getSafeLogger()?.warn(
+      "plugins",
+      `Plugin '${pluginName}' validation failed: contextProvider extension must be an object`,
+    );
+    return false;
+  }
+
+  const prov = provider as Record<string, unknown>;
+
+  if (typeof prov.name !== "string") {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: contextProvider.name must be a string`);
+    return false;
+  }
+
+  if (typeof prov.getContext !== "function") {
+    getSafeLogger()?.warn(
+      "plugins",
+      `Plugin '${pluginName}' validation failed: contextProvider.getContext must be a function`,
+    );
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validate reporter extension.
+ */
+function validateReporter(pluginName: string, reporter: unknown): boolean {
+  if (typeof reporter !== "object" || reporter === null) {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: reporter extension must be an object`);
+    return false;
+  }
+
+  const rep = reporter as Record<string, unknown>;
+
+  if (typeof rep.name !== "string") {
+    getSafeLogger()?.warn("plugins", `Plugin '${pluginName}' validation failed: reporter.name must be a string`);
+    return false;
+  }
+
+  // At least one event handler is optional, but all must be functions if present
+  const eventHandlers = ["onRunStart", "onStoryComplete", "onRunEnd"];
+  for (const handler of eventHandlers) {
+    if (handler in rep && typeof rep[handler] !== "function") {
+      getSafeLogger()?.warn(
+        "plugins",
+        `Plugin '${pluginName}' validation failed: reporter.${handler} must be a function`,
+      );
+      return false;
+    }
+  }
+
+  return true;
+}