@armstrongnate/april 0.0.1

package/README.md

@@ -0,0 +1,81 @@
+# april
+
+She does all the work so you don't have to, and with about the same level of enthusiasm.
+
+april watches for GitHub issues assigned to you with a specific label, then spins up a Claude Code session in a tmux window to work the issue end-to-end — from reading the issue to opening a PR.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) >= 22
+- [gh](https://cli.github.com/) (authenticated)
+- [tmux](https://github.com/tmux/tmux)
+- [Claude Code](https://claude.ai/claude-code) CLI
+
+## Install
+
+```bash
+npm i -g @armstrongnate/april
+# or: pnpm add -g @armstrongnate/april
+```
+
+Then:
+
+```bash
+april init                         # writes ~/.config/april/config.yaml + installs the issue-worker skill
+$EDITOR ~/.config/april/config.yaml
+april install                      # registers the user service and starts it
+april logs -f
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `april init` | Copies the bundled `config.example.yaml` to `~/.config/april/config.yaml` and the `issue-worker` skill to `~/.claude/skills/`. Won't overwrite without `--force`. |
+| `april install` | Installs and starts the user service. Pass `--print` to see the unit/plist without writing it. |
+| `april uninstall` | Stops and removes the service. |
+| `april start` / `stop` / `restart` | Lifecycle. |
+| `april status` | Shows service status. |
+| `april logs -f [-n N]` | Streams logs. `-n` sets line count (default 100). |
+| `april daemon` | Runs the worker in the foreground (for debugging; the service uses `dist/index.js` directly). |
+
+## Service backend
+
+- **Linux** uses systemd user services at `~/.config/systemd/user/april.service`. Logs go to the journal (`journalctl --user -u april`).
+- **macOS** uses launchd LaunchAgents at `~/Library/LaunchAgents/dev.april.daemon.plist`. Logs go to `~/Library/Logs/april/april.log`.
+
+### Linux: keep april running after logout
+
+User services stop when you log out unless linger is enabled. On a server you SSH into:
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+`april install` reminds you if it sees linger is off.
+
+### Node version managers
+
+`april install` captures the absolute path of the `node` binary it was invoked with (e.g. `~/.nvm/versions/node/v22.x.x/bin/node`) and bakes it into the unit/plist. If you later remove or change that node version, the service will fail to start — re-run `april install` after switching.
+
+## Usage
+
+Once installed, label a GitHub issue with `agent:todo` and assign it to yourself. april will:
+
+1. Create a git worktree for the issue
+2. Run any configured post-worktree hooks (e.g. `pnpm i`)
+3. Spawn a tmux session with Claude Code
+4. Claude reads the issue, implements a fix, and opens a PR
+5. Issue labels transition: `agent:todo` → `agent:wip` → `agent:review`
+
+Attach to a running session anytime with `tmux attach -t <session-name>`.
+
+## Development
+
+```bash
+pnpm install
+cp config.example.yaml config.yaml
+pnpm dev
+```
+
+`pnpm dev` runs the daemon in the foreground from the source tree. Config is loaded from `~/.config/april/config.yaml` if it exists, otherwise `./config.yaml`.

package/config.example.yaml

@@ -0,0 +1,16 @@
+assignee: "your-github-username"
+label: "agent:todo"
+claudeSkill: "issue-worker"
+# claudeModel: "opus"              # optional, defaults to opus
+# claudeAllowedTools:              # optional, defaults to Edit, Write, Bash(*)
+#   - "Edit"
+#   - "Write"
+#   - "Bash(*)"
+port: 7890
+repos:
+  - owner: "org"
+    name: "repo-name"
+    path: "~/path/to/repo"
+    # defaultBranch: "main"         # optional, defaults to main
+    # slackChannel: "team-channel"  # optional, posts PR link to this channel
+    # postWorktreeHook: "pnpm i"   # optional, runs in worktree after creation

package/dist/cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { backend } from "./service/index.js";
+import { run as runInit } from "./commands/init.js";
+const HELP = `april — issue worker
+
+Usage:
+  april <command> [options]
+
+Commands:
+  init              Copy bundled config + skill to ~/.config/april and ~/.claude
+  install [--print] Install and start the user service. --print emits the unit/plist to stdout instead.
+  uninstall         Stop and remove the user service
+  start             Start the service
+  stop              Stop the service
+  restart           Restart the service
+  status            Show service status
+  logs [-f] [-n N]  Show service logs (-f to follow, -n lines, default 100)
+  daemon            Run april in the foreground (used by the service; rarely invoked directly)
+  help              Show this help
+  version           Show version
+
+Options for init:
+  --force, -f       Overwrite existing files
+`;
+function parseLogsArgs(args) {
+    let follow = false;
+    let lines = 100;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "-f" || a === "--follow") {
+            follow = true;
+        }
+        else if (a === "-n" || a === "--lines") {
+            const v = args[i + 1];
+            if (!v)
+                throw new Error(`${a} requires a value`);
+            const n = parseInt(v, 10);
+            if (Number.isNaN(n) || n < 0)
+                throw new Error(`${a} value must be a non-negative integer`);
+            lines = n;
+            i++;
+        }
+        else if (/^-n\d+$/.test(a)) {
+            lines = parseInt(a.slice(2), 10);
+        }
+        else {
+            throw new Error(`unknown option: ${a}`);
+        }
+    }
+    return { follow, lines };
+}
+async function readVersion() {
+    const { readFileSync } = await import("node:fs");
+    const { fileURLToPath } = await import("node:url");
+    const { dirname, resolve } = await import("node:path");
+    const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf-8"));
+    return pkg.version;
+}
+async function main() {
+    const [, , cmd, ...rest] = process.argv;
+    if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+        console.log(HELP);
+        return 0;
+    }
+    if (cmd === "version" || cmd === "--version" || cmd === "-v") {
+        console.log(await readVersion());
+        return 0;
+    }
+    if (cmd === "init") {
+        return runInit(rest);
+    }
+    if (cmd === "daemon") {
+        // Run the long-running process inline. Importing index.js triggers main();
+        // we then hang forever and let its SIGINT/SIGTERM handlers terminate the process.
+        await import("./index.js");
+        await new Promise(() => { });
+        return 0; // unreachable
+    }
+    // Service commands
+    const svc = backend();
+    switch (cmd) {
+        case "install":
+            if (rest.includes("--print")) {
+                process.stdout.write(svc.serviceFile());
+                return 0;
+            }
+            svc.install();
+            return 0;
+        case "uninstall":
+            svc.uninstall();
+            return 0;
+        case "start":
+            svc.start();
+            console.log("✓ Started");
+            return 0;
+        case "stop":
+            svc.stop();
+            console.log("✓ Stopped");
+            return 0;
+        case "restart":
+            svc.restart();
+            console.log("✓ Restarted");
+            return 0;
+        case "status":
+            return svc.status();
+        case "logs": {
+            const { follow, lines } = parseLogsArgs(rest);
+            return svc.logs(follow, lines);
+        }
+        default:
+            console.error(`Unknown command: ${cmd}`);
+            console.error(HELP);
+            return 2;
+    }
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/commands/init.js

@@ -0,0 +1,48 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+// Resolve the bundled package root from this file's installed location.
+// dist/commands/init.js -> dist/.. (the package root, where config.example.yaml + skills/ live)
+function packageRoot() {
+    const here = fileURLToPath(import.meta.url);
+    return resolve(dirname(here), "..", "..");
+}
+function copyIfMissing(src, dst, label, force) {
+    mkdirSync(dirname(dst), { recursive: true });
+    if (existsSync(dst) && !force) {
+        console.log(`  ${label}: already exists at ${dst} (use --force to overwrite)`);
+        return "exists";
+    }
+    copyFileSync(src, dst);
+    console.log(`  ${label}: wrote ${dst}`);
+    return "wrote";
+}
+export function run(args) {
+    const force = args.includes("--force") || args.includes("-f");
+    const root = packageRoot();
+    console.log("april init");
+    console.log("");
+    const configSrc = join(root, "config.example.yaml");
+    const configDst = join(homedir(), ".config", "april", "config.yaml");
+    if (!existsSync(configSrc)) {
+        console.error(`  Cannot find bundled config.example.yaml at ${configSrc}`);
+        return 1;
+    }
+    const configResult = copyIfMissing(configSrc, configDst, "config", force);
+    const skillSrc = join(root, "skills", "issue-worker", "SKILL.md");
+    const skillDst = join(homedir(), ".claude", "skills", "issue-worker", "SKILL.md");
+    if (!existsSync(skillSrc)) {
+        console.error(`  Cannot find bundled skill at ${skillSrc}`);
+        return 1;
+    }
+    copyIfMissing(skillSrc, skillDst, "skill", force);
+    console.log("");
+    if (configResult === "wrote") {
+        console.log(`Next: edit ${configDst}, then run \`april install\`.`);
+    }
+    else {
+        console.log(`Next: review ${configDst}, then run \`april install\`.`);
+    }
+    return 0;
+}

