reqon-dsl 0.2.0 → 0.3.0

package/dist/pause/manager.js

@@ -0,0 +1,245 @@
+/**
+ * Pause Manager - Orchestrates resource-free long pauses
+ *
+ * Handles pause creation, monitoring, and resume coordination.
+ * Integrates with webhook server for webhook-based resume triggers.
+ */
+import { createPauseState, parseDuration, isPauseExpired, getRemainingTime, formatDuration, } from './state.js';
+/**
+ * Manages resource-free long pauses
+ */
+export class PauseManager {
+    config;
+    pollTimer;
+    isRunning = false;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Create a new pause and persist state
+     */
+    async createPause(options) {
+        const duration = parseDuration(options.duration);
+        // Build resume trigger states
+        const resumeTriggers = [];
+        // Always include timeout by default
+        const triggers = options.resumeTriggers ?? [{ type: 'timeout' }];
+        const hasTimeout = triggers.some((t) => t.type === 'timeout');
+        if (!hasTimeout) {
+            triggers.push({ type: 'timeout' });
+        }
+        for (const trigger of triggers) {
+            if (trigger.type === 'timeout') {
+                resumeTriggers.push({ type: 'timeout', active: true });
+            }
+            else if (trigger.type === 'webhook') {
+                const triggerState = {
+                    type: 'webhook',
+                    path: trigger.path,
+                    active: true,
+                };
+                // Register webhook if server available
+                if (this.config.webhookServer) {
+                    const registration = await this.registerWebhookTrigger(options.executionId, trigger.path, duration);
+                    triggerState.registrationId = registration.id;
+                }
+                resumeTriggers.push(triggerState);
+            }
+        }
+        // Create pause state
+        const pause = createPauseState(options.executionId, options.mission, duration, options.checkpoint, resumeTriggers);
+        // Persist
+        await this.config.store.save(pause);
+        this.log(`Created pause ${pause.id} for ${formatDuration(duration)}`);
+        return pause;
+    }
+    /**
+     * Resume a pause manually
+     */
+    async resumeManually(pauseId) {
+        const pause = await this.config.store.load(pauseId);
+        if (!pause) {
+            throw new Error(`Pause not found: ${pauseId}`);
+        }
+        if (pause.status !== 'waiting') {
+            throw new Error(`Pause ${pauseId} is not waiting (status: ${pause.status})`);
+        }
+        return this.markResumed(pause, 'manual');
+    }
+    /**
+     * Resume a pause by execution ID
+     */
+    async resumeByExecution(executionId) {
+        const pause = await this.config.store.loadByExecution(executionId);
+        if (!pause) {
+            return null;
+        }
+        return this.resumeManually(pause.id);
+    }
+    /**
+     * Cancel a pause (without resuming execution)
+     */
+    async cancelPause(pauseId) {
+        const pause = await this.config.store.load(pauseId);
+        if (!pause) {
+            throw new Error(`Pause not found: ${pauseId}`);
+        }
+        if (pause.status !== 'waiting') {
+            return; // Already not waiting
+        }
+        await this.config.store.update(pauseId, {
+            status: 'cancelled',
+            resumedAt: new Date(),
+            resumedBy: 'cancelled',
+        });
+        // Cleanup webhook registrations
+        await this.cleanupWebhooks(pause);
+        this.log(`Cancelled pause ${pauseId}`);
+    }
+    /**
+     * Handle webhook callback for a pause
+     */
+    async handleWebhook(pauseId, payload) {
+        const pause = await this.config.store.load(pauseId);
+        if (!pause || pause.status !== 'waiting') {
+            return false;
+        }
+        // Check if this pause has an active webhook trigger
+        const webhookTrigger = pause.resumeTriggers.find((t) => t.type === 'webhook' && t.active);
+        if (!webhookTrigger) {
+            return false;
+        }
+        // Mark resumed with webhook payload
+        await this.markResumed(pause, 'webhook', payload);
+        return true;
+    }
+    /**
+     * Start monitoring for expired pauses
+     */
+    startMonitoring() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        const interval = this.config.pollInterval ?? 60000; // Default: 1 minute
+        this.pollTimer = setInterval(async () => {
+            await this.checkExpiredPauses();
+        }, interval);
+        this.log(`Started pause monitoring (interval: ${formatDuration(interval)})`);
+    }
+    /**
+     * Stop monitoring
+     */
+    stopMonitoring() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = undefined;
+        }
+        this.isRunning = false;
+        this.log('Stopped pause monitoring');
+    }
+    /**
+     * Check for and process expired pauses
+     */
+    async checkExpiredPauses() {
+        const expired = await this.config.store.findExpired();
+        const resumed = [];
+        for (const pause of expired) {
+            const updated = await this.markResumed(pause, 'timeout');
+            resumed.push(updated);
+        }
+        return resumed;
+    }
+    /**
+     * Get all active pauses
+     */
+    async getActivePauses() {
+        return this.config.store.listActive();
+    }
+    /**
+     * Get pause by ID
+     */
+    async getPause(pauseId) {
+        return this.config.store.load(pauseId);
+    }
+    /**
+     * Get pause status summary
+     */
+    async getStatus() {
+        const active = await this.config.store.listActive();
+        const expired = active.filter((p) => isPauseExpired(p));
+        const waiting = active.filter((p) => !isPauseExpired(p));
+        return {
+            totalActive: active.length,
+            waiting: waiting.length,
+            expired: expired.length,
+            nextExpiration: waiting.length > 0
+                ? waiting.reduce((min, p) => (p.expiresAt < min ? p.expiresAt : min), waiting[0].expiresAt)
+                : undefined,
+            pauses: active.map((p) => ({
+                id: p.id,
+                mission: p.mission,
+                executionId: p.executionId,
+                remaining: getRemainingTime(p),
+                remainingFormatted: formatDuration(getRemainingTime(p)),
+            })),
+        };
+    }
+    async markResumed(pause, resumedBy, webhookPayload) {
+        const updates = {
+            status: 'resumed',
+            resumedAt: new Date(),
+            resumedBy,
+        };
+        if (webhookPayload !== undefined) {
+            updates.webhookPayload = webhookPayload;
+        }
+        await this.config.store.update(pause.id, updates);
+        // Cleanup webhook registrations
+        await this.cleanupWebhooks(pause);
+        const updated = await this.config.store.load(pause.id);
+        if (!updated) {
+            throw new Error(`Failed to load updated pause: ${pause.id}`);
+        }
+        this.log(`Pause ${pause.id} resumed by ${resumedBy}`);
+        // Trigger callback
+        if (this.config.onResume) {
+            await this.config.onResume(updated);
+        }
+        return updated;
+    }
+    async registerWebhookTrigger(executionId, path, timeout) {
+        if (!this.config.webhookServer) {
+            throw new Error('Webhook server not configured for webhook triggers');
+        }
+        // Register a webhook listener that will call handleWebhook
+        const registration = await this.config.webhookServer.register(executionId, {
+            path,
+            timeout,
+            expectedEvents: 1,
+        });
+        return { id: registration.id };
+    }
+    async cleanupWebhooks(pause) {
+        if (!this.config.webhookServer)
+            return;
+        for (const trigger of pause.resumeTriggers) {
+            if (trigger.type === 'webhook' && trigger.registrationId) {
+                try {
+                    await this.config.webhookServer.unregister(trigger.registrationId);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        }
+    }
+    log(message) {
+        this.config.log?.(`[PauseManager] ${message}`);
+    }
+}
+/**
+ * Create a pause manager
+ */
+export function createPauseManager(config) {
+    return new PauseManager(config);
+}

package/dist/pause/state.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Pause State - Types for resource-free long pauses
+ *
+ * Supports pausing execution for extended periods (days/weeks)
+ * while persisting state and releasing resources.
+ */
+/**
+ * Persisted pause state
+ */
+export interface PauseState {
+    /** Unique pause ID */
+    id: string;
+    /** Execution ID this pause belongs to */
+    executionId: string;
+    /** Mission name */
+    mission: string;
+    /** When the pause started */
+    pausedAt: Date;
+    /** When the pause will expire (resume due to timeout) */
+    expiresAt: Date;
+    /** Original duration specified (in milliseconds) */
+    duration: number;
+    /** Current status */
+    status: 'waiting' | 'resumed' | 'expired' | 'cancelled';
+    /** How the pause was resumed (if resumed) */
+    resumedBy?: 'timeout' | 'webhook' | 'manual' | 'cancelled';
+    /** When resumed */
+    resumedAt?: Date;
+    /** Resume trigger configuration */
+    resumeTriggers: PauseResumeTriggerState[];
+    /** Checkpoint data for resuming execution */
+    checkpoint: PauseCheckpoint;
+    /** Webhook data if resumed by webhook */
+    webhookPayload?: unknown;
+}
+/**
+ * Resume trigger state
+ */
+export interface PauseResumeTriggerState {
+    type: 'timeout' | 'webhook';
+    /** For webhook: the registered path */
+    path?: string;
+    /** For webhook: registration ID */
+    registrationId?: string;
+    /** Whether this trigger is active */
+    active: boolean;
+}
+/**
+ * Checkpoint data for resuming after pause
+ */
+export interface PauseCheckpoint {
+    /** Stage index to resume from */
+    stageIndex: number;
+    /** Step index within action to resume from (after pause step) */
+    stepIndex: number;
+    /** Current action name */
+    action: string;
+    /** For loops: current item index */
+    itemIndex?: number;
+    /** Saved context variables */
+    variables: Record<string, unknown>;
+    /** Saved response value */
+    response?: unknown;
+}
+/**
+ * Generate a unique pause ID
+ */
+export declare function generatePauseId(executionId: string): string;
+/**
+ * Parse duration string to milliseconds
+ * Supports: "7d", "1d", "12h", "30m", "45s", or raw milliseconds
+ */
+export declare function parseDuration(duration: string | number): number;
+/**
+ * Format duration for display
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Create initial pause state
+ */
+export declare function createPauseState(executionId: string, mission: string, duration: number, checkpoint: PauseCheckpoint, resumeTriggers: PauseResumeTriggerState[]): PauseState;
+/**
+ * Check if a pause has expired
+ */
+export declare function isPauseExpired(pause: PauseState): boolean;
+/**
+ * Get remaining time for a pause (in milliseconds)
+ */
+export declare function getRemainingTime(pause: PauseState): number;
+/**
+ * Get pause summary for display
+ */
+export declare function getPauseSummary(pause: PauseState): string;

package/dist/pause/state.js

@@ -0,0 +1,103 @@
+/**
+ * Pause State - Types for resource-free long pauses
+ *
+ * Supports pausing execution for extended periods (days/weeks)
+ * while persisting state and releasing resources.
+ */
+/**
+ * Generate a unique pause ID
+ */
+export function generatePauseId(executionId) {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 6);
+    return `pause_${executionId}_${timestamp}_${random}`;
+}
+/**
+ * Parse duration string to milliseconds
+ * Supports: "7d", "1d", "12h", "30m", "45s", or raw milliseconds
+ */
+export function parseDuration(duration) {
+    if (typeof duration === 'number') {
+        return duration;
+    }
+    const match = duration.match(/^(\d+(?:\.\d+)?)\s*(d|h|m|s|ms)?$/i);
+    if (!match) {
+        throw new Error(`Invalid duration format: ${duration}. Use "7d", "12h", "30m", "45s", or milliseconds.`);
+    }
+    const value = parseFloat(match[1]);
+    const unit = (match[2] || 'ms').toLowerCase();
+    const multipliers = {
+        ms: 1,
+        s: 1000,
+        m: 60 * 1000,
+        h: 60 * 60 * 1000,
+        d: 24 * 60 * 60 * 1000,
+    };
+    const multiplier = multipliers[unit];
+    if (multiplier === undefined) {
+        throw new Error(`Unknown duration unit: ${unit}`);
+    }
+    return Math.round(value * multiplier);
+}
+/**
+ * Format duration for display
+ */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60 * 1000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    if (ms < 60 * 60 * 1000)
+        return `${(ms / (60 * 1000)).toFixed(1)}m`;
+    if (ms < 24 * 60 * 60 * 1000)
+        return `${(ms / (60 * 60 * 1000)).toFixed(1)}h`;
+    return `${(ms / (24 * 60 * 60 * 1000)).toFixed(1)}d`;
+}
+/**
+ * Create initial pause state
+ */
+export function createPauseState(executionId, mission, duration, checkpoint, resumeTriggers) {
+    const now = new Date();
+    return {
+        id: generatePauseId(executionId),
+        executionId,
+        mission,
+        pausedAt: now,
+        expiresAt: new Date(now.getTime() + duration),
+        duration,
+        status: 'waiting',
+        resumeTriggers,
+        checkpoint,
+    };
+}
+/**
+ * Check if a pause has expired
+ */
+export function isPauseExpired(pause) {
+    return pause.status === 'waiting' && new Date() >= pause.expiresAt;
+}
+/**
+ * Get remaining time for a pause (in milliseconds)
+ */
+export function getRemainingTime(pause) {
+    if (pause.status !== 'waiting')
+        return 0;
+    const remaining = pause.expiresAt.getTime() - Date.now();
+    return Math.max(0, remaining);
+}
+/**
+ * Get pause summary for display
+ */
+export function getPauseSummary(pause) {
+    const remaining = getRemainingTime(pause);
+    if (pause.status === 'resumed') {
+        return `Pause ${pause.id}: resumed by ${pause.resumedBy} at ${pause.resumedAt?.toISOString()}`;
+    }
+    if (pause.status === 'expired') {
+        return `Pause ${pause.id}: expired at ${pause.expiresAt.toISOString()}`;
+    }
+    if (pause.status === 'cancelled') {
+        return `Pause ${pause.id}: cancelled`;
+    }
+    return `Pause ${pause.id}: waiting (${formatDuration(remaining)} remaining)`;
+}

