@mainahq/core 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mainahq/core",
-  "version": "0.6.0",
+  "version": "0.7.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

@@ -493,4 +493,172 @@ describe("createCloudClient", () => {
 			expect(result.error).toBe("Job not found");
 		}
 	});
+
+	// ── postFeedbackBatch ─────────────────────────────────────────────────
+
+	test("postFeedbackBatch sends events in snake_case", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { received: 3 } })),
+		);
+
+		const client = setupClient();
+		const result = await client.postFeedbackBatch([
+			{
+				promptHash: "hash-1",
+				command: "commit",
+				accepted: true,
+				timestamp: "2026-01-01T00:00:00Z",
+			},
+			{
+				promptHash: "hash-2",
+				command: "review",
+				accepted: false,
+				context: "user edited",
+				diffHash: "diff-abc",
+			},
+			{
+				promptHash: "hash-3",
+				command: "fix",
+				accepted: true,
+			},
+		]);
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.received).toBe(3);
+		}
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const url = call[0] as string;
+		expect(url).toBe("https://api.test.maina.dev/feedback/batch");
+
+		const requestInit = call[1] as RequestInit;
+		expect(requestInit.method).toBe("POST");
+
+		const body = JSON.parse(requestInit.body as string);
+		expect(body.events).toHaveLength(3);
+		// Verify snake_case mapping
+		expect(body.events[0].prompt_hash).toBe("hash-1");
+		expect(body.events[0].command).toBe("commit");
+		expect(body.events[0].accepted).toBe(true);
+		expect(body.events[0].timestamp).toBe("2026-01-01T00:00:00Z");
+		expect(body.events[1].diff_hash).toBe("diff-abc");
+		expect(body.events[1].context).toBe("user edited");
+	});
+
+	test("postFeedbackBatch returns error on failure", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Unauthorized" }, 401)),
+		);
+
+		const client = setupClient();
+		const result = await client.postFeedbackBatch([]);
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toBe("Unauthorized");
+		}
+	});
+
+	// ── getFeedbackImprovements ──────────────────────────────────────────
+
+	test("getFeedbackImprovements returns improvements with camelCase mapping", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(
+				jsonResponse({
+					data: {
+						improvements: [
+							{
+								command: "commit",
+								prompt_hash: "hash-abc",
+								samples: 50,
+								accept_rate: 0.85,
+								status: "healthy",
+							},
+							{
+								command: "review",
+								prompt_hash: "hash-def",
+								samples: 30,
+								accept_rate: 0.4,
+								status: "needs_improvement",
+							},
+						],
+						team_totals: {
+							total_events: 200,
+							accept_rate: 0.72,
+						},
+					},
+				}),
+			),
+		);
+
+		const client = setupClient();
+		const result = await client.getFeedbackImprovements();
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.improvements).toHaveLength(2);
+			expect(result.value.improvements[0]?.command).toBe("commit");
+			expect(result.value.improvements[0]?.promptHash).toBe("hash-abc");
+			expect(result.value.improvements[0]?.samples).toBe(50);
+			expect(result.value.improvements[0]?.acceptRate).toBe(0.85);
+			expect(result.value.improvements[0]?.status).toBe("healthy");
+			expect(result.value.improvements[1]?.status).toBe("needs_improvement");
+			expect(result.value.teamTotals.totalEvents).toBe(200);
+			expect(result.value.teamTotals.acceptRate).toBe(0.72);
+		}
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const url = call[0] as string;
+		expect(url).toBe("https://api.test.maina.dev/feedback/improvements");
+	});
+
+	test("getFeedbackImprovements handles camelCase response", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(
+				jsonResponse({
+					data: {
+						improvements: [
+							{
+								command: "fix",
+								promptHash: "hash-ghi",
+								samples: 10,
+								acceptRate: 0.95,
+								status: "excellent",
+							},
+						],
+						teamTotals: {
+							totalEvents: 100,
+							acceptRate: 0.9,
+						},
+					},
+				}),
+			),
+		);
+
+		const client = setupClient();
+		const result = await client.getFeedbackImprovements();
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.improvements[0]?.promptHash).toBe("hash-ghi");
+			expect(result.value.improvements[0]?.acceptRate).toBe(0.95);
+			expect(result.value.teamTotals.totalEvents).toBe(100);
+			expect(result.value.teamTotals.acceptRate).toBe(0.9);
+		}
+	});
+
+	test("getFeedbackImprovements returns error on failure", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Forbidden" }, 403)),
+		);
+
+		const client = setupClient();
+		const result = await client.getFeedbackImprovements();
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toBe("Forbidden");
+		}
+	});
 });

package/src/cloud/client.ts

