kanbot 0.0.0-stage → 0.1.0

package/src/commands/sync.ts

@@ -0,0 +1,31 @@
+import { defineCommand } from "citty";
+import { loadAgents } from "../agents/load.ts";
+import { sync } from "../agents/sync.ts";
+import { writeConfigSchema } from "../config.ts";
+import { log } from "../log.ts";
+
+export default defineCommand({
+	meta: {
+		name: "sync",
+		description:
+			"Generate .claude/agents, .codex/agents, permissions and the config schema",
+	},
+	args: {
+		check: {
+			type: "boolean",
+			description: "Exit 1 if generated files are stale",
+			default: false,
+		},
+	},
+	async run({ args }) {
+		const root = process.cwd();
+		const changed = await sync(root, await loadAgents(root), {
+			check: args.check,
+		});
+		if (await writeConfigSchema(root, { check: args.check }))
+			changed.push(".kanbot/config.schema.json");
+		if (!changed.length) return log.info("Generated files are up to date.");
+		for (const f of changed) log.info(`${args.check ? "stale" : "wrote"} ${f}`);
+		if (args.check) process.exit(1);
+	},
+});

package/src/commands/upgrade.ts

@@ -0,0 +1,70 @@
+import { defineCommand } from "citty";
+import pkg from "../../package.json" with { type: "json" };
+import { loadAgents } from "../agents/load.ts";
+import { sync } from "../agents/sync.ts";
+import { writeConfigSchema } from "../config.ts";
+import { log } from "../log.ts";
+import {
+	applyUpgrade,
+	type Change,
+	NEW_SUFFIX,
+	planUpgrade,
+	readManifest,
+} from "../templates.ts";
+
+const HEADINGS: Record<Change["action"], string> = {
+	add: "Added",
+	update: "Updated",
+	conflict: `You edited these; kanbot's new version is next to each as *${NEW_SUFFIX}`,
+	deleted: "You deleted these; left out",
+	removed: "No longer shipped by kanbot; left in place",
+};
+
+export default defineCommand({
+	meta: {
+		name: "upgrade",
+		description:
+			"Update kanbot's agents, skills and workflows in this repo, keeping your edits",
+	},
+	args: {
+		"dry-run": {
+			type: "boolean",
+			description: "Show what would change without writing",
+			default: false,
+		},
+	},
+	async run({ args }) {
+		const root = process.cwd();
+		const from = (await readManifest(root))?.version ?? "no manifest";
+		const plan = await planUpgrade(root);
+		log.info(`kanbot ${from} → ${pkg.version}`);
+		for (const action of Object.keys(HEADINGS) as Change["action"][]) {
+			const paths = plan.changes
+				.filter((c) => c.action === action)
+				.map((c) => c.path);
+			if (paths.length)
+				console.log(
+					`\n${HEADINGS[action]}:\n${paths.map((p) => `  ${p}`).join("\n")}`,
+				);
+		}
+		if (!plan.changes.length) log.info("Templates are up to date.");
+		if (args["dry-run"]) return;
+
+		await applyUpgrade(root, plan);
+		const generated = await sync(root, await loadAgents(root));
+		if (await writeConfigSchema(root))
+			generated.push(".kanbot/config.schema.json");
+		for (const f of generated) log.info(`~ ${f} (generated)`);
+
+		const conflicts = plan.changes.some((c) => c.action === "conflict");
+		console.log(`
+Next steps:
+  ${
+		conflicts
+			? `1. Merge each *${NEW_SUFFIX} file into the file next to it, then delete it.
+     Ask your agent: "use kanbot-admin to merge the kanbot upgrade".
+  2. `
+			: "1. "
+	}Review the diff and commit. Changes are not committed for you.`);
+	},
+});

package/src/completion.ts

