kanbot 0.2.0 → 0.4.0

package/src/github/app.ts

@@ -0,0 +1,153 @@
+import { createSign } from "node:crypto";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Config } from "../config.ts";
+import { UserError } from "../errors.ts";
+import { Gh, type TokenSource } from "./gh.ts";
+
+const API = "https://api.github.com";
+/** Renew installation tokens this long before GitHub expires them (1 h). */
+const RENEW_MS = 5 * 60_000;
+
+export type AppConfig = NonNullable<Config["identity"]["app"]>;
+
+/** Where `kanbot app create` stores the app's private key. Never in the repo. */
+export function appKeyPath(appId: number) {
+	return join(homedir(), ".kanbot", "apps", `${appId}.pem`);
+}
+
+const b64url = (s: string) => Buffer.from(s).toString("base64url");
+
+/** A short-lived JWT that authenticates as the app itself. */
+export function appJwt(appId: number, key: string, now = Date.now()) {
+	const iat = Math.floor(now / 1000) - 60;
+	const head = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+	const body = b64url(
+		JSON.stringify({ iat, exp: iat + 9 * 60, iss: String(appId) }),
+	);
+	const sig = createSign("RSA-SHA256")
+		.update(`${head}.${body}`)
+		.sign(key, "base64url");
+	return `${head}.${body}.${sig}`;
+}
+
+async function api<T>(
+	path: string,
+	jwt: string,
+	method = "GET",
+	body?: unknown,
+): Promise<T> {
+	const res = await fetch(`${API}${path}`, {
+		method,
+		headers: {
+			accept: "application/vnd.github+json",
+			authorization: `Bearer ${jwt}`,
+			"x-github-api-version": "2022-11-28",
+		},
+		body: body === undefined ? undefined : JSON.stringify(body),
+	});
+	if (!res.ok)
+		throw new Error(
+			`GitHub ${method} ${path} failed (${res.status}): ${await res.text()}`,
+		);
+	return (await res.json()) as T;
+}
+
+/**
+ * Installation tokens for one repo, cached until shortly before they expire.
+ * Scoped to that repo only.
+ */
+export function appTokens(app: AppConfig, repo: string): TokenSource {
+	const keyFile = appKeyPath(app.id);
+	let cached: { token: string; expires: number } | null = null;
+	let installation: number | null = null;
+	return async () => {
+		if (cached && Date.now() < cached.expires - RENEW_MS) return cached.token;
+		if (!existsSync(keyFile))
+			throw new UserError(`No private key for the kanbot app ${app.slug}.`, {
+				why: `Expected it at ${keyFile}.`,
+				fix: "Run `kanbot app create`, or copy the key there from the machine that created the app.",
+				docs: "identity#app-mode",
+			});
+		const jwt = appJwt(app.id, await Bun.file(keyFile).text());
+		installation ??= await api<{ id: number }>(
+			`/repos/${repo}/installation`,
+			jwt,
+		)
+			.then((r) => r.id)
+			.catch((e) => {
+				throw new UserError(`The kanbot app ${app.slug} can't reach ${repo}.`, {
+					why: String(e),
+					fix: `Install it on the repo: https://github.com/apps/${app.slug}/installations/new`,
+					docs: "identity#app-mode",
+				});
+			});
+		const res = await api<{ token: string; expires_at: string }>(
+			`/app/installations/${installation}/access_tokens`,
+			jwt,
+			"POST",
+			{ repositories: [repo.split("/")[1]] },
+		);
+		cached = { token: res.token, expires: Date.parse(res.expires_at) };
+		return res.token;
+	};
+}
+
+/**
+ * The client kanbot talks as: the app in app mode, otherwise the user's own.
+ * Commits, pushes, board moves and merges always stay on the user's client.
+ */
+export function botClient(config: Config, user: Gh): Gh {
+	const { mode, app } = config.identity;
+	if (mode !== "app") return user;
+	if (!app)
+		throw new UserError("identity.mode is app, but no app is set.", {
+			fix: "kanbot app create",
+			docs: "identity#app-mode",
+		});
+	return new Gh(config.repo, user.dryRun, appTokens(app, config.repo));
+}
+
+// ---- manifest flow --------------------------------------------------------------
+
+/** Permissions the app needs to talk on issues and PRs. Nothing else. */
+export const APP_PERMISSIONS = {
+	issues: "write",
+	pull_requests: "write",
+	contents: "read",
+	metadata: "read",
+} as const;
+
+export function appManifest(name: string, redirectUrl: string) {
+	return {
+		name,
+		url: "https://github.com/mikaelbr/kanbot",
+		redirect_url: redirectUrl,
+		description:
+			"kanbot's voice on GitHub: plans, reviews and replies. Commits stay yours.",
+		public: false,
+		hook_attributes: {
+			url: "https://github.com/mikaelbr/kanbot",
+			active: false,
+		},
+		default_permissions: APP_PERMISSIONS,
+		default_events: [],
+	};
+}
+
+export type CreatedApp = { id: number; slug: string; pem: string };
+
+/** Trade the manifest flow's one-time code for the new app's credentials. */
+export function convertManifest(code: string): Promise<CreatedApp> {
+	return fetch(`${API}/app-manifests/${code}/conversions`, {
+		method: "POST",
+		headers: { accept: "application/vnd.github+json" },
+	}).then(async (res) => {
+		if (!res.ok)
+			throw new Error(
+				`Creating the app failed (${res.status}): ${await res.text()}`,
+			);
+		return (await res.json()) as CreatedApp;
+	});
+}

