@ravshansbox/pi-github 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# pi-github
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Watches open issues in a GitHub repo and answers new issues and comments with [pi](https://github.com/earendil-works/pi) agents.
+
+## How it works
+
+- Polls the repo of the current directory for new issues and comments every 30 seconds. Pull requests are ignored.
+- Only handles issues and comments created after the first start. After a restart it picks up where it stopped, including runs a crash cut off. A crash right after posting a reply can lead to that reply being posted twice.
+- Each issue gets its own git worktree in `.worktrees/issue-<number>` on branch `issue-<number>`, and its own pi session that continues across comments.
+- Issues are handled in parallel, up to 3 at once. Comments on the same issue are handled one after another.
+- The agent's final message is posted as a comment that starts with `agent:`. Comments that start with `agent:` are ignored, so it does not answer itself.
+- If the agent made commits, the branch is pushed and a pull request is opened once. Later commits update the same pull request.
+- State and sessions are kept in `.git/pi-github`.
+
+## Requirements
+
+- Node.js 24 or later
+- [GitHub CLI](https://cli.github.com) logged in (`gh auth login`), or a `GH_TOKEN` environment variable
+- pi set up with a model and credentials (`~/.pi/agent`)
+
+## Use
+
+```sh
+cd path/to/your/repo
+npx -y @ravshansbox/pi-github [--interval <seconds>] [--concurrency <number>]
+```
+
+Press Ctrl+C to stop after running agents finish, or press it twice to quit at once.
+
+## Security
+
+Anyone who can comment on the repo can instruct an agent that has full tools on your machine and your GitHub token. The worktree only separates git changes; it is not a sandbox. Run it in a container or as a separate user with a token limited to the repo if the repo is public.

package/dist/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { git } from "./git.js";
+import { createGitHub } from "./github.js";
+import { createPiAgent } from "./pi-agent.js";
+import { parseRepo, watch } from "./watch.js";
+const { values } = parseArgs({
+    options: {
+        interval: { type: "string", default: "30" },
+        concurrency: { type: "string", default: "3" },
+        help: { type: "boolean", short: "h", default: false },
+    },
+});
+if (values.help) {
+    console.log(`Usage: pi-github [--interval <seconds>] [--concurrency <number>]
+
+Watches open issues in the GitHub repo of the current directory and answers new issues and comments with pi agents.
+
+Options:
+  --interval <seconds>     Time between polls (default: 30)
+  --concurrency <number>   Most issues handled at once (default: 3)`);
+    process.exit(0);
+}
+const repoRoot = await git(process.cwd(), "rev-parse", "--show-toplevel");
+const repo = parseRepo(await git(repoRoot, "remote", "get-url", "origin"));
+const token = process.env.GH_TOKEN ?? execFileSync("gh", ["auth", "token"], { encoding: "utf8" }).trim();
+const dataDir = join(await git(repoRoot, "rev-parse", "--path-format=absolute", "--git-common-dir"), "pi-github");
+const github = createGitHub({ baseUrl: "https://api.github.com", token, repo });
+const agent = createPiAgent({ github, repo, sessionsDir: join(dataDir, "sessions") });
+const controller = new AbortController();
+process.on("SIGINT", () => {
+    if (controller.signal.aborted)
+        process.exit(130);
+    console.log("Stopping after running agents finish. Press Ctrl+C again to quit now.");
+    controller.abort();
+});
+const log = (message) => console.log(`${new Date().toISOString()} ${message}`);
+log(`Watching ${repo}`);
+await watch({
+    github,
+    agent,
+    repoRoot,
+    stateFile: join(dataDir, "state.json"),
+    intervalMs: Number(values.interval) * 1000,
+    concurrency: Number(values.concurrency),
+    signal: controller.signal,
+    log,
+});

package/dist/dispatcher.js

@@ -0,0 +1,50 @@
+export function createDispatcher({ concurrency, handle, onError = () => { }, }) {
+    const queues = new Map();
+    const waiting = [];
+    const active = new Set();
+    let idleWaiters = [];
+    function pump() {
+        while (active.size < concurrency && waiting.length > 0) {
+            const issueNumber = waiting.shift();
+            active.add(issueNumber);
+            void drain(issueNumber);
+        }
+        if (active.size === 0 && waiting.length === 0) {
+            for (const resolve of idleWaiters)
+                resolve();
+            idleWaiters = [];
+        }
+    }
+    async function drain(issueNumber) {
+        const queue = queues.get(issueNumber);
+        while (queue.length > 0) {
+            const trigger = queue.shift();
+            try {
+                await handle(trigger);
+            }
+            catch (error) {
+                onError(trigger, error);
+            }
+        }
+        queues.delete(issueNumber);
+        active.delete(issueNumber);
+        pump();
+    }
+    return {
+        dispatch(trigger) {
+            const queue = queues.get(trigger.issueNumber);
+            if (queue) {
+                queue.push(trigger);
+                return;
+            }
+            queues.set(trigger.issueNumber, [trigger]);
+            waiting.push(trigger.issueNumber);
+            pump();
+        },
+        idle() {
+            if (active.size === 0 && waiting.length === 0)
+                return Promise.resolve();
+            return new Promise((resolve) => idleWaiters.push(resolve));
+        },
+    };
+}

package/dist/git.js

@@ -0,0 +1,45 @@
+import { execFile } from "node:child_process";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export async function git(cwd, ...args) {
+    const { stdout } = await execFileAsync("git", args, { cwd });
+    return stdout.trim();
+}
+export const branchFor = (issueNumber) => `issue-${issueNumber}`;
+async function excludeWorktrees(repoRoot) {
+    const exclude = join(await git(repoRoot, "rev-parse", "--path-format=absolute", "--git-common-dir"), "info", "exclude");
+    const current = existsSync(exclude) ? await readFile(exclude, "utf8") : "";
+    if (current.split("\n").includes("/.worktrees/"))
+        return;
+    await mkdir(join(exclude, ".."), { recursive: true });
+    await appendFile(exclude, `${current === "" || current.endsWith("\n") ? "" : "\n"}/.worktrees/\n`);
+}
+export async function ensureWorktree(repoRoot, issueNumber, base) {
+    const path = join(repoRoot, ".worktrees", `issue-${issueNumber}`);
+    if (existsSync(path))
+        return path;
+    await excludeWorktrees(repoRoot);
+    const branch = branchFor(issueNumber);
+    await git(repoRoot, "fetch", "-q", "origin", base);
+    const branchExists = (await git(repoRoot, "branch", "--list", branch)) !== "";
+    if (branchExists)
+        await git(repoRoot, "worktree", "add", "-q", path, branch);
+    else
+        await git(repoRoot, "worktree", "add", "-q", "-b", branch, path, `origin/${base}`);
+    return path;
+}
+export async function hasUnpushedCommits(worktree, base) {
+    const branch = await git(worktree, "branch", "--show-current");
+    const remoteBranch = (await git(worktree, "ls-remote", "--heads", "origin", branch)) !== "";
+    const compareWith = remoteBranch ? `origin/${branch}` : `origin/${base}`;
+    if (remoteBranch)
+        await git(worktree, "fetch", "-q", "origin", branch);
+    return Number(await git(worktree, "rev-list", "--count", `${compareWith}..HEAD`)) > 0;
+}
+export async function pushBranch(worktree) {
+    const branch = await git(worktree, "branch", "--show-current");
+    await git(worktree, "push", "-q", "-u", "origin", branch);
+}

package/dist/github.js

@@ -0,0 +1,61 @@
+export function createGitHub({ baseUrl, token, repo }) {
+    const cache = new Map();
+    async function request(method, url, body, headers = {}) {
+        const response = await fetch(url.startsWith("http") ? url : `${baseUrl}${url}`, {
+            method,
+            headers: {
+                accept: "application/vnd.github+json",
+                authorization: `Bearer ${token}`,
+                "x-github-api-version": "2022-11-28",
+                ...(body === undefined ? {} : { "content-type": "application/json" }),
+                ...headers,
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!response.ok && response.status !== 304) {
+            throw new Error(`GitHub ${method} ${url} failed: ${response.status} ${await response.text()}`);
+        }
+        return response;
+    }
+    async function list(path) {
+        const items = [];
+        let url = path;
+        while (url) {
+            const cached = cache.get(url);
+            const response = await request("GET", url, undefined, cached ? { "if-none-match": cached.etag } : {});
+            if (response.status === 304 && cached) {
+                items.push(...cached.data);
+                url = cached.next;
+                continue;
+            }
+            const data = (await response.json());
+            const next = response.headers.get("link")?.match(/<([^>]+)>;\s*rel="next"/)?.[1];
+            const etag = response.headers.get("etag");
+            if (etag)
+                cache.set(url, { etag, data, next });
+            items.push(...data);
+            url = next;
+        }
+        return items;
+    }
+    return {
+        listIssues: (since) => list(`/repos/${repo}/issues?state=open&sort=updated&direction=asc&per_page=100&since=${encodeURIComponent(since)}`),
+        listIssueComments: (since) => list(`/repos/${repo}/issues/comments?sort=updated&direction=asc&per_page=100&since=${encodeURIComponent(since)}`),
+        postComment: async (issueNumber, body) => {
+            await request("POST", `/repos/${repo}/issues/${issueNumber}/comments`, { body });
+        },
+        getDefaultBranch: async () => {
+            const data = (await (await request("GET", `/repos/${repo}`)).json());
+            return data.default_branch;
+        },
+        getIssue: async (issueNumber) => (await (await request("GET", `/repos/${repo}/issues/${issueNumber}`)).json()),
+        hasOpenPullRequest: async (branch) => {
+            const owner = repo.split("/")[0];
+            const response = await request("GET", `/repos/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${branch}`)}`);
+            return (await response.json()).length > 0;
+        },
+        createPullRequest: async (pull) => {
+            await request("POST", `/repos/${repo}/pulls`, pull);
+        },
+    };
+}

package/dist/handler.js

@@ -0,0 +1,21 @@
+import { branchFor, ensureWorktree, hasUnpushedCommits, pushBranch } from "./git.js";
+import { agentPrefix } from "./poller.js";
+export async function handleTrigger(trigger, { github, agent, repoRoot }) {
+    const base = await github.getDefaultBranch();
+    const worktree = await ensureWorktree(repoRoot, trigger.issueNumber, base);
+    const answer = await agent.run(trigger, { cwd: worktree });
+    if (await hasUnpushedCommits(worktree, base)) {
+        await pushBranch(worktree);
+        const branch = branchFor(trigger.issueNumber);
+        if (!(await github.hasOpenPullRequest(branch))) {
+            const issue = await github.getIssue(trigger.issueNumber);
+            await github.createPullRequest({
+                head: branch,
+                base,
+                title: issue.title,
+                body: `${agentPrefix} Closes #${trigger.issueNumber}`,
+            });
+        }
+    }
+    await github.postComment(trigger.issueNumber, `${agentPrefix} ${answer}`);
+}

package/dist/pi-agent.js

@@ -0,0 +1,20 @@
+import { join } from "node:path";
+import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import { buildPrompt } from "./prompt.js";
+export function createPiAgent({ github, repo, sessionsDir }) {
+    return {
+        async run(trigger, { cwd }) {
+            const sessionManager = SessionManager.continueRecent(cwd, join(sessionsDir, `issue-${trigger.issueNumber}`));
+            const { session } = await createAgentSession({ cwd, sessionManager });
+            try {
+                const issue = await github.getIssue(trigger.issueNumber);
+                const firstInSession = session.messages.length === 0;
+                await session.prompt(buildPrompt({ repo, issue, trigger, firstInSession }));
+                return session.getLastAssistantText() ?? "";
+            }
+            finally {
+                session.dispose();
+            }
+        },
+    };
+}

package/dist/poller.js

@@ -0,0 +1,49 @@
+export const agentPrefix = "agent:";
+export function initialPollState(now) {
+    const startedAt = now.toISOString();
+    return { startedAt, issuesSince: startedAt, commentsSince: startedAt, seen: [] };
+}
+const newest = (since, items) => items.reduce((latest, item) => (item.updated_at > latest ? item.updated_at : latest), since);
+export async function poll(github, state) {
+    const [issues, comments] = await Promise.all([
+        github.listIssues(state.issuesSince),
+        github.listIssueComments(state.commentsSince),
+    ]);
+    const candidates = [
+        ...issues
+            .filter((issue) => !issue.pull_request)
+            .map((issue) => ({
+            key: `issue:${issue.number}`,
+            kind: "issue",
+            issueNumber: issue.number,
+            author: issue.user.login,
+            body: issue.body ?? "",
+            createdAt: issue.created_at,
+        })),
+        ...comments
+            .filter((comment) => !comment.html_url.includes("/pull/"))
+            .map((comment) => ({
+            key: `comment:${comment.id}`,
+            kind: "comment",
+            issueNumber: Number(comment.issue_url.split("/").pop()),
+            author: comment.user.login,
+            body: comment.body,
+            createdAt: comment.created_at,
+        })),
+    ];
+    const seen = new Set(state.seen);
+    const triggers = candidates
+        .filter((trigger) => trigger.createdAt >= state.startedAt)
+        .filter((trigger) => !trigger.body.trimStart().startsWith(agentPrefix))
+        .filter((trigger) => !seen.has(trigger.key))
+        .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    return {
+        triggers,
+        state: {
+            ...state,
+            issuesSince: newest(state.issuesSince, issues),
+            commentsSince: newest(state.commentsSince, comments),
+            seen: [...state.seen, ...triggers.map((trigger) => trigger.key)],
+        },
+    };
+}

package/dist/prompt.js

@@ -0,0 +1,14 @@
+import { branchFor } from "./git.js";
+export function buildPrompt({ repo, issue, trigger, firstInSession, }) {
+    const message = `${trigger.kind === "issue" ? "New issue" : "New comment"} from @${trigger.author}:\n\n${trigger.body}`;
+    if (!firstInSession)
+        return message;
+    return [
+        `You are handling GitHub issue #${issue.number} in ${repo}: ${issue.title}`,
+        `Your working directory is a git worktree on branch ${branchFor(issue.number)}.`,
+        "If the request needs code changes, make them and commit them. Do not push and do not open pull requests; that happens automatically after you finish.",
+        "Your final message is posted as a comment on the issue, so write it for the person who asked.",
+        ...(trigger.kind === "comment" ? [`Issue description:\n\n${issue.body ?? ""}`] : []),
+        message,
+    ].join("\n\n");
+}

package/dist/watch.js

@@ -0,0 +1,68 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { createDispatcher } from "./dispatcher.js";
+import { handleTrigger } from "./handler.js";
+import { initialPollState, poll } from "./poller.js";
+export function parseRepo(remoteUrl) {
+    const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+    if (!match)
+        throw new Error(`${remoteUrl} is not a GitHub remote`);
+    return `${match[1]}/${match[2]}`;
+}
+async function loadState(stateFile) {
+    try {
+        return JSON.parse(await readFile(stateFile, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return initialPollState(new Date());
+        throw error;
+    }
+}
+async function saveState(stateFile, state) {
+    await mkdir(dirname(stateFile), { recursive: true });
+    const temporaryFile = `${stateFile}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    await writeFile(temporaryFile, `${JSON.stringify(state, null, 2)}\n`);
+    await rename(temporaryFile, stateFile);
+}
+export async function watch({ github, agent, repoRoot, stateFile, intervalMs, concurrency, signal, log, }) {
+    let { pending = [], ...pollState } = await loadState(stateFile);
+    let saving = Promise.resolve();
+    const save = () => (saving = saving.then(() => saveState(stateFile, { ...pollState, pending })));
+    const dispatcher = createDispatcher({
+        concurrency,
+        handle: async (trigger) => {
+            try {
+                await handleTrigger(trigger, { github, agent, repoRoot });
+                log(`#${trigger.issueNumber}: answered @${trigger.author}`);
+            }
+            finally {
+                pending = pending.filter((candidate) => candidate.key !== trigger.key);
+                await save();
+            }
+        },
+        onError: (trigger, error) => log(`#${trigger.issueNumber}: failed: ${error instanceof Error ? error.message : error}`),
+    });
+    for (const trigger of pending) {
+        log(`#${trigger.issueNumber}: resuming ${trigger.kind} from @${trigger.author}`);
+        dispatcher.dispatch(trigger);
+    }
+    while (!signal.aborted) {
+        try {
+            const result = await poll(github, pollState);
+            pollState = result.state;
+            pending = [...pending, ...result.triggers];
+            await save();
+            for (const trigger of result.triggers) {
+                log(`#${trigger.issueNumber}: new ${trigger.kind} from @${trigger.author}`);
+                dispatcher.dispatch(trigger);
+            }
+        }
+        catch (error) {
+            log(`poll failed: ${error instanceof Error ? error.message : error}`);
+        }
+        await sleep(intervalMs, undefined, { signal }).catch(() => { });
+    }
+    await dispatcher.idle();
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@ravshansbox/pi-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Watch GitHub issues and answer them with pi agents",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "pi-github": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test 'test/**/*.test.ts'",
+    "prepare": "tsc"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "semantic-release": "^25.0.9",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ravshansbox/pi-github.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}