kanbot 0.5.2 → 0.6.0

package/src/main.ts

@@ -17,6 +17,7 @@ export const main = defineCommand({
 		doctor: () => import("./commands/doctor.ts").then((m) => m.default),
 		run: () => import("./commands/run.ts").then((m) => m.default),
 		status: () => import("./commands/status.ts").then((m) => m.default),
+		report: () => import("./commands/report.ts").then((m) => m.default),
 		completion: () => import("./commands/completion.ts").then((m) => m.default),
 	},
 });

package/src/providers/login.ts

@@ -0,0 +1,46 @@
+import type { Config } from "../config.ts";
+
+export type Login = {
+	/** The CLI is on PATH. */
+	installed: boolean;
+	/** Logged in with a subscription, not an API key. */
+	ok: boolean;
+	detail?: string;
+};
+
+async function cmd(args: string[]) {
+	const p = Bun.spawn(args, { stdout: "pipe", stderr: "pipe" });
+	const [out, err, code] = await Promise.all([
+		new Response(p.stdout).text(),
+		new Response(p.stderr).text(),
+		p.exited,
+	]);
+	return { ok: code === 0, out: `${out}${err}`.trim() };
+}
+
+/** Whether the provider's CLI is installed and logged in with a subscription. */
+export async function providerLogin(
+	provider: Config["provider"],
+): Promise<Login> {
+	if (!Bun.which(provider)) return { installed: false, ok: false };
+	if (provider === "claude") {
+		const s = await cmd(["claude", "auth", "status"]);
+		const sub = /"authMethod":\s*"claude\.ai"/.test(s.out);
+		return {
+			installed: true,
+			ok: s.ok && sub,
+			detail: sub ? undefined : "Not using a claude.ai login.",
+		};
+	}
+	const s = await cmd(["codex", "login", "status"]);
+	return {
+		installed: true,
+		ok: s.ok && /ChatGPT/i.test(s.out),
+		detail: s.out.split("\n")[0],
+	};
+}
+
+export const LOGIN_FIX: Record<Config["provider"], string> = {
+	claude: "claude auth login",
+	codex: "codex login",
+};

package/src/report.ts