package/src/github/gh.ts

@@ -1,15 +1,29 @@
 import { log } from "../log.ts";
 
+/** Returns a GitHub token to use instead of `gh`'s own login. */
+export type TokenSource = () => Promise<string>;
+
 /**
  * Thin wrapper over the `gh` CLI so kanbot reuses the user's existing auth.
+ * With a `token`, calls run as that identity instead (the kanbot app).
  * Reads always run; writes are skipped (and logged) in dry-run mode.
  */
 export class Gh {
 	constructor(
 		readonly repo: string,
 		readonly dryRun = false,
+		private readonly token?: TokenSource,
 	) {}
 
+	/** True when calls run as the kanbot app, not the user. */
+	get isBot() {
+		return this.token !== undefined;
+	}
+
+	private async env() {
+		return this.token ? { GH_TOKEN: await this.token() } : undefined;
+	}
+
 	get owner() {
 		return this.repo.split("/")[0] as string;
 	}
@@ -35,7 +49,11 @@ export class Gh {
 	}
 
 	private async queryOnce<T>(input: string): Promise<T> {
-		const out = await run(["api", "graphql", "--input", "-"], input);
+		const out = await run(
+			["api", "graphql", "--input", "-"],
+			input,
+			await this.env(),
+		);
 		const json = JSON.parse(out) as { data: T; errors?: { message: string }[] };
 		if (json.errors?.length) {
 			throw new Error(
@@ -58,7 +76,9 @@ export class Gh {
 	}
 
 	async rest<T = unknown>(path: string): Promise<T> {
-		return JSON.parse(await run(["api", path])) as T;
+		return JSON.parse(
+			await run(["api", path], undefined, await this.env()),
+		) as T;
 	}
 
 	async restWrite<T = unknown>(
@@ -80,6 +100,7 @@ export class Gh {
 				...(body === undefined ? [] : ["--input", "-"]),
 			],
 			body === undefined ? undefined : JSON.stringify(body),
+			await this.env(),
 		);
 		return (out.trim() ? JSON.parse(out) : null) as T;
 	}
@@ -90,9 +111,14 @@ export class Gh {
 	}
 }
 
-export async function run(args: string[], input?: string): Promise<string> {
+export async function run(
+	args: string[],
+	input?: string,
+	env?: Record<string, string>,
+): Promise<string> {
 	const proc = Bun.spawn(["gh", ...args], {
 		stdin: input === undefined ? "ignore" : new Blob([input]),
+		env: env ? { ...process.env, ...env } : undefined,
 		stdout: "pipe",
 		stderr: "pipe",
 	});

package/src/jobs/prompts.ts

@@ -1,3 +1,4 @@
+import { type Capabilities, capabilitiesSection } from "../capabilities.ts";
 import {
 	type FixJob,
 	type ImplementJob,
@@ -6,6 +7,7 @@ import {
 	reviewPasses,
 } from "../daemon/derive.ts";
 import type { Comment, Issue, PR } from "../daemon/types.ts";
+import { SIGNATURE } from "../github/api.ts";
 import { extractPlan, isKanbot, stripPlan } from "../github/markers.ts";
 import type { Finding } from "../schemas/results.ts";
 
@@ -20,6 +22,8 @@ const RULES = `## Ground rules
 - Your final answer must be the structured JSON result. Put everything the human should see in it.
 - Write short and plain: only what the reader needs to act or understand. Don't restate the input or narrate your process.`;
 
+const VALIDATION = "List what you used under Validation in the PR body.";
+
 function quote(text: string) {
 	return text.trim() ? text.trim() : "_(empty)_";
 }
@@ -36,7 +40,10 @@ function conversation(comments: Comment[], limit = 30) {
 }
 
 function stripMarkers(body: string) {
-	return body.replace(/<!--\s*kanbot[^>]*-->/g, "").trim();
+	return body
+		.replace(SIGNATURE, "")
+		.replace(/<!--\s*kanbot[^>]*-->/g, "")
+		.trim();
 }
 
 /**
@@ -105,7 +112,11 @@ export function planPrompt(job: PlanJob, explore: number | null) {
 	return parts.join("\n\n");
 }
 
-export function implementPrompt(job: ImplementJob, base: string) {
+export function implementPrompt(
+	job: ImplementJob,
+	base: string,
+	capabilities: Capabilities = {},
+) {
 	const { issue } = job.item;
 	const parts = [
 		issueHeader(issue),
@@ -122,13 +133,18 @@ export function implementPrompt(job: ImplementJob, base: string) {
 			`## Recent human comments on the issue\n${conversation(humanNotes)}`,
 		);
 	parts.push(
+		capabilitiesSection(capabilities, VALIDATION),
 		`## Workspace\n- Branch \`${job.branch}\`, created from \`origin/${base}\`.\n- Commit your work with conventional commit messages. Uncommitted changes are committed for you, but prefer small commits.\n- Run the project's tests and linters before finishing and report them in \`testsRun\`.`,
 		RULES,
 	);
-	return parts.join("\n\n");
+	return parts.filter(Boolean).join("\n\n");
 }
 
-export function reviewPrompt(job: ReviewJob, base: string) {
+export function reviewPrompt(
+	job: ReviewJob,
+	base: string,
+	capabilities: Capabilities = {},
+) {
 	const { issue } = job.item;
 	const { pr } = job;
 	return [
@@ -136,7 +152,8 @@ export function reviewPrompt(job: ReviewJob, base: string) {
 		`## Plan / acceptance criteria\n${extractPlan(issue.body) ?? stripPlan(issue.body)}`,
 		`## Pull request #${pr.number}: ${pr.title}\nBranch \`${pr.headRefName}\` (checked out). Diff with: \`git diff origin/${base}...HEAD\`. CI status: ${pr.checks ?? "none"}.\n\n### PR description\n${quote(stripMarkers(pr.body))}`,
 		humanDecisions(pr),
-		`## Review pass ${job.pass} of ${reviewPasses(issue).length}\nYou only review. Do not edit files or commit.`,
+		capabilitiesSection(capabilities),
+		`## Review pass ${job.pass} of ${reviewPasses(issue).length}: ${job.pass === 1 ? "technical" : "acceptance"}\nYou only review. Do not edit files or commit.${job.pass === 2 && Object.values(capabilities).some((c) => c.required) ? " A required capability that applies but is missing from the PR body's Validation section is a blocker." : ""}`,
 		RULES,
 	]
 		.filter(Boolean)
@@ -144,7 +161,12 @@ export function reviewPrompt(job: ReviewJob, base: string) {
 }
 
 /** `details`: CI logs for a CI fix, the conflicted files for a conflict fix. */
-export function fixPrompt(job: FixJob, base: string, details: string | null) {
+export function fixPrompt(
+	job: FixJob,
+	base: string,
+	details: string | null,
+	capabilities: Capabilities = {},
+) {
 	const { issue } = job.item;
 	const { pr } = job;
 	const parts = [
@@ -152,6 +174,8 @@ export function fixPrompt(job: FixJob, base: string, details: string | null) {
 		`## Plan / acceptance criteria\n${extractPlan(issue.body) ?? stripPlan(issue.body)}`,
 		`## Pull request #${pr.number}: ${pr.title}\nBranch \`${pr.headRefName}\` (checked out). Diff with: \`git diff origin/${base}...HEAD\`.\n\n### Current PR description\n${quote(stripMarkers(pr.body))}`,
 	];
+	const caps = capabilitiesSection(capabilities, VALIDATION);
+	if (caps) parts.push(caps);
 	const r = job.reason;
 	const decisions = r.type === "feedback" ? null : humanDecisions(pr);
 	if (decisions) parts.push(decisions);