@northflare/runner 0.0.12 → 0.0.13

package/src/utils/StateManager.ts

@@ -1,187 +0,0 @@
-/**
- * State Manager for persisting runner state
- * 
- * Manages persistent state including lastProcessedAt timestamp
- * to enable proper catch-up on restart.
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import { createLogger } from './logger';
-
-const logger = createLogger('StateManager');
-
-export interface RunnerState {
-  runnerId: string;
-  runnerUid: string | null;
-  lastProcessedAt: string | null; // ISO string
-  isActiveRunner: boolean;
-  updatedAt: string; // ISO string
-}
-
-export class StateManager {
-  private statePath: string;
-  private state: RunnerState | null = null;
-  private saveTimer: NodeJS.Timeout | null = null;
-
-  constructor(dataDir: string, runnerId: string) {
-    // Namespace state file by runnerId (stable external ID) to separate different users
-    const stateFile = `runner-state-${runnerId}.json`;
-    this.statePath = path.join(dataDir, stateFile);
-  }
-
-  /**
-   * Load state from disk
-   */
-  async loadState(): Promise<RunnerState | null> {
-    try {
-      const content = await fs.readFile(this.statePath, 'utf-8');
-      this.state = JSON.parse(content);
-      logger.info('Loaded runner state', {
-        runnerId: this.state?.runnerId,
-        runnerUid: this.state?.runnerUid,
-        lastProcessedAt: this.state?.lastProcessedAt,
-        isActiveRunner: this.state?.isActiveRunner,
-      });
-      return this.state;
-    } catch (error) {
-      if ((error as any).code === 'ENOENT') {
-        logger.debug('No state file found, starting fresh');
-        return null;
-      }
-      logger.error('Failed to load state file:', error);
-      return null;
-    }
-  }
-
-  /**
-   * Save state to disk
-   */
-  async saveState(state: RunnerState): Promise<void> {
-    this.state = state;
-    
-    // Cancel any pending save
-    if (this.saveTimer) {
-      clearTimeout(this.saveTimer);
-    }
-
-    // Debounce saves to avoid excessive disk writes
-    this.saveTimer = setTimeout(async () => {
-      try {
-        // Ensure directory exists
-        const dir = path.dirname(this.statePath);
-        await fs.mkdir(dir, { recursive: true });
-
-        // Update timestamp
-        state.updatedAt = new Date().toISOString();
-
-        // Write atomically by writing to temp file first
-        const tempPath = `${this.statePath}.tmp`;
-        await fs.writeFile(tempPath, JSON.stringify(state, null, 2), 'utf-8');
-        await fs.rename(tempPath, this.statePath);
-
-        logger.debug('Saved runner state', {
-          runnerId: state.runnerId,
-          lastProcessedAt: state.lastProcessedAt,
-          isActiveRunner: state.isActiveRunner,
-        });
-      } catch (error) {
-        logger.error('Failed to save state file:', error);
-        throw error;
-      }
-    }, 1000); // 1 second debounce
-  }
-
-  /**
-   * Update lastProcessedAt timestamp
-   */
-  async updateLastProcessedAt(timestamp: Date | string): Promise<void> {
-    if (!this.state) {
-      throw new Error('State not loaded');
-    }
-
-    const isoString = timestamp instanceof Date ? timestamp.toISOString() : timestamp;
-    
-    const updatedState: RunnerState = {
-      ...this.state,
-      lastProcessedAt: isoString,
-    };
-
-    await this.saveState(updatedState);
-  }
-
-  /**
-   * Update runner registration details
-   */
-  async updateRunnerRegistration(
-    runnerId: string,
-    runnerUid: string | null,
-    lastProcessedAt: Date | null
-  ): Promise<void> {
-    const state: RunnerState = this.state || {
-      runnerId: '',
-      runnerUid: null,
-      lastProcessedAt: null,
-      isActiveRunner: false,
-      updatedAt: new Date().toISOString(),
-    };
-
-    const updatedState: RunnerState = {
-      ...state,
-      runnerId,
-      runnerUid,
-      lastProcessedAt: lastProcessedAt ? lastProcessedAt.toISOString() : null,
-    };
-
-    await this.saveState(updatedState);
-  }
-
-  /**
-   * Update active runner status
-   */
-  async updateActiveStatus(isActive: boolean): Promise<void> {
-    if (!this.state) {
-      throw new Error('State not loaded');
-    }
-
-    const updatedState: RunnerState = {
-      ...this.state,
-      isActiveRunner: isActive,
-    };
-
-    await this.saveState(updatedState);
-  }
-
-  /**
-   * Get current state
-   */
-  getState(): RunnerState | null {
-    return this.state;
-  }
-
-  /**
-   * Get lastProcessedAt as Date
-   */
-  getLastProcessedAt(): Date | null {
-    if (!this.state || !this.state.lastProcessedAt) {
-      return null;
-    }
-    return new Date(this.state.lastProcessedAt);
-  }
-
-  /**
-   * Clear state (for testing or reset)
-   */
-  async clearState(): Promise<void> {
-    this.state = null;
-    try {
-      await fs.unlink(this.statePath);
-      logger.info('Cleared runner state');
-    } catch (error) {
-      if ((error as any).code !== 'ENOENT') {
-        logger.error('Failed to clear state file:', error);
-        throw error;
-      }
-    }
-  }
-}

