kanbot 0.0.0-stage → 0.2.0

package/src/main.ts

@@ -0,0 +1,21 @@
+import { defineCommand } from "citty";
+import pkg from "../package.json" with { type: "json" };
+
+export const main = defineCommand({
+	meta: {
+		name: "kanbot",
+		version: pkg.version,
+		description: "Run an autonomous dev team from a GitHub Project board",
+	},
+	subCommands: {
+		init: () => import("./commands/init.ts").then((m) => m.default),
+		board: () => import("./commands/board.ts").then((m) => m.default),
+		upgrade: () => import("./commands/upgrade.ts").then((m) => m.default),
+		skills: () => import("./commands/skills.ts").then((m) => m.default),
+		sync: () => import("./commands/sync.ts").then((m) => m.default),
+		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),
+		completion: () => import("./commands/completion.ts").then((m) => m.default),
+	},
+});

package/src/providers/claude.ts

@@ -0,0 +1,122 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentDef } from "../agents/load.ts";
+import {
+	agentInstructions,
+	CLAUDE_ATTRIBUTION,
+	CLAUDE_DENY,
+	claudeTools,
+} from "../agents/sync.ts";
+import {
+	looksRateLimited,
+	type Provider,
+	type RunInput,
+	type RunResult,
+	spawnWorker,
+} from "./types.ts";
+
+type ResultEvent = {
+	type: "result";
+	is_error: boolean;
+	subtype: string;
+	result?: string;
+	structured_output?: unknown;
+	api_error_status?: number | null;
+};
+
+/** Claude Code headless (`claude -p`), using the logged-in subscription. */
+export const claude: Provider = {
+	name: "claude",
+	async run(input: RunInput): Promise<RunResult> {
+		const { agent } = input;
+		// Pass agent definitions explicitly so runs don't depend on what is
+		// committed in the worktree's .claude/agents.
+		const tmp = await mkdtemp(join(tmpdir(), "kanbot-claude-"));
+		const agentsFile = join(tmp, "agents.json");
+		await Bun.write(agentsFile, JSON.stringify(claudeAgentsJson(input.agents)));
+		const cmd = [
+			"claude",
+			"-p",
+			"--agents",
+			agentsFile,
+			"--agent",
+			agent.name,
+			"--output-format",
+			"stream-json",
+			"--verbose",
+			"--json-schema",
+			JSON.stringify(input.schema),
+			"--permission-mode",
+			"acceptEdits",
+			"--allowedTools",
+			...headlessTools(agent),
+			"--disallowedTools",
+			...CLAUDE_DENY,
+			"--no-session-persistence",
+			// Isolate from the user's own setup: no user-level plugins, skills or
+			// MCP servers, so workers only see the repo's agents and skills.
+			"--setting-sources",
+			"project,local",
+			"--strict-mcp-config",
+			"--settings",
+			JSON.stringify(CLAUDE_ATTRIBUTION),
+		];
+		if (agent.models.claude) cmd.push("--model", agent.models.claude);
+		if (agent.effort) cmd.push("--effort", agent.effort);
+
+		const res = await spawnWorker(cmd, {
+			cwd: input.cwd,
+			stdin: input.prompt,
+			timeoutMs: input.timeoutMs,
+			logFile: input.logFile,
+		}).finally(() => rm(tmp, { recursive: true, force: true }));
+		if (res.timedOut)
+			return { ok: false, error: "timed out", rateLimited: false };
+
+		const result = res.stdout
+			.split("\n")
+			.reverse()
+			.map((line) => {
+				try {
+					return JSON.parse(line) as ResultEvent;
+				} catch {
+					return null;
+				}
+			})
+			.find((e) => e?.type === "result");
+
+		if (!result || result.is_error || result.structured_output === undefined) {
+			const detail =
+				result?.result ?? res.stderr.slice(-2000) ?? `exit ${res.code}`;
+			return {
+				ok: false,
+				error: `claude ${result?.subtype ?? "failed"}: ${detail}`,
+				rateLimited:
+					result?.api_error_status === 429 || looksRateLimited(detail),
+			};
+		}
+		return { ok: true, output: result.structured_output };
+	},
+};
+
+export function claudeAgentsJson(agents: AgentDef[]) {
+	return Object.fromEntries(
+		agents.map((a) => [
+			a.name,
+			{
+				description: a.description,
+				prompt: agentInstructions(a),
+				tools: headlessTools(a),
+				...(a.models.claude ? { model: a.models.claude } : {}),
+				...(a.skills.length ? { skills: a.skills } : {}),
+			},
+		]),
+	);
+}
+
+/** Headless column agents answer through the StructuredOutput tool. */
+function headlessTools(agent: AgentDef) {
+	const tools = claudeTools(agent);
+	return agent.output ? [...tools, "StructuredOutput"] : tools;
+}

