kanbot 0.2.0 → 0.3.0

package/README.md

@@ -26,10 +26,12 @@ Full docs: [docs/](./docs/00-index.md). Demo video: [docs/assets/demo.mp4](./doc
 | **Ready**       | Moving a card here approves the plan. Cards are picked top-down.                                                                                 |
 | **In Progress** | An agent implements it in its own worktree and opens a PR.                                                                                       |
 | **Review**      | Two agent reviews, with fixes. Then you're notified. Comment on the PR and an agent addresses it. CI failures and merge conflicts are fixed too. |
-| **Done**        | You merge.                                                                                                                                       |
+| **Done**        | You merge, or approve and kanbot merges ([`merge.onApproval`](./docs/12-identity.md#merge-on-approval)).                                         |
 
 A Bun daemon polls the board and runs one `claude -p` / `codex exec` process per job. GitHub is the only state, so you can restart it any time. Agents never get a GitHub token; the daemon makes every comment, push and PR. Only collaborators with write access can steer agents.
 
+kanbot talks as you by default. Run `kanbot app create` to have it talk as its own bot instead, so you can tell its messages apart and approve its PRs. Commits stay yours. With `merge.onApproval`, approving a PR merges it. [More](./docs/12-identity.md)
+
 ## Setup
 
 Requires [Bun](https://bun.sh) ≥ 1.3, `gh` logged in, and `claude` or `codex` logged in.
@@ -46,6 +48,8 @@ kanbot run
 
 Use `kanbot run --once --dry-run` to see what it would do. Run one daemon per repo.
 
+For a guided setup, run `bunx kanbot skills install` and ask your agent "help me set up kanbot".
+
 ## Labels
 
 | Label                                 | Meaning                                           |
@@ -110,4 +114,6 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org). A `c
 2. A draft release updates with the next version and notes. `feat` bumps minor, `fix` patch. On 0.x, breaking changes bump minor.
 3. Publish the draft on GitHub. This tags the commit, publishes to npm with provenance, and commits the version to `package.json` on `main`.
 
+Docs: [kanbot.mib.im](https://kanbot.mib.im) shows the latest release, [kanbot.mib.im/main](https://kanbot.mib.im/main/) shows `main`. Both deploy on every push to `main` and on each release. `pnpm docs:dev` serves your working tree.
+
 Preview the next release with `pnpm release:preview`. Mark the draft as a pre-release to publish under the `next` tag.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kanbot",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Run an autonomous dev team (Claude Code or Codex) from a GitHub Project board",
 	"type": "module",
 	"license": "MIT",

package/schema/config.schema.json

@@ -165,6 +165,60 @@
 				}
 			}
 		},
+		"identity": {
+			"default": {},
+			"type": "object",
+			"properties": {
+				"mode": {
+					"default": "user",
+					"description": "Who kanbot talks as. `user`: your account. `app`: a kanbot GitHub App, so its comments and PRs show as a bot. Commits are always yours.",
+					"type": "string",
+					"enum": ["user", "app"]
+				},
+				"app": {
+					"default": null,
+					"description": "Set by `kanbot app create`. The private key lives in ~/.kanbot/apps/<id>.pem.",
+					"anyOf": [
+						{
+							"type": "object",
+							"properties": {
+								"id": {
+									"type": "integer",
+									"minimum": -9007199254740991,
+									"maximum": 9007199254740991,
+									"description": "GitHub App ID."
+								},
+								"slug": {
+									"type": "string",
+									"description": "App slug, as in github.com/apps/<slug>."
+								}
+							},
+							"required": ["id", "slug"]
+						},
+						{
+							"type": "null"
+						}
+					]
+				}
+			}
+		},
+		"merge": {
+			"default": {},
+			"type": "object",
+			"properties": {
+				"onApproval": {
+					"default": false,
+					"description": "Merge a kanbot PR when a collaborator approves it, checks pass and agent review is done. Merges as you. Needs identity.mode app to approve your own kanbot PRs.",
+					"type": "boolean"
+				},
+				"method": {
+					"default": "squash",
+					"description": "Merge method used for approved PRs.",
+					"type": "string",
+					"enum": ["squash", "merge", "rebase"]
+				}
+			}
+		},
 		"codex": {
 			"default": {},
 			"type": "object",

package/src/commands/app.ts

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { chmod, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { defineCommand } from "citty";
+import { loadConfig, saveConfig } from "../config.ts";
+import { UserError } from "../errors.ts";
+import { appKeyPath, appManifest, convertManifest } from "../github/app.ts";
+import { Gh } from "../github/gh.ts";
+import { log } from "../log.ts";
+
+const WAIT_MS = 10 * 60_000;
+
+function openBrowser(url: string) {
+	const cmd =
+		process.platform === "darwin"
+			? "open"
+			: process.platform === "win32"
+				? "explorer"
+				: "xdg-open";
+	try {
+		Bun.spawn([cmd, url], { stdout: "ignore", stderr: "ignore" });
+	} catch {}
+}
+
+const escAttr = (s: string) => s.replace(/&/g, "&").replace(/"/g, """);
+
+/** A page that posts the manifest to GitHub, as the manifest flow requires. */
+function formPage(action: string, manifest: unknown) {
+	return `<!doctype html><meta charset="utf-8"><title>kanbot app</title>
+<form id="f" method="post" action="${escAttr(action)}">
+<input type="hidden" name="manifest" value="${escAttr(JSON.stringify(manifest))}">
+<button>Create the kanbot app on GitHub</button></form>
+<script>document.getElementById("f").submit()</script>`;
+}
+
+const page = (msg: string) =>
+	new Response(
+		`<!doctype html><meta charset="utf-8"><title>kanbot app</title><p>${msg}</p>`,
+		{ headers: { "content-type": "text/html" } },
+	);
+
+const create = defineCommand({
+	meta: {
+		name: "create",
+		description:
+			"Create a GitHub App for kanbot to talk as, and switch to app mode",
+	},
+	args: {
+		name: {
+			type: "string",
+			description: "App name, unique on GitHub (default: kanbot-<owner>)",
+		},
+	},
+	async run({ args }) {
+		const root = process.cwd();
+		const config = await loadConfig(root);
+		const gh = new Gh(config.repo);
+		const owner = gh.owner;
+		const { type } = await gh.rest<{ type: string }>(`users/${owner}`);
+		const name = (args.name ?? `kanbot-${owner}`).slice(0, 34);
+		const state = randomUUID();
+		const action =
+			type === "Organization"
+				? `https://github.com/organizations/${owner}/settings/apps/new?state=${state}`
+				: `https://github.com/settings/apps/new?state=${state}`;
+
+		const got = Promise.withResolvers<string>();
+		const server = Bun.serve({
+			port: 0,
+			hostname: "localhost",
+			fetch(req): Response {
+				const url = new URL(req.url);
+				if (url.pathname === "/")
+					return new Response(
+						formPage(
+							action,
+							appManifest(name, `http://localhost:${url.port}/callback`),
+						),
+						{ headers: { "content-type": "text/html" } },
+					);
+				if (url.pathname !== "/callback")
+					return new Response("", { status: 404 });
+				const code = url.searchParams.get("code");
+				if (url.searchParams.get("state") !== state || !code)
+					return page("Unexpected request. Run `kanbot app create` again.");
+				got.resolve(code);
+				return page("App created. Go back to your terminal.");
+			},
+		});
+		const start = `http://localhost:${server.port}/`;
+		log.info(`Opening ${start} — confirm the app on GitHub.`);
+		openBrowser(start);
+		const timer = setTimeout(
+			() => got.reject(new Error("timed out waiting for GitHub")),
+			WAIT_MS,
+		);
+		let code: string;
+		try {
+			code = await got.promise;
+		} catch (e) {
+			throw new UserError("No app was created.", {
+				why: String(e),
+				fix: "kanbot app create",
+				docs: "identity#app-mode",
+			});
+		} finally {
+			clearTimeout(timer);
+			server.stop();
+		}
+
+		const app = await convertManifest(code);
+		const keyFile = appKeyPath(app.id);
+		await mkdir(dirname(keyFile), { recursive: true });
+		await Bun.write(keyFile, app.pem);
+		await chmod(keyFile, 0o600);
+		await saveConfig(root, {
+			identity: { mode: "app", app: { id: app.id, slug: app.slug } },
+		});
+		const install = `https://github.com/apps/${app.slug}/installations/new`;
+		log.info(`Created ${app.slug} (id ${app.id}). Key: ${keyFile}`);
+		log.info(`Now install it on ${config.repo}: ${install}`);
+		openBrowser(install);
+		console.log(
+			"\nThen commit .kanbot/config.yml, run `kanbot doctor` and restart the daemon.",
+		);
+	},
+});
+
+const link = defineCommand({
+	meta: {
+		name: "link",
+		description: "Use a kanbot app you already created, e.g. for another repo",
+	},
+	args: {
+		id: { type: "string", required: true, description: "GitHub App ID" },
+		slug: {
+			type: "string",
+			required: true,
+			description: "App slug, as in github.com/apps/<slug>",
+		},
+	},
+	async run({ args }) {
+		const root = process.cwd();
+		const id = Number(args.id);
+		if (!Number.isInteger(id))
+			throw new UserError("--id must be a number.", {
+				docs: "identity#use-the-app-in-another-repo",
+			});
+		await saveConfig(root, {
+			identity: { mode: "app", app: { id, slug: args.slug } },
+		});
+		const config = await loadConfig(root);
+		log.info(`kanbot talks as ${args.slug}[bot] in ${config.repo}.`);
+		if (!existsSync(appKeyPath(id)))
+			log.warn(`No private key at ${appKeyPath(id)}. Copy it there.`);
+		log.info(
+			`Install it on the repo if needed: https://github.com/apps/${args.slug}/installations/new`,
+		);
+	},
+});
+
+export default defineCommand({
+	meta: {
+		name: "app",
+		description: "Manage the GitHub App kanbot talks as",
+	},
+	subCommands: { create, link },
+});

