@voidlabs.gg/voidshift-agents 0.5.1 → 0.7.0

package/dist/notify.js

@@ -0,0 +1,233 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentsDir, readAgentsConfig } from "./config.js";
+import { keyStore, readSecret, removeSecret, storeSecret } from "./secrets.js";
+import { listRuns } from "./state.js";
+// Run pings go to a Discord webhook: one global, and optionally one per
+// workflow that wins over it. Both are kept as secrets.
+const WEBHOOK = /^https:\/\/(discord\.com|discordapp\.com|ptb\.discord\.com|canary\.discord\.com)\/api\/webhooks\/\d+\/[A-Za-z0-9_-]+$/;
+const LIMIT = 2000;
+const TIMEOUT_MS = 5000;
+export const looksLikeWebhook = (url) => WEBHOOK.test(url);
+// A workflow name as it can appear in a secret name.
+export const slug = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const secretName = (workflow) => (workflow ? `discord-${slug(workflow)}` : 'discord');
+// Never throws: a secrets file that cannot be read means no ping.
+function readWebhook(configDir, workflow, platform) {
+    if (workflow !== undefined && !slug(workflow))
+        return null;
+    try {
+        return readSecret(configDir, secretName(workflow), platform);
+    }
+    catch {
+        return null;
+    }
+}
+// The workflow's own webhook, else the global one.
+export const webhookFor = (configDir, workflow, platform = process.platform) => (workflow ? readWebhook(configDir, workflow, platform) : null) ?? readWebhook(configDir, undefined, platform);
+// Posts one message. Never throws: returns why it failed, or null. A slow
+// network gives up after the timeout, even when the fetch ignores its signal.
+export async function postDiscord(url, content, fetcher = fetch, timeoutMs = TIMEOUT_MS) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(`no answer from Discord in ${timeoutMs / 1000}s`), timeoutMs);
+    });
+    const send = (async () => {
+        try {
+            const res = await fetcher(url, {
+                method: 'POST',
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: { 'Content-Type': 'application/json' },
+                // No mentions are parsed, so card text can never ping anyone.
+                body: JSON.stringify({ content: content.slice(0, LIMIT), username: 'VoidShift', allowed_mentions: { parse: [] } }),
+            });
+            return res.ok ? null : `Discord answered ${res.status}`;
+        }
+        catch (err) {
+            const cause = err.cause;
+            return `could not reach Discord (${cause?.code ?? cause?.message ?? err.message})`;
+        }
+    })();
+    try {
+        return await Promise.race([send, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const HEADINGS = { ready: 'PR ready', passed: 'Checks passed', parked: 'Parked', failed: 'Failed' };
+export function runMessage(e) {
+    const link = e.prUrl || e.url;
+    const reason = (e.kind === 'parked' || e.kind === 'failed') && e.reason ? e.reason.slice(0, 300) : '';
+    return [`**${HEADINGS[e.kind]}** ${e.card} ${e.title}, workflow ${e.workflow}`, link ?? '', reason].filter(Boolean).join('\n');
+}
+// Pings the run's webhook, if one is set. Logs a failure and never throws.
+export async function notifyRun(configDir, e, log, fetcher = fetch, platform = process.platform) {
+    const url = webhookFor(configDir, e.workflow, platform);
+    if (!url)
+        return;
+    const err = await postDiscord(url, runMessage(e), fetcher);
+    if (err)
+        log(`discord: ${err}`);
+}
+// The runner paused or resumed, with why; a budget pause can use it too.
+export async function notifyRunner(configDir, paused, reason, log, fetcher = fetch, platform = process.platform) {
+    const url = webhookFor(configDir, undefined, platform);
+    if (!url)
+        return;
+    const err = await postDiscord(url, `**Runner ${paused ? 'paused' : 'resumed'}** ${reason}`, fetcher);
+    if (err)
+        log(`discord: ${err}`);
+}
+const notifyPath = (configDir) => join(agentsDir(configDir), 'notify.json');
+export function readNotifyState(configDir) {
+    try {
+        return JSON.parse(readFileSync(notifyPath(configDir), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeNotifyState(configDir, state) {
+    mkdirSync(agentsDir(configDir), { recursive: true });
+    writeFileSync(notifyPath(configDir), JSON.stringify(state, null, 2) + '\n');
+}
+const SUMMARY_HOUR = 9;
+const DAY = 86_400_000;
+const localDay = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+// Runs ended since the last summary (or the last day), counted by outcome,
+// with the pull requests and parked cards.
+export function summaryMessage(configDir, since, paused) {
+    const runs = listRuns(configDir)
+        .map((e) => e.record)
+        .filter((r) => r && r.outcome !== 'running' && r.endedAt && Date.parse(r.endedAt) > since.getTime());
+    if (!runs.length)
+        return null;
+    const counts = new Map();
+    for (const r of runs)
+        counts.set(r.outcome, (counts.get(r.outcome) ?? 0) + 1);
+    const prs = runs.filter((r) => r.outcome === 'verified' && r.prUrl).slice(0, 10);
+    const parked = runs.filter((r) => r.outcome === 'parked').slice(0, 10);
+    const lines = [`**Daily summary** ${[...counts].map(([o, n]) => `${n} ${o}`).join(', ')}`];
+    if (paused)
+        lines.push('Runner paused');
+    if (prs.length)
+        lines.push('PRs:', ...prs.map((r) => `${r.card} ${r.prUrl}`));
+    if (parked.length)
+        lines.push('Parked:', ...parked.map((r) => `${r.card} ${r.title}${r.reason ? `: ${r.reason.slice(0, 120)}` : ''}`));
+    return lines.join('\n');
+}
+// Sends the summary once a day, on the first call at or after 09:00 local.
+// The day is recorded before posting, so overlapping calls send it once.
+export async function sendSummary(configDir, paused, log, now = new Date(), fetcher = fetch, platform = process.platform) {
+    try {
+        if (now.getHours() < SUMMARY_HOUR)
+            return;
+        const state = readNotifyState(configDir);
+        const today = localDay(now);
+        if (state.summaryDay === today)
+            return;
+        const url = webhookFor(configDir, undefined, platform);
+        if (!url)
+            return;
+        const since = state.summaryAt ? new Date(state.summaryAt) : new Date(now.getTime() - DAY);
+        writeNotifyState(configDir, { summaryDay: today, summaryAt: now.toISOString() });
+        const message = summaryMessage(configDir, since, paused);
+        if (!message)
+            return;
+        const err = await postDiscord(url, message, fetcher);
+        if (err)
+            log(`discord: ${err}`);
+    }
+    catch (err) {
+        log(`discord: ${err.message}`);
+    }
+}
+// Why an override cannot be kept for this workflow, or null.
+function overrideProblem(configDir, workflow) {
+    const s = slug(workflow);
+    if (!s)
+        return `Workflow ${workflow} has no letters or digits, so it cannot have its own webhook.`;
+    const other = Object.keys(readAgentsConfig(configDir).workflows).find((n) => n !== workflow && slug(n) === s);
+    return other ? `Workflows ${workflow} and ${other} would share a webhook. Rename one first.` : null;
+}
+// Tests the webhook with one message and stores it only when that worked.
+export async function addWebhook(configDir, url, workflow, log, fetcher = fetch, platform = process.platform) {
+    if (!looksLikeWebhook(url)) {
+        log('That is not a Discord webhook URL. It looks like https://discord.com/api/webhooks/123/abc.');
+        return false;
+    }
+    const problem = workflow ? overrideProblem(configDir, workflow) : null;
+    if (problem) {
+        log(problem);
+        return false;
+    }
+    const err = await postDiscord(url, `VoidShift is connected. Run pings${workflow ? ` for workflow ${workflow}` : ''} come here.`, fetcher);
+    if (err) {
+        log(`Discord did not take the test message: ${err}. Nothing was stored.`);
+        return false;
+    }
+    if (!storeSecret(configDir, secretName(workflow), url, platform)) {
+        log(`Discord took the test message but the webhook could not be stored in ${keyStore(platform)}.`);
+        return false;
+    }
+    log(`Webhook${workflow ? ` for workflow ${workflow}` : ''} stored in ${keyStore(platform)}. A test message was sent.`);
+    return true;
+}
+// Sends a test message to the webhook a workflow's runs would use.
+export async function testWebhook(configDir, workflow, log, fetcher = fetch, platform = process.platform) {
+    const url = webhookFor(configDir, workflow, platform);
+    if (!url) {
+        log('No webhook set. Run vsf agents discord to add one.');
+        return false;
+    }
+    const err = await postDiscord(url, `Test message from VoidShift${workflow ? ` for workflow ${workflow}` : ''}.`, fetcher);
+    log(err ? `discord: ${err}` : 'Test message sent.');
+    return !err;
+}
+export function removeWebhook(configDir, workflow, log, platform = process.platform) {
+    if (!readWebhook(configDir, workflow, platform)) {
+        log('No webhook set.');
+        return true;
+    }
+    if (!removeSecret(configDir, secretName(workflow), platform)) {
+        log(`Could not remove the webhook from ${keyStore(platform)}.`);
+        return false;
+    }
+    log(`Webhook${workflow ? ` for workflow ${workflow}` : ''} removed.`);
+    return true;
+}
+// Carries a workflow's webhook across a rename. Returns why the rename must
+// not go ahead, or null; nothing is changed when it refuses.
+export function moveWebhook(configDir, from, to, platform = process.platform) {
+    if (slug(from) === slug(to))
+        return null;
+    const mine = readWebhook(configDir, from, platform);
+    const theirs = slug(to) ? readWebhook(configDir, to, platform) : null;
+    if (!mine && !theirs)
+        return null;
+    if (!slug(to))
+        return `${to} has no letters or digits, so workflow ${from} would lose its webhook. Pick another name.`;
+    const other = Object.keys(readAgentsConfig(configDir).workflows).find((n) => n !== from && slug(n) === slug(to));
+    if (other)
+        return `Workflow ${other} would share a webhook with ${to}. Pick another name.`;
+    // A webhook left behind by a deleted workflow is not inherited.
+    if (theirs)
+        removeSecret(configDir, secretName(to), platform);
+    if (mine) {
+        if (!storeSecret(configDir, secretName(to), mine, platform))
+            return `Could not move the webhook of workflow ${from}.`;
+        removeSecret(configDir, secretName(from), platform);
+    }
+    return null;
+}
+// Drops a deleted workflow's webhook. Never throws.
+export function dropWebhook(configDir, workflow, platform = process.platform) {
+    try {
+        if (readWebhook(configDir, workflow, platform))
+            removeSecret(configDir, secretName(workflow), platform);
+    }
+    catch {
+        // nothing more to do
+    }
+}

package/dist/runner.d.ts

@@ -1,12 +1,15 @@
 import { type AgentsConfig, type Workflow, type Project, type Trigger } from './config.ts';
 import type { Card } from './linear.ts';
 import { type Tracker, type Trackers } from './tracker.ts';
+import type { RunEvent } from './notify.ts';
 export interface RunContext {
     configDir: string;
     config: AgentsConfig;
     trackers: Trackers;
     log: (line: string) => void;
     selfCommand: string[];
+    notify?: (event: RunEvent) => Promise<void>;
+    summary?: (paused: boolean) => Promise<void>;
 }
 export declare function summarize(output: string): string;
 export declare function runCard(card: Card, trigger: Trigger, workflowName: string, workflow: Workflow, project: Project, rc: RunContext, opts?: {
@@ -16,15 +19,38 @@ type Job = {
     card: Card;
     trigger: Trigger;
     workflow: string;
+    workspace: string;
 };
 export declare function cronCard(workflow: string, task: string, at: Date): Card;
-export declare function nextJob(rc: RunContext, only?: string, workflowName?: string, opts?: {
+export interface JobQuery {
+    only?: string;
+    workflow?: string;
+    schedule?: string;
     force?: boolean;
+    busy?: Set<string>;
+    skip?: Set<string>;
+    limit?: number;
     now?: Date;
-}): Promise<Job | null>;
+}
+export declare function findJobs(rc: RunContext, q?: JobQuery): Promise<Job[]>;
+export declare function nextJob(rc: RunContext, only?: string, workflowName?: string, opts?: Omit<JobQuery, 'only' | 'workflow' | 'limit'>): Promise<Job | null>;
 export declare function cancelCard(tracker: Tracker, configDir: string, cardId: string, label: string, source?: 'linear' | 'voidtrack'): Promise<boolean>;
 export declare function tick(rc: RunContext, only?: string, opts?: {
     workflow?: string;
     from?: string;
+    schedule?: string;
+    child?: boolean;
 }): Promise<number>;
+export interface ChildRun {
+    kill(signal: NodeJS.Signals): unknown;
+    once(event: 'exit' | 'error', listener: (err?: Error) => void): unknown;
+    exitCode: number | null;
+}
+export interface DispatchDeps {
+    start: (args: string[]) => ChildRun;
+    waitMs: number;
+    reload?: () => AgentsConfig;
+}
+export declare const jobArgs: (job: Job) => string[];
+export declare function dispatch(rc: RunContext, over?: Partial<DispatchDeps>): Promise<number>;
 export {};