mulch-cli 0.5.0 → 0.6.0

package/src/utils/git.ts

@@ -0,0 +1,89 @@
+import { execFileSync } from "node:child_process";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+
+export function isGitRepo(cwd: string): boolean {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd,
+      stdio: "pipe",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getChangedFiles(cwd: string, since: string): string[] {
+  const files = new Set<string>();
+
+  // Committed changes (since ref)
+  try {
+    const committed = execFileSync("git", ["diff", "--name-only", since], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (committed) {
+      for (const f of committed.split("\n")) {
+        if (f) files.add(f);
+      }
+    }
+  } catch {
+    // ref might not exist (e.g., first commit) — fall through
+  }
+
+  // Staged but uncommitted changes
+  try {
+    const staged = execFileSync("git", ["diff", "--name-only", "--cached"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (staged) {
+      for (const f of staged.split("\n")) {
+        if (f) files.add(f);
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  // Unstaged working tree changes
+  try {
+    const unstaged = execFileSync("git", ["diff", "--name-only"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (unstaged) {
+      for (const f of unstaged.split("\n")) {
+        if (f) files.add(f);
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  return [...files].sort();
+}
+
+export function fileMatchesAny(file: string, changedFiles: string[]): boolean {
+  return changedFiles.some(
+    (changed) =>
+      changed === file || changed.endsWith(file) || file.endsWith(changed),
+  );
+}
+
+export function filterByContext(
+  records: ExpertiseRecord[],
+  changedFiles: string[],
+): ExpertiseRecord[] {
+  return records.filter((r) => {
+    // Records without a files field are always relevant (conventions, failures, decisions, guides)
+    if (!("files" in r) || !r.files || r.files.length === 0) {
+      return true;
+    }
+    // Records with files: keep if any file matches a changed file
+    return r.files.some((f) => fileMatchesAny(f, changedFiles));
+  });
+}

package/src/utils/index.ts

@@ -0,0 +1,54 @@
+export {
+  getMulchDir,
+  getConfigPath,
+  getExpertiseDir,
+  getExpertisePath,
+  readConfig,
+  writeConfig,
+  initMulchDir,
+} from "./config.ts";
+
+export {
+  readExpertiseFile,
+  appendRecord,
+  createExpertiseFile,
+  getFileModTime,
+  countRecords,
+  filterByType,
+  generateRecordId,
+} from "./expertise.ts";
+
+export {
+  formatDomainExpertise,
+  formatPrimeOutput,
+  formatStatusOutput,
+  formatTimeAgo,
+  getRecordSummary,
+} from "./format.ts";
+
+export {
+  outputJson,
+  outputJsonError,
+} from "./json-output.ts";
+
+export {
+  isGitRepo,
+  getChangedFiles,
+  fileMatchesAny,
+  filterByContext,
+} from "./git.ts";
+
+export {
+  MARKER_START,
+  MARKER_END,
+  hasMarkerSection,
+  replaceMarkerSection,
+  removeMarkerSection,
+  wrapInMarkers,
+} from "./markers.ts";
+
+export {
+  getCurrentVersion,
+  getLatestVersion,
+  compareSemver,
+} from "./version.ts";

package/src/utils/json-output.ts

@@ -0,0 +1,13 @@
+export interface JsonResult {
+  success: boolean;
+  command: string;
+  [key: string]: unknown;
+}
+
+export function outputJson(result: JsonResult): void {
+  console.log(JSON.stringify(result, null, 2));
+}
+
+export function outputJsonError(command: string, error: string): void {
+  console.error(JSON.stringify({ success: false, command, error }, null, 2));
+}

package/src/utils/lock.ts

@@ -0,0 +1,82 @@
+import { constants } from "node:fs";
+import { lstat, open, unlink } from "node:fs/promises";
+
+const LOCK_STALE_MS = 30_000; // 30 seconds
+const LOCK_RETRY_INTERVAL_MS = 50;
+const LOCK_TIMEOUT_MS = 5_000; // 5 seconds
+
+/**
+ * Advisory file-level lock using O_CREAT | O_EXCL.
+ * Wraps an async function with lock acquisition and guaranteed cleanup.
+ */
+export async function withFileLock<T>(
+  filePath: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const lockPath = `${filePath}.lock`;
+  await acquireLock(lockPath);
+  try {
+    return await fn();
+  } finally {
+    await releaseLock(lockPath);
+  }
+}
+
+async function acquireLock(lockPath: string): Promise<void> {
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+
+  while (true) {
+    try {
+      const fd = await open(
+        lockPath,
+        constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY,
+      );
+      await fd.close();
+      return;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw err;
+      }
+
+      // Lock file exists — check if it's stale
+      if (await isStaleLock(lockPath)) {
+        try {
+          await unlink(lockPath);
+        } catch {
+          // Another process may have already removed it
+        }
+        continue;
+      }
+
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Timed out waiting for lock on ${lockPath}. If no other mulch process is running, delete the lock file manually.`,
+        );
+      }
+
+      await sleep(LOCK_RETRY_INTERVAL_MS);
+    }
+  }
+}
+
+async function isStaleLock(lockPath: string): Promise<boolean> {
+  try {
+    const stats = await lstat(lockPath);
+    return Date.now() - stats.mtimeMs > LOCK_STALE_MS;
+  } catch {
+    // Lock file disappeared between check — not stale, just gone
+    return false;
+  }
+}
+
+async function releaseLock(lockPath: string): Promise<void> {
+  try {
+    await unlink(lockPath);
+  } catch {
+    // Lock file already gone — acceptable
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/utils/markers.ts

@@ -0,0 +1,51 @@
+const MARKER_START = "<!-- mulch:start -->";
+const MARKER_END = "<!-- mulch:end -->";
+
+export { MARKER_START, MARKER_END };
+
+/**
+ * Check whether content contains the mulch marker section.
+ */
+export function hasMarkerSection(content: string): boolean {
+  return content.includes(MARKER_START);
+}
+
+/**
+ * Replace the marker-bounded section with new content.
+ * Returns null if no markers found.
+ */
+export function replaceMarkerSection(
+  content: string,
+  newSection: string,
+): string | null {
+  const startIdx = content.indexOf(MARKER_START);
+  const endIdx = content.indexOf(MARKER_END);
+  if (startIdx === -1 || endIdx === -1) return null;
+
+  const before = content.substring(0, startIdx);
+  const after = content.substring(endIdx + MARKER_END.length);
+
+  return before + newSection + after;
+}
+
+/**
+ * Remove the marker-bounded section entirely.
+ * Cleans up extra newlines left behind.
+ */
+export function removeMarkerSection(content: string): string {
+  const startIdx = content.indexOf(MARKER_START);
+  const endIdx = content.indexOf(MARKER_END);
+  if (startIdx === -1 || endIdx === -1) return content;
+
+  const before = content.substring(0, startIdx);
+  const after = content.substring(endIdx + MARKER_END.length);
+
+  return `${(before + after).replace(/\n{3,}/g, "\n\n").trim()}\n`;
+}
+
+/**
+ * Wrap a snippet in mulch markers.
+ */
+export function wrapInMarkers(snippet: string): string {
+  return `${MARKER_START}\n${snippet}${MARKER_END}`;
+}

package/{dist/utils/scoring.d.ts → src/utils/scoring.ts}

@@ -1,29 +1,51 @@
-import type { ExpertiseRecord, Outcome } from "../schemas/record.js";
+import type { ExpertiseRecord, Outcome } from "../schemas/record.ts";
+
 export type { Outcome };
+
 /**
  * An ExpertiseRecord with outcome history for confirmation-frequency scoring.
  * Since ExpertiseRecord now includes outcomes?: Outcome[], this is an alias.
  */
 export type ScoredRecord = ExpertiseRecord;
+
 /**
  * Returns the number of successful outcomes for a record.
  * Successful outcomes indicate confirmed, working applications of the record.
  */
-export declare function getSuccessCount(record: ScoredRecord): number;
+export function getSuccessCount(record: ScoredRecord): number {
+  if (!record.outcomes || record.outcomes.length === 0) return 0;
+  return record.outcomes.filter((o) => o.status === "success").length;
+}
+
 /**
  * Returns the number of failed outcomes for a record.
  */
-export declare function getFailureCount(record: ScoredRecord): number;
+export function getFailureCount(record: ScoredRecord): number {
+  if (!record.outcomes || record.outcomes.length === 0) return 0;
+  return record.outcomes.filter((o) => o.status === "failure").length;
+}
+
 /**
  * Returns the total number of recorded outcomes (applications) for a record.
  */
-export declare function getTotalApplications(record: ScoredRecord): number;
+export function getTotalApplications(record: ScoredRecord): number {
+  return record.outcomes?.length ?? 0;
+}
+
 /**
  * Returns the success rate (0-1) for a record.
  * Partial outcomes are counted as 0.5 (half success).
  * Returns 0 for records with no outcomes.
  */
-export declare function getSuccessRate(record: ScoredRecord): number;
+export function getSuccessRate(record: ScoredRecord): number {
+  const total = getTotalApplications(record);
+  if (total === 0) return 0;
+  const partialCount =
+    record.outcomes?.filter((o) => o.status === "partial").length ?? 0;
+  const successCount = getSuccessCount(record);
+  return (successCount + partialCount * 0.5) / total;
+}
+
 /**
  * Computes the confirmation-frequency score for a record.
  *
@@ -34,7 +56,15 @@ export declare function getSuccessRate(record: ScoredRecord): number;
  * Records with no outcomes return 0.
  * Records with only failures return 0.
  */
-export declare function computeConfirmationScore(record: ScoredRecord): number;
+export function computeConfirmationScore(record: ScoredRecord): number {
+  if (!record.outcomes || record.outcomes.length === 0) return 0;
+  const successCount = getSuccessCount(record);
+  const partialCount = record.outcomes.filter(
+    (o) => o.status === "partial",
+  ).length;
+  return successCount + partialCount * 0.5;
+}
+
 /**
  * Applies a confirmation-frequency boost to a base score (e.g., a BM25 relevance score).
  *
@@ -47,11 +77,25 @@ export declare function computeConfirmationScore(record: ScoredRecord): number;
  * @param boostFactor - Multiplier controlling boost magnitude (default: 0.1)
  * @returns The boosted score
  */
-export declare function applyConfirmationBoost(baseScore: number, record: ScoredRecord, boostFactor?: number): number;
+export function applyConfirmationBoost(
+  baseScore: number,
+  record: ScoredRecord,
+  boostFactor = 0.1,
+): number {
+  const confirmationScore = computeConfirmationScore(record);
+  if (confirmationScore === 0) return baseScore;
+  return baseScore * (1 + boostFactor * confirmationScore);
+}
+
 /**
  * Sorts records by confirmation-frequency score, highest first.
  * Records with equal scores maintain their original relative order (stable sort).
  * Records with no outcomes (score = 0) sort to the end.
  */
-export declare function sortByConfirmationScore<T extends ScoredRecord>(records: T[]): T[];
-//# sourceMappingURL=scoring.d.ts.map
+export function sortByConfirmationScore<T extends ScoredRecord>(
+  records: T[],
+): T[] {
+  return [...records].sort(
+    (a, b) => computeConfirmationScore(b) - computeConfirmationScore(a),
+  );
+}

package/src/utils/version.ts

@@ -0,0 +1,46 @@
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Read the current CLI version from package.json.
+ */
+export function getCurrentVersion(): string {
+  const pkgPath = join(import.meta.dir, "..", "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version: string };
+  return pkg.version;
+}
+
+/**
+ * Fetch the latest published version of mulch-cli from npm.
+ * Returns null if the registry is unreachable.
+ */
+export function getLatestVersion(): string | null {
+  try {
+    const result = execSync("npm view mulch-cli version", {
+      encoding: "utf-8",
+      timeout: 10000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return result.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compare two semver strings (major.minor.patch).
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ */
+export function compareSemver(a: string, b: string): -1 | 0 | 1 {
+  const partsA = a.split(".").map(Number);
+  const partsB = b.split(".").map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const segA = partsA[i] ?? 0;
+    const segB = partsB[i] ?? 0;
+    if (segA < segB) return -1;
+    if (segA > segB) return 1;
+  }
+  return 0;
+}

package/dist/api.d.ts

@@ -1,65 +0,0 @@
-import type { ExpertiseRecord, Classification, Outcome } from "./schemas/record.js";
-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[];
-    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 declare function recordExpertise(domain: string, record: ExpertiseRecord, options?: RecordOptions): Promise<RecordResult>;
-/**
- * Search expertise records across domains using BM25 ranking.
- * Returns domains with at least one matching record.
- */
-export declare function searchExpertise(query: string, options?: SearchOptions): Promise<SearchResult[]>;
-/**
- * Query all records in a domain with optional filtering.
- */
-export declare function queryDomain(domain: string, options?: QueryOptions): Promise<ExpertiseRecord[]>;
-/**
- * Edit an existing record by ID in the given domain.
- * Only provided fields in updates are modified; all other fields are preserved.
- */
-export declare function editRecord(domain: string, id: string, updates: RecordUpdates, options?: EditOptions): Promise<ExpertiseRecord>;
-//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAepF,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAErB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAmCvB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,EAAE,CAAC,CA6CzB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC,CAwB5B;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAoG1B"}