package/dist/config.js

@@ -0,0 +1,97 @@
+import { readFileSync, existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+import { parse as parseYaml } from "yaml";
+import { createLogger } from "./logger.js";
+const log = createLogger("config");
+function findConfigPath() {
+    const envPath = process.env.APRIL_CONFIG;
+    if (envPath) {
+        if (!existsSync(envPath)) {
+            throw new Error(`Config file from APRIL_CONFIG not found: ${envPath}`);
+        }
+        return resolve(envPath);
+    }
+    const xdgPath = join(homedir(), ".config", "april", "config.yaml");
+    if (existsSync(xdgPath)) {
+        return xdgPath;
+    }
+    const localPath = resolve("config.yaml");
+    if (existsSync(localPath)) {
+        return localPath;
+    }
+    throw new Error("No config file found. Searched:\n" +
+        `  - APRIL_CONFIG env var (not set)\n` +
+        `  - ${xdgPath}\n` +
+        `  - ${localPath}\n` +
+        "Create a config.yaml (see config.example.yaml).");
+}
+function validateTools() {
+    const tools = ["gh", "tmux", "git", "claude"];
+    for (const tool of tools) {
+        try {
+            execSync(`which ${tool}`, { stdio: "pipe" });
+        }
+        catch {
+            throw new Error(`Required tool "${tool}" not found on PATH. Install it before running april.`);
+        }
+    }
+}
+function validateString(obj, key, context) {
+    const val = obj[key];
+    if (typeof val !== "string" || val.trim().length === 0) {
+        throw new Error(`${context}: "${key}" is required and must be a non-empty string`);
+    }
+    return val.trim();
+}
+export function loadConfig() {
+    validateTools();
+    const configPath = findConfigPath();
+    log.info(`Loading config from ${configPath}`);
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = parseYaml(raw);
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("Config file is empty or not a valid YAML object");
+    }
+    const assignee = validateString(parsed, "assignee", "config");
+    const label = validateString(parsed, "label", "config");
+    const claudeSkill = validateString(parsed, "claudeSkill", "config");
+    const claudeModel = typeof parsed.claudeModel === "string" ? parsed.claudeModel.trim() : undefined;
+    const claudeAllowedTools = Array.isArray(parsed.claudeAllowedTools)
+        ? parsed.claudeAllowedTools.filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => t.trim())
+        : undefined;
+    const port = Number(parsed.port);
+    if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+        throw new Error(`config: "port" must be an integer between 1024 and 65535, got: ${parsed.port}`);
+    }
+    if (!Array.isArray(parsed.repos) || parsed.repos.length === 0) {
+        throw new Error("config: \"repos\" must be a non-empty array");
+    }
+    const repos = parsed.repos.map((r, i) => {
+        if (!r || typeof r !== "object") {
+            throw new Error(`config.repos[${i}]: must be an object`);
+        }
+        const repo = r;
+        const owner = validateString(repo, "owner", `config.repos[${i}]`);
+        const name = validateString(repo, "name", `config.repos[${i}]`);
+        const path = validateString(repo, "path", `config.repos[${i}]`);
+        const resolvedPath = resolve(path.startsWith("~") ? path.replace("~", homedir()) : path);
+        if (!existsSync(resolvedPath)) {
+            throw new Error(`config.repos[${i}]: path does not exist: ${resolvedPath}`);
+        }
+        const defaultBranch = typeof repo.defaultBranch === "string" && repo.defaultBranch.trim().length > 0
+            ? repo.defaultBranch.trim()
+            : "main";
+        const slackChannel = typeof repo.slackChannel === "string" && repo.slackChannel.trim().length > 0
+            ? repo.slackChannel.trim()
+            : undefined;
+        const postWorktreeHook = typeof repo.postWorktreeHook === "string" && repo.postWorktreeHook.trim().length > 0
+            ? repo.postWorktreeHook.trim()
+            : undefined;
+        return { owner, name, path: resolvedPath, defaultBranch, slackChannel, postWorktreeHook };
+    });
+    const config = { assignee, label, claudeSkill, claudeModel, claudeAllowedTools, port, repos };
+    log.info(`Config loaded: assignee=${assignee}, label=${label}, repos=${repos.map((r) => `${r.owner}/${r.name}`).join(", ")}`);
+    return config;
+}

