add-handler

name	add-handler
description	Step-by-step guide for creating a new PR handler for auto-me-bot GitHub App, including handler file, tests, CONFIG_SPEC registration, and documentation

What I do

• Create handler files at src/handlers/pr-<name>.js with match() and run() functions
• Implement match() to return boolean based on payload event and actions
• Implement run() with check-run lifecycle: in_progress → operations → completed
• Generate test files at tests/handlers/pr-<name>.test.js with Sinon stubs and full coverage
• Add handler to CONFIG_SPEC and events to ON_EVENTS in src/auto-me-bot.js
• Update test registration in tests/auto-me-bot.test.js (stubs, allHandlers, patchedConfigSpec)
• Create handler docs, update mkdocs.yml navigation, config.md, and examples.md
• Verify: handler file, tests, registration, documentation, tests pass, lint passes

When to use me

Use when you want to add a new handler to auto-me-bot. Ask clarifying questions if the handler's purpose, config type, or target webhook events are not specified.

Prerequisites

• Understand the handler contract (match + run functions)
• Know which GitHub webhook event(s) the handler should respond to
• Have a clear definition of what the handler should check/enforce

Steps

1. Create Handler File

• Location: src/handlers/<config-type>-<handler-name>.js
• For PR handlers: src/handlers/pr-<handler-name>.js

2. Implement match() Function

function match(context) {
    let event = 'pull_request';
    let actions = ['opened', 'edited']; // Adjust based on handler needs
    return event in context.payload ? actions.includes(context.payload.action) : false;
}

3. Implement run() Function

const CHECK_NAME = 'Handler Name';
const BOT_CHECK_URL = 'https://auto-me-bot.figenblat.com/handlers/handler-name';

async function run(context, config, startedAt) {
    let checkRun = await context.octokit.checks.create(context.repo({
        head_sha: context.payload.pull_request.head.sha,
        name: CHECK_NAME,
        details_url: BOT_CHECK_URL,
        started_at: startedAt,
        status: 'in_progress'
    }));

    try {
        let success = true; // Replace with actual logic

        await context.octokit.checks.update(context.repo({
            check_run_id: checkRun.data.id,
            name: CHECK_NAME,
            details_url: BOT_CHECK_URL,
            started_at: startedAt,
            status: 'completed',
            completed_at: new Date().toISOString(),
            conclusion: success ? 'success' : 'failure',
            output: {
                title: success ? 'Success message' : 'Failure message',
                summary: 'Detailed explanation'
            }
        }));
    } catch (error) {
        await context.octokit.checks.update(context.repo({
            check_run_id: checkRun.data.id,
            status: 'completed',
            conclusion: 'failure',
            output: {
                title: 'Error occurred',
                summary: error.message
            }
        }));
    }
}

export default {match, run}

4. Create Test File

• Location: tests/handlers/<config-type>-<handler-name>.test.js
• Test both match() and run() functions
• Use Sinon to stub context.octokit methods
• Achieve full coverage

5. Register Handler

Edit src/auto-me-bot.js:

import handlerName from './handlers/pr-handler-name.js'

const CONFIG_SPEC = Object.freeze({
    pr: {
        // ... existing handlers
        handlerName: handlerName,
    }
});

const ON_EVENTS = Object.freeze([
    // ... existing events
    'pull_request.opened', // Example
]);

6. Update Test Registration

Edit tests/auto-me-bot.test.js:

• Create stub in beforeEach
• Add stub to allHandlers list
• Add patch to patchedConfigSpec

7. Create Documentation

• Create docs/handlers/handler-name.md
• Update mkdocs.yml navigation
• Update docs/config.md
• Add example to docs/examples.md

8. Test Everything

npm run lint
npm test
mkdocs serve

Verification

• Handler file created with match() and run()
• Test file created with full coverage
• Handler registered in CONFIG_SPEC
• Events added to ON_EVENTS
• Test registration updated
• Documentation created
• All tests pass
• Linting passes