kanbot 0.0.0-stage → 0.2.0

package/src/commands/init.ts

@@ -0,0 +1,119 @@
+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 { UserError } from "../errors.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 UserError("Not a git repository.", {
+				why: `No .git in ${root}. Run init from the repo root.`,
+				fix: "cd into your repo's root, or run `git init`.",
+				docs: "getting-started#set-up-a-repository",
+				more: "",
+			});
+		if (!["claude", "codex"].includes(args.provider))
+			throw new UserError(`Unknown provider "${args.provider}".`, {
+				fix: "kanbot init --provider claude|codex",
+				docs: "providers#choose-a-provider",
+				more: "",
+			});
+
+		// Fail on gh or remote problems before writing anything.
+		const repo =
+			!existsSync(configPath(root)) || args.force
+				? (JSON.parse(
+						await run([
+							"repo",
+							"view",
+							"--json",
+							"nameWithOwner,defaultBranchRef",
+						]),
+					) as { nameWithOwner: string; defaultBranchRef: { name: string } })
+				: null;
+
+		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 (repo) {
+			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,70 @@
+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, run } 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 run([
+				"issue",
+				"list",
+				"--repo",
+				config.repo,
+				"--label",
+				LABELS.needsHuman,
+				"--json",
+				"number,title",
+			]),
+		) 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()}`,
+			);
+		}
+	},
+});

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`;
+}