@mainahq/core 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mainahq/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Maina core engines — Context, Prompt, and Verify for verification-first development",

package/src/cloud/__tests__/client.test.ts

@@ -250,4 +250,247 @@ describe("createCloudClient", () => {
 			expect(result.error).toContain("Network unreachable");
 		}
 	});
+
+	// ── submitVerify ─────────────────────────────────────────────────────────
+
+	test("submitVerify sends diff, repo, and base_branch", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { jobId: "job-abc-123" } })),
+		);
+
+		const client = setupClient();
+		const result = await client.submitVerify({
+			diff: "--- a/file.ts\n+++ b/file.ts\n@@ -1 +1 @@\n-old\n+new",
+			repo: "acme/app",
+			baseBranch: "main",
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.jobId).toBe("job-abc-123");
+		}
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const url = call[0] as string;
+		const requestInit = call[1] as RequestInit;
+		expect(url).toBe("https://api.test.maina.dev/verify");
+		expect(requestInit.method).toBe("POST");
+		const body = JSON.parse(requestInit.body as string);
+		expect(body.diff).toContain("+new");
+		expect(body.repo).toBe("acme/app");
+		expect(body.base_branch).toBe("main");
+	});
+
+	test("submitVerify omits base_branch when not provided", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { jobId: "job-def-456" } })),
+		);
+
+		const client = setupClient();
+		await client.submitVerify({
+			diff: "some diff",
+			repo: "acme/app",
+		});
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const requestInit = call[1] as RequestInit;
+		const body = JSON.parse(requestInit.body as string);
+		expect(body.base_branch).toBeUndefined();
+	});
+
+	test("submitVerify returns error on 401", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Unauthorized" }, 401)),
+		);
+
+		const client = setupClient();
+		const result = await client.submitVerify({
+			diff: "diff",
+			repo: "acme/app",
+		});
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toBe("Unauthorized");
+		}
+	});
+
+	// ── getVerifyStatus ──────────────────────────────────────────────────────
+
+	test("getVerifyStatus returns queued status", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(
+				jsonResponse({
+					data: { status: "queued", currentStep: "Waiting in queue" },
+				}),
+			),
+		);
+
+		const client = setupClient();
+		const result = await client.getVerifyStatus("job-abc-123");
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.status).toBe("queued");
+			expect(result.value.currentStep).toBe("Waiting in queue");
+		}
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const url = call[0] as string;
+		expect(url).toBe("https://api.test.maina.dev/verify/job-abc-123/status");
+	});
+
+	test("getVerifyStatus returns running status", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(
+				jsonResponse({
+					data: {
+						status: "running",
+						currentStep: "Running Biome lint",
+					},
+				}),
+			),
+		);
+
+		const client = setupClient();
+		const result = await client.getVerifyStatus("job-abc-123");
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.status).toBe("running");
+			expect(result.value.currentStep).toBe("Running Biome lint");
+		}
+	});
+
+	test("getVerifyStatus returns error on 404", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Job not found" }, 404)),
+		);
+
+		const client = setupClient();
+		const result = await client.getVerifyStatus("nonexistent");
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toBe("Job not found");
+		}
+	});
+
+	test("getVerifyStatus retries on 500", async () => {
+		let attempts = 0;
+		mockFetch.mockImplementation(() => {
+			attempts++;
+			if (attempts === 1) {
+				return Promise.resolve(jsonResponse({ error: "Internal error" }, 500));
+			}
+			return Promise.resolve(
+				jsonResponse({
+					data: { status: "done", currentStep: "Complete" },
+				}),
+			);
+		});
+
+		const client = setupClient({ maxRetries: 2 });
+		const result = await client.getVerifyStatus("job-abc-123");
+
+		expect(result.ok).toBe(true);
+		expect(attempts).toBe(2);
+	});
+
+	// ── getVerifyResult ──────────────────────────────────────────────────────
+
+	test("getVerifyResult returns passing result", async () => {
+		const verifyResult = {
+			id: "job-abc-123",
+			status: "done",
+			passed: true,
+			findings: [],
+			findingsErrors: 0,
+			findingsWarnings: 0,
+			proofKey: "proof-xyz-789",
+			durationMs: 4523,
+		};
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: verifyResult })),
+		);
+
+		const client = setupClient();
+		const result = await client.getVerifyResult("job-abc-123");
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.id).toBe("job-abc-123");
+			expect(result.value.passed).toBe(true);
+			expect(result.value.findings).toHaveLength(0);
+			expect(result.value.proofKey).toBe("proof-xyz-789");
+			expect(result.value.durationMs).toBe(4523);
+		}
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const url = call[0] as string;
+		expect(url).toBe("https://api.test.maina.dev/verify/job-abc-123");
+	});
+
+	test("getVerifyResult returns failing result with findings", async () => {
+		const verifyResult = {
+			id: "job-fail-456",
+			status: "failed",
+			passed: false,
+			findings: [
+				{
+					tool: "biome",
+					file: "src/index.ts",
+					line: 42,
+					message: "Unexpected console.log",
+					severity: "error",
+					ruleId: "no-console",
+				},
+				{
+					tool: "semgrep",
+					file: "src/utils.ts",
+					line: 10,
+					message: "Potential SQL injection",
+					severity: "warning",
+				},
+			],
+			findingsErrors: 1,
+			findingsWarnings: 1,
+			proofKey: null,
+			durationMs: 3200,
+		};
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: verifyResult })),
+		);
+
+		const client = setupClient();
+		const result = await client.getVerifyResult("job-fail-456");
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.passed).toBe(false);
+			expect(result.value.findings).toHaveLength(2);
+			expect(result.value.findings[0]?.tool).toBe("biome");
+			expect(result.value.findings[0]?.severity).toBe("error");
+			expect(result.value.findings[0]?.ruleId).toBe("no-console");
+			expect(result.value.findings[1]?.tool).toBe("semgrep");
+			expect(result.value.findings[1]?.ruleId).toBeUndefined();
+			expect(result.value.findingsErrors).toBe(1);
+			expect(result.value.findingsWarnings).toBe(1);
+			expect(result.value.proofKey).toBeNull();
+		}
+	});
+
+	test("getVerifyResult returns error on 404", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Job not found" }, 404)),
+		);
+
+		const client = setupClient();
+		const result = await client.getVerifyResult("nonexistent");
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toBe("Job not found");
+		}
+	});
 });

