kanbot 0.5.2 → 0.6.0

package/README.md

@@ -114,6 +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.
+Docs: [kanbot.mib.im](https://kanbot.mib.im) shows the latest release plus later commits that only touch `docs/` or `README.md`, so docs fixes need no 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.5.2",
+	"version": "0.6.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

@@ -79,6 +79,27 @@
 			"minimum": 1,
 			"maximum": 9007199254740991
 		},
+		"wip": {
+			"description": "Work-in-progress limits.",
+			"default": {},
+			"type": "object",
+			"properties": {
+				"awaitingHuman": {
+					"default": null,
+					"description": "When this many items wait on you (`kanbot status`), no new Ready card starts. Started work runs on. null: no limit.",
+					"anyOf": [
+						{
+							"type": "integer",
+							"minimum": 1,
+							"maximum": 9007199254740991
+						},
+						{
+							"type": "null"
+						}
+					]
+				}
+			}
+		},
 		"pollSeconds": {
 			"default": 60,
 			"description": "Seconds between board polls.",

package/src/ask.ts

@@ -0,0 +1,88 @@
+import { color } from "./color.ts";
+
+/** Reads one answer. Null means no answer (end of input). */
+export type Ask = (question: string) => string | null;
+export type Say = (line: string) => void;
+
+export type Choice<T> = { value: T; label: string; hint?: string };
+
+/** Numbered list; Enter picks the default. */
+export function choose<T>(
+	ask: Ask,
+	say: Say,
+	question: string,
+	choices: Choice<T>[],
+	def = 0,
+): T {
+	say(color.bold(question));
+	choices.forEach((c, i) => {
+		const hint = c.hint ? color.dim(` — ${c.hint}`) : "";
+		say(`  ${i + 1}. ${c.label}${hint}`);
+	});
+	for (;;) {
+		const a = ask(`Pick 1-${choices.length} [${def + 1}]:`)?.trim();
+		if (!a) return (choices[def] as Choice<T>).value;
+		const picked =
+			choices[Number(a) - 1] ??
+			choices.find((c) => String(c.value) === a || c.label === a);
+		if (picked) return picked.value;
+		say(`  Type a number from 1 to ${choices.length}.`);
+	}
+}
+
+export function confirm(ask: Ask, question: string, def: boolean): boolean {
+	const a = ask(`${question} ${def ? "[Y/n]" : "[y/N]"}`)?.trim();
+	if (!a) return def;
+	return /^y/i.test(a);
+}
+
+/** A whole number ≥ min. With `none`, typing it returns null. */
+export function askNumber(
+	ask: Ask,
+	say: Say,
+	question: string,
+	def: number | null,
+	opts: { min?: number; none?: string } = {},
+): number | null {
+	const min = opts.min ?? 1;
+	const shown = def ?? opts.none;
+	for (;;) {
+		const a = ask(`${question} [${shown}]`)?.trim();
+		if (!a) return def;
+		if (opts.none && a === opts.none) return null;
+		const n = Number(a);
+		if (Number.isInteger(n) && n >= min) return n;
+		say(
+			`  Type a whole number, ${min} or more${opts.none ? `, or "${opts.none}"` : ""}.`,
+		);
+	}
+}
+
+/** Free text; Enter keeps the default. `valid` returns an error to ask again. */
+export function askText(
+	ask: Ask,
+	say: Say,
+	question: string,
+	valid: (s: string) => string | null = () => null,
+): string | null {
+	for (;;) {
+		const a = ask(question)?.trim();
+		if (!a) return null;
+		const err = valid(a);
+		if (!err) return a;
+		say(`  ${err}`);
+	}
+}
+
+/** Opens a URL in the default browser. Silent if it can't. */
+export 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 {}
+}

package/src/commands/app.ts

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { chmod, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { defineCommand } from "citty";
+import { openBrowser } from "../ask.ts";
 import { loadConfig, saveConfig } from "../config.ts";
 import { UserError } from "../errors.ts";
 import { appKeyPath, appManifest, convertManifest } from "../github/app.ts";
@@ -11,18 +12,6 @@ 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. */
@@ -40,6 +29,77 @@ const page = (msg: string) =>
 		{ headers: { "content-type": "text/html" } },
 	);
 
