discoclaw 0.1.0

package/dist/version.test.js

@@ -0,0 +1,31 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+vi.mock('execa', () => ({
+    execa: vi.fn(),
+}));
+import { getGitHash } from './version.js';
+describe('getGitHash', () => {
+    let mockExeca;
+    beforeEach(async () => {
+        const mod = await import('execa');
+        mockExeca = mod.execa;
+        mockExeca.mockReset();
+    });
+    it('returns the short hash from git rev-parse output', async () => {
+        mockExeca.mockResolvedValueOnce({ stdout: 'f52710d\n' });
+        const hash = await getGitHash();
+        expect(hash).toBe('f52710d');
+        expect(mockExeca).toHaveBeenCalledWith('git', ['rev-parse', '--short', 'HEAD']);
+    });
+    it('trims whitespace from git output', async () => {
+        mockExeca.mockResolvedValueOnce({ stdout: '  abc1234  \n' });
+        expect(await getGitHash()).toBe('abc1234');
+    });
+    it('returns null when git exits with an error', async () => {
+        mockExeca.mockRejectedValueOnce(new Error('not a git repository'));
+        expect(await getGitHash()).toBeNull();
+    });
+    it('returns null when git output is empty', async () => {
+        mockExeca.mockResolvedValueOnce({ stdout: '   ' });
+        expect(await getGitHash()).toBeNull();
+    });
+});

package/dist/webhook/server.js