@@ -0,0 +1,245 @@
+import { UserError } from "./errors.ts";
+
+/** A PR or issue touched in the report period, with its comments. */
+export type Activity = {
+	kind: "pr" | "issue";
+	number: number;
+	title: string;
+	url: string;
+	/** PRs only. */
+	headRefName?: string;
+	createdAt: string;
+	mergedAt?: string | null;
+	comments: { body: string; createdAt: string }[];
+};
+
+/** The board right now, from the snapshot. */
+export type BoardNow = {
+	waiting: number;
+	limit: number | null;
+	needsHuman: number;
+	/** Open cards in Planning, Ready, In Progress or Review. */
+	active: number;
+};
+
+export type Loops = {
+	review: number;
+	ci: number;
+	conflict: number;
+	feedback: number;
+};
+
+export type Health = "ON_TRACK" | "AT_RISK" | "OFF_TRACK" | "INACTIVE";
+
+export type Report = {
+	since: string;
+	until: string;
+	merged: {
+		number: number;
+		title: string;
+		url: string;
+		cycleMs: number;
+		waitMs: number | null;
+	}[];
+	loops: Loops;
+	needsHuman: { number: number; url: string; reason: string }[];
+	now: BoardNow;
+	health: Health;
+	why: string[];
+	next: string[];
+};
+
+const LOOP_MARKERS: Record<keyof Loops, string> = {
+	review: "fixed",
+	ci: "ci",
+	conflict: "conflict",
+	feedback: "feedback-round",
+};
+
+/** True for `<!-- kanbot:kind -->` and `<!-- kanbot:kind:… -->`. */
+const has = (body: string, kind: string) =>
+	body.includes(`<!-- kanbot:${kind} `) ||
+	body.includes(`<!-- kanbot:${kind}:`);
+
+/** `7d`, `2w`, `12h` or `YYYY-MM-DD` → start of the period. */
+export function parseSince(value: string, now = Date.now()): Date {
+	const m = value.match(/^(\d+)([hdw])$/);
+	if (m) {
+		const hours = { h: 1, d: 24, w: 24 * 7 }[m[2] as "h" | "d" | "w"];
+		return new Date(now - Number(m[1]) * hours * 3_600_000);
+	}
+	if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+		const d = new Date(`${value}T00:00:00Z`);
+		if (!Number.isNaN(d.getTime())) return d;
+	}
+	throw new UserError(`Can't read --since "${value}".`, {
+		why: "Use a duration like 7d, 2w or 12h, or a date like 2026-10-01.",
+		fix: "kanbot report --since 7d",
+		more: "",
+	});
+}
+
+/** The reason line from a `needs-human` or `blocked` comment. */
+export function reasonOf(body: string): string {
+	const line =
+		body
+			.replace(/<sub>.*?<\/sub>/g, "")
+			.replace(/<!--.*?-->/g, "")
+			.replace(/^\s*\*\*[^*]+\*\*\s*/m, "")
+			.split("\n")
+			.map((l) => l.trim())
+			.find((l) => l && !l.startsWith("Remove `")) ?? "";
+	return line.length > 90 ? `${line.slice(0, 89)}…` : line || "no reason given";
+}
+
+export function median(xs: number[]): number | null {
+	if (!xs.length) return null;
+	const s = [...xs].sort((a, b) => a - b);
+	const mid = Math.floor(s.length / 2);
+	return s.length % 2
+		? (s[mid] as number)
+		: ((s[mid - 1] as number) + (s[mid] as number)) / 2;
+}
+
+/** Short duration like `45m`, `6h` or `2d 4h`. */
+export function duration(ms: number): string {
+	const m = Math.max(0, Math.floor(ms / 60_000));
+	if (m < 60) return `${m}m`;
+	const h = Math.floor(m / 60);
+	if (h < 24) return `${h}h`;
+	const d = Math.floor(h / 24);
+	return h % 24 ? `${d}d ${h % 24}h` : `${d}d`;
+}
+
+export function buildReport(
+	activity: Activity[],
+	now: BoardNow,
+	since: Date,
+	until = new Date(),
+): Report {
+	const inPeriod = (at: string) => Date.parse(at) >= since.getTime();
+	const loops: Loops = { review: 0, ci: 0, conflict: 0, feedback: 0 };
+	const merged: Report["merged"] = [];
+
+	for (const a of activity) {
+		if (a.kind !== "pr" || !a.headRefName?.startsWith("kanbot/")) continue;
+		if (!a.mergedAt || !inPeriod(a.mergedAt)) continue;
+		const mergedAt = Date.parse(a.mergedAt);
+		for (const c of a.comments)
+			for (const [k, kind] of Object.entries(LOOP_MARKERS))
+				if (has(c.body, kind)) loops[k as keyof Loops]++;
+		// The last "agent review complete" before merge starts the final wait.
+		const ready = a.comments
+			.filter(
+				(c) => has(c.body, "ready") && Date.parse(c.createdAt) <= mergedAt,
+			)
+			.at(-1);
+		merged.push({
+			number: a.number,
+			title: a.title,
+			url: a.url,
+			cycleMs: mergedAt - Date.parse(a.createdAt),
+			waitMs: ready ? mergedAt - Date.parse(ready.createdAt) : null,
+		});
+	}
+
+	const needsHuman = activity.flatMap((a) =>
+		a.comments
+			.filter(
+				(c) =>
+					inPeriod(c.createdAt) &&
+					(has(c.body, "needs-human") || has(c.body, "blocked")),
+			)
+			.map((c) => ({ number: a.number, url: a.url, reason: reasonOf(c.body) })),
+	);
+
+	const report = {
+		since: since.toISOString(),
+		until: until.toISOString(),
+		merged,
+		loops,
+		needsHuman,
+		now,
+	};
+	return { ...report, ...healthOf(report), next: nextSteps(report) };
+}
+
+type Base = Omit<Report, "health" | "why" | "next">;
+
+/** Board health from fixed rules, so it means the same every week. */
+export function healthOf(r: Base): { health: Health; why: string[] } {
+	const { now } = r;
+	if (!r.merged.length && !now.active)
+		return { health: "INACTIVE", why: ["Nothing merged and no active cards."] };
+	const why: string[] = [];
+	if (!r.merged.length && (now.waiting || now.needsHuman)) {
+		why.push(`Nothing merged, ${now.waiting} item(s) waiting on you.`);
+		return { health: "OFF_TRACK", why };
+	}
+	if (now.limit !== null && now.waiting >= now.limit)
+		why.push(`WIP limit reached (${now.waiting}/${now.limit}).`);
+	if (now.needsHuman)
+		why.push(`${now.needsHuman} card(s) labeled needs-human.`);
+	return { health: why.length ? "AT_RISK" : "ON_TRACK", why };
+}
+
+/** At most two concrete changes to try. */
+export function nextSteps(r: Base): string[] {
+	const out: string[] = [];
+	const n = r.merged.length;
+	const cycle = median(r.merged.map((m) => m.cycleMs));
+	const wait = median(
+		r.merged.flatMap((m) => (m.waitMs === null ? [] : [m.waitMs])),
+	);
+	if (r.now.needsHuman)
+		out.push("Clear needs-human cards: fix the cause, then remove the label.");
+	if (cycle && wait !== null && wait > cycle / 2)
+		out.push(
+			"Most cycle time is waiting on you. Run `kanbot status` and clear the queue.",
+		);
+	if (n && r.loops.ci > n)
+		out.push(
+			"CI fails often. Map a `verify` capability that runs the same checks.",
+		);
+	if (n && r.loops.review / n > 2)
+		out.push(
+			"Reviews often need fixes. Add what they catch to project-memory.",
+		);
+	if (n && r.loops.conflict / n > 1)
+		out.push(
+			"Conflicts are frequent. Lower `concurrency` or split cards smaller.",
+		);
+	return out.slice(0, 2);
+}
+
+const HEALTH_LABEL: Record<Health, string> = {
+	ON_TRACK: "On track",
+	AT_RISK: "At risk",
+	OFF_TRACK: "Off track",
+	INACTIVE: "Inactive",
+};
+
+/** Markdown for the terminal and for the board's status update. */
+export function renderReport(r: Report): string {
+	const day = (iso: string) => iso.slice(0, 10);
+	const med = (xs: number[]) => {
+		const m = median(xs);
+		return m === null ? "—" : duration(m);
+	};
+	const waits = r.merged.flatMap((m) => (m.waitMs === null ? [] : [m.waitMs]));
+	const { loops, now } = r;
+	const lines = [
+		`**${HEALTH_LABEL[r.health]}** · ${day(r.since)} → ${day(r.until)}`,
+		...r.why.map((w) => `> ${w}`),
+		"",
+		`- Merged: ${r.merged.length} PR(s)`,
+		`- Cycle, PR opened → merged: median ${med(r.merged.map((m) => m.cycleMs))}`,
+		`- Waiting on you, agent-reviewed → merged: median ${med(waits)}`,
+		`- Fix loops: ${loops.review} review, ${loops.ci} CI, ${loops.conflict} conflict, ${loops.feedback} feedback`,
+		`- Waiting on you now: ${now.waiting}${now.limit === null ? "" : ` of ${now.limit}`}`,
+		`- needs-human: ${r.needsHuman.length} this period`,
+		...r.needsHuman.slice(0, 5).map((h) => `  - #${h.number} ${h.reason}`),
+	];
+	if (r.next.length) lines.push("", "**Next**", ...r.next.map((s) => `- ${s}`));
+	return lines.join("\n");
+}

