kanbot 0.0.0-stage → 0.1.0

package/src/cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { runMain } from "citty";
+import { main } from "./main.ts";
+
+runMain(main);

package/src/commands/board.ts

@@ -0,0 +1,140 @@
+import { defineCommand } from "citty";
+import { LABELS, loadConfig, saveConfig } from "../config.ts";
+import { ensureCopilotRuleset, ensureLabel } from "../github/api.ts";
+import { Gh } from "../github/gh.ts";
+import { createBoard, loadBoard, missingColumns } from "../github/project.ts";
+import { log } from "../log.ts";
+
+export const REPO_LABELS: [name: string, color: string, description: string][] =
+	[
+		[
+			LABELS.technical,
+			"5319e7",
+			"Technical work; planned as a technical goal instead of a user story",
+		],
+		["type:frontend", "1d76db", "User-facing UI work"],
+		["type:backend", "0e8a16", "Server, data or API work"],
+		["type:docs", "c5def5", "Documentation"],
+		["type:infra", "bfd4f2", "Tooling, CI, infrastructure"],
+		[
+			"explore:2",
+			"fbca04",
+			"Implement 2 alternative approaches as separate PRs",
+		],
+		[
+			"explore:3",
+			"fbca04",
+			"Implement 3 alternative approaches as separate PRs",
+		],
+		[
+			"explore:4",
+			"fbca04",
+			"Implement 4 alternative approaches as separate PRs",
+		],
+		[LABELS.working, "ededed", "An kanbot agent is working on this"],
+		[
+			LABELS.review,
+			"5319e7",
+			"Have kanbot agents review this PR, without a board card",
+		],
+		[
+			LABELS.agentReviewed,
+			"0e8a16",
+			"Passed both agent review passes; ready for human testing",
+		],
+		[
+			LABELS.needsHuman,
+			"d93f0b",
+			"Agents stopped; remove the label to let them retry",
+		],
+		["variant:1", "f9d0c4", "Exploratory approach 1"],
+		["variant:2", "f9d0c4", "Exploratory approach 2"],
+		["variant:3", "f9d0c4", "Exploratory approach 3"],
+		["variant:4", "f9d0c4", "Exploratory approach 4"],
+	];
+
+export async function ensureLabels(gh: Gh) {
+	for (const [name, color, description] of REPO_LABELS)
+		await ensureLabel(gh, name, color, description);
+}
+
+const create = defineCommand({
+	meta: {
+		name: "create",
+		description:
+			"Create a GitHub Project board for this repo with the kanbot columns",
+	},
+	args: {
+		title: {
+			type: "string",
+			description: "Project title (default: repo name)",
+		},
+	},
+	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}`);
+	},
+});
+
+const link = defineCommand({
+	meta: { name: "link", description: "Use an existing project board" },
+	args: {
+		owner: {
+			type: "string",
+			required: true,
+			description: "User or org login that owns the project",
+		},
+		number: { type: "string", required: true, description: "Project number" },
+	},
+	async run({ args }) {
+		const root = process.cwd();
+		await saveConfig(root, {
+			project: { owner: args.owner, number: Number(args.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}`,
+		);
+	},
+});
+
+export default defineCommand({
+	meta: { name: "board", description: "Manage the GitHub Project board" },
+	subCommands: { create, link },
+});

package/src/commands/completion.ts

@@ -0,0 +1,24 @@
+import { basename } from "node:path";
+import { defineCommand } from "citty";
+import { buildSpec, render, SHELLS, type Shell } from "../completion.ts";
+
+export default defineCommand({
+	meta: {
+		name: "completion",
+		description: "Print a shell completion script (zsh, bash or fish)",
+	},
+	args: {
+		shell: {
+			type: "enum",
+			options: [...SHELLS],
+			description: "Target shell (default: $SHELL)",
+		},
+	},
+	async run({ args }) {
+		const shell = args.shell ?? basename(process.env.SHELL ?? "");
+		if (!SHELLS.includes(shell as Shell))
+			throw new Error(`Pass --shell ${SHELLS.join("|")}`);
+		const { main } = await import("../main.ts");
+		process.stdout.write(render(shell as Shell, await buildSpec(main)));
+	},
+});

