@mainahq/core 0.2.0 → 0.4.0

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.");
+}

package/src/cloud/client.ts

@@ -0,0 +1,190 @@
+/**
+ * Cloud HTTP client.
+ *
+ * Provides authenticated access to the maina cloud API for prompt sync,
+ * team management, and feedback reporting. All methods return Result<T, string>.
+ */
+
+import type { Result } from "../db/index";
+import type {
+	ApiResponse,
+	CloudConfig,
+	CloudFeedbackPayload,
+	PromptRecord,
+	TeamInfo,
+	TeamMember,
+} 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 };
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_RETRIES = 3;
+const INITIAL_BACKOFF_MS = 500;
+
+/** Status codes that trigger a retry. */
+function isRetryable(status: number): boolean {
+	return status === 429 || status >= 500;
+}
+
+/**
+ * Sleep for the given number of milliseconds.
+ * Extracted so tests can verify backoff behaviour.
+ */
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── Cloud Client ────────────────────────────────────────────────────────────
+
+export interface CloudClient {
+	/** Check API availability. */
+	health(): Promise<Result<{ status: string }, string>>;
+
+	/** Download team prompts. */
+	getPrompts(): Promise<Result<PromptRecord[], string>>;
+
+	/** Upload local prompts. */
+	putPrompts(prompts: PromptRecord[]): Promise<Result<void, string>>;
+
+	/** Fetch team information. */
+	getTeam(): Promise<Result<TeamInfo, string>>;
+
+	/** List team members. */
+	getTeamMembers(): Promise<Result<TeamMember[], string>>;
+
+	/** Invite a new member by email. */
+	inviteTeamMember(
+		email: string,
+		role?: "admin" | "member",
+	): Promise<Result<{ invited: boolean }, string>>;
+
+	/** Report prompt feedback to the cloud. */
+	postFeedback(
+		payload: CloudFeedbackPayload,
+	): Promise<Result<{ recorded: boolean }, string>>;
+}
+
+/**
+ * Create a cloud API client.
+ *
+ * Every request attaches `Authorization: Bearer <token>` when a token is
+ * present in the config. Transient failures (429, 5xx) are retried up to
+ * `maxRetries` times with exponential backoff.
+ */
+export function createCloudClient(config: CloudConfig): CloudClient {
+	const {
+		baseUrl,
+		token,
+		timeoutMs = DEFAULT_TIMEOUT_MS,
+		maxRetries = DEFAULT_MAX_RETRIES,
+	} = config;
+
+	/** Build standard headers. */
+	function headers(): Record<string, string> {
+		const h: Record<string, string> = {
+			"Content-Type": "application/json",
+			Accept: "application/json",
+		};
+		if (token) {
+			h.Authorization = `Bearer ${token}`;
+		}
+		return h;
+	}
+
+	/** Make an HTTP request with retry + timeout. */
+	async function request<T>(
+		method: string,
+		path: string,
+		body?: unknown,
+	): Promise<Result<T, string>> {
+		let lastError = "Unknown error";
+
+		for (let attempt = 0; attempt <= maxRetries; attempt++) {
+			if (attempt > 0) {
+				const backoff = INITIAL_BACKOFF_MS * 2 ** (attempt - 1);
+				await sleep(backoff);
+			}
+
+			try {
+				const controller = new AbortController();
+				const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+				const response = await fetch(`${baseUrl}${path}`, {
+					method,
+					headers: headers(),
+					body: body ? JSON.stringify(body) : undefined,
+					signal: controller.signal,
+				});
+
+				clearTimeout(timer);
+
+				if (isRetryable(response.status) && attempt < maxRetries) {
+					lastError = `HTTP ${response.status}`;
+					continue;
+				}
+
+				if (!response.ok) {
+					const text = await response.text();
+					let message: string;
+					try {
+						const parsed = JSON.parse(text) as ApiResponse<unknown>;
+						message = parsed.error ?? `HTTP ${response.status}`;
+					} catch {
+						message = text || `HTTP ${response.status}`;
+					}
+					return err(message);
+				}
+
+				// 204 No Content — return void-compatible
+				if (response.status === 204) {
+					return ok(undefined as unknown as T);
+				}
+
+				const json = (await response.json()) as ApiResponse<T>;
+				if (json.error) {
+					return err(json.error);
+				}
+				return ok(json.data as T);
+			} catch (e) {
+				if (
+					e instanceof DOMException &&
+					e.name === "AbortError" &&
+					attempt < maxRetries
+				) {
+					lastError = "Request timed out";
+					continue;
+				}
+				lastError = e instanceof Error ? e.message : String(e);
+				// Transient network errors are retried via the outer loop
+			}
+		}
+
+		return err(`Request failed after ${maxRetries + 1} attempts: ${lastError}`);
+	}
+
+	return {
+		health: () => request<{ status: string }>("GET", "/health"),
+
+		getPrompts: () => request<PromptRecord[]>("GET", "/prompts"),
+
+		putPrompts: (prompts) => request<void>("PUT", "/prompts", { prompts }),
+
+		getTeam: () => request<TeamInfo>("GET", "/team"),
+
+		getTeamMembers: () => request<TeamMember[]>("GET", "/team/members"),
+
+		inviteTeamMember: (email, role = "member") =>
+			request<{ invited: boolean }>("POST", "/team/invite", { email, role }),
+
+		postFeedback: (payload) =>
+			request<{ recorded: boolean }>("POST", "/feedback", payload),
+	};
+}