package/src/setup.ts

@@ -0,0 +1,170 @@
+import {
+	type Ask,
+	askNumber,
+	askText,
+	choose,
+	confirm,
+	type Say,
+} from "./ask.ts";
+import type { Config } from "./config.ts";
+import type { Login } from "./providers/login.ts";
+
+type Provider = Config["provider"];
+
+const loginHint = (l: Login) =>
+	l.ok ? "logged in" : l.installed ? "not logged in" : "not installed";
+
+/** Picks the provider, defaulting to the one that is logged in. */
+export function askProvider(
+	ask: Ask,
+	say: Say,
+	logins: Record<Provider, Login>,
+): Provider {
+	const def = !logins.claude.ok && logins.codex.ok ? 1 : 0;
+	return choose<Provider>(
+		ask,
+		say,
+		"Which agent CLI runs the workers?",
+		[
+			{
+				value: "claude",
+				label: "Claude Code",
+				hint: `Claude subscription, ${loginHint(logins.claude)}`,
+			},
+			{
+				value: "codex",
+				label: "Codex",
+				hint: `ChatGPT plan, ${loginHint(logins.codex)}`,
+			},
+		],
+		def,
+	);
+}
+
+export type Identity = Config["identity"]["mode"];
+
+export function askIdentity(ask: Ask, say: Say): Identity {
+	return choose<Identity>(ask, say, "Who should kanbot talk as on GitHub?", [
+		{
+			value: "user",
+			label: "You",
+			hint: "no setup; comments end with a 🤖 kanbot line",
+		},
+		{
+			value: "app",
+			label: "Its own bot",
+			hint: "creates a GitHub App; clear who said what, and you can approve its PRs",
+		},
+	]);
+}
+
+/** Merge on approval. Only useful when someone other than you can approve. */
+export function askMerge(
+	ask: Ask,
+	say: Say,
+	identity: Identity,
+): Partial<Config["merge"]> {
+	if (identity === "user")
+		say(
+			"  As you, kanbot's PRs are yours, so only another collaborator can approve them.",
+		);
+	return confirm(
+		ask,
+		"Merge a kanbot PR when it's approved and checks pass?",
+		identity === "app",
+	)
+		? { onApproval: true }
+		: {};
+}
+
+/** Config keys that differ from defaults. Fields left out keep defaults. */
+export type OptionsPatch = Partial<
+	Pick<Config, "concurrency" | "wip" | "notify" | "review" | "codex">
+>;
+
+/** Offers the defaults, and asks for each only if the user wants to change them. */
+export function askOptions(
+	ask: Ask,
+	say: Say,
+	provider: Provider,
+): OptionsPatch {
+	say("These defaults suit most repos:");
+	say("  3 agents at once");
+	say("  No limit on items waiting for you");
+	say("  Desktop notifications, no webhook");
+	say("  No Copilot review");
+	if (provider === "codex") say("  Codex workers have no network access");
+	if (!confirm(ask, "Change any of these?", false)) return {};
+
+	const patch: OptionsPatch = {};
+	const concurrency = askNumber(ask, say, "Agents at once?", 3) ?? 3;
+	if (concurrency !== 3) patch.concurrency = concurrency;
+
+	say(
+		"  New work pauses when this many PRs and plans wait on you. 5 suits one person.",
+	);
+	const wip = askNumber(ask, say, "Limit on items waiting for you?", null, {
+		none: "none",
+	});
+	if (wip !== null) patch.wip = { awaitingHuman: wip };
+
+	const webhook = askText(
+		ask,
+		say,
+		"Webhook for phone alerts, e.g. https://ntfy.sh/<topic> (Enter to skip):",
+		(s) => (URL.canParse(s) ? null : "Not a URL. Try again, or Enter to skip."),
+	);
+	if (webhook) patch.notify = { webhook } as Config["notify"];
+
+	if (
+		confirm(
+			ask,
+			"Have Copilot review PRs too? Needs a paid plan; each review uses credits.",
+			false,
+		)
+	)
+		patch.review = { copilot: true } as Config["review"];
+
+	if (
+		provider === "codex" &&
+		confirm(
+			ask,
+			"Let Codex workers reach the network (package installs)?",
+			false,
+		)
+	)
+		patch.codex = { networkAccess: true };
+	return patch;
+}
+
+export type BoardChoice =
+	| { kind: "create" }
+	| { kind: "link"; owner: string; number: number }
+	| { kind: "skip" };
+
+export function askBoard(
+	ask: Ask,
+	say: Say,
+	parse: (url: string) => { owner: string; number: number } | null,
+): BoardChoice {
+	const kind = choose<BoardChoice["kind"]>(
+		ask,
+		say,
+		"kanbot runs from a GitHub Project board with six columns.",
+		[
+			{ value: "create", label: "Create a new board", hint: "recommended" },
+			{ value: "link", label: "Use an existing board" },
+			{ value: "skip", label: "Skip", hint: "run `kanbot board create` later" },
+		],
+	);
+	if (kind !== "link") return { kind };
+	const url = askText(
+		ask,
+		say,
+		"Project URL (github.com/users/<owner>/projects/<n>):",
+		(s) =>
+			parse(s) ? null : "Not a project URL. Try again, or Enter to skip.",
+	);
+	const p = url ? parse(url) : null;
+	return p ? { kind, ...p } : { kind: "skip" };
+}