package/src/providers/codex.ts

@@ -0,0 +1,98 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { agentInstructions } from "../agents/sync.ts";
+import { git } from "../daemon/git.ts";
+import {
+	looksRateLimited,
+	type Provider,
+	type RunInput,
+	type RunResult,
+	spawnWorker,
+} from "./types.ts";
+
+/** Codex CLI headless (`codex exec`), using the logged-in ChatGPT plan. */
+export function codex({ networkAccess }: { networkAccess: boolean }): Provider {
+	return {
+		name: "codex",
+		async run(input: RunInput): Promise<RunResult> {
+			const { agent } = input;
+			const tmp = await mkdtemp(join(tmpdir(), "kanbot-codex-"));
+			try {
+				const schemaFile = join(tmp, "schema.json");
+				const lastFile = join(tmp, "last.json");
+				await Bun.write(schemaFile, JSON.stringify(input.schema));
+				// Worktree commits write into the main repo's .git dir.
+				const gitDir = await git(
+					input.cwd,
+					"rev-parse",
+					"--path-format=absolute",
+					"--git-common-dir",
+				);
+				const sandbox =
+					agent.tools.includes("edit") || agent.tools.includes("bash")
+						? "workspace-write"
+						: "read-only";
+				const cmd = [
+					"codex",
+					"exec",
+					"--json",
+					"--ephemeral",
+					"--sandbox",
+					sandbox,
+					"--cd",
+					input.cwd,
+					"--add-dir",
+					gitDir,
+					"--output-schema",
+					schemaFile,
+					"--output-last-message",
+					lastFile,
+					"-c",
+					`developer_instructions=${JSON.stringify(agentInstructions(agent))}`,
+				];
+				if (networkAccess)
+					cmd.push("-c", "sandbox_workspace_write.network_access=true");
+				if (agent.models.codex && agent.models.codex !== "default")
+					cmd.push("--model", agent.models.codex);
+				if (agent.effort) {
+					cmd.push(
+						"-c",
+						`model_reasoning_effort="${agent.effort === "max" ? "xhigh" : agent.effort}"`,
+					);
+				}
+				cmd.push("-");
+
+				const res = await spawnWorker(cmd, {
+					cwd: input.cwd,
+					stdin: input.prompt,
+					timeoutMs: input.timeoutMs,
+					logFile: input.logFile,
+				});
+				if (res.timedOut)
+					return { ok: false, error: "timed out", rateLimited: false };
+
+				const last = Bun.file(lastFile);
+				if (res.code !== 0 || !(await last.exists())) {
+					const detail = (res.stderr || res.stdout).slice(-2000);
+					return {
+						ok: false,
+						error: `codex exit ${res.code}: ${detail}`,
+						rateLimited: looksRateLimited(detail),
+					};
+				}
+				try {
+					return { ok: true, output: JSON.parse(await last.text()) };
+				} catch {
+					return {
+						ok: false,
+						error: "codex final message was not JSON",
+						rateLimited: false,
+					};
+				}
+			} finally {
+				await rm(tmp, { recursive: true, force: true });
+			}
+		},
+	};
+}

package/src/providers/types.ts