package/src/commands/doctor.ts

@@ -0,0 +1,250 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { defineCommand } from "citty";
+import { loadAgents } from "../agents/load.ts";
+import { sync } from "../agents/sync.ts";
+import { loadConfig, writeConfigSchema } from "../config.ts";
+import { git } from "../daemon/git.ts";
+import { copilotReviewRule } from "../github/api.ts";
+import { Gh, run } from "../github/gh.ts";
+import {
+	boardWorkflows,
+	loadBoard,
+	missingColumns,
+} from "../github/project.ts";
+import { NEW_SUFFIX, pendingMerges, planUpgrade } from "../templates.ts";
+import { REPO_LABELS } from "./board.ts";
+
+type Check = { name: string; ok: boolean; detail?: string; fix?: 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() };
+}
+
+export default defineCommand({
+	meta: {
+		name: "doctor",
+		description: "Check that everything kanbot needs is in place",
+	},
+	async run() {
+		const root = process.cwd();
+		const checks: Check[] = [];
+		const add = (c: Check) => {
+			checks.push(c);
+			console.log(
+				`${c.ok ? "✔" : "✖"} ${c.name}${c.detail ? ` — ${c.detail}` : ""}${!c.ok && c.fix ? `\n    fix: ${c.fix}` : ""}`,
+			);
+		};
+
+		const auth = await cmd(["gh", "auth", "status"]);
+		add({ name: "gh logged in", ok: auth.ok, fix: "gh auth login" });
+		add({
+			name: "gh token has project scope",
+			ok: /'project'/.test(auth.out),
+			fix: "gh auth refresh -s project",
+		});
+
+		let config: Awaited<ReturnType<typeof loadConfig>>;
+		try {
+			config = await loadConfig(root);
+			add({
+				name: "config",
+				ok: true,
+				detail: `${config.repo}, provider ${config.provider}`,
+			});
+		} catch (e) {
+			add({ name: "config", ok: false, detail: String(e), fix: "kanbot init" });
+			return process.exit(1);
+		}
+
+		if (config.provider === "claude") {
+			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 (would bill API usage)",
+				fix: "claude auth login",
+			});
+		} else {
+			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],
+				fix: "codex login",
+			});
+		}
+
+		try {
+			const agents = await loadAgents(root);
+			add({
+				name: "agents",
+				ok: true,
+				detail: `${agents.filter((a) => a.tier === "column").length} column, ${agents.filter((a) => a.tier === "sub").length} sub`,
+			});
+			const needed = [
+				"planner",
+				"reviewer-code",
+				"reviewer-spec",
+				"fixer",
+				...Object.values(config.implementers),
+			];
+			const missing = [...new Set(needed)].filter(
+				(n) => !agents.some((a) => a.name === n),
+			);
+			add({
+				name: "agents referenced by config exist",
+				ok: !missing.length,
+				detail: missing.join(", ") || undefined,
+			});
+			const stale = await sync(root, agents, { check: true });
+			add({
+				name: "generated agent files up to date",
+				ok: !stale.length,
+				detail: stale.join(", ") || undefined,
+				fix: "kanbot sync",
+			});
+			add({
+				name: "config schema up to date",
+				ok: !(await writeConfigSchema(root, { check: true })),
+				fix: "kanbot sync",
+			});
+		} catch (e) {
+			add({ name: "agents", ok: false, detail: String(e) });
+		}
+
+		const plan = await planUpgrade(root);
+		const behind = plan.changes.filter((c) =>
+			["add", "update", "conflict"].includes(c.action),
+		);
+		add({
+			name: "templates up to date",
+			ok: !behind.length,
+			detail: behind.length
+				? `${behind.length} file(s) differ from this kanbot version`
+				: undefined,
+			fix: "kanbot upgrade",
+		});
+		const merges = await pendingMerges(root);
+		add({
+			name: `no unmerged ${NEW_SUFFIX} files`,
+			ok: !merges.length,
+			detail: merges.join(", ") || undefined,
+			fix: `merge each into the file next to it and delete it (kanbot-admin skill can help)`,
+		});
+
+		await git(root, "fetch", "origin", config.baseBranch).catch(() => {});
+		const tree = await git(
+			root,
+			"ls-tree",
+			"-r",
+			"--name-only",
+			`origin/${config.baseBranch}`,
+		).catch(() => "");
+		for (const path of [
+			".agents/skills/",
+			".claude/agents/",
+			".codex/agents/",
+			"AGENTS.md",
+		]) {
+			add({
+				name: `${path} committed on origin/${config.baseBranch}`,
+				ok: tree.split("\n").some((f) => f.startsWith(path)),
+				detail: "worktrees are created from the base branch",
+				fix: "commit and push the kanbot files",
+			});
+		}
+		add({
+			name: ".github/workflows/kanbot-merged.yml",
+			ok: existsSync(join(root, ".github/workflows/kanbot-merged.yml")),
+		});
+
+		const gh = new Gh(config.repo);
+		try {
+			const board = await loadBoard(gh, config);
+			const missing = missingColumns(board);
+			add({
+				name: "project board",
+				ok: !missing.length,
+				detail: missing.length
+					? `missing columns: ${missing.join(", ")}`
+					: board.url,
+				fix: "kanbot board create",
+			});
+			// 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",
+			]) {
+				add({
+					name: `board workflow "${name}" enabled`,
+					ok: workflows.some((w) => w.name === name && w.enabled),
+					fix: `enable it in ${board.url} → ⋯ → Workflows`,
+				});
+			}
+		} catch (e) {
+			add({
+				name: "project board",
+				ok: false,
+				detail: String(e),
+				fix: "kanbot board create",
+			});
+		}
+
+		const labels = (
+			JSON.parse(
+				await run([
+					"label",
+					"list",
+					"--repo",
+					config.repo,
+					"--limit",
+					"200",
+					"--json",
+					"name",
+				]),
+			) as { name: string }[]
+		).map((l) => l.name);
+		const missingLabels = REPO_LABELS.map(([n]) => n).filter(
+			(n) => !labels.includes(n),
+		);
+		add({
+			name: "labels",
+			ok: !missingLabels.length,
+			detail: missingLabels.join(", ") || undefined,
+			fix: "kanbot board create",
+		});
+
+		if (config.review.copilot) {
+			const rule = await copilotReviewRule(gh, config.baseBranch).catch(
+				() => null,
+			);
+			add({
+				name: "Copilot review requested on PRs",
+				ok: rule !== null,
+				detail: rule
+					? `re-review on push: ${rule.parameters?.review_on_push ? "on" : "off"}`
+					: "review.copilot is on, but no ruleset requests Copilot review",
+				fix: "kanbot board create",
+			});
+			add({
+				name: ".github/copilot-instructions.md committed",
+				ok: tree.split("\n").includes(".github/copilot-instructions.md"),
+				fix: "kanbot sync, then commit and push",
+			});
+		}
+
+		if (checks.some((c) => !c.ok)) process.exit(1);
+	},
+});