package/dist/pause/store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pause Store - Persistence for pause states
+ *
+ * Stores pause state for resource-free long pauses,
+ * enabling resumption after extended periods.
+ */
+import type { PauseState } from './state.js';
+/**
+ * Pause store interface
+ */
+export interface PauseStore {
+    /** Save a pause state */
+    save(pause: PauseState): Promise<void>;
+    /** Load a pause by ID */
+    load(id: string): Promise<PauseState | null>;
+    /** Load pause by execution ID */
+    loadByExecution(executionId: string): Promise<PauseState | null>;
+    /** List all active (waiting) pauses */
+    listActive(): Promise<PauseState[]>;
+    /** List pauses for a mission */
+    listByMission(mission: string): Promise<PauseState[]>;
+    /** Delete a pause state */
+    delete(id: string): Promise<void>;
+    /** Find pauses that have expired but not yet processed */
+    findExpired(): Promise<PauseState[]>;
+    /** Update pause state (e.g., when resumed) */
+    update(id: string, updates: Partial<PauseState>): Promise<void>;
+}
+/**
+ * File-based pause store
+ */
+export declare class FilePauseStore implements PauseStore {
+    private baseDir;
+    private initialized;
+    constructor(baseDir?: string);
+    private getFilePath;
+    private deserialize;
+    save(pause: PauseState): Promise<void>;
+    load(id: string): Promise<PauseState | null>;
+    loadByExecution(executionId: string): Promise<PauseState | null>;
+    listActive(): Promise<PauseState[]>;
+    listByMission(mission: string): Promise<PauseState[]>;
+    delete(id: string): Promise<void>;
+    findExpired(): Promise<PauseState[]>;
+    update(id: string, updates: Partial<PauseState>): Promise<void>;
+}
+/**
+ * In-memory pause store (for testing)
+ */
+export declare class MemoryPauseStore implements PauseStore {
+    private pauses;
+    save(pause: PauseState): Promise<void>;
+    load(id: string): Promise<PauseState | null>;
+    loadByExecution(executionId: string): Promise<PauseState | null>;
+    listActive(): Promise<PauseState[]>;
+    listByMission(mission: string): Promise<PauseState[]>;
+    delete(id: string): Promise<void>;
+    findExpired(): Promise<PauseState[]>;
+    update(id: string, updates: Partial<PauseState>): Promise<void>;
+    clear(): void;
+}