+/** Creates a GitHub App in the browser and switches config to app mode. */
+export async function createApp(root: string, name?: string) {
+	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 appName = (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(appName, `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);
+}
+
 const create = defineCommand({
 	meta: {
 		name: "create",
@@ -53,74 +113,7 @@ const create = defineCommand({
 		},
 	},
 	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);
+		await createApp(process.cwd(), args.name);
 		console.log(
 			"\nThen commit .kanbot/config.yml, run `kanbot doctor` and restart the daemon.",
 		);

package/src/commands/board.ts

@@ -1,9 +1,16 @@
 import { defineCommand } from "citty";
-import { LABELS, loadConfig, saveConfig } from "../config.ts";
+import { type Config, LABELS, loadConfig, saveConfig } from "../config.ts";
 import { UserError } from "../errors.ts";
 import { ensureCopilotRuleset, ensureLabel } from "../github/api.ts";
 import { Gh } from "../github/gh.ts";
-import { createBoard, loadBoard, missingColumns } from "../github/project.ts";
+import {
+	type Board,
+	createBoard,
+	loadBoard,
+	missingColumns,
+	neededWorkflows,
+	workflowsUrl,
+} from "../github/project.ts";
 import { log } from "../log.ts";
 
 export const REPO_LABELS: [name: string, color: string, description: string][] =
@@ -55,6 +62,76 @@ export async function ensureLabels(gh: Gh) {
 		await ensureLabel(gh, name, color, description);
 }
 
+/**
+ * Creates the board (or keeps the configured one), labels and Copilot
+ * ruleset, then prints the workflows to turn on. Returns the board, or null
+ * if creation was skipped.
+ */
+export async function setupBoard(root: string, title?: string) {
+	const config = await loadConfig(root);
+	const gh = new Gh(config.repo);
+	if (config.project) {
+		log.info(
+			`Project already configured (${config.project.owner} #${config.project.number}); only ensuring labels.`,
+		);
+	} else {
+		const project = await createBoard(gh, config, title ?? gh.name);
+		if (!project) return null;
+		await saveConfig(root, {
+			project: { owner: project.owner, number: project.number },
+		});
+		log.info(`Created project ${project.url}`);
+	}
+	await ensureLabels(gh);
+	log.info(`Labels ensured: ${REPO_LABELS.map(([n]) => n).join(", ")}`);
+	if (config.review.copilot) {
+		await ensureCopilotRuleset(gh, config.review.copilotOnPush);
+		log.info("Copilot review ruleset ensured.");
+	}
+	const board = await loadBoard(gh, await loadConfig(root));
+	warnMissing(board);
+	printWorkflows(config, board);
+	return board;
+}
+
+/** Saves an existing project as the board and adds the labels. */
+export async function linkBoard(root: string, owner: string, number: number) {
+	await saveConfig(root, { project: { owner, number } });
+	const config = await loadConfig(root);
+	const gh = new Gh(config.repo);
+	const board = await loadBoard(gh, config);
+	await ensureLabels(gh);
+	log.info(`Linked ${board.url}`);
+	warnMissing(board);
+	return board;
+}
+
+function warnMissing(board: Board) {
+	const missing = missingColumns(board);
+	if (missing.length)
+		log.warn(
+			`Board is missing columns: ${missing.join(", ")} — add them to the Status field.`,
+		);
+}
+
+export function printWorkflows(config: Config, board: Board) {
+	const steps = neededWorkflows(config).map(
+		(w) => `  • ${w.name.padEnd(21)} → ${w.set}`,
+	);
+	console.log(`
+Turn on these built-in workflows. GitHub's API can't, so do it here:
+${workflowsUrl(board)}
+${steps.join("\n")}`);
+}
+
+/** Owner and number from a project URL like github.com/users/<owner>/projects/<n>. */
+export function parseProjectUrl(url: string) {
+	const m = url.match(
+		/github\.com\/(?:users|orgs)\/([^/\s]+)\/projects\/(\d+)/,
+	);
+	return m ? { owner: m[1] as string, number: Number(m[2]) } : null;
+}
+
 const create = defineCommand({
 	meta: {
 		name: "create",
@@ -68,40 +145,8 @@ const create = defineCommand({
 		},
 	},
 	async run({ args }) {
-		const root = process.cwd();
-		const config = await loadConfig(root);
-		const gh = new Gh(config.repo);
-		if (config.project) {
-			log.info(
-				`Project already configured (${config.project.owner} #${config.project.number}); only ensuring labels.`,
-			);
-		} else {
-			const project = await createBoard(gh, config, args.title ?? gh.name);
-			if (!project) return;
-			await saveConfig(root, {
-				project: { owner: project.owner, number: project.number },
-			});
-			log.info(`Created project ${project.url}`);
-		}
-		await ensureLabels(gh);
-		log.info(`Labels ensured: ${REPO_LABELS.map(([n]) => n).join(", ")}`);
-		if (config.review.copilot) {
-			await ensureCopilotRuleset(gh, config.review.copilotOnPush);
-			log.info("Copilot review ruleset ensured.");
-		}
-		const board = await loadBoard(gh, await loadConfig(root));
-		const missing = missingColumns(board);
-		if (missing.length)
-			log.warn(
-				`Board is missing columns: ${missing.join(", ")} — add them to the Status field.`,
-			);
-		console.log(`
-Enable these built-in project workflows (Project → ⋯ → Workflows), they can't be set via the API:
-  • Item closed           → set Status: ${config.columns.done}
-  • Pull request merged   → set Status: ${config.columns.done}
-  • Auto-add to project   → filter is:issue repo:${config.repo}   (new issues land in the board)
-  • Item added to project → set Status: ${config.columns.ideas}
-${board.url}`);
+		if (await setupBoard(process.cwd(), args.title))
+			console.log("Then run kanbot doctor.");
 	},
 });
 
@@ -120,24 +165,15 @@ const link = defineCommand({
 		number: { type: "string", required: true, description: "Project number" },
 	},
 	async run({ args }) {
-		const root = process.cwd();
 		const number = Number(args.number);
 		if (!Number.isInteger(number))
 			throw new UserError("--number must be a number.", {
 				why: "It's the number at the end of the project URL.",
 				docs: "getting-started#create-the-board",
 			});
-		await saveConfig(root, {
-			project: { owner: args.owner, number },
-		});
-		const config = await loadConfig(root);
-		const board = await loadBoard(new Gh(config.repo), config);
-		const missing = missingColumns(board);
-		log.info(
-			missing.length
-				? `Linked, but missing columns: ${missing.join(", ")}`
-				: `Linked ${board.url}`,
-		);
+		const config = await loadConfig(process.cwd());
+		const board = await linkBoard(process.cwd(), args.owner, number);
+		printWorkflows(config, board);
 	},
 });
 

package/src/commands/doctor.ts

@@ -15,7 +15,10 @@ import {
 	boardWorkflows,
 	loadBoard,
 	missingColumns,
+	neededWorkflows,
+	workflowsUrl,
 } from "../github/project.ts";
+import { LOGIN_FIX, providerLogin } from "../providers/login.ts";
 import {
 	codexSupports,
 	type McpServer,
@@ -171,27 +174,25 @@ export default defineCommand({
 			return summary(checks);
 		}
 
+		const login = await providerLogin(config.provider);
 		if (config.provider === "claude") {
 			section("Claude Code");
-			const s = await cmd(["claude", "auth", "status"]);
-			const sub = /"authMethod":\s*"claude\.ai"/.test(s.out);
 			add({
 				name: "claude CLI logged in with a subscription",
-				ok: s.ok && sub,
-				detail: sub ? undefined : "Not using a claude.ai login.",
+				ok: login.ok,
+				detail: login.installed ? login.detail : "claude is not installed.",
 				why: "Workers run `claude`. An API key login bills per token instead of your plan.",
-				fix: "claude auth login",
+				fix: LOGIN_FIX.claude,
 				docs: "providers#claude-code",
 			});
 		} else {
 			section("Codex");
-			const s = await cmd(["codex", "login", "status"]);
 			add({
 				name: "codex CLI logged in with ChatGPT",
-				ok: s.ok && /ChatGPT/i.test(s.out),
-				detail: s.out.split("\n")[0],
+				ok: login.ok,
+				detail: login.installed ? login.detail : "codex is not installed.",
 				why: "Workers run `codex` on your ChatGPT plan.",
-				fix: "codex login",
+				fix: LOGIN_FIX.codex,
 				docs: "providers#codex",
 			});
 			add({
@@ -402,16 +403,17 @@ export default defineCommand({
 			});
 			// Moving cards to Done on close/merge and adding new issues are left to GitHub.
 			const workflows = await boardWorkflows(gh, board);
-			for (const name of [
-				"Item closed",
-				"Pull request merged",
-				"Auto-add to project",
-			]) {
+			for (const w of neededWorkflows(config)) {
+				const on = workflows.some((x) => x.name === w.name && x.enabled);
 				add({
-					name: `board workflow "${name}" enabled`,
-					ok: workflows.some((w) => w.name === name && w.enabled),
-					why: "kanbot leaves adding new issues and moving closed ones to Done to GitHub.",
-					fix: `enable it in ${board.url} → ⋯ → Workflows`,
+					name: `board workflow "${w.name}" enabled`,
+					ok: on || !w.required,
+					warn: !on && !w.required,
+					why: w.required
+						? "kanbot leaves adding new issues and moving closed ones to Done to GitHub."
+						: `Without it, new issues land with no Status and kanbot ignores them until you set one.`,
+					fix: `open ${workflowsUrl(board)} → "${w.name}" → ${w.set} → turn it on`,
+					docs: "getting-started#create-the-board",
 				});
 			}
 		} catch (e) {