@nathapp/nax 0.50.2 → 0.51.0

package/src/pipeline/types.ts

@@ -1,220 +0,0 @@
-/**
- * Pipeline Framework Types
- *
- * Composable stage-based execution pipeline for refactoring the monolithic runner.
- */
-
-import type { AgentResult } from "../agents/types";
-import type { NaxConfig } from "../config/schema";
-import type { ConstitutionResult } from "../constitution/types";
-import type { BuiltContext } from "../context/types";
-import type { PidRegistry } from "../execution/pid-registry";
-import type { HooksConfig } from "../hooks/types";
-import type { InteractionChain } from "../interaction/chain";
-import type { StoryMetrics } from "../metrics/types";
-import type { PluginRegistry } from "../plugins/registry";
-import type { PRD, UserStory } from "../prd/types";
-import type { ReviewResult } from "../review/types";
-import type { FailureCategory } from "../tdd/types";
-import type { VerifyResult } from "../verification/orchestrator-types";
-
-/**
- * Routing result from complexity classification
- */
-export interface RoutingResult {
-  /** Classified complexity */
-  complexity: "simple" | "medium" | "complex" | "expert";
-  /** Selected model tier */
-  modelTier: "fast" | "balanced" | "powerful";
-  /** Test strategy */
-  testStrategy: "test-after" | "tdd-simple" | "three-session-tdd" | "three-session-tdd-lite";
-  /** Reasoning for the classification */
-  reasoning: string;
-  /** Estimated cost for this story */
-  estimatedCost?: number;
-}
-
-/**
- * Pipeline context — shared state passed through all stages.
- *
- * Stages read from and write to this context. It accumulates data
- * as the pipeline progresses through each stage.
- *
- * @example
- * ```ts
- * const ctx: PipelineContext = {
- *   config: loadedConfig,
- *   prd: loadedPRD,
- *   story: currentStory,
- *   stories: [currentStory],
- *   routing: { complexity: "simple", modelTier: "fast", ... },
- *   workdir: "/home/user/project",
- *   hooks: loadedHooks,
- * };
- * ```
- */
-export type AgentGetFn = (name: string) => import("../agents/types").AgentAdapter | undefined;
-
-export interface PipelineContext {
-  /** Ngent configuration */
-  config: NaxConfig;
-  /**
-   * Resolved config for this story's package.
-   * When story.workdir is set, this is root config merged with package config.
-   * When no workdir, this equals ctx.config (root).
-   * Set once per story in the iteration runner before pipeline execution.
-   */
-  effectiveConfig: NaxConfig;
-  /** Full PRD document */
-  prd: PRD;
-  /** Current story (or batch leader) */
-  story: UserStory;
-  /** Batch of stories (length 1 for single-story execution) */
-  stories: UserStory[];
-  /** Routing result from complexity classification */
-  routing: RoutingResult;
-  /** Working directory (project root) */
-  workdir: string;
-  /** Absolute path to the prd.json file (used by routing stage to persist initial classification) */
-  prdPath?: string;
-  /** Feature directory (optional, e.g., nax/features/my-feature/) */
-  featureDir?: string;
-  /** Hooks configuration */
-  hooks: HooksConfig;
-  /** Plugin registry (optional, for plugin-provided extensions) */
-  plugins?: PluginRegistry;
-  /**
-   * Protocol-aware agent resolver. When set (ACP mode), returns AcpAgentAdapter;
-   * falls back to standalone getAgent (CLI mode) when absent.
-   */
-  agentGetFn?: AgentGetFn;
-  /** PID registry for crash recovery — passed through to agent.run() for child process registration. */
-  pidRegistry?: PidRegistry;
-  /** Interaction chain (optional, for human-in-the-loop triggers) */
-  interaction?: InteractionChain;
-  /** Constitution result (set by constitutionStage) */
-  constitution?: ConstitutionResult;
-  /** Context markdown for the agent (set by contextStage) */
-  contextMarkdown?: string;
-  /** Built context with element-level token tracking (set by contextStage) */
-  builtContext?: BuiltContext;
-  /** Final prompt sent to agent (set by promptStage) */
-  prompt?: string;
-  /** Agent execution result (set by executionStage) */
-  agentResult?: AgentResult;
-  /** Verify result (set by verifyStage) */
-  verifyResult?: VerifyResult;
-  /** Review result (set by reviewStage) */
-  reviewResult?: ReviewResult;
-  /** Acceptance test failures (set by acceptanceStage) */
-  acceptanceFailures?: {
-    failedACs: string[];
-    testOutput: string;
-  };
-  /** Story start timestamp (ISO string, set by runner before pipeline) */
-  storyStartTime?: string;
-  /** Tracks how many times the rectify stage has run this pipeline (for event attempt numbers). */
-  rectifyAttempt?: number;
-  /** Tracks how many times the autofix stage has run this pipeline (for event attempt numbers). */
-  autofixAttempt?: number;
-  /** Git HEAD ref captured before agent ran this attempt (FEAT-010: precise smart-runner diff) */
-  storyGitRef?: string;
-  /** Collected story metrics (set by completionStage) */
-  storyMetrics?: StoryMetrics[];
-  /** Whether to retry the story in lite mode after a failure */
-  retryAsLite?: boolean;
-  /** Results from acceptance-setup stage (set by acceptanceSetupStage) */
-  acceptanceSetup?: {
-    totalCriteria: number;
-    testableCount: number;
-    redFailCount: number;
-  };
-  /** Failure category from TDD orchestrator (set by executionStage on TDD failure) */
-  tddFailureCategory?: FailureCategory;
-  /** Set to true when TDD full-suite gate already passed — verify stage skips to avoid redundant run (BUG-054) */
-  fullSuiteGatePassed?: boolean;
-  /** Number of runtime crashes (RUNTIME_CRASH verify status) encountered for this story (BUG-070) */
-  storyRuntimeCrashes?: number;
-  /** Structured review findings from plugin reviewers — passed to escalation for retry context */
-  reviewFindings?: import("../plugins/types").ReviewFinding[];
-  /** Accumulated cost across all prior escalation attempts (BUG-067) */
-  accumulatedAttemptCost?: number;
-}
-
-/**
- * Stage action — determines how the pipeline proceeds after a stage executes.
- */
-export type StageAction =
-  /** Continue to the next stage */
-  | { action: "continue"; cost?: number }
-  /** Skip this story (mark as skipped, don't run further stages) */
-  | { action: "skip"; reason: string; cost?: number }
-  /** Story was decomposed into sub-stories — don't consume an iteration, emit story:decomposed event */
-  | { action: "decomposed"; reason: string; subStoryCount: number; cost?: number }
-  /** Mark story as failed (don't run further stages) */
-  | { action: "fail"; reason: string; cost?: number }
-  /** Escalate to a higher tier and retry the pipeline */
-  | { action: "escalate"; reason?: string; cost?: number }
-  /** Pause execution (user intervention required via queue command) */
-  | { action: "pause"; reason: string; cost?: number }
-  /** Retry from a specific stage (used by rectify/autofix stages) */
-  | { action: "retry"; fromStage: string; cost?: number };
-
-/**
- * Result returned by a pipeline stage after execution.
- */
-export type StageResult = StageAction;
-
-/**
- * A single pipeline stage.
- *
- * Stages are composable units of work that execute sequentially.
- * Each stage can read from and modify the pipeline context, then
- * return an action that determines whether to continue, skip, fail,
- * escalate, or pause.
- *
- * @example
- * ```ts
- * const routingStage: PipelineStage = {
- *   name: "routing",
- *   enabled: (ctx) => true,
- *   execute: async (ctx) => {
- *     const result = await classifyComplexity(ctx.story);
- *     ctx.routing = result;
- *     return { action: "continue" };
- *   },
- * };
- * ```
- */
-export interface PipelineStage {
-  /** Unique stage identifier (e.g., "routing", "execution", "review") */
-  name: string;
-
-  /**
-   * Determines if this stage should run.
-   *
-   * If false, the stage is skipped and the pipeline continues to the next stage.
-   *
-   * @param ctx - Current pipeline context
-   * @returns true if the stage should execute, false to skip
-   */
-  enabled: (ctx: PipelineContext) => boolean;
-
-  /**
-   * Optional human-readable reason why the stage was skipped.
-   * Distinguishes "not needed" (conditions not met) from "disabled" (config).
-   * Used by the pipeline runner for better observability (BUG-055).
-   */
-  skipReason?: (ctx: PipelineContext) => string;
-
-  /**
-   * Execute the stage logic.
-   *
-   * Can read from and modify the pipeline context, then returns a result
-   * that determines how the pipeline should proceed.
-   *
-   * @param ctx - Current pipeline context
-   * @returns Stage result indicating next action
-   */
-  execute: (ctx: PipelineContext) => Promise<StageResult>;
-}

