kanbot 0.0.0-stage → 0.2.0

package/src/daemon/types.ts

@@ -0,0 +1,73 @@
+import type { ColumnKey } from "../config.ts";
+
+export type Comment = {
+	id: string;
+	databaseId: number;
+	author: string;
+	body: string;
+	createdAt: string;
+};
+
+export type ReviewThread = {
+	id: string;
+	isResolved: boolean;
+	path: string | null;
+	line: number | null;
+	comments: Comment[];
+};
+
+export type Checks =
+	| "SUCCESS"
+	| "FAILURE"
+	| "ERROR"
+	| "PENDING"
+	| "EXPECTED"
+	| null;
+
+export type PR = {
+	id: string;
+	number: number;
+	url: string;
+	title: string;
+	body: string;
+	state: "OPEN" | "CLOSED" | "MERGED";
+	headRefName: string;
+	headSha: string;
+	createdAt: string;
+	labels: string[];
+	comments: Comment[];
+	/** Submitted reviews that have a body. */
+	reviews: Comment[];
+	threads: ReviewThread[];
+	checks: Checks;
+	/** UNKNOWN while GitHub is still computing it. */
+	mergeable: "MERGEABLE" | "CONFLICTING" | "UNKNOWN";
+};
+
+export type Issue = {
+	id: string;
+	number: number;
+	url: string;
+	title: string;
+	body: string;
+	state: "OPEN" | "CLOSED";
+	labels: string[];
+	comments: Comment[];
+	prs: PR[];
+	/** A PR labeled `kanbot-review`, reviewed without a card. Fields mirror the PR. */
+	prOnly?: boolean;
+};
+
+export type Item = {
+	itemId: string;
+	column: ColumnKey | null;
+	/** Index in board order; lower is higher priority. */
+	position: number;
+	issue: Issue;
+};
+
+export type Snapshot = {
+	items: Item[];
+	/** Logins whose comments agents act on (collaborators with write access). */
+	trusted: ReadonlySet<string>;
+};

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

