mulch-cli 0.4.3 → 0.6.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/mulch-cli)](https://www.npmjs.com/package/mulch-cli)
 [![CI](https://img.shields.io/github/actions/workflow/status/jayminwest/mulch/ci.yml?branch=main)](https://github.com/jayminwest/mulch/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![node](https://img.shields.io/node/v/mulch-cli)](https://nodejs.org)
+[![bun](https://img.shields.io/badge/runtime-bun-f472b6)](https://bun.sh)
 
 Structured expertise files that accumulate over time, live in git, work with any agent, and run locally with zero dependencies.
 
@@ -23,6 +23,17 @@ Or use directly with npx — no install required:
 npx mulch-cli <command>
 ```
 
+### Development
+
+Mulch uses [Bun](https://bun.sh) as its development runtime and test runner:
+
+```bash
+bun install            # Install dependencies
+bun test               # Run all tests
+bun run lint           # Lint with Biome
+bun run typecheck      # Type-check with tsc
+```
+
 ## Quick Start
 
 ```bash
@@ -71,7 +82,7 @@ Everything is git-tracked. Clone a repo and your agents immediately have the pro
 | `mulch record <domain> --type <type>` | Record an expertise record (`--tags`, `--force`, `--relates-to`, `--supersedes`, `--batch`, `--stdin`, `--dry-run`, `--evidence-bead`) |
 | `mulch edit <domain> <id>` | Edit an existing record by ID or 1-based index |
 | `mulch delete <domain> <id>` | Delete a record by ID or 1-based index |
-| `mulch query [domain]` | Query expertise (use `--all` for all domains, `--classification`, `--file` filters) |
+| `mulch query [domain]` | Query expertise (use `--all` for all domains, `--classification`, `--file`, `--outcome-status`, `--sort-by-score` filters) |
 | `mulch prime [domains...]` | Output AI-optimized expertise context (`--budget`, `--no-limit`, `--context`, `--files`, `--exclude-domain`, `--format`, `--export`) |
 | `mulch search [query]` | Search records across domains with BM25 ranking (`--domain`, `--type`, `--tag`, `--classification`, `--file`, `--sort-by-score` filters) |
 | `mulch compact [domain]` | Analyze compaction candidates or apply a compaction (`--analyze`, `--auto`, `--apply`, `--dry-run`, `--min-group`, `--max-records`) |
@@ -197,9 +208,18 @@ The `--apply`, default (non-dry-run), and `--fix` variants acquire locks and are
 
 ## Programmatic API
 
-Mulch exports core utilities for use as a library:
+Mulch exports both low-level utilities and a high-level programmatic API:
 
 ```typescript
+// High-level API — recommended for most use cases
+import {
+  recordExpertise,   // Record a new expertise entry (with dedup and locking)
+  searchExpertise,   // Search records across domains
+  queryDomain,       // Query all records for a domain
+  editRecord,        // Edit an existing record by ID
+} from "mulch-cli";
+
+// Low-level utilities
 import {
   readConfig,
   getExpertisePath,
@@ -213,7 +233,7 @@ import {
 } from "mulch-cli";
 ```
 
-Types (`ExpertiseRecord`, `MulchConfig`, `RecordType`, `Classification`, `ScoredRecord`, `Outcome`, etc.) are also exported.
+Types (`ExpertiseRecord`, `MulchConfig`, `RecordType`, `Classification`, `ScoredRecord`, `Outcome`, `RecordOptions`, `RecordResult`, `SearchOptions`, `SearchResult`, `QueryOptions`, `EditOptions`, `RecordUpdates`, etc.) are also exported.
 
 ## Contributing
 

package/package.json

@@ -1,25 +1,20 @@
 {
   "name": "mulch-cli",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "Let your agents grow 🌱 — structured expertise files that accumulate over time, live in git, work with any agent",
   "type": "module",
   "bin": {
-    "mulch": "./dist/cli.js"
+    "mulch": "src/cli.ts"
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "main": "src/index.ts",
+  "files": ["src"],
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "tsc --noEmit"
+    "test": "bun test",
+    "lint": "bunx biome check .",
+    "typecheck": "tsc --noEmit"
   },
   "engines": {
-    "node": ">=18"
+    "bun": ">=1.0.0"
   },
   "keywords": [
     "ai",
@@ -42,9 +37,9 @@
     "js-yaml": "^4.1.1"
   },
   "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/bun": "latest",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.2.2",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "typescript": "^5.9.3"
   }
 }

package/src/api.ts

@@ -0,0 +1,310 @@
+import type {
+  Classification,
+  ExpertiseRecord,
+  Outcome,
+} from "./schemas/record.ts";
+import { getExpertisePath, readConfig } from "./utils/config.ts";
+import {
+  appendRecord,
+  filterByClassification,
+  filterByFile,
+  filterByType,
+  findDuplicate,
+  readExpertiseFile,
+  resolveRecordId,
+  searchRecords,
+  writeExpertiseFile,
+} from "./utils/expertise.ts";
+import { withFileLock } from "./utils/lock.ts";
+
+export interface RecordOptions {
+  force?: boolean;
+  cwd?: string;
+}
+
+export interface RecordResult {
+  action: "created" | "updated" | "skipped";
+  record: ExpertiseRecord;
+}
+
+export interface SearchOptions {
+  domain?: string;
+  type?: string;
+  tag?: string;
+  classification?: string;
+  file?: string;
+  cwd?: string;
+}
+
+export interface SearchResult {
+  domain: string;
+  records: ExpertiseRecord[];
+}
+
+export interface QueryOptions {
+  type?: string;
+  classification?: string;
+  file?: string;
+  cwd?: string;
+}
+
+export interface EditOptions {
+  cwd?: string;
+}
+
+export interface RecordUpdates {
+  classification?: Classification;
+  tags?: string[];
+  relates_to?: string[];
+  supersedes?: string[];
+  outcomes?: Outcome[];
+  // type-specific fields
+  content?: string;
+  name?: string;
+  description?: string;
+  resolution?: string;
+  title?: string;
+  rationale?: string;
+  files?: string[];
+}
+
+/**
+ * Record an expertise record in the given domain.
+ * Named record types (pattern, decision, reference, guide) are upserted on
+ * duplicate key; convention and failure duplicates are skipped unless force=true.
+ */
+export async function recordExpertise(
+  domain: string,
+  record: ExpertiseRecord,
+  options: RecordOptions = {},
+): Promise<RecordResult> {
+  const { force = false, cwd } = options;
+
+  const config = await readConfig(cwd);
+  if (!config.domains.includes(domain)) {
+    throw new Error(
+      `Domain "${domain}" not found in config. Available domains: ${config.domains.join(", ") || "(none)"}`,
+    );
+  }
+
+  const filePath = getExpertisePath(domain, cwd);
+
+  return withFileLock(filePath, async () => {
+    const existing = await readExpertiseFile(filePath);
+    const dup = findDuplicate(existing, record);
+
+    if (dup && !force) {
+      const isNamed =
+        record.type === "pattern" ||
+        record.type === "decision" ||
+        record.type === "reference" ||
+        record.type === "guide";
+
+      if (isNamed) {
+        existing[dup.index] = record;
+        await writeExpertiseFile(filePath, existing);
+        return { action: "updated" as const, record };
+      }
+      return { action: "skipped" as const, record: dup.record };
+    }
+    await appendRecord(filePath, record);
+    return { action: "created" as const, record };
+  });
+}
+
+/**
+ * Search expertise records across domains using BM25 ranking.
+ * Returns domains with at least one matching record.
+ */
+export async function searchExpertise(
+  query: string,
+  options: SearchOptions = {},
+): Promise<SearchResult[]> {
+  const { cwd } = options;
+  const config = await readConfig(cwd);
+
+  let domainsToSearch: string[];
+  if (options.domain) {
+    if (!config.domains.includes(options.domain)) {
+      throw new Error(
+        `Domain "${options.domain}" not found in config. Available domains: ${config.domains.join(", ")}`,
+      );
+    }
+    domainsToSearch = [options.domain];
+  } else {
+    domainsToSearch = config.domains;
+  }
+
+  const results: SearchResult[] = [];
+
+  for (const d of domainsToSearch) {
+    const filePath = getExpertisePath(d, cwd);
+    let records = await readExpertiseFile(filePath);
+
+    if (options.type) {
+      records = filterByType(records, options.type);
+    }
+    if (options.tag) {
+      const tagLower = options.tag.toLowerCase();
+      records = records.filter((r) =>
+        r.tags?.some((t) => t.toLowerCase() === tagLower),
+      );
+    }
+    if (options.classification) {
+      records = filterByClassification(records, options.classification);
+    }
+    if (options.file) {
+      records = filterByFile(records, options.file);
+    }
+
+    const matches = searchRecords(records, query);
+    if (matches.length > 0) {
+      results.push({ domain: d, records: matches });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Query all records in a domain with optional filtering.
+ */
+export async function queryDomain(
+  domain: string,
+  options: QueryOptions = {},
+): Promise<ExpertiseRecord[]> {
+  const { cwd } = options;
+  const config = await readConfig(cwd);
+
+  if (!config.domains.includes(domain)) {
+    throw new Error(
+      `Domain "${domain}" not found in config. Available domains: ${config.domains.join(", ") || "(none)"}`,
+    );
+  }
+
+  const filePath = getExpertisePath(domain, cwd);
+  let records = await readExpertiseFile(filePath);
+
+  if (options.type) {
+    records = filterByType(records, options.type);
+  }
+  if (options.classification) {
+    records = filterByClassification(records, options.classification);
+  }
+  if (options.file) {
+    records = filterByFile(records, options.file);
+  }
+
+  return records;
+}
+
+/**
+ * Edit an existing record by ID in the given domain.
+ * Only provided fields in updates are modified; all other fields are preserved.
+ */
+export async function editRecord(
+  domain: string,
+  id: string,
+  updates: RecordUpdates,
+  options: EditOptions = {},
+): Promise<ExpertiseRecord> {
+  const { cwd } = options;
+  const config = await readConfig(cwd);
+
+  if (!config.domains.includes(domain)) {
+    throw new Error(
+      `Domain "${domain}" not found in config. Available domains: ${config.domains.join(", ") || "(none)"}`,
+    );
+  }
+
+  const filePath = getExpertisePath(domain, cwd);
+
+  return withFileLock(filePath, async () => {
+    const records = await readExpertiseFile(filePath);
+    const resolved = resolveRecordId(records, id);
+
+    if (!resolved.ok) {
+      throw new Error(resolved.error);
+    }
+
+    const targetIndex = resolved.index;
+    const record = { ...records[targetIndex] };
+
+    // Apply common updates
+    if (updates.classification !== undefined) {
+      record.classification = updates.classification;
+    }
+    if (updates.tags !== undefined) {
+      record.tags = updates.tags;
+    }
+    if (updates.relates_to !== undefined) {
+      record.relates_to = updates.relates_to;
+    }
+    if (updates.supersedes !== undefined) {
+      record.supersedes = updates.supersedes;
+    }
+    if (updates.outcomes !== undefined) {
+      record.outcomes = updates.outcomes;
+    }
+
+    // Apply type-specific updates
+    switch (record.type) {
+      case "convention":
+        if (updates.content !== undefined) {
+          record.content = updates.content;
+        }
+        break;
+      case "pattern":
+        if (updates.name !== undefined) {
+          record.name = updates.name;
+        }
+        if (updates.description !== undefined) {
+          record.description = updates.description;
+        }
+        if (updates.files !== undefined) {
+          record.files = updates.files;
+        }
+        break;
+      case "failure":
+        if (updates.description !== undefined) {
+          record.description = updates.description;
+        }
+        if (updates.resolution !== undefined) {
+          record.resolution = updates.resolution;
+        }
+        break;
+      case "decision":
+        if (updates.title !== undefined) {
+          record.title = updates.title;
+        }
+        if (updates.rationale !== undefined) {
+          record.rationale = updates.rationale;
+        }
+        break;
+      case "reference":
+        if (updates.name !== undefined) {
+          record.name = updates.name;
+        }
+        if (updates.description !== undefined) {
+          record.description = updates.description;
+        }
+        if (updates.files !== undefined) {
+          record.files = updates.files;
+        }
+        break;
+      case "guide":
+        if (updates.name !== undefined) {
+          record.name = updates.name;
+        }
+        if (updates.description !== undefined) {
+          record.description = updates.description;
+        }
+        break;
+    }
+
+    records[targetIndex] = record;
+    await writeExpertiseFile(filePath, records);
+
+    return record;
+  });
+}

package/src/cli.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import { registerAddCommand } from "./commands/add.ts";
+import { registerCompactCommand } from "./commands/compact.ts";
+import { registerDeleteCommand } from "./commands/delete.ts";
+import { registerDiffCommand } from "./commands/diff.ts";
+import { registerDoctorCommand } from "./commands/doctor.ts";
+import { registerEditCommand } from "./commands/edit.ts";
+import { registerInitCommand } from "./commands/init.ts";
+import { registerLearnCommand } from "./commands/learn.ts";
+import { registerOnboardCommand } from "./commands/onboard.ts";
+import { registerPrimeCommand } from "./commands/prime.ts";
+import { registerPruneCommand } from "./commands/prune.ts";
+import { registerQueryCommand } from "./commands/query.ts";
+import { registerReadyCommand } from "./commands/ready.ts";
+import { registerRecordCommand } from "./commands/record.ts";
+import { registerSearchCommand } from "./commands/search.ts";
+import { registerSetupCommand } from "./commands/setup.ts";
+import { registerStatusCommand } from "./commands/status.ts";
+import { registerSyncCommand } from "./commands/sync.ts";
+import { registerUpdateCommand } from "./commands/update.ts";
+import { registerValidateCommand } from "./commands/validate.ts";
+
+const program = new Command();
+
+program
+  .name("mulch")
+  .description("Let your agents grow 🌱")
+  .version("0.6.0")
+  .option("--json", "output as structured JSON");
+
+registerInitCommand(program);
+registerAddCommand(program);
+registerRecordCommand(program);
+registerEditCommand(program);
+registerQueryCommand(program);
+registerSetupCommand(program);
+registerPrimeCommand(program);
+registerOnboardCommand(program);
+registerStatusCommand(program);
+registerValidateCommand(program);
+registerPruneCommand(program);
+registerSearchCommand(program);
+registerDoctorCommand(program);
+registerReadyCommand(program);
+registerSyncCommand(program);
+registerDeleteCommand(program);
+registerLearnCommand(program);
+registerCompactCommand(program);
+registerDiffCommand(program);
+registerUpdateCommand(program);
+
+program.parse();

package/src/commands/add.ts

@@ -0,0 +1,61 @@
+import { existsSync } from "node:fs";
+import chalk from "chalk";
+import type { Command } from "commander";
+import {
+  getExpertisePath,
+  getMulchDir,
+  readConfig,
+  writeConfig,
+} from "../utils/config.ts";
+import { createExpertiseFile } from "../utils/expertise.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+
+export function registerAddCommand(program: Command): void {
+  program
+    .command("add")
+    .argument("<domain>", "expertise domain to add")
+    .description("Add a new expertise domain")
+    .action(async (domain: string) => {
+      const jsonMode = program.opts().json === true;
+      const mulchDir = getMulchDir();
+
+      if (!existsSync(mulchDir)) {
+        if (jsonMode) {
+          outputJsonError(
+            "add",
+            "No .mulch/ directory found. Run `mulch init` first.",
+          );
+        } else {
+          console.error(
+            chalk.red("No .mulch/ directory found. Run `mulch init` first."),
+          );
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      const config = await readConfig();
+
+      if (config.domains.includes(domain)) {
+        if (jsonMode) {
+          outputJsonError("add", `Domain "${domain}" already exists.`);
+        } else {
+          console.error(chalk.red(`Domain "${domain}" already exists.`));
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      const expertisePath = getExpertisePath(domain);
+      await createExpertiseFile(expertisePath);
+
+      config.domains.push(domain);
+      await writeConfig(config);
+
+      if (jsonMode) {
+        outputJson({ success: true, command: "add", domain });
+      } else {
+        console.log(chalk.green(`Added domain "${domain}".`));
+      }
+    });
+}