@nathapp/nax 0.50.2 → 0.51.0

package/src/interaction/plugins/webhook.ts

@@ -1,286 +0,0 @@
-/**
- * Webhook Interaction Plugin (v0.15.0 US-007)
- *
- * Send interaction requests via HTTP POST to configured URL.
- * Start local HTTP server to receive callbacks with HMAC verification.
- */
-
-import { createHmac, timingSafeEqual } from "node:crypto";
-import type { Server } from "node:http";
-import { z } from "zod";
-import type { InteractionPlugin, InteractionRequest, InteractionResponse } from "../types";
-
-/**
- * Injectable sleep — kept for backward compat with existing tests that override it.
- * No longer used internally by receive() (replaced by event-driven delivery).
- * @internal
- */
-export const _webhookPluginDeps = {
-  sleep: (ms: number): Promise<void> => Bun.sleep(ms),
-};
-
-/** Webhook plugin configuration */
-interface WebhookConfig {
-  /** Webhook URL to POST requests to */
-  url?: string;
-  /** Local callback port (default: 8765) */
-  callbackPort?: number;
-  /** HMAC secret for signature verification */
-  secret?: string;
-  /** Maximum payload size in bytes (default: 1MB) */
-  maxPayloadBytes?: number;
-}
-
-/** Zod schema for validating webhook plugin config */
-const WebhookConfigSchema = z.object({
-  url: z.string().url().optional(),
-  callbackPort: z.number().int().min(1024).max(65535).optional(),
-  secret: z.string().optional(),
-  maxPayloadBytes: z.number().int().positive().optional(),
-});
-
-/** Zod schema for validating webhook callback payloads */
-const InteractionResponseSchema = z.object({
-  requestId: z.string(),
-  action: z.enum(["approve", "reject", "choose", "input", "skip", "abort"]),
-  value: z.string().optional(),
-  respondedBy: z.string().optional(),
-  respondedAt: z.number(),
-});
-
-/**
- * Webhook plugin for HTTP-based interaction
- */
-export class WebhookInteractionPlugin implements InteractionPlugin {
-  name = "webhook";
-  private config: WebhookConfig = {};
-  private server: Server | null = null;
-  private serverStartPromise: Promise<void> | null = null;
-  /** Legacy map for responses that arrive before receive() is called */
-  private pendingResponses = new Map<string, InteractionResponse>();
-  /** Event-driven callbacks: requestId → resolve fn (set by receive(), called by handleRequest) */
-  private receiveCallbacks = new Map<string, (response: InteractionResponse) => void>();
-
-  async init(config: Record<string, unknown>): Promise<void> {
-    const cfg = WebhookConfigSchema.parse(config);
-    this.config = {
-      url: cfg.url,
-      callbackPort: cfg.callbackPort ?? 8765,
-      secret: cfg.secret,
-      maxPayloadBytes: cfg.maxPayloadBytes ?? 1024 * 1024, // 1MB default
-    };
-    if (!this.config.url) {
-      throw new Error("Webhook plugin requires 'url' config");
-    }
-  }
-
-  async destroy(): Promise<void> {
-    if (this.server) {
-      await this.stopServer();
-    }
-  }
-
-  async send(request: InteractionRequest): Promise<void> {
-    if (!this.config.url) {
-      throw new Error("Webhook plugin not initialized");
-    }
-
-    const payload = {
-      ...request,
-      callbackUrl: `http://localhost:${this.config.callbackPort}/nax/interact/${request.id}`,
-    };
-
-    const signature = this.config.secret ? this.sign(JSON.stringify(payload)) : undefined;
-
-    const headers: Record<string, string> = {
-      "Content-Type": "application/json",
-    };
-    if (signature) {
-      headers["X-Nax-Signature"] = signature;
-    }
-
-    try {
-      const response = await fetch(this.config.url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(payload),
-      });
-
-      if (!response.ok) {
-        const errorBody = await response.text().catch(() => "");
-        throw new Error(`Webhook POST failed (${response.status}): ${errorBody || response.statusText}`);
-      }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(`Failed to send webhook request: ${msg}`);
-    }
-  }
-
-  async receive(requestId: string, timeout = 60000): Promise<InteractionResponse> {
-    // Start HTTP server to receive callback
-    await this.startServer();
-
-    // Check if a response already arrived before receive() was called
-    const early = this.pendingResponses.get(requestId);
-    if (early) {
-      this.pendingResponses.delete(requestId);
-      return early;
-    }
-
-    // Event-driven: resolve immediately when handleRequest delivers the response
-    return new Promise<InteractionResponse>((resolve) => {
-      const timer = setTimeout(() => {
-        this.receiveCallbacks.delete(requestId);
-        resolve({
-          requestId,
-          action: "skip",
-          respondedBy: "timeout",
-          respondedAt: Date.now(),
-        });
-      }, timeout);
-
-      this.receiveCallbacks.set(requestId, (response) => {
-        clearTimeout(timer);
-        this.receiveCallbacks.delete(requestId);
-        resolve(response);
-      });
-    });
-  }
-
-  async cancel(requestId: string): Promise<void> {
-    this.pendingResponses.delete(requestId);
-    this.receiveCallbacks.delete(requestId);
-  }
-
-  /**
-   * Deliver a response to a waiting receive() callback, or store for later pickup.
-   */
-  private deliverResponse(requestId: string, response: InteractionResponse): void {
-    const cb = this.receiveCallbacks.get(requestId);
-    if (cb) {
-      cb(response);
-    } else {
-      // receive() hasn't been called yet — store for early-pickup path
-      this.pendingResponses.set(requestId, response);
-    }
-  }
-
-  /**
-   * Start HTTP server for callbacks (with mutex to prevent race conditions)
-   */
-  private async startServer(): Promise<void> {
-    if (this.server) return; // Already running
-    if (this.serverStartPromise) {
-      await this.serverStartPromise;
-      return;
-    }
-    this.serverStartPromise = (async () => {
-      const port = this.config.callbackPort ?? 8765;
-      this.server = Bun.serve({
-        port,
-        fetch: (req) => this.handleRequest(req),
-      }) as unknown as Server;
-    })();
-    await this.serverStartPromise;
-    this.serverStartPromise = null;
-  }
-
-  /**
-   * Stop HTTP server
-   */
-  private async stopServer(): Promise<void> {
-    if (!this.server) return;
-
-    // Bun.serve returns a server with stop() method
-    const bunServer = this.server as unknown as { stop: () => void };
-    bunServer.stop();
-    this.server = null;
-    this.serverStartPromise = null;
-  }
-
-  /**
-   * Handle HTTP request
-   */
-  private async handleRequest(req: Request): Promise<Response> {
-    const url = new URL(req.url);
-
-    // Only accept POST to /nax/interact/:requestId
-    if (req.method !== "POST" || !url.pathname.startsWith("/nax/interact/")) {
-      return new Response("Not Found", { status: 404 });
-    }
-
-    const requestId = url.pathname.split("/").pop();
-    if (!requestId) {
-      return new Response("Bad Request", { status: 400 });
-    }
-
-    // Check content length before reading body
-    const contentLength = req.headers.get("Content-Length");
-    const maxBytes = this.config.maxPayloadBytes ?? 1024 * 1024;
-    if (contentLength && Number.parseInt(contentLength, 10) > maxBytes) {
-      return new Response("Payload Too Large", { status: 413 });
-    }
-
-    // Verify signature if secret is configured
-    if (this.config.secret) {
-      const signature = req.headers.get("X-Nax-Signature");
-      const body = await req.text();
-
-      // Check actual body size (in case Content-Length was missing)
-      if (body.length > maxBytes) {
-        return new Response("Payload Too Large", { status: 413 });
-      }
-
-      if (!signature || !this.verify(body, signature)) {
-        return new Response("Unauthorized", { status: 401 });
-      }
-
-      // Parse and validate verified body
-      try {
-        const parsed = JSON.parse(body);
-        const response = InteractionResponseSchema.parse(parsed);
-        this.deliverResponse(requestId, response);
-      } catch {
-        // Sanitize error - do not leak parse/validation details
-        return new Response("Bad Request: Invalid response format", { status: 400 });
-      }
-    } else {
-      // No signature verification - still validate structure
-      try {
-        const parsed = await req.json();
-        const response = InteractionResponseSchema.parse(parsed);
-        this.deliverResponse(requestId, response);
-      } catch {
-        // Sanitize error - do not leak parse/validation details
-        return new Response("Bad Request: Invalid response format", { status: 400 });
-      }
-    }
-
-    return new Response("OK", { status: 200 });
-  }
-
-  /**
-   * Sign payload with HMAC-SHA256
-   */
-  private sign(payload: string): string {
-    if (!this.config.secret) return "";
-    const hmac = createHmac("sha256", this.config.secret);
-    hmac.update(payload);
-    return hmac.digest("hex");
-  }
-
-  /**
-   * Verify HMAC signature
-   */
-  private verify(payload: string, signature: string): boolean {
-    if (!this.config.secret) return false;
-    const expected = this.sign(payload);
-    if (expected.length !== signature.length) return false;
-
-    try {
-      return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
-    } catch {
-      return false;
-    }
-  }
-}

