@nseng-ai/vibechk 0.1.1

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@nseng-ai/vibechk",
+	"version": "0.1.1",
+	"type": "module",
+	"files": [
+		"src"
+	],
+	"engines": {
+		"node": ">=24.12.0",
+		"pnpm": ">=11.8.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"bin": {
+		"vibechk": "src/cli.ts"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"dependencies": {
+		"@nseng-ai/capability-kit": "0.1.1",
+		"@nseng-ai/clinkr": "0.1.1",
+		"@nseng-ai/foundation": "0.1.1",
+		"zod": "^4.4.3"
+	}
+}

package/src/cli.ts

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+
+import {
+	ClinkrGroup,
+	failure,
+	negative,
+	ok,
+	usageError,
+	type ClinkrExit,
+	type ClinkrFailureExit,
+	type ClinkrNegativeExit,
+	type ClinkrUsageErrorExit,
+	type RenderCapabilities,
+} from "@nseng-ai/clinkr";
+import { rawCommand } from "@nseng-ai/clinkr/raw";
+import { defineCli, type CliEntrypointDeps } from "@nseng-ai/foundation/cli-runtime";
+import { z } from "zod";
+
+import type { ArtifactOutputBounds, LoadedBundle } from "./models.ts";
+import {
+	renderComparisonReport,
+	renderRunReport,
+	renderRunsTable,
+	runListEntryToJson,
+} from "./reports.ts";
+import { listBundles, readBundle, resolveStoreRoot, VibechkError } from "./store.ts";
+import type { VibechkWorkdirGateway } from "./repository.ts";
+import { RealVibechkWorkdirGateway } from "./repository.ts";
+import { buildProductionRunnerRegistry, type RunnerRegistry } from "./runners.ts";
+import { generateRunId } from "./ids.ts";
+import { executeRun } from "./workflow.ts";
+export interface CliDeps extends CliEntrypointDeps {
+	runnerRegistry?: RunnerRegistry;
+	repositoryGatewayFactory?: (workdir: string) => VibechkWorkdirGateway;
+	clock?: () => Date;
+	idGenerator?: () => string;
+	defaultRunnerName?: string;
+}
+
+interface VibechkCliContext {
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	runnerRegistry: RunnerRegistry;
+	repositoryGatewayFactory: (workdir: string) => VibechkWorkdirGateway;
+	clock: () => Date;
+	idGenerator: () => string;
+	defaultRunnerName: string;
+	stdout: (text: string) => void;
+	stderr: (text: string) => void;
+}
+
+const DEFAULT_RUNS_LIMIT = 50;
+const DEFAULT_ARTIFACT_BYTE_LIMIT = 200_000;
+
+const runsRequestSchema = z.object({
+	store: z.string().optional(),
+	outputFormat: z.enum(["table", "json"]).default("table"),
+	maxRuns: z.number().int().positive().default(DEFAULT_RUNS_LIMIT),
+});
+
+const showRequestSchema = z.object({
+	idOrPrefix: z.string(),
+	store: z.string().optional(),
+	maxArtifactBytes: z.number().int().positive().default(DEFAULT_ARTIFACT_BYTE_LIMIT),
+});
+
+const diffRequestSchema = z.object({
+	baselineId: z.string(),
+	treatmentId: z.string(),
+	store: z.string().optional(),
+	maxArtifactBytes: z.number().int().positive().default(DEFAULT_ARTIFACT_BYTE_LIMIT),
+});
+
+const runRequestSchema = z.object({
+	plan: z.string(),
+	workdir: z.string().default("."),
+	runner: z.string().optional(),
+	model: z.string().optional(),
+	store: z.string().optional(),
+});
+
+const entry = defineCli<VibechkCliContext, CliDeps, undefined>({
+	metaUrl: import.meta.url,
+	runtime: "typescript",
+	description: "Run lightweight agent context evals and publish Markdown evidence.",
+	prepareRun: ({ args, deps, cwd, env, stdout, stderr }) => {
+		const runnerRegistry = deps.runnerRegistry ?? buildProductionRunnerRegistry();
+		const repositoryGatewayFactory =
+			deps.repositoryGatewayFactory ??
+			((workdir: string) => new RealVibechkWorkdirGateway({ workdir }));
+		const clock = deps.clock ?? (() => new Date());
+		const idGenerator = deps.idGenerator ?? generateRunId;
+		const defaultRunnerName = deps.defaultRunnerName ?? "claude";
+		const context: VibechkCliContext = {
+			cwd,
+			env,
+			runnerRegistry,
+			repositoryGatewayFactory,
+			clock,
+			idGenerator,
+			defaultRunnerName,
+			stdout: deps.stdout ?? stdout,
+			stderr: deps.stderr ?? stderr,
+		};
+		return {
+			type: "run",
+			context,
+			buildState: undefined,
+			args: normalizeRunsFormatArgs(args),
+		};
+	},
+	configureCli: ({ root }) => {
+		root.command({
+			name: "runs",
+			description: "List local vibechk run bundles from the configured store.",
+			schema: runsRequestSchema,
+			handler: runRuns,
+			renderHuman: renderRuns,
+		});
+
+		root.command({
+			name: "show",
+			description: "Render a Markdown report for a single run.",
+			schema: showRequestSchema,
+			positionals: {
+				idOrPrefix: { position: 0 },
+			},
+			handler: runShow,
+			renderHuman: renderShow,
+		});
+
+		root.command({
+			name: "diff",
+			description: "Render a Markdown comparison report for two runs.",
+			schema: diffRequestSchema,
+			positionals: {
+				baselineId: { position: 0 },
+				treatmentId: { position: 1 },
+			},
+			handler: runDiff,
+			renderHuman: renderDiff,
+		});
+
+		root.command(
+			rawCommand({
+				name: "run",
+				description: "Run a plan in a clean git workdir and persist a local run bundle.",
+				schema: runRequestSchema,
+				run: runRun,
+			}),
+		);
+	},
+	handleRunError: ({ error, stderr }) => {
+		if (error instanceof VibechkError) {
+			stderr(`Error: ${error.message}\n`);
+			return 1;
+		}
+	},
+});
+
+export const VERSION = entry.version;
+
+export function buildCli(): ClinkrGroup<VibechkCliContext> {
+	return entry.buildCli(undefined);
+}
+
+type RunsRequest = z.infer<typeof runsRequestSchema>;
+type ShowRequest = z.infer<typeof showRequestSchema>;
+type DiffRequest = z.infer<typeof diffRequestSchema>;
+type RunRequest = z.infer<typeof runRequestSchema>;
+
+interface RunsOutputBounds {
+	kind: "runs-list";
+	appliedLimit: number;
+	returnedCount: number;
+	totalCount: number;
+	isComplete: boolean;
+	continuation: string | null;
+}
+
+type BoundedBundle = Omit<LoadedBundle, "planText" | "transcript" | "diffPatch"> & {
+	planText: string;
+	transcript: string;
+	diffPatch: string;
+	outputBounds: {
+		plan: ArtifactOutputBounds;
+		transcript: ArtifactOutputBounds;
+		diff: ArtifactOutputBounds;
+	};
+};
+
+type RunsResult =
+	| { type: "json"; entries: unknown[]; outputBounds: RunsOutputBounds }
+	| { type: "table"; loaded: LoadedBundle[]; outputBounds: RunsOutputBounds };
+type VibechkReadOnlyErrorData = {
+	type: "lookup-error";
+	idOrPrefix?: unknown;
+	matches?: unknown;
+};
+type ShowResult = { loaded: BoundedBundle } | VibechkReadOnlyErrorData;
+type DiffResult = { baseline: BoundedBundle; treatment: BoundedBundle } | VibechkReadOnlyErrorData;
+
+async function runRuns(ctx: VibechkCliContext, request: RunsRequest) {
+	const storeRoot = resolveStoreRoot(request.store, ctx.env);
+	const loaded = await listBundles(storeRoot);
+	const bounded = loaded.slice(0, request.maxRuns);
+	const outputBounds = runsOutputBounds({
+		returnedCount: bounded.length,
+		totalCount: loaded.length,
+		appliedLimit: request.maxRuns,
+	});
+
+	if (request.outputFormat === "json") {
+		return ok<RunsResult>({
+			type: "json",
+			entries: bounded.map(runListEntryToJson),
+			outputBounds,
+		});
+	}
+	return ok<RunsResult>({ type: "table", loaded: bounded, outputBounds });
+}
+
+function renderRuns(result: RunsResult, caps: RenderCapabilities = { canEmitAnsi: false }): string {
+	if (result.type === "json") {
+		return JSON.stringify({ entries: result.entries, outputBounds: result.outputBounds });
+	}
+	if (result.loaded.length === 0) {
+		return "No vibechk runs found.";
+	}
+	const table = renderRunsTable(result.loaded, caps);
+	if (result.outputBounds.isComplete) return table;
+	return `${table}\n${result.outputBounds.continuation ?? "More runs are available."}`;
+}
+
+async function runShow(
+	ctx: VibechkCliContext,
+	request: ShowRequest,
+): Promise<ClinkrExit<ShowResult>> {
+	try {
+		const storeRoot = resolveStoreRoot(request.store, ctx.env);
+		const loaded = await readBundle(storeRoot, request.idOrPrefix);
+		return ok<ShowResult>({ loaded: boundBundleArtifacts(loaded, request.maxArtifactBytes) });
+	} catch (error) {
+		return vibechkReadOnlyErrorExit(error);
+	}
+}
+
+function renderShow(
+	result: ShowResult,
+	_caps: RenderCapabilities = { canEmitAnsi: false },
+): string {
+	if (!("loaded" in result)) return result.type;
+	return renderRunReport(result.loaded);
+}
+
+async function runDiff(
+	ctx: VibechkCliContext,
+	request: DiffRequest,
+): Promise<ClinkrExit<DiffResult>> {
+	try {
+		const storeRoot = resolveStoreRoot(request.store, ctx.env);
+		const baseline = await readBundle(storeRoot, request.baselineId);
+		const treatment = await readBundle(storeRoot, request.treatmentId);
+		return ok<DiffResult>({
+			baseline: boundBundleArtifacts(baseline, request.maxArtifactBytes),
+			treatment: boundBundleArtifacts(treatment, request.maxArtifactBytes),
+		});
+	} catch (error) {
+		return vibechkReadOnlyErrorExit(error);
+	}
+}
+
+function renderDiff(
+	result: DiffResult,
+	_caps: RenderCapabilities = { canEmitAnsi: false },
+): string {
+	if (!("baseline" in result)) return result.type;
+	return renderComparisonReport(result.baseline, result.treatment);
+}
+
+function runsOutputBounds(options: {
+	readonly returnedCount: number;
+	readonly totalCount: number;
+	readonly appliedLimit: number;
+}): RunsOutputBounds {
+	const isComplete = options.returnedCount >= options.totalCount;
+	return {
+		kind: "runs-list",
+		appliedLimit: options.appliedLimit,
+		returnedCount: options.returnedCount,
+		totalCount: options.totalCount,
+		isComplete,
+		continuation: isComplete
+			? null
+			: `Showing ${options.returnedCount} of ${options.totalCount} runs. Re-run with --max-runs ${options.totalCount} or use a narrower store.`,
+	};
+}
+
+function boundBundleArtifacts(loaded: LoadedBundle, maxArtifactBytes: number): BoundedBundle {
+	const plan = boundArtifact(loaded.planText, "plan", maxArtifactBytes);
+	const transcript = boundArtifact(loaded.transcript, "transcript", maxArtifactBytes);
+	const diff = boundArtifact(loaded.diffPatch, "diff", maxArtifactBytes);
+	return {
+		...loaded,
+		planText: plan.text,
+		transcript: transcript.text,
+		diffPatch: diff.text,
+		outputBounds: {
+			plan: plan.outputBounds,
+			transcript: transcript.outputBounds,
+			diff: diff.outputBounds,
+		},
+	};
+}
+
+function boundArtifact(
+	text: string,
+	artifact: ArtifactOutputBounds["artifact"],
+	maxArtifactBytes: number,
+): { text: string; outputBounds: ArtifactOutputBounds } {
+	const originalBytes = Buffer.byteLength(text, "utf-8");
+	if (originalBytes <= maxArtifactBytes) {
+		return {
+			text,
+			outputBounds: {
+				kind: "artifact",
+				artifact,
+				appliedByteLimit: maxArtifactBytes,
+				originalBytes,
+				returnedBytes: originalBytes,
+				isComplete: true,
+				continuation: null,
+			},
+		};
+	}
+
+	const boundedText = textByByteLimit(text, maxArtifactBytes);
+	return {
+		text: boundedText,
+		outputBounds: {
+			kind: "artifact",
+			artifact,
+			appliedByteLimit: maxArtifactBytes,
+			originalBytes,
+			returnedBytes: Buffer.byteLength(boundedText, "utf-8"),
+			isComplete: false,
+			continuation: `${artifact} was truncated to ${maxArtifactBytes} bytes. Re-run with --max-artifact-bytes ${originalBytes} or inspect the run directory directly.`,
+		},
+	};
+}
+
+function textByByteLimit(text: string, maxBytes: number): string {
+	let bytes = 0;
+	let endIndex = 0;
+	for (const character of text) {
+		const nextBytes = bytes + Buffer.byteLength(character, "utf-8");
+		if (nextBytes > maxBytes) break;
+		bytes = nextBytes;
+		endIndex += character.length;
+	}
+	return text.slice(0, endIndex);
+}
+
+function vibechkReadOnlyErrorExit(
+	error: unknown,
+): ClinkrNegativeExit<VibechkReadOnlyErrorData> | ClinkrFailureExit | ClinkrUsageErrorExit {
+	if (!(error instanceof VibechkError)) throw error;
+	if (error.code === "run_not_found" || error.code === "ambiguous_run") {
+		return negative(error.message, { data: vibechkReadOnlyErrorData(error.data) });
+	}
+	if (error.code === "store_config_error") return usageError(error.message, error.data);
+	return failure(error.code, error.message, error.data);
+}
+
+function vibechkReadOnlyErrorData(data: Record<string, unknown>): VibechkReadOnlyErrorData {
+	return {
+		type: "lookup-error",
+		...(data["idOrPrefix"] === undefined ? {} : { idOrPrefix: data["idOrPrefix"] }),
+		...(data["matches"] === undefined ? {} : { matches: data["matches"] }),
+	};
+}
+
+async function runRun(ctx: VibechkCliContext, request: RunRequest): Promise<number> {
+	const runnerName = request.runner ?? ctx.defaultRunnerName;
+	const runner = ctx.runnerRegistry.get(runnerName);
+	const repository = ctx.repositoryGatewayFactory(request.workdir);
+
+	const result = await executeRun({
+		planPath: request.plan,
+		workdir: request.workdir,
+		runnerName,
+		model: request.model ?? null,
+		store: request.store,
+		env: ctx.env,
+		deps: {
+			runner,
+			repository,
+			clock: ctx.clock,
+			idGenerator: ctx.idGenerator,
+			stdout: ctx.stdout,
+			stderr: ctx.stderr,
+		},
+	});
+
+	ctx.stdout(`Run ID: ${result.runId}\n`);
+	return result.exitCode;
+}
+
+export async function runCli(args: readonly string[], deps: CliDeps = {}): Promise<number> {
+	return await entry.run(args, deps);
+}
+
+function normalizeRunsFormatArgs(args: readonly string[]): readonly string[] {
+	if (args[0] !== "runs") return args;
+	// `runs` exposes a domain outputFormat choice (`table|json`) to avoid colliding with
+	// Clinkr's global `--format human|json|markdown`; keep the old `runs --format` alias.
+	const normalized: string[] = [];
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === undefined) continue;
+		if (arg === "--format") {
+			normalized.push("--output-format");
+			continue;
+		}
+		if (arg.startsWith("--format=")) {
+			normalized.push(`--output-format=${arg.slice("--format=".length)}`);
+			continue;
+		}
+		normalized.push(arg);
+	}
+	return normalized;
+}
+
+await entry.runIfMain({ isImportMetaMain: import.meta.main });

