@mainahq/core 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mainahq/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Maina core engines — Context, Prompt, and Verify for verification-first development",
@@ -33,5 +33,8 @@
     "@ai-sdk/openai": "^3.0.50",
     "ai": "^6.0.145",
     "drizzle-orm": "^0.45.2"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/ai/__tests__/delegation.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "bun:test";
+import {
+	type DelegationRequest,
+	formatDelegationRequest,
+	parseDelegationRequest,
+} from "../delegation";
+
+describe("formatDelegationRequest", () => {
+	it("should format a request with all fields", () => {
+		const req: DelegationRequest = {
+			task: "ai-review",
+			context: "Reviewing diff for cross-function consistency",
+			prompt: "Review this diff:\n+const x = 1;",
+			expectedFormat: "json",
+			schema: '{"findings":[]}',
+		};
+
+		const formatted = formatDelegationRequest(req);
+
+		expect(formatted).toContain("---MAINA_AI_REQUEST---");
+		expect(formatted).toContain("---END_MAINA_AI_REQUEST---");
+		expect(formatted).toContain("task: ai-review");
+		expect(formatted).toContain("context: Reviewing diff");
+		expect(formatted).toContain("expected_format: json");
+		expect(formatted).toContain("schema: ");
+		expect(formatted).toContain("prompt: |");
+		expect(formatted).toContain("  Review this diff:");
+	});
+
+	it("should format without optional schema", () => {
+		const req: DelegationRequest = {
+			task: "commit-msg",
+			context: "Generate commit message",
+			prompt: "Generate a commit message for these changes",
+			expectedFormat: "text",
+		};
+
+		const formatted = formatDelegationRequest(req);
+		expect(formatted).not.toContain("schema:");
+	});
+});
+
+describe("parseDelegationRequest", () => {
+	it("should parse a formatted request back", () => {
+		const original: DelegationRequest = {
+			task: "ai-review",
+			context: "Reviewing diff",
+			prompt: "Review this diff:\n+const x = 1;",
+			expectedFormat: "json",
+			schema: '{"findings":[]}',
+		};
+
+		const formatted = formatDelegationRequest(original);
+		const parsed = parseDelegationRequest(formatted);
+
+		expect(parsed).not.toBeNull();
+		expect(parsed?.task).toBe("ai-review");
+		expect(parsed?.context).toBe("Reviewing diff");
+		expect(parsed?.expectedFormat).toBe("json");
+		expect(parsed?.schema).toBe('{"findings":[]}');
+		expect(parsed?.prompt).toContain("Review this diff:");
+		expect(parsed?.prompt).toContain("+const x = 1;");
+	});
+
+	it("should return null for text without markers", () => {
+		expect(parseDelegationRequest("no markers here")).toBeNull();
+	});
+
+	it("should return null for empty task", () => {
+		const text =
+			"---MAINA_AI_REQUEST---\ncontext: test\n---END_MAINA_AI_REQUEST---";
+		expect(parseDelegationRequest(text)).toBeNull();
+	});
+
+	it("should handle multiline prompts", () => {
+		const req: DelegationRequest = {
+			task: "review",
+			context: "Code review",
+			prompt: "Line 1\nLine 2\nLine 3",
+			expectedFormat: "markdown",
+		};
+
+		const formatted = formatDelegationRequest(req);
+		const parsed = parseDelegationRequest(formatted);
+
+		expect(parsed?.prompt).toContain("Line 1");
+		expect(parsed?.prompt).toContain("Line 2");
+		expect(parsed?.prompt).toContain("Line 3");
+	});
+
+	it("should parse request embedded in other text", () => {
+		const text = `Some output before
+---MAINA_AI_REQUEST---
+task: test
+context: testing
+prompt: |
+  hello
+---END_MAINA_AI_REQUEST---
+Some output after`;
+
+		const parsed = parseDelegationRequest(text);
+		expect(parsed?.task).toBe("test");
+		expect(parsed?.prompt).toBe("hello");
+	});
+});

package/src/ai/delegation.ts