package/src/cloud/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Cloud client shared types.
+ *
+ * Used by the cloud HTTP client, auth module, and CLI commands
+ * for syncing prompts, team management, and device-flow auth.
+ */
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+export interface CloudConfig {
+	/** Base URL of the maina cloud API (e.g. "https://api.maina.dev"). */
+	baseUrl: string;
+	/** Bearer token for authenticated requests. */
+	token?: string;
+	/** Request timeout in milliseconds. Default: 10_000. */
+	timeoutMs?: number;
+	/** Maximum retry attempts for transient failures. Default: 3. */
+	maxRetries?: number;
+}
+
+// ── Prompts ─────────────────────────────────────────────────────────────────
+
+export interface PromptRecord {
+	/** Unique prompt identifier. */
+	id: string;
+	/** File path relative to .maina/prompts/ (e.g. "commit.md"). */
+	path: string;
+	/** Full prompt content (markdown). */
+	content: string;
+	/** SHA-256 hash of the content for change detection. */
+	hash: string;
+	/** ISO-8601 timestamp of last modification. */
+	updatedAt: string;
+}
+
+// ── Team ────────────────────────────────────────────────────────────────────
+
+export interface TeamInfo {
+	/** Team identifier. */
+	id: string;
+	/** Display name. */
+	name: string;
+	/** Current billing plan. */
+	plan: string;
+	/** Number of seats used / total. */
+	seats: { used: number; total: number };
+}
+
+export interface TeamMember {
+	/** User email. */
+	email: string;
+	/** Role within the team. */
+	role: "owner" | "admin" | "member";
+	/** ISO-8601 join date. */
+	joinedAt: string;
+}
+
+// ── Device-Code OAuth ───────────────────────────────────────────────────────
+
+export interface DeviceCodeResponse {
+	/** The code the user enters on the verification page. */
+	userCode: string;
+	/** The device code used to poll for token completion. */
+	deviceCode: string;
+	/** URL the user should visit. */
+	verificationUri: string;
+	/** Polling interval in seconds. */
+	interval: number;
+	/** Seconds until the device code expires. */
+	expiresIn: number;
+}
+
+export interface TokenResponse {
+	/** Bearer access token. */
+	accessToken: string;
+	/** Refresh token (if applicable). */
+	refreshToken?: string;
+	/** Seconds until the access token expires. */
+	expiresIn: number;
+}
+
+// ── API Envelope ────────────────────────────────────────────────────────────
+
+export interface ApiResponse<T> {
+	/** Response payload (present on success). */
+	data?: T;
+	/** Error message (present on failure). */
+	error?: string;
+	/** Optional metadata. */
+	meta?: Record<string, unknown>;
+}
+
+// ── Feedback ────────────────────────────────────────────────────────────────
+
+export interface CloudFeedbackPayload {
+	/** Prompt hash the feedback refers to. */
+	promptHash: string;
+	/** Command that generated the output. */
+	command: string;
+	/** Whether the user accepted the output. */
+	accepted: boolean;
+	/** ISO-8601 timestamp. */
+	timestamp: string;
+	/** Optional context about the feedback. */
+	context?: string;
+}

package/src/context/relevance.ts