package/src/exec-util.ts

@@ -0,0 +1,37 @@
+import type { CommandExecApi, ExecOptions, ExecResult } from "@nseng-ai/foundation/exec";
+
+import { VibechkError } from "./store.ts";
+
+export interface RunVibechkCommandOptions {
+	readonly execApi: CommandExecApi;
+	readonly command: string;
+	readonly args: readonly string[];
+	readonly execOptions?: ExecOptions;
+	readonly missingExecutableMessage: string;
+	readonly startupFailurePrefix: string;
+}
+
+export async function runVibechkCommand(options: RunVibechkCommandOptions): Promise<ExecResult> {
+	let result: ExecResult;
+	try {
+		result = await options.execApi.exec(options.command, [...options.args], options.execOptions);
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw commandStartupError(options, message);
+	}
+	if (result.startupError !== undefined) {
+		throw commandStartupError(options, result.startupError);
+	}
+	return result;
+}
+
+export function isMissingExecutableError(message: string): boolean {
+	return message.includes("ENOENT");
+}
+
+function commandStartupError(options: RunVibechkCommandOptions, message: string): VibechkError {
+	if (isMissingExecutableError(message)) {
+		return new VibechkError(options.missingExecutableMessage);
+	}
+	return new VibechkError(`${options.startupFailurePrefix}: ${message}`);
+}