@@ -0,0 +1,332 @@
+import type { Checks, Comment, Issue, PR } from "../daemon/types.ts";
+import type { Gh } from "./gh.ts";
+
+const COMMENT = "id databaseId author { login } body createdAt";
+
+const PR_FIELDS = `
+	id number url title body state headRefName headRefOid mergeable createdAt
+	labels(first: 30) { nodes { name } }
+	comments(last: 100) { nodes { ${COMMENT} } }
+	reviews(last: 50) { nodes { ${COMMENT} } }
+	reviewThreads(last: 100) {
+		nodes {
+			id isResolved path line
+			comments(last: 30) { nodes { ${COMMENT} } }
+		}
+	}
+	commits(last: 1) { nodes { commit { statusCheckRollup { state } } } }`;
+
+const ISSUE_QUERY = `
+query($owner: String!, $name: String!, $number: Int!) {
+	repository(owner: $owner, name: $name) {
+		issue(number: $number) {
+			id number url title body state
+			labels(first: 50) { nodes { name } }
+			comments(last: 100) { nodes { ${COMMENT} } }
+			closedByPullRequestsReferences(first: 10, includeClosedPrs: true) {
+				nodes { ${PR_FIELDS} }
+			}
+		}
+	}
+}`;
+
+const LABELED_PRS_QUERY = `
+query($owner: String!, $name: String!, $label: String!) {
+	repository(owner: $owner, name: $name) {
+		pullRequests(labels: [$label], states: OPEN, first: 50) {
+			nodes { isCrossRepository ${PR_FIELDS} }
+		}
+	}
+}`;
+
+type RawComment = Omit<Comment, "author"> & {
+	author: { login: string } | null;
+};
+type Nodes<T> = { nodes: T[] };
+
+const comment = (c: RawComment): Comment => ({
+	...c,
+	author: c.author?.login ?? "ghost",
+});
+const names = (l: Nodes<{ name: string }>) => l.nodes.map((n) => n.name);
+
+export async function fetchIssue(gh: Gh, number: number): Promise<Issue> {
+	// biome-ignore lint/suspicious/noExplicitAny: raw GraphQL shape, mapped below
+	const data = await gh.query<any>(ISSUE_QUERY, {
+		owner: gh.owner,
+		name: gh.name,
+		number,
+	});
+	const i = data.repository.issue;
+	return {
+		id: i.id,
+		number: i.number,
+		url: i.url,
+		title: i.title,
+		body: i.body,
+		state: i.state,
+		labels: names(i.labels),
+		comments: i.comments.nodes.map(comment),
+		prs: i.closedByPullRequestsReferences.nodes.map(mapPR),
+	};
+}
+
+/**
+ * Open PRs with `label`, for review without a board card. Fork PRs are left
+ * out: their branch isn't on origin, so fixes couldn't be pushed.
+ */
+export async function fetchLabeledPRs(gh: Gh, label: string): Promise<PR[]> {
+	// biome-ignore lint/suspicious/noExplicitAny: raw GraphQL shape, mapped below
+	const data = await gh.query<any>(LABELED_PRS_QUERY, {
+		owner: gh.owner,
+		name: gh.name,
+		label,
+	});
+	return data.repository.pullRequests.nodes
+		.filter((p: { isCrossRepository: boolean }) => !p.isCrossRepository)
+		.map(mapPR);
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: raw GraphQL shape
+function mapPR(p: any): PR {
+	return {
+		id: p.id,
+		number: p.number,
+		url: p.url,
+		title: p.title,
+		body: p.body,
+		state: p.state,
+		headRefName: p.headRefName,
+		headSha: p.headRefOid,
+		createdAt: p.createdAt,
+		labels: names(p.labels),
+		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
+		threads: p.reviewThreads.nodes.map((t: any) => ({
+			id: t.id,
+			isResolved: t.isResolved,
+			path: t.path,
+			line: t.line,
+			comments: t.comments.nodes.map(comment),
+		})),
+		checks: (p.commits.nodes[0]?.commit.statusCheckRollup?.state ??
+			null) as Checks,
+		mergeable: p.mergeable,
+	};
+}
+
+// ---- writes ---------------------------------------------------------------
+
+export function postComment(gh: Gh, number: number, body: string) {
+	return gh.restWrite(
+		`comment on #${number}`,
+		"POST",
+		gh.r(`/issues/${number}/comments`),
+		{ body },
+	);
+}
+
+export function updateIssueBody(gh: Gh, number: number, body: string) {
+	return gh.restWrite(
+		`update body of #${number}`,
+		"PATCH",
+		gh.r(`/issues/${number}`),
+		{ body },
+	);
+}
+
+export function addLabels(gh: Gh, number: number, labels: string[]) {
+	if (!labels.length) return Promise.resolve(null);
+	return gh.restWrite(
+		`label #${number} ${labels.join(",")}`,
+		"POST",
+		gh.r(`/issues/${number}/labels`),
+		{
+			labels,
+		},
+	);
+}
+
+export async function removeLabel(gh: Gh, number: number, label: string) {
+	try {
+		await gh.restWrite(
+			`unlabel #${number} ${label}`,
+			"DELETE",
+			gh.r(`/issues/${number}/labels/${encodeURIComponent(label)}`),
+		);
+	} catch (e) {
+		if (!String(e).includes("404")) throw e;
+	}
+}
+
+export function react(
+	gh: Gh,
+	subjectId: string,
+	content: "EYES" | "THUMBS_UP" | "ROCKET",
+) {
+	return gh.mutate(
+		`react ${content}`,
+		`mutation($s: ID!, $c: ReactionContent!) { addReaction(input: { subjectId: $s, content: $c }) { reaction { content } } }`,
+		{ s: subjectId, c: content },
+	);
+}
+
+export async function createIssue(gh: Gh, title: string, body: string) {
+	return gh.restWrite<{ number: number; node_id: string }>(
+		`create issue "${title}"`,
+		"POST",
+		gh.r("/issues"),
+		{ title, body },
+	);
+}
+
+export function addSubIssue(gh: Gh, parentId: string, childId: string) {
+	return gh.mutate(
+		"add sub-issue",
+		`mutation($p: ID!, $c: ID!) { addSubIssue(input: { issueId: $p, subIssueId: $c }) { issue { id } } }`,
+		{ p: parentId, c: childId },
+	);
+}
+
+export function createPR(
+	gh: Gh,
+	pr: {
+		title: string;
+		body: string;
+		head: string;
+		base: string;
+		draft?: boolean;
+	},
+) {
+	return gh.restWrite<{ number: number; html_url: string }>(
+		`open PR ${pr.head} → ${pr.base}`,
+		"POST",
+		gh.r("/pulls"),
+		pr,
+	);
+}
+
+export function updatePRBody(gh: Gh, number: number, body: string) {
+	return gh.restWrite(
+		`update body of PR #${number}`,
+		"PATCH",
+		gh.r(`/pulls/${number}`),
+		{ body },
+	);
+}
+
+export function closePR(gh: Gh, number: number) {
+	return gh.restWrite(
+		`close PR #${number}`,
+		"PATCH",
+		gh.r(`/pulls/${number}`),
+		{ state: "closed" },
+	);
+}
+
+export function replyToThread(gh: Gh, threadId: string, body: string) {
+	return gh.mutate(
+		"reply to review thread",
+		`mutation($t: ID!, $b: String!) {
+			addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $t, body: $b }) { comment { id } }
+		}`,
+		{ t: threadId, b: body },
+	);
+}
+
+export function resolveThread(gh: Gh, threadId: string) {
+	return gh.mutate(
+		"resolve review thread",
+		`mutation($t: ID!) { resolveReviewThread(input: { threadId: $t }) { thread { id } } }`,
+		{ t: threadId },
+	);
+}
+
+export async function ensureLabel(
+	gh: Gh,
+	name: string,
+	color: string,
+	description: string,
+) {
+	try {
+		await gh.restWrite(`create label ${name}`, "POST", gh.r("/labels"), {
+			name,
+			color,
+			description,
+		});
+	} catch (e) {
+		if (!String(e).includes("already_exists")) throw e;
+	}
+}
+
+export async function failedCheckLogs(gh: Gh, sha: string): Promise<string> {
+	type Runs = {
+		check_runs: {
+			name: string;
+			conclusion: string | null;
+			output: {
+				title: string | null;
+				summary: string | null;
+				text: string | null;
+			};
+		}[];
+	};
+	const runs = await gh.rest<Runs>(
+		gh.r(`/commits/${sha}/check-runs?per_page=50`),
+	);
+	return runs.check_runs
+		.filter((r) => r.conclusion === "failure" || r.conclusion === "timed_out")
+		.map(
+			(r) =>
+				`### ${r.name} (${r.conclusion})\n${[r.output.title, r.output.summary, r.output.text].filter(Boolean).join("\n").slice(0, 6000)}`,
+		)
+		.join("\n\n");
+}
+
+// ---- Copilot code review ------------------------------------------------------
+
+const COPILOT_RULESET = "kanbot: Copilot review";
+
+/** Create or update the branch ruleset that requests Copilot review on PRs. */
+export async function ensureCopilotRuleset(gh: Gh, onPush: boolean) {
+	const body = {
+		name: COPILOT_RULESET,
+		target: "branch",
+		enforcement: "active",
+		conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+		rules: [
+			{
+				type: "copilot_code_review",
+				parameters: {
+					review_on_push: onPush,
+					review_draft_pull_requests: false,
+				},
+			},
+		],
+	};
+	const sets = await gh.rest<{ id: number; name: string }[]>(gh.r("/rulesets"));
+	const existing = sets.find((s) => s.name === COPILOT_RULESET);
+	return existing
+		? gh.restWrite(
+				"update Copilot review ruleset",
+				"PUT",
+				gh.r(`/rulesets/${existing.id}`),
+				body,
+			)
+		: gh.restWrite(
+				"create Copilot review ruleset",
+				"POST",
+				gh.r("/rulesets"),
+				body,
+			);
+}
+
+/** The active Copilot review rule on `branch`, if any. */
+export async function copilotReviewRule(gh: Gh, branch: string) {
+	type Rule = { type: string; parameters?: { review_on_push?: boolean } };
+	const rules = await gh.rest<Rule[]>(
+		gh.r(`/rules/branches/${encodeURIComponent(branch)}`),
+	);
+	return rules.find((r) => r.type === "copilot_code_review") ?? null;
+}

package/src/github/gh.ts

@@ -0,0 +1,110 @@
+import { log } from "../log.ts";
+
+/**
+ * Thin wrapper over the `gh` CLI so kanbot reuses the user's existing auth.
+ * Reads always run; writes are skipped (and logged) in dry-run mode.
+ */
+export class Gh {
+	constructor(
+		readonly repo: string,
+		readonly dryRun = false,
+	) {}
+
+	get owner() {
+		return this.repo.split("/")[0] as string;
+	}
+	get name() {
+		return this.repo.split("/")[1] as string;
+	}
+
+	async query<T>(
+		query: string,
+		variables: Record<string, unknown> = {},
+	): Promise<T> {
+		const input = JSON.stringify({ query, variables });
+		// Projects mutations sometimes fail with "temporary conflict … try again"
+		// when a board workflow (e.g. Auto-add) touches the same item.
+		for (let attempt = 1; ; attempt++) {
+			try {
+				return await this.queryOnce<T>(input);
+			} catch (e) {
+				if (attempt >= 3 || !/try again/i.test(String(e))) throw e;
+				await Bun.sleep(1000 * attempt);
+			}
+		}
+	}
+
+	private async queryOnce<T>(input: string): Promise<T> {
+		const out = await run(["api", "graphql", "--input", "-"], input);
+		const json = JSON.parse(out) as { data: T; errors?: { message: string }[] };
+		if (json.errors?.length) {
+			throw new Error(
+				`GraphQL: ${json.errors.map((e) => e.message).join("; ")}`,
+			);
+		}
+		return json.data;
+	}
+
+	async mutate<T>(
+		what: string,
+		query: string,
+		variables: Record<string, unknown> = {},
+	): Promise<T | null> {
+		if (this.dryRun) {
+			log.info(`[dry-run] ${what}`);
+			return null;
+		}
+		return this.query<T>(query, variables);
+	}
+
+	async rest<T = unknown>(path: string): Promise<T> {
+		return JSON.parse(await run(["api", path])) as T;
+	}
+
+	async restWrite<T = unknown>(
+		what: string,
+		method: "POST" | "PATCH" | "PUT" | "DELETE",
+		path: string,
+		body?: unknown,
+	): Promise<T | null> {
+		if (this.dryRun) {
+			log.info(`[dry-run] ${what}`);
+			return null;
+		}
+		const out = await run(
+			[
+				"api",
+				"-X",
+				method,
+				path,
+				...(body === undefined ? [] : ["--input", "-"]),
+			],
+			body === undefined ? undefined : JSON.stringify(body),
+		);
+		return (out.trim() ? JSON.parse(out) : null) as T;
+	}
+
+	/** `repos/{owner}/{name}` + suffix */
+	r(suffix: string) {
+		return `repos/${this.repo}${suffix}`;
+	}
+}
+
+export async function run(args: string[], input?: string): Promise<string> {
+	const proc = Bun.spawn(["gh", ...args], {
+		stdin: input === undefined ? "ignore" : new Blob([input]),
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [out, err, code] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+	if (code !== 0) {
+		throw new Error(
+			`gh ${args.slice(0, 3).join(" ")} failed (${code}): ${err.trim() || out.trim()}`,
+		);
+	}
+	return out;
+}