@os-eco/overstory-cli 0.6.10 → 0.7.0

package/src/mulch/client.ts

@@ -2,7 +2,11 @@
  * Mulch CLI client.
  *
  * Wraps the `mulch` command-line tool for structured expertise operations.
- * Uses Bun.spawn — zero runtime dependencies.
+ * record(), search(), and query() use the @os-eco/mulch-cli programmatic API
+ * via a variable-based dynamic import so tsc cannot statically resolve the
+ * module (avoiding type errors in mulch's raw .ts source files).
+ * Remaining methods (prime, status, diff, learn, prune, doctor, ready, compact)
+ * remain as Bun.spawn CLI wrappers.
  */
 
 import { AgentError } from "../errors.ts";
@@ -87,6 +91,149 @@ export interface MulchClient {
 	): Promise<MulchCompactResult>;
 }
 
+/**
+ * Local type matching @os-eco/mulch-cli ExpertiseRecord.
+ * Defined locally to avoid tsc following into mulch's raw .ts source
+ * (which conflicts with our noUncheckedIndexedAccess setting).
+ */
+type MulchClassification = "foundational" | "tactical" | "observational";
+
+interface MulchEvidence {
+	commit?: string;
+	date?: string;
+	issue?: string;
+	file?: string;
+	bead?: string;
+}
+
+interface MulchOutcome {
+	status: "success" | "failure" | "partial";
+	duration?: number;
+	test_results?: string;
+	agent?: string;
+	notes?: string;
+	recorded_at?: string;
+}
+
+type MulchExpertiseRecord =
+	| {
+			type: "convention";
+			content: string;
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "pattern";
+			name: string;
+			description: string;
+			files?: string[];
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "failure";
+			description: string;
+			resolution: string;
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "decision";
+			title: string;
+			rationale: string;
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "reference";
+			name: string;
+			description: string;
+			files?: string[];
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "guide";
+			name: string;
+			description: string;
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  };
+
+/**
+ * Interface for mulch programmatic API functions.
+ * Uses a dynamic import with a variable specifier so tsc cannot statically
+ * resolve the module (avoiding type errors in mulch's raw .ts source files).
+ */
+interface MulchProgrammaticApi {
+	recordExpertise(
+		domain: string,
+		record: MulchExpertiseRecord,
+		options?: { force?: boolean; cwd?: string },
+	): Promise<{ action: "created" | "updated" | "skipped"; record: MulchExpertiseRecord }>;
+	searchExpertise(
+		query: string,
+		options?: {
+			domain?: string;
+			type?: string;
+			tag?: string;
+			classification?: string;
+			file?: string;
+			cwd?: string;
+		},
+	): Promise<Array<{ domain: string; records: MulchExpertiseRecord[] }>>;
+	queryDomain(
+		domain: string,
+		options?: { type?: string; classification?: string; file?: string; cwd?: string },
+	): Promise<MulchExpertiseRecord[]>;
+}
+
+const MULCH_PKG = "@os-eco/mulch-cli";
+let _mulchApi: MulchProgrammaticApi | undefined;
+
+async function loadMulchApi(): Promise<MulchProgrammaticApi> {
+	if (!_mulchApi) {
+		_mulchApi = (await import(MULCH_PKG)) as MulchProgrammaticApi;
+	}
+	return _mulchApi;
+}
+
 /**
  * Run a shell command and capture its output.
  */
@@ -105,6 +252,127 @@ async function runCommand(
 	return { stdout, stderr, exitCode };
 }
 
