cuekit 0.0.12

package/src/doctor.ts

@@ -0,0 +1,438 @@
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { loadProjectConfig as loadProjectConfigFromDisk } from "@cuekit/project-config";
+import {
+	DEFAULT_DB_PATH,
+	findInvalidTaskRows,
+	openDatabase,
+	repairTaskSqliteTimestamps,
+} from "@cuekit/store";
+import pkg from "../package.json" with { type: "json" };
+import { formatCheckLine } from "./output.ts";
+
+export type DoctorLevel = "ok" | "warn" | "fail";
+export type DoctorCheck = { level: DoctorLevel; label: string; detail: string };
+export type DoctorResult = {
+	exitCode: number;
+	checks: DoctorCheck[];
+	stdout: string;
+	stderr?: string;
+};
+
+export type DoctorExecResult =
+	| { ok: true; stdout: string; stderr?: string }
+	| { ok: false; stdout?: string; stderr: string };
+export type DoctorExec = (command: string, args: string[]) => Promise<DoctorExecResult>;
+
+export type WritableStateResult =
+	| { ok: true; path: string }
+	| { ok: false; path: string; reason: string };
+export type DoctorProjectConfigResult =
+	| { ok: true; source: "config"; path: string }
+	| { ok: true; source: "git" | "cwd" }
+	| { ok: false; error: string };
+export type LatestReleaseResult = { ok: true; tag: string } | { ok: false; reason: string };
+
+export type RunDoctorOptions = {
+	cwd?: string;
+	env?: Record<string, string | undefined>;
+	fix?: boolean;
+	exec?: DoctorExec;
+	checkWritableState?: (env: Record<string, string | undefined>) => Promise<WritableStateResult>;
+	checkStateDbTaskRows?: (
+		env: Record<string, string | undefined>,
+		fix: boolean,
+	) => Promise<DoctorCheck>;
+	loadProjectConfig?: (cwd: string) => DoctorProjectConfigResult;
+	getCurrentVersion?: () => string | undefined;
+	getLatestRelease?: () => Promise<LatestReleaseResult>;
+};
+
+type DoctorSpawnSync = (
+	command: string,
+	args: string[],
+) => {
+	success: boolean;
+	stdout: Uint8Array;
+	stderr: Uint8Array;
+};
+
+export function createDoctorExec(spawnSync: DoctorSpawnSync): DoctorExec {
+	return async (command, args) => {
+		try {
+			const proc = spawnSync(command, args);
+			const stdout = proc.stdout.toString();
+			const stderr = proc.stderr.toString();
+			return proc.success
+				? { ok: true, stdout, stderr }
+				: { ok: false, stdout, stderr: stderr || "command failed" };
+		} catch (error) {
+			return { ok: false, stderr: error instanceof Error ? error.message : String(error) };
+		}
+	};
+}
+
+export const defaultDoctorExec = createDoctorExec((command, args) =>
+	Bun.spawnSync([command, ...args], { stdout: "pipe", stderr: "pipe" }),
+);
+
+function findWritableExistingParent(path: string): string | undefined {
+	let current = path;
+	while (true) {
+		if (existsSync(current)) {
+			try {
+				if (statSync(current).isDirectory()) return current;
+			} catch {
+				return undefined;
+			}
+		}
+		const parent = dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}
+
+async function defaultCheckWritableState(
+	env: Record<string, string | undefined>,
+): Promise<WritableStateResult> {
+	const path =
+		env.CUEKIT_DB_PATH && env.CUEKIT_DB_PATH.length > 0 ? env.CUEKIT_DB_PATH : DEFAULT_DB_PATH;
+	if (path === ":memory:") return { ok: true, path };
+	const parent = findWritableExistingParent(dirname(path));
+	if (!parent) return { ok: false, path, reason: "no writable parent directory found" };
+	try {
+		accessSync(parent, constants.W_OK);
+		return { ok: true, path };
+	} catch (error) {
+		return { ok: false, path, reason: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+async function defaultCheckStateDbTaskRows(
+	env: Record<string, string | undefined>,
+	fix: boolean,
+): Promise<DoctorCheck> {
+	const path =
+		env.CUEKIT_DB_PATH && env.CUEKIT_DB_PATH.length > 0 ? env.CUEKIT_DB_PATH : DEFAULT_DB_PATH;
+	if (path === ":memory:") {
+		return { level: "ok", label: "state db task rows", detail: "skipped (:memory:)" };
+	}
+	if (!existsSync(path)) {
+		return { level: "ok", label: "state db task rows", detail: "not created yet" };
+	}
+	let db: ReturnType<typeof openDatabase> | undefined;
+	try {
+		db = openDatabase({ path });
+		const repaired = fix ? repairTaskSqliteTimestamps(db) : 0;
+		const invalid = findInvalidTaskRows(db);
+		if (invalid.length === 0) {
+			return {
+				level: "ok",
+				label: "state db task rows",
+				detail: repaired > 0 ? `repaired ${repaired} SQLite timestamp(s)` : "healthy",
+			};
+		}
+		const examples = invalid
+			.slice(0, 3)
+			.map((row) => row.id)
+			.join(", ");
+		return {
+			level: "warn",
+			label: "state db task rows",
+			detail: `${invalid.length} invalid task row(s)${examples ? ` (${examples})` : ""}${
+				fix ? " after repair" : " (run cuekit doctor --fix)"
+			}`,
+		};
+	} catch (error) {
+		return {
+			level: "warn",
+			label: "state db task rows",
+			detail: `could not inspect (${error instanceof Error ? error.message : String(error)})`,
+		};
+	} finally {
+		try {
+			db?.close();
+		} catch {
+			// ignore close errors in diagnostics
+		}
+	}
+}
+
+function readMultiplexerSettings(cwd: string): {
+	requested: "tmux" | "zellij" | "herdr";
+	strict: boolean;
+} {
+	try {
+		const loaded = loadProjectConfigFromDisk(cwd);
+		if (loaded.ok && loaded.discovery.source === "config") {
+			const configured = loaded.config.multiplexer;
+			return {
+				requested: typeof configured === "string" ? configured : (configured?.backend ?? "tmux"),
+				strict:
+					typeof configured === "object" && configured?.strict !== undefined
+						? configured.strict
+						: loaded.config.multiplexer_strict === true,
+			};
+		}
+	} catch {
+		// fall through
+	}
+	return { requested: "tmux", strict: false };
+}
+
+function defaultLoadProjectConfig(cwd: string): DoctorProjectConfigResult {
+	const loaded = loadProjectConfigFromDisk(cwd);
+	if (!loaded.ok) return { ok: false, error: loaded.error };
+	if (loaded.discovery.source === "config" && loaded.discovery.configPath) {
+		return { ok: true, source: "config", path: loaded.discovery.configPath };
+	}
+	return { ok: true, source: loaded.discovery.source === "git" ? "git" : "cwd" };
+}
+
+async function defaultGetLatestRelease(): Promise<LatestReleaseResult> {
+	try {
+		const response = await fetch("https://api.github.com/repos/takemo101/cuekit/releases/latest", {
+			headers: { accept: "application/vnd.github+json" },
+		});
+		if (!response.ok) return { ok: false, reason: `HTTP ${response.status}` };
+		const body = (await response.json()) as { tag_name?: unknown };
+		return typeof body.tag_name === "string" && body.tag_name.length > 0
+			? { ok: true, tag: body.tag_name }
+			: { ok: false, reason: "missing tag_name" };
+	} catch (error) {
+		return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function trimVersionOutput(value: string): string {
+	return value.trim().split(/\s+/).join(" ");
+}
+
+function normalizeReleaseVersion(value: string): string {
+	return value.trim().replace(/^v/, "");
+}
+
+const ADAPTER_EXECUTABLES = [
+	{ kind: "claude-code", command: "claude" },
+	{ kind: "pi", command: "pi" },
+	{ kind: "opencode", command: "opencode" },
+	{ kind: "jcode", command: "jcode" },
+	{ kind: "gemini", command: "gemini" },
+] as const;
+
+function renderDoctor(checks: DoctorCheck[]): string {
+	return [
+		"cuekit doctor",
+		"",
+		...checks.map(formatCheckLine),
+		"",
+		"Next:",
+		"  cuekit mcp config",
+		"  cuekit update",
+		"",
+	].join("\n");
+}
+
+export async function runDoctor(options: RunDoctorOptions = {}): Promise<DoctorResult> {
+	const env = options.env ?? process.env;
+	const fix = options.fix === true;
+	const exec = options.exec ?? defaultDoctorExec;
+	const checks: DoctorCheck[] = [];
+
+	const currentVersion = options.getCurrentVersion ? options.getCurrentVersion() : pkg.version;
+	checks.push(
+		currentVersion
+			? { level: "ok", label: "cuekit", detail: currentVersion }
+			: { level: "warn", label: "cuekit", detail: "version unknown" },
+	);
+
+	const bunVersion = await exec("bun", ["--version"]);
+	checks.push(
+		bunVersion.ok
+			? { level: "ok", label: "bun", detail: trimVersionOutput(bunVersion.stdout) }
+			: { level: "fail", label: "bun", detail: bunVersion.stderr || "not found" },
+	);
+
+	// Active multiplexer backend. Reads `multiplexer.backend` from project config
+	// (default tmux). When an optional backend is configured but its probe fails,
+	// the runtime factory soft-falls-back to tmux; doctor reports this so the
+	// operator can see at a glance whether they got the backend they asked
+	// for.
+	const cwdForConfig = options.cwd ?? process.cwd();
+	const { requested: requestedMultiplexer, strict: multiplexerStrict } =
+		readMultiplexerSettings(cwdForConfig);
+	const optionalBackendProbe =
+		requestedMultiplexer === "zellij"
+			? await exec("zellij", ["--version"])
+			: requestedMultiplexer === "herdr"
+				? await exec("herdr", ["--version"])
+				: null;
+	const fallbackApplied =
+		requestedMultiplexer !== "tmux" &&
+		optionalBackendProbe !== null &&
+		!optionalBackendProbe.ok &&
+		!multiplexerStrict;
+	const strictFailure =
+		requestedMultiplexer !== "tmux" &&
+		optionalBackendProbe !== null &&
+		!optionalBackendProbe.ok &&
+		multiplexerStrict;
+	const activeBackend = strictFailure
+		? `${requestedMultiplexer} unavailable (strict mode)`
+		: fallbackApplied
+			? `tmux (fallback from ${requestedMultiplexer})`
+			: requestedMultiplexer;
+	checks.push({
+		level: strictFailure ? "fail" : "ok",
+		label: "active backend",
+		detail: activeBackend,
+	});
+
+	if (optionalBackendProbe !== null && requestedMultiplexer !== "tmux") {
+		checks.push(
+			optionalBackendProbe.ok
+				? {
+						level: "ok",
+						label: requestedMultiplexer,
+						detail: trimVersionOutput(optionalBackendProbe.stdout),
+					}
+				: {
+						level: multiplexerStrict ? "fail" : "warn",
+						label: requestedMultiplexer,
+						detail:
+							optionalBackendProbe.stderr ||
+							(multiplexerStrict ? "not found (strict mode)" : "not found (falling back to tmux)"),
+					},
+		);
+	}
+
+	const tmuxVersion = await exec("tmux", ["-V"]);
+	const tmuxRequired = requestedMultiplexer === "tmux" || fallbackApplied;
+	checks.push(
+		tmuxVersion.ok
+			? { level: "ok", label: "tmux", detail: trimVersionOutput(tmuxVersion.stdout) }
+			: {
+					level: tmuxRequired ? "fail" : "warn",
+					label: "tmux",
+					detail:
+						tmuxVersion.stderr || (tmuxRequired ? "not found" : "not found (not active backend)"),
+				},
+	);
+
+	// Confirm `capture-pane` is recognised as a subcommand. cuekit's TUI
+	// reads live pane content through `tmux capture-pane -p -e -J ...`
+	// (#376), so a tmux without that subcommand would silently fall back
+	// to the file-tail and the operator would never know why the live
+	// view stayed stale. Probing against a guaranteed-missing target
+	// returns a 1 with "no such session" — that's the success path here.
+	if (tmuxVersion.ok) {
+		const capture = await exec("tmux", [
+			"capture-pane",
+			"-p",
+			"-t",
+			"cuekit-doctor-probe-no-such-session",
+		]);
+		const stderr = (capture.stderr ?? "").toLowerCase();
+		const supportsCapture =
+			capture.ok || stderr.includes("session") || stderr.includes("can't find");
+		checks.push(
+			supportsCapture
+				? {
+						level: "ok",
+						label: "tmux capture-pane",
+						detail: "supported",
+					}
+				: {
+						level: "warn",
+						label: "tmux capture-pane",
+						detail: capture.stderr || "subcommand not recognised",
+					},
+		);
+	}
+
+	const writableState = await (options.checkWritableState ?? defaultCheckWritableState)(env);
+	checks.push(
+		writableState.ok
+			? { level: "ok", label: "state db", detail: `${writableState.path} writable` }
+			: {
+					level: "fail",
+					label: "state db",
+					detail: `${writableState.path}: ${writableState.reason}`,
+				},
+	);
+	checks.push(await (options.checkStateDbTaskRows ?? defaultCheckStateDbTaskRows)(env, fix));
+
+	const projectConfig = (options.loadProjectConfig ?? defaultLoadProjectConfig)(
+		options.cwd ?? process.cwd(),
+	);
+	if (!projectConfig.ok) {
+		checks.push({ level: "fail", label: "project config", detail: projectConfig.error });
+	} else if (projectConfig.source === "config") {
+		checks.push({ level: "ok", label: "project config", detail: projectConfig.path });
+	} else {
+		checks.push({
+			level: "warn",
+			label: "project config",
+			detail: `not found (using ${projectConfig.source} scope)`,
+		});
+	}
+
+	checks.push({ level: "ok", label: "MCP config helper", detail: "cuekit mcp config" });
+
+	// Parent PATH summary so operators can spot mismatches with pane
+	// environments (especially under herdr or nested tmux).
+	const parentPath = env.PATH ?? "";
+	checks.push({
+		level: "ok",
+		label: "parent PATH",
+		detail: parentPath ? `${parentPath.split(":").length} entries` : "not set",
+	});
+
+	for (const adapter of ADAPTER_EXECUTABLES) {
+		const result = await exec(adapter.command, ["--version"]);
+		checks.push(
+			result.ok
+				? {
+						level: "ok",
+						label: `adapter ${adapter.kind}`,
+						detail: `${adapter.command} found`,
+					}
+				: {
+						level: "warn",
+						label: `adapter ${adapter.kind}`,
+						detail: `${adapter.command} not found`,
+					},
+		);
+	}
+
+	// Warn when adapters were found in the parent PATH but the active
+	// multiplexer backend runs tasks in panes that may inherit a different
+	// PATH. This is especially common with herdr or when cuekit itself is
+	// already running inside a multiplexer session.
+	const anyAdapterFound = checks.some(
+		(c) =>
+			c.label.startsWith("adapter ") && c.level === "ok" && c.detail.includes("found"),
+	);
+	if (anyAdapterFound && requestedMultiplexer !== "tmux") {
+		checks.push({
+			level: "warn",
+			label: "pane PATH",
+			detail: `${requestedMultiplexer} panes may have a different PATH; verify with 'echo $PATH' inside a fresh ${requestedMultiplexer} pane`,
+		});
+	}
+
+	const latest = await (options.getLatestRelease ?? defaultGetLatestRelease)();
+	if (!latest.ok) {
+		checks.push({ level: "warn", label: "update", detail: `skipped (${latest.reason})` });
+	} else if (
+		currentVersion &&
+		normalizeReleaseVersion(currentVersion) === normalizeReleaseVersion(latest.tag)
+	) {
+		checks.push({ level: "ok", label: "update", detail: "up to date" });
+	} else {
+		checks.push({ level: "warn", label: "update", detail: `${latest.tag} available` });
+	}
+
+	const exitCode = checks.some((check) => check.level === "fail") ? 1 : 0;
+	return { exitCode, checks, stdout: renderDoctor(checks) };
+}

package/src/human-commands.ts

@@ -0,0 +1,188 @@
+import { registerPiMcpServer } from "@cuekit/mcp";
+import { type ProjectConfigInitResult, runProjectConfigInit } from "@cuekit/project-config";
+import { registerJcodeMcpServer } from "./jcode-mcp-config.ts";
+
+export type HumanCommandResult = {
+	exitCode: number;
+	stdout: string;
+	stderr?: string;
+};
+
+export type RunInitDependencies = {
+	cwd?: string;
+	runProjectConfigInit?: typeof runProjectConfigInit;
+};
+
+export function printInitHelp(): string {
+	return [
+		"cuekit init — create safe project-local cuekit config",
+		"",
+		"Usage: cuekit init [--dry-run] [--force] [--no-gitignore] [--unsafe-bypass]",
+		"",
+		"Creates .cuekit.yaml in the current directory and adds .cuekit/tasks/ to .gitignore.",
+		"",
+		"Options:",
+		"  --dry-run       Show what would be written without changing files",
+		"  --force         Overwrite an existing .cuekit.yaml",
+		"  --no-gitignore  Do not create or update .gitignore",
+		"  --unsafe-bypass Generate adapter permissions: bypass (unsafe; explicit opt-in)",
+		"  -h, --help      Show this help",
+		"",
+	].join("\n");
+}
+
+function formatInitSummary(result: ProjectConfigInitResult): string {
+	const prefix = result.dryRun ? "dry-run: " : "";
+	const lines = [
+		`${prefix}cuekit init ${result.dryRun ? "would update" : "updated"} ${result.cwd}`,
+	];
+	for (const path of result.created) lines.push(`${prefix}created ${path}`);
+	for (const path of result.updated) lines.push(`${prefix}updated ${path}`);
+	for (const path of result.skipped) lines.push(`${prefix}skipped ${path}`);
+	return `${lines.join("\n")}\n`;
+}
+
+export function runInitCommand(
+	argv: string[],
+	dependencies: RunInitDependencies = {},
+): HumanCommandResult {
+	if (argv.includes("--help") || argv.includes("-h")) {
+		return { exitCode: 0, stdout: printInitHelp() };
+	}
+	const unsafeBypass = argv.includes("--unsafe-bypass");
+	try {
+		const result = (dependencies.runProjectConfigInit ?? runProjectConfigInit)({
+			cwd: dependencies.cwd ?? process.cwd(),
+			dryRun: argv.includes("--dry-run"),
+			force: argv.includes("--force"),
+			gitignore: !argv.includes("--no-gitignore"),
+			unsafeBypass,
+		});
+		return {
+			exitCode: 0,
+			stdout: formatInitSummary(result),
+			...(unsafeBypass
+				? {
+						stderr:
+							"warning: --unsafe-bypass writes project-local adapter permissions: bypass; only use this for trusted repositories\n",
+					}
+				: {}),
+		};
+	} catch (err) {
+		return {
+			exitCode: 1,
+			stdout: "",
+			stderr: `${err instanceof Error ? err.message : String(err)}\n`,
+		};
+	}
+}
+
+export function printTuiHelp(): string {
+	return [
+		"cuekit tui — interactive task cockpit",
+		"",
+		"Usage: cuekit tui [--path] [--all]",
+		"",
+		"By default, uses .cuekit.yaml project scope when present, otherwise the current repository/worktree.",
+		"Use --path to ignore .cuekit.yaml identity and scope by the current path/Git root.",
+		"Use --all to show tasks across all projects for this invocation.",
+		"",
+		"Keys: ↑/↓ select, r refresh, a attach (returns after detach), t teams/tasks, s steer, c cancel, d delete, q quit",
+		"",
+	].join("\n");
+}
+
+function splitAgentArgs(argv: string[], agent: string): { hasAgent: boolean; rest: string[] } {
+	const rest: string[] = [];
+	let hasAgent = false;
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === undefined) continue;
+		if ((arg === "--agent" || arg === "-a") && argv[i + 1] === agent) {
+			hasAgent = true;
+			i++;
+			continue;
+		}
+		if (arg === `--agent=${agent}` || arg === `-a=${agent}`) {
+			hasAgent = true;
+			continue;
+		}
+		rest.push(arg);
+	}
+	return { hasAgent, rest };
+}
+
+export function splitPiAgentArgs(argv: string[]): { hasPi: boolean; rest: string[] } {
+	const result = splitAgentArgs(argv, "pi");
+	return { hasPi: result.hasAgent, rest: result.rest };
+}
+
+export function hasExplicitAgent(argv: string[]): boolean {
+	return argv.some(
+		(arg) =>
+			arg === "--agent" || arg === "-a" || arg.startsWith("--agent=") || arg.startsWith("-a="),
+	);
+}
+
+export function runPiMcpAddCommand(
+	argv: string[],
+): HumanCommandResult & { shouldDelegate: boolean; delegateArgv: string[] } {
+	const piAgents = splitPiAgentArgs(argv);
+	if (!piAgents.hasPi) {
+		return { exitCode: 0, stdout: "", shouldDelegate: true, delegateArgv: ["mcp", "add", ...argv] };
+	}
+
+	const result = registerPiMcpServer({
+		global: !piAgents.rest.includes("--no-global"),
+	});
+	return {
+		exitCode: 0,
+		stdout: `Registered MCP server '${result.serverName}' for Pi: ${result.path}\n`,
+		shouldDelegate: hasExplicitAgent(piAgents.rest),
+		delegateArgv: ["mcp", "add", ...piAgents.rest],
+	};
+}
+
+export type McpAddCommandResult = HumanCommandResult & {
+	shouldDelegate: boolean;
+	delegateArgv: string[];
+};
+
+export type RunJcodeMcpAddDependencies = {
+	cwd?: string;
+	home?: string;
+	jcodeHome?: string;
+};
+
+export function runJcodeMcpAddCommand(
+	argv: string[],
+	dependencies: RunJcodeMcpAddDependencies = {},
+): McpAddCommandResult {
+	const jcodeAgents = splitAgentArgs(argv, "jcode");
+	if (!jcodeAgents.hasAgent) {
+		return { exitCode: 0, stdout: "", shouldDelegate: true, delegateArgv: ["mcp", "add", ...argv] };
+	}
+
+	try {
+		const result = registerJcodeMcpServer({
+			global: !jcodeAgents.rest.includes("--no-global"),
+			cwd: dependencies.cwd,
+			home: dependencies.home,
+			jcodeHome: dependencies.jcodeHome,
+		});
+		return {
+			exitCode: 0,
+			stdout: `Registered MCP server '${result.serverName}' for jcode: ${result.path}\n`,
+			shouldDelegate: hasExplicitAgent(jcodeAgents.rest),
+			delegateArgv: ["mcp", "add", ...jcodeAgents.rest],
+		};
+	} catch (err) {
+		return {
+			exitCode: 1,
+			stdout: "",
+			stderr: `${err instanceof Error ? err.message : String(err)}\n`,
+			shouldDelegate: false,
+			delegateArgv: ["mcp", "add", ...jcodeAgents.rest],
+		};
+	}
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./dispatch.ts";
+export * from "./doctor.ts";
+export * from "./human-commands.ts";
+export * from "./jcode-mcp-config.ts";
+export * from "./output.ts";
+export * from "./update.ts";