package/src/utils/config.ts

@@ -1,327 +0,0 @@
-/**
- * Configuration management utilities
- */
-
-import { RunnerConfig, EnvironmentConfig, RetryStrategy } from "../types";
-import fs from "fs/promises";
-import path from "path";
-import { createLogger } from "./logger";
-import { Command } from "commander";
-
-const logger = createLogger("ConfigManager");
-
-export class ConfigManager {
-  private static DEFAULT_CONFIG: Partial<RunnerConfig> = {
-    dataDir: ConfigManager.resolveDefaultDataDir(),
-    heartbeatInterval: 120000, // 2 minutes
-    retryStrategy: "exponential" as RetryStrategy,
-    retryIntervalSecs: 60,
-    retryDurationSecs: 900,
-  };
-
-  private static resolveDefaultDataDir(): string {
-    try {
-      const envPaths = require("env-paths").default || require("env-paths");
-      const paths = envPaths("northflare-runner", { suffix: "" });
-      return paths.data;
-    } catch (error) {
-      logger.debug("Falling back to cwd-relative data directory", error);
-      return path.resolve("./data");
-    }
-  }
-
-  /**
-   * Load configuration without parsing command line arguments
-   * Used when arguments have already been parsed by the CLI
-   */
-  static async loadConfig(configPath?: string): Promise<RunnerConfig> {
-    // Validate required environment variables
-    this.validateEnvironment();
-
-    // Start with defaults
-    let config: Partial<RunnerConfig> = { ...this.DEFAULT_CONFIG };
-
-    // Determine config path - use provided path or default location
-    let effectiveConfigPath = configPath;
-    if (!effectiveConfigPath) {
-      // Try to use default config location
-      try {
-        const envPaths = require("env-paths").default || require("env-paths");
-        const paths = envPaths("northflare-runner", { suffix: "" });
-        const defaultConfigPath = path.join(paths.config, "config.json");
-
-        // Check if default config exists
-        const fs = require("fs");
-        if (fs.existsSync(defaultConfigPath)) {
-          effectiveConfigPath = defaultConfigPath;
-          logger.info(`Using default config file: ${defaultConfigPath}`);
-        }
-      } catch (error) {
-        // env-paths not available or error accessing default location
-        logger.debug("Could not check default config location:", error);
-      }
-    }
-
-    // Load from config file if we have a path
-    if (effectiveConfigPath) {
-      const fileConfig = await this.loadConfigFile(effectiveConfigPath);
-      config = { ...config, ...fileConfig };
-    }
-
-    // Override with environment variables
-    const envConfig = this.loadFromEnvironment();
-    config = { ...config, ...envConfig };
-
-    // Validate final configuration
-    this.validateConfig(config);
-
-    return config as RunnerConfig;
-  }
-
-  /**
-   * Parse command line arguments and load configuration
-   */
-  static async parseArgsAndLoadConfig(argv: string[]): Promise<RunnerConfig> {
-    const program = new Command();
-
-    program
-      .name("northflare-runner")
-      .description(
-        "Northflare Runner - Executes Claude agents for task processing"
-      )
-      .version("1.0.0")
-      .option("-c, --config <path>", "Path to configuration file")
-      .option(
-        "--retry-strategy <strategy>",
-        "Registration retry strategy (none, interval, exponential)",
-        "exponential"
-      )
-      .option(
-        "--retry-interval-secs <seconds>",
-        "Retry interval in seconds for interval strategy",
-        "60"
-      )
-      .option(
-        "--retry-duration-secs <seconds>",
-        "Max retry duration in seconds for exponential strategy",
-        "900"
-      )
-      .option("--data-dir <path>", "Data directory path")
-      .option(
-        "--heartbeat-interval <ms>",
-        "Heartbeat interval in milliseconds",
-        "120000"
-      );
-
-    program.parse(argv);
-    const options = program.opts();
-
-    // Validate required environment variables
-    this.validateEnvironment();
-
-    // Start with defaults
-    let config: Partial<RunnerConfig> = { ...this.DEFAULT_CONFIG };
-
-    // Load from config file if provided
-    if (options["config"]) {
-      const fileConfig = await this.loadConfigFile(options["config"]);
-      config = { ...config, ...fileConfig };
-    }
-
-    // Override with environment variables
-    const envConfig = this.loadFromEnvironment();
-    config = { ...config, ...envConfig };
-
-    // Override with CLI arguments (highest priority)
-    if (options["retryStrategy"]) {
-      config.retryStrategy = options["retryStrategy"] as RetryStrategy;
-    }
-    if (options["retryIntervalSecs"]) {
-      config.retryIntervalSecs = parseInt(options["retryIntervalSecs"]);
-    }
-    if (options["retryDurationSecs"]) {
-      config.retryDurationSecs = parseInt(options["retryDurationSecs"]);
-    }
-    if (options["dataDir"]) {
-      config.dataDir = options["dataDir"];
-    }
-    if (options["heartbeatInterval"]) {
-      config.heartbeatInterval = parseInt(options["heartbeatInterval"]);
-    }
-
-    // Validate final configuration
-    this.validateConfig(config);
-
-    return config as RunnerConfig;
-  }
-
-  /**
-   * Validate required environment variables
-   */
-  private static validateEnvironment(): void {
-    // Set default for NORTHFLARE_WORKSPACE_DIR if not provided
-    if (!process.env["NORTHFLARE_WORKSPACE_DIR"]) {
-      try {
-        const envPaths = require("env-paths").default || require("env-paths");
-        const paths = envPaths("northflare-runner", { suffix: "" });
-        process.env["NORTHFLARE_WORKSPACE_DIR"] = paths.data;
-      } catch (error) {
-        // Fallback to original default if env-paths is not available
-        process.env["NORTHFLARE_WORKSPACE_DIR"] = "/workspace";
-      }
-    }
-
-    // Set default for NORTHFLARE_ORCHESTRATOR_URL if not provided
-    if (!process.env["NORTHFLARE_ORCHESTRATOR_URL"]) {
-      process.env["NORTHFLARE_ORCHESTRATOR_URL"] = "https://api.northflare.app";
-    }
-
-    const required = [
-      "NORTHFLARE_RUNNER_TOKEN",
-      "NORTHFLARE_WORKSPACE_DIR",
-      "NORTHFLARE_ORCHESTRATOR_URL",
-    ];
-
-    const missing = required.filter((key) => !process.env[key]);
-
-    if (missing.length > 0) {
-      throw new Error(
-        `Missing required environment variables: ${missing.join(", ")}\n` +
-          "Please set these environment variables before starting the runner."
-      );
-    }
-  }
-
-  /**
-   * Load configuration from environment variables
-   */
-  private static loadFromEnvironment(): Partial<RunnerConfig> {
-    const config: Partial<RunnerConfig> = {
-      orchestratorUrl: process.env["NORTHFLARE_ORCHESTRATOR_URL"]!,
-    };
-
-    // Optional environment overrides
-    if (process.env["NORTHFLARE_DATA_DIR"]) {
-      config.dataDir = process.env["NORTHFLARE_DATA_DIR"];
-    }
-
-    return config;
-  }
-
-  /**
-   * Load configuration from file
-   */
-  private static async loadConfigFile(
-    configPath: string
-  ): Promise<Partial<RunnerConfig>> {
-    try {
-      const absolutePath = path.resolve(configPath);
-      const content = await fs.readFile(absolutePath, "utf-8");
-
-      // Support both JSON and YAML formats
-      if (configPath.endsWith(".json")) {
-        const config = JSON.parse(content);
-
-        // Log if runnerRepos are found in config
-        if (config.runnerRepos && Array.isArray(config.runnerRepos)) {
-          logger.info(
-            `Found ${config.runnerRepos.length} runner repos in config file`
-          );
-        }
-
-        return config;
-      } else if (configPath.endsWith(".yaml") || configPath.endsWith(".yml")) {
-        // For YAML support, we'd need to add a yaml parser dependency
-        throw new Error("YAML configuration files are not yet supported");
-      } else {
-        throw new Error("Configuration file must be .json format");
-      }
-    } catch (error) {
-      if ((error as any).code === "ENOENT") {
-        logger.warn(`Configuration file not found: ${configPath}`);
-        return {};
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Validate final configuration
-   */
-  private static validateConfig(config: Partial<RunnerConfig>): void {
-    // Note: Runner ID will be generated by server during registration
-
-    if (!config.orchestratorUrl) {
-      throw new Error("orchestratorUrl is required");
-    }
-
-    if (!config.dataDir) {
-      throw new Error("dataDir is required");
-    }
-
-    if (!config.heartbeatInterval || config.heartbeatInterval < 1000) {
-      throw new Error("heartbeatInterval must be at least 1000ms");
-    }
-
-    // Validate retry strategy
-    const validStrategies: RetryStrategy[] = [
-      "none",
-      "interval",
-      "exponential",
-    ];
-    if (
-      !config.retryStrategy ||
-      !validStrategies.includes(config.retryStrategy)
-    ) {
-      throw new Error(
-        `retryStrategy must be one of: ${validStrategies.join(", ")}`
-      );
-    }
-
-    if (
-      config.retryStrategy === "interval" &&
-      (!config.retryIntervalSecs || config.retryIntervalSecs < 1)
-    ) {
-      throw new Error(
-        "retryIntervalSecs must be at least 1 when using interval strategy"
-      );
-    }
-
-    if (
-      config.retryStrategy === "exponential" &&
-      (!config.retryDurationSecs || config.retryDurationSecs < 1)
-    ) {
-      throw new Error(
-        "retryDurationSecs must be at least 1 when using exponential strategy"
-      );
-    }
-  }
-
-  /**
-   * Get all environment configuration
-   */
-  static getEnvironmentConfig(): EnvironmentConfig {
-    return {
-      NORTHFLARE_RUNNER_TOKEN: process.env["NORTHFLARE_RUNNER_TOKEN"]!,
-      NORTHFLARE_WORKSPACE_DIR: process.env["NORTHFLARE_WORKSPACE_DIR"]!,
-      NORTHFLARE_ORCHESTRATOR_URL: process.env["NORTHFLARE_ORCHESTRATOR_URL"]!,
-      NORTHFLARE_RUNNER_DEBUG: process.env["NORTHFLARE_RUNNER_DEBUG"],
-      DEBUG: process.env["DEBUG"],
-    };
-  }
-
-  /**
-   * Save configuration file with updated data
-   */
-  static async saveConfigFile(configPath: string, config: any): Promise<void> {
-    try {
-      const absolutePath = path.resolve(configPath);
-      const content = JSON.stringify(config, null, 2);
-      await fs.writeFile(absolutePath, content, "utf-8");
-      logger.info(`Updated configuration file: ${absolutePath}`);
-    } catch (error) {
-      logger.error("Failed to save configuration file", error);
-      throw error;
-    }
-  }
-}

package/src/utils/console.ts

@@ -1,15 +0,0 @@
-/**
- * Console wrapper that suppresses output when not in debug mode
- */
-
-import { isRunnerDebugEnabled } from "./debug";
-
-const isDebug = isRunnerDebugEnabled();
-
-export const console = {
-  log: isDebug ? global.console.log.bind(global.console) : () => {},
-  warn: isDebug ? global.console.warn.bind(global.console) : () => {},
-  error: global.console.error.bind(global.console), // Always show errors
-  info: isDebug ? global.console.info.bind(global.console) : () => {},
-  debug: isDebug ? global.console.debug.bind(global.console) : () => {},
-};

package/src/utils/debug.ts

@@ -1,18 +0,0 @@
-export function isRunnerDebugEnabled(): boolean {
-  const explicitFlag = process.env["NORTHFLARE_RUNNER_DEBUG"];
-  if (typeof explicitFlag === "string") {
-    return isTruthy(explicitFlag);
-  }
-
-  const legacyFlag = process.env["DEBUG"];
-  if (typeof legacyFlag === "string") {
-    return isTruthy(legacyFlag);
-  }
-
-  return false;
-}
-
-function isTruthy(value: string): boolean {
-  const normalized = value.trim().toLowerCase();
-  return normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on";
-}

package/src/utils/expand-env.ts

@@ -1,22 +0,0 @@
-export function expandEnv(
-  obj: any,
-  env: Record<string, string | undefined> = process.env
-): any {
-  if (typeof obj === "string") {
-    return obj.replace(/\$\{([^}]+)\}/g, (match, key) => env[key] || match);
-  }
-
-  if (Array.isArray(obj)) {
-    return obj.map((item) => expandEnv(item, env));
-  }
-
-  if (obj && typeof obj === "object") {
-    const result: Record<string, any> = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = expandEnv(value, env);
-    }
-    return result;
-  }
-
-  return obj;
-}

package/src/utils/logger.ts

@@ -1,134 +0,0 @@
-/**
- * Logger configuration using Winston
- */
-
-import winston from "winston";
-import path from "path";
-import { isRunnerDebugEnabled } from "./debug";
-
-// Custom log levels
-const levels = {
-  error: 0,
-  warn: 1,
-  info: 2,
-  http: 3,
-  verbose: 4,
-  debug: 5,
-  silly: 6,
-};
-
-// Log colors
-const colors = {
-  error: "red",
-  warn: "yellow",
-  info: "green",
-  http: "magenta",
-  verbose: "cyan",
-  debug: "blue",
-  silly: "gray",
-};
-
-winston.addColors(colors);
-
-const debugEnabled = isRunnerDebugEnabled();
-
-// Format for console output
-const consoleFormat = winston.format.combine(
-  winston.format.colorize({ all: true }),
-  winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
-  winston.format.printf(({ timestamp, level, message, stack, ...metadata }) => {
-    let msg = `${timestamp} [${level}]: ${message}`;
-    // Only show stack traces and metadata in debug mode
-    if (debugEnabled) {
-      if (stack) {
-        msg += `\n${stack}`;
-      }
-      const filteredMetadata = { ...metadata };
-      delete filteredMetadata["component"]; // Keep component info
-      if (Object.keys(filteredMetadata).length > 0) {
-        msg += ` ${JSON.stringify(filteredMetadata)}`;
-      }
-    }
-    return msg;
-  })
-);
-
-// Format for file output
-const fileFormat = winston.format.combine(
-  winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
-  winston.format.errors({ stack: true }),
-  winston.format.json()
-);
-
-// Create logger instance
-export const logger = winston.createLogger({
-  level: debugEnabled ? "debug" : "info",
-  levels,
-  transports: [
-    // Always include console transport for errors
-    new winston.transports.Console({
-      format: consoleFormat,
-      level: debugEnabled ? "debug" : "error",
-    }),
-  ],
-});
-
-// Add file transports if log directory is configured
-export function configureFileLogging(logDir: string): void {
-  // Error log file
-  logger.add(
-    new winston.transports.File({
-      filename: path.join(logDir, "error.log"),
-      level: "error",
-      format: fileFormat,
-      maxsize: 10 * 1024 * 1024, // 10MB
-      maxFiles: 5,
-    })
-  );
-
-  // Combined log file
-  logger.add(
-    new winston.transports.File({
-      filename: path.join(logDir, "combined.log"),
-      format: fileFormat,
-      maxsize: 50 * 1024 * 1024, // 50MB
-      maxFiles: 10,
-    })
-  );
-
-  // Debug log file (only in debug mode)
-  if (debugEnabled) {
-    logger.add(
-      new winston.transports.File({
-        filename: path.join(logDir, "debug.log"),
-        level: "debug",
-        format: fileFormat,
-        maxsize: 100 * 1024 * 1024, // 100MB
-        maxFiles: 3,
-      })
-    );
-  }
-}
-
-// Create child logger for specific components
-export function createLogger(component: string): winston.Logger {
-  return logger.child({ component });
-}
-
-// Log unhandled errors
-logger.exceptions.handle(
-  new winston.transports.File({
-    filename: "exceptions.log",
-    format: fileFormat,
-  })
-);
-
-logger.rejections.handle(
-  new winston.transports.File({
-    filename: "rejections.log",
-    format: fileFormat,
-  })
-);
-
-// Export default logger
-export default logger;