package/src/cloud/auth.ts

@@ -144,7 +144,7 @@ export async function startDeviceFlow(
 		}
 
 		const body = (await response.json()) as {
-			data?: DeviceCodeResponse;
+			data?: Record<string, unknown>;
 			error?: string;
 		};
 		if (body.error) {
@@ -153,7 +153,14 @@ export async function startDeviceFlow(
 		if (!body.data) {
 			return err("Invalid response: missing data");
 		}
-		return ok(body.data);
+		const d = body.data;
+		return ok({
+			userCode: (d.userCode ?? d.user_code) as string,
+			deviceCode: (d.deviceCode ?? d.device_code) as string,
+			verificationUri: (d.verificationUri ?? d.verification_uri) as string,
+			interval: (d.interval ?? 5) as number,
+			expiresIn: (d.expiresIn ?? d.expires_in ?? 900) as number,
+		});
 	} catch (e) {
 		return err(
 			`Device flow request failed: ${e instanceof Error ? e.message : String(e)}`,
@@ -188,8 +195,8 @@ export async function pollForToken(
 					Accept: "application/json",
 				},
 				body: JSON.stringify({
-					deviceCode,
-					grantType: "urn:ietf:params:oauth:grant-type:device_code",
+					device_code: deviceCode,
+					grant_type: "urn:ietf:params:oauth:grant-type:device_code",
 				}),
 			});
 
@@ -204,7 +211,7 @@ export async function pollForToken(
 			}
 
 			const body = (await response.json()) as {
-				data?: TokenResponse;
+				data?: Record<string, unknown>;
 				error?: string;
 			};
 			if (body.error) {
@@ -217,7 +224,12 @@ export async function pollForToken(
 			if (!body.data) {
 				return err("Invalid token response: missing data");
 			}
-			return ok(body.data);
+			const d = body.data;
+			return ok({
+				accessToken: (d.accessToken ?? d.access_token) as string,
+				refreshToken: (d.refreshToken ?? d.refresh_token) as string | undefined,
+				expiresIn: (d.expiresIn ?? d.expires_in ?? 0) as number,
+			});
 		} catch (e) {
 			// Network errors during polling are transient — keep trying
 			if (Date.now() >= deadline) {

package/src/cloud/client.ts

@@ -11,8 +11,11 @@ import type {
 	CloudConfig,
 	CloudFeedbackPayload,
 	PromptRecord,
+	SubmitVerifyPayload,
 	TeamInfo,
 	TeamMember,
+	VerifyResultResponse,
+	VerifyStatusResponse,
 } from "./types";
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
@@ -70,6 +73,17 @@ export interface CloudClient {
 	postFeedback(
 		payload: CloudFeedbackPayload,
 	): Promise<Result<{ recorded: boolean }, string>>;
+
+	/** Submit a diff for cloud verification. */
+	submitVerify(
+		payload: SubmitVerifyPayload,
+	): Promise<Result<{ jobId: string }, string>>;
+
+	/** Poll the status of a verification job. */
+	getVerifyStatus(jobId: string): Promise<Result<VerifyStatusResponse, string>>;
+
+	/** Retrieve the full result of a completed verification job. */
+	getVerifyResult(jobId: string): Promise<Result<VerifyResultResponse, string>>;
 }
 
 /**
@@ -186,5 +200,51 @@ export function createCloudClient(config: CloudConfig): CloudClient {
 
 		postFeedback: (payload) =>
 			request<{ recorded: boolean }>("POST", "/feedback", payload),
+
+		submitVerify: async (payload) => {
+			// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
+			const result = await request<any>("POST", "/verify", {
+				diff: payload.diff,
+				repo: payload.repo,
+				base_branch: payload.baseBranch,
+			});
+			if (!result.ok) return result;
+			const d = result.value;
+			return ok({ jobId: d.jobId ?? d.job_id });
+		},
+
+		getVerifyStatus: async (jobId) => {
+			// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
+			const result = await request<any>("GET", `/verify/${jobId}/status`);
+			if (!result.ok) return result;
+			const d = result.value;
+			return ok({
+				status: d.status,
+				currentStep: d.currentStep ?? d.current_step ?? d.step ?? "",
+			});
+		},
+
+		getVerifyResult: async (jobId) => {
+			// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
+			const result = await request<any>("GET", `/verify/${jobId}`);
+			if (!result.ok) return result;
+			const d = result.value;
+			const items = d.findings?.items ?? d.findings ?? [];
+			return ok({
+				id: d.id,
+				status: d.status,
+				passed: d.passed,
+				findings: items,
+				findingsErrors:
+					d.findingsErrors ?? d.findings_errors ?? d.findings?.errors ?? 0,
+				findingsWarnings:
+					d.findingsWarnings ??
+					d.findings_warnings ??
+					d.findings?.warnings ??
+					0,
+				proofKey: d.proofKey ?? d.proof_key ?? d.proof_url ?? null,
+				durationMs: d.durationMs ?? d.duration_ms ?? 0,
+			});
+		},
 	};
 }

package/src/cloud/types.ts

@@ -8,7 +8,7 @@
 // ── Configuration ───────────────────────────────────────────────────────────
 
 export interface CloudConfig {
-	/** Base URL of the maina cloud API (e.g. "https://api.maina.dev"). */
+	/** Base URL of the maina cloud API (e.g. "https://api.mainahq.com"). */
 	baseUrl: string;
 	/** Bearer token for authenticated requests. */
 	token?: string;
@@ -90,6 +90,58 @@ export interface ApiResponse<T> {
 	meta?: Record<string, unknown>;
 }
 
+// ── Verify ─────────────────────────────────────────────────────────────────
+
+export interface SubmitVerifyPayload {
+	/** Diff content to verify. */
+	diff: string;
+	/** Repository identifier (e.g. "owner/repo"). */
+	repo: string;
+	/** Base branch to compare against. */
+	baseBranch?: string;
+}
+
+export interface VerifyStatusResponse {
+	/** Current job status. */
+	status: "queued" | "running" | "done" | "failed";
+	/** Human-readable description of the current step. */
+	currentStep: string;
+}
+
+export interface VerifyFinding {
+	/** Tool that produced the finding (e.g. "biome", "semgrep"). */
+	tool: string;
+	/** File path relative to repository root. */
+	file: string;
+	/** Line number in the file. */
+	line: number;
+	/** Finding description. */
+	message: string;
+	/** Severity level. */
+	severity: "error" | "warning" | "info";
+	/** Optional rule identifier. */
+	ruleId?: string;
+}
+
+export interface VerifyResultResponse {
+	/** Job identifier. */
+	id: string;
+	/** Final job status. */
+	status: "done" | "failed";
+	/** Whether all checks passed. */
+	passed: boolean;
+	/** Array of individual findings from verification tools. */
+	findings: VerifyFinding[];
+	/** Count of error-level findings. */
+	findingsErrors: number;
+	/** Count of warning-level findings. */
+	findingsWarnings: number;
+	/** Proof key for passing verification (null when failed). */
+	proofKey: string | null;
+	/** Total verification duration in milliseconds. */
+	durationMs: number;
+}
+
 // ── Feedback ────────────────────────────────────────────────────────────────
 
 export interface CloudFeedbackPayload {

package/src/index.ts

@@ -66,9 +66,13 @@ export type {
 	CloudFeedbackPayload,
 	DeviceCodeResponse,
 	PromptRecord,
+	SubmitVerifyPayload,
 	TeamInfo,
 	TeamMember,
 	TokenResponse,
+	VerifyFinding,
+	VerifyResultResponse,
+	VerifyStatusResponse,
 } from "./cloud/types";
 // Config
 export { getApiKey, isHostMode, shouldDelegateToHost } from "./config/index";
@@ -306,16 +310,12 @@ export {
 	runCoverage,
 } from "./verify/coverage";
 export {
-	type DetectedTool,
 	detectTool,
 	detectTools,
 	isToolAvailable,
 	TOOL_REGISTRY,
-	type ToolName,
 } from "./verify/detect";
 export {
-	type DiffFilterResult,
-	type Finding,
 	filterByDiff,
 	filterByDiffWithMap,
 	parseChangedLines,
@@ -343,12 +343,7 @@ export {
 	runMutation,
 } from "./verify/mutation";
 // Verify — Pipeline
-export {
-	type PipelineOptions,
-	type PipelineResult,
-	runPipeline,
-	type ToolReport,
-} from "./verify/pipeline";
+export { runPipeline } from "./verify/pipeline";
 // Verify — Proof
 export {
 	formatVerificationProof,
@@ -376,12 +371,22 @@ export {
 } from "./verify/sonar";
 export {
 	parseBiomeOutput,
-	type SyntaxDiagnostic,
-	type SyntaxGuardResult,
 	syntaxGuard,
 } from "./verify/syntax-guard";
 // Verify — Typecheck + Consistency (built-in checks)
 export { runTypecheck, type TypecheckResult } from "./verify/typecheck";
+// Verify — Public Type Surface (consolidated for external consumers like maina-cloud)
+export type {
+	DetectedTool,
+	DiffFilterResult,
+	Finding,
+	PipelineOptions,
+	PipelineResult,
+	SyntaxDiagnostic,
+	SyntaxGuardResult,
+	ToolName,
+	ToolReport,
+} from "./verify/types";
 // Verify — Visual
 export {
 	captureScreenshot,

package/src/verify/__tests__/types.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, test } from "bun:test";
+import type {
+	DetectedTool,
+	Finding,
+	PipelineOptions,
+	PipelineResult,
+	ToolReport,
+} from "../types";
+
+// ─── Verify Type Exports ────────────────────────────────────────────────────
+
+describe("verify/types re-exports", () => {
+	test("Finding type has expected shape", () => {
+		const finding: Finding = {
+			tool: "semgrep",
+			file: "src/index.ts",
+			line: 42,
+			message: "unused variable",
+			severity: "warning",
+		};
+		expect(finding.tool).toBe("semgrep");
+		expect(finding.file).toBe("src/index.ts");
+		expect(finding.line).toBe(42);
+		expect(finding.message).toBe("unused variable");
+		expect(finding.severity).toBe("warning");
+	});
+
+	test("Finding type supports optional fields", () => {
+		const finding: Finding = {
+			tool: "eslint",
+			file: "app.ts",
+			line: 10,
+			column: 5,
+			message: "no-unused-vars",
+			severity: "error",
+			ruleId: "no-unused-vars",
+		};
+		expect(finding.column).toBe(5);
+		expect(finding.ruleId).toBe("no-unused-vars");
+	});
+
+	test("ToolReport type has expected shape", () => {
+		const report: ToolReport = {
+			tool: "trivy",
+			findings: [],
+			skipped: false,
+			duration: 123,
+		};
+		expect(report.tool).toBe("trivy");
+		expect(report.findings).toEqual([]);
+		expect(report.skipped).toBe(false);
+		expect(report.duration).toBe(123);
+	});
+
+	test("PipelineResult type has expected shape", () => {
+		const result: PipelineResult = {
+			passed: true,
+			syntaxPassed: true,
+			tools: [],
+			findings: [],
+			hiddenCount: 0,
+			detectedTools: [],
+			duration: 500,
+			cacheHits: 2,
+			cacheMisses: 1,
+		};
+		expect(result.passed).toBe(true);
+		expect(result.syntaxPassed).toBe(true);
+		expect(result.tools).toEqual([]);
+		expect(result.findings).toEqual([]);
+		expect(result.hiddenCount).toBe(0);
+		expect(result.detectedTools).toEqual([]);
+		expect(result.duration).toBe(500);
+		expect(result.cacheHits).toBe(2);
+		expect(result.cacheMisses).toBe(1);
+	});
+
+	test("PipelineOptions type has expected shape", () => {
+		const opts: PipelineOptions = {
+			files: ["src/app.ts"],
+			baseBranch: "main",
+			diffOnly: true,
+			deep: false,
+			cwd: "/tmp",
+			mainaDir: ".maina",
+			languages: ["typescript"],
+		};
+		expect(opts.files).toEqual(["src/app.ts"]);
+		expect(opts.baseBranch).toBe("main");
+		expect(opts.diffOnly).toBe(true);
+		expect(opts.deep).toBe(false);
+	});
+
+	test("DetectedTool type has expected shape", () => {
+		const tool: DetectedTool = {
+			name: "biome",
+			command: "biome",
+			version: "1.5.0",
+			available: true,
+		};
+		expect(tool.name).toBe("biome");
+		expect(tool.command).toBe("biome");
+		expect(tool.version).toBe("1.5.0");
+		expect(tool.available).toBe(true);
+	});
+
+	test("DetectedTool supports null version", () => {
+		const tool: DetectedTool = {
+			name: "semgrep",
+			command: "semgrep",
+			version: null,
+			available: false,
+		};
+		expect(tool.version).toBeNull();
+		expect(tool.available).toBe(false);
+	});
+});
+
+// ─── Verify types re-exported from @mainahq/core index ──────────────────────
+
+describe("verify types from core index", () => {
+	test("types are importable from core index", async () => {
+		const coreIndex = await import("../../index");
+		// The module should export these — we verify by checking the module loaded
+		// Type-only exports don't appear at runtime, but the module must resolve
+		expect(coreIndex).toBeDefined();
+		expect(typeof coreIndex.VERSION).toBe("string");
+	});
+});

package/src/verify/types.ts

@@ -0,0 +1,17 @@
+/**
+ * Verify Engine — Public Type Exports.
+ *
+ * Consolidated re-exports of all verify types for the public API surface.
+ * Consumers (e.g. maina-cloud) import from here or from @mainahq/core.
+ * Types are NOT duplicated — each re-exports from its source module.
+ */
+
+// DetectedTool, ToolName from detect
+export type { DetectedTool, ToolName } from "./detect";
+// Finding + DiffFilterResult from diff-filter
+export type { DiffFilterResult, Finding } from "./diff-filter";
+// PipelineResult, PipelineOptions, ToolReport from pipeline
+export type { PipelineOptions, PipelineResult, ToolReport } from "./pipeline";
+
+// SyntaxDiagnostic, SyntaxGuardResult from syntax-guard (used in PipelineResult)
+export type { SyntaxDiagnostic, SyntaxGuardResult } from "./syntax-guard";