@@ -0,0 +1,111 @@
+/**
+ * AI Delegation Protocol — structured stdout protocol for host agents.
+ *
+ * When maina runs inside Claude Code/Codex/OpenCode without an API key,
+ * AI-dependent steps output request blocks that the host agent can
+ * parse and process with its own AI.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface DelegationRequest {
+	task: string;
+	context: string;
+	prompt: string;
+	expectedFormat: "json" | "markdown" | "text";
+	schema?: string;
+}
+
+// ─── Constants ────────────────────────────────────────────────────────────
+
+const START_MARKER = "---MAINA_AI_REQUEST---";
+const END_MARKER = "---END_MAINA_AI_REQUEST---";
+
+// ─── Format ───────────────────────────────────────────────────────────────
+
+/**
+ * Format a delegation request as a structured text block.
+ * This block is output to stdout for host agents to parse.
+ */
+export function formatDelegationRequest(req: DelegationRequest): string {
+	const lines: string[] = [START_MARKER];
+	lines.push(`task: ${req.task}`);
+	lines.push(`context: ${req.context}`);
+	lines.push(`expected_format: ${req.expectedFormat}`);
+	if (req.schema) {
+		lines.push(`schema: ${req.schema}`);
+	}
+	lines.push("prompt: |");
+	// Indent prompt lines by 2 spaces (YAML-style block scalar)
+	for (const line of req.prompt.split("\n")) {
+		lines.push(`  ${line}`);
+	}
+	lines.push(END_MARKER);
+	return lines.join("\n");
+}
+
+// ─── Parse ────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a delegation request block from text.
+ * Returns null if the text doesn't contain a valid request block.
+ */
+export function parseDelegationRequest(text: string): DelegationRequest | null {
+	const startIdx = text.indexOf(START_MARKER);
+	const endIdx = text.indexOf(END_MARKER);
+	if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+		return null;
+	}
+
+	const block = text.slice(startIdx + START_MARKER.length, endIdx).trim();
+	const lines = block.split("\n");
+
+	let task = "";
+	let context = "";
+	let expectedFormat: DelegationRequest["expectedFormat"] = "text";
+	let schema: string | undefined;
+	const promptLines: string[] = [];
+	let inPrompt = false;
+
+	for (const line of lines) {
+		if (inPrompt) {
+			// Prompt lines are indented by 2 spaces
+			promptLines.push(line.startsWith("  ") ? line.slice(2) : line);
+			continue;
+		}
+
+		if (line.startsWith("task: ")) {
+			task = line.slice(6).trim();
+		} else if (line.startsWith("context: ")) {
+			context = line.slice(9).trim();
+		} else if (line.startsWith("expected_format: ")) {
+			const fmt = line.slice(17).trim();
+			if (fmt === "json" || fmt === "markdown" || fmt === "text") {
+				expectedFormat = fmt;
+			}
+		} else if (line.startsWith("schema: ")) {
+			schema = line.slice(8).trim();
+		} else if (line.startsWith("prompt: |")) {
+			inPrompt = true;
+		}
+	}
+
+	if (!task) return null;
+
+	return {
+		task,
+		context,
+		prompt: promptLines.join("\n").trim(),
+		expectedFormat,
+		schema,
+	};
+}
+
+/**
+ * Output a delegation request to stdout.
+ * Used by tryAIGenerate when in host mode.
+ */
+export function outputDelegationRequest(req: DelegationRequest): void {
+	const formatted = formatDelegationRequest(req);
+	process.stdout.write(`\n${formatted}\n`);
+}

package/src/ai/try-generate.ts

@@ -1,4 +1,5 @@
 import { getApiKey, isHostMode } from "../config/index";
+import { outputDelegationRequest } from "./delegation";
 
 export interface DelegationPrompt {
 	task: string;
@@ -69,6 +70,22 @@ export async function tryAIGenerate(
 			}
 		}
 
