@nseng-ai/vibechk 0.1.1

package/src/reports.ts

@@ -0,0 +1,342 @@
+import type { RenderCapabilities } from "@nseng-ai/clinkr";
+import { renderTextTable, type TextTableColumn } from "@nseng-ai/foundation/text-table";
+
+import type { ArtifactOutputBounds, LoadedBundle } from "./models.ts";
+import { encodeMetrics } from "./models.ts";
+
+type RenderableBundle = LoadedBundle & {
+	readonly outputBounds?: {
+		readonly plan: ArtifactOutputBounds;
+		readonly transcript: ArtifactOutputBounds;
+		readonly diff: ArtifactOutputBounds;
+	};
+};
+
+type MetricRow = [string, keyof LoadedBundle["bundle"]["metrics"]];
+
+const METRIC_ROWS: MetricRow[] = [
+	["Wall time seconds", "wallTimeSeconds"],
+	["Input tokens", "inputTokens"],
+	["Output tokens", "outputTokens"],
+	["Total tokens", "totalTokens"],
+	["Cost USD", "costUsd"],
+];
+
+const RUNS_TABLE_COLUMNS = [
+	{ header: "RUN ID" },
+	{ header: "STARTED AT" },
+	{ header: "STATUS" },
+	{ header: "RUNNER" },
+	{ header: "MODEL" },
+	{ header: "BRANCH" },
+	{ header: "WORKDIR" },
+] satisfies readonly TextTableColumn[];
+
+export function renderRunReport(loaded: RenderableBundle): string {
+	const bundle = loaded.bundle;
+	const resultBranch = bundle.resultBranch ?? "null";
+	const diffPatch = diffBody(loaded.diffPatch);
+	const transcript = transcriptBody(loaded.transcript);
+
+	const lines = [
+		`# Vibechk Run \`${bundle.runId}\``,
+		"",
+		"## Summary",
+		"",
+		`- Status: ${bundle.status}`,
+		`- Runner: ${bundle.runner}`,
+		`- Model: ${formatValue(bundle.model)}`,
+		`- Workdir: ${bundle.workdir}`,
+		`- Started: ${bundle.startedAt.toISOString()}`,
+		`- Finished: ${bundle.finishedAt.toISOString()}`,
+		`- Starting branch: ${bundle.git.startingBranch}`,
+		`- Starting commit: ${bundle.git.startingCommit}`,
+		`- Result branch: ${resultBranch}`,
+		"",
+		"## Metrics",
+		"",
+		"| Metric | Value |",
+		"| --- | --- |",
+	];
+
+	for (const [label, fieldName] of METRIC_ROWS) {
+		lines.push(`| ${label} | ${formatValue(bundle.metrics[fieldName])} |`);
+	}
+
+	lines.push("", ...renderArtifactBounds(loaded), "");
+
+	lines.push(
+		"<details>",
+		"<summary>Plan</summary>",
+		"",
+		"```markdown",
+		loaded.planText,
+		"```",
+		"",
+		"</details>",
+		"",
+		"<details>",
+		"<summary>Transcript</summary>",
+		"",
+		"```text",
+		transcript,
+		"```",
+		"",
+		"</details>",
+		"",
+		"## Diff",
+		"",
+		"```diff",
+		diffPatch,
+		"```",
+		"",
+	);
+
+	return lines.join("\n");
+}
+
+export function renderRunsTable(
+	loadedBundles: LoadedBundle[],
+	caps: RenderCapabilities = { canEmitAnsi: false },
+): string {
+	return renderTextTable({
+		columns: RUNS_TABLE_COLUMNS,
+		rows: loadedBundles.map((loaded) => runsTableRow(loaded)),
+		canEmitAnsi: caps.canEmitAnsi,
+	});
+}
+
+export function runListEntryToJson(loaded: LoadedBundle): Record<string, unknown> {
+	const bundle = loaded.bundle;
+	return {
+		run_id: bundle.runId,
+		started_at: bundle.startedAt.toISOString(),
+		finished_at: bundle.finishedAt.toISOString(),
+		status: bundle.status,
+		runner: bundle.runner,
+		runner_version: bundle.runnerVersion,
+		model: bundle.model,
+		workdir: bundle.workdir,
+		starting_branch: bundle.git.startingBranch,
+		starting_commit: bundle.git.startingCommit,
+		result_branch: bundle.resultBranch,
+		branch_created: bundle.branchCreated,
+		runner_exit_code: bundle.runnerExitCode,
+		metrics: encodeMetrics(bundle.metrics),
+		run_dir: loaded.runDir,
+	};
+}
+
+export function renderComparisonReport(
+	baseline: RenderableBundle,
+	treatment: RenderableBundle,
+): string {
+	const baselineBundle = baseline.bundle;
+	const treatmentBundle = treatment.bundle;
+
+	const lines = [
+		"# Vibechk Comparison",
+		"",
+		`Baseline: \`${baselineBundle.runId}\`  `,
+		`Treatment: \`${treatmentBundle.runId}\``,
+		"",
+		"## Biggest Metric Deltas",
+		"",
+		deltaBullet(
+			"Wall time seconds",
+			baselineBundle.metrics.wallTimeSeconds,
+			treatmentBundle.metrics.wallTimeSeconds,
+		),
+		deltaBullet(
+			"Total tokens",
+			baselineBundle.metrics.totalTokens,
+			treatmentBundle.metrics.totalTokens,
+		),
+		deltaBullet(
+			"Input tokens",
+			baselineBundle.metrics.inputTokens,
+			treatmentBundle.metrics.inputTokens,
+		),
+		deltaBullet(
+			"Output tokens",
+			baselineBundle.metrics.outputTokens,
+			treatmentBundle.metrics.outputTokens,
+		),
+		deltaBullet("Cost USD", baselineBundle.metrics.costUsd, treatmentBundle.metrics.costUsd),
+		"",
+		"## Configuration",
+		"",
+		"| Field | Baseline | Treatment |",
+		"| --- | --- | --- |",
+		configRow("Runner", baselineBundle.runner, treatmentBundle.runner),
+		configRow("Runner version", baselineBundle.runnerVersion, treatmentBundle.runnerVersion),
+		configRow("Model", baselineBundle.model, treatmentBundle.model),
+		configRow(
+			"Starting branch",
+			baselineBundle.git.startingBranch,
+			treatmentBundle.git.startingBranch,
+		),
+		configRow(
+			"Starting commit",
+			baselineBundle.git.startingCommit,
+			treatmentBundle.git.startingCommit,
+		),
+		configRow("Result branch", baselineBundle.resultBranch, treatmentBundle.resultBranch),
+		"",
+		"## Metrics",
+		"",
+		"| Metric | Baseline | Treatment | Delta |",
+		"| --- | --- | --- | --- |",
+	];
+
+	for (const [label, fieldName] of METRIC_ROWS) {
+		const baselineValue = baselineBundle.metrics[fieldName];
+		const treatmentValue = treatmentBundle.metrics[fieldName];
+		lines.push(
+			`| ${label} | ${formatValue(baselineValue)} | ${formatValue(treatmentValue)} | ${formatDelta(baselineValue, treatmentValue)} |`,
+		);
+	}
+
+	lines.push("", ...renderComparisonArtifactBounds(baseline, treatment), "");
+	lines.push(...renderPlanComparison(baseline.planText, treatment.planText));
+	lines.push(
+		"",
+		"## Baseline Diff",
+		"",
+		"```diff",
+		diffBody(baseline.diffPatch),
+		"```",
+		"",
+		"## Treatment Diff",
+		"",
+		"```diff",
+		diffBody(treatment.diffPatch),
+		"```",
+		"",
+	);
+
+	return lines.join("\n");
+}
+
+function deltaBullet(label: string, baseline: number | null, treatment: number | null): string {
+	if (baseline === null || treatment === null) {
+		return `- ${label}: ${formatValue(baseline)} -> ${formatValue(treatment)} (n/a)`;
+	}
+	const delta = treatment - baseline;
+	const sign = delta >= 0 ? "+" : "";
+	return `- ${label}: ${baseline} -> ${treatment} (${sign}${delta})`;
+}
+
+function formatDelta(baseline: number | null, treatment: number | null): string {
+	if (baseline === null || treatment === null) {
+		return "n/a";
+	}
+	const delta = treatment - baseline;
+	const sign = delta >= 0 ? "+" : "";
+	return `${sign}${delta}`;
+}
+
+function configRow(label: string, baseline: string | null, treatment: string | null): string {
+	return `| ${label} | ${formatValue(baseline)} | ${formatValue(treatment)} |`;
+}
+
+function renderPlanComparison(baselinePlan: string, treatmentPlan: string): string[] {
+	if (baselinePlan === treatmentPlan) {
+		return [
+			"<details>",
+			"<summary>Plan</summary>",
+			"",
+			"```markdown",
+			baselinePlan,
+			"```",
+			"",
+			"</details>",
+		];
+	}
+	return [
+		"> Warning: baseline and treatment plans differ.",
+		"",
+		"<details>",
+		"<summary>Baseline Plan</summary>",
+		"",
+		"```markdown",
+		baselinePlan,
+		"```",
+		"",
+		"</details>",
+		"",
+		"<details>",
+		"<summary>Treatment Plan</summary>",
+		"",
+		"```markdown",
+		treatmentPlan,
+		"```",
+		"",
+		"</details>",
+	];
+}
+
+function renderArtifactBounds(loaded: RenderableBundle): string[] {
+	const bounds = renderArtifactBoundsLines(loaded);
+	if (bounds.length === 0) return [];
+	return ["## Output Bounds", "", ...bounds];
+}
+
+function renderComparisonArtifactBounds(
+	baseline: RenderableBundle,
+	treatment: RenderableBundle,
+): string[] {
+	const lines: string[] = [];
+	const baselineBounds = renderArtifactBoundsLines(baseline, "Baseline");
+	const treatmentBounds = renderArtifactBoundsLines(treatment, "Treatment");
+	if (baselineBounds.length === 0 && treatmentBounds.length === 0) return [];
+	lines.push("## Output Bounds", "");
+	lines.push(...baselineBounds, ...treatmentBounds);
+	return lines;
+}
+
+function renderArtifactBoundsLines(loaded: RenderableBundle, label?: string): string[] {
+	if (loaded.outputBounds === undefined) return [];
+	return Object.values(loaded.outputBounds)
+		.filter((bounds) => !bounds.isComplete)
+		.map((bounds) => formatArtifactBoundsBullet(bounds, label));
+}
+
+function formatArtifactBoundsBullet(
+	bounds: ArtifactOutputBounds,
+	label: string | undefined,
+): string {
+	const labelPrefix = label === undefined ? "" : `${label} `;
+	return `- ${labelPrefix}${artifactLabel(bounds.artifact)} truncated: returned ${bounds.returnedBytes} of ${bounds.originalBytes} bytes (limit ${bounds.appliedByteLimit}). ${bounds.continuation ?? ""}`;
+}
+
+function artifactLabel(artifact: ArtifactOutputBounds["artifact"]): string {
+	if (artifact === "diff") return "diff";
+	if (artifact === "plan") return "plan";
+	return "transcript";
+}
+
+function formatValue(value: string | number | null): string {
+	return value === null ? "null" : String(value);
+}
+
+function runsTableRow(loaded: LoadedBundle): string[] {
+	const bundle = loaded.bundle;
+	return [
+		bundle.runId,
+		bundle.startedAt.toISOString(),
+		bundle.status,
+		bundle.runner,
+		formatValue(bundle.model) === "null" ? "-" : formatValue(bundle.model),
+		bundle.resultBranch ?? "-",
+		bundle.workdir,
+	];
+}
+
+function transcriptBody(transcript: string): string {
+	return transcript === "" ? "_No transcript captured._" : transcript;
+}
+
+function diffBody(diffPatch: string): string {
+	return diffPatch === "" ? "_No workdir changes._" : diffPatch;
+}