@@ -0,0 +1,217 @@
+import type { ArgsDef, CommandDef, Resolvable } from "citty";
+
+export const SHELLS = ["zsh", "bash", "fish"] as const;
+export type Shell = (typeof SHELLS)[number];
+
+type Flag = {
+	name: string;
+	alias: string[];
+	description: string;
+	takesValue: boolean;
+	options: string[];
+};
+
+export type Spec = {
+	name: string;
+	description: string;
+	flags: Flag[];
+	subs: Spec[];
+};
+
+async function resolve<T>(
+	v: Resolvable<T> | undefined,
+): Promise<T | undefined> {
+	return typeof v === "function" ? (v as () => T | Promise<T>)() : v;
+}
+
+const HELP: Flag = {
+	name: "help",
+	alias: ["h"],
+	description: "Show help",
+	takesValue: false,
+	options: [],
+};
+
+const VERSION: Flag = {
+	name: "version",
+	alias: [],
+	description: "Show version",
+	takesValue: false,
+	options: [],
+};
+
+/** Walks the citty command tree, loading lazy subcommands. */
+export async function buildSpec(
+	cmd: CommandDef<ArgsDef>,
+	name?: string,
+): Promise<Spec> {
+	const meta = await resolve(cmd.meta);
+	const args = (await resolve(cmd.args)) ?? {};
+	const subs = (await resolve(cmd.subCommands)) ?? {};
+	const flags: Flag[] = Object.entries(args)
+		.filter(([, a]) => a.type !== "positional")
+		.map(([key, a]) => ({
+			name: key,
+			alias: "alias" in a && a.alias !== undefined ? [a.alias].flat() : [],
+			description: a.description ?? "",
+			takesValue: a.type !== "boolean",
+			options: a.type === "enum" ? (a.options ?? []) : [],
+		}));
+	flags.push(HELP);
+	if (meta?.version) flags.push(VERSION);
+	return {
+		name: name ?? meta?.name ?? "",
+		description: meta?.description ?? "",
+		flags,
+		subs: await Promise.all(
+			Object.entries(subs).map(async ([key, sub]) =>
+				buildSpec((await resolve(sub)) as CommandDef<ArgsDef>, key),
+			),
+		),
+	};
+}
+
+export function render(shell: Shell, spec: Spec): string {
+	return { zsh, bash, fish }[shell](spec);
+}
+
+const dashed = (f: string) => (f.length === 1 ? `-${f}` : `--${f}`);
+const sq = (s: string) => `'${s.replaceAll("'", `'\\''`)}'`;
+
+function walk(spec: Spec, path: string[] = []): [string[], Spec][] {
+	return [
+		[path, spec],
+		...spec.subs.flatMap((s) => walk(s, [...path, s.name])),
+	];
+}
+
+function zsh(root: Spec): string {
+	const esc = (s: string) => s.replace(/([[\]:\\])/g, "\\$1");
+	const fn = (path: string[]) => [`_${root.name}`, ...path].join("_");
+	const funcs = walk(root).map(([path, spec]) => {
+		const flags = spec.flags.map((f) => {
+			const names = [f.name, ...f.alias].map(dashed);
+			const excl = names.length > 1 ? `(${names.join(" ")})` : "";
+			const value = !f.takesValue
+				? ""
+				: f.options.length
+					? `:${f.name}:(${f.options.join(" ")})`
+					: `:${f.name}: `;
+			const spec = `[${esc(f.description)}]${value}`;
+			return names.length > 1
+				? `${sq(excl)}{${names.join(",")}}${sq(spec)}`
+				: sq(names[0] + spec);
+		});
+		if (!spec.subs.length)
+			return `${fn(path)}() {\n\t_arguments -s \\\n\t\t${flags.join(" \\\n\t\t")}\n}`;
+		const cmds = spec.subs.map((s) => sq(`${esc(s.name)}:${s.description}`));
+		const cases = spec.subs.map(
+			(s) => `\t\t${s.name}) ${fn([...path, s.name])} ;;`,
+		);
+		return `${fn(path)}() {
+	local curcontext="$curcontext" state line
+	_arguments -C \\
+		${flags.join(" \\\n\t\t")} \\
+		'1: :->cmd' \\
+		'*:: :->args'
+	case $state in
+	cmd)
+		local -a cmds=(${cmds.join(" ")})
+		_describe command cmds ;;
+	args)
+		case $line[1] in
+${cases.join("\n")}
+		esac ;;
+	esac
+}`;
+	});
+	return `#compdef ${root.name}
+
+${funcs.join("\n\n")}
+
+if [ "$funcstack[1]" = "_${root.name}" ]; then
+	_${root.name} "$@"
+else
+	compdef _${root.name} ${root.name}
+fi
+`;
+}
+
+function bash(root: Spec): string {
+	const nodes = walk(root);
+	const specCases = nodes.map(([path, spec]) => {
+		const subs = spec.subs.map((s) => s.name).join(" ");
+		const flags = spec.flags
+			.flatMap((f) => [f.name, ...f.alias].map(dashed))
+			.join(" ");
+		return `\t${JSON.stringify(path.join(" "))}) subs=${sq(subs)}; flags=${sq(flags)} ;;`;
+	});
+	const valueCases = nodes.flatMap(([path, spec]) =>
+		spec.flags
+			.filter((f) => f.takesValue)
+			.map((f) => {
+				const pattern = [f.name, ...f.alias]
+					.map((n) => JSON.stringify(`${path.join(" ")}:${dashed(n)}`))
+					.join("|");
+				const action = f.options.length
+					? `COMPREPLY=($(compgen -W ${sq(f.options.join(" "))} -- "$cur")); return`
+					: "return";
+				return `\t${pattern}) ${action} ;;`;
+			}),
+	);
+	const n = root.name;
+	return `_${n}_spec() {
+	case "$1" in
+${specCases.join("\n")}
+	esac
+}
+
+_${n}() {
+	local cur=\${COMP_WORDS[COMP_CWORD]} prev=\${COMP_WORDS[COMP_CWORD-1]}
+	local cmdpath="" subs flags i
+	_${n}_spec ""
+	for ((i = 1; i < COMP_CWORD; i++)); do
+		if [[ " $subs " == *" \${COMP_WORDS[i]} "* ]]; then
+			cmdpath="\${cmdpath:+$cmdpath }\${COMP_WORDS[i]}"
+			_${n}_spec "$cmdpath"
+		fi
+	done
+	case "$cmdpath:$prev" in
+${valueCases.join("\n")}
+	esac
+	COMPREPLY=($(compgen -W "$subs $flags" -- "$cur"))
+}
+
+complete -F _${n} ${n}
+`;
+}
+
+function fish(root: Spec): string {
+	const n = root.name;
+	const lines = [`complete -c ${n} -f`];
+	for (const [path, spec] of walk(root)) {
+		const seen = path.map((p) => `__fish_seen_subcommand_from ${p}`);
+		if (spec.subs.length) {
+			const names = spec.subs.map((s) => s.name).join(" ");
+			const cond = path.length
+				? [...seen, `not __fish_seen_subcommand_from ${names}`].join("; and ")
+				: "__fish_use_subcommand";
+			for (const s of spec.subs)
+				lines.push(
+					`complete -c ${n} -n ${sq(cond)} -a ${s.name} -d ${sq(s.description)}`,
+				);
+		}
+		for (const f of spec.flags) {
+			const parts = [`complete -c ${n}`];
+			if (seen.length) parts.push(`-n ${sq(seen.join("; and "))}`);
+			parts.push(`-l ${f.name}`);
+			for (const a of f.alias)
+				parts.push(a.length === 1 ? `-s ${a}` : `-l ${a}`);
+			if (f.takesValue) parts.push("-x");
+			if (f.options.length) parts.push(`-a ${sq(f.options.join(" "))}`);
+			if (f.description) parts.push(`-d ${sq(f.description)}`);
+			lines.push(parts.join(" "));
+		}
+	}
+	return `${lines.join("\n")}\n`;
+}

package/src/config.ts

@@ -0,0 +1,213 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { parse, parseDocument } from "yaml";
+import { z } from "zod";
+
+export const COLUMN_KEYS = [
+	"ideas",
+	"planning",
+	"ready",
+	"inProgress",
+	"review",
+	"done",
+] as const;
+export type ColumnKey = (typeof COLUMN_KEYS)[number];
+
+export const JOB_KINDS = ["fix", "review", "plan", "implement"] as const;
+export type JobKind = (typeof JOB_KINDS)[number];
+
+export const ConfigSchema = z.object({
+	provider: z
+		.enum(["claude", "codex"])
+		.default("claude")
+		.describe("Agent CLI that runs workers."),
+	repo: z
+		.string()
+		.regex(/^[^/]+\/[^/]+$/, "expected owner/name")
+		.describe("GitHub repo as owner/name."),
+	baseBranch: z.string().default("main").describe("Branch agents work from."),
+	project: z
+		.object({ owner: z.string(), number: z.number().int() })
+		.nullable()
+		.default(null)
+		.describe("GitHub Project board. Set by `kanbot board create`."),
+	columns: z
+		.object({
+			ideas: z.string().default("Ideas"),
+			planning: z.string().default("Planning"),
+			ready: z.string().default("Ready"),
+			inProgress: z.string().default("In Progress"),
+			review: z.string().default("Review"),
+			done: z.string().default("Done"),
+		})
+		.prefault({})
+		.describe("Names of the board's Status options."),
+	concurrency: z
+		.number()
+		.int()
+		.min(1)
+		.default(3)
+		.describe(
+			"Max concurrent agent workers. Each exploratory variant is one worker.",
+		),
+	pollSeconds: z
+		.number()
+		.int()
+		.min(10)
+		.default(60)
+		.describe("Seconds between board polls."),
+	priority: z
+		.array(z.enum(JOB_KINDS))
+		.default([...JOB_KINDS])
+		.describe("Order in which waiting jobs get free slots."),
+	maxAttempts: z
+		.number()
+		.int()
+		.min(1)
+		.default(2)
+		.describe("Attempts per job before the issue is labeled needs-human."),
+	timeoutMinutes: z
+		.object({
+			plan: z.number().default(20),
+			implement: z.number().default(90),
+			review: z.number().default(30),
+			fix: z.number().default(45),
+		})
+		.prefault({})
+		.describe("Per-job timeout in minutes."),
+	implementers: z
+		.record(z.string(), z.string())
+		.default({
+			frontend: "implementer-frontend",
+			backend: "implementer-backend",
+			docs: "implementer-docs",
+			infra: "implementer-technical",
+			default: "implementer-backend",
+		})
+		.describe(
+			"Maps a type:<key> label to an agent. `default` is the fallback.",
+		),
+	review: z
+		.object({
+			copilot: z
+				.boolean()
+				.default(false)
+				.describe(
+					"Wait for GitHub Copilot's code review and have the fixer address its comments. Needs a paid Copilot plan; each review uses credits.",
+				),
+			copilotOnPush: z
+				.boolean()
+				.default(false)
+				.describe(
+					"Have Copilot review again after every push. One review per push.",
+				),
+			copilotWaitMinutes: z
+				.number()
+				.int()
+				.min(1)
+				.default(15)
+				.describe(
+					"Minutes to wait for Copilot's review before going on without it.",
+				),
+		})
+		.prefault({}),
+	codex: z
+		.object({
+			networkAccess: z
+				.boolean()
+				.default(false)
+				.describe("Let codex workers reach the network (package installs)."),
+		})
+		.prefault({}),
+	notify: z
+		.object({
+			desktop: z
+				.boolean()
+				.default(true)
+				.describe("Show desktop notifications."),
+			webhook: z
+				.string()
+				.url()
+				.nullable()
+				.default(null)
+				.describe(
+					"POSTs {title, message, url} as JSON, e.g. an ntfy.sh topic URL.",
+				),
+		})
+		.prefault({}),
+});
+export type Config = z.infer<typeof ConfigSchema>;
+
+export const LABELS = {
+	technical: "technical",
+	working: "kanbot:working",
+	agentReviewed: "agent-reviewed",
+	needsHuman: "needs-human",
+	review: "kanbot-review",
+	explorePrefix: "explore:",
+	typePrefix: "type:",
+	variantPrefix: "variant:",
+} as const;
+
+export function configPath(root: string) {
+	return join(root, ".kanbot", "config.yml");
+}
+
+export function configSchemaPath(root: string) {
+	return join(root, ".kanbot", "config.schema.json");
+}
+
+/** Points editors (yaml-language-server) at the schema next to the config. */
+const SCHEMA_HEADER = "# yaml-language-server: $schema=./config.schema.json\n";
+
+/** JSON Schema for config.yml. Fields with defaults are optional. */
+export function configJsonSchema() {
+	return {
+		...z.toJSONSchema(ConfigSchema, { io: "input", target: "draft-7" }),
+		title: "kanbot config",
+	};
+}
+
+/** Ignores formatting, so a formatter touching the file doesn't make it stale. */
+export function sameJson(a: string, b: string) {
+	try {
+		return JSON.stringify(JSON.parse(a)) === JSON.stringify(JSON.parse(b));
+	} catch {
+		return false;
+	}
+}
+
+export function renderConfigSchema(): string {
+	return `${JSON.stringify(configJsonSchema(), null, "\t")}\n`;
+}
+
+/** Writes .kanbot/config.schema.json. Returns true if it was missing or stale. */
+export async function writeConfigSchema(
+	root: string,
+	opts: { check?: boolean } = {},
+): Promise<boolean> {
+	const path = configSchemaPath(root);
+	const next = renderConfigSchema();
+	if (existsSync(path) && sameJson(await Bun.file(path).text(), next))
+		return false;
+	if (!opts.check) await Bun.write(path, next);
+	return true;
+}
+
+export async function loadConfig(root: string): Promise<Config> {
+	const path = configPath(root);
+	if (!existsSync(path)) {
+		throw new Error(`No ${path}. Run \`kanbot init\` first.`);
+	}
+	return ConfigSchema.parse(parse(await Bun.file(path).text()) ?? {});
+}
+
+/** Sets top-level keys, keeping the user's comments and formatting. */
+export async function saveConfig(root: string, patch: Partial<Config>) {
+	const path = configPath(root);
+	const text = existsSync(path) ? await Bun.file(path).text() : SCHEMA_HEADER;
+	const doc = parseDocument(text);
+	for (const [key, value] of Object.entries(patch)) doc.set(key, value);
+	await Bun.write(path, String(doc));
+	await writeConfigSchema(root);
+}