@mainahq/core 0.3.0 → 0.5.0

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

package/src/feedback/trace-analysis.ts

@@ -0,0 +1,153 @@
+/**
+ * Post-workflow RL Trace Analysis — analyzes completed workflow traces
+ * to propose prompt improvements.
+ *
+ * After a full workflow completes (brainstorm → ... → pr):
+ * 1. Collects the full trace from workflow context
+ * 2. Analyzes: which steps had issues? How did findings trend?
+ * 3. Proposes prompt improvements based on patterns
+ * 4. Feeds into maina learn automatically
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface TraceStep {
+	command: string;
+	timestamp: string;
+	summary: string;
+	findingsCount?: number;
+}
+
+export interface PromptImprovement {
+	promptFile: string;
+	reason: string;
+	suggestion: string;
+	confidence: number;
+}
+
+export interface TraceResult {
+	steps: TraceStep[];
+	improvements: PromptImprovement[];
+	summary: string;
+}
+
+// ─── Trace Parsing ───────────────────────────────────────────────────────
+
+/**
+ * Parse the workflow context file into structured trace steps.
+ */
+function parseWorkflowContext(content: string): TraceStep[] {
+	const steps: TraceStep[] = [];
+	const stepPattern =
+		/^## (\w+) \((\d{4}-\d{2}-\d{2}T[\d:.]+Z)\)\s*\n([\s\S]*?)(?=\n## |\n*$)/gm;
+
+	for (const match of content.matchAll(stepPattern)) {
+		const command = match[1] ?? "";
+		const timestamp = match[2] ?? "";
+		const summary = (match[3] ?? "").trim();
+
+		// Extract findings count if present
+		const findingsMatch = summary.match(/(\d+)\s+findings?/);
+		const findingsCount = findingsMatch
+			? Number.parseInt(findingsMatch[1] ?? "0", 10)
+			: undefined;
+
+		steps.push({ command, timestamp, summary, findingsCount });
+	}
+
+	return steps;
+}
+
+// ─── Analysis ────────────────────────────────────────────────────────────
+
+/**
+ * Analyze trace steps for patterns that suggest prompt improvements.
+ */
+function analyzePatterns(steps: TraceStep[]): PromptImprovement[] {
+	const improvements: PromptImprovement[] = [];
+
+	// Pattern 1: Multiple commits with findings before a clean one
+	const commitSteps = steps.filter(
+		(s) => s.command === "commit" && s.findingsCount !== undefined,
+	);
+	const dirtyCommits = commitSteps.filter(
+		(s) => s.findingsCount !== undefined && s.findingsCount > 0,
+	);
+
+	if (dirtyCommits.length >= 2) {
+		improvements.push({
+			promptFile: "prompts/review.md",
+			reason: `${dirtyCommits.length} commits had verification findings before clean pass — review prompt may need to catch these patterns earlier.`,
+			suggestion:
+				"Add examples of common finding patterns to the review prompt so AI catches them in the first pass.",
+			confidence: 0.6,
+		});
+	}
+
+	// Pattern 2: Workflow has no review step
+	const hasReview = steps.some((s) => s.command === "review");
+	if (steps.length >= 3 && !hasReview) {
+		improvements.push({
+			promptFile: "prompts/commit.md",
+			reason:
+				"Workflow completed without a review step — commit prompt could remind about review.",
+			suggestion:
+				"Add a reminder to run maina review before committing when changes are substantial.",
+			confidence: 0.4,
+		});
+	}
+
+	return improvements;
+}
+
+/**
+ * Generate a human-readable summary of the trace analysis.
+ */
+function generateSummary(
+	steps: TraceStep[],
+	improvements: PromptImprovement[],
+): string {
+	if (steps.length === 0) return "No workflow trace found.";
+
+	const commands = steps.map((s) => s.command).join(" → ");
+	const totalFindings = steps
+		.filter((s) => s.findingsCount !== undefined)
+		.reduce((sum, s) => sum + (s.findingsCount ?? 0), 0);
+
+	let summary = `Workflow: ${commands} (${steps.length} steps, ${totalFindings} total findings)`;
+
+	if (improvements.length > 0) {
+		summary += `\n${improvements.length} improvement(s) suggested.`;
+	}
+
+	return summary;
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────
+
+/**
+ * Analyze the current workflow trace and generate improvement proposals.
+ *
+ * This runs after maina pr completes. It reads the workflow context,
+ * correlates with feedback data, and proposes prompt improvements
+ * that are automatically fed into maina learn.
+ */
+export async function analyzeWorkflowTrace(
+	mainaDir: string,
+): Promise<TraceResult> {
+	const workflowFile = join(mainaDir, "workflow", "current.md");
+
+	if (!existsSync(workflowFile)) {
+		return { steps: [], improvements: [], summary: "No workflow trace found." };
+	}
+
+	const content = readFileSync(workflowFile, "utf-8");
+	const steps = parseWorkflowContext(content);
+	const improvements = analyzePatterns(steps);
+	const summary = generateSummary(steps, improvements);
+
+	return { steps, improvements, summary };
+}

package/src/index.ts

@@ -50,6 +50,26 @@ export {
 	type CacheStats,
 	createCacheManager,
 } from "./cache/manager";
+// Cloud
+export {
+	type AuthConfig,
+	clearAuthConfig,
+	loadAuthConfig,
+	pollForToken,
+	saveAuthConfig,
+	startDeviceFlow,
+} from "./cloud/auth";
+export { type CloudClient, createCloudClient } from "./cloud/client";
+export type {
+	ApiResponse,
+	CloudConfig,
+	CloudFeedbackPayload,
+	DeviceCodeResponse,
+	PromptRecord,
+	TeamInfo,
+	TeamMember,
+	TokenResponse,
+} from "./cloud/types";
 // Config
 export { getApiKey, isHostMode, shouldDelegateToHost } from "./config/index";
 export { calculateTokens } from "./context/budget";
@@ -144,6 +164,12 @@ export {
 	type RulePreference,
 	savePreferences,
 } from "./feedback/preferences";
+export {
+	analyzeWorkflowTrace,
+	type PromptImprovement,
+	type TraceResult,
+	type TraceStep,
+} from "./feedback/trace-analysis";
 // Git
 export {
 	type Commit,
@@ -268,6 +294,10 @@ export {
 	resolveReferencedFunctions,
 	runAIReview,
 } from "./verify/ai-review";
+export {
+	type ConsistencyResult,
+	checkConsistency,
+} from "./verify/consistency";
 // Verify — Coverage
 export {
 	type CoverageOptions,
@@ -298,6 +328,13 @@ export {
 	hashFinding,
 	parseFixResponse,
 } from "./verify/fix";
+// Verify — Lighthouse
+export {
+	type LighthouseOptions,
+	type LighthouseResult,
+	parseLighthouseJson,
+	runLighthouse,
+} from "./verify/lighthouse";
 // Verify — Mutation
 export {
 	type MutationOptions,
@@ -343,6 +380,8 @@ export {
 	type SyntaxGuardResult,
 	syntaxGuard,
 } from "./verify/syntax-guard";
+// Verify — Typecheck + Consistency (built-in checks)
+export { runTypecheck, type TypecheckResult } from "./verify/typecheck";
 // Verify — Visual
 export {
 	captureScreenshot,
@@ -357,6 +396,13 @@ export {
 	type VisualDiffResult,
 	type VisualVerifyResult,
 } from "./verify/visual";
+// Verify — ZAP DAST
+export {
+	parseZapJson,
+	runZap,
+	type ZapOptions,
+	type ZapResult,
+} from "./verify/zap";
 // Workflow
 export {
 	appendWorkflowStep,

package/src/init/__tests__/init.test.ts

@@ -225,4 +225,55 @@ describe("bootstrap", () => {
 			}
 		}
 	});
+
+	test("auto-configures biome.json when no linter detected", async () => {
+		// Project with no linter in dependencies
+		writeFileSync(
+			join(tmpDir, "package.json"),
+			JSON.stringify({ dependencies: {} }),
+		);
+
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			const biomePath = join(tmpDir, "biome.json");
+			expect(existsSync(biomePath)).toBe(true);
+
+			const biomeConfig = JSON.parse(readFileSync(biomePath, "utf-8"));
+			expect(biomeConfig.linter.enabled).toBe(true);
+			expect(biomeConfig.linter.rules.recommended).toBe(true);
+			expect(biomeConfig.formatter.enabled).toBe(true);
+
+			expect(result.value.created).toContain("biome.json");
+			expect(result.value.detectedStack.linter).toBe("biome");
+		}
+	});
+
+	test("does not overwrite existing biome.json", async () => {
+		writeFileSync(
+			join(tmpDir, "package.json"),
+			JSON.stringify({ dependencies: {} }),
+		);
+		writeFileSync(join(tmpDir, "biome.json"), '{"custom": true}');
+
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+
+		const content = readFileSync(join(tmpDir, "biome.json"), "utf-8");
+		expect(JSON.parse(content)).toEqual({ custom: true });
+	});
+
+	test("skips biome.json when linter already detected", async () => {
+		writeFileSync(
+			join(tmpDir, "package.json"),
+			JSON.stringify({ devDependencies: { eslint: "^9.0.0" } }),
+		);
+
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(existsSync(join(tmpDir, "biome.json"))).toBe(false);
+			expect(result.value.detectedStack.linter).toBe("eslint");
+		}
+	});
 });