@@ -47,6 +47,11 @@ function resolveImportPath(
 		// Rust
 		`${base}.rs`,
 		`${base}/mod.rs`,
+		// C#
+		`${base}.cs`,
+		// Java
+		`${base}.java`,
+		`${base}.kt`,
 	];
 
 	for (const candidate of candidates) {

package/src/context/retrieval.ts

@@ -236,6 +236,9 @@ export async function searchWithGrep(
 				"--include=*.py",
 				"--include=*.go",
 				"--include=*.rs",
+				"--include=*.cs",
+				"--include=*.java",
+				"--include=*.kt",
 				"--exclude-dir=node_modules",
 				"--exclude-dir=dist",
 				"--exclude-dir=.git",

package/src/context/semantic.ts

@@ -31,6 +31,9 @@ const SOURCE_EXTENSIONS = new Set([
 	".pyi",
 	".go",
 	".rs",
+	".cs",
+	".java",
+	".kt",
 ]);
 
 /**

package/src/feedback/__tests__/trace-analysis.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for post-workflow RL trace analysis.
+ *
+ * Verifies that analyzeWorkflowTrace() reads workflow context,
+ * correlates with feedback data, and generates prompt improvements.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+describe("analyzeWorkflowTrace", () => {
+	let mainaDir: string;
+
+	beforeEach(() => {
+		mainaDir = join(tmpdir(), `maina-trace-test-${Date.now()}`);
+		mkdirSync(join(mainaDir, "workflow"), { recursive: true });
+		mkdirSync(join(mainaDir, "prompts"), { recursive: true });
+	});
+
+	afterEach(() => {
+		rmSync(mainaDir, { recursive: true, force: true });
+	});
+
+	it("should parse workflow context into trace steps", async () => {
+		writeFileSync(
+			join(mainaDir, "workflow", "current.md"),
+			[
+				"# Workflow: feature/test",
+				"",
+				"## plan (2026-04-05T10:00:00.000Z)",
+				"Feature scaffolded.",
+				"",
+				"## commit (2026-04-05T10:05:00.000Z)",
+				"Verified: 8 tools, 0 findings. Committed.",
+			].join("\n"),
+		);
+
+		const { analyzeWorkflowTrace } = await import("../trace-analysis");
+		const result = await analyzeWorkflowTrace(mainaDir);
+
+		expect(result.steps).toHaveLength(2);
+		expect(result.steps[0]?.command).toBe("plan");
+		expect(result.steps[1]?.command).toBe("commit");
+	});
+
+	it("should return empty improvements when no workflow exists", async () => {
+		rmSync(join(mainaDir, "workflow"), { recursive: true, force: true });
+
+		const { analyzeWorkflowTrace } = await import("../trace-analysis");
+		const result = await analyzeWorkflowTrace(mainaDir);
+
+		expect(result.steps).toEqual([]);
+		expect(result.improvements).toEqual([]);
+	});
+
+	it("should generate improvements from trace patterns", async () => {
+		writeFileSync(
+			join(mainaDir, "workflow", "current.md"),
+			[
+				"# Workflow: feature/test",
+				"",
+				"## commit (2026-04-05T10:00:00.000Z)",
+				"Verified: 8 tools, 2 findings. Committed.",
+				"",
+				"## commit (2026-04-05T10:05:00.000Z)",
+				"Verified: 8 tools, 3 findings. Committed.",
+				"",
+				"## commit (2026-04-05T10:10:00.000Z)",
+				"Verified: 8 tools, 0 findings. Committed.",
+			].join("\n"),
+		);
+
+		const { analyzeWorkflowTrace } = await import("../trace-analysis");
+		const result = await analyzeWorkflowTrace(mainaDir);
+
+		expect(result.steps).toHaveLength(3);
+		// Should detect that early commits had findings, suggesting improvement
+		expect(typeof result.summary).toBe("string");
+	});
+
+	it("should return TraceResult with correct shape", async () => {
+		writeFileSync(
+			join(mainaDir, "workflow", "current.md"),
+			"# Workflow: test\n",
+		);
+
+		const { analyzeWorkflowTrace } = await import("../trace-analysis");
+		const result = await analyzeWorkflowTrace(mainaDir);
+
+		expect(result).toHaveProperty("steps");
+		expect(result).toHaveProperty("improvements");
+		expect(result).toHaveProperty("summary");
+		expect(Array.isArray(result.steps)).toBe(true);
+		expect(Array.isArray(result.improvements)).toBe(true);
+	});
+});