kanbot 0.1.0 → 0.3.0

package/src/config.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { parse, parseDocument } from "yaml";
 import { z } from "zod";
+import { UserError } from "./errors.ts";
 
 export const COLUMN_KEYS = [
 	"ideas",
@@ -111,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
@@ -197,9 +232,35 @@ export async function writeConfigSchema(
 export async function loadConfig(root: string): Promise<Config> {
 	const path = configPath(root);
 	if (!existsSync(path)) {
-		throw new Error(`No ${path}. Run \`kanbot init\` first.`);
+		throw new UserError("kanbot is not set up in this repo.", {
+			why: "No .kanbot/config.yml in this directory.",
+			fix: "kanbot init",
+			docs: "getting-started#set-up-a-repository",
+		});
+	}
+	let raw: unknown;
+	try {
+		raw = parse(await Bun.file(path).text());
+	} catch (e) {
+		throw new UserError(
+			".kanbot/config.yml is not valid YAML.",
+			{
+				why: (e as Error).message.trim(),
+				fix: "Fix the syntax at the line shown above.",
+				docs: "configuration#config-file",
+			},
+			{ cause: e },
+		);
+	}
+	const config = ConfigSchema.safeParse(raw ?? {});
+	if (!config.success) {
+		throw new UserError(".kanbot/config.yml has invalid values.", {
+			why: z.prettifyError(config.error),
+			fix: "Fix the fields above. .kanbot/config.schema.json lists allowed values.",
+			docs: "configuration#config-file",
+		});
 	}
-	return ConfigSchema.parse(parse(await Bun.file(path).text()) ?? {});
+	return config.data;
 }
 
 /** Sets top-level keys, keeping the user's comments and formatting. */

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/lock.ts

@@ -1,5 +1,6 @@
 import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { UserError } from "../errors.ts";
 
 /** One daemon per repo. Stale locks (dead pid) are taken over. */
 export async function acquireLock(root: string): Promise<() => void> {
@@ -7,7 +8,11 @@ export async function acquireLock(root: string): Promise<() => void> {
 	if (existsSync(file)) {
 		const pid = Number(await Bun.file(file).text());
 		if (pid && isAlive(pid)) {
-			throw new Error(`kanbot is already running for this repo (pid ${pid})`);
+			throw new UserError("kanbot is already running for this repo.", {
+				why: `Process ${pid} holds .kanbot/daemon.pid. Only one daemon runs per repo.`,
+				fix: `Stop it with \`kill ${pid}\`, or check it with \`kanbot status\`.`,
+				docs: "usage#kanbot-run",
+			});
 		}
 	}
 	await Bun.write(file, String(process.pid));

package/src/daemon/loop.ts

@@ -1,6 +1,9 @@
 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";
@@ -45,14 +48,21 @@ export async function runDaemon(root: string, opts: RunOptions) {
 	const board = await loadBoard(gh, config);
 	const missing = missingColumns(board);
 	if (missing.length)
-		throw new Error(`Board is missing columns: ${missing.join(", ")}`);
+		throw new UserError("The project board is missing columns.", {
+			why: `No Status option for: ${missing.map((k) => config.columns[k]).join(", ")}.`,
+			fix: "kanbot board create adds them. Or match `columns` in .kanbot/config.yml to your board.",
+			docs: "configuration#columns",
+		});
 
 	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),
@@ -77,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 {
@@ -195,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/errors.ts

@@ -0,0 +1,171 @@
+export const DOCS_URL = "https://kanbot.mib.im";
+const ISSUES_URL = "https://github.com/mikaelbr/kanbot/issues";
+
+export type ErrorHelp = {
+	/** Why it failed: the underlying error or the rule that was broken. */
+	why?: string;
+	/** What to do about it, usually a command. */
+	fix?: string;
+	/** Docs page and anchor, e.g. "configuration#config-file". */
+	docs?: string;
+	/** How to learn more. Defaults to `kanbot doctor`; "" hides it. */
+	more?: string;
+};
+
+/** An expected failure. Printed without a stack trace. */
+export class UserError extends Error {
+	constructor(
+		message: string,
+		readonly help: ErrorHelp = {},
+		options?: ErrorOptions,
+	) {
+		super(message, options);
+		this.name = "UserError";
+	}
+}
+
+const INSTALL: Record<string, ErrorHelp> = {
+	gh: {
+		fix: "Install the GitHub CLI from https://cli.github.com, then run `gh auth login`.",
+		docs: "getting-started#requirements",
+	},
+	git: {
+		fix: "Install git from https://git-scm.com/downloads.",
+		docs: "getting-started#requirements",
+	},
+	claude: {
+		fix: "Install Claude Code, then run `claude auth login`.",
+		docs: "providers#claude-code",
+	},
+	codex: {
+		fix: "Install Codex (npm i -g @openai/codex), then run `codex login`.",
+		docs: "providers#codex",
+	},
+};
+
+/** Known failures from gh, git and the GitHub API, matched on message. */
+const KNOWN: [RegExp, string, ErrorHelp][] = [
+	[
+		/gh auth login|not logged in|HTTP 401|Bad credentials/i,
+		"GitHub CLI is not logged in.",
+		{ fix: "gh auth login", docs: "getting-started#requirements" },
+	],
+	[
+		/INSUFFICIENT_SCOPES|required scopes|scope.*project/i,
+		"GitHub token is missing the `project` scope.",
+		{ fix: "gh auth refresh -s project", docs: "getting-started#requirements" },
+	],
+	[
+		/rate limit/i,
+		"GitHub API rate limit reached.",
+		{ fix: "Wait a few minutes and try again." },
+	],
+	[
+		/Could not resolve to a ProjectV2/i,
+		"Project board not found.",
+		{
+			fix: "Check `project` in .kanbot/config.yml, or run `kanbot board create`.",
+			docs: "getting-started#create-the-board",
+		},
+	],
+	[
+		/Could not resolve to a Repository|HTTP 404/i,
+		"GitHub repository not found, or gh has no access to it.",
+		{
+			fix: "Check `repo` in .kanbot/config.yml and run `gh repo view <owner/name>`.",
+			docs: "configuration#config-file",
+		},
+	],
+	[
+		/not a git repository/i,
+		"Not inside a git repository.",
+		{ fix: "cd into your repo, or run `git init`." },
+	],
+	[
+		/no git remotes|none of the git remotes/i,
+		"This repo has no GitHub remote.",
+		{
+			fix: "git remote add origin <url> && git push -u origin HEAD",
+			docs: "getting-started#set-up-a-repository",
+		},
+	],
+	[
+		/ENOTFOUND|ECONNREFUSED|ETIMEDOUT|dial tcp|error connecting/i,
+		"Could not reach GitHub.",
+		{ fix: "Check your network connection and try again." },
+	],
+];
+
+export type Described = ErrorHelp & { message: string; expected: boolean };
+
+export function describeError(e: unknown, command = ""): Described {
+	if (e instanceof UserError)
+		return { message: e.message, ...e.help, expected: true };
+	if (!(e instanceof Error)) return { message: String(e), expected: false };
+	const raw = e.message.trim();
+
+	// citty argument errors: unknown command, bad flag value, …
+	if (e.name === "CLIError") {
+		const unknown = (e as { code?: string }).code === "E_UNKNOWN_COMMAND";
+		return {
+			message: Bun.stripANSI(raw),
+			fix: `Run \`kanbot ${unknown ? "" : `${command} `}--help\` to see valid options.`,
+			docs: "usage",
+			more: "",
+			expected: true,
+		};
+	}
+
+	const bin = raw.match(/Executable not found in \$PATH: "(.+)"/)?.[1];
+	if (bin)
+		return {
+			message: `\`${bin}\` is not installed or not on PATH.`,
+			why: raw,
+			...INSTALL[bin],
+			expected: true,
+		};
+
+	const known = KNOWN.find(([re]) => re.test(raw));
+	if (known)
+		return { message: known[1], why: raw, ...known[2], expected: true };
+	const tool = raw.match(/^(gh|git) .* failed/)?.[1];
+	if (tool)
+		return {
+			message: `A \`${tool}\` command failed.`,
+			why: raw,
+			fix:
+				tool === "gh"
+					? "Read the gh error above. `gh auth status` shows login and scopes."
+					: "Read the git error above. `git status` shows the repo state.",
+			expected: true,
+		};
+	return { message: raw, expected: false };
+}
+
+const indent = (s: string) => s.replace(/^(?=.)/gm, "  ");
+
+export function formatError(
+	e: unknown,
+	opts: { debug?: boolean; command?: string } = {},
+): string {
+	const d = describeError(e, opts.command);
+	const lines = [`✖ ${d.message}`];
+	if (d.why) lines.push("", indent(d.why));
+	lines.push("");
+	if (d.fix) lines.push(`  Fix:  ${d.fix}`);
+	if (d.docs) lines.push(`  Docs: ${DOCS_URL}/${d.docs}`);
+	if (opts.debug && e instanceof Error && e.stack) {
+		lines.push("", e.stack);
+		if (e.cause instanceof Error && e.cause.stack)
+			lines.push("", `Caused by: ${e.cause.stack}`);
+	} else if (d.expected) {
+		const more = d.more ?? "Run `kanbot doctor` to check your setup.";
+		if (more) lines.push(`  More: ${more}`);
+	} else {
+		lines.push(
+			"  More: rerun with KANBOT_DEBUG=1 for a stack trace.",
+			`        If it looks like a bug, report it at ${ISSUES_URL}`,
+		);
+	}
+	return lines.join("\n");
+}

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) },
 	);
 }
 

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;
+	});
+}