stageflow 0.25.0 → 0.30.0

package/dist/runtime/emailSource.js

@@ -0,0 +1,304 @@
+import path from "node:path";
+import { ImapFlow } from "imapflow";
+import { getCatalogScanPaths } from "../config/browseCatalog.js";
+import { loadTriggerOutcome } from "../config/loadTrigger.js";
+import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
+import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { matchesEventFilter } from "./triggerEventMatch.js";
+export const DEFAULT_EMAIL_RECONNECT_BASE_DELAY_MS = 1_000;
+export const DEFAULT_EMAIL_RECONNECT_MAX_DELAY_MS = 30_000;
+export const EMAIL_TEXT_EXCERPT_MAX_CHARS = 2_000;
+function defaultCreateEmailClient(config) {
+    const client = new ImapFlow({
+        host: config.host,
+        port: config.port,
+        secure: config.port === 993 || config.port === 465,
+        auth: { user: config.user, pass: config.password },
+        logger: false,
+    });
+    return {
+        async connect() {
+            await client.connect();
+            const mailbox = await client.mailboxOpen("INBOX");
+            return { uidNext: mailbox.uidNext };
+        },
+        idle() {
+            void client.idle().catch(() => {
+                // Connection drop surfaces via the 'close'/'error' events below.
+            });
+        },
+        async fetchNewMessages(sinceUid) {
+            if (sinceUid <= 0)
+                return [];
+            const results = [];
+            for await (const msg of client.fetch(`${sinceUid + 1}:*`, { uid: true, envelope: true, bodyParts: ["TEXT"] }, { uid: true })) {
+                if (msg.uid <= sinceUid)
+                    continue;
+                const fromAddr = msg.envelope?.from?.[0];
+                const from = fromAddr?.address ?? fromAddr?.name ?? "";
+                const subject = msg.envelope?.subject ?? "";
+                const rawDate = msg.envelope?.date;
+                const date = rawDate instanceof Date ? rawDate.toISOString() : String(rawDate ?? "");
+                const text = msg.bodyParts?.get("TEXT")?.toString("utf8").slice(0, EMAIL_TEXT_EXCERPT_MAX_CHARS) ?? "";
+                results.push({ uid: msg.uid, from, subject, date, text });
+            }
+            return results;
+        },
+        async close() {
+            try {
+                await client.logout();
+            }
+            catch {
+                client.close();
+            }
+        },
+        onExists(listener) {
+            client.on("exists", () => listener());
+        },
+        onClose(listener) {
+            client.on("close", () => listener());
+        },
+        onError(listener) {
+            client.on("error", (err) => listener(err));
+        },
+    };
+}
+function parseMailboxConfig(definition) {
+    const config = definition.event?.config;
+    const host = config?.host;
+    const port = config?.port;
+    const user = config?.user;
+    const secretRef = config?.secretRef;
+    if (typeof host !== "string" ||
+        host.length === 0 ||
+        typeof port !== "number" ||
+        !Number.isFinite(port) ||
+        typeof user !== "string" ||
+        user.length === 0 ||
+        typeof secretRef !== "string" ||
+        secretRef.length === 0) {
+        return undefined;
+    }
+    return { host, port, user, secretRef };
+}
+function mailboxKeyFor(config) {
+    return `email:${config.host}:${config.port}:${config.user}`;
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * `TriggerSourcePort` adapter for `event`-kind triggers whose `event.source`
+ * starts with `email.`. Unlike the poll-based adapters this one is push-based:
+ * on `start()` it groups triggers by distinct mailbox (`host`+`port`+`user`),
+ * opens exactly one real IMAP/IDLE connection per mailbox regardless of how
+ * many triggers watch it, and reacts to the server's new-message
+ * notification instead of ticking on an interval. A dropped connection
+ * reconnects with bounded exponential backoff rather than going dark.
+ */
+export class EmailSource {
+    store;
+    cwd;
+    logError;
+    env;
+    createEmailClient;
+    reconnectBaseDelayMs;
+    reconnectMaxDelayMs;
+    connections = new Map();
+    stopped = false;
+    constructor(options) {
+        this.store = options.store;
+        this.cwd = options.cwd ?? process.cwd();
+        this.logError =
+            options.logError ??
+                ((message) => {
+                    console.error(message);
+                });
+        this.env = options.env ?? process.env;
+        this.createEmailClient = options.createEmailClient ?? defaultCreateEmailClient;
+        this.reconnectBaseDelayMs = options.reconnectBaseDelayMs ?? DEFAULT_EMAIL_RECONNECT_BASE_DELAY_MS;
+        this.reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? DEFAULT_EMAIL_RECONNECT_MAX_DELAY_MS;
+    }
+    async start(onFire) {
+        this.stopped = false;
+        const ctx = catalogContextFromStageflow(await resolveStageflowContext(this.cwd));
+        const scanPaths = await getCatalogScanPaths(ctx);
+        if (!scanPaths)
+            return;
+        const projectRoot = ctx.projectRoot ?? undefined;
+        const groups = await this.discover(scanPaths.triggerPaths);
+        for (const [mailboxKey, group] of groups) {
+            for (const match of group.matches) {
+                const definitionRef = projectRoot !== undefined
+                    ? path.relative(projectRoot, match.path).replace(/\\/g, "/")
+                    : match.path;
+                await this.store.upsertTrigger({
+                    id: match.definition.id,
+                    definitionRef,
+                    enabled: true,
+                });
+            }
+            await this.connectMailbox(mailboxKey, group, onFire);
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        for (const [mailboxKey, conn] of this.connections) {
+            conn.stopping = true;
+            if (conn.reconnectTimer !== undefined) {
+                clearTimeout(conn.reconnectTimer);
+                conn.reconnectTimer = undefined;
+            }
+            if (conn.client) {
+                try {
+                    await conn.client.close();
+                }
+                catch (err) {
+                    this.logError(`email: closing mailbox "${mailboxKey}" failed: ${errMsg(err)}`);
+                }
+            }
+        }
+        this.connections.clear();
+    }
+    async discover(triggerPaths) {
+        const groups = new Map();
+        for (const triggerPath of triggerPaths) {
+            const outcome = await loadTriggerOutcome(triggerPath);
+            if (!outcome.ok)
+                continue;
+            const definition = outcome.value;
+            if (definition.kind !== "event" || !definition.enabled)
+                continue;
+            const source = definition.event?.source;
+            if (typeof source !== "string" || !source.startsWith("email."))
+                continue;
+            const config = parseMailboxConfig(definition);
+            if (!config) {
+                this.logError(`email: trigger "${definition.id}" has incomplete event.config ` +
+                    `(expected host, port, user, secretRef); skipping`);
+                continue;
+            }
+            const mailboxKey = mailboxKeyFor(config);
+            const group = groups.get(mailboxKey) ?? { config, matches: [] };
+            group.matches.push({ path: triggerPath, definition });
+            groups.set(mailboxKey, group);
+        }
+        return groups;
+    }
+    async connectMailbox(mailboxKey, group, onFire) {
+        let conn = this.connections.get(mailboxKey);
+        if (!conn) {
+            conn = { group, onFire, reconnectAttempt: 0, stopping: false };
+            this.connections.set(mailboxKey, conn);
+        }
+        if (conn.stopping || this.stopped)
+            return;
+        let password;
+        try {
+            password = readSecretFromEnvOrFile(this.env, group.config.secretRef);
+        }
+        catch (err) {
+            this.logError(`email: failed to read secret "${group.config.secretRef}" for mailbox "${mailboxKey}": ${errMsg(err)}`);
+            return;
+        }
+        if (password === undefined) {
+            this.logError(`email: secret "${group.config.secretRef}" is not set for mailbox "${mailboxKey}"; skipping`);
+            return;
+        }
+        const client = this.createEmailClient({
+            host: group.config.host,
+            port: group.config.port,
+            user: group.config.user,
+            password,
+        });
+        conn.client = client;
+        client.onError((err) => {
+            this.logError(`email: mailbox "${mailboxKey}" error: ${errMsg(err)}`);
+        });
+        client.onClose(() => {
+            const current = this.connections.get(mailboxKey);
+            if (this.stopped || !current || current.stopping)
+                return;
+            this.scheduleReconnect(mailboxKey);
+        });
+        client.onExists(() => {
+            void this.processNewMail(mailboxKey).catch((err) => {
+                this.logError(`email: processing new mail for mailbox "${mailboxKey}" failed: ${errMsg(err)}`);
+            });
+        });
+        try {
+            const { uidNext } = await client.connect();
+            const existing = await this.store.getTriggerAdapterState(mailboxKey, "uid");
+            if (existing === null) {
+                await this.store.setTriggerAdapterState(mailboxKey, "uid", String(Math.max(uidNext - 1, 0)));
+            }
+            client.idle();
+            conn.reconnectAttempt = 0;
+        }
+        catch (err) {
+            this.logError(`email: connecting to mailbox "${mailboxKey}" failed: ${errMsg(err)}`);
+            this.scheduleReconnect(mailboxKey);
+        }
+    }
+    scheduleReconnect(mailboxKey) {
+        const conn = this.connections.get(mailboxKey);
+        if (!conn || conn.stopping || this.stopped)
+            return;
+        const attempt = conn.reconnectAttempt;
+        const delay = Math.min(this.reconnectBaseDelayMs * 2 ** attempt, this.reconnectMaxDelayMs);
+        conn.reconnectAttempt = attempt + 1;
+        conn.reconnectTimer = setTimeout(() => {
+            conn.reconnectTimer = undefined;
+            void this.connectMailbox(mailboxKey, conn.group, conn.onFire);
+        }, delay).unref();
+    }
+    async processNewMail(mailboxKey) {
+        const conn = this.connections.get(mailboxKey);
+        if (!conn?.client)
+            return;
+        const watermarkRaw = await this.store.getTriggerAdapterState(mailboxKey, "uid");
+        const sinceUid = watermarkRaw !== null ? Number(watermarkRaw) : 0;
+        const messages = await conn.client.fetchNewMessages(sinceUid);
+        if (messages.length === 0)
+            return;
+        let maxUid = sinceUid;
+        for (const message of messages) {
+            if (message.uid <= sinceUid)
+                continue;
+            if (message.uid > maxUid)
+                maxUid = message.uid;
+            const summary = {
+                from: message.from,
+                subject: message.subject,
+                date: message.date,
+                text: message.text,
+            };
+            for (const { definition } of conn.group.matches) {
+                if (!matchesEventFilter(definition.event?.match, summary))
+                    continue;
+                await this.fireSafely(conn.onFire, definition, message, summary);
+            }
+        }
+        if (maxUid > sinceUid) {
+            await this.store.setTriggerAdapterState(mailboxKey, "uid", String(maxUid));
+        }
+    }
+    async fireSafely(onFire, definition, message, summary) {
+        try {
+            if (definition.task !== undefined) {
+                await onFire({ triggerId: definition.id });
+                return;
+            }
+            const task = {
+                id: `${definition.id}-email-${message.uid}`,
+                goal: `Handle email: ${message.subject}`,
+                input: summary,
+            };
+            await onFire({ triggerId: definition.id, task });
+        }
+        catch (err) {
+            this.logError(`email: firing trigger "${definition.id}" failed: ${errMsg(err)}`);
+        }
+    }
+}

package/dist/runtime/gitCheckoutCapability.js

@@ -1,20 +1,14 @@
 import { createHash } from "node:crypto";
-import { execFile } from "node:child_process";
 import { lstat, readFile, readlink } from "node:fs/promises";
 import path from "node:path";
-function runGit(root, args) {
-    return new Promise((resolve, reject) => {
-        execFile("git", ["-C", root, ...args], { encoding: "buffer", maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
-            if (error) {
-                const detail = Buffer.isBuffer(stderr)
-                    ? stderr.toString("utf8").trim()
-                    : "";
-                reject(new Error(detail || error.message));
-                return;
-            }
-            resolve(stdout);
-        });
+import { runGit as execGit } from "../git/exec.js";
+async function runGit(root, args) {
+    const result = await execGit({
+        cwd: root,
+        args,
+        maxBuffer: 16 * 1024 * 1024,
     });
+    return Buffer.from(result.stdout, "utf8");
 }
 function nulPaths(output) {
     return output.toString("utf8").split("\0").filter(Boolean);

package/dist/runtime/githubPollSource.d.ts

@@ -0,0 +1,86 @@
+import type { RunStore } from "../runstore/port.js";
+import type { TriggerFireEvent, TriggerSourcePort } from "./triggerPort.js";
+export declare const DEFAULT_GITHUB_POLL_INTERVAL_MS = 60000;
+export declare const DEFAULT_GITHUB_TOKEN_SECRET = "GITHUB_TOKEN";
+/** Parse `STAGEFLOW_GITHUB_POLL_INTERVAL_MS`; default 60s; `0` disables. */
+export declare function githubPollIntervalMsFromEnv(env?: NodeJS.ProcessEnv): number;
+export type GithubPullItem = {
+    number: number;
+    title: string;
+    html_url: string;
+    state: string;
+    merged_at: string | null;
+    created_at: string;
+    updated_at: string;
+    user: {
+        login: string;
+    } | null;
+};
+export type GithubPollResponse = {
+    status: number;
+    etag?: string;
+    items: GithubPullItem[];
+};
+/**
+ * Narrow, test-friendly seam over "list PR activity for a repo, conditionally
+ * on an ETag". The default implementation adapts `octokit.rest.pulls.list`;
+ * tests inject a fake so no real GitHub calls happen.
+ */
+export type GithubPollClient = {
+    listPulls(params: {
+        owner: string;
+        repo: string;
+        etag?: string;
+    }): Promise<GithubPollResponse>;
+};
+export declare function defaultCreateGithubClient(token: string): GithubPollClient;
+export type NormalizedGithubEvent = {
+    action: "opened" | "merged" | "closed" | "updated";
+    number: number;
+    title: string;
+    url: string;
+    author: string;
+    repo: string;
+    updatedAt: string;
+};
+export type GithubPollSourceOptions = {
+    store: RunStore;
+    cwd?: string;
+    intervalMs?: number;
+    logError?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+    /** Injectable client factory so tests never hit real GitHub. */
+    createGithubClient?: (token: string) => GithubPollClient;
+};
+/**
+ * `TriggerSourcePort` adapter for `event`-kind triggers whose `event.source`
+ * starts with `github.`. Ticks on an interval; each tick re-scans the catalog,
+ * groups triggers by their distinct `event.config.repo` (one API call per repo
+ * per tick regardless of how many triggers watch it), and diffs each repo's
+ * PR list against a persisted ETag + cursor to find genuinely new activity.
+ *
+ * The first tick for a never-before-seen repo only seeds the cursor — it
+ * never fires for a repo's pre-existing PR history, mirroring how
+ * `ScheduleSource` seeds `next_run_at` without firing on first sight.
+ */
+export declare class GithubPollSource implements TriggerSourcePort {
+    private readonly store;
+    private readonly cwd;
+    private readonly intervalMs;
+    private readonly logError;
+    private readonly env;
+    private readonly createGithubClient;
+    private interval;
+    private inFlight;
+    constructor(options: GithubPollSourceOptions);
+    start(onFire: (event: TriggerFireEvent) => Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * One discovery + poll + fire pass. Public so tests can drive it directly
+     * instead of waiting on real interval timers.
+     */
+    tick(onFire: (event: TriggerFireEvent) => Promise<void>): Promise<void>;
+    private discover;
+    private pollRepo;
+    private fireSafely;
+}