package/dist/index.js

@@ -0,0 +1,114 @@
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { createLogger } from "./logger.js";
+import { loadConfig } from "./config.js";
+import { handleNewIssue, fetchOpenIssues, isIssueActive, getActiveCounts } from "./spawner.js";
+import { startServer } from "./server.js";
+import { startWebhookForwarders, shutdownForwarders } from "./processes.js";
+const log = createLogger("main");
+const PID_PATH = join(homedir(), ".config", "april", "april.pid");
+function checkPidFile() {
+    if (!existsSync(PID_PATH))
+        return;
+    try {
+        const pid = parseInt(readFileSync(PID_PATH, "utf-8").trim(), 10);
+        if (Number.isNaN(pid))
+            return;
+        try {
+            process.kill(pid, 0);
+            log.warn(`Another april instance may be running (pid=${pid}). Proceeding anyway.`);
+        }
+        catch {
+            log.debug("Stale PID file found, removing");
+        }
+    }
+    catch {
+        // Can't read PID file, ignore
+    }
+}
+function writePidFile() {
+    const dir = dirname(PID_PATH);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(PID_PATH, String(process.pid), "utf-8");
+}
+function removePidFile() {
+    try {
+        unlinkSync(PID_PATH);
+    }
+    catch {
+        // Ignore
+    }
+}
+async function main() {
+    console.log("");
+    console.log("  april v0.0.1");
+    console.log("");
+    // 1. Load config
+    const config = loadConfig();
+    // 2. PID file check
+    checkPidFile();
+    writePidFile();
+    // 3. Reconcile missed issues
+    for (const repo of config.repos) {
+        log.info(`Checking for missed issues in ${repo.owner}/${repo.name}...`);
+        const openIssues = fetchOpenIssues(repo, config);
+        for (const issue of openIssues) {
+            if (!isIssueActive(repo, issue.number)) {
+                log.info(`Found missed issue: #${issue.number} — "${issue.title}"`);
+                await handleNewIssue(repo, issue, config);
+            }
+        }
+    }
+    // 4. Start HTTP server
+    const onNewIssue = async (result) => {
+        await handleNewIssue(result.repo, result.issue, config);
+    };
+    let server;
+    try {
+        server = await startServer(config, onNewIssue);
+    }
+    catch (err) {
+        log.error(`Failed to start server: ${err instanceof Error ? err.message : String(err)}`);
+        removePidFile();
+        process.exit(1);
+    }
+    // 5. Start webhook forwarders
+    const children = startWebhookForwarders(config);
+    // Print startup banner
+    const { worktrees, sessions } = getActiveCounts(config);
+    const repoList = config.repos.map((r) => `${r.owner}/${r.name}`).join(", ");
+    console.log(`  Assignee: ${config.assignee}`);
+    console.log(`  Label: ${config.label}`);
+    console.log(`  Repos: ${repoList}`);
+    console.log(`  Active: ${worktrees} worktree${worktrees === 1 ? "" : "s"}, ${sessions} tmux session${sessions === 1 ? "" : "s"}`);
+    console.log(`  Server: http://localhost:${config.port}`);
+    console.log(`  Forwarders: ${children.length} active`);
+    console.log("");
+    // 6. Graceful shutdown
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log.info(`Received ${signal}, shutting down...`);
+        shutdownForwarders(children);
+        try {
+            await server.close();
+            log.info("Server closed");
+        }
+        catch {
+            // Ignore
+        }
+        removePidFile();
+        log.info("Goodbye");
+        process.exit(0);
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    removePidFile();
+    process.exit(1);
+});

