@armstrongnate/april 0.0.1 → 0.0.3

package/README.md

@@ -8,25 +8,106 @@ april watches for GitHub issues assigned to you with a specific label, then spin
 
 - [Node.js](https://nodejs.org/) >= 22
 - [gh](https://cli.github.com/) (authenticated)
+- The `gh-webhook` extension: `gh extension install cli/gh-webhook`
 - [tmux](https://github.com/tmux/tmux)
 - [Claude Code](https://claude.ai/claude-code) CLI
 
-## Install
+## Quick install
 
 ```bash
 npm i -g @armstrongnate/april
-# or: pnpm add -g @armstrongnate/april
+april init                         # writes ~/.config/april/config.yaml + skill + env file; checks prereqs
+$EDITOR ~/.config/april/config.yaml
+april install                      # registers the user service and starts it
+april logs -f
+```
+
+`april init` and the daemon both verify that the `cli/gh-webhook` extension is installed and refuse to proceed without it.
+
+## Server install (full playbook)
+
+The minimal flow above leaves out auth setup and a few server-specific gotchas. This is the end-to-end recipe for a fresh Linux server.
+
+### 1. System prerequisites
+
+```bash
+# Install node 22+, tmux, gh, claude code via your usual route, then:
+gh extension install cli/gh-webhook
 ```
 
-Then:
+### 2. Create a Personal Access Token
+
+The systemd user service runs in a stripped-down environment — no shell config, no keyring/DBus, no credential helpers. Whatever clever auth you have set up in your interactive shell almost certainly will not be available to the daemon. **You need an explicit token in the env file.**
+
+Generate one on your GitHub host's web UI: Settings → Developer settings → Personal access tokens.
+
+**Classic PAT scopes:**
+- `repo` — issue read/write, label updates, PR creation, code access (no smaller scope works for private repo issues)
+- `admin:repo_hook` — needed for `gh webhook forward` to register and clean up its temporary `cli` webhook
+- `workflow` — only if Claude might modify `.github/workflows/*` files
+
+**Fine-grained PAT** (GHES 3.10+):
+- Repository access: select the repos
+- Permissions: Issues R/W, Pull requests R/W, Contents R/W, Webhooks R/W, Metadata R, Workflows R/W (last one optional)
+
+The daemon's own needs are smaller (Issues R/W + Webhooks R/W + Metadata R), but Claude inherits the same env when it runs inside tmux, so the token has to cover both — see [Token inheritance](#token-inheritance) below.
+
+### 3. Install the package
 
 ```bash
-april init                         # writes ~/.config/april/config.yaml + installs the issue-worker skill
+npm i -g @armstrongnate/april
+april init
 $EDITOR ~/.config/april/config.yaml
-april install                      # registers the user service and starts it
+```
+
+### 4. Configure auth in the env file
+
+```bash
+$EDITOR ~/.config/april/env
+```
+
+For a **GitHub Enterprise Server** host:
+
+```
+GH_HOST=your.ghes.host
+GH_ENTERPRISE_TOKEN=ghp_...
+```
+
+For **github.com**:
+
+```
+GH_TOKEN=ghp_...
+```
+
+`gh` is host-aware about which env var it reads: `GH_TOKEN` is github.com-only; `GH_ENTERPRISE_TOKEN` covers any other host (used together with `GH_HOST`). Setting `GH_TOKEN` while `GH_HOST` points elsewhere will silently fail.
+
+### 5. Install and start the service
+
+```bash
+april install
+```
+
+This writes `~/.config/systemd/user/april.service`, enables it, and starts it. The unit references the env file via `EnvironmentFile=-~/.config/april/env`, so anything you put there flows through on each restart.
+
+### 6. Enable linger (Linux servers)
+
+systemd user services stop when you log out unless linger is enabled. On any server you SSH out of:
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+`april install` warns you if it sees this is off.
+
+### 7. Verify
+
+```bash
+april status
 april logs -f
 ```
 
+Healthy logs include `Starting webhook forwarder for <repo>` and no immediate errors. Then label an issue with `agent:todo` and watch it kick off.
+
 ## Commands
 
 | Command | What it does |
@@ -39,24 +120,112 @@ april logs -f
 | `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). |
 
+## Environment variables
+
+The daemon reads extra env vars from `~/.config/april/env`. One `KEY=VALUE` per line, `#` for comments, optional double-quotes around values:
+
+```sh
+# ~/.config/april/env
+GH_HOST=your.ghes.host
+GH_ENTERPRISE_TOKEN=ghp_...
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+APRIL_DEBUG=1
+```
+
+This file is seeded by `april install` (and `april init`) and is **never overwritten by reinstalls** — safe to put long-lived secrets here.
+
+After editing:
+- **Linux:** `april restart`. The systemd unit re-reads the env file on each start.
+- **macOS:** `april install && april restart`. launchd has no `EnvironmentFile=` equivalent, so values are inlined into the plist at install time; you have to regenerate it after editing.
+
+### Token inheritance
+
+`spawner.ts` runs Claude inside tmux with `tmux new-session -d <claudeCommand>` — no login shell. So Claude inherits the daemon's env directly, including any `GH_TOKEN` / `GH_ENTERPRISE_TOKEN` you set in the env file. Practical implication: the PAT you provide has to cover what *both* april and Claude need, not just april. If you want Claude to fall back to your shell's auth (a credential helper, network-level auth, etc.), you'd need to wrap the tmux command in a login shell — not currently supported.
+
 ## 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
+### 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.
+
+## GitHub Enterprise Server caveat
 
-User services stop when you log out unless linger is enabled. On a server you SSH into:
+`gh webhook forward` relies on GitHub's hosted webhook-relay infrastructure. **That relay is github.com-only — it is not part of GHES.** If your repos live on a GHES instance, you will see this in the logs after the daemon authenticates fine:
+
+```
+Error: you do not have access to this feature
+```
+
+The webhook extension itself works against GHES (it can authenticate, list extensions, etc.), but the actual `forward` subcommand has no relay to talk to.
+
+Workarounds (none currently shipped — file an issue if you need them wired up):
+
+1. **Direct webhook delivery.** Expose april's port publicly (reverse proxy + TLS, or a tunnel like cloudflared / tailscale funnel / ngrok), and configure a webhook on the GHES repo pointing at `https://your-server/webhook/github`. Skip `gh webhook forward` entirely.
+2. **Polling.** Replace the forwarder with a periodic poll of open issues. april already has reconciliation-on-startup; turning it into a timer is small.
+3. **Third-party relay** like smee.io.
+
+## Upgrading
 
 ```bash
-sudo loginctl enable-linger $USER
+april upgrade
 ```
 
-`april install` reminds you if it sees linger is off.
+This runs the package install, regenerates the unit/plist, and restarts the service in one go. Pass a specific version (`april upgrade 0.0.5`) to pin, or `--with pnpm|yarn` if `april upgrade` picks the wrong package manager.
 
-### Node version managers
+Manual equivalent if you want to do it yourself:
 
-`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.
+```bash
+npm i -g @armstrongnate/april@latest
+april install        # regenerates the unit/plist with any template changes (also runs daemon-reload on Linux)
+april restart
+```
+
+**If you skip `april install` after upgrading, new template features (`EnvironmentFile=`, env-var changes, etc.) will not appear in your existing unit file** — `npm` only updates the package, not anything systemd has on disk.
+
+## Troubleshooting
+
+### `Required gh extension not installed: cli/gh-webhook`
+
+Install it as the same user that runs the service:
+
+```bash
+gh extension install cli/gh-webhook
+```
+
+### `gh auth token not found for host "..."`
+
+`gh-webhook` shells out to `gh auth token` to extract a Bearer token, and your gh setup doesn't have an extractable one (you might be relying on a credential helper, network-level auth like Cloudflare Access, or a wrapper script). Add an explicit `GH_TOKEN` / `GH_ENTERPRISE_TOKEN` to `~/.config/april/env`, then `april restart`.
+
+### `you do not have access to this feature` on `gh webhook forward`
+
+Your host (likely GHES) doesn't expose the webhook-forwarding relay. See [GitHub Enterprise Server caveat](#github-enterprise-server-caveat).
+
+### Service starts but env vars in `~/.config/april/env` aren't applied
+
+You're running a unit that was generated before `EnvironmentFile=` support landed (anything from before v0.0.2). Confirm:
+
+```bash
+systemctl --user cat april | grep -i environment
+```
+
+If you don't see `EnvironmentFile=`, regenerate:
+
+```bash
+april install
+systemctl --user daemon-reload
+april restart
+```
+
+### `Token:` is empty in `gh auth status` but `gh` commands work
+
+Means your auth is provided by something other than a stored token (credential helper, network auth, wrapper). The webhook extension still needs an actual token — it doesn't matter how `gh` does its other API calls. Add `GH_TOKEN` / `GH_ENTERPRISE_TOKEN` to the env file.
+
+### Service can't find `gh` / `tmux` / `claude` even though they're on your shell PATH
+
+`april install` captures `$PATH` at install time and bakes it into the unit. If you installed any of those tools after running `april install`, re-run `april install` to recapture PATH.
 
 ## Usage
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { backend } from "./service/index.js";
 import { run as runInit } from "./commands/init.js";
+import { run as runUpgrade } from "./commands/upgrade.js";
 const HELP = `april — issue worker
 
 Usage:
@@ -9,6 +10,8 @@ Usage:
 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.
+  upgrade [VER]     Upgrade the npm package, regenerate the unit, and restart. VER defaults to "latest".
+                    Pass --with npm|pnpm|yarn to override the auto-detected package manager.
   uninstall         Stop and remove the user service
   start             Start the service
   stop              Stop the service
@@ -70,6 +73,9 @@ async function main() {
     if (cmd === "init") {
         return runInit(rest);
     }
+    if (cmd === "upgrade") {
+        return runUpgrade(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.

package/dist/commands/init.js

@@ -2,6 +2,8 @@ import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
 import { copyFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
+import { ensureEnvFile, envFilePath } from "../service/envfile.js";
+import { isGhWebhookExtensionInstalled, GH_EXTENSION_INSTALL_CMD } from "../precheck.js";
 // 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() {
@@ -37,6 +39,18 @@ export function run(args) {
         return 1;
     }
     copyIfMissing(skillSrc, skillDst, "skill", force);
+    const envState = ensureEnvFile();
+    console.log(`  env:    ${envState === "created" ? "wrote" : "already exists"} ${envFilePath()}`);
+    console.log("");
+    console.log("Checks:");
+    if (isGhWebhookExtensionInstalled()) {
+        console.log("  ✓ gh extension cli/gh-webhook installed");
+    }
+    else {
+        console.log("  ✗ gh extension cli/gh-webhook NOT installed");
+        console.log(`    Install with:  ${GH_EXTENSION_INSTALL_CMD}`);
+        console.log("    (april will refuse to start without it.)");
+    }
     console.log("");
     if (configResult === "wrote") {
         console.log(`Next: edit ${configDst}, then run \`april install\`.`);

package/dist/commands/upgrade.js

@@ -0,0 +1,55 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const PACKAGE = "@armstrongnate/april";
+function detectPackageManager() {
+    // Where this script lives reveals which global install dir it's in.
+    const here = fileURLToPath(import.meta.url);
+    if (/[\\/]\.?pnpm[\\/]|[\\/]Library[\\/]pnpm[\\/]/.test(here))
+        return "pnpm";
+    if (/[\\/]\.config[\\/]yarn[\\/]|[\\/]\.yarn[\\/]/.test(here))
+        return "yarn";
+    return "npm";
+}
+function pmInstallArgs(pm, ref) {
+    switch (pm) {
+        case "pnpm":
+            return ["add", "-g", ref];
+        case "yarn":
+            return ["global", "add", ref];
+        case "npm":
+            return ["install", "-g", ref];
+    }
+}
+function step(name, cmd, args) {
+    console.log(`\n→ ${name}`);
+    console.log(`  $ ${cmd} ${args.join(" ")}`);
+    const res = spawnSync(cmd, args, { stdio: "inherit" });
+    if ((res.status ?? 1) !== 0) {
+        throw new Error(`${name} failed (exit ${res.status})`);
+    }
+}
+export function run(args) {
+    let pm = detectPackageManager();
+    // --with <pm> override
+    const withIdx = args.indexOf("--with");
+    if (withIdx >= 0) {
+        const v = args[withIdx + 1];
+        if (v !== "npm" && v !== "pnpm" && v !== "yarn") {
+            console.error(`--with must be one of: npm, pnpm, yarn`);
+            return 2;
+        }
+        pm = v;
+    }
+    let ref = `${PACKAGE}@latest`;
+    // Allow `april upgrade <version>` to pin
+    const positional = args.filter((a, i) => !a.startsWith("--") && args[i - 1] !== "--with");
+    if (positional[0])
+        ref = `${PACKAGE}@${positional[0]}`;
+    console.log(`april upgrade — using ${pm}, target ${ref}`);
+    step(`Installing ${ref}`, pm, pmInstallArgs(pm, ref));
+    // From here on, `april` resolves to the freshly installed binary on PATH.
+    step("Regenerating service unit (april install)", "april", ["install"]);
+    step("Restarting service (april restart)", "april", ["restart"]);
+    console.log("\n✓ Upgrade complete. Tail logs with: april logs -f");
+    return 0;
+}

package/dist/config.js

@@ -4,6 +4,7 @@ import { resolve, join } from "node:path";
 import { homedir } from "node:os";
 import { parse as parseYaml } from "yaml";
 import { createLogger } from "./logger.js";
+import { isGhWebhookExtensionInstalled, GH_EXTENSION_INSTALL_CMD } from "./precheck.js";
 const log = createLogger("config");
 function findConfigPath() {
     const envPath = process.env.APRIL_CONFIG;
@@ -37,6 +38,10 @@ function validateTools() {
             throw new Error(`Required tool "${tool}" not found on PATH. Install it before running april.`);
         }
     }
+    if (!isGhWebhookExtensionInstalled()) {
+        throw new Error(`Required gh extension not installed: cli/gh-webhook.\n` +
+            `Install it with:\n  ${GH_EXTENSION_INSTALL_CMD}`);
+    }
 }
 function validateString(obj, key, context) {
     const val = obj[key];

package/dist/precheck.js

@@ -0,0 +1,18 @@
+import { execFileSync } from "node:child_process";
+export const REQUIRED_GH_EXTENSION = "cli/gh-webhook";
+export const GH_EXTENSION_INSTALL_CMD = `gh extension install ${REQUIRED_GH_EXTENSION}`;
+export function isGhWebhookExtensionInstalled() {
+    try {
+        const out = execFileSync("gh", ["extension", "list"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10_000,
+        });
+        // `gh extension list` output includes the extension repo (e.g. cli/gh-webhook)
+        // somewhere in each row; substring match is sufficient.
+        return out.includes(REQUIRED_GH_EXTENSION);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/service/envfile.js

@@ -0,0 +1,48 @@
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+export function envFilePath() {
+    return join(homedir(), ".config", "april", "env");
+}
+const DEFAULT_HEADER = `# april daemon environment variables
+# One KEY=VALUE per line. Lines starting with # are ignored.
+# Values may be wrapped in double quotes if they contain spaces or special chars.
+# After editing, run: april restart
+`;
+/** Create the env file with a friendly header if it doesn't exist. Never overwrites. */
+export function ensureEnvFile() {
+    const path = envFilePath();
+    if (existsSync(path))
+        return "exists";
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, DEFAULT_HEADER, "utf-8");
+    return "created";
+}
+/**
+ * Parse the env file and return key/value pairs. Used by launchd, which has
+ * no native EnvironmentFile= equivalent — values must be inlined into the plist.
+ *
+ * Format: KEY=VALUE per line. # for comments. Optional double-quotes around the value.
+ */
+export function parseEnvFile() {
+    const path = envFilePath();
+    if (!existsSync(path))
+        return {};
+    const result = {};
+    const raw = readFileSync(path, "utf-8");
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq < 1)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        let value = trimmed.slice(eq + 1).trim();
+        if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}

package/dist/service/launchd.js

@@ -3,6 +3,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { dirname } from "node:path";
 import { homedir, userInfo } from "node:os";
 import { daemonEntryPath, nodeBinaryPath, launchdPlistPath, launchdLogPath, launchdLogDir, LAUNCHD_LABEL, } from "./paths.js";
+import { parseEnvFile, ensureEnvFile } from "./envfile.js";
 function escapeXml(s) {
     return s
         .replace(/&/g, "&")
@@ -15,6 +16,16 @@ export function plistContents() {
     const entry = daemonEntryPath();
     const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
     const log = launchdLogPath();
+    // Built-ins always set; user file overrides on conflict.
+    const env = {
+        PATH: path,
+        NODE_ENV: "production",
+        HOME: homedir(),
+        ...parseEnvFile(),
+    };
+    const envEntries = Object.entries(env)
+        .map(([k, v]) => `        <key>${escapeXml(k)}</key>\n        <string>${escapeXml(v)}</string>`)
+        .join("\n");
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -39,12 +50,7 @@ export function plistContents() {
     <string>${escapeXml(homedir())}</string>
     <key>EnvironmentVariables</key>
     <dict>
-        <key>PATH</key>
-        <string>${escapeXml(path)}</string>
-        <key>NODE_ENV</key>
-        <string>production</string>
-        <key>HOME</key>
-        <string>${escapeXml(homedir())}</string>
+${envEntries}
     </dict>
     <key>StandardOutPath</key>
     <string>${escapeXml(log)}</string>
@@ -75,6 +81,8 @@ function serviceTarget() {
 }
 export function install() {
     ensureLaunchctl();
+    // Seed env file so it's discoverable; values are parsed and inlined into the plist below.
+    ensureEnvFile();
     mkdirSync(launchdLogDir(), { recursive: true });
     const path = launchdPlistPath();
     mkdirSync(dirname(path), { recursive: true });

package/dist/service/systemd.js

@@ -3,6 +3,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { dirname } from "node:path";
 import { homedir } from "node:os";
 import { daemonEntryPath, nodeBinaryPath, systemdUnitPath, SERVICE_NAME, } from "./paths.js";
+import { envFilePath, ensureEnvFile } from "./envfile.js";
 function runSystemctl(args) {
     const res = spawnSync("systemctl", ["--user", ...args], { encoding: "utf-8" });
     return {
@@ -28,6 +29,7 @@ RestartSec=5s
 WorkingDirectory=${homedir()}
 Environment=PATH=${path}
 Environment=NODE_ENV=production
+EnvironmentFile=-${envFilePath()}
 StandardOutput=journal
 StandardError=journal
 
@@ -57,6 +59,8 @@ function lingerEnabled() {
 }
 export function install() {
     ensureSystemctlPresent();
+    // Seed env file so EnvironmentFile=- has something to find on first install.
+    ensureEnvFile();
     const path = systemdUnitPath();
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, unitContents(), "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armstrongnate/april",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "She does all the work so you don't have to. Watches GitHub issues and spawns Claude Code sessions to work them.",
   "type": "module",
   "bin": {