@mainahq/core 1.0.0 → 1.0.1

package/package.json

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

@@ -661,4 +661,175 @@ describe("createCloudClient", () => {
 			expect(result.error).toBe("Forbidden");
 		}
 	});
+
+	// ── postEpisodicEntries ─────────────────────────────────────────────────
+
+	test("postEpisodicEntries sends entries in snake_case", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { received: 2 } })),
+		);
+
+		const client = setupClient();
+		const result = await client.postEpisodicEntries([
+			{
+				repo: "acme/app",
+				entryType: "review",
+				title: "Accepted review",
+				summary: "Fixed auth middleware",
+				relevanceScore: 0.9,
+			},
+			{
+				repo: "acme/app",
+				entryType: "commit",
+				title: "Commit summary",
+				summary: "Added logging",
+			},
+		]);
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.received).toBe(2);
+		}
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const url = call[0] as string;
+		expect(url).toBe("https://api.test.maina.dev/context/episodic");
+
+		const requestInit = call[1] as RequestInit;
+		expect(requestInit.method).toBe("POST");
+
+		const body = JSON.parse(requestInit.body as string);
+		expect(body.entries).toHaveLength(2);
+		// Verify snake_case mapping
+		expect(body.entries[0].entry_type).toBe("review");
+		expect(body.entries[0].relevance_score).toBe(0.9);
+		expect(body.entries[0].repo).toBe("acme/app");
+		expect(body.entries[1].entry_type).toBe("commit");
+	});
+
+	test("postEpisodicEntries returns error on failure", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Unauthorized" }, 401)),
+		);
+
+		const client = setupClient();
+		const result = await client.postEpisodicEntries([]);
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toBe("Unauthorized");
+		}
+	});
+
+	// ── getEpisodicEntries ──────────────────────────────────────────────────
+
+	test("getEpisodicEntries returns mapped entries", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(
+				jsonResponse({
+					data: {
+						entries: [
+							{
+								id: "ep_001",
+								repo: "acme/app",
+								entry_type: "review",
+								title: "Auth review",
+								summary: "Fixed auth flow",
+								relevance_score: 0.85,
+								member_id: "mem_abc",
+								decay_factor: 0.95,
+								created_at: "2026-04-01T00:00:00Z",
+								accessed_at: "2026-04-02T00:00:00Z",
+							},
+						],
+					},
+				}),
+			),
+		);
+
+		const client = setupClient();
+		const result = await client.getEpisodicEntries("acme/app");
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toHaveLength(1);
+			const entry = result.value[0] as (typeof result.value)[number];
+			expect(entry.id).toBe("ep_001");
+			expect(entry.entryType).toBe("review");
+			expect(entry.relevanceScore).toBe(0.85);
+			expect(entry.memberId).toBe("mem_abc");
+			expect(entry.decayFactor).toBe(0.95);
+			expect(entry.createdAt).toBe("2026-04-01T00:00:00Z");
+			expect(entry.accessedAt).toBe("2026-04-02T00:00:00Z");
+		}
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const url = call[0] as string;
+		expect(url).toBe(
+			"https://api.test.maina.dev/context/episodic?repo=acme%2Fapp",
+		);
+	});
+
+	test("getEpisodicEntries handles camelCase response", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(
+				jsonResponse({
+					data: {
+						entries: [
+							{
+								id: "ep_002",
+								repo: "acme/app",
+								entryType: "commit",
+								title: "Commit entry",
+								summary: "Added tests",
+								relevanceScore: 0.7,
+								memberId: "mem_xyz",
+								decayFactor: 0.8,
+								createdAt: "2026-04-03T00:00:00Z",
+								accessedAt: "2026-04-03T12:00:00Z",
+							},
+						],
+					},
+				}),
+			),
+		);
+
+		const client = setupClient();
+		const result = await client.getEpisodicEntries("acme/app");
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value[0]?.entryType).toBe("commit");
+			expect(result.value[0]?.relevanceScore).toBe(0.7);
+			expect(result.value[0]?.memberId).toBe("mem_xyz");
+		}
+	});
+
+	test("getEpisodicEntries returns empty array when no entries", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { entries: [] } })),
+		);
+
+		const client = setupClient();
+		const result = await client.getEpisodicEntries("acme/app");
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toEqual([]);
+		}
+	});
+
+	test("getEpisodicEntries returns error on failure", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Forbidden" }, 403)),
+		);
+
+		const client = setupClient();
+		const result = await client.getEpisodicEntries("acme/app");
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toBe("Forbidden");
+		}
+	});
 });