package/src/commands/doctor.ts

@@ -7,6 +7,7 @@ import { loadConfig, writeConfigSchema } from "../config.ts";
 import { git } from "../daemon/git.ts";
 import { describeError } from "../errors.ts";
 import { copilotReviewRule } from "../github/api.ts";
+import { appKeyPath, appTokens } from "../github/app.ts";
 import { Gh, run } from "../github/gh.ts";
 import {
 	boardWorkflows,
@@ -236,6 +237,40 @@ export default defineCommand({
 			fix: "kanbot board create",
 		});
 
+		const { mode, app } = config.identity;
+		if (mode === "app") {
+			add({
+				name: "kanbot app set",
+				ok: app !== null,
+				detail: app ? `${app.slug} (id ${app.id})` : undefined,
+				fix: "kanbot app create",
+			});
+			if (app) {
+				const key = appKeyPath(app.id);
+				add({
+					name: "kanbot app private key",
+					ok: existsSync(key),
+					detail: key,
+					fix: "kanbot app create, or copy the key from the machine that created the app",
+				});
+				if (existsSync(key)) {
+					try {
+						await appTokens(app, config.repo)();
+						add({ name: `kanbot app installed on ${config.repo}`, ok: true });
+					} catch (e) {
+						add({
+							name: `kanbot app installed on ${config.repo}`,
+							ok: false,
+							...explain(
+								e,
+								`https://github.com/apps/${app.slug}/installations/new`,
+							),
+						});
+					}
+				}
+			}
+		}
+
 		if (config.review.copilot) {
 			const rule = await copilotReviewRule(gh, config.baseBranch).catch(
 				() => null,

package/src/commands/skills.ts

@@ -6,7 +6,7 @@ import { log } from "../log.ts";
 import { listTemplates } from "../templates.ts";
 
 /** Skills that work outside a kanbot repo, so they can be installed per user. */
-export const GLOBAL_SKILLS = ["kanbot-idea"];
+export const GLOBAL_SKILLS = ["kanbot-idea", "kanbot-guide"];
 
 /** User-level skill folders: Claude Code reads the first, Codex the second. */
 export const globalSkillDirs = (home = homedir()) => ({

package/src/config.ts

@@ -112,6 +112,40 @@ export const ConfigSchema = z.object({
 				),
 		})
 		.prefault({}),
+	identity: z
+		.object({
+			mode: z
+				.enum(["user", "app"])
+				.default("user")
+				.describe(
+					"Who kanbot talks as. `user`: your account. `app`: a kanbot GitHub App, so its comments and PRs show as a bot. Commits are always yours.",
+				),
+			app: z
+				.object({
+					id: z.number().int().describe("GitHub App ID."),
+					slug: z.string().describe("App slug, as in github.com/apps/<slug>."),
+				})
+				.nullable()
+				.default(null)
+				.describe(
+					"Set by `kanbot app create`. The private key lives in ~/.kanbot/apps/<id>.pem.",
+				),
+		})
+		.prefault({}),
+	merge: z
+		.object({
+			onApproval: z
+				.boolean()
+				.default(false)
+				.describe(
+					"Merge a kanbot PR when a collaborator approves it, checks pass and agent review is done. Merges as you. Needs identity.mode app to approve your own kanbot PRs.",
+				),
+			method: z
+				.enum(["squash", "merge", "rebase"])
+				.default("squash")
+				.describe("Merge method used for approved PRs."),
+		})
+		.prefault({}),
 	codex: z
 		.object({
 			networkAccess: z

package/src/daemon/derive.ts

@@ -73,6 +73,7 @@ export type Action =
 	| { kind: "move"; item: Item; to: ColumnKey; why: string }
 	| { kind: "label"; number: number; add: string[]; remove: string[] }
 	| { kind: "agentReviewed"; item: Item; pr: PR }
+	| { kind: "merge"; item: Item; pr: PR; by: string }
 	| { kind: "compare"; item: Item; prs: PR[] }
 	| { kind: "needsHuman"; number: number; why: string }
 	| { kind: "resetFailures"; prefix: string }
@@ -161,6 +162,22 @@ export function copilotThreads(pr: PR) {
 	});
 }
 
+/**
+ * Who approved the PR's current head, if anyone. A trusted reviewer's pending
+ * change request blocks it, and approvals of older commits don't count.
+ */
+export function approvedBy(
+	pr: PR,
+	trusted: ReadonlySet<string>,
+): string | null {
+	const verdicts = pr.verdicts.filter((v) => trusted.has(v.author));
+	if (verdicts.some((v) => v.state === "CHANGES_REQUESTED")) return null;
+	return (
+		verdicts.find((v) => v.state === "APPROVED" && v.commit === pr.headSha)
+			?.author ?? null
+	);
+}
+
 const fixCount = (pr: PR, kind: "ci" | "conflict") =>
 	pr.comments.reduce((n, c) => n + markerValues(c.body, kind).length, 0);
 
@@ -263,6 +280,8 @@ export function derive(snapshot: Snapshot, ctx: DeriveContext) {
 					const job = prJob(item, pr, trusted, ctx, blocked);
 					if (job === "agentReviewed")
 						actions.push({ kind: "agentReviewed", item, pr });
+					else if (typeof job === "object" && job && "mergeBy" in job)
+						actions.push({ kind: "merge", item, pr, by: job.mergeBy });
 					else if (job === "ciExhausted") {
 						actions.push({
 							kind: "needsHuman",
@@ -299,7 +318,13 @@ function prJob(
 	trusted: ReadonlySet<string>,
 	ctx: DeriveContext,
 	blocked: (issue: Issue, key: string) => boolean,
-): Job | "agentReviewed" | "ciExhausted" | "conflictExhausted" | null {
+):
+	| Job
+	| { mergeBy: string }
+	| "agentReviewed"
+	| "ciExhausted"
+	| "conflictExhausted"
+	| null {
 	const { issue } = item;
 	const prKey = `#${issue.number}:pr${pr.number}`;
 	// One job per PR at a time, whatever its kind.
@@ -393,6 +418,18 @@ function prJob(
 	}
 
 	if (!pr.labels.includes(LABELS.agentReviewed)) return "agentReviewed";
+
+	// 6. Approved by a human: merge. Only kanbot's own PRs, never kanbot-review ones.
+	if (
+		ctx.config.merge.onApproval &&
+		pr.headRefName.startsWith("kanbot/") &&
+		!issue.labels.includes(LABELS.needsHuman) &&
+		pr.mergeable === "MERGEABLE" &&
+		(pr.checks === "SUCCESS" || pr.checks === null)
+	) {
+		const by = approvedBy(pr, trusted);
+		if (by) return { mergeBy: by };
+	}
 	return null;
 }
 

package/src/daemon/loop.ts

@@ -2,6 +2,8 @@ import { loadAgents } from "../agents/load.ts";
 import { sync } from "../agents/sync.ts";
 import { type Config, loadConfig } from "../config.ts";
 import { UserError } from "../errors.ts";
+import { viewer } from "../github/api.ts";
+import { botClient } from "../github/app.ts";
 import { Gh } from "../github/gh.ts";
 import { loadBoard, missingColumns } from "../github/project.ts";
 import { Trust } from "../github/trust.ts";
@@ -54,10 +56,13 @@ export async function runDaemon(root: string, opts: RunOptions) {
 
 	const release = opts.dryRun ? () => {} : await acquireLock(root);
 	const state = await new State(root).load();
+	const bot = botClient(config, gh);
 	const deps: JobDeps = {
 		root,
 		config,
 		gh,
+		bot,
+		me: await viewer(gh),
 		board,
 		agents,
 		provider: providerFor(config),
@@ -82,7 +87,7 @@ export async function runDaemon(root: string, opts: RunOptions) {
 	process.on("SIGTERM", stop);
 
 	log.info(
-		`kanbot: ${config.repo} · ${board.url} · provider ${config.provider} · ${config.concurrency} workers${opts.dryRun ? " · DRY RUN" : ""}`,
+		`kanbot: ${config.repo} · ${board.url} · provider ${config.provider} · ${config.concurrency} workers · talks as ${config.identity.mode === "app" ? `${config.identity.app?.slug}[bot]` : deps.me}${opts.dryRun ? " · DRY RUN" : ""}`,
 	);
 
 	try {
@@ -200,6 +205,8 @@ function describeAction(a: Action) {
 			return `label #${a.number} +[${a.add}] -[${a.remove}]`;
 		case "agentReviewed":
 			return `mark PR #${a.pr.number} agent-reviewed`;
+		case "merge":
+			return `merge PR #${a.pr.number}, approved by ${a.by}`;
 		case "compare":
 			return `post comparison on #${a.item.issue.number}`;
 		case "needsHuman":

package/src/daemon/snapshot.ts

@@ -63,6 +63,7 @@ export async function takeSnapshot(
 		...issue.prs.flatMap((p) => [
 			...p.comments.map((c) => c.author),
 			...p.reviews.map((c) => c.author),
+			...p.verdicts.map((v) => v.author),
 			...p.threads.flatMap((t) => t.comments.map((c) => c.author)),
 		]),
 	]);

package/src/daemon/types.ts

@@ -24,6 +24,21 @@ export type Checks =
 	| "EXPECTED"
 	| null;
 
+export type ReviewState =
+	| "APPROVED"
+	| "CHANGES_REQUESTED"
+	| "COMMENTED"
+	| "DISMISSED"
+	| "PENDING";
+
+/** A reviewer's latest review on a PR, body or not. */
+export type ReviewVerdict = {
+	author: string;
+	state: ReviewState;
+	/** Head commit the review was made on. */
+	commit: string | null;
+};
+
 export type PR = {
 	id: string;
 	number: number;
@@ -38,6 +53,8 @@ export type PR = {
 	comments: Comment[];
 	/** Submitted reviews that have a body. */
 	reviews: Comment[];
+	/** Latest review per reviewer, for approvals. */
+	verdicts: ReviewVerdict[];
 	threads: ReviewThread[];
 	checks: Checks;
 	/** UNKNOWN while GitHub is still computing it. */

package/src/github/api.ts

@@ -8,6 +8,7 @@ const PR_FIELDS = `
 	labels(first: 30) { nodes { name } }
 	comments(last: 100) { nodes { ${COMMENT} } }
 	reviews(last: 50) { nodes { ${COMMENT} } }
+	latestReviews(last: 20) { nodes { author { login } state commit { oid } } }
 	reviewThreads(last: 100) {
 		nodes {
 			id isResolved path line
@@ -103,6 +104,12 @@ function mapPR(p: any): PR {
 		comments: p.comments.nodes.map(comment),
 		reviews: p.reviews.nodes.map(comment).filter((r: Comment) => r.body.trim()),
 		// biome-ignore lint/suspicious/noExplicitAny: raw GraphQL shape
+		verdicts: p.latestReviews.nodes.map((r: any) => ({
+			author: r.author?.login ?? "ghost",
+			state: r.state,
+			commit: r.commit?.oid ?? null,
+		})),
+		// biome-ignore lint/suspicious/noExplicitAny: raw GraphQL shape
 		threads: p.reviewThreads.nodes.map((t: any) => ({
 			id: t.id,
 			isResolved: t.isResolved,
@@ -118,12 +125,21 @@ function mapPR(p: any): PR {
 
 // ---- writes ---------------------------------------------------------------
 
+/**
+ * Visible sign on kanbot's comments when it posts as the user. In app mode
+ * GitHub's bot badge already says so.
+ */
+export const SIGNATURE = "<sub>🤖 kanbot</sub>";
+
+export const signed = (gh: Gh, body: string) =>
+	gh.isBot ? body : `${SIGNATURE}\n\n${body}`;
+
 export function postComment(gh: Gh, number: number, body: string) {
 	return gh.restWrite(
 		`comment on #${number}`,
 		"POST",
 		gh.r(`/issues/${number}/comments`),
-		{ body },
+		{ body: signed(gh, body) },
 	);
 }
 
@@ -216,6 +232,35 @@ export function updatePRBody(gh: Gh, number: number, body: string) {
 	);
 }
 
+/** Merge only if the head is still `sha`, so later pushes aren't merged unseen. */
+export function mergePR(
+	gh: Gh,
+	number: number,
+	sha: string,
+	method: "squash" | "merge" | "rebase",
+) {
+	return gh.restWrite(
+		`merge PR #${number} (${method})`,
+		"PUT",
+		gh.r(`/pulls/${number}/merge`),
+		{ sha, merge_method: method },
+	);
+}
+
+export function requestReview(gh: Gh, number: number, logins: string[]) {
+	return gh.restWrite(
+		`request review on #${number} from ${logins.join(",")}`,
+		"POST",
+		gh.r(`/pulls/${number}/requested_reviewers`),
+		{ reviewers: logins },
+	);
+}
+
+/** Login of the account `gh` is signed in as. */
+export async function viewer(gh: Gh) {
+	return (await gh.rest<{ login: string }>("user")).login;
+}
+
 export function closePR(gh: Gh, number: number) {
 	return gh.restWrite(
 		`close PR #${number}`,
@@ -231,7 +276,7 @@ export function replyToThread(gh: Gh, threadId: string, body: string) {
 		`mutation($t: ID!, $b: String!) {
 			addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $t, body: $b }) { comment { id } }
 		}`,
-		{ t: threadId, b: body },
+		{ t: threadId, b: signed(gh, body) },
 	);
 }