package/dist/pause/store.js

@@ -0,0 +1,156 @@
+/**
+ * Pause Store - Persistence for pause states
+ *
+ * Stores pause state for resource-free long pauses,
+ * enabling resumption after extended periods.
+ */
+import { join } from 'node:path';
+import { ensureDirectory, writeJsonFile, readJsonFile, listFiles, deleteFile, restoreDates, } from '../utils/file.js';
+/**
+ * File-based pause store
+ */
+export class FilePauseStore {
+    baseDir;
+    initialized;
+    constructor(baseDir = '.reqon-data/pauses') {
+        this.baseDir = baseDir;
+        this.initialized = ensureDirectory(this.baseDir);
+    }
+    getFilePath(id) {
+        return join(this.baseDir, `${id}.json`);
+    }
+    deserialize(parsed) {
+        restoreDates(parsed, ['pausedAt', 'expiresAt', 'resumedAt']);
+        return parsed;
+    }
+    async save(pause) {
+        await this.initialized;
+        await writeJsonFile(this.getFilePath(pause.id), pause);
+    }
+    async load(id) {
+        await this.initialized;
+        const parsed = await readJsonFile(this.getFilePath(id));
+        return parsed ? this.deserialize(parsed) : null;
+    }
+    async loadByExecution(executionId) {
+        const all = await this.listActive();
+        return all.find((p) => p.executionId === executionId) ?? null;
+    }
+    async listActive() {
+        await this.initialized;
+        const files = await listFiles(this.baseDir, '.json');
+        const pauses = [];
+        for (const file of files) {
+            const parsed = await readJsonFile(file);
+            if (parsed) {
+                const pause = this.deserialize(parsed);
+                if (pause.status === 'waiting') {
+                    pauses.push(pause);
+                }
+            }
+        }
+        return pauses.sort((a, b) => a.expiresAt.getTime() - b.expiresAt.getTime());
+    }
+    async listByMission(mission) {
+        await this.initialized;
+        const files = await listFiles(this.baseDir, '.json');
+        const pauses = [];
+        for (const file of files) {
+            const parsed = await readJsonFile(file);
+            if (parsed) {
+                const pause = this.deserialize(parsed);
+                if (pause.mission === mission) {
+                    pauses.push(pause);
+                }
+            }
+        }
+        return pauses.sort((a, b) => b.pausedAt.getTime() - a.pausedAt.getTime());
+    }
+    async delete(id) {
+        await this.initialized;
+        await deleteFile(this.getFilePath(id));
+    }
+    async findExpired() {
+        const active = await this.listActive();
+        const now = new Date();
+        return active.filter((p) => p.expiresAt <= now);
+    }
+    async update(id, updates) {
+        const pause = await this.load(id);
+        if (!pause) {
+            throw new Error(`Pause not found: ${id}`);
+        }
+        const updated = { ...pause, ...updates };
+        await this.save(updated);
+    }
+}
+/**
+ * In-memory pause store (for testing)
+ */
+export class MemoryPauseStore {
+    pauses = new Map();
+    async save(pause) {
+        this.pauses.set(pause.id, JSON.parse(JSON.stringify(pause)));
+    }
+    async load(id) {
+        const pause = this.pauses.get(id);
+        if (!pause)
+            return null;
+        const restored = JSON.parse(JSON.stringify(pause));
+        restored.pausedAt = new Date(restored.pausedAt);
+        restored.expiresAt = new Date(restored.expiresAt);
+        if (restored.resumedAt) {
+            restored.resumedAt = new Date(restored.resumedAt);
+        }
+        return restored;
+    }
+    async loadByExecution(executionId) {
+        for (const pause of this.pauses.values()) {
+            if (pause.executionId === executionId && pause.status === 'waiting') {
+                return this.load(pause.id);
+            }
+        }
+        return null;
+    }
+    async listActive() {
+        const pauses = [];
+        for (const pause of this.pauses.values()) {
+            if (pause.status === 'waiting') {
+                const loaded = await this.load(pause.id);
+                if (loaded)
+                    pauses.push(loaded);
+            }
+        }
+        return pauses.sort((a, b) => a.expiresAt.getTime() - b.expiresAt.getTime());
+    }
+    async listByMission(mission) {
+        const pauses = [];
+        for (const pause of this.pauses.values()) {
+            if (pause.mission === mission) {
+                const loaded = await this.load(pause.id);
+                if (loaded)
+                    pauses.push(loaded);
+            }
+        }
+        return pauses.sort((a, b) => b.pausedAt.getTime() - a.pausedAt.getTime());
+    }
+    async delete(id) {
+        this.pauses.delete(id);
+    }
+    async findExpired() {
+        const active = await this.listActive();
+        const now = new Date();
+        return active.filter((p) => p.expiresAt <= now);
+    }
+    async update(id, updates) {
+        const pause = await this.load(id);
+        if (!pause) {
+            throw new Error(`Pause not found: ${id}`);
+        }
+        const updated = { ...pause, ...updates };
+        await this.save(updated);
+    }
+    clear() {
+        this.pauses.clear();
+    }
+}

package/dist/plugin.d.ts

@@ -1,16 +1,13 @@
 /**
- * Reqon plugin for Vague.
- *
- * This plugin registers Reqon's keywords and statement parsers with Vague,
- * allowing Vague to parse Reqon syntax when the plugin is registered.
- *
- * Usage:
- *   import { registerPlugin } from 'vague-lang';
- *   import { reqonPlugin } from 'reqon';
- *   registerPlugin(reqonPlugin);
- *
- * Or simply import the plugin module to auto-register:
- *   import 'reqon/plugin';
+ * ---
+ * purpose: Vague plugin - registers Reqon keywords with Vague's lexer
+ * exports:
+ *   - reqonPlugin - plugin object for manual registration
+ *   - registerReqonPlugin, unregisterReqonPlugin - registration helpers
+ * related:
+ *   - ./lexer/tokens.ts - REQON_KEYWORDS map
+ *   - vague-lang - parent DSL framework
+ * ---
  */
 import { type VaguePlugin } from 'vague-lang';
 /**