package/templates/.agents/skills/kanbot-guide/SKILL.md

@@ -43,11 +43,11 @@ Agents never get a GitHub token. The daemon does every comment, push and PR. Onl
 Go step by step. Run each command, check its output, then go on. If `.kanbot/config.yml` exists, run `kanbot doctor` first and skip what passes.
 
 1. **Requirements.** Bun 1.3+, `gh` logged in, `claude` or `codex` logged in with a subscription (not an API key). Run `gh auth refresh -s project`.
-2. **Provider.** Ask which subscription they have, then `bunx kanbot init --provider claude|codex` in the repo root.
+2. **Init.** Best: have them run `bunx kanbot init` in their own terminal. It asks for provider, identity, options, capabilities and the board. Without a terminal, ask which subscription they have and run `bunx kanbot init --yes --provider claude|codex`; then go on with the steps below.
 3. **Conventions.** Fill in `.agents/skills/project-conventions/SKILL.md` with them: stack, commands to test, lint and typecheck. Adjust `.github/workflows/ci.yml` to run the same. Every agent reads this first. Draft it from manifests and CI, ask what you can't find, and have them run each command. Link `project-conventions`.
 4. **Capabilities.** kanbot runs the process; the repo's own skills and agents do the work. Ask which skills they have for proving acceptance criteria (`verify`), technical review (`review`) and something a human can try (`preview`), and map them under `capabilities` in `.kanbot/config.yml`. See [Capabilities](#capabilities).