@@ -10,6 +10,9 @@ import type {
 	ApiResponse,
 	CloudConfig,
 	CloudFeedbackPayload,
+	CloudPromptImprovement,
+	FeedbackEvent,
+	FeedbackImprovementsResponse,
 	PromptRecord,
 	SubmitVerifyPayload,
 	TeamInfo,
@@ -74,6 +77,16 @@ export interface CloudClient {
 		payload: CloudFeedbackPayload,
 	): Promise<Result<{ recorded: boolean }, string>>;
 
+	/** Upload a batch of feedback events to the cloud. */
+	postFeedbackBatch(
+		events: FeedbackEvent[],
+	): Promise<Result<{ received: number }, string>>;
+
+	/** Fetch feedback-based improvement suggestions from the cloud. */
+	getFeedbackImprovements(): Promise<
+		Result<FeedbackImprovementsResponse, string>
+	>;
+
 	/** Submit a diff for cloud verification. */
 	submitVerify(
 		payload: SubmitVerifyPayload,
@@ -201,6 +214,47 @@ export function createCloudClient(config: CloudConfig): CloudClient {
 		postFeedback: (payload) =>
 			request<{ recorded: boolean }>("POST", "/feedback", payload),
 
+		postFeedbackBatch: async (events) => {
+			// Map camelCase → snake_case for cloud API
+			const snakeEvents = events.map((e) => ({
+				prompt_hash: e.promptHash,
+				command: e.command,
+				accepted: e.accepted,
+				context: e.context,
+				diff_hash: e.diffHash,
+				timestamp: e.timestamp,
+			}));
+			return request<{ received: number }>("POST", "/feedback/batch", {
+				events: snakeEvents,
+			});
+		},
+
+		getFeedbackImprovements: async () => {
+			// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
+			const result = await request<any>("GET", "/feedback/improvements");
+			if (!result.ok) return result;
+			const d = result.value;
+			const rawImprovements = d.improvements ?? [];
+			const improvements: CloudPromptImprovement[] = rawImprovements.map(
+				// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
+				(i: any) => ({
+					command: i.command,
+					promptHash: i.promptHash ?? i.prompt_hash,
+					samples: i.samples,
+					acceptRate: i.acceptRate ?? i.accept_rate,
+					status: i.status,
+				}),
+			);
+			const totals = d.teamTotals ?? d.team_totals ?? {};
+			return ok({
+				improvements,
+				teamTotals: {
+					totalEvents: totals.totalEvents ?? totals.total_events ?? 0,
+					acceptRate: totals.acceptRate ?? totals.accept_rate ?? 0,
+				},
+			});
+		},
+
 		submitVerify: async (payload) => {
 			// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
 			const result = await request<any>("POST", "/verify", {

package/src/cloud/types.ts

@@ -156,3 +156,45 @@ export interface CloudFeedbackPayload {
 	/** Optional context about the feedback. */
 	context?: string;
 }
+
+// ── Feedback Batch (learn --cloud) ─────────────────────────────────────────
+
+export interface FeedbackEvent {
+	/** Prompt hash the feedback refers to. */
+	promptHash: string;
+	/** Command that generated the output. */
+	command: string;
+	/** Whether the user accepted the output. */
+	accepted: boolean;
+	/** Optional context about the feedback. */
+	context?: string;
+	/** Optional diff hash for traceability. */
+	diffHash?: string;
+	/** ISO-8601 timestamp. */
+	timestamp?: string;
+}
+
+export interface FeedbackBatchPayload {
+	/** Array of feedback events to upload. */
+	events: FeedbackEvent[];
+}
+
+export interface CloudPromptImprovement {
+	/** Command the improvement applies to. */
+	command: string;
+	/** Prompt hash that was analysed. */
+	promptHash: string;
+	/** Number of feedback samples analysed. */
+	samples: number;
+	/** Accept rate (0–1). */
+	acceptRate: number;
+	/** Health status based on accept rate. */
+	status: "needs_improvement" | "healthy" | "excellent";
+}
+
+export interface FeedbackImprovementsResponse {
+	/** Per-command improvement assessments. */
+	improvements: CloudPromptImprovement[];
+	/** Aggregated team-wide feedback totals. */
+	teamTotals: { totalEvents: number; acceptRate: number };
+}

package/src/feedback/__tests__/sync.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { recordOutcome } from "../../prompts/engine";
+import { exportFeedbackForCloud } from "../sync";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		import.meta.dir,
+		`tmp-sync-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+	try {
+		const { rmSync } = require("node:fs");
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		// ignore
+	}
+});
+
+describe("exportFeedbackForCloud", () => {
+	test("returns empty array when no feedback exists", () => {
+		const events = exportFeedbackForCloud(tmpDir);
+		expect(events).toEqual([]);
+	});
+
+	test("exports accepted feedback events", () => {
+		recordOutcome(tmpDir, "hash-abc", {
+			accepted: true,
+			command: "commit",
+		});
+
+		const events = exportFeedbackForCloud(tmpDir);
+
+		expect(events).toHaveLength(1);
+		expect(events[0]?.promptHash).toBe("hash-abc");
+		expect(events[0]?.command).toBe("commit");
+		expect(events[0]?.accepted).toBe(true);
+		expect(events[0]?.timestamp).toBeDefined();
+	});
+
+	test("exports rejected feedback events", () => {
+		recordOutcome(tmpDir, "hash-def", {
+			accepted: false,
+			command: "review",
+		});
+
+		const events = exportFeedbackForCloud(tmpDir);
+
+		expect(events).toHaveLength(1);
+		expect(events[0]?.accepted).toBe(false);
+		expect(events[0]?.command).toBe("review");
+	});
+
+	test("exports context when present", () => {
+		recordOutcome(tmpDir, "hash-ctx", {
+			accepted: true,
+			command: "commit",
+			context: "user edited the message",
+		});
+
+		const events = exportFeedbackForCloud(tmpDir);
+
+		expect(events).toHaveLength(1);
+		expect(events[0]?.context).toBe("user edited the message");
+	});
+
+	test("omits context when not present", () => {
+		recordOutcome(tmpDir, "hash-no-ctx", {
+			accepted: true,
+			command: "commit",
+		});
+
+		const events = exportFeedbackForCloud(tmpDir);
+
+		expect(events).toHaveLength(1);
+		expect(events[0]?.context).toBeUndefined();
+	});
+
+	test("exports multiple events in chronological order", () => {
+		recordOutcome(tmpDir, "hash-1", { accepted: true, command: "commit" });
+		recordOutcome(tmpDir, "hash-2", { accepted: false, command: "review" });
+		recordOutcome(tmpDir, "hash-3", { accepted: true, command: "fix" });
+
+		const events = exportFeedbackForCloud(tmpDir);
+
+		expect(events).toHaveLength(3);
+		expect(events[0]?.promptHash).toBe("hash-1");
+		expect(events[1]?.promptHash).toBe("hash-2");
+		expect(events[2]?.promptHash).toBe("hash-3");
+	});
+
+	test("returns empty array on invalid db path", () => {
+		const events = exportFeedbackForCloud(
+			"/nonexistent/path/that/does/not/exist",
+		);
+		expect(events).toEqual([]);
+	});
+});

package/src/feedback/sync.ts

@@ -0,0 +1,54 @@
+/**
+ * Feedback sync — exports local feedback records for cloud upload.
+ *
+ * Reads from the local SQLite feedback.db and maps records to the
+ * cloud-compatible FeedbackEvent format for batch upload.
+ */
+
+import type { FeedbackEvent } from "../cloud/types";
+import { getFeedbackDb } from "../db/index";
+
+/** Raw row shape from the feedback table. */
+interface FeedbackRow {
+	prompt_hash: string;
+	command: string;
+	accepted: number;
+	context: string | null;
+	created_at: string;
+}
+
+/**
+ * Export all local feedback records in the cloud-compatible format.
+ *
+ * Reads from the feedback table in the SQLite database at `mainaDir/feedback.db`
+ * and maps each row to a `FeedbackEvent` object ready for batch upload.
+ */
+export function exportFeedbackForCloud(mainaDir: string): FeedbackEvent[] {
+	const dbResult = getFeedbackDb(mainaDir);
+	if (!dbResult.ok) {
+		return [];
+	}
+
+	const { db } = dbResult.value;
+
+	const rows = db
+		.query(
+			"SELECT prompt_hash, command, accepted, context, created_at FROM feedback ORDER BY created_at ASC",
+		)
+		.all() as FeedbackRow[];
+
+	return rows.map((row) => {
+		const event: FeedbackEvent = {
+			promptHash: row.prompt_hash,
+			command: row.command,
+			accepted: row.accepted === 1,
+			timestamp: row.created_at,
+		};
+
+		if (row.context) {
+			event.context = row.context;
+		}
+
+		return event;
+	});
+}

package/src/index.ts

@@ -64,7 +64,11 @@ export type {
 	ApiResponse,
 	CloudConfig,
 	CloudFeedbackPayload,
+	CloudPromptImprovement,
 	DeviceCodeResponse,
+	FeedbackBatchPayload,
+	FeedbackEvent,
+	FeedbackImprovementsResponse,
 	PromptRecord,
 	SubmitVerifyPayload,
 	TeamInfo,
@@ -168,6 +172,7 @@ export {
 	type RulePreference,
 	savePreferences,
 } from "./feedback/preferences";
+export { exportFeedbackForCloud } from "./feedback/sync";
 export {
 	analyzeWorkflowTrace,
 	type PromptImprovement,

package/src/language/__tests__/__fixtures__/detect/composer.lock

@@ -0,0 +1 @@
+{"packages": []}