@mainahq/core 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mainahq/core",
-  "version": "0.3.0",
+  "version": "0.5.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/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");
+		}
+	});
+});

package/src/cloud/auth.ts

@@ -0,0 +1,232 @@
+/**
+ * OAuth device-flow authentication.
+ *
+ * Implements the device authorization grant (RFC 8628) for CLI login.
+ * Tokens are stored at ~/.maina/auth.json.
+ */
+
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { Result } from "../db/index";
+import type { DeviceCodeResponse, TokenResponse } from "./types";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function ok<T>(value: T): Result<T, string> {
+	return { ok: true, value };
+}
+
+function err(error: string): Result<never, string> {
+	return { ok: false, error };
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── Auth Config Path ────────────────────────────────────────────────────────
+
+export interface AuthConfig {
+	/** Bearer access token. */
+	accessToken: string;
+	/** Refresh token (if available). */
+	refreshToken?: string;
+	/** ISO-8601 timestamp when the token expires. */
+	expiresAt?: string;
+}
+
+/**
+ * Return the path to the auth config file.
+ * Uses `configDir` override for testing; defaults to `~/.maina/auth.json`.
+ */
+export function getAuthConfigPath(configDir?: string): string {
+	const dir = configDir ?? join(homedir(), ".maina");
+	return join(dir, "auth.json");
+}
+
+// ── Load / Save / Clear ─────────────────────────────────────────────────────
+
+/**
+ * Load saved auth config from disk.
+ * Returns err if not logged in or the file is malformed.
+ */
+export function loadAuthConfig(configDir?: string): Result<AuthConfig, string> {
+	const path = getAuthConfigPath(configDir);
+	if (!existsSync(path)) {
+		return err("Not logged in. Run `maina login` first.");
+	}
+
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw) as AuthConfig;
+		if (!parsed.accessToken) {
+			return err("Auth config is missing accessToken.");
+		}
+		return ok(parsed);
+	} catch (e) {
+		return err(
+			`Failed to read auth config: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
+}
+
+/**
+ * Persist auth config to disk.
+ */
+export function saveAuthConfig(
+	config: AuthConfig,
+	configDir?: string,
+): Result<void, string> {
+	const path = getAuthConfigPath(configDir);
+
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, JSON.stringify(config, null, 2), "utf-8");
+		return ok(undefined);
+	} catch (e) {
+		return err(
+			`Failed to save auth config: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
+}
+
+/**
+ * Remove auth config from disk (logout).
+ */
+export function clearAuthConfig(configDir?: string): Result<void, string> {
+	const path = getAuthConfigPath(configDir);
+	if (!existsSync(path)) {
+		return ok(undefined);
+	}
+
+	try {
+		unlinkSync(path);
+		return ok(undefined);
+	} catch (e) {
+		return err(
+			`Failed to clear auth config: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
+}
+
+// ── Device Flow ─────────────────────────────────────────────────────────────
+
+/**
+ * Initiate the device authorization flow.
+ *
+ * Calls `POST /auth/device` on the cloud API to obtain a user code and
+ * verification URI.
+ */
+export async function startDeviceFlow(
+	baseUrl: string,
+): Promise<Result<DeviceCodeResponse, string>> {
+	try {
+		const response = await fetch(`${baseUrl}/auth/device`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Accept: "application/json",
+			},
+		});
+
+		if (!response.ok) {
+			const text = await response.text();
+			return err(
+				`Device flow initiation failed (HTTP ${response.status}): ${text}`,
+			);
+		}
+
+		const body = (await response.json()) as {
+			data?: DeviceCodeResponse;
+			error?: string;
+		};
+		if (body.error) {
+			return err(body.error);
+		}
+		if (!body.data) {
+			return err("Invalid response: missing data");
+		}
+		return ok(body.data);
+	} catch (e) {
+		return err(
+			`Device flow request failed: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
+}
+
+/**
+ * Poll the cloud API until the user completes the device flow or the code
+ * expires.
+ *
+ * Respects the `interval` returned by the server. Returns the token
+ * response on success.
+ */
+export async function pollForToken(
+	baseUrl: string,
+	deviceCode: string,
+	interval: number,
+	expiresIn: number,
+): Promise<Result<TokenResponse, string>> {
+	const deadline = Date.now() + expiresIn * 1000;
+	const pollInterval = Math.max(interval, 5) * 1000;
+
+	while (Date.now() < deadline) {
+		await sleep(pollInterval);
+
+		try {
+			const response = await fetch(`${baseUrl}/auth/token`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Accept: "application/json",
+				},
+				body: JSON.stringify({
+					deviceCode,
+					grantType: "urn:ietf:params:oauth:grant-type:device_code",
+				}),
+			});
+
+			if (response.status === 428 || response.status === 400) {
+				// "authorization_pending" — the user hasn't completed login yet
+				continue;
+			}
+
+			if (!response.ok) {
+				const text = await response.text();
+				return err(`Token request failed (HTTP ${response.status}): ${text}`);
+			}
+
+			const body = (await response.json()) as {
+				data?: TokenResponse;
+				error?: string;
+			};
+			if (body.error) {
+				// "slow_down" → increase interval
+				if (body.error === "slow_down") {
+					continue;
+				}
+				return err(body.error);
+			}
+			if (!body.data) {
+				return err("Invalid token response: missing data");
+			}
+			return ok(body.data);
+		} catch (e) {
+			// Network errors during polling are transient — keep trying
+			if (Date.now() >= deadline) {
+				return err(
+					`Token polling failed: ${e instanceof Error ? e.message : String(e)}`,
+				);
+			}
+		}
+	}
+
+	return err("Device code expired. Please try logging in again.");
+}