@@ -0,0 +1,199 @@
+/**
+ * Webhook server — Phase 1
+ *
+ * Listens on POST /webhook/:source. Each source maps to an HMAC secret
+ * and a target Discord channel. Verified requests are dispatched through
+ * the existing cron execution pipeline (executeCronJob), giving webhooks
+ * runtime invocation, channel routing, model selection, and logging for free.
+ *
+ * Config file format (JSON):
+ *   {
+ *     "<source>": {
+ *       "secret": "<hmac-sha256-secret>",
+ *       "channel": "<discord-channel-name-or-id>",
+ *       "prompt": "<optional instruction override>"
+ *     }
+ *   }
+ *
+ * HMAC verification: callers must send an `X-Hub-Signature-256` header
+ * with value `sha256=<hex-digest>` computed over the raw request body
+ * using the per-source secret (same convention as GitHub webhooks).
+ */
+import http from 'node:http';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { executeCronJob } from '../cron/executor.js';
+// ---------------------------------------------------------------------------
+// HMAC helpers
+// ---------------------------------------------------------------------------
+/**
+ * Constant-time comparison of two HMAC digests.
+ * Returns true when the signature header matches the expected value.
+ */
+function verifySignature(body, secret, signatureHeader) {
+    if (!signatureHeader.startsWith('sha256='))
+        return false;
+    const supplied = signatureHeader.slice('sha256='.length);
+    const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
+    try {
+        return crypto.timingSafeEqual(Buffer.from(supplied, 'hex'), Buffer.from(expected, 'hex'));
+    }
+    catch {
+        // timingSafeEqual throws when buffers differ in length.
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Config loader
+// ---------------------------------------------------------------------------
+export async function loadWebhookConfig(configPath) {
+    const raw = await fs.readFile(configPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Webhook config must be a JSON object');
+    }
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Synthetic CronJob factory
+// ---------------------------------------------------------------------------
+let webhookJobCounter = 0;
+function buildWebhookJob(source, src, bodyText, guildId) {
+    webhookJobCounter += 1;
+    const id = `webhook-${source}-${webhookJobCounter}`;
+    const prompt = src.prompt !== undefined
+        ? src.prompt.replaceAll('{{body}}', bodyText).replaceAll('{{source}}', source)
+        : `A webhook event was received from source "${source}".\n\nPayload:\n${bodyText}`;
+    return {
+        id,
+        cronId: '',
+        threadId: '',
+        guildId,
+        name: `webhook:${source}`,
+        def: {
+            triggerType: 'webhook',
+            timezone: 'UTC',
+            channel: src.channel,
+            prompt,
+        },
+        cron: null,
+        running: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// Request body reader
+// ---------------------------------------------------------------------------
+const MAX_BODY_BYTES = 256 * 1024; // 256 KB
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                req.destroy();
+                reject(new Error('Request body too large'));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+}
+// ---------------------------------------------------------------------------
+// HTTP response helpers
+// ---------------------------------------------------------------------------
+function respond(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: status < 400, message: body }));
+}
+/**
+ * Start the webhook HTTP server.
+ *
+ * Returns a handle with the underlying `http.Server` and a `close()` method.
+ */
+export async function startWebhookServer(opts) {
+    const { configPath, port = 8080, host = '127.0.0.1', guildId, executorCtx, log, } = opts;
+    // Load config eagerly so startup fails fast on bad JSON.
+    let config = await loadWebhookConfig(configPath);
+    log?.info({ configPath, sources: Object.keys(config) }, 'webhook:config loaded');
+    const server = http.createServer(async (req, res) => {
+        // Only handle POST /webhook/:source
+        const url = req.url ?? '';
+        const match = url.match(/^\/webhook\/([^/?#]+)$/);
+        if (!match) {
+            respond(res, 404, 'Not found');
+            return;
+        }
+        if (req.method !== 'POST') {
+            respond(res, 405, 'Method Not Allowed');
+            return;
+        }
+        let source;
+        try {
+            source = decodeURIComponent(match[1]);
+        }
+        catch {
+            respond(res, 400, 'Bad request');
+            return;
+        }
+        const src = config[source];
+        if (!src) {
+            log?.warn({ source }, 'webhook:unknown source');
+            // Return 404 to avoid leaking which sources exist.
+            respond(res, 404, 'Not found');
+            return;
+        }
+        // Read body before verifying signature.
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg === 'Request body too large') {
+                log?.warn({ source }, 'webhook:body too large');
+                respond(res, 413, 'Payload Too Large');
+                return;
+            }
+            log?.warn({ source, err }, 'webhook:body read error');
+            respond(res, 400, 'Bad request');
+            return;
+        }
+        // Verify HMAC signature.
+        const sigHeader = String(req.headers['x-hub-signature-256'] ?? '');
+        if (!verifySignature(body, src.secret, sigHeader)) {
+            log?.warn({ source }, 'webhook:signature verification failed');
+            respond(res, 401, 'Unauthorized');
+            return;
+        }
+        // Signature OK — ack immediately, then dispatch in the background.
+        respond(res, 202, 'Accepted');
+        const bodyText = body.toString('utf8');
+        const job = buildWebhookJob(source, src, bodyText, guildId);
+        log?.info({ source, jobId: job.id, channel: src.channel }, 'webhook:dispatching');
+        // Fire-and-forget — errors are handled inside executeCronJob.
+        void executeCronJob(job, executorCtx).catch((err) => {
+            log?.error({ source, jobId: job.id, err }, 'webhook:executor error');
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => resolve());
+    });
+    log?.info({ port, host }, 'webhook:server listening');
+    return {
+        server,
+        close() {
+            return new Promise((resolve, reject) => {
+                server.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        },
+    };
+}

package/dist/webhook/server.test.js

@@ -0,0 +1,460 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import http from 'node:http';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { startWebhookServer, loadWebhookConfig } from './server.js';
+import { executeCronJob } from '../cron/executor.js';
+vi.mock('../cron/executor.js', () => ({
+    executeCronJob: vi.fn().mockResolvedValue(undefined),
+}));
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function signBody(body, secret) {
+    const hmac = crypto.createHmac('sha256', secret);
+    hmac.update(typeof body === 'string' ? Buffer.from(body, 'utf8') : body);
+    return 'sha256=' + hmac.digest('hex');
+}
+function makeRequest(port, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const rawBody = opts.body ?? '';
+        const bodyBuf = typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf8') : rawBody;
+        const req = http.request({
+            hostname: '127.0.0.1',
+            port,
+            path: opts.path ?? '/',
+            method: opts.method ?? 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': bodyBuf.length,
+                ...opts.headers,
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => {
+                const text = Buffer.concat(chunks).toString('utf8');
+                try {
+                    resolve({ status: res.statusCode ?? 0, body: JSON.parse(text) });
+                }
+                catch {
+                    reject(new Error(`Failed to parse response body: ${text}`));
+                }
+            });
+            res.on('error', reject);
+        });
+        req.on('error', reject);
+        if (bodyBuf.length)
+            req.write(bodyBuf);
+        req.end();
+    });
+}
+function mockLog() {
+    return { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+}
+// Give the fire-and-forget dispatch one event-loop tick to settle.
+function tick() {
+    return new Promise((r) => setImmediate(r));
+}
+// ---------------------------------------------------------------------------
+// loadWebhookConfig
+// ---------------------------------------------------------------------------
+describe('loadWebhookConfig', () => {
+    let tmpDir;
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'webhook-cfg-'));
+    });
+    afterEach(async () => {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    it('parses a valid config file', async () => {
+        const config = {
+            github: { secret: 'abc123', channel: 'deploys' },
+            alerts: { secret: 'xyz789', channel: 'ops', prompt: 'Handle alert' },
+        };
+        const cfgPath = path.join(tmpDir, 'webhooks.json');
+        await fs.writeFile(cfgPath, JSON.stringify(config), 'utf8');
+        const loaded = await loadWebhookConfig(cfgPath);
+        expect(loaded).toEqual(config);
+    });
+    it('throws when file does not exist', async () => {
+        await expect(loadWebhookConfig(path.join(tmpDir, 'missing.json'))).rejects.toThrow();
+    });
+    it('throws when JSON is invalid', async () => {
+        const cfgPath = path.join(tmpDir, 'bad.json');
+        await fs.writeFile(cfgPath, 'not json', 'utf8');
+        await expect(loadWebhookConfig(cfgPath)).rejects.toThrow();
+    });
+    it('throws when config is an array', async () => {
+        const cfgPath = path.join(tmpDir, 'array.json');
+        await fs.writeFile(cfgPath, '[]', 'utf8');
+        await expect(loadWebhookConfig(cfgPath)).rejects.toThrow('Webhook config must be a JSON object');
+    });
+    it('throws when config is a primitive', async () => {
+        const cfgPath = path.join(tmpDir, 'prim.json');
+        await fs.writeFile(cfgPath, '"hello"', 'utf8');
+        await expect(loadWebhookConfig(cfgPath)).rejects.toThrow('Webhook config must be a JSON object');
+    });
+});
+// ---------------------------------------------------------------------------
+// startWebhookServer — HTTP routing
+// ---------------------------------------------------------------------------
+describe('startWebhookServer HTTP routing', () => {
+    let tmpDir;
+    let port;
+    let handle;
+    const config = {
+        github: { secret: 'gh-secret', channel: 'deploys' },
+        alerts: { secret: 'alert-secret', channel: 'ops', prompt: 'Alert received.' },
+    };
+    const baseOpts = () => ({
+        host: '127.0.0.1',
+        guildId: 'guild-1',
+        executorCtx: {},
+        log: mockLog(),
+    });
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'webhook-srv-'));
+        const configPath = path.join(tmpDir, 'webhooks.json');
+        await fs.writeFile(configPath, JSON.stringify(config), 'utf8');
+        handle = await startWebhookServer({ ...baseOpts(), configPath, port: 0 });
+        const addr = handle.server.address();
+        port = addr.port;
+    });
+    afterEach(async () => {
+        await handle.close();
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    it('returns 404 for paths that do not match /webhook/:source', async () => {
+        const res = await makeRequest(port, { path: '/not-a-webhook' });
+        expect(res.status).toBe(404);
+        expect(res.body.ok).toBe(false);
+    });
+    it('returns 404 for root path', async () => {
+        const res = await makeRequest(port, { path: '/' });
+        expect(res.status).toBe(404);
+    });
+    it('returns 404 for /webhook/ with no source segment', async () => {
+        const res = await makeRequest(port, { path: '/webhook/' });
+        expect(res.status).toBe(404);
+    });
+    it('returns 405 for GET requests', async () => {
+        const res = await makeRequest(port, { path: '/webhook/github', method: 'GET' });
+        expect(res.status).toBe(405);
+        expect(res.body.ok).toBe(false);
+    });
+    it('returns 405 for PUT requests', async () => {
+        const res = await makeRequest(port, { path: '/webhook/github', method: 'PUT' });
+        expect(res.status).toBe(405);
+    });
+    it('returns 400 for a malformed percent-encoded source (%GG)', async () => {
+        const res = await makeRequest(port, { path: '/webhook/%GG' });
+        expect(res.status).toBe(400);
+        expect(res.body.ok).toBe(false);
+    });
+    it('returns 400 for another malformed percent-encoding (foo%ZZbar)', async () => {
+        const res = await makeRequest(port, { path: '/webhook/foo%ZZbar' });
+        expect(res.status).toBe(400);
+    });
+    it('returns 404 for an unknown source', async () => {
+        const body = '{}';
+        const res = await makeRequest(port, {
+            path: '/webhook/unknown-source',
+            body,
+            headers: { 'x-hub-signature-256': signBody(body, 'any') },
+        });
+        expect(res.status).toBe(404);
+        expect(res.body.ok).toBe(false);
+    });
+    it('returns 401 when the signature header is absent', async () => {
+        const res = await makeRequest(port, { path: '/webhook/github', body: '{"event":"push"}' });
+        expect(res.status).toBe(401);
+        expect(res.body.ok).toBe(false);
+    });
+    it('returns 401 for a malformed signature value', async () => {
+        const res = await makeRequest(port, {
+            path: '/webhook/github',
+            body: '{"event":"push"}',
+            headers: { 'x-hub-signature-256': 'sha256=deadbeef' },
+        });
+        expect(res.status).toBe(401);
+    });
+    it('returns 401 when the signature uses the wrong secret', async () => {
+        const body = '{"event":"push"}';
+        const res = await makeRequest(port, {
+            path: '/webhook/github',
+            body,
+            headers: { 'x-hub-signature-256': signBody(body, 'wrong-secret') },
+        });
+        expect(res.status).toBe(401);
+    });
+    it('returns 202 for a valid signed POST', async () => {
+        const body = '{"event":"push"}';
+        const res = await makeRequest(port, {
+            path: '/webhook/github',
+            body,
+            headers: { 'x-hub-signature-256': signBody(body, 'gh-secret') },
+        });
+        expect(res.status).toBe(202);
+        expect(res.body.ok).toBe(true);
+    });
+    it('accepts a valid request with an empty body', async () => {
+        const body = '';
+        const res = await makeRequest(port, {
+            path: '/webhook/github',
+            body,
+            headers: { 'x-hub-signature-256': signBody(body, 'gh-secret') },
+        });
+        expect(res.status).toBe(202);
+    });
+});
+// ---------------------------------------------------------------------------
+// startWebhookServer — executeCronJob dispatch
+// ---------------------------------------------------------------------------
+describe('startWebhookServer dispatch', () => {
+    let tmpDir;
+    let port;
+    let handle;
+    const config = {
+        github: { secret: 'gh-secret', channel: 'deploys' },
+        alerts: { secret: 'alert-secret', channel: 'ops', prompt: 'Alert: {{body}}' },
+        notify: { secret: 'notify-secret', channel: 'general', prompt: 'Event from {{source}}!' },
+        combined: { secret: 'combined-secret', channel: 'all', prompt: '{{source}} says: {{body}}' },
+        static: { secret: 'static-secret', channel: 'static-ch', prompt: 'No placeholders here' },
+        multi: { secret: 'multi-secret', channel: 'multi-ch', prompt: '{{body}} then {{body}} again' },
+    };
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'webhook-disp-'));
+        const configPath = path.join(tmpDir, 'webhooks.json');
+        await fs.writeFile(configPath, JSON.stringify(config), 'utf8');
+        handle = await startWebhookServer({
+            configPath,
+            port: 0,
+            host: '127.0.0.1',
+            guildId: 'guild-1',
+            executorCtx: {},
+            log: mockLog(),
+        });
+        const addr = handle.server.address();
+        port = addr.port;
+    });
+    afterEach(async () => {
+        await handle.close();
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    const sourceSecrets = {
+        github: 'gh-secret',
+        alerts: 'alert-secret',
+        notify: 'notify-secret',
+        combined: 'combined-secret',
+        static: 'static-secret',
+        multi: 'multi-secret',
+    };
+    async function postValid(source, body = '{}') {
+        return makeRequest(port, {
+            path: `/webhook/${source}`,
+            body,
+            headers: { 'x-hub-signature-256': signBody(body, sourceSecrets[source]) },
+        });
+    }
+    it('calls executeCronJob once after a valid request', async () => {
+        await postValid('github');
+        await tick();
+        expect(vi.mocked(executeCronJob)).toHaveBeenCalledOnce();
+    });
+    it('does not call executeCronJob for an invalid signature', async () => {
+        await makeRequest(port, {
+            path: '/webhook/github',
+            body: '{}',
+            headers: { 'x-hub-signature-256': 'sha256=invalid' },
+        });
+        await tick();
+        expect(vi.mocked(executeCronJob)).not.toHaveBeenCalled();
+    });
+    it('dispatches job with correct guildId and channel', async () => {
+        await postValid('github');
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.guildId).toBe('guild-1');
+        expect(job.def.channel).toBe('deploys');
+    });
+    it('builds default prompt from source name and body when no custom prompt is set', async () => {
+        const body = 'payload data here';
+        await postValid('github', body);
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.def.prompt).toContain('github');
+        expect(job.def.prompt).toContain('payload data here');
+    });
+    it('uses the custom prompt when one is configured', async () => {
+        await postValid('alerts', '{"level":"warn"}');
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.def.prompt).toBe('Alert: {"level":"warn"}');
+    });
+    it('replaces {{source}} in a custom prompt with the source name', async () => {
+        await postValid('notify', '{}');
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.def.prompt).toBe('Event from notify!');
+    });
+    it('replaces both {{body}} and {{source}} in a custom prompt', async () => {
+        await postValid('combined', 'hello world');
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.def.prompt).toBe('combined says: hello world');
+    });
+    it('passes through a custom prompt with no placeholders unchanged', async () => {
+        await postValid('static', '{}');
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.def.prompt).toBe('No placeholders here');
+    });
+    it('replaces all occurrences of {{body}} when it appears multiple times', async () => {
+        await postValid('multi', 'ping');
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.def.prompt).toBe('ping then ping again');
+    });
+    it('names the job with the source', async () => {
+        await postValid('github');
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.name).toBe('webhook:github');
+    });
+    it('assigns a unique id to each dispatch', async () => {
+        await postValid('github');
+        await tick();
+        await postValid('github');
+        await tick();
+        const calls = vi.mocked(executeCronJob).mock.calls;
+        expect(calls).toHaveLength(2);
+        const id0 = calls[0][0].id;
+        const id1 = calls[1][0].id;
+        expect(id0).not.toBe(id1);
+    });
+    it('leaves schedule undefined and sets timezone to UTC on the synthetic job', async () => {
+        await postValid('github');
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.def.schedule).toBeUndefined();
+        expect(job.def.timezone).toBe('UTC');
+    });
+    it('sets triggerType to webhook on the synthetic job', async () => {
+        await postValid('github');
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.def.triggerType).toBe('webhook');
+    });
+    it('decodes a valid percent-encoded source name before looking it up', async () => {
+        // 'alerts' with the first character 'a' encoded as %61
+        const body = '{}';
+        const res = await makeRequest(port, {
+            path: '/webhook/%61lerts',
+            body,
+            headers: { 'x-hub-signature-256': signBody(body, 'alert-secret') },
+        });
+        expect(res.status).toBe(202);
+        await tick();
+        const [job] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(job.name).toBe('webhook:alerts');
+    });
+    it('passes the executorCtx through to executeCronJob', async () => {
+        const executorCtx = { __marker: 'test-ctx' };
+        const cfgPath = path.join(tmpDir, 'webhooks2.json');
+        await fs.writeFile(cfgPath, JSON.stringify(config), 'utf8');
+        const h2 = await startWebhookServer({
+            configPath: cfgPath,
+            port: 0,
+            host: '127.0.0.1',
+            guildId: 'g2',
+            executorCtx,
+            log: mockLog(),
+        });
+        const p2 = h2.server.address().port;
+        const body = '{}';
+        await makeRequest(p2, {
+            path: '/webhook/github',
+            body,
+            headers: { 'x-hub-signature-256': signBody(body, 'gh-secret') },
+        });
+        await tick();
+        await h2.close();
+        const [, ctx] = vi.mocked(executeCronJob).mock.calls[0];
+        expect(ctx).toBe(executorCtx);
+    });
+});
+// ---------------------------------------------------------------------------
+// startWebhookServer — body size limit
+// ---------------------------------------------------------------------------
+describe('startWebhookServer body size limit', () => {
+    let tmpDir;
+    let port;
+    let handle;
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'webhook-body-'));
+        const configPath = path.join(tmpDir, 'webhooks.json');
+        await fs.writeFile(configPath, JSON.stringify({ src: { secret: 's', channel: 'c' } }), 'utf8');
+        handle = await startWebhookServer({
+            configPath,
+            port: 0,
+            host: '127.0.0.1',
+            guildId: 'guild-1',
+            executorCtx: {},
+            log: mockLog(),
+        });
+        const addr = handle.server.address();
+        port = addr.port;
+    });
+    afterEach(async () => {
+        await handle.close();
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    it('returns 413 or closes connection for a 257 KB body, and never dispatches', async () => {
+        const bigBody = Buffer.alloc(257 * 1024, 0x78); // 257 KB of 'x'
+        let status;
+        try {
+            const res = await makeRequest(port, {
+                path: '/webhook/src',
+                body: bigBody,
+                headers: { 'x-hub-signature-256': signBody(bigBody, 's') },
+            });
+            status = res.status;
+        }
+        catch {
+            // req.destroy() on the server side may reset the connection before the
+            // 413 response can be flushed to the client.
+        }
+        // If a response was received it must be 413.
+        if (status !== undefined) {
+            expect(status).toBe(413);
+        }
+        // executeCronJob must never be called regardless of response fate.
+        await tick();
+        expect(vi.mocked(executeCronJob)).not.toHaveBeenCalled();
+    });
+});
+// ---------------------------------------------------------------------------
+// startWebhookServer — close
+// ---------------------------------------------------------------------------
+describe('startWebhookServer close', () => {
+    it('close() resolves and the server stops accepting connections', async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'webhook-close-'));
+        const configPath = path.join(tmpDir, 'webhooks.json');
+        await fs.writeFile(configPath, JSON.stringify({}), 'utf8');
+        const handle = await startWebhookServer({
+            configPath,
+            port: 0,
+            host: '127.0.0.1',
+            guildId: 'guild-1',
+            executorCtx: {},
+        });
+        const { port } = handle.server.address();
+        await handle.close();
+        // After close, new connections should be refused.
+        await expect(makeRequest(port, { path: '/' })).rejects.toThrow();
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+});