+		// Output structured request for host agent to process
+		outputDelegationRequest({
+			task,
+			context: `AI ${task} requested — process with host AI`,
+			prompt: userPrompt,
+			expectedFormat:
+				task === "commit"
+					? "text"
+					: task.includes("review")
+						? "json"
+						: "markdown",
+			schema: task.includes("review")
+				? '{"findings":[{"file":"path","line":42,"message":"desc","severity":"warning"}]}'
+				: undefined,
+		});
+
 		// Host mode — return structured delegation for host agent to process
 		return {
 			text: null,

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

@@ -0,0 +1,164 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	clearAuthConfig,
+	getAuthConfigPath,
+	loadAuthConfig,
+	saveAuthConfig,
+	startDeviceFlow,
+} from "../auth";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+const originalFetch = globalThis.fetch;
+
+let tmpDir: string;
+let mockFetch: ReturnType<typeof mock>;
+
+function jsonResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "Content-Type": "application/json" },
+	});
+}
+
+// ── Setup / Teardown ────────────────────────────────────────────────────────
+
+beforeEach(() => {
+	tmpDir = join(
+		import.meta.dir,
+		`tmp-auth-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+
+	mockFetch = mock(() =>
+		Promise.resolve(jsonResponse({ data: { status: "ok" } })),
+	);
+	globalThis.fetch = mockFetch as unknown as typeof fetch;
+});
+
+afterEach(() => {
+	globalThis.fetch = originalFetch;
+	try {
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		// ignore
+	}
+});
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("getAuthConfigPath", () => {
+	test("returns path inside custom config dir", () => {
+		const path = getAuthConfigPath("/custom/dir");
+		expect(path).toBe("/custom/dir/auth.json");
+	});
+
+	test("defaults to home directory", () => {
+		const path = getAuthConfigPath();
+		expect(path).toContain(".maina");
+		expect(path).toEndWith("auth.json");
+	});
+});
+
+describe("saveAuthConfig / loadAuthConfig", () => {
+	test("round-trips auth config", () => {
+		const config = {
+			accessToken: "tok-abc-123",
+			refreshToken: "ref-xyz",
+			expiresAt: "2026-12-31T23:59:59Z",
+		};
+
+		const saveResult = saveAuthConfig(config, tmpDir);
+		expect(saveResult.ok).toBe(true);
+
+		const loadResult = loadAuthConfig(tmpDir);
+		expect(loadResult.ok).toBe(true);
+		if (loadResult.ok) {
+			expect(loadResult.value.accessToken).toBe("tok-abc-123");
+			expect(loadResult.value.refreshToken).toBe("ref-xyz");
+			expect(loadResult.value.expiresAt).toBe("2026-12-31T23:59:59Z");
+		}
+	});
+
+	test("creates parent directories", () => {
+		const nested = join(tmpDir, "a", "b", "c");
+		const result = saveAuthConfig({ accessToken: "t" }, nested);
+		expect(result.ok).toBe(true);
+		expect(existsSync(join(nested, "auth.json"))).toBe(true);
+	});
+
+	test("returns error when not logged in", () => {
+		const result = loadAuthConfig(join(tmpDir, "nonexistent"));
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toContain("Not logged in");
+		}
+	});
+
+	test("returns error for malformed config", () => {
+		const authPath = join(tmpDir, "auth.json");
+		writeFileSync(authPath, '{"no_token": true}', "utf-8");
+
+		const result = loadAuthConfig(tmpDir);
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toContain("missing accessToken");
+		}
+	});
+});
+
+describe("clearAuthConfig", () => {
+	test("removes auth file", () => {
+		saveAuthConfig({ accessToken: "t" }, tmpDir);
+		const authPath = getAuthConfigPath(tmpDir);
+		expect(existsSync(authPath)).toBe(true);
+
+		const result = clearAuthConfig(tmpDir);
+		expect(result.ok).toBe(true);
+		expect(existsSync(authPath)).toBe(false);
+	});
+
+	test("succeeds when no file exists", () => {
+		const result = clearAuthConfig(join(tmpDir, "nonexistent"));
+		expect(result.ok).toBe(true);
+	});
+});
+
+describe("startDeviceFlow", () => {
+	test("returns device code response on success", async () => {
+		const deviceData = {
+			userCode: "ABCD-1234",
+			deviceCode: "dev-code-xyz",
+			verificationUri: "https://maina.dev/device",
+			interval: 5,
+			expiresIn: 900,
+		};
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: deviceData })),
+		);
+
+		const result = await startDeviceFlow("https://api.maina.dev");
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.userCode).toBe("ABCD-1234");
+			expect(result.value.deviceCode).toBe("dev-code-xyz");
+			expect(result.value.verificationUri).toBe("https://maina.dev/device");
+		}
+	});
+
+	test("returns error on API failure", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Service unavailable" }, 503)),
+		);
+
+		const result = await startDeviceFlow("https://api.maina.dev");
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toContain("503");
+		}
+	});
+});

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

@@ -0,0 +1,253 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { type CloudClient, createCloudClient } from "../client";
+import type { CloudConfig } from "../types";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+const originalFetch = globalThis.fetch;
+
+let mockFetch: ReturnType<typeof mock>;
+
+function jsonResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "Content-Type": "application/json" },
+	});
+}
+
+function setupClient(overrides?: Partial<CloudConfig>): CloudClient {
+	return createCloudClient({
+		baseUrl: "https://api.test.maina.dev",
+		token: "test-token-abc",
+		timeoutMs: 5_000,
+		maxRetries: 2,
+		...overrides,
+	});
+}
+
+// ── Setup / Teardown ────────────────────────────────────────────────────────
+
+beforeEach(() => {
+	mockFetch = mock(() =>
+		Promise.resolve(jsonResponse({ data: { status: "ok" } })),
+	);
+	globalThis.fetch = mockFetch as unknown as typeof fetch;
+});
+
+afterEach(() => {
+	globalThis.fetch = originalFetch;
+});
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("createCloudClient", () => {
+	test("health returns ok status", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { status: "ok" } })),
+		);
+
+		const client = setupClient();
+		const result = await client.health();
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.status).toBe("ok");
+		}
+	});
+
+	test("attaches Authorization header when token is provided", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { status: "ok" } })),
+		);
+
+		const client = setupClient({ token: "my-secret-token" });
+		await client.health();
+
+		expect(mockFetch).toHaveBeenCalledTimes(1);
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const requestInit = call[1] as RequestInit;
+		const authHeader = (requestInit.headers as Record<string, string>)
+			.Authorization;
+		expect(authHeader).toBe("Bearer my-secret-token");
+	});
+
+	test("omits Authorization header when no token", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { status: "ok" } })),
+		);
+
+		const client = setupClient({ token: undefined });
+		await client.health();
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const requestInit = call[1] as RequestInit;
+		const h = requestInit.headers as Record<string, string>;
+		expect(h.Authorization).toBeUndefined();
+	});
+
+	test("retries on 500 errors", async () => {
+		let attempts = 0;
+		mockFetch.mockImplementation(() => {
+			attempts++;
+			if (attempts < 3) {
+				return Promise.resolve(jsonResponse({ error: "Internal error" }, 500));
+			}
+			return Promise.resolve(jsonResponse({ data: { status: "ok" } }));
+		});
+
+		const client = setupClient({ maxRetries: 2 });
+		const result = await client.health();
+
+		expect(result.ok).toBe(true);
+		expect(attempts).toBe(3);
+	});
+
+	test("retries on 429 rate limit", async () => {
+		let attempts = 0;
+		mockFetch.mockImplementation(() => {
+			attempts++;
+			if (attempts === 1) {
+				return Promise.resolve(
+					jsonResponse({ error: "Too many requests" }, 429),
+				);
+			}
+			return Promise.resolve(jsonResponse({ data: { status: "ok" } }));
+		});
+
+		const client = setupClient({ maxRetries: 2 });
+		const result = await client.health();
+
+		expect(result.ok).toBe(true);
+		expect(attempts).toBe(2);
+	});
+
+	test("returns error after exhausting retries", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Server down" }, 503)),
+		);
+
+		const client = setupClient({ maxRetries: 1 });
+		const result = await client.health();
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toContain("Server down");
+		}
+	});
+
+	test("returns error on non-retryable 4xx", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ error: "Forbidden" }, 403)),
+		);
+
+		const client = setupClient();
+		const result = await client.health();
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toBe("Forbidden");
+		}
+	});
+
+	test("getPrompts returns prompt records", async () => {
+		const prompts = [
+			{
+				id: "p1",
+				path: "commit.md",
+				content: "# Commit",
+				hash: "abc",
+				updatedAt: "2026-01-01T00:00:00Z",
+			},
+		];
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: prompts })),
+		);
+
+		const client = setupClient();
+		const result = await client.getPrompts();
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toHaveLength(1);
+			expect(result.value[0]?.path).toBe("commit.md");
+		}
+	});
+
+	test("putPrompts sends prompts array", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(new Response(null, { status: 204 })),
+		);
+
+		const client = setupClient();
+		const result = await client.putPrompts([
+			{
+				id: "p1",
+				path: "commit.md",
+				content: "# Commit",
+				hash: "abc",
+				updatedAt: "2026-01-01T00:00:00Z",
+			},
+		]);
+
+		expect(result.ok).toBe(true);
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const requestInit = call[1] as RequestInit;
+		expect(requestInit.method).toBe("PUT");
+		const body = JSON.parse(requestInit.body as string);
+		expect(body.prompts).toHaveLength(1);
+	});
+
+	test("inviteTeamMember sends email and role", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { invited: true } })),
+		);
+
+		const client = setupClient();
+		const result = await client.inviteTeamMember("new@example.com", "admin");
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.invited).toBe(true);
+		}
+
+		const call = mockFetch.mock.calls[0] as unknown[];
+		const requestInit = call[1] as RequestInit;
+		const body = JSON.parse(requestInit.body as string);
+		expect(body.email).toBe("new@example.com");
+		expect(body.role).toBe("admin");
+	});
+
+	test("postFeedback sends payload", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.resolve(jsonResponse({ data: { recorded: true } })),
+		);
+
+		const client = setupClient();
+		const result = await client.postFeedback({
+			promptHash: "hash-123",
+			command: "commit",
+			accepted: true,
+			timestamp: "2026-01-01T00:00:00Z",
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.recorded).toBe(true);
+		}
+	});
+
+	test("handles network errors gracefully", async () => {
+		mockFetch.mockImplementation(() =>
+			Promise.reject(new Error("Network unreachable")),
+		);
+
+		const client = setupClient({ maxRetries: 0 });
+		const result = await client.health();
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toContain("Network unreachable");
+		}
+	});
+});