@nathapp/nax 0.18.1

package/src/hooks/runner.ts

@@ -0,0 +1,286 @@
+/**
+ * Hook Runner
+ *
+ * Loads hooks.json and executes hooks at lifecycle events.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getLogger } from "../logger";
+import type { HookContext, HookDef, HookEvent, HooksConfig } from "./types";
+
+const DEFAULT_TIMEOUT = 5000;
+
+/** Extended hooks config that tracks global vs project hooks */
+export interface LoadedHooksConfig extends HooksConfig {
+  /** Global hooks (loaded from ~/.nax/hooks.json) */
+  _global?: HooksConfig;
+  /** Whether global hooks were skipped */
+  _skipGlobal?: boolean;
+}
+
+/**
+ * Load hooks config from global and project paths.
+ *
+ * Both global and project hooks are preserved independently (not merged).
+ * The skipGlobal flag in project config disables global hook loading.
+ *
+ * @param projectDir - Project nax directory path
+ * @param globalDir - Global nax directory path (optional)
+ * @returns Merged hooks config with both global and project hooks
+ */
+export async function loadHooksConfig(projectDir: string, globalDir?: string): Promise<LoadedHooksConfig> {
+  let globalHooks: HooksConfig = { hooks: {} };
+  let projectHooks: HooksConfig = { hooks: {} };
+  let skipGlobal = false;
+
+  // Load project hooks first to check skipGlobal flag
+  const projectPath = join(projectDir, "hooks.json");
+  if (existsSync(projectPath)) {
+    try {
+      const projectData = await Bun.file(projectPath).json();
+      projectHooks = projectData as HooksConfig;
+      // Check if project config has skipGlobal flag
+      skipGlobal = (projectData as { skipGlobal?: boolean }).skipGlobal ?? false;
+    } catch (err) {
+      const logger = getLogger();
+      logger.warn("hooks", "Failed to parse project hooks.json", { path: projectPath, error: String(err) });
+    }
+  }
+
+  // Load global hooks only if not skipped
+  if (!skipGlobal && globalDir) {
+    const globalPath = join(globalDir, "hooks.json");
+    if (existsSync(globalPath)) {
+      try {
+        const globalData = await Bun.file(globalPath).json();
+        globalHooks = globalData as HooksConfig;
+      } catch (err) {
+        const logger = getLogger();
+        logger.warn("hooks", "Failed to parse global hooks.json", { path: globalPath, error: String(err) });
+      }
+    }
+  }
+
+  // Return project hooks as the main config, with global hooks stored separately
+  return {
+    ...projectHooks,
+    _global: skipGlobal ? undefined : globalHooks,
+    _skipGlobal: skipGlobal,
+  };
+}
+
+/**
+ * Escape environment variable values to prevent injection
+ * @param value - Raw value to escape
+ * @returns Escaped value safe for subprocess environment
+ */
+function escapeEnvValue(value: string): string {
+  // Remove null bytes and newlines that could cause issues
+  return value.replace(/\0/g, "").replace(/\n/g, " ").replace(/\r/g, "");
+}
+
+/**
+ * Build environment variables from hook context
+ * All values are escaped to prevent injection attacks
+ */
+function buildEnv(ctx: HookContext): Record<string, string> {
+  const env: Record<string, string> = {
+    NAX_EVENT: escapeEnvValue(ctx.event),
+    NAX_FEATURE: escapeEnvValue(ctx.feature),
+  };
+
+  if (ctx.storyId) env.NAX_STORY_ID = escapeEnvValue(ctx.storyId);
+  if (ctx.status) env.NAX_STATUS = escapeEnvValue(ctx.status);
+  if (ctx.reason) env.NAX_REASON = escapeEnvValue(ctx.reason);
+  if (ctx.cost !== undefined) env.NAX_COST = ctx.cost.toFixed(4);
+  if (ctx.model) env.NAX_MODEL = escapeEnvValue(ctx.model);
+  if (ctx.agent) env.NAX_AGENT = escapeEnvValue(ctx.agent);
+  if (ctx.iteration !== undefined) env.NAX_ITERATION = String(ctx.iteration);
+
+  return env;
+}
+
+/**
+ * Detect shell operators that indicate shell interpolation
+ * @param command - Command string to check
+ * @returns true if shell operators detected
+ */
+function hasShellOperators(command: string): boolean {
+  // Check for common shell operators that require shell interpretation
+  const shellOperators = /[|&;$`<>(){}]/;
+  return shellOperators.test(command);
+}
+
+/**
+ * Validate hook command for injection patterns
+ * @param command - Command string to validate
+ * @throws Error if obvious injection pattern detected
+ */
+function validateHookCommand(command: string): void {
+  // Reject commands with obvious injection patterns
+  const dangerousPatterns = [
+    /\$\(.*\)/, // Command substitution $(...)
+    /`.*`/, // Backtick command substitution
+    /\|\s*bash/, // Piping to bash
+    /\|\s*sh/, // Piping to sh
+    /;\s*rm\s+-rf/, // Dangerous deletion
+    /&&\s*rm\s+-rf/, // Dangerous deletion after success
+    /\beval\s+/, // SEC-3 fix: eval command
+    /curl\s+[^|]*\|\s*/, // SEC-3 fix: curl piping
+    /python\s+-c/, // SEC-3 fix: python -c execution
+  ];
+
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(command)) {
+      throw new Error(`Hook command contains dangerous pattern: ${pattern.source}`);
+    }
+  }
+}
+
+/**
+ * Parse command string into argv array
+ * Simple space-based splitting (does not handle complex quoting)
+ * @param command - Command string
+ * @returns Array of command and arguments
+ */
+function parseCommandToArgv(command: string): string[] {
+  return command.trim().split(/\s+/);
+}
+
+/**
+ * Execute a single hook
+ *
+ * SECURITY WARNING: Hook commands are executed as subprocesses.
+ * - Commands are parsed into argv arrays to avoid shell injection
+ * - Shell operators (|, &&, ;, $, etc.) trigger a security warning
+ * - Obvious injection patterns are rejected
+ * - Environment variables are escaped
+ * - Only configure hooks from trusted sources
+ *
+ * @param hookDef - Hook definition from config
+ * @param ctx - Hook context with environment variables
+ * @param workdir - Working directory for command execution
+ * @returns Promise with success status and output
+ */
+async function executeHook(
+  hookDef: HookDef,
+  ctx: HookContext,
+  workdir: string,
+): Promise<{ success: boolean; output: string }> {
+  if (hookDef.enabled === false) {
+    return { success: true, output: "(disabled)" };
+  }
+
+  // Validate command for injection patterns
+  try {
+    validateHookCommand(hookDef.command);
+  } catch (err) {
+    return {
+      success: false,
+      output: `Security validation failed: ${err}`,
+    };
+  }
+
+  // Warn if shell operators detected
+  const logger = getLogger();
+  if (hasShellOperators(hookDef.command)) {
+    logger.warn("hooks", "[SECURITY] Hook command contains shell operators", {
+      command: hookDef.command,
+      warning: "Shell operators may enable injection attacks. Consider using simple commands only.",
+    });
+  }
+
+  const timeout = hookDef.timeout ?? DEFAULT_TIMEOUT;
+  const env = buildEnv(ctx);
+
+  // Pass full context as JSON via stdin
+  const contextJson = JSON.stringify(ctx);
+
+  // Parse command to argv array (no shell interpolation)
+  const argv = parseCommandToArgv(hookDef.command);
+  if (argv.length === 0) {
+    return { success: false, output: "Empty command" };
+  }
+
+  const proc = Bun.spawn(argv, {
+    cwd: workdir,
+    stdin: new Response(contextJson),
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, ...env },
+  });
+
+  // Timeout handling
+  const timeoutId = setTimeout(() => {
+    proc.kill("SIGTERM");
+  }, timeout);
+
+  const exitCode = await proc.exited;
+  clearTimeout(timeoutId);
+
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+
+  const output = (stdout + stderr).trim();
+
+  // Check if process was killed by timeout
+  if (exitCode !== 0 && output === "") {
+    return {
+      success: false,
+      output: `Hook timed out after ${timeout}ms`,
+    };
+  }
+
+  return {
+    success: exitCode === 0,
+    output,
+  };
+}
+
+/**
+ * Fire a hook event for both global and project hooks.
+ *
+ * Both hooks fire independently - global failure doesn't block project hook.
+ *
+ * @param config - Loaded hooks config (contains both global and project hooks)
+ * @param event - Hook event name
+ * @param ctx - Hook context
+ * @param workdir - Working directory
+ */
+export async function fireHook(
+  config: LoadedHooksConfig,
+  event: HookEvent,
+  ctx: HookContext,
+  workdir: string,
+): Promise<void> {
+  const logger = getLogger();
+
+  // Fire global hook first (if present and not skipped)
+  if (config._global && !config._skipGlobal) {
+    const globalHookDef = config._global.hooks[event];
+    if (globalHookDef && globalHookDef.enabled !== false) {
+      try {
+        const result = await executeHook(globalHookDef, { ...ctx, event }, workdir);
+        if (!result.success) {
+          logger.warn("hooks", `Global hook ${event} failed`, { event, output: result.output });
+        }
+      } catch (err) {
+        logger.warn("hooks", `Global hook ${event} error`, { event, error: String(err) });
+      }
+    }
+  }
+
+  // Fire project hook (independent of global hook result)
+  const projectHookDef = config.hooks[event];
+  if (projectHookDef && projectHookDef.enabled !== false) {
+    try {
+      const result = await executeHook(projectHookDef, { ...ctx, event }, workdir);
+      if (!result.success) {
+        logger.warn("hooks", `Project hook ${event} failed`, { event, output: result.output });
+      }
+    } catch (err) {
+      logger.warn("hooks", `Project hook ${event} error`, { event, error: String(err) });
+    }
+  }
+}

package/src/hooks/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Hook System Types
+ *
+ * Script-based lifecycle hooks configured via hooks.json.
+ */
+
+/** All supported hook events */
+export type HookEvent =
+  | "on-start"
+  | "on-story-start"
+  | "on-story-complete"
+  | "on-story-fail"
+  | "on-pause"
+  | "on-resume"
+  | "on-session-end"
+  | "on-complete"
+  | "on-error";
+
+/** Single hook definition */
+export interface HookDef {
+  /** Command to execute */
+  command: string;
+  /** Timeout in milliseconds (default: 5000) */
+  timeout?: number;
+  /** Whether this hook is enabled (default: true) */
+  enabled?: boolean;
+  /** Interaction prompt (v0.15.0) */
+  interaction?: {
+    /** Interaction type */
+    type: "confirm" | "choose" | "input" | "review" | "notify";
+    /** Summary template (supports {{variable}} syntax) */
+    summary: string;
+    /** Detail template (optional) */
+    detail?: string;
+    /** Fallback behavior on timeout */
+    fallback: "continue" | "skip" | "escalate" | "abort";
+    /** Timeout in milliseconds (optional) */
+    timeout?: number;
+  };
+}
+
+/** hooks.json schema */
+export interface HooksConfig {
+  hooks: Partial<Record<HookEvent, HookDef>>;
+}
+
+/** Context passed to hooks via environment variables */
+export interface HookContext {
+  /** Event name */
+  event: HookEvent;
+  /** Feature name */
+  feature: string;
+  /** Current story ID */
+  storyId?: string;
+  /** Status (pass/fail/paused/error) */
+  status?: string;
+  /** Reason for pause/error */
+  reason?: string;
+  /** Accumulated cost (USD) */
+  cost?: number;
+  /** Current model */
+  model?: string;
+  /** Current agent */
+  agent?: string;
+  /** Current iteration number */
+  iteration?: number;
+}

package/src/interaction/chain.ts

@@ -0,0 +1,154 @@
+/**
+ * Interaction Plugin Chain (v0.15.0)
+ *
+ * Manages plugin priority, fallback cascade, and request routing.
+ */
+
+import type { InteractionFallback, InteractionPlugin, InteractionRequest, InteractionResponse } from "./types";
+
+/** Plugin chain entry */
+interface ChainEntry {
+  plugin: InteractionPlugin;
+  priority: number;
+}
+
+/** Plugin chain configuration */
+export interface ChainConfig {
+  /** Default timeout for all requests (ms) */
+  defaultTimeout: number;
+  /** Default fallback behavior */
+  defaultFallback: InteractionFallback;
+}
+
+/**
+ * Interaction plugin chain with priority and fallback cascade
+ */
+export class InteractionChain {
+  private plugins: ChainEntry[] = [];
+  private config: ChainConfig;
+
+  constructor(config: ChainConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Register a plugin with priority (higher = earlier in chain)
+   */
+  register(plugin: InteractionPlugin, priority = 0): void {
+    this.plugins.push({ plugin, priority });
+    this.plugins.sort((a, b) => b.priority - a.priority); // descending
+  }
+
+  /**
+   * Get primary plugin (highest priority)
+   */
+  getPrimary(): InteractionPlugin | null {
+    return this.plugins[0]?.plugin ?? null;
+  }
+
+  /**
+   * Send interaction request through the chain
+   */
+  async send(request: InteractionRequest): Promise<void> {
+    const plugin = this.getPrimary();
+    if (!plugin) {
+      throw new Error("No interaction plugin registered");
+    }
+    await plugin.send(request);
+  }
+
+  /**
+   * Receive interaction response with timeout and fallback cascade
+   */
+  async receive(requestId: string, timeout?: number): Promise<InteractionResponse> {
+    if (this.plugins.length === 0) {
+      throw new Error("No interaction plugin registered");
+    }
+
+    const timeoutMs = timeout ?? this.config.defaultTimeout;
+    const errors: Error[] = [];
+
+    // Try each plugin in priority order (fallback cascade)
+    for (const entry of this.plugins) {
+      try {
+        const response = await entry.plugin.receive(requestId, timeoutMs);
+        return response;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        errors.push(error);
+        // Continue to next plugin
+      }
+    }
+
+    // All plugins failed - throw with all error messages
+    const errorMessages = errors.map((e) => e.message).join("; ");
+    throw new Error(`All interaction plugins failed: ${errorMessages}`);
+  }
+
+  /**
+   * Send and receive in one call (convenience method)
+   */
+  async prompt(request: InteractionRequest): Promise<InteractionResponse> {
+    await this.send(request);
+    const response = await this.receive(request.id, request.timeout);
+    return response;
+  }
+
+  /**
+   * Cancel a pending interaction
+   */
+  async cancel(requestId: string): Promise<void> {
+    const plugin = this.getPrimary();
+    if (plugin?.cancel) {
+      await plugin.cancel(requestId);
+    }
+  }
+
+  /**
+   * Initialize all plugins
+   */
+  async init(pluginConfigs: Record<string, Record<string, unknown>>): Promise<void> {
+    for (const entry of this.plugins) {
+      if (entry.plugin.init) {
+        const config = pluginConfigs[entry.plugin.name] ?? {};
+        await entry.plugin.init(config);
+      }
+    }
+  }
+
+  /**
+   * Destroy all plugins
+   */
+  async destroy(): Promise<void> {
+    for (const entry of this.plugins) {
+      if (entry.plugin.destroy) {
+        await entry.plugin.destroy();
+      }
+    }
+  }
+
+  /**
+   * Apply fallback behavior to get final action
+   */
+  applyFallback(response: InteractionResponse, fallback: InteractionFallback): InteractionAction {
+    // If user responded explicitly, use their action
+    if (response.respondedBy !== "timeout" && response.respondedBy !== "system") {
+      return response.action;
+    }
+
+    // Otherwise apply fallback
+    switch (fallback) {
+      case "continue":
+        return "approve";
+      case "skip":
+        return "skip";
+      case "escalate":
+        return "approve"; // proceed but escalate tier
+      case "abort":
+        return "abort";
+    }
+  }
+}
+
+/** Convenience type for action */
+type InteractionAction = InteractionResponse["action"];

package/src/interaction/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Interaction System — Barrel Exports (v0.15.0)
+ */
+
+// Types
+export type {
+  InteractionType,
+  InteractionStage,
+  InteractionFallback,
+  InteractionRequest,
+  InteractionAction,
+  InteractionResponse,
+  InteractionPlugin,
+  TriggerName,
+  TriggerConfig,
+  TriggerSafety,
+  TriggerMetadata,
+} from "./types";
+export { TRIGGER_METADATA } from "./types";
+
+// Chain
+export { InteractionChain } from "./chain";
+export type { ChainConfig } from "./chain";
+
+// State persistence
+export {
+  serializeRunState,
+  deserializeRunState,
+  clearRunState,
+  savePendingInteraction,
+  loadPendingInteraction,
+  deletePendingInteraction,
+  listPendingInteractions,
+} from "./state";
+export type { RunState } from "./state";
+
+// Plugins
+export { CLIInteractionPlugin } from "./plugins/cli";
+export { TelegramInteractionPlugin } from "./plugins/telegram";
+export { WebhookInteractionPlugin } from "./plugins/webhook";
+export { AutoInteractionPlugin } from "./plugins/auto";
+
+// Triggers
+export {
+  isTriggerEnabled,
+  createTriggerRequest,
+  executeTrigger,
+  checkSecurityReview,
+  checkCostExceeded,
+  checkMergeConflict,
+  checkCostWarning,
+  checkMaxRetries,
+  checkPreMerge,
+  checkStoryAmbiguity,
+  checkReviewGate,
+} from "./triggers";
+export type { TriggerContext } from "./triggers";
+
+// Initialization
+export { initInteractionChain } from "./init";

package/src/interaction/init.ts

@@ -0,0 +1,83 @@
+/**
+ * Interaction Chain Initialization Helper
+ *
+ * Creates and initializes interaction chain from config.
+ */
+
+import type { NaxConfig } from "../config";
+import { getSafeLogger } from "../logger";
+import { InteractionChain } from "./chain";
+import { AutoInteractionPlugin } from "./plugins/auto";
+import { CLIInteractionPlugin } from "./plugins/cli";
+import { TelegramInteractionPlugin } from "./plugins/telegram";
+import { WebhookInteractionPlugin } from "./plugins/webhook";
+import type { InteractionPlugin } from "./types";
+
+/**
+ * Create interaction plugin based on config
+ */
+function createInteractionPlugin(pluginName: string): InteractionPlugin {
+  switch (pluginName) {
+    case "cli":
+      return new CLIInteractionPlugin();
+    case "telegram":
+      return new TelegramInteractionPlugin();
+    case "webhook":
+      return new WebhookInteractionPlugin();
+    case "auto":
+      return new AutoInteractionPlugin();
+    default:
+      throw new Error(`Unknown interaction plugin: ${pluginName}`);
+  }
+}
+
+/**
+ * Initialize interaction chain from config
+ *
+ * @param config - Nax configuration
+ * @param headless - Whether running in headless mode (skip interactions)
+ * @returns Initialized interaction chain or null if disabled/headless
+ */
+export async function initInteractionChain(config: NaxConfig, headless: boolean): Promise<InteractionChain | null> {
+  const logger = getSafeLogger();
+
+  // If headless mode, skip interaction system
+  if (headless) {
+    logger?.debug("interaction", "Headless mode - skipping interaction system");
+    return null;
+  }
+
+  // If no interaction config, skip
+  if (!config.interaction) {
+    logger?.debug("interaction", "No interaction config - skipping interaction system");
+    return null;
+  }
+
+  // Create chain
+  const chain = new InteractionChain({
+    defaultTimeout: config.interaction.defaults.timeout,
+    defaultFallback: config.interaction.defaults.fallback,
+  });
+
+  // Create and register plugin
+  const pluginName = config.interaction.plugin;
+  try {
+    const plugin = createInteractionPlugin(pluginName);
+    chain.register(plugin, 100);
+
+    // Initialize plugin
+    const pluginConfig = config.interaction.config ?? {};
+    await chain.init({ [pluginName]: pluginConfig });
+
+    logger?.info("interaction", `Initialized ${pluginName} interaction plugin`, {
+      timeout: config.interaction.defaults.timeout,
+      fallback: config.interaction.defaults.fallback,
+    });
+
+    return chain;
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    logger?.error("interaction", `Failed to initialize interaction plugin: ${error}`);
+    throw err;
+  }
+}