package/src/repository.ts

@@ -0,0 +1,174 @@
+import { NodeCommandExecApi } from "@nseng-ai/foundation/exec";
+import {
+	type CommandExecApi,
+	type ExecResult,
+	formatCommand,
+	formatCommandFailure,
+} from "@nseng-ai/foundation/exec";
+import { RealGitGateway } from "@nseng-ai/capability-kit/git";
+import type { GitGateway, GitOperationResult, GitResult } from "@nseng-ai/capability-kit/git";
+
+import { isMissingExecutableError, runVibechkCommand } from "./exec-util.ts";
+import type { GitProvenance } from "./models.ts";
+import { VibechkError } from "./store.ts";
+
+const GIT_TIMEOUT_MS = 10_000;
+
+export interface VibechkWorkdirGateway {
+	readProvenance(): Promise<GitProvenance>;
+	isClean(): Promise<boolean>;
+	diffPatch(): Promise<string>;
+	hasChanges(): Promise<boolean>;
+	createResultBranchAndCommit(branch: string, message: string): Promise<void>;
+	restoreBranch(branch: string): Promise<void>;
+}
+
+export interface RealVibechkWorkdirGatewayOptions {
+	workdir: string;
+	execApi?: CommandExecApi;
+	coreGit?: GitGateway;
+}
+
+export class RealVibechkWorkdirGateway implements VibechkWorkdirGateway {
+	private readonly workdir: string;
+	private readonly execApi: CommandExecApi;
+	private readonly coreGit: GitGateway;
+
+	constructor(options: RealVibechkWorkdirGatewayOptions) {
+		this.workdir = options.workdir;
+		this.execApi = options.execApi ?? new NodeCommandExecApi();
+		this.coreGit = options.coreGit ?? new RealGitGateway(this.execApi);
+	}
+
+	async readProvenance(): Promise<GitProvenance> {
+		return {
+			repoRoot: await this.repoRoot(),
+			startingBranch: await this.currentBranch(),
+			startingCommit: await this.currentCommit(),
+			remotes: await this.remotes(),
+		};
+	}
+
+	async isClean(): Promise<boolean> {
+		return !(await this.hasChanges());
+	}
+
+	async diffPatch(): Promise<string> {
+		if (await this.hasChanges()) {
+			await this.runGit(
+				["add", "-N", "."],
+				`Could not prepare untracked files for diff in ${this.workdir}`,
+			);
+		}
+		return await this.runGit(
+			["diff", "--binary", "HEAD"],
+			`Could not capture git diff in ${this.workdir}`,
+		);
+	}
+
+	async hasChanges(): Promise<boolean> {
+		const result = await this.coreGit.hasUncommittedChangesUnder({
+			cwd: this.workdir,
+			relativePath: ".",
+		});
+		return this.unwrapGitResult(result, `Could not read git status in ${this.workdir}`);
+	}
+
+	async createResultBranchAndCommit(branch: string, message: string): Promise<void> {
+		const branchResult = await this.coreGit.createBranchAtHead({ cwd: this.workdir, branch });
+		this.unwrapGitOperationResult(branchResult, `Could not create result branch ${branch}`);
+		await this.runGit(["switch", branch], `Could not switch to result branch ${branch}`);
+		await this.runGit(["add", "-A"], `Could not stage vibechk changes on ${branch}`);
+		await this.runGit(["commit", "-m", message], `Could not commit vibechk changes on ${branch}`);
+	}
+
+	async restoreBranch(branch: string): Promise<void> {
+		await this.runGit(["switch", branch], `Could not switch back to branch ${branch}`);
+	}
+
+	private async repoRoot(): Promise<string> {
+		const result = await this.coreGit.repoRoot({ cwd: this.workdir });
+		return this.unwrapGitResult(result, `Workdir ${this.workdir} is not a git repository.`);
+	}
+
+	private async currentBranch(): Promise<string> {
+		const result = await this.coreGit.currentBranch({ cwd: this.workdir });
+		if (result.type === "branch") return result.branch;
+		if (result.type === "detached") {
+			throw new VibechkError(
+				`Could not determine current branch in ${this.workdir}\nDetached HEAD.`,
+			);
+		}
+		if (isMissingExecutableError(result.error.message)) {
+			throw new VibechkError("git is not installed or not on PATH.");
+		}
+		throw new VibechkError(
+			`Could not determine current branch in ${this.workdir}\n${result.error.message}`,
+		);
+	}
+
+	private async currentCommit(): Promise<string> {
+		const result = await this.coreGit.headCommit({ cwd: this.workdir });
+		return this.unwrapGitResult(result, `Could not determine current commit in ${this.workdir}`);
+	}
+
+	private async remotes(): Promise<Record<string, string>> {
+		const output = await this.runGit(
+			["remote", "-v"],
+			`Could not list git remotes in ${this.workdir}`,
+		);
+		const remotes: Record<string, string> = {};
+		for (const line of output.split("\n")) {
+			const parts = line.split(/\s+/u);
+			if (
+				parts.length >= 2 &&
+				parts[0] !== undefined &&
+				parts[1] !== undefined &&
+				!(parts[0] in remotes)
+			) {
+				remotes[parts[0]] = parts[1];
+			}
+		}
+		return remotes;
+	}
+
+	private unwrapGitResult<T>(result: GitResult<T>, errorMessage: string): T {
+		if (result.ok) return result.value;
+		if (isMissingExecutableError(result.error.message)) {
+			throw new VibechkError("git is not installed or not on PATH.");
+		}
+		throw new VibechkError(`${errorMessage}\n${result.error.message}`);
+	}
+
+	private unwrapGitOperationResult(result: GitOperationResult, errorMessage: string): void {
+		if (result.ok) return;
+		if (isMissingExecutableError(result.error.message)) {
+			throw new VibechkError("git is not installed or not on PATH.");
+		}
+		throw new VibechkError(`${errorMessage}\n${result.error.message}`);
+	}
+
+	private async runGit(args: readonly string[], errorMessage: string): Promise<string> {
+		const result = await this.runGitRaw(args);
+		if (result.code !== 0 || result.killed) {
+			throw new VibechkError(
+				formatCommandFailure(errorMessage, formatCommand("git", args), result),
+			);
+		}
+		return result.stdout.trim();
+	}
+
+	private async runGitRaw(args: readonly string[]): Promise<ExecResult> {
+		return await runVibechkCommand({
+			execApi: this.execApi,
+			command: "git",
+			args,
+			execOptions: {
+				cwd: this.workdir,
+				timeout: GIT_TIMEOUT_MS,
+			},
+			missingExecutableMessage: "git is not installed or not on PATH.",
+			startupFailurePrefix: "git command failed before completion",
+		});
+	}
+}