package/src/commands/init.ts

@@ -0,0 +1,102 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { defineCommand } from "citty";
+import { loadAgents } from "../agents/load.ts";
+import { sync } from "../agents/sync.ts";
+import { configPath, saveConfig, writeConfigSchema } from "../config.ts";
+import { run } from "../github/gh.ts";
+import { log } from "../log.ts";
+import { applyUpgrade, NEW_SUFFIX, planUpgrade } from "../templates.ts";
+
+const GITIGNORE = [".kanbot/state.json", ".kanbot/logs/", ".kanbot/daemon.pid"];
+
+export default defineCommand({
+	meta: {
+		name: "init",
+		description:
+			"Scaffold kanbot agents, skills and GitHub files into this repo",
+	},
+	args: {
+		provider: {
+			type: "enum",
+			options: ["claude", "codex"],
+			description: "Agent provider",
+			default: "claude",
+		},
+		force: {
+			type: "boolean",
+			description: "Overwrite existing files, including your edits",
+			default: false,
+		},
+	},
+	async run({ args }) {
+		const root = process.cwd();
+		if (!existsSync(join(root, ".git")))
+			throw new Error("Run inside a git repository.");
+		if (!["claude", "codex"].includes(args.provider))
+			throw new Error("--provider must be claude or codex");
+
+		const plan = await planUpgrade(root, { force: args.force });
+		await applyUpgrade(root, plan);
+		for (const c of plan.changes) {
+			if (c.action === "add" || c.action === "update") log.info(`+ ${c.path}`);
+			if (c.action === "conflict")
+				log.warn(
+					`! ${c.path} exists; kanbot's version is in ${c.path}${NEW_SUFFIX}`,
+				);
+		}
+		log.info("+ .kanbot/manifest.json");
+
+		if (!existsSync(configPath(root)) || args.force) {
+			const repo = JSON.parse(
+				await run(["repo", "view", "--json", "nameWithOwner,defaultBranchRef"]),
+			) as {
+				nameWithOwner: string;
+				defaultBranchRef: { name: string };
+			};
+			await saveConfig(root, {
+				provider: args.provider as "claude" | "codex",
+				repo: repo.nameWithOwner,
+				baseBranch: repo.defaultBranchRef.name,
+			});
+			log.info(
+				`+ .kanbot/config.yml (${repo.nameWithOwner}, base ${repo.defaultBranchRef.name})`,
+			);
+		}
+
+		const codeowners = join(root, ".github", "CODEOWNERS");
+		if (!existsSync(codeowners)) {
+			const login = (await run(["api", "user", "--jq", ".login"])).trim();
+			await Bun.write(
+				codeowners,
+				`# Human reviewers. kanbot acts as your account, so this documents ownership\n# rather than triggering review requests for your own PRs.\n* @${login}\n`,
+			);
+			log.info(`+ .github/CODEOWNERS (@${login})`);
+		}
+
+		await appendGitignore(root);
+		const changed = await sync(root, await loadAgents(root));
+		if (await writeConfigSchema(root))
+			changed.push(".kanbot/config.schema.json");
+		for (const f of changed) log.info(`~ ${f} (generated)`);
+
+		console.log(`
+Next steps:
+  1. Review AGENTS.md and fill in .agents/skills/project-conventions/SKILL.md
+  2. Adjust .github/workflows/ci.yml to your stack (agents fix failing CI)
+  3. kanbot board create        # creates the project board and labels
+  4. kanbot doctor              # checks auth, board, generated files
+  5. Commit and push these files to the default branch (agents work from it)
+  6. kanbot run                 # start the loop (or kanbot run --once --dry-run)`);
+	},
+});
+
+async function appendGitignore(root: string) {
+	const path = join(root, ".gitignore");
+	const current = existsSync(path) ? await Bun.file(path).text() : "";
+	const missing = GITIGNORE.filter((l) => !current.split("\n").includes(l));
+	if (!missing.length) return;
+	const sep = current && !current.endsWith("\n") ? "\n" : "";
+	await Bun.write(path, `${current}${sep}\n# kanbot\n${missing.join("\n")}\n`);
+	log.info("~ .gitignore");
+}