@@ -0,0 +1,94 @@
+import type { AgentDef } from "../agents/load.ts";
+import type { Config } from "../config.ts";
+
+export type RunInput = {
+	agent: AgentDef;
+	/** All agents, so the worker can delegate to subagents. */
+	agents: AgentDef[];
+	prompt: string;
+	cwd: string;
+	/** JSON Schema the final answer must match. */
+	schema: object;
+	timeoutMs: number;
+	logFile: string;
+	/** Main repo checkout, e.g. so sandboxes can write the shared .git dir. */
+	repoRoot: string;
+};
+
+export type RunResult =
+	| { ok: true; output: unknown }
+	| { ok: false; error: string; rateLimited: boolean };
+
+export interface Provider {
+	readonly name: Config["provider"];
+	run(input: RunInput): Promise<RunResult>;
+}
+
+const RATE_LIMIT =
+	/usage limit|rate limit|rate_limit|429|quota|limit reached|try again later/i;
+
+export function looksRateLimited(text: string) {
+	return RATE_LIMIT.test(text);
+}
+
+/** Env for workers: never hand them GitHub credentials. */
+export function workerEnv(): Record<string, string> {
+	const env: Record<string, string> = {};
+	for (const [k, v] of Object.entries(process.env)) {
+		if (v === undefined) continue;
+		if (/^(GH|GITHUB)_.*TOKEN$|^GH_ENTERPRISE_TOKEN$/.test(k)) continue;
+		env[k] = v;
+	}
+	env.KANBOT_WORKER = "1";
+	return env;
+}
+
+export type Spawned = {
+	stdout: string;
+	stderr: string;
+	code: number;
+	timedOut: boolean;
+};
+
+/** Spawn a worker, tee stdout to the job log, enforce the timeout. */
+export async function spawnWorker(
+	cmd: string[],
+	{
+		cwd,
+		stdin,
+		timeoutMs,
+		logFile,
+	}: { cwd: string; stdin: string; timeoutMs: number; logFile: string },
+): Promise<Spawned> {
+	const proc = Bun.spawn(cmd, {
+		cwd,
+		env: workerEnv(),
+		stdin: new Blob([stdin]),
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		proc.kill("SIGTERM");
+		setTimeout(() => proc.kill("SIGKILL"), 10_000);
+	}, timeoutMs);
+	const sink = Bun.file(logFile).writer();
+	const decoder = new TextDecoder();
+	let stdout = "";
+	const readOut = (async () => {
+		for await (const chunk of proc.stdout) {
+			sink.write(chunk);
+			stdout += decoder.decode(chunk, { stream: true });
+		}
+	})();
+	const [stderr, code] = await Promise.all([
+		new Response(proc.stderr).text(),
+		proc.exited,
+		readOut,
+	]);
+	clearTimeout(timer);
+	if (stderr) sink.write(`\n--- stderr ---\n${stderr}`);
+	await sink.end();
+	return { stdout, stderr, code, timedOut };
+}

package/src/schemas/results.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+
+/*
+ * Output contracts for column agents. Both CLIs enforce these natively
+ * (claude --json-schema, codex --output-schema). Codex uses strict schemas, so
+ * every field is required; use null or empty arrays for "nothing".
+ */
+
+export const PlanResult = z.strictObject({
+	plan: z
+		.string()
+		.describe(
+			"Full markdown plan per plan-template; replaces the previous plan. Aim for under 30 lines.",
+		),
+	summary: z.string().describe("One sentence to the human on what changed."),
+	replies: z
+		.array(
+			z.strictObject({
+				commentId: z.string().describe("id of the human comment answered"),
+				body: z.string().describe("One or two sentences."),
+			}),
+		)
+		.describe("One reply per human comment given as input."),
+	newIssues: z
+		.array(
+			z.strictObject({
+				title: z.string(),
+				body: z.string(),
+				subIssue: z
+					.boolean()
+					.describe("true when it is split out of this issue"),
+				column: z.enum(["ideas", "planning"]),
+			}),
+		)
+		.describe("Issues to create, e.g. when the human asks to split work."),
+	labels: z
+		.array(z.string())
+		.describe("Labels the issue should have, e.g. type:frontend or technical."),
+	questions: z
+		.array(z.string())
+		.describe(
+			"Only questions blocking approval, one line each, with the default you assume.",
+		),
+});
+export type PlanResult = z.infer<typeof PlanResult>;
+
+export const ImplementResult = z.strictObject({
+	status: z.enum(["done", "blocked"]),
+	prTitle: z.string().describe("Conventional commit, under 72 characters."),
+	prBody: z
+		.string()
+		.describe(
+			"Short markdown PR description per pr-description, under ~20 lines. No 'Closes' line, risks or test results.",
+		),
+	testsRun: z
+		.array(z.string())
+		.describe("One line each: command and result, e.g. `bun test`: 5 pass."),
+	screenshots: z
+		.array(z.string())
+		.describe("Repo-relative paths of screenshots committed for review."),
+	risks: z
+		.array(z.string())
+		.describe("Real risks only, one line each. Empty when none."),
+	blockedReason: z.string().nullable(),
+});
+export type ImplementResult = z.infer<typeof ImplementResult>;
+
+export const Finding = z.strictObject({
+	id: z.string().describe("Short stable id like F1"),
+	severity: z.enum(["blocker", "major", "minor", "nit"]),
+	path: z.string().nullable(),
+	line: z.number().int().nullable(),
+	body: z
+		.string()
+		.describe("One to three sentences: the problem, why it matters, the fix."),
+});
+export type Finding = z.infer<typeof Finding>;
+
+export const ReviewResult = z.strictObject({
+	verdict: z.enum(["approve", "changes"]),
+	summary: z.string().describe("One or two sentences."),
+	findings: z.array(Finding),
+});
+export type ReviewResult = z.infer<typeof ReviewResult>;
+
+export const FixResult = z.strictObject({
+	addressed: z.array(
+		z.strictObject({
+			ref: z.string().describe("Finding id or comment/thread id handled"),
+			reply: z
+				.string()
+				.describe("One or two sentences: what changed, or why not."),
+			resolved: z.boolean(),
+		}),
+	),
+	summary: z.string().describe("One sentence."),
+	prBody: z
+		.string()
+		.nullable()
+		.describe(
+			"Full updated PR description when your changes made the current one wrong (behaviour, copy, screenshots); null otherwise.",
+		),
+});
+export type FixResult = z.infer<typeof FixResult>;
+
+export const RESULT_SCHEMAS = {
+	"plan-result": PlanResult,
+	"implement-result": ImplementResult,
+	"review-result": ReviewResult,
+	"fix-result": FixResult,
+} as const;
+export type ResultSchemaName = keyof typeof RESULT_SCHEMAS;
+
+export function jsonSchema(name: ResultSchemaName) {
+	return z.toJSONSchema(RESULT_SCHEMAS[name], { target: "draft-7" });
+}

