mulch-cli 0.4.3 → 0.6.0

package/src/utils/config.ts

@@ -0,0 +1,117 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import type { MulchConfig } from "../schemas/config.ts";
+import { DEFAULT_CONFIG } from "../schemas/config.ts";
+
+const MULCH_DIR = ".mulch";
+const CONFIG_FILE = "mulch.config.yaml";
+const EXPERTISE_DIR = "expertise";
+
+export const GITATTRIBUTES_LINE = ".mulch/expertise/*.jsonl merge=union";
+
+export const MULCH_README = `# .mulch/
+
+This directory is managed by [mulch](https://github.com/jayminwest/mulch) — a structured expertise layer for coding agents.
+
+## Key Commands
+
+- \`mulch init\`      — Initialize a .mulch directory
+- \`mulch add\`       — Add a new domain
+- \`mulch record\`    — Record an expertise record
+- \`mulch edit\`      — Edit an existing record
+- \`mulch query\`     — Query expertise records
+- \`mulch prime [domain]\` — Output a priming prompt (optionally scoped to one domain)
+- \`mulch search\`   — Search records across domains
+- \`mulch status\`    — Show domain statistics
+- \`mulch validate\`  — Validate all records against the schema
+- \`mulch prune\`     — Remove expired records
+
+## Structure
+
+- \`mulch.config.yaml\` — Configuration file
+- \`expertise/\`        — JSONL files, one per domain
+`;
+
+export function getMulchDir(cwd: string = process.cwd()): string {
+  return join(cwd, MULCH_DIR);
+}
+
+export function getConfigPath(cwd: string = process.cwd()): string {
+  return join(getMulchDir(cwd), CONFIG_FILE);
+}
+
+export function getExpertiseDir(cwd: string = process.cwd()): string {
+  return join(getMulchDir(cwd), EXPERTISE_DIR);
+}
+
+export function validateDomainName(domain: string): void {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(domain)) {
+    throw new Error(
+      `Invalid domain name: "${domain}". Only alphanumeric characters, hyphens, and underscores are allowed.`,
+    );
+  }
+}
+
+export function getExpertisePath(
+  domain: string,
+  cwd: string = process.cwd(),
+): string {
+  validateDomainName(domain);
+  return join(getExpertiseDir(cwd), `${domain}.jsonl`);
+}
+
+export async function readConfig(
+  cwd: string = process.cwd(),
+): Promise<MulchConfig> {
+  const configPath = getConfigPath(cwd);
+  const content = await readFile(configPath, "utf-8");
+  return yaml.load(content) as MulchConfig;
+}
+
+export async function writeConfig(
+  config: MulchConfig,
+  cwd: string = process.cwd(),
+): Promise<void> {
+  const configPath = getConfigPath(cwd);
+  const content = yaml.dump(config, { lineWidth: -1 });
+  await writeFile(configPath, content, "utf-8");
+}
+
+export async function initMulchDir(cwd: string = process.cwd()): Promise<void> {
+  const mulchDir = getMulchDir(cwd);
+  const expertiseDir = getExpertiseDir(cwd);
+  await mkdir(mulchDir, { recursive: true });
+  await mkdir(expertiseDir, { recursive: true });
+
+  // Only write default config if none exists — preserve user customizations
+  const configPath = getConfigPath(cwd);
+  if (!existsSync(configPath)) {
+    await writeConfig({ ...DEFAULT_CONFIG }, cwd);
+  }
+
+  // Create or append .gitattributes with merge=union for JSONL files
+  const gitattributesPath = join(cwd, ".gitattributes");
+  let existing = "";
+  try {
+    existing = await readFile(gitattributesPath, "utf-8");
+  } catch {
+    // File doesn't exist yet — will create it
+  }
+  if (!existing.includes(GITATTRIBUTES_LINE)) {
+    const separator =
+      existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await writeFile(
+      gitattributesPath,
+      `${existing + separator + GITATTRIBUTES_LINE}\n`,
+      "utf-8",
+    );
+  }
+
+  // Create .mulch/README.md if missing
+  const readmePath = join(mulchDir, "README.md");
+  if (!existsSync(readmePath)) {
+    await writeFile(readmePath, MULCH_README, "utf-8");
+  }
+}

package/src/utils/expertise.ts

