kanbot 0.0.0-stage → 0.2.0

package/src/agents/sync.ts

@@ -0,0 +1,219 @@
+import { existsSync, lstatSync } from "node:fs";
+import { mkdir, readdir, rm, symlink } from "node:fs/promises";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { configPath, loadConfig } from "../config.ts";
+import { UserError } from "../errors.ts";
+import type { AgentDef } from "./load.ts";
+
+/*
+ * .kanbot/agents/*.md is the single source of truth. This module renders it
+ * into each CLI's native format so agents work both headless (driven by the
+ * daemon) and in interactive sessions:
+ *   Claude: .claude/agents/<name>.md + .claude/settings.json permissions
+ *   Codex:  .codex/agents/<name>.toml
+ * Skills live in .agents/skills (Codex native); .claude/skills symlinks to it.
+ */
+
+export const GENERATED =
+	"generated by kanbot — edit .kanbot/agents/ and run `kanbot sync`";
+
+const CLAUDE_TOOLS: Record<string, string[]> = {
+	read: ["Read", "Grep", "Glob"],
+	edit: ["Edit", "Write", "NotebookEdit"],
+	bash: ["Bash"],
+	web: ["WebFetch", "WebSearch"],
+};
+
+/** Agents never touch GitHub; the daemon owns all remote side effects. */
+export const CLAUDE_DENY = [
+	"Bash(gh *)",
+	"Bash(git push *)",
+	"Bash(git remote *)",
+	"Bash(git config *)",
+];
+
+/** Agents act as the human's account: no Claude co-author trailers or PR footers. */
+export const CLAUDE_ATTRIBUTION = {
+	attribution: { commit: "", pr: "" },
+	includeCoAuthoredBy: false,
+};
+
+export function claudeTools(agent: AgentDef): string[] {
+	const tools = agent.tools.flatMap((t) => CLAUDE_TOOLS[t] ?? []);
+	if (agent.skills.length) tools.push("Skill");
+	if (agent.subagents.length) tools.push("Task");
+	return [...new Set(tools)];
+}
+
+export function renderClaudeAgent(agent: AgentDef): string {
+	const fm: Record<string, unknown> = {
+		name: agent.name,
+		description: agent.description,
+		tools: claudeTools(agent).join(", "),
+	};
+	if (agent.models.claude) fm.model = agent.models.claude;
+	if (agent.effort) fm.effort = agent.effort;
+	if (agent.skills.length) fm.skills = agent.skills;
+	return `---\n${stringify(fm).trim()}\n---\n<!-- ${GENERATED} -->\n\n${agentInstructions(agent)}\n`;
+}
+
+export function renderClaudeSettings(agents: AgentDef[]): string {
+	const allow = [...new Set(agents.flatMap(claudeTools))].sort();
+	return `${JSON.stringify(
+		{
+			$comment: GENERATED,
+			permissions: { allow, deny: CLAUDE_DENY },
+			...CLAUDE_ATTRIBUTION,
+		},
+		null,
+		2,
+	)}\n`;
+}
+
+const tomlString = (s: string) => JSON.stringify(s);
+
+export function renderCodexAgent(agent: AgentDef): string {
+	const lines = [
+		`# ${GENERATED}`,
+		`name = ${tomlString(agent.name)}`,
+		`description = ${tomlString(agent.description)}`,
+	];
+	if (agent.models.codex && agent.models.codex !== "default") {
+		lines.push(`model = ${tomlString(agent.models.codex)}`);
+	}
+	if (agent.effort) {
+		const effort = agent.effort === "max" ? "xhigh" : agent.effort;
+		lines.push(`model_reasoning_effort = ${tomlString(effort)}`);
+	}
+	lines.push(
+		`developer_instructions = ${tomlString(agentInstructions(agent))}`,
+	);
+	return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Body plus the parts of the frontmatter that a CLI can't express natively, so
+ * the agent knows which skills and helpers it is expected to use.
+ */
+export function agentInstructions(agent: AgentDef): string {
+	const extra: string[] = [];
+	if (agent.skills.length) {
+		extra.push(
+			`Skills to load when relevant: ${agent.skills.map((s) => `\`${s}\``).join(", ")}.`,
+		);
+	}
+	if (agent.subagents.length) {
+		extra.push(
+			`Subagents you can delegate to: ${agent.subagents.map((s) => `\`${s}\``).join(", ")}. Delegate focused, independent work to them; keep the final decisions yourself.`,
+		);
+	}
+	return extra.length
+		? `${agent.body}\n\n## Toolbox\n\n${extra.join("\n")}`
+		: agent.body;
+}
+
+export type SyncFile = { path: string; content: string };
+
+const COPILOT_INSTRUCTIONS = join(".github", "copilot-instructions.md");
+
+/** Points Copilot code review at the same rules the kanbot reviewers use. */
+export const renderCopilotInstructions =
+	() => `<!-- generated by kanbot from review.copilot in .kanbot/config.yml -->
+
+# Code review
+
+AI agents write most changes in this repo, from a plan in the linked issue. When you review a pull request:
+
+- Use the checklist and severity rubric in \`.agents/skills/code-review/SKILL.md\`.
+- Check the change against the plan in the linked issue and the PR description.
+- Hold it to \`AGENTS.md\`, \`.agents/skills/project-conventions/SKILL.md\` and the facts in \`.agents/skills/project-memory/\`.
+- Comment on real problems: bugs, missing tests, security, broken conventions. Leave style to the linter.
+`;
+
+export function renderAll(agents: AgentDef[]): SyncFile[] {
+	return [
+		...agents.map((a) => ({
+			path: join(".claude", "agents", `${a.name}.md`),
+			content: renderClaudeAgent(a),
+		})),
+		{
+			path: join(".claude", "settings.json"),
+			content: renderClaudeSettings(agents),
+		},
+		...agents.map((a) => ({
+			path: join(".codex", "agents", `${a.name}.toml`),
+			content: renderCodexAgent(a),
+		})),
+	];
+}
+
+/** Writes generated files. Returns paths whose content changed. */
+export async function sync(
+	root: string,
+	agents: AgentDef[],
+	{ check = false } = {},
+): Promise<string[]> {
+	const files = renderAll(agents);
+	const copilot =
+		existsSync(configPath(root)) && (await loadConfig(root)).review.copilot;
+	if (copilot)
+		files.push({
+			path: COPILOT_INSTRUCTIONS,
+			content: renderCopilotInstructions(),
+		});
+	const changed: string[] = [];
+	for (const f of files) {
+		const abs = join(root, f.path);
+		const existing = existsSync(abs) ? await Bun.file(abs).text() : null;
+		if (existing === f.content) continue;
+		changed.push(f.path);
+		if (!check) await Bun.write(abs, f.content);
+	}
+	// Remove generated agents whose source was deleted.
+	const keep = new Set(files.map((f) => f.path));
+	for (const [dir, ext] of [
+		[join(".claude", "agents"), ".md"],
+		[join(".codex", "agents"), ".toml"],
+	] as const) {
+		const abs = join(root, dir);
+		if (!existsSync(abs)) continue;
+		for (const name of await readdir(abs)) {
+			const rel = join(dir, name);
+			if (!name.endsWith(ext) || keep.has(rel)) continue;
+			const text = await Bun.file(join(abs, name)).text();
+			if (!text.includes(GENERATED)) continue;
+			changed.push(rel);
+			if (!check) await rm(join(abs, name));
+		}
+	}
+	const instructions = join(root, COPILOT_INSTRUCTIONS);
+	if (
+		!copilot &&
+		existsSync(instructions) &&
+		(await Bun.file(instructions).text()).includes("generated by kanbot")
+	) {
+		changed.push(COPILOT_INSTRUCTIONS);
+		if (!check) await rm(instructions);
+	}
+	if (!(await linkSkills(root, check))) changed.push(join(".claude", "skills"));
+	return changed;
+}
+
+/** Ensure .claude/skills -> ../.agents/skills. Returns true when already correct. */
+async function linkSkills(root: string, check: boolean) {
+	const link = join(root, ".claude", "skills");
+	const ok = existsSync(link) && lstatSync(link).isSymbolicLink();
+	if (ok || check) return ok;
+	if (existsSync(link)) {
+		throw new UserError("Cannot link .claude/skills.", {
+			why: ".claude/skills exists and is not a symlink. kanbot keeps skills in .agents/skills and links to them.",
+			fix: "Move its skills into .agents/skills, delete .claude/skills, then rerun.",
+			docs: "skills#add-a-skill",
+		});
+	}
+	await mkdir(join(root, ".agents", "skills"), { recursive: true });
+	await mkdir(join(root, ".claude"), { recursive: true });
+	await symlink(join("..", ".agents", "skills"), link);
+	return false;
+}

package/src/cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+import { runCommand, runMain } from "citty";
+import { formatError } from "./errors.ts";
+import { main } from "./main.ts";
+
+const args = process.argv.slice(2);
+const usage =
+	!args.length ||
+	args.some((a) => a === "--help" || a === "-h") ||
+	(args.length === 1 && (args[0] === "--version" || args[0] === "-v"));
+
+// citty prints usage for help, version and a bare `kanbot`.
+if (usage) {
+	await runMain(main);
+} else {
+	try {
+		await runCommand(main, { rawArgs: args });
+	} catch (e) {
+		// Leading positionals name the command, e.g. "board create".
+		const end = args.findIndex((a) => a.startsWith("-"));
+		const command = args.slice(0, end < 0 ? undefined : end).join(" ");
+		console.error(
+			formatError(e, { debug: !!process.env.KANBOT_DEBUG, command }),
+		);
+		process.exit(1);
+	}
+}

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,30 @@
+import { basename } from "node:path";
+import { defineCommand } from "citty";
+import { buildSpec, render, SHELLS, type Shell } from "../completion.ts";
+import { UserError } from "../errors.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 UserError("Could not detect your shell.", {
+				why: `$SHELL is "${shell}", which is not supported.`,
+				fix: `kanbot completion --shell ${SHELLS.join("|")}`,
+				docs: "getting-started#shell-completion",
+				more: "",
+			});
+		const { main } = await import("../main.ts");
+		process.stdout.write(render(shell as Shell, await buildSpec(main)));
+	},
+});

package/src/commands/doctor.ts

@@ -0,0 +1,260 @@
+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 { describeError } from "../errors.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() };
+}
+
+/** Failure detail and fix for a check, from a thrown error. */
+function explain(e: unknown, fallback?: string) {
+	const d = describeError(e);
+	const detail = [d.message, d.why].filter(Boolean).join("\n");
+	return {
+		detail: detail.replace(/\n/g, "\n    "),
+		fix: d.fix ?? fallback,
+	};
+}
+
+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, ...explain(e, "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, ...explain(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,
+				...explain(e, "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);
+	},
+});