package/src/interaction/state.ts

@@ -1,171 +0,0 @@
-/**
- * State Persistence for Pause/Resume (v0.15.0 US-003)
- *
- * Serializes run state when pausing, loads state when resuming.
- */
-
-import * as path from "node:path";
-import type { InteractionRequest, InteractionResponse } from "./types";
-
-/** Serialized run state for pause/resume */
-export interface RunState {
-  /** Feature name */
-  feature: string;
-  /** PRD path */
-  prdPath: string;
-  /** Current iteration number */
-  iteration: number;
-  /** Accumulated cost (USD) */
-  totalCost: number;
-  /** Stories completed */
-  storiesCompleted: number;
-  /** Pending interactions */
-  pendingInteractions: InteractionRequest[];
-  /** Completed interactions */
-  completedInteractions: Array<{
-    request: InteractionRequest;
-    response: InteractionResponse;
-  }>;
-  /** Pause timestamp */
-  pausedAt: number;
-  /** Pause reason */
-  pauseReason: string;
-  /** Current story ID (if paused mid-story) */
-  currentStoryId?: string;
-  /** Current tier */
-  currentTier?: string;
-  /** Current model */
-  currentModel?: string;
-  /** Arbitrary metadata */
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * Serialize run state to JSON file
- */
-export async function serializeRunState(state: RunState, featureDir: string): Promise<string> {
-  const stateFile = path.join(featureDir, "run-state.json");
-  const json = JSON.stringify(state, null, 2);
-  await Bun.write(stateFile, json);
-  return stateFile;
-}
-
-/**
- * Deserialize run state from JSON file
- */
-export async function deserializeRunState(featureDir: string): Promise<RunState | null> {
-  const stateFile = path.join(featureDir, "run-state.json");
-  try {
-    const file = Bun.file(stateFile);
-    const exists = await file.exists();
-    if (!exists) {
-      return null;
-    }
-    const json = await file.text();
-    const state = JSON.parse(json) as RunState;
-    return state;
-  } catch (err) {
-    // Corrupted or invalid state file
-    return null;
-  }
-}
-
-/**
- * Delete run state file (after successful resume)
- */
-export async function clearRunState(featureDir: string): Promise<void> {
-  const stateFile = path.join(featureDir, "run-state.json");
-  try {
-    await Bun.write(stateFile, ""); // truncate
-    // Note: Bun doesn't have fs.unlink, so we truncate instead
-  } catch {
-    // Ignore errors
-  }
-}
-
-/**
- * Save a pending interaction to the interactions directory
- */
-export async function savePendingInteraction(request: InteractionRequest, featureDir: string): Promise<string> {
-  const interactionsDir = path.join(featureDir, "interactions");
-  // Ensure directory exists
-  await Bun.write(path.join(interactionsDir, ".gitkeep"), "");
-
-  const filename = `${request.id}.json`;
-  const filePath = path.join(interactionsDir, filename);
-  const json = JSON.stringify(request, null, 2);
-  await Bun.write(filePath, json);
-  return filePath;
-}
-
-/**
- * Load a pending interaction from the interactions directory
- */
-export async function loadPendingInteraction(
-  requestId: string,
-  featureDir: string,
-): Promise<InteractionRequest | null> {
-  const interactionsDir = path.join(featureDir, "interactions");
-  const filename = `${requestId}.json`;
-  const filePath = path.join(interactionsDir, filename);
-
-  try {
-    const file = Bun.file(filePath);
-    const exists = await file.exists();
-    if (!exists) {
-      return null;
-    }
-    const json = await file.text();
-    const request = JSON.parse(json) as InteractionRequest;
-    return request;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Delete a pending interaction file (after response received)
- */
-export async function deletePendingInteraction(requestId: string, featureDir: string): Promise<void> {
-  const interactionsDir = path.join(featureDir, "interactions");
-  const filename = `${requestId}.json`;
-  const filePath = path.join(interactionsDir, filename);
-
-  try {
-    await Bun.write(filePath, ""); // truncate
-  } catch {
-    // Ignore errors
-  }
-}
-
-/**
- * List all pending interaction IDs
- */
-export async function listPendingInteractions(featureDir: string): Promise<string[]> {
-  const interactionsDir = path.join(featureDir, "interactions");
-
-  try {
-    const dir = Bun.file(interactionsDir);
-    const exists = await dir.exists();
-    if (!exists) {
-      return [];
-    }
-
-    // Use Bun.spawn to list files
-    const proc = Bun.spawn(["ls", interactionsDir], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const output = await new Response(proc.stdout).text();
-    await proc.exited;
-
-    const files = output
-      .split("\n")
-      .filter((f) => f.endsWith(".json") && f !== ".gitkeep")
-      .map((f) => f.replace(".json", ""));
-
-    return files;
-  } catch {
-    return [];
-  }
-}

package/src/interaction/triggers.ts

@@ -1,250 +0,0 @@
-/**
- * Built-in Triggers Integration (v0.15.0 US-004)
- *
- * Wires 8 built-in triggers into the runner loop and hooks system.
- */
-
-import type { NaxConfig } from "../config";
-import type { InteractionChain } from "./chain";
-import type { InteractionFallback, InteractionRequest, InteractionResponse, TriggerName } from "./types";
-import { TRIGGER_METADATA } from "./types";
-
-/** Trigger context data for template substitution */
-export interface TriggerContext {
-  featureName: string;
-  storyId?: string;
-  cost?: number;
-  limit?: number;
-  tier?: string;
-  model?: string;
-  iteration?: number;
-  reason?: string;
-  [key: string]: unknown;
-}
-
-/**
- * Check if a trigger is enabled in config
- */
-export function isTriggerEnabled(trigger: TriggerName, config: NaxConfig): boolean {
-  const triggerConfig = config.interaction?.triggers?.[trigger];
-  if (triggerConfig === undefined) return false;
-  if (typeof triggerConfig === "boolean") return triggerConfig;
-  return triggerConfig.enabled;
-}
-
-/**
- * Get trigger configuration (fallback, timeout)
- */
-function getTriggerConfig(trigger: TriggerName, config: NaxConfig): { fallback: InteractionFallback; timeout: number } {
-  const metadata = TRIGGER_METADATA[trigger];
-  const triggerConfig = config.interaction?.triggers?.[trigger];
-  const defaults = config.interaction?.defaults ?? {
-    timeout: 600000,
-    fallback: "escalate" as InteractionFallback,
-  };
-
-  let fallback: InteractionFallback = metadata.defaultFallback;
-  let timeout = defaults.timeout;
-
-  if (typeof triggerConfig === "object") {
-    if (triggerConfig.fallback) {
-      fallback = triggerConfig.fallback as InteractionFallback;
-    }
-    if (triggerConfig.timeout) {
-      timeout = triggerConfig.timeout;
-    }
-  }
-
-  return { fallback, timeout };
-}
-
-/**
- * Substitute {{variable}} placeholders in a template string
- */
-function substituteTemplate(template: string, context: TriggerContext): string {
-  let result = template;
-  for (const [key, value] of Object.entries(context)) {
-    if (value !== undefined) {
-      result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), String(value));
-    }
-  }
-  return result;
-}
-
-/**
- * Create an interaction request for a built-in trigger
- */
-export function createTriggerRequest(
-  trigger: TriggerName,
-  context: TriggerContext,
-  config: NaxConfig,
-): InteractionRequest {
-  const metadata = TRIGGER_METADATA[trigger];
-  const { fallback, timeout } = getTriggerConfig(trigger, config);
-
-  const summary = substituteTemplate(metadata.defaultSummary, context);
-  const id = `trigger-${trigger}-${Date.now()}`;
-
-  return {
-    id,
-    type: "confirm",
-    featureName: context.featureName,
-    storyId: context.storyId,
-    stage: "custom",
-    summary,
-    fallback,
-    timeout,
-    createdAt: Date.now(),
-    metadata: {
-      trigger,
-      safety: metadata.safety,
-    },
-  };
-}
-
-/**
- * Execute a trigger and return response
- */
-export async function executeTrigger(
-  trigger: TriggerName,
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<InteractionResponse> {
-  const request = createTriggerRequest(trigger, context, config);
-  const response = await chain.prompt(request);
-  return response;
-}
-
-/**
- * Check security-review trigger (abort on critical issues)
- */
-export async function checkSecurityReview(
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<boolean> {
-  if (!isTriggerEnabled("security-review", config)) return true;
-
-  const response = await executeTrigger("security-review", context, config, chain);
-  return response.action !== "abort";
-}
-
-/**
- * Check cost-exceeded trigger (abort on limit exceeded)
- */
-export async function checkCostExceeded(
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<boolean> {
-  if (!isTriggerEnabled("cost-exceeded", config)) return true;
-
-  const response = await executeTrigger("cost-exceeded", context, config, chain);
-  return response.action !== "abort";
-}
-
-/**
- * Check merge-conflict trigger (abort on conflict)
- */
-export async function checkMergeConflict(
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<boolean> {
-  if (!isTriggerEnabled("merge-conflict", config)) return true;
-
-  const response = await executeTrigger("merge-conflict", context, config, chain);
-  return response.action !== "abort";
-}
-
-/**
- * Check cost-warning trigger (escalate on approaching limit)
- */
-export async function checkCostWarning(
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<"continue" | "escalate"> {
-  if (!isTriggerEnabled("cost-warning", config)) return "continue";
-
-  const response = await executeTrigger("cost-warning", context, config, chain);
-  return response.action === "approve" ? "escalate" : "continue";
-}
-
-/**
- * Check max-retries trigger (skip story on max retries)
- */
-export async function checkMaxRetries(
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<"continue" | "skip"> {
-  if (!isTriggerEnabled("max-retries", config)) return "continue";
-
-  const response = await executeTrigger("max-retries", context, config, chain);
-  return response.action === "skip" ? "skip" : "continue";
-}
-
-/**
- * Check pre-merge trigger (escalate before merging)
- */
-export async function checkPreMerge(
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<boolean> {
-  if (!isTriggerEnabled("pre-merge", config)) return true;
-
-  const response = await executeTrigger("pre-merge", context, config, chain);
-  return response.action === "approve";
-}
-
-/**
- * Check story-ambiguity trigger (continue with best effort)
- */
-export async function checkStoryAmbiguity(
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<boolean> {
-  if (!isTriggerEnabled("story-ambiguity", config)) return true;
-
-  const response = await executeTrigger("story-ambiguity", context, config, chain);
-  return response.action === "approve";
-}
-
-/**
- * Check review-gate trigger (proceed with review)
- */
-export async function checkReviewGate(
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<boolean> {
-  if (!isTriggerEnabled("review-gate", config)) return true;
-
-  const response = await executeTrigger("review-gate", context, config, chain);
-  return response.action === "approve";
-}
-
-/**
- * Check story-oversized trigger (decompose, skip, or continue)
- */
-export async function checkStoryOversized(
-  context: TriggerContext,
-  config: NaxConfig,
-  chain: InteractionChain,
-): Promise<"decompose" | "skip" | "continue"> {
-  if (!isTriggerEnabled("story-oversized", config)) return "continue";
-
-  try {
-    const response = await executeTrigger("story-oversized", context, config, chain);
-    if (response.action === "approve") return "decompose";
-    if (response.action === "skip") return "skip";
-    return "continue";
-  } catch {
-    // No plugin registered or all plugins failed — apply default fallback
-    return "continue";
-  }
-}