package/src/templates.ts

@@ -0,0 +1,192 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import pkg from "../package.json" with { type: "json" };
+import knownHashes from "./known-hashes.json" with { type: "json" };
+
+/*
+ * Template files installed into consumer repos, and how upgrades treat them.
+ * `.kanbot/manifest.json` records the hash of each template as installed, so an
+ * upgrade can tell files you edited from files it may replace.
+ */
+
+export const TEMPLATES = join(import.meta.dir, "..", "templates");
+const MANIFEST = join(".kanbot", "manifest.json");
+export const NEW_SUFFIX = ".kanbot-new";
+
+/**
+ * - `kanbot`: belongs to kanbot; always replaced.
+ * - `user`: yours after install; never touched again.
+ * - `shared`: replaced while unedited; your edits get a `.kanbot-new` copy.
+ */
+export type FileClass = "kanbot" | "user" | "shared";
+
+const CLASSES: [prefix: string, FileClass][] = [
+	[".github/workflows/kanbot-", "kanbot"],
+	[".agents/skills/kanbot-admin/", "kanbot"],
+	[".agents/skills/kanbot-idea/", "kanbot"],
+	["AGENTS.md", "user"],
+	["CLAUDE.md", "user"],
+	[".agents/skills/project-conventions/", "user"],
+	[".agents/skills/project-memory/", "user"],
+	[".github/workflows/ci.yml", "user"],
+	[".github/ISSUE_TEMPLATE/", "user"],
+	[".github/pull_request_template.md", "user"],
+];
+
+export function fileClass(path: string): FileClass {
+	return CLASSES.find(([prefix]) => path.startsWith(prefix))?.[1] ?? "shared";
+}
+
+/** Git blob id, so hashes of past versions can be read from git history. */
+export function hash(content: Uint8Array) {
+	const h = new Bun.CryptoHasher("sha1");
+	h.update(`blob ${content.length}\0`);
+	h.update(content);
+	return h.digest("hex");
+}
+
+export type Manifest = { version: string; files: Record<string, string> };
+
+export async function readManifest(root: string): Promise<Manifest | null> {
+	const file = Bun.file(join(root, MANIFEST));
+	return (await file.exists()) ? ((await file.json()) as Manifest) : null;
+}
+
+async function writeManifest(root: string, files: Record<string, string>) {
+	const sorted = Object.fromEntries(
+		Object.entries(files).sort(([a], [b]) => a.localeCompare(b)),
+	);
+	const manifest: Manifest = { version: pkg.version, files: sorted };
+	await Bun.write(
+		join(root, MANIFEST),
+		`${JSON.stringify(manifest, null, "\t")}\n`,
+	);
+}
+
+/** Template files as repo-relative paths with forward slashes. */
+export async function listTemplates(dir = TEMPLATES) {
+	const out = new Map<string, Uint8Array>();
+	const walk = async (d: string) => {
+		for (const e of await readdir(d, { withFileTypes: true })) {
+			const p = join(d, e.name);
+			if (e.isDirectory()) await walk(p);
+			else
+				out.set(
+					relative(dir, p).split(sep).join("/"),
+					await Bun.file(p).bytes(),
+				);
+		}
+	};
+	await walk(dir);
+	return out;
+}
+
+export type Change = {
+	path: string;
+	action:
+		| "add" // new template, written
+		| "update" // unedited, replaced
+		| "conflict" // edited by you; new version goes to <path>.kanbot-new
+		| "deleted" // you deleted it; left out
+		| "removed"; // no longer shipped; left in place
+	content?: Uint8Array;
+};
+
+export type Plan = { changes: Change[]; files: Record<string, string> };
+
+type Options = {
+	templates?: string;
+	known?: Record<string, string[]>;
+	/** `init --force`: overwrite everything. */
+	force?: boolean;
+};
+
+/**
+ * Work out what an upgrade would change. Without a manifest, a file that
+ * matches any past template version counts as unedited.
+ */
+export async function planUpgrade(
+	root: string,
+	opts: Options = {},
+): Promise<Plan> {
+	const templates = await listTemplates(opts.templates);
+	const known: Record<string, string[]> = opts.known ?? knownHashes;
+	const manifest = await readManifest(root);
+	const files: Record<string, string> = {};
+	const changes: Change[] = [];
+
+	for (const [path, content] of templates) {
+		const next = hash(content);
+		const target = join(root, path);
+		const recorded = manifest?.files[path];
+		const write = (action: Change["action"]) => {
+			changes.push({ path, action, content });
+			files[path] = next;
+		};
+
+		if (!existsSync(target)) {
+			if (recorded && !opts.force) {
+				changes.push({ path, action: "deleted" });
+				files[path] = recorded;
+			} else write("add");
+			continue;
+		}
+		const current = hash(await Bun.file(target).bytes());
+		if (current === next) {
+			files[path] = next;
+			continue;
+		}
+		if (opts.force) {
+			write("update");
+			continue;
+		}
+		const cls = fileClass(path);
+		if (cls === "user") {
+			files[path] = recorded ?? current;
+			continue;
+		}
+		if (cls === "shared" && recorded === next) {
+			// Template unchanged since install: your edits stand.
+			files[path] = next;
+			continue;
+		}
+		const unedited = recorded
+			? current === recorded
+			: (known[path] ?? []).includes(current);
+		if (cls === "kanbot" || unedited) {
+			write("update");
+			continue;
+		}
+		// Record the new version as the base, so once you merge it, later
+		// upgrades only flag the file when the template changes again.
+		changes.push({ path, action: "conflict", content });
+		files[path] = next;
+	}
+
+	for (const path of Object.keys(manifest?.files ?? {})) {
+		if (!templates.has(path) && existsSync(join(root, path)))
+			changes.push({ path, action: "removed" });
+	}
+	return { changes, files };
+}
+
+/** Write the planned files and the manifest. */
+export async function applyUpgrade(root: string, plan: Plan) {
+	for (const c of plan.changes) {
+		if (!c.content) continue;
+		const to = join(
+			root,
+			c.action === "conflict" ? `${c.path}${NEW_SUFFIX}` : c.path,
+		);
+		await mkdir(dirname(to), { recursive: true });
+		await Bun.write(to, c.content);
+	}
+	await writeManifest(root, plan.files);
+}
+
+/** Leftover `.kanbot-new` files waiting to be merged. */
+export async function pendingMerges(root: string, dir = TEMPLATES) {
+	const paths = [...(await listTemplates(dir)).keys()];
+	return paths.filter((p) => existsSync(join(root, `${p}${NEW_SUFFIX}`)));
+}