+/**
+ * Build an ExpertiseRecord from record() options.
+ *
+ * CRITICAL MAPPING: --description maps to record.content for convention records,
+ * but to record.description for all other types.
+ */
+function buildExpertiseRecord(options: {
+	type: string;
+	name?: string;
+	description?: string;
+	title?: string;
+	rationale?: string;
+	tags?: string[];
+	classification?: string;
+	evidenceBead?: string;
+	outcomeStatus?: "success" | "failure";
+	outcomeDuration?: number;
+	outcomeTestResults?: string;
+	outcomeAgent?: string;
+}): MulchExpertiseRecord {
+	const base = {
+		classification: (options.classification ?? "tactical") as
+			| "foundational"
+			| "tactical"
+			| "observational",
+		recorded_at: new Date().toISOString(),
+		tags: options.tags,
+		evidence: options.evidenceBead ? { bead: options.evidenceBead } : undefined,
+		outcomes: options.outcomeStatus
+			? [
+					{
+						status: options.outcomeStatus as "success" | "failure" | "partial",
+						duration: options.outcomeDuration,
+						test_results: options.outcomeTestResults,
+						agent: options.outcomeAgent,
+						recorded_at: new Date().toISOString(),
+					},
+				]
+			: undefined,
+	};
+
+	switch (options.type) {
+		case "convention":
+			return { ...base, type: "convention", content: options.description ?? "" };
+		case "pattern":
+			return {
+				...base,
+				type: "pattern",
+				name: options.name ?? "",
+				description: options.description ?? "",
+			};
+		case "failure":
+			return {
+				...base,
+				type: "failure",
+				description: options.description ?? "",
+				resolution: "",
+			};
+		case "decision":
+			return {
+				...base,
+				type: "decision",
+				title: options.title ?? "",
+				rationale: options.rationale ?? "",
+			};
+		case "reference":
+			return {
+				...base,
+				type: "reference",
+				name: options.name ?? "",
+				description: options.description ?? "",
+			};
+		case "guide":
+			return {
+				...base,
+				type: "guide",
+				name: options.name ?? "",
+				description: options.description ?? "",
+			};
+		default:
+			return {
+				...base,
+				type: "convention",
+				content: options.description ?? "",
+			} as MulchExpertiseRecord;
+	}
+}
+
+/**
+ * Format search/query results as a plain string for callers that expect string output.
+ * Preserves behavior for parseConflictPatterns regex in resolver.ts.
+ */
+function formatSearchResults(
+	results: Array<{ domain: string; records: MulchExpertiseRecord[] }>,
+): string {
+	const lines: string[] = [];
+	for (const result of results) {
+		for (const record of result.records) {
+			lines.push(formatRecordText(record));
+		}
+	}
+	return lines.join("\n");
+}
+
+function formatRecordText(record: MulchExpertiseRecord): string {
+	switch (record.type) {
+		case "convention":
+			return record.content;
+		case "pattern":
+			return record.description;
+		case "failure":
+			return record.description;
+		case "decision":
+			return `${record.title}: ${record.rationale}`;
+		case "reference":
+			return record.description;
+		case "guide":
+			return record.description;
+	}
+}
+
 /**
  * Create a MulchClient bound to the given working directory.
  *
@@ -158,61 +426,60 @@ export function createMulchClient(cwd: string): MulchClient {
 		},
 
 		async record(domain, options) {
-			const args = ["record", domain, "--type", options.type];
-			if (options.name) {
-				args.push("--name", options.name);
-			}
-			if (options.description) {
-				args.push("--description", options.description);
-			}
-			if (options.title) {
-				args.push("--title", options.title);
-			}
-			if (options.rationale) {
-				args.push("--rationale", options.rationale);
-			}
-			if (options.tags && options.tags.length > 0) {
-				args.push("--tags", options.tags.join(","));
-			}
-			if (options.classification) {
-				args.push("--classification", options.classification);
-			}
+			// stdin mode: no programmatic API equivalent, fall back to CLI
 			if (options.stdin) {
+				const args = ["record", domain, "--type", options.type];
+				if (options.description) args.push("--description", options.description);
 				args.push("--stdin");
+				await runMulch(args, `record ${domain}`);
+				return;
 			}
-			if (options.evidenceBead) {
-				args.push("--evidence-bead", options.evidenceBead);
-			}
-			if (options.outcomeStatus) {
-				args.push("--outcome-status", options.outcomeStatus);
-			}
-			if (options.outcomeDuration !== undefined) {
-				args.push("--outcome-duration", String(options.outcomeDuration));
-			}
-			if (options.outcomeTestResults) {
-				args.push("--outcome-test-results", options.outcomeTestResults);
-			}
-			if (options.outcomeAgent) {
-				args.push("--outcome-agent", options.outcomeAgent);
+
+			const expertiseRecord = buildExpertiseRecord(options);
+			const api = await loadMulchApi();
+			try {
+				await api.recordExpertise(domain, expertiseRecord, { cwd });
+			} catch (error) {
+				if (error instanceof Error && error.message.includes("not found in config")) {
+					// Auto-create domain (matching mulch CLI 0.6.1+ behavior)
+					await runMulch(["add", domain], `add ${domain}`);
+					await api.recordExpertise(domain, expertiseRecord, { cwd });
+				} else {
+					throw new AgentError(
+						`mulch record ${domain} failed: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
 			}
-			await runMulch(args, `record ${domain}`);
 		},
 
 		async query(domain) {
-			const args = ["query"];
-			if (domain) {
-				args.push(domain);
+			if (!domain) {
+				throw new AgentError("mulch query failed (exit 1): domain argument required");
+			}
+			try {
+				const api = await loadMulchApi();
+				const records = await api.queryDomain(domain, { cwd });
+				return formatSearchResults([{ domain, records }]);
+			} catch (error) {
+				throw new AgentError(
+					`mulch query failed: ${error instanceof Error ? error.message : String(error)}`,
+				);
 			}
-			const { stdout } = await runMulch(args, "query");
-			return stdout;
 		},
 
 		async search(query, options) {
-			const args = ["search", query];
-			if (options?.file) args.push("--file", options.file);
-			if (options?.sortByScore) args.push("--sort-by-score");
-			const { stdout } = await runMulch(args, "search");
-			return stdout;
+			try {
+				const api = await loadMulchApi();
+				const results = await api.searchExpertise(query, {
+					file: options?.file,
+					cwd,
+				});
+				return formatSearchResults(results);
+			} catch (error) {
+				throw new AgentError(
+					`mulch search failed: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
 		},
 
 		async diff(options) {