package/src/ids.ts

@@ -0,0 +1,12 @@
+export function generateRunId(): string {
+	const hex = randomHex(4);
+	return hex.toLowerCase();
+}
+
+function randomHex(bytes: number): string {
+	const array = new Uint8Array(bytes);
+	crypto.getRandomValues(array);
+	return Array.from(array)
+		.map((byte) => byte.toString(16).padStart(2, "0"))
+		.join("");
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { buildCli, runCli, VERSION } from "./cli.ts";
+export type { CliDeps } from "./cli.ts";
+export type { GitProvenance, LoadedBundle, Metrics, RunBundle, RunStatus } from "./models.ts";
+export { parseRunBundle } from "./models.ts";
+export {
+	renderComparisonReport,
+	renderRunReport,
+	renderRunsTable,
+	runListEntryToJson,
+} from "./reports.ts";
+export { listBundles, readBundle, resolveStoreRoot, VibechkError } from "./store.ts";

package/src/models.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+
+export type RunStatus = "success" | "failed";
+
+export interface Metrics {
+	wallTimeSeconds: number | null;
+	inputTokens: number | null;
+	outputTokens: number | null;
+	totalTokens: number | null;
+	costUsd: number | null;
+}
+
+export interface GitProvenance {
+	repoRoot: string;
+	startingBranch: string;
+	startingCommit: string;
+	remotes: Record<string, string>;
+}
+
+export interface RunBundle {
+	schemaVersion: number;
+	runId: string;
+	status: RunStatus;
+	startedAt: Date;
+	finishedAt: Date;
+	runner: string;
+	runnerVersion: string | null;
+	model: string | null;
+	planSource: string;
+	workdir: string;
+	git: GitProvenance;
+	metrics: Metrics;
+	resultBranch: string | null;
+	branchCreated: boolean;
+	runnerExitCode: number;
+	error: string | null;
+}
+
+export interface LoadedBundle {
+	bundle: RunBundle;
+	runDir: string;
+	planText: string;
+	transcript: string;
+	diffPatch: string;
+}
+
+export interface ArtifactOutputBounds {
+	kind: "artifact";
+	artifact: "plan" | "transcript" | "diff";
+	appliedByteLimit: number;
+	originalBytes: number;
+	returnedBytes: number;
+	isComplete: boolean;
+	continuation: string | null;
+}
+
+// Zod schema for parsing bundle.json with snake_case keys
+const metricsSchema = z.object({
+	wall_time_seconds: z.number().nullable(),
+	input_tokens: z.number().int().nullable(),
+	output_tokens: z.number().int().nullable(),
+	total_tokens: z.number().int().nullable(),
+	cost_usd: z.number().nullable(),
+});
+
+const gitProvenanceSchema = z.object({
+	repo_root: z.string(),
+	starting_branch: z.string(),
+	starting_commit: z.string(),
+	remotes: z.record(z.string(), z.string()),
+});
+
+const runBundleSchema = z.object({
+	schema_version: z.number().int(),
+	run_id: z.string(),
+	status: z.enum(["success", "failed"]),
+	started_at: z.string(),
+	finished_at: z.string(),
+	runner: z.string(),
+	runner_version: z.string().nullable(),
+	model: z.string().nullable(),
+	plan_source: z.string(),
+	workdir: z.string(),
+	git: gitProvenanceSchema,
+	metrics: metricsSchema,
+	result_branch: z.string().nullable(),
+	branch_created: z.boolean(),
+	runner_exit_code: z.number().int(),
+	error: z.string().nullable(),
+});
+
+export type RunBundleJson = z.input<typeof runBundleSchema>;
+
+export function encodeMetrics(metrics: Metrics): z.input<typeof metricsSchema> {
+	return {
+		wall_time_seconds: metrics.wallTimeSeconds,
+		input_tokens: metrics.inputTokens,
+		output_tokens: metrics.outputTokens,
+		total_tokens: metrics.totalTokens,
+		cost_usd: metrics.costUsd,
+	};
+}
+
+export function encodeRunBundle(bundle: RunBundle): RunBundleJson {
+	return {
+		schema_version: bundle.schemaVersion,
+		run_id: bundle.runId,
+		status: bundle.status,
+		started_at: bundle.startedAt.toISOString(),
+		finished_at: bundle.finishedAt.toISOString(),
+		runner: bundle.runner,
+		runner_version: bundle.runnerVersion,
+		model: bundle.model,
+		plan_source: bundle.planSource,
+		workdir: bundle.workdir,
+		git: {
+			repo_root: bundle.git.repoRoot,
+			starting_branch: bundle.git.startingBranch,
+			starting_commit: bundle.git.startingCommit,
+			remotes: bundle.git.remotes,
+		},
+		metrics: encodeMetrics(bundle.metrics),
+		result_branch: bundle.resultBranch,
+		branch_created: bundle.branchCreated,
+		runner_exit_code: bundle.runnerExitCode,
+		error: bundle.error,
+	};
+}
+
+export function parseRunBundle(data: unknown): RunBundle {
+	const parsed = runBundleSchema.parse(data);
+	return {
+		schemaVersion: parsed.schema_version,
+		runId: parsed.run_id,
+		status: parsed.status,
+		startedAt: new Date(parsed.started_at),
+		finishedAt: new Date(parsed.finished_at),
+		runner: parsed.runner,
+		runnerVersion: parsed.runner_version,
+		model: parsed.model,
+		planSource: parsed.plan_source,
+		workdir: parsed.workdir,
+		git: {
+			repoRoot: parsed.git.repo_root,
+			startingBranch: parsed.git.starting_branch,
+			startingCommit: parsed.git.starting_commit,
+			remotes: parsed.git.remotes,
+		},
+		metrics: {
+			wallTimeSeconds: parsed.metrics.wall_time_seconds,
+			inputTokens: parsed.metrics.input_tokens,
+			outputTokens: parsed.metrics.output_tokens,
+			totalTokens: parsed.metrics.total_tokens,
+			costUsd: parsed.metrics.cost_usd,
+		},
+		resultBranch: parsed.result_branch,
+		branchCreated: parsed.branch_created,
+		runnerExitCode: parsed.runner_exit_code,
+		error: parsed.error,
+	};
+}