@@ -0,0 +1,379 @@
+import { createHash, randomBytes } from "node:crypto";
+import {
+  appendFile,
+  readFile,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import type {
+  Classification,
+  ExpertiseRecord,
+  RecordType,
+} from "../schemas/record.ts";
+import { DEFAULT_BM25_PARAMS, searchBM25 } from "./bm25.ts";
+
+export async function readExpertiseFile(
+  filePath: string,
+): Promise<ExpertiseRecord[]> {
+  let content: string;
+  try {
+    content = await readFile(filePath, "utf-8");
+  } catch {
+    return [];
+  }
+
+  const records: ExpertiseRecord[] = [];
+  const lines = content.split("\n").filter((line) => line.trim().length > 0);
+  for (const line of lines) {
+    const raw = JSON.parse(line) as Record<string, unknown>;
+    // Normalize legacy outcome (singular) to outcomes (array) for backward compat
+    if (
+      "outcome" in raw &&
+      raw.outcome !== null &&
+      raw.outcome !== undefined &&
+      !("outcomes" in raw)
+    ) {
+      const legacy = raw.outcome as Record<string, unknown>;
+      raw.outcomes = [
+        {
+          status: legacy.status,
+          ...(legacy.duration !== undefined
+            ? { duration: legacy.duration }
+            : {}),
+          ...(legacy.test_results !== undefined
+            ? { test_results: legacy.test_results }
+            : {}),
+          ...(legacy.agent !== undefined ? { agent: legacy.agent } : {}),
+        },
+      ];
+      raw.outcome = undefined;
+    }
+    records.push(raw as unknown as ExpertiseRecord);
+  }
+  return records;
+}
+
+export function generateRecordId(record: ExpertiseRecord): string {
+  let key: string;
+  switch (record.type) {
+    case "convention":
+      key = `convention:${record.content}`;
+      break;
+    case "pattern":
+      key = `pattern:${record.name}`;
+      break;
+    case "failure":
+      key = `failure:${record.description}`;
+      break;
+    case "decision":
+      key = `decision:${record.title}`;
+      break;
+    case "reference":
+      key = `reference:${record.name}`;
+      break;
+    case "guide":
+      key = `guide:${record.name}`;
+      break;
+  }
+  return `mx-${createHash("sha256").update(key).digest("hex").slice(0, 6)}`;
+}
+
+export async function appendRecord(
+  filePath: string,
+  record: ExpertiseRecord,
+): Promise<void> {
+  if (!record.id) {
+    record.id = generateRecordId(record);
+  }
+  const line = `${JSON.stringify(record)}\n`;
+  await appendFile(filePath, line, "utf-8");
+}
+
+export async function createExpertiseFile(filePath: string): Promise<void> {
+  await writeFile(filePath, "", "utf-8");
+}
+
+export async function getFileModTime(filePath: string): Promise<Date | null> {
+  try {
+    const stats = await stat(filePath);
+    return stats.mtime;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeExpertiseFile(
+  filePath: string,
+  records: ExpertiseRecord[],
+): Promise<void> {
+  for (const r of records) {
+    if (!r.id) {
+      r.id = generateRecordId(r);
+    }
+  }
+  const content =
+    records.map((r) => JSON.stringify(r)).join("\n") +
+    (records.length > 0 ? "\n" : "");
+  const tmpPath = `${filePath}.tmp.${randomBytes(8).toString("hex")}`;
+  await writeFile(tmpPath, content, "utf-8");
+  try {
+    await rename(tmpPath, filePath);
+  } catch (err) {
+    try {
+      await unlink(tmpPath);
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw err;
+  }
+}
+
+export function countRecords(records: ExpertiseRecord[]): number {
+  return records.length;
+}
+
+export function filterByType(
+  records: ExpertiseRecord[],
+  type: string,
+): ExpertiseRecord[] {
+  return records.filter((r) => r.type === type);
+}
+
+export function filterByClassification(
+  records: ExpertiseRecord[],
+  classification: string,
+): ExpertiseRecord[] {
+  return records.filter((r) => r.classification === classification);
+}
+
+export function filterByFile(
+  records: ExpertiseRecord[],
+  file: string,
+): ExpertiseRecord[] {
+  const fileLower = file.toLowerCase();
+  return records.filter((r) => {
+    if ("files" in r && r.files) {
+      return r.files.some((f) => f.toLowerCase().includes(fileLower));
+    }
+    return false;
+  });
+}
+
+export function findDuplicate(
+  existing: ExpertiseRecord[],
+  newRecord: ExpertiseRecord,
+): { index: number; record: ExpertiseRecord } | null {
+  for (let i = 0; i < existing.length; i++) {
+    const record = existing[i];
+    if (record.type !== newRecord.type) continue;
+
+    switch (record.type) {
+      case "pattern":
+        if (newRecord.type === "pattern" && record.name === newRecord.name) {
+          return { index: i, record };
+        }
+        break;
+      case "decision":
+        if (newRecord.type === "decision" && record.title === newRecord.title) {
+          return { index: i, record };
+        }
+        break;
+      case "convention":
+        if (
+          newRecord.type === "convention" &&
+          record.content === newRecord.content
+        ) {
+          return { index: i, record };
+        }
+        break;
+      case "failure":
+        if (
+          newRecord.type === "failure" &&
+          record.description === newRecord.description
+        ) {
+          return { index: i, record };
+        }
+        break;
+      case "reference":
+        if (newRecord.type === "reference" && record.name === newRecord.name) {
+          return { index: i, record };
+        }
+        break;
+      case "guide":
+        if (newRecord.type === "guide" && record.name === newRecord.name) {
+          return { index: i, record };
+        }
+        break;
+    }
+  }
+  return null;
+}
+
+export type ResolveResult =
+  | { ok: true; index: number; record: ExpertiseRecord }
+  | { ok: false; error: string };
+
+/**
+ * Resolve an identifier to a record within a domain.
+ * Accepts: full ID (mx-abc123), bare hash (abc123), or prefix (abc / mx-abc).
+ * Returns the unique matching record or an error if not found / ambiguous.
+ */
+export function resolveRecordId(
+  records: ExpertiseRecord[],
+  identifier: string,
+): ResolveResult {
+  // Normalize: strip mx- prefix if present to get the hash part
+  const hash = identifier.startsWith("mx-") ? identifier.slice(3) : identifier;
+
+  // Try exact match first
+  const exactIndex = records.findIndex((r) => r.id === `mx-${hash}`);
+  if (exactIndex !== -1) {
+    return { ok: true, index: exactIndex, record: records[exactIndex] };
+  }
+
+  // Try prefix match
+  const matches: Array<{ index: number; record: ExpertiseRecord }> = [];
+  for (let i = 0; i < records.length; i++) {
+    const rid = records[i].id;
+    if (rid?.startsWith(`mx-${hash}`)) {
+      matches.push({ index: i, record: records[i] });
+    }
+  }
+
+  if (matches.length === 1) {
+    return { ok: true, index: matches[0].index, record: matches[0].record };
+  }
+
+  if (matches.length > 1) {
+    const ids = matches.map((m) => m.record.id).join(", ");
+    return {
+      ok: false,
+      error: `Ambiguous identifier "${identifier}" matches ${matches.length} records: ${ids}. Use more characters to disambiguate.`,
+    };
+  }
+
+  return {
+    ok: false,
+    error: `Record "${identifier}" not found. Run \`mulch query\` to see record IDs.`,
+  };
+}
+
+/**
+ * Search records using BM25 ranking algorithm.
+ * Returns records sorted by relevance (highest score first).
+ */
+export function searchRecords(
+  records: ExpertiseRecord[],
+  query: string,
+): ExpertiseRecord[] {
+  const results = searchBM25(records, query, DEFAULT_BM25_PARAMS);
+  return results.map((r) => r.record);
+}
+
+export interface DomainHealth {
+  governance_utilization: number;
+  stale_count: number;
+  type_distribution: Record<RecordType, number>;
+  classification_distribution: Record<Classification, number>;
+  oldest_timestamp: string | null;
+  newest_timestamp: string | null;
+}
+
+/**
+ * Check if a record is stale based on classification and shelf life.
+ */
+export function isRecordStale(
+  record: ExpertiseRecord,
+  now: Date,
+  shelfLife: { tactical: number; observational: number },
+): boolean {
+  const classification: Classification = record.classification;
+
+  if (classification === "foundational") {
+    return false;
+  }
+
+  const recordedAt = new Date(record.recorded_at);
+  const ageInDays = Math.floor(
+    (now.getTime() - recordedAt.getTime()) / (1000 * 60 * 60 * 24),
+  );
+
+  if (classification === "tactical") {
+    return ageInDays > shelfLife.tactical;
+  }
+
+  if (classification === "observational") {
+    return ageInDays > shelfLife.observational;
+  }
+
+  return false;
+}
+
+/**
+ * Calculate comprehensive health metrics for a domain.
+ */
+export function calculateDomainHealth(
+  records: ExpertiseRecord[],
+  maxEntries: number,
+  shelfLife: { tactical: number; observational: number },
+): DomainHealth {
+  const now = new Date();
+
+  // Initialize distributions
+  const typeDistribution: Record<RecordType, number> = {
+    convention: 0,
+    pattern: 0,
+    failure: 0,
+    decision: 0,
+    reference: 0,
+    guide: 0,
+  };
+
+  const classificationDistribution: Record<Classification, number> = {
+    foundational: 0,
+    tactical: 0,
+    observational: 0,
+  };
+
+  let staleCount = 0;
+  let oldestTimestamp: string | null = null;
+  let newestTimestamp: string | null = null;
+
+  // Calculate metrics
+  for (const record of records) {
+    // Type distribution
+    typeDistribution[record.type]++;
+
+    // Classification distribution
+    classificationDistribution[record.classification]++;
+
+    // Stale count
+    if (isRecordStale(record, now, shelfLife)) {
+      staleCount++;
+    }
+
+    // Oldest/newest timestamps
+    const recordedAt = record.recorded_at;
+    if (!oldestTimestamp || recordedAt < oldestTimestamp) {
+      oldestTimestamp = recordedAt;
+    }
+    if (!newestTimestamp || recordedAt > newestTimestamp) {
+      newestTimestamp = recordedAt;
+    }
+  }
+
+  // Governance utilization (as percentage, 0-100)
+  const governanceUtilization =
+    maxEntries > 0 ? Math.round((records.length / maxEntries) * 100) : 0;
+
+  return {
+    governance_utilization: governanceUtilization,
+    stale_count: staleCount,
+    type_distribution: typeDistribution,
+    classification_distribution: classificationDistribution,
+    oldest_timestamp: oldestTimestamp,
+    newest_timestamp: newestTimestamp,
+  };
+}