package/src/plugins/extensions.ts

@@ -1,225 +0,0 @@
-/**
- * Plugin extension types
- *
- * Defines interfaces for specific plugin extensions that can be provided.
- */
-
-import type { UserStory } from "../prd/types";
-
-// ============================================================================
-// Review Extension
-// ============================================================================
-
-/**
- * A single structured finding from a review check.
- *
- * Designed to be service-agnostic — works with Semgrep, ESLint, SonarQube,
- * Snyk, CodeQL, and other SAST/DAST/linting tools.
- */
-export interface ReviewFinding {
-  /** Rule or check ID (e.g., "detect-non-literal-regexp", "no-unused-vars") */
-  ruleId: string;
-  /** Severity level (tool-agnostic scale) */
-  severity: "critical" | "error" | "warning" | "info" | "low";
-  /** File path (relative to workdir) */
-  file: string;
-  /** Line number (1-indexed) */
-  line: number;
-  /** Column number (1-indexed, optional) */
-  column?: number;
-  /** End line number (optional, for multi-line findings) */
-  endLine?: number;
-  /** End column number (optional) */
-  endColumn?: number;
-  /** Human-readable message */
-  message: string;
-  /** Optional URL for rule documentation or details */
-  url?: string;
-  /** Source tool that produced this finding (e.g., "semgrep", "eslint", "snyk") */
-  source?: string;
-  /** Finding category (e.g., "security", "performance", "style", "bug") */
-  category?: string;
-}
-
-/**
- * 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;
-  /** Structured findings (optional — plugins can provide machine-readable results) */
-  findings?: ReviewFinding[];
-}
-
-/**
- * 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";
-  runElapsedMs: 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>;
-}

package/src/plugins/index.ts

@@ -1,33 +0,0 @@
-/**
- * Plugin System — Public API
- *
- * Exports all plugin types, interfaces, and loading utilities.
- */
-
-export type {
-  NaxPlugin,
-  PluginType,
-  PluginExtensions,
-  PluginConfigEntry,
-  PluginLogger,
-  IReviewPlugin,
-  ReviewCheckResult,
-  IContextProvider,
-  ContextProviderResult,
-  IReporter,
-  RunStartEvent,
-  StoryCompleteEvent,
-  RunEndEvent,
-} from "./types";
-
-// Re-export optimizer types from optimizer module (via types.ts)
-export type {
-  IPromptOptimizer,
-  PromptOptimizerInput,
-  PromptOptimizerResult,
-} from "./types";
-
-export { validatePlugin } from "./validator";
-export { loadPlugins } from "./loader";
-export { PluginRegistry } from "./registry";
-export { createPluginLogger } from "./plugin-logger";