package/src/commands/run.ts

@@ -0,0 +1,32 @@
+import { defineCommand } from "citty";
+import { runDaemon } from "../daemon/loop.ts";
+import { log } from "../log.ts";
+
+export default defineCommand({
+	meta: { name: "run", description: "Run the kanbot loop for this repo" },
+	args: {
+		once: {
+			type: "boolean",
+			description: "Run a single tick, wait for its jobs, exit",
+			default: false,
+		},
+		"dry-run": {
+			type: "boolean",
+			description: "Print what would happen; change nothing",
+			default: false,
+		},
+		verbose: {
+			type: "boolean",
+			alias: "v",
+			description: "Verbose logging",
+			default: false,
+		},
+	},
+	async run({ args }) {
+		log.verbose = args.verbose;
+		await runDaemon(process.cwd(), {
+			once: args.once || args["dry-run"],
+			dryRun: args["dry-run"],
+		});
+	},
+});

package/src/commands/skills.ts

@@ -0,0 +1,63 @@
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { defineCommand } from "citty";
+import { log } from "../log.ts";
+import { listTemplates } from "../templates.ts";
+
+/** Skills that work outside a kanbot repo, so they can be installed per user. */
+export const GLOBAL_SKILLS = ["kanbot-idea"];
+
+/** User-level skill folders: Claude Code reads the first, Codex the second. */
+export const globalSkillDirs = (home = homedir()) => ({
+	claude: join(home, ".claude", "skills"),
+	codex: join(home, ".agents", "skills"),
+});
+
+export async function installGlobal(
+	providers: ("claude" | "codex")[],
+	home = homedir(),
+) {
+	const dirs = globalSkillDirs(home);
+	const templates = await listTemplates();
+	const written: string[] = [];
+	for (const [path, content] of templates) {
+		const m = path.match(/^\.agents\/skills\/([^/]+)\/(.+)$/);
+		if (!m?.[1] || !m[2] || !GLOBAL_SKILLS.includes(m[1])) continue;
+		for (const p of providers) {
+			const to = join(dirs[p], m[1], m[2]);
+			await mkdir(dirname(to), { recursive: true });
+			await Bun.write(to, content);
+			written.push(to);
+		}
+	}
+	return written;
+}
+
+const install = defineCommand({
+	meta: {
+		name: "install",
+		description: `Install ${GLOBAL_SKILLS.join(", ")} for your user, to use from any directory`,
+	},
+	args: {
+		provider: {
+			type: "enum",
+			options: ["claude", "codex", "both"],
+			description: "Which agent CLI to install for",
+			default: "both",
+		},
+	},
+	async run({ args }) {
+		const providers =
+			args.provider === "both"
+				? (["claude", "codex"] as const)
+				: [args.provider as "claude" | "codex"];
+		for (const f of await installGlobal([...providers])) log.info(`+ ${f}`);
+		log.info("Rerun after upgrading kanbot to get the latest version.");
+	},
+});
+
+export default defineCommand({
+	meta: { name: "skills", description: "Manage kanbot skills" },
+	subCommands: { install },
+});