-5. **Board.** `kanbot board create`, or `kanbot board link --owner <login> --number <n>` for an existing project. Have them enable the four built-in project workflows it prints; they can't be set through the API.
-6. **Options.** Go through [Choose options](#choose-options). For app mode, run `kanbot app create` and have them install the app on the repo.
+5. **Board.** Skip if `init` made one. Otherwise `kanbot board create`, or `kanbot board link --owner <login> --number <n>` for an existing project. Have them enable the four built-in project workflows it prints; they can't be set through the API.
+6. **Options.** Skip what `init` asked. Otherwise go through [Choose options](#choose-options). For app mode, run `kanbot app create` and have them install the app on the repo.
 7. **Commit and push** the kanbot files. Agents only see what's on the pushed base branch.
 8. **Check.** `kanbot doctor` until it passes, then `kanbot run --once --dry-run`, then `kanbot run`.
 9. **First card.** Have them write an issue, put it in Planning and read the plan. Point to `workflow`.
@@ -69,16 +69,17 @@ capabilities:
 
 Ask only about what matters to them. Defaults are fine for the rest. Options live in `.kanbot/config.yml`; restart the daemon after changes.
 
-| Option                             | Ask                                                       | Recommend                                                                                                                       |
-| ---------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `identity.mode` (`user` \| `app`)  | Should kanbot talk as you, or as its own bot?             | `app`: clear who said what, GitHub notifies you, and you can approve its PRs. `user` for zero setup. Commits are yours in both. |
-| `merge.onApproval`, `merge.method` | Merge by approving the PR, or press merge yourself?       | `true` with `app` mode. In `user` mode only another collaborator can approve.                                                   |
-| `provider`                         | Claude or ChatGPT subscription?                           | Whichever they pay for.                                                                                                         |
-| `concurrency`                      | How many agents at once?                                  | Default 3. Lower on a small machine or near usage limits.                                                                       |
-| `review.copilot`                   | Want GitHub Copilot as an extra reviewer? (costs credits) | Off unless they have a paid Copilot plan.                                                                                       |
-| `notify.desktop`, `notify.webhook` | Where do you want to hear that a PR is ready?             | Desktop. Add an ntfy.sh webhook for phone alerts.                                                                               |
-| `codex.networkAccess`              | Do agents need to install packages? (Codex only)          | Off unless installs fail.                                                                                                       |
-| `explore:N` label                  | Want several approaches built for some issues?            | Per issue, not config.                                                                                                          |
+| Option                             | Ask                                                                  | Recommend                                                                                                                       |
+| ---------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `identity.mode` (`user` \| `app`)  | Should kanbot talk as you, or as its own bot?                        | `app`: clear who said what, GitHub notifies you, and you can approve its PRs. `user` for zero setup. Commits are yours in both. |
+| `merge.onApproval`, `merge.method` | Merge by approving the PR, or press merge yourself?                  | `true` with `app` mode. In `user` mode only another collaborator can approve.                                                   |
+| `provider`                         | Claude or ChatGPT subscription?                                      | Whichever they pay for.                                                                                                         |
+| `concurrency`                      | How many agents at once?                                             | Default 3. Lower on a small machine or near usage limits.                                                                       |
+| `wip.awaitingHuman`                | How many items can wait on you before agents stop starting new work? | 5 for a solo builder. Off (`null`) by default. Optional: same limit on the board's Review column (column menu → Set limit).     |
+| `review.copilot`                   | Want GitHub Copilot as an extra reviewer? (costs credits)            | Off unless they have a paid Copilot plan.                                                                                       |
+| `notify.desktop`, `notify.webhook` | Where do you want to hear that a PR is ready?                        | Desktop. Add an ntfy.sh webhook for phone alerts.                                                                               |
+| `codex.networkAccess`              | Do agents need to install packages? (Codex only)                     | Off unless installs fail.                                                                                                       |
+| `explore:N` label                  | Want several approaches built for some issues?                       | Per issue, not config.                                                                                                          |
 
 ### Who does what
 
@@ -105,8 +106,9 @@ Warn: never enable the branch rule "Require approval of the most recent reviewab
 
 1. `kanbot doctor`: prints a fix for each failed check.
 2. `kanbot status`: board by column, what waits on the user (oldest first), daemon, failures, rate-limit pause.
-3. `.kanbot/logs/*.jsonl`: full agent transcripts.
-4. `needs-human` label: the issue has a comment saying why. Fix the cause, then remove the label to retry.
-5. Nothing happens: is the daemon running, are kanbot files pushed to the base branch, is the card in an active column?
-6. Card stays in Ready: the plan has open questions, or the issue is blocked by open issues. kanbot commented why. Answer questions in Planning; blocked cards start when the blockers close.
-7. Agent didn't use a skill: is it mapped under `capabilities`, does its `when` fit, and is it committed?
+3. `kanbot report`: merged PRs, cycle time, wait on the user, fix loops and `needs-human` causes for the last 7 days. `--post` adds it to the board's Status updates.
+4. `.kanbot/logs/*.jsonl`: full agent transcripts.
+5. `needs-human` label: the issue has a comment saying why. Fix the cause, then remove the label to retry.
+6. Nothing happens: is the daemon running, are kanbot files pushed to the base branch, is the card in an active column?
+7. Card stays in Ready: the plan has open questions, or the issue is blocked by open issues. kanbot commented why. Answer questions in Planning; blocked cards start when the blockers close.
+8. Agent didn't use a skill: is it mapped under `capabilities`, does its `when` fit, and is it committed?