@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/cli/fleet-graph.ts

@@ -0,0 +1,102 @@
+import type { ExecutionPlanStep } from "../domains/dispatch/execution-plan.js";
+import { inspectFleet } from "./fleet-preflight.js";
+
+/**
+ * The contract-level kind of a compiled step. The execution plan knows only
+ * `agent` and `code`; a version 5 `gate` or `plan` step compiles to an agent
+ * step carrying `gate` or `plan` facts, and the graph names it as the author
+ * wrote it.
+ */
+function contractKind(step: ExecutionPlanStep): "agent" | "code" | "gate" | "plan" {
+	if (step.kind === "code") return "code";
+	if (step.gate !== undefined) return "gate";
+	if (step.plan !== undefined) return "plan";
+	return "agent";
+}
+
+function projectedStep(step: ExecutionPlanStep): Record<string, unknown> {
+	return {
+		id: step.id,
+		kind: contractKind(step),
+		...(step.kind === "agent" ? { agent: step.agentId } : { command: step.commandId }),
+		...(step.kind === "agent" && step.gate !== undefined
+			? { gate: { path: step.gate.path, command: step.gate.commandId } }
+			: {}),
+		...(step.kind === "agent" && step.plan !== undefined
+			? { plan: { roster: [...step.plan.roster], maxTasks: step.plan.maxTasks, proposals: step.plan.proposals } }
+			: {}),
+		...(step.kind === "agent" && step.target !== undefined ? { target: step.target } : {}),
+		...(step.kind === "agent" && step.profile !== undefined ? { profile: step.profile } : {}),
+		scope: step.scope,
+		writes: [...(step.writes ?? [])],
+		dependencies: [...step.dependencies],
+	};
+}
+
+export function runFleetGraph(args: ReadonlyArray<string>): number {
+	const json = args.includes("--json");
+	const name = args.find((arg) => !arg.startsWith("-"));
+	const unknown = args.find((arg, index) => (arg.startsWith("-") && arg !== "--json") || index > 1);
+	if (name === undefined || unknown !== undefined) {
+		process.stderr.write("clio-coder fleet: graph: usage: clio-coder fleet graph <name> [--json]\n");
+		return 2;
+	}
+	try {
+		const { plan } = inspectFleet(name);
+		const byId = new Map(plan.steps.map((step) => [step.id, step]));
+		const waves = plan.waves.map((ids, index) => ({
+			wave: index + 1,
+			steps: ids.flatMap((id) => {
+				const step = byId.get(id);
+				return step === undefined ? [] : [projectedStep(step)];
+			}),
+		}));
+		const loops = plan.loops.map((loop) => ({
+			id: loop.id,
+			check: loop.checkStepIds.map((id) => projectedStep(byId.get(id) as ExecutionPlanStep)),
+			repair: loop.repairStepIds.map((id) => projectedStep(byId.get(id) as ExecutionPlanStep)),
+		}));
+		if (json) {
+			process.stdout.write(`${JSON.stringify({ fleet: name, planHash: plan.hash, waves, loops }, null, 2)}\n`);
+			return 0;
+		}
+		for (const wave of waves) {
+			process.stdout.write(`wave ${wave.wave}\n`);
+			for (const step of wave.steps) {
+				const subject = step.kind === "code" ? `command=${step.command}` : `agent=${step.agent}`;
+				const gate = step.gate as { path: string; command: string } | undefined;
+				const plan = step.plan as { roster: string[]; maxTasks: number; proposals: boolean } | undefined;
+				const detail =
+					gate !== undefined
+						? ` gate=${gate.path} run=${gate.command}`
+						: plan !== undefined
+							? ` roster=${JSON.stringify(plan.roster)} maxTasks=${plan.maxTasks}${plan.proposals ? " proposals" : ""}`
+							: "";
+				const route =
+					step.target !== undefined
+						? ` target=${step.target}`
+						: step.profile !== undefined
+							? ` profile=${step.profile}`
+							: "";
+				process.stdout.write(
+					`  ${step.id} kind=${step.kind} ${subject}${route} scope=${step.scope} writes=${JSON.stringify(step.writes)}${detail}\n`,
+				);
+			}
+		}
+		for (const loop of loops) {
+			process.stdout.write(`loop ${loop.id}\n`);
+			for (const step of loop.check)
+				process.stdout.write(
+					`  check ${step.id} kind=${step.kind} scope=${step.scope} writes=${JSON.stringify(step.writes)}\n`,
+				);
+			for (const step of loop.repair)
+				process.stdout.write(
+					`  repair ${step.id} kind=${step.kind} scope=${step.scope} writes=${JSON.stringify(step.writes)}\n`,
+				);
+		}
+		return 0;
+	} catch (error) {
+		process.stderr.write(`clio-coder fleet: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+}

package/src/cli/fleet-new.ts

@@ -0,0 +1,36 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolvePackageRoot } from "../core/package-root.js";
+
+const BUILTINS = ["build-review", "build-test", "sdlc"] as const;
+const SAFE_STEM = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u;
+
+function usage(message: string): number {
+	process.stderr.write(`clio-coder fleet: new: ${message}\n`);
+	return 2;
+}
+
+export function runFleetNew(args: ReadonlyArray<string>): number {
+	const name = args[0];
+	const fromIndex = args.indexOf("--from");
+	const builtin = fromIndex === -1 ? undefined : args[fromIndex + 1];
+	const known = BUILTINS.join(", ");
+	if (name === undefined) return usage("usage: clio-coder fleet new <name> --from <builtin>");
+	if (!SAFE_STEM.test(name)) return usage(`'${name}' is not a safe file stem`);
+	if (fromIndex === -1 || builtin === undefined) return usage("--from <builtin> is required");
+	const expected = new Set([name, "--from", builtin]);
+	const unknown = args.find((arg) => !expected.has(arg));
+	if (unknown !== undefined) return usage(`unknown argument: ${unknown}`);
+	if (!(BUILTINS as ReadonlyArray<string>).includes(builtin)) {
+		return usage(`unknown builtin '${builtin}'. Known builtins: ${known}`);
+	}
+	const destination = join(process.cwd(), ".clio-coder", "fleets", `${name}.md`);
+	if (existsSync(destination)) return usage(`destination already exists: ${destination}`);
+	const source = join(resolvePackageRoot(), "src", "domains", "agents", "fleets", `${builtin}.md`);
+	mkdirSync(dirname(destination), { recursive: true });
+	const sourceText = readFileSync(source, "utf8");
+	const renamed = sourceText.replace(/^name:\s*[^\n]+$/mu, `name: ${name}`);
+	writeFileSync(destination, renamed, { flag: "wx" });
+	process.stdout.write(`${destination}\n`);
+	return 0;
+}

package/src/cli/fleet-preflight.ts

@@ -0,0 +1,121 @@
+import { join } from "node:path";
+import { readSettings } from "../core/config.js";
+import { resolvePackageRoot } from "../core/package-root.js";
+import { clioConfigDir } from "../core/xdg.js";
+import {
+	type FleetCommandRegistry,
+	type FleetContract,
+	loadFleetCommands,
+	loadFleetContract,
+	renderFleetPrompt,
+} from "../domains/agents/index.js";
+import { type AgentRecipeDiagnostic, loadRecipesFromDir, mergeRecipes } from "../domains/agents/registry.js";
+import { type AgentSpec, normalizeAgentSpec } from "../domains/agents/spec.js";
+import type { ExecutionPlan } from "../domains/dispatch/execution-plan.js";
+import { requestExecutionRole, withAttemptRole } from "../domains/dispatch/execution-role.js";
+import { compileFleetExecutionPlan } from "../domains/dispatch/fleet-plan.js";
+
+export interface FleetPreflightResult {
+	contract: FleetContract;
+	commands: FleetCommandRegistry | null;
+	plan: ExecutionPlan;
+	checks: ReadonlyArray<{ check: "parse" | "graph" | "commands" | "agents" | "plan"; summary: string }>;
+}
+
+function discoverSpecs(cwd: string): AgentSpec[] {
+	const diagnostics: AgentRecipeDiagnostic[] = [];
+	const builtin = loadRecipesFromDir(
+		{ dir: join(resolvePackageRoot(), "src", "domains", "agents", "builtins"), source: "builtin" },
+		diagnostics,
+	);
+	const user = loadRecipesFromDir({ dir: join(clioConfigDir(), "agents"), source: "user" }, diagnostics);
+	const project = loadRecipesFromDir({ dir: join(cwd, ".clio-coder", "agents"), source: "project" }, diagnostics);
+	return mergeRecipes(builtin, user, project).map(normalizeAgentSpec);
+}
+
+export function inspectFleet(name: string, vars?: Readonly<Record<string, string>>): FleetPreflightResult {
+	const cwd = process.cwd();
+	const contract = loadFleetContract(cwd, name);
+	const commands = loadFleetCommands(cwd);
+	const prompt = vars === undefined ? contract.body : renderFleetPrompt(contract.body, vars);
+	const specs = discoverSpecs(cwd);
+	const byId = new Map(specs.map((spec) => [spec.id, spec]));
+	const resolved = new Set<string>();
+	const settings = readSettings();
+	const targetIds = new Set(settings.targets.map((target) => target.id));
+	const profileIds = new Set(Object.keys(settings.workers?.profiles ?? {}));
+	for (const step of contract.steps) {
+		const positions =
+			step.kind === "loop"
+				? [
+						...(step.check.kind === "agent" ? [{ id: `${step.id}.check`, route: step.check }] : []),
+						{ id: `${step.id}.repair`, route: step.repair },
+					]
+				: step.kind === "agent" || step.kind === "gate" || step.kind === "plan"
+					? [{ id: step.id, route: step }]
+					: [];
+		for (const position of positions) {
+			if (position.route.target !== undefined && !targetIds.has(position.route.target)) {
+				throw new Error(`unknown target '${position.route.target}' at step '${position.id}'`);
+			}
+			if (position.route.profile !== undefined && !profileIds.has(position.route.profile)) {
+				throw new Error(`unknown profile '${position.route.profile}' at step '${position.id}'`);
+			}
+		}
+	}
+	const plan = compileFleetExecutionPlan({
+		contract,
+		task: prompt,
+		resolveAgent(context) {
+			const spec = byId.get(context.agentId);
+			if (spec === undefined) {
+				throw new Error(
+					`unknown agent '${context.agentId}' (step '${context.stepId}' must name a recipe from 'clio-coder agents')`,
+				);
+			}
+			if (spec.capabilityClass === "orchestration" || spec.capabilityClass === "internal") {
+				throw new Error(`fleet step '${context.stepId}' has no automatable agent authority`);
+			}
+			resolved.add(spec.id);
+			const role = requestExecutionRole({
+				agentId: spec.id,
+				resolveFacts: (id) => {
+					const found = byId.get(id);
+					return found === undefined
+						? null
+						: {
+								category: found.category,
+								capabilityClass: found.capabilityClass,
+								resultContractKind: found.resultContract.kind,
+							};
+				},
+				...(context.gateRole === undefined ? {} : { gateRole: context.gateRole }),
+			});
+			return {
+				requestedAuthority: spec.capabilityClass,
+				approvedAuthority: spec.capabilityClass,
+				expectedResultContract:
+					context.planRole === true
+						? "delegation-plan"
+						: context.gateAuthorRole === true
+							? "artifact-report"
+							: context.gateRole === "reviewer"
+								? "verifier-report"
+								: spec.resultContract.kind,
+				executionRole: withAttemptRole(role, context.attempt),
+			};
+		},
+	});
+	return {
+		contract,
+		commands,
+		plan,
+		checks: [
+			{ check: "parse", summary: `parsed contract version ${contract.version}` },
+			{ check: "graph", summary: `validated ${contract.steps.length} declared steps` },
+			{ check: "commands", summary: `validated ${plan.steps.filter((step) => step.kind === "code").length} code steps` },
+			{ check: "agents", summary: `resolved ${resolved.size} agents` },
+			{ check: "plan", summary: `compiled ${plan.steps.length} plan steps with hash ${plan.hash}` },
+		],
+	};
+}

package/src/cli/fleet-validate.ts

@@ -0,0 +1,30 @@
+import { FLEET_COMMANDS_REMEDY, FleetCommandRegistryMissingError } from "../domains/agents/index.js";
+import { preflightWriteBoundaries } from "../domains/dispatch/write-boundary-enforcer.js";
+import { inspectFleet } from "./fleet-preflight.js";
+
+export function runFleetValidate(args: ReadonlyArray<string>): number {
+	const json = args.includes("--json");
+	const unknown = args.find((arg, index) => (arg.startsWith("-") && arg !== "--json") || index > 1);
+	const name = args.find((arg) => !arg.startsWith("-"));
+	if (name === undefined || unknown !== undefined) {
+		process.stderr.write("clio-coder fleet: validate: usage: clio-coder fleet validate <name> [--json]\n");
+		return 2;
+	}
+	try {
+		const result = inspectFleet(name);
+		preflightWriteBoundaries(result.plan, process.cwd());
+		if (json)
+			process.stdout.write(
+				`${JSON.stringify({ valid: true, fleet: name, checks: result.checks, planHash: result.plan.hash }, null, 2)}\n`,
+			);
+		else for (const check of result.checks) process.stdout.write(`${check.check}: ${check.summary}\n`);
+		return 0;
+	} catch (error) {
+		const raw = error instanceof Error ? error.message : String(error);
+		const message = raw.startsWith("unknown agent '") ? `preflight failed: ${raw}` : raw;
+		const diagnostics = [message, ...(error instanceof FleetCommandRegistryMissingError ? [FLEET_COMMANDS_REMEDY] : [])];
+		if (json) process.stdout.write(`${JSON.stringify({ valid: false, fleet: name, diagnostics }, null, 2)}\n`);
+		else process.stderr.write(`clio-coder fleet: ${diagnostics.join("\n  ")}\n`);
+		return 1;
+	}
+}