cli4ai 0.8.2 → 0.8.3

package/src/core/scheduler.ts

@@ -0,0 +1,601 @@
+/**
+ * Scheduler core - manages scheduled routine execution.
+ *
+ * Storage structure:
+ * ~/.cli4ai/scheduler/
+ * ├── scheduler.pid          # Daemon PID
+ * ├── state.json             # Next runs, last results
+ * ├── runs/                  # Execution records
+ * │   └── <routine>-<ts>.json
+ * └── logs/
+ *     └── scheduler.log      # Daemon logs
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, readdirSync } from 'fs';
+import { resolve, join } from 'path';
+import parser from 'cron-parser';
+import { SCHEDULER_DIR, ensureCli4aiHome } from './config.js';
+import { getScheduledRoutines, type ScheduledRoutineInfo } from './routines.js';
+import { loadRoutineDefinition, runRoutine, type RoutineSchedule, type RoutineRunSummary } from './routine-engine.js';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATHS
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const SCHEDULER_PID_FILE = resolve(SCHEDULER_DIR, 'scheduler.pid');
+export const SCHEDULER_STATE_FILE = resolve(SCHEDULER_DIR, 'state.json');
+export const SCHEDULER_RUNS_DIR = resolve(SCHEDULER_DIR, 'runs');
+export const SCHEDULER_LOGS_DIR = resolve(SCHEDULER_DIR, 'logs');
+export const SCHEDULER_LOG_FILE = resolve(SCHEDULER_LOGS_DIR, 'scheduler.log');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface ScheduledRoutineState {
+  name: string;
+  path: string;
+  schedule: RoutineSchedule;
+  nextRunAt: string | null;
+  lastRunAt: string | null;
+  lastStatus: 'success' | 'failed' | null;
+  running: boolean;
+  retryCount: number;
+}
+
+export interface SchedulerState {
+  version: 1;
+  startedAt: string;
+  routines: Record<string, ScheduledRoutineState>;
+}
+
+export interface SchedulerRunRecord {
+  routine: string;
+  startedAt: string;
+  finishedAt: string;
+  status: 'success' | 'failed';
+  exitCode: number;
+  durationMs: number;
+  retryAttempt: number;
+  error?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// INTERVAL PARSING
+// ═══════════════════════════════════════════════════════════════════════════
+
+const INTERVAL_PATTERN = /^(\d+)(s|m|h|d)$/;
+
+const INTERVAL_MULTIPLIERS: Record<string, number> = {
+  s: 1000,
+  m: 60 * 1000,
+  h: 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000
+};
+
+/**
+ * Parse an interval string like "30s", "5m", "1h", "1d" into milliseconds.
+ */
+export function parseInterval(interval: string): number {
+  const match = interval.match(INTERVAL_PATTERN);
+  if (!match) {
+    throw new Error(`Invalid interval format: ${interval}`);
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  return value * INTERVAL_MULTIPLIERS[unit];
+}
+
+/**
+ * Calculate the next run time for a schedule.
+ * If both cron and interval are specified, returns the earlier of the two.
+ */
+export function getNextRunTime(schedule: RoutineSchedule, after: Date = new Date()): Date | null {
+  const candidates: Date[] = [];
+
+  // Calculate from cron expression
+  if (schedule.cron) {
+    try {
+      const options: parser.ParserOptions = {
+        currentDate: after,
+        tz: schedule.timezone
+      };
+      const cronExpr = parser.parseExpression(schedule.cron, options);
+      candidates.push(cronExpr.next().toDate());
+    } catch {
+      // Invalid cron expression - skip
+    }
+  }
+
+  // Calculate from interval
+  if (schedule.interval) {
+    try {
+      const intervalMs = parseInterval(schedule.interval);
+      candidates.push(new Date(after.getTime() + intervalMs));
+    } catch {
+      // Invalid interval - skip
+    }
+  }
+
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  // Return the earliest next run time
+  return candidates.reduce((earliest, candidate) =>
+    candidate < earliest ? candidate : earliest
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DAEMON LIFECYCLE
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get the PID of the running daemon, or null if not running.
+ */
+export function getDaemonPid(): number | null {
+  if (!existsSync(SCHEDULER_PID_FILE)) {
+    return null;
+  }
+
+  try {
+    const pid = parseInt(readFileSync(SCHEDULER_PID_FILE, 'utf-8').trim(), 10);
+    if (isNaN(pid)) return null;
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a process with the given PID is running.
+ */
+function isProcessRunning(pid: number): boolean {
+  try {
+    // Sending signal 0 doesn't actually send a signal, but checks if process exists
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if the scheduler daemon is running.
+ */
+export function isDaemonRunning(): boolean {
+  const pid = getDaemonPid();
+  if (pid === null) return false;
+  return isProcessRunning(pid);
+}
+
+/**
+ * Write the daemon PID file.
+ */
+export function writeDaemonPid(pid: number): void {
+  ensureSchedulerDirs();
+  writeFileSync(SCHEDULER_PID_FILE, String(pid));
+}
+
+/**
+ * Remove the daemon PID file.
+ */
+export function removeDaemonPid(): void {
+  if (existsSync(SCHEDULER_PID_FILE)) {
+    unlinkSync(SCHEDULER_PID_FILE);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// STATE MANAGEMENT
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function ensureSchedulerDirs(): void {
+  ensureCli4aiHome();
+  if (!existsSync(SCHEDULER_RUNS_DIR)) {
+    mkdirSync(SCHEDULER_RUNS_DIR, { recursive: true });
+  }
+  if (!existsSync(SCHEDULER_LOGS_DIR)) {
+    mkdirSync(SCHEDULER_LOGS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Load scheduler state from disk.
+ */
+export function loadSchedulerState(): SchedulerState | null {
+  if (!existsSync(SCHEDULER_STATE_FILE)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(SCHEDULER_STATE_FILE, 'utf-8');
+    return JSON.parse(content) as SchedulerState;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save scheduler state to disk.
+ */
+export function saveSchedulerState(state: SchedulerState): void {
+  ensureSchedulerDirs();
+  writeFileSync(SCHEDULER_STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+/**
+ * Save a run record to disk.
+ */
+export function saveRunRecord(record: SchedulerRunRecord): void {
+  ensureSchedulerDirs();
+  const filename = `${record.routine}-${new Date(record.startedAt).getTime()}.json`;
+  const filepath = resolve(SCHEDULER_RUNS_DIR, filename);
+  writeFileSync(filepath, JSON.stringify(record, null, 2));
+}
+
+/**
+ * Get run history for a routine (or all routines).
+ */
+export function getRunHistory(routineName?: string, limit: number = 20): SchedulerRunRecord[] {
+  ensureSchedulerDirs();
+
+  if (!existsSync(SCHEDULER_RUNS_DIR)) {
+    return [];
+  }
+
+  const files = readdirSync(SCHEDULER_RUNS_DIR)
+    .filter(f => f.endsWith('.json'))
+    .filter(f => !routineName || f.startsWith(`${routineName}-`))
+    .sort()
+    .reverse()
+    .slice(0, limit);
+
+  const records: SchedulerRunRecord[] = [];
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(resolve(SCHEDULER_RUNS_DIR, file), 'utf-8');
+      records.push(JSON.parse(content) as SchedulerRunRecord);
+    } catch {
+      // Skip invalid files
+    }
+  }
+
+  return records;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LOGGING
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type LogLevel = 'info' | 'warn' | 'error' | 'debug';
+
+export function appendSchedulerLog(level: LogLevel, message: string): void {
+  ensureSchedulerDirs();
+  const timestamp = new Date().toISOString();
+  const line = `[${timestamp}] [${level.toUpperCase()}] ${message}\n`;
+  const fd = require('fs').appendFileSync(SCHEDULER_LOG_FILE, line);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SCHEDULER CLASS
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface SchedulerOptions {
+  tickIntervalMs?: number;
+  projectDir?: string;
+}
+
+export class Scheduler {
+  private state: SchedulerState;
+  private tickIntervalMs: number;
+  private projectDir: string | undefined;
+  private running: boolean = false;
+  private tickTimer: NodeJS.Timeout | null = null;
+  private routineChainByName: Map<string, Promise<void>> = new Map();
+
+  constructor(options: SchedulerOptions = {}) {
+    this.tickIntervalMs = options.tickIntervalMs ?? 10000; // 10 seconds default
+    this.projectDir = options.projectDir;
+
+    // Load or initialize state
+    const existingState = loadSchedulerState();
+    if (existingState) {
+      this.state = existingState;
+    } else {
+      this.state = {
+        version: 1,
+        startedAt: new Date().toISOString(),
+        routines: {}
+      };
+    }
+  }
+
+  /**
+   * Refresh the list of scheduled routines from disk.
+   */
+  refreshRoutines(): void {
+    const scheduled = getScheduledRoutines(this.projectDir);
+
+    // Remove routines that no longer exist or are disabled
+    const currentNames = new Set(scheduled.map(r => r.name));
+    for (const name of Object.keys(this.state.routines)) {
+      if (!currentNames.has(name)) {
+        delete this.state.routines[name];
+      }
+    }
+
+    // Add or update routines
+    for (const routine of scheduled) {
+      const existing = this.state.routines[routine.name];
+
+      if (existing) {
+        // Update schedule if changed
+        existing.schedule = routine.schedule;
+        existing.path = routine.path;
+        // Recalculate next run if schedule changed
+        if (!existing.nextRunAt) {
+          existing.nextRunAt = getNextRunTime(routine.schedule)?.toISOString() ?? null;
+        }
+      } else {
+        // New routine
+        this.state.routines[routine.name] = {
+          name: routine.name,
+          path: routine.path,
+          schedule: routine.schedule,
+          nextRunAt: getNextRunTime(routine.schedule)?.toISOString() ?? null,
+          lastRunAt: null,
+          lastStatus: null,
+          running: false,
+          retryCount: 0
+        };
+      }
+    }
+
+    saveSchedulerState(this.state);
+  }
+
+  /**
+   * Start the scheduler loop.
+   */
+  async start(): Promise<void> {
+    if (this.running) return;
+
+    this.running = true;
+    this.state.startedAt = new Date().toISOString();
+
+    appendSchedulerLog('info', 'Scheduler started');
+    this.refreshRoutines();
+
+    // Run tick loop
+    this.scheduleTick();
+  }
+
+  /**
+   * Stop the scheduler loop.
+   */
+  async stop(): Promise<void> {
+    this.running = false;
+
+    if (this.tickTimer) {
+      clearTimeout(this.tickTimer);
+      this.tickTimer = null;
+    }
+
+    appendSchedulerLog('info', 'Scheduler stopped');
+    saveSchedulerState(this.state);
+  }
+
+  /**
+   * Get current scheduler state (for status display).
+   */
+  getState(): SchedulerState {
+    return this.state;
+  }
+
+  private scheduleTick(): void {
+    if (!this.running) return;
+
+    this.tickTimer = setTimeout(async () => {
+      await this.tick();
+      this.scheduleTick();
+    }, this.tickIntervalMs);
+  }
+
+  private isRoutineActive(name: string): boolean {
+    return this.routineChainByName.has(name);
+  }
+
+  private enqueueRoutineExecution(routine: ScheduledRoutineState): void {
+    const name = routine.name;
+    const prev = this.routineChainByName.get(name) ?? Promise.resolve();
+    const next = prev
+      .catch(() => {
+        // Keep queue alive even if a previous run rejected unexpectedly.
+      })
+      .then(async () => {
+        try {
+          await this.executeRoutine(routine);
+        } catch (err) {
+          appendSchedulerLog(
+            'error',
+            `Unexpected error executing routine ${routine.name}: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      });
+
+    this.routineChainByName.set(name, next);
+    next.finally(() => {
+      if (this.routineChainByName.get(name) === next) {
+        this.routineChainByName.delete(name);
+      }
+    });
+  }
+
+  /**
+   * Execute one tick - check for routines that need to run.
+   */
+  private async tick(): Promise<void> {
+    const now = new Date();
+
+    // Refresh routines periodically to pick up changes
+    this.refreshRoutines();
+
+    for (const [name, routine] of Object.entries(this.state.routines)) {
+      if (!routine.nextRunAt) continue;
+
+      const nextRun = new Date(routine.nextRunAt);
+      if (nextRun > now) continue;
+
+      const concurrency = routine.schedule.concurrency ?? 'skip';
+
+      // Advance next run time immediately to avoid re-triggering the same run.
+      routine.nextRunAt = getNextRunTime(routine.schedule, now)?.toISOString() ?? null;
+      saveSchedulerState(this.state);
+
+      if (this.isRoutineActive(name)) {
+        if (concurrency === 'skip') {
+          appendSchedulerLog('debug', `Skipping ${name}: still running from previous invocation`);
+          continue;
+        }
+
+        appendSchedulerLog('debug', `Queueing ${name}: previous invocation still running`);
+        this.enqueueRoutineExecution(routine);
+        continue;
+      }
+
+      // Execute the routine (async, doesn't block the tick loop)
+      this.enqueueRoutineExecution(routine);
+    }
+  }
+
+  /**
+   * Execute a routine (async, doesn't block the tick loop).
+   */
+  private async executeRoutine(routine: ScheduledRoutineState): Promise<void> {
+    const startedAt = new Date();
+
+    routine.running = true;
+    saveSchedulerState(this.state);
+
+    appendSchedulerLog('info', `Starting routine: ${routine.name}`);
+
+    let result: RoutineRunSummary | null = null;
+    let error: string | undefined;
+
+    try {
+      const def = loadRoutineDefinition(routine.path);
+      const invocationDir = this.projectDir ?? process.cwd();
+      result = await runRoutine(def, {}, invocationDir);
+    } catch (err) {
+      error = err instanceof Error ? err.message : String(err);
+      appendSchedulerLog('error', `Routine ${routine.name} failed: ${error}`);
+    }
+
+    const finishedAt = new Date();
+    const status: 'success' | 'failed' = result?.status === 'success' ? 'success' : 'failed';
+
+    // Log routine output
+    if (result) {
+      for (const step of result.steps) {
+        // Log stderr (where progress messages typically go)
+        if (step.stderr) {
+          for (const line of step.stderr.split('\n')) {
+            if (line.trim()) {
+              appendSchedulerLog('info', `[${routine.name}] ${line}`);
+            }
+          }
+        }
+        // Log stdout if it's not JSON (JSON output is typically for machine consumption)
+        if (step.stdout && !step.json) {
+          for (const line of step.stdout.split('\n')) {
+            if (line.trim()) {
+              appendSchedulerLog('info', `[${routine.name}] ${line}`);
+            }
+          }
+        }
+      }
+    }
+
+    // Save run record
+    const record: SchedulerRunRecord = {
+      routine: routine.name,
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      status,
+      exitCode: result?.exitCode ?? 1,
+      durationMs: finishedAt.getTime() - startedAt.getTime(),
+      retryAttempt: routine.retryCount,
+      error
+    };
+    saveRunRecord(record);
+
+    // Update routine state
+    routine.running = false;
+    routine.lastRunAt = finishedAt.toISOString();
+    routine.lastStatus = status;
+
+    // Handle retries
+    const maxRetries = routine.schedule.retries ?? 0;
+    if (status === 'failed' && routine.retryCount < maxRetries) {
+      routine.retryCount++;
+      const retryDelay = routine.schedule.retryDelayMs ?? 60000;
+      routine.nextRunAt = new Date(finishedAt.getTime() + retryDelay).toISOString();
+      appendSchedulerLog('info', `Scheduling retry ${routine.retryCount}/${maxRetries} for ${routine.name}`);
+    } else {
+      // Reset retry count and calculate next run
+      routine.retryCount = 0;
+    }
+
+    saveSchedulerState(this.state);
+    appendSchedulerLog('info', `Finished routine: ${routine.name} (${status})`);
+  }
+
+  /**
+   * Manually trigger a routine to run now.
+   */
+  async runNow(routineName: string): Promise<SchedulerRunRecord> {
+    const routine = this.state.routines[routineName];
+    if (!routine) {
+      throw new Error(`Routine not found: ${routineName}`);
+    }
+
+    const startedAt = new Date();
+    let result: RoutineRunSummary | null = null;
+    let error: string | undefined;
+
+    try {
+      const def = loadRoutineDefinition(routine.path);
+      const invocationDir = this.projectDir ?? process.cwd();
+      result = await runRoutine(def, {}, invocationDir);
+    } catch (err) {
+      error = err instanceof Error ? err.message : String(err);
+    }
+
+    const finishedAt = new Date();
+    const status: 'success' | 'failed' = result?.status === 'success' ? 'success' : 'failed';
+
+    const record: SchedulerRunRecord = {
+      routine: routineName,
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      status,
+      exitCode: result?.exitCode ?? 1,
+      durationMs: finishedAt.getTime() - startedAt.getTime(),
+      retryAttempt: 0,
+      error
+    };
+    saveRunRecord(record);
+
+    // Update state
+    routine.lastRunAt = finishedAt.toISOString();
+    routine.lastStatus = status;
+    routine.nextRunAt = getNextRunTime(routine.schedule, finishedAt)?.toISOString() ?? null;
+    saveSchedulerState(this.state);
+
+    return record;
+  }
+}

package/src/lib/cli.ts

@@ -1,12 +1,12 @@
 /**
- * cli4ai - cliforai.com
+ * cli4ai - cli4ai.com
  * Standardized CLI framework for AI agent tools
  */
 
 import { Command } from 'commander';
 
-export const BRAND = 'cli4ai - cliforai.com';
-export const VERSION = '0.8.2';
+export const BRAND = 'cli4ai - cli4ai.com';
+export const VERSION = '0.8.3';
 
 // ═══════════════════════════════════════════════════════════════════════════
 // TYPES
@@ -36,10 +36,29 @@ export const ErrorCodes = {
   PARSE_ERROR: 'PARSE_ERROR',
   MANIFEST_ERROR: 'MANIFEST_ERROR',
   INSTALL_ERROR: 'INSTALL_ERROR',
+  NPM_ERROR: 'NPM_ERROR',
 } as const;
 
 export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
 
+const EXIT_CODES: Record<string, number> = {
+  [ErrorCodes.NOT_FOUND]: 2,
+  [ErrorCodes.INVALID_INPUT]: 3,
+  [ErrorCodes.ENV_MISSING]: 4,
+  [ErrorCodes.MANIFEST_ERROR]: 4,
+  [ErrorCodes.INSTALL_ERROR]: 4,
+  [ErrorCodes.AUTH_FAILED]: 6,
+  [ErrorCodes.NETWORK_ERROR]: 7,
+  [ErrorCodes.RATE_LIMITED]: 8,
+  [ErrorCodes.TIMEOUT]: 9,
+  [ErrorCodes.PARSE_ERROR]: 10,
+  [ErrorCodes.NPM_ERROR]: 11,
+};
+
+function getExitCode(code: string): number {
+  return EXIT_CODES[code] ?? 1;
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // ENV VALIDATION
 // ═══════════════════════════════════════════════════════════════════════════
@@ -106,14 +125,15 @@ export function output(data: unknown): void {
 export function outputError(
   code: string,
   message: string,
-  details?: Record<string, unknown>
+  details?: Record<string, unknown>,
+  exitCodeOverride?: number
 ): never {
   console.error(JSON.stringify({
     error: code,
     message,
     ...details
   }));
-  process.exit(1);
+  process.exit(exitCodeOverride ?? getExitCode(code));
 }
 
 /**

package/src/mcp/adapter.ts

@@ -73,18 +73,26 @@ export async function executeTool(
   entryPath: string,
   runtime: string,
   command: string,
-  args: Record<string, string>
+  args: Record<string, string>,
+  argOrder?: string[]
 ): Promise<McpToolResult> {
   return new Promise((resolve) => {
     // Build command arguments
     const cmdArgs = [command];
-    for (const [key, value] of Object.entries(args)) {
-      if (value !== undefined && value !== '') {
-        cmdArgs.push(value);
-      }
+
+    // Prefer manifest-defined arg order (positional), fall back to stable ordering.
+    const orderedKeys = argOrder ?? Object.keys(args).sort();
+    for (const key of orderedKeys) {
+      const value = args[key];
+      if (value !== undefined && value !== '') cmdArgs.push(value);
     }
 
-    const proc = spawn(runtime, ['run', entryPath, ...cmdArgs], {
+    const runtimeArgs =
+      runtime === 'node'
+        ? [entryPath, ...cmdArgs]
+        : ['run', entryPath, ...cmdArgs];
+
+    const proc = spawn(runtime, runtimeArgs, {
       stdio: ['pipe', 'pipe', 'pipe'],
       env: { ...process.env }
     });