package/src/cloud/auth.ts

@@ -229,6 +229,7 @@ export async function pollForToken(
 				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,
+				firstTime: (d.firstTime ?? d.first_time ?? false) as boolean,
 			});
 		} catch (e) {
 			// Network errors during polling are transient — keep trying

package/src/cloud/client.ts

@@ -9,10 +9,14 @@ import type { Result } from "../db/index";
 import type {
 	ApiResponse,
 	CloudConfig,
+	CloudEpisodicEntry,
 	CloudFeedbackPayload,
 	CloudPromptImprovement,
+	EpisodicCloudEntry,
 	FeedbackEvent,
 	FeedbackImprovementsResponse,
+	ProfileUpdatePayload,
+	ProfileUpdateResponse,
 	PromptRecord,
 	SubmitVerifyPayload,
 	TeamInfo,
@@ -54,6 +58,11 @@ export interface CloudClient {
 	/** Check API availability. */
 	health(): Promise<Result<{ status: string }, string>>;
 
+	/** Update user profile (email, name) during onboarding. */
+	updateProfile(
+		payload: ProfileUpdatePayload,
+	): Promise<Result<ProfileUpdateResponse, string>>;
+
 	/** Download team prompts. */
 	getPrompts(): Promise<Result<PromptRecord[], string>>;
 
@@ -87,6 +96,27 @@ export interface CloudClient {
 		Result<FeedbackImprovementsResponse, string>
 	>;
 
+	/** Post workflow stats to cloud analytics. */
+	postWorkflowStats(stats: {
+		totalCommits: number;
+		totalVerifyTimeMs: number;
+		avgVerifyTimeMs: number;
+		totalFindings: number;
+		totalContextTokens: number;
+		cacheHitRate: number;
+		passRate: number;
+	}): Promise<Result<{ received: boolean }, string>>;
+
+	/** Upload episodic entries to the cloud for team sharing. */
+	postEpisodicEntries(
+		entries: EpisodicCloudEntry[],
+	): Promise<Result<{ received: number }, string>>;
+
+	/** Fetch team's episodic entries for a repo from the cloud. */
+	getEpisodicEntries(
+		repo: string,
+	): Promise<Result<CloudEpisodicEntry[], string>>;
+
 	/** Submit a diff for cloud verification. */
 	submitVerify(
 		payload: SubmitVerifyPayload,
@@ -200,6 +230,18 @@ export function createCloudClient(config: CloudConfig): CloudClient {
 	return {
 		health: () => request<{ status: string }>("GET", "/health"),
 
+		updateProfile: async (payload) => {
+			// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
+			const result = await request<any>("PATCH", "/auth/profile", payload);
+			if (!result.ok) return result;
+			const d = result.value;
+			return ok({
+				email: d.email,
+				name: d.name,
+				isOnboarded: d.isOnboarded ?? d.is_onboarded ?? false,
+			});
+		},
+
 		getPrompts: () => request<PromptRecord[]>("GET", "/prompts"),
 
 		putPrompts: (prompts) => request<void>("PUT", "/prompts", { prompts }),
@@ -255,6 +297,58 @@ export function createCloudClient(config: CloudConfig): CloudClient {
 			});
 		},
 
+		postEpisodicEntries: async (entries) => {
+			// Map camelCase → snake_case for cloud API
+			const snakeEntries = entries.map((e) => ({
+				repo: e.repo,
+				entry_type: e.entryType,
+				title: e.title,
+				summary: e.summary,
+				relevance_score: e.relevanceScore,
+			}));
+			return request<{ received: number }>("POST", "/context/episodic", {
+				entries: snakeEntries,
+			});
+		},
+
+		getEpisodicEntries: async (repo) => {
+			// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
+			const result = await request<any>(
+				"GET",
+				`/context/episodic?repo=${encodeURIComponent(repo)}`,
+			);
+			if (!result.ok) return result;
+			const d = result.value;
+			const rawEntries = d.entries ?? [];
+			const mapped: CloudEpisodicEntry[] = rawEntries.map(
+				// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
+				(e: any) => ({
+					id: e.id,
+					repo: e.repo,
+					entryType: e.entryType ?? e.entry_type,
+					title: e.title,
+					summary: e.summary,
+					relevanceScore: e.relevanceScore ?? e.relevance_score ?? 1.0,
+					memberId: e.memberId ?? e.member_id,
+					decayFactor: e.decayFactor ?? e.decay_factor ?? 1.0,
+					createdAt: e.createdAt ?? e.created_at,
+					accessedAt: e.accessedAt ?? e.accessed_at,
+				}),
+			);
+			return ok(mapped);
+		},
+
+		postWorkflowStats: (stats) =>
+			request<{ received: boolean }>("POST", "/feedback/stats", {
+				total_commits: stats.totalCommits,
+				total_verify_time_ms: stats.totalVerifyTimeMs,
+				avg_verify_time_ms: stats.avgVerifyTimeMs,
+				total_findings: stats.totalFindings,
+				total_context_tokens: stats.totalContextTokens,
+				cache_hit_rate: stats.cacheHitRate,
+				pass_rate: stats.passRate,
+			}),
+
 		submitVerify: async (payload) => {
 			// biome-ignore lint/suspicious/noExplicitAny: snake_case API mapping
 			const result = await request<any>("POST", "/verify", {

package/src/cloud/types.ts

@@ -77,6 +77,26 @@ export interface TokenResponse {
 	refreshToken?: string;
 	/** Seconds until the access token expires. */
 	expiresIn: number;
+	/** True when the user has no email set (first-time signup). */
+	firstTime?: boolean;
+}
+
+// ── Profile ────────────────────────────────────────────────────────────────
+
+export interface ProfileUpdatePayload {
+	/** User email address. */
+	email: string;
+	/** User display name. */
+	name: string;
+}
+
+export interface ProfileUpdateResponse {
+	/** Updated email. */
+	email: string;
+	/** Updated name. */
+	name: string;
+	/** Whether onboarding is complete. */
+	isOnboarded: boolean;
 }
 
 // ── API Envelope ────────────────────────────────────────────────────────────
@@ -157,6 +177,34 @@ export interface CloudFeedbackPayload {
 	context?: string;
 }
 
+// ── Episodic Context (team sharing) ───────────────────────────────────────
+
+export interface EpisodicCloudEntry {
+	/** Repository identifier (e.g. "owner/repo"). */
+	repo: string;
+	/** Type of episodic entry (e.g. "review", "commit", "session"). */
+	entryType: string;
+	/** Short title for the entry. */
+	title: string;
+	/** Compressed summary of the entry. */
+	summary: string;
+	/** Relevance score (0-1). Default: 1.0. */
+	relevanceScore?: number;
+}
+
+export interface CloudEpisodicEntry extends EpisodicCloudEntry {
+	/** Unique identifier (ep_<uuid>). */
+	id: string;
+	/** Team member who created the entry. */
+	memberId: string;
+	/** Ebbinghaus decay factor (0-1). */
+	decayFactor: number;
+	/** ISO-8601 creation timestamp. */
+	createdAt: string;
+	/** ISO-8601 last access timestamp. */
+	accessedAt: string;
+}
+
 // ── Feedback Batch (learn --cloud) ─────────────────────────────────────────
 
 export interface FeedbackEvent {

package/src/context/engine.ts

@@ -1,6 +1,10 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getChangedFiles, getStagedFiles } from "../git/index";
+import { loadAuthConfig } from "../cloud/auth";
+import { createCloudClient } from "../cloud/client";
+import type { CloudEpisodicEntry } from "../cloud/types";
+import { getChangedFiles, getRepoSlug, getStagedFiles } from "../git/index";
 import {
 	assembleBudget,
 	type BudgetAllocation,
@@ -172,10 +176,51 @@ async function buildWorkingLayer(
 	}
 }
 
+/**
+ * Deduplicate cloud entries against local entries by hashing title+summary.
+ * Returns only the cloud entries not already present locally.
+ */
+function deduplicateCloudEntries(
+	localEntries: import("./episodic").EpisodicEntry[],
+	cloudEntries: CloudEpisodicEntry[],
+): import("./episodic").EpisodicEntry[] {
+	const localHashes = new Set(
+		localEntries.map((e) => {
+			const key = `${e.summary}::${e.content}`;
+			return createHash("sha256").update(key).digest("hex").slice(0, 16);
+		}),
+	);
+
+	return cloudEntries
+		.filter((ce) => {
+			const key = `${ce.title}::${ce.summary}`;
+			const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
+			return !localHashes.has(hash);
+		})
+		.map((ce) => ({
+			id: ce.id,
+			content: ce.summary,
+			summary: ce.title,
+			relevance: (ce.relevanceScore ?? 1.0) * ce.decayFactor,
+			accessCount: 0,
+			createdAt: ce.createdAt,
+			lastAccessedAt: ce.accessedAt,
+			type: ce.entryType,
+		}));
+}
+
+const CLOUD_URL = process.env.MAINA_CLOUD_URL ?? "https://api.mainahq.com";
+
 /**
  * Build the episodic layer content. Never throws.
+ * When the user is logged into the cloud, also fetches team episodic entries
+ * and merges them (deduplicated by title+summary hash) with local entries.
  */
-function buildEpisodicLayer(mainaDir: string, filter?: string[]): LayerContent {
+async function buildEpisodicLayer(
+	mainaDir: string,
+	repoRoot: string,
+	filter?: string[],
+): Promise<LayerContent> {
 	try {
 		decayAllEntries(mainaDir);
 
@@ -194,6 +239,30 @@ function buildEpisodicLayer(mainaDir: string, filter?: string[]): LayerContent {
 			entries = getEntries(mainaDir);
 		}
 
+		// Merge cloud episodic entries if logged in
+		try {
+			const auth = loadAuthConfig();
+			if (auth.ok && auth.value.accessToken) {
+				const client = createCloudClient({
+					baseUrl: CLOUD_URL,
+					token: auth.value.accessToken,
+				});
+				const repo = await getRepoSlug(repoRoot);
+				const cloudResult = await client.getEpisodicEntries(repo);
+				if (cloudResult.ok && cloudResult.value.length > 0) {
+					const uniqueCloud = deduplicateCloudEntries(
+						entries,
+						cloudResult.value,
+					);
+					entries = [...entries, ...uniqueCloud];
+					// Re-sort by relevance descending after merging
+					entries.sort((a, b) => b.relevance - a.relevance);
+				}
+			}
+		} catch {
+			// Cloud fetch failure is silent — local entries are still available
+		}
+
 		const text = assembleEpisodicText(entries);
 		return {
 			name: "episodic",
@@ -291,9 +360,7 @@ export async function assembleContext(
 		const episodicFilter = Array.isArray(needs.episodic)
 			? needs.episodic
 			: undefined;
-		layerPromises.push(
-			Promise.resolve(buildEpisodicLayer(mainaDir, episodicFilter)),
-		);
+		layerPromises.push(buildEpisodicLayer(mainaDir, repoRoot, episodicFilter));
 	}
 
 	// Retrieval layer — auto-generates search query from staged/changed files if not provided

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

@@ -1,8 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { addEntry } from "../../context/episodic";
 import { recordOutcome } from "../../prompts/engine";
-import { exportFeedbackForCloud } from "../sync";
+import { exportEpisodicForCloud, exportFeedbackForCloud } from "../sync";
 
 let tmpDir: string;
 
@@ -102,3 +103,64 @@ describe("exportFeedbackForCloud", () => {
 		expect(events).toEqual([]);
 	});
 });
+
+describe("exportEpisodicForCloud", () => {
+	test("returns empty array when no episodic entries exist", () => {
+		const entries = exportEpisodicForCloud(tmpDir, "acme/app");
+		expect(entries).toEqual([]);
+	});
+
+	test("exports episodic entries in cloud format", () => {
+		addEntry(tmpDir, {
+			content: "Fixed authentication middleware to use JWT",
+			summary: "Auth fix",
+			type: "review",
+		});
+
+		const entries = exportEpisodicForCloud(tmpDir, "acme/app");
+
+		expect(entries).toHaveLength(1);
+		expect(entries[0]?.repo).toBe("acme/app");
+		expect(entries[0]?.entryType).toBe("review");
+		expect(entries[0]?.title).toBe("Auth fix");
+		expect(entries[0]?.summary).toBe(
+			"Fixed authentication middleware to use JWT",
+		);
+		expect(entries[0]?.relevanceScore).toBe(1.0);
+	});
+
+	test("exports multiple entries with correct types", () => {
+		addEntry(tmpDir, {
+			content: "Added rate limiting",
+			summary: "Rate limit",
+			type: "commit",
+		});
+		addEntry(tmpDir, {
+			content: "Code review feedback on error handling",
+			summary: "Error handling review",
+			type: "review",
+		});
+
+		const entries = exportEpisodicForCloud(tmpDir, "org/repo");
+
+		expect(entries).toHaveLength(2);
+		expect(entries[0]?.entryType).toBe("commit");
+		expect(entries[1]?.entryType).toBe("review");
+		expect(entries[0]?.repo).toBe("org/repo");
+		expect(entries[1]?.repo).toBe("org/repo");
+	});
+
+	test("uses type as title fallback when summary is empty", () => {
+		addEntry(tmpDir, {
+			content: "Some content",
+			summary: "",
+			type: "session",
+		});
+
+		const entries = exportEpisodicForCloud(tmpDir, "acme/app");
+
+		expect(entries).toHaveLength(1);
+		// When summary is empty string, title falls back to type
+		expect(entries[0]?.title).toBe("session");
+	});
+});

package/src/feedback/collector.ts

@@ -1,8 +1,13 @@
 import { hashContent } from "../cache/keys";
+import { loadAuthConfig } from "../cloud/auth";
+import { createCloudClient } from "../cloud/client";
 import { getFeedbackDb } from "../db/index";
+import { getRepoSlug } from "../git/index";
 import { recordOutcome } from "../prompts/engine";
 import { compressReview, storeCompressedReview } from "./compress";
 
+const CLOUD_URL = process.env.MAINA_CLOUD_URL ?? "https://api.mainahq.com";
+
 export interface FeedbackRecord {
 	promptHash: string;
 	task: string;
@@ -88,6 +93,34 @@ export function recordFeedbackWithCompression(
 		});
 		if (compressed) {
 			storeCompressedReview(mainaDir, compressed, record.task);
+
+			// Auto-sync episodic entry to cloud (fire-and-forget)
+			queueMicrotask(async () => {
+				try {
+					const auth = loadAuthConfig();
+					if (auth.ok && auth.value.accessToken) {
+						const client = createCloudClient({
+							baseUrl: CLOUD_URL,
+							token: auth.value.accessToken,
+						});
+						const repo = await getRepoSlug();
+						const title =
+							record.task === "review"
+								? "Accepted review"
+								: `Accepted ${record.task} review`;
+						await client.postEpisodicEntries([
+							{
+								repo,
+								entryType: record.task,
+								title,
+								summary: compressed,
+							},
+						]);
+					}
+				} catch {
+					// Cloud sync failure is silent
+				}
+			});
 		}
 	}
 }
@@ -123,6 +156,27 @@ export function recordFeedbackAsync(
 		} catch {
 			// Never throw from background feedback
 		}
+
+		// Auto-sync to cloud if logged in (fire-and-forget, never blocks)
+		try {
+			const auth = loadAuthConfig();
+			if (auth.ok && auth.value.accessToken) {
+				const client = createCloudClient({
+					baseUrl: CLOUD_URL,
+					token: auth.value.accessToken,
+				});
+				client.postFeedbackBatch([
+					{
+						promptHash: record.promptHash,
+						command: record.task,
+						accepted: record.accepted,
+						context: record.modification,
+					},
+				]);
+			}
+		} catch {
+			// Cloud sync failure is silent
+		}
 	});
 }