package/src/commands/status.ts

@@ -0,0 +1,61 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { defineCommand } from "citty";
+import { COLUMN_KEYS, LABELS, loadConfig } from "../config.ts";
+import { State } from "../daemon/state.ts";
+import { Gh } from "../github/gh.ts";
+import { listItems, loadBoard } from "../github/project.ts";
+
+export default defineCommand({
+	meta: {
+		name: "status",
+		description: "Show board columns, daemon state and failures",
+	},
+	async run() {
+		const root = process.cwd();
+		const config = await loadConfig(root);
+		const gh = new Gh(config.repo);
+		const board = await loadBoard(gh, config);
+		const items = await listItems(gh, board);
+
+		const pidFile = join(root, ".kanbot", "daemon.pid");
+		const pid = existsSync(pidFile)
+			? (await Bun.file(pidFile).text()).trim()
+			: null;
+		console.log(
+			`${config.repo} · ${board.url}\ndaemon: ${pid ? `pid ${pid}` : "not running"} · provider ${config.provider}\n`,
+		);
+
+		for (const key of COLUMN_KEYS) {
+			const inCol = items.filter(
+				(i) => i.column === key && (key === "done" || i.state === "OPEN"),
+			);
+			const shown =
+				key === "done"
+					? `${inCol.length}`
+					: inCol.map((i) => `#${i.number}`).join(" ") || "—";
+			console.log(`${config.columns[key].padEnd(12)} ${shown}`);
+		}
+
+		const needsHuman = JSON.parse(
+			await Bun.$`gh issue list --repo ${config.repo} --label ${LABELS.needsHuman} --json number,title`.text(),
+		) as { number: number; title: string }[];
+		if (needsHuman.length) {
+			console.log(
+				`\nneeds-human:\n${needsHuman.map((i) => `  #${i.number} ${i.title}`).join("\n")}`,
+			);
+		}
+
+		const state = await new State(root).load();
+		if (state.failures.size) {
+			console.log(
+				`\nfailures:\n${[...state.failures].map(([k, n]) => `  ${k}: ${n}`).join("\n")}`,
+			);
+		}
+		if (state.pausedUntil > Date.now()) {
+			console.log(
+				`\npaused (rate limit) until ${new Date(state.pausedUntil).toLocaleString()}`,
+			);
+		}
+	},
+});