package/src/runners.ts

@@ -0,0 +1,126 @@
+import { NodeCommandExecApi } from "@nseng-ai/foundation/exec";
+import type { CommandExecApi, ExecResult } from "@nseng-ai/foundation/exec";
+
+import { runVibechkCommand } from "./exec-util.ts";
+import type { Metrics } from "./models.ts";
+import { VibechkError } from "./store.ts";
+
+export interface RunnerRequest {
+	planText: string;
+	workdir: string;
+	model: string | null;
+	runId: string;
+	artifactsDir: string;
+}
+
+export interface RunnerResult {
+	exitCode: number;
+	transcript: string;
+	metrics: Metrics;
+	artifacts: Record<string, unknown>;
+	runnerVersion: string | null;
+}
+
+export interface Runner {
+	name: string;
+	run(
+		request: RunnerRequest,
+		transcriptSink: (text: string) => void,
+		stdoutSink: (text: string) => void,
+	): Promise<RunnerResult>;
+}
+
+export class RunnerRegistry {
+	private readonly runners: Map<string, Runner>;
+
+	constructor(runners: readonly Runner[]) {
+		this.runners = new Map(runners.map((runner) => [runner.name, runner]));
+	}
+
+	get(name: string): Runner {
+		const runner = this.runners.get(name);
+		if (runner !== undefined) {
+			return runner;
+		}
+		const availableNames = Array.from(this.runners.keys()).sort().join(", ");
+		const available = availableNames === "" ? "none" : availableNames;
+		throw new VibechkError(`Unsupported runner '${name}'. Available runners: ${available}.`);
+	}
+
+	names(): readonly string[] {
+		return Array.from(this.runners.keys()).sort();
+	}
+}
+
+export class ClaudeRunner implements Runner {
+	readonly name = "claude";
+	private readonly execApi: CommandExecApi;
+
+	constructor(execApi: CommandExecApi = new NodeCommandExecApi()) {
+		this.execApi = execApi;
+	}
+
+	async run(
+		request: RunnerRequest,
+		transcriptSink: (text: string) => void,
+		stdoutSink: (text: string) => void,
+	): Promise<RunnerResult> {
+		const command = this.buildCommand(request);
+		const started = performance.now();
+
+		const result = await this.executeCommand(command, request.workdir, transcriptSink, stdoutSink);
+		const wallTimeSeconds = Math.round((performance.now() - started) / 10) / 100;
+
+		return {
+			exitCode: result.code,
+			transcript: "",
+			metrics: {
+				wallTimeSeconds,
+				inputTokens: null,
+				outputTokens: null,
+				totalTokens: null,
+				costUsd: null,
+			},
+			artifacts: {},
+			runnerVersion: null,
+		};
+	}
+
+	private buildCommand(request: RunnerRequest): readonly [string, ...string[]] {
+		const command = ["claude", "--print", "--permission-mode", "acceptEdits"];
+		if (request.model !== null) {
+			command.push("--model", request.model);
+		}
+		command.push(request.planText);
+		return [command[0] ?? "claude", ...command.slice(1)];
+	}
+
+	private async executeCommand(
+		command: readonly [string, ...string[]],
+		workdir: string,
+		transcriptSink: (text: string) => void,
+		stdoutSink: (text: string) => void,
+	): Promise<ExecResult> {
+		const streamText = (text: string): void => {
+			stdoutSink(text);
+			transcriptSink(text);
+		};
+
+		return await runVibechkCommand({
+			execApi: this.execApi,
+			command: command[0],
+			args: command.slice(1),
+			execOptions: {
+				cwd: workdir,
+				onStdout: streamText,
+				onStderr: streamText,
+			},
+			missingExecutableMessage: "Runner 'claude' is not installed or not on PATH.",
+			startupFailurePrefix: "Runner 'claude' failed to start",
+		});
+	}
+}
+
+export function buildProductionRunnerRegistry(): RunnerRegistry {
+	return new RunnerRegistry([new ClaudeRunner()]);
+}