package/dist/logger.js

@@ -0,0 +1,36 @@
+import { stdout } from "node:process";
+const isTTY = stdout.isTTY ?? false;
+const isDebug = process.env.APRIL_DEBUG === "1";
+const COLORS = {
+    info: "\x1b[36m", // cyan
+    warn: "\x1b[33m", // yellow
+    error: "\x1b[31m", // red
+    debug: "\x1b[90m", // gray
+};
+const RESET = "\x1b[0m";
+function format(level, component, message) {
+    const ts = new Date().toISOString();
+    const tag = `[${level}] [${component}]`;
+    if (isTTY) {
+        return `${COLORS[level]}${ts} ${tag}${RESET} ${message}`;
+    }
+    return `${ts} ${tag} ${message}`;
+}
+export function createLogger(component) {
+    return {
+        info(message) {
+            console.log(format("info", component, message));
+        },
+        warn(message) {
+            console.warn(format("warn", component, message));
+        },
+        error(message) {
+            console.error(format("error", component, message));
+        },
+        debug(message) {
+            if (isDebug) {
+                console.log(format("debug", component, message));
+            }
+        },
+    };
+}

package/dist/processes.js

@@ -0,0 +1,138 @@
+import { spawn, execFileSync } from "node:child_process";
+import { createLogger } from "./logger.js";
+const log = createLogger("forwarder");
+/**
+ * Delete any stale `cli` webhooks on a repo left behind by a previous
+ * gh webhook forward process that didn't shut down cleanly.
+ */
+function cleanupStaleWebhooks(repoKey) {
+    try {
+        const output = execFileSync("gh", [
+            "api", `repos/${repoKey}/hooks`, "--jq", '.[] | select(.name == "cli") | .id',
+        ], { encoding: "utf-8", timeout: 15_000, stdio: ["pipe", "pipe", "pipe"] });
+        const ids = output.trim().split("\n").filter(Boolean);
+        for (const id of ids) {
+            log.info(`Cleaning up stale webhook ${id} on ${repoKey}`);
+            try {
+                execFileSync("gh", ["api", "-X", "DELETE", `repos/${repoKey}/hooks/${id}`], {
+                    timeout: 15_000, stdio: "pipe",
+                });
+            }
+            catch (err) {
+                log.warn(`Failed to delete webhook ${id} on ${repoKey}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    catch {
+        // No hooks or API error — not critical, gh webhook forward will report the real error
+    }
+}
+const INITIAL_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30_000;
+const UPTIME_RESET_MS = 60_000;
+const MAX_CONSECUTIVE_FAILURES = 5;
+const forwarders = [];
+function spawnForwarder(config, repoKey, url) {
+    const state = {
+        child: null,
+        repoKey,
+        consecutiveFailures: 0,
+        lastStartTime: 0,
+        backoffMs: INITIAL_BACKOFF_MS,
+        stopped: false,
+    };
+    function start() {
+        if (state.stopped)
+            return;
+        state.lastStartTime = Date.now();
+        log.info(`Starting webhook forwarder for ${repoKey}`);
+        const child = spawn("gh", [
+            "webhook", "forward",
+            `--repo=${repoKey}`,
+            "--events=issues",
+            `--url=${url}`,
+        ], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        state.child = child;
+        child.stdout?.on("data", (data) => {
+            const lines = data.toString("utf-8").trim().split("\n");
+            for (const line of lines) {
+                if (line.trim())
+                    log.debug(`[${repoKey}] ${line}`);
+            }
+        });
+        child.stderr?.on("data", (data) => {
+            const lines = data.toString("utf-8").trim().split("\n");
+            for (const line of lines) {
+                if (line.trim())
+                    log.warn(`[${repoKey}] ${line}`);
+            }
+        });
+        child.on("exit", (code, signal) => {
+            if (state.stopped)
+                return;
+            const uptime = Date.now() - state.lastStartTime;
+            if (uptime >= UPTIME_RESET_MS) {
+                // Was running long enough, reset backoff
+                state.consecutiveFailures = 0;
+                state.backoffMs = INITIAL_BACKOFF_MS;
+            }
+            else {
+                state.consecutiveFailures++;
+                state.backoffMs = Math.min(state.backoffMs * 2, MAX_BACKOFF_MS);
+            }
+            if (state.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                log.error(`Forwarder for ${repoKey} failed ${MAX_CONSECUTIVE_FAILURES} consecutive times, giving up`);
+                return;
+            }
+            log.warn(`Forwarder for ${repoKey} exited (code=${code}, signal=${signal}), ` +
+                `restarting in ${state.backoffMs}ms (failure ${state.consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES})`);
+            setTimeout(() => start(), state.backoffMs);
+        });
+    }
+    start();
+    return state;
+}
+export function startWebhookForwarders(config) {
+    const url = `http://localhost:${config.port}/webhook/github`;
+    for (const repo of config.repos) {
+        const repoKey = `${repo.owner}/${repo.name}`;
+        cleanupStaleWebhooks(repoKey);
+        const state = spawnForwarder(config, repoKey, url);
+        forwarders.push(state);
+    }
+    return forwarders.map((f) => f.child);
+}
+export function shutdownForwarders(children) {
+    log.info("Shutting down webhook forwarders...");
+    // Mark all as stopped to prevent restarts
+    for (const f of forwarders) {
+        f.stopped = true;
+    }
+    // Send SIGTERM to all
+    for (const child of children) {
+        if (child && !child.killed) {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                // Already dead
+            }
+        }
+    }
+    // Force kill after 5s
+    setTimeout(() => {
+        for (const child of children) {
+            if (child && !child.killed) {
+                try {
+                    log.warn(`Force killing forwarder (pid=${child.pid})`);
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    // Already dead
+                }
+            }
+        }
+    }, 5000);
+}