mulch-cli 0.5.0 → 0.6.0

package/src/commands/prune.ts

@@ -0,0 +1,128 @@
+import chalk from "chalk";
+import type { Command } from "commander";
+import type { Classification, ExpertiseRecord } from "../schemas/record.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { readExpertiseFile, writeExpertiseFile } from "../utils/expertise.ts";
+import { outputJson } from "../utils/json-output.ts";
+import { withFileLock } from "../utils/lock.ts";
+
+interface PruneResult {
+  domain: string;
+  before: number;
+  pruned: number;
+  after: number;
+}
+
+export function isStale(
+  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;
+}
+
+export function registerPruneCommand(program: Command): void {
+  program
+    .command("prune")
+    .description("Remove outdated or low-value expertise records")
+    .option("--dry-run", "Show what would be pruned without removing", false)
+    .action(async (options: { dryRun: boolean }) => {
+      const jsonMode = program.opts().json === true;
+      const config = await readConfig();
+      const now = new Date();
+      const shelfLife = config.classification_defaults.shelf_life;
+      const results: PruneResult[] = [];
+      let totalPruned = 0;
+
+      for (const domain of config.domains) {
+        const filePath = getExpertisePath(domain);
+
+        const domainResult = await withFileLock(filePath, async () => {
+          const records = await readExpertiseFile(filePath);
+
+          if (records.length === 0) {
+            return null;
+          }
+
+          const kept: ExpertiseRecord[] = [];
+          let pruned = 0;
+
+          for (const record of records) {
+            if (isStale(record, now, shelfLife)) {
+              pruned++;
+            } else {
+              kept.push(record);
+            }
+          }
+
+          if (pruned > 0) {
+            if (!options.dryRun) {
+              await writeExpertiseFile(filePath, kept);
+            }
+            return {
+              domain,
+              before: records.length,
+              pruned,
+              after: kept.length,
+            };
+          }
+          return null;
+        });
+
+        if (domainResult) {
+          results.push(domainResult);
+          totalPruned += domainResult.pruned;
+        }
+      }
+
+      if (jsonMode) {
+        outputJson({
+          success: true,
+          command: "prune",
+          dryRun: options.dryRun,
+          totalPruned,
+          results,
+        });
+        return;
+      }
+
+      if (totalPruned === 0) {
+        console.log(
+          chalk.green("No stale records found. All records are current."),
+        );
+        return;
+      }
+
+      const label = options.dryRun ? "Would prune" : "Pruned";
+      const prefix = options.dryRun ? chalk.yellow("[DRY RUN] ") : "";
+
+      for (const result of results) {
+        console.log(
+          `${prefix}${chalk.cyan(result.domain)}: ${label} ${chalk.red(String(result.pruned))} of ${result.before} records (${result.after} remaining)`,
+        );
+      }
+
+      console.log(
+        `\n${prefix}${chalk.bold(`Total: ${label.toLowerCase()} ${totalPruned} stale ${totalPruned === 1 ? "record" : "records"}.`)}`,
+      );
+    });
+}

package/src/commands/query.ts

@@ -0,0 +1,177 @@
+import { type Command, Option } from "commander";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import {
+  filterByClassification,
+  filterByFile,
+  filterByType,
+  getFileModTime,
+  readExpertiseFile,
+} from "../utils/expertise.ts";
+import { formatDomainExpertise } from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import {
+  type ScoredRecord,
+  sortByConfirmationScore,
+} from "../utils/scoring.ts";
+
+export function registerQueryCommand(program: Command): void {
+  program
+    .command("query")
+    .argument("[domain]", "expertise domain to query")
+    .description("Query expertise records")
+    .option("--type <type>", "filter by record type")
+    .addOption(
+      new Option(
+        "--classification <classification>",
+        "filter by classification",
+      ).choices(["foundational", "tactical", "observational"]),
+    )
+    .option("--file <file>", "filter by associated file path (substring match)")
+    .addOption(
+      new Option(
+        "--outcome-status <status>",
+        "filter by outcome status",
+      ).choices(["success", "failure"]),
+    )
+    .option(
+      "--sort-by-score",
+      "sort results by confirmation-frequency score (highest first)",
+    )
+    .option("--all", "show all domains")
+    .action(
+      async (domain: string | undefined, options: Record<string, unknown>) => {
+        const jsonMode = program.opts().json === true;
+        try {
+          const config = await readConfig();
+
+          const domainsToQuery: string[] = [];
+
+          if (options.all) {
+            domainsToQuery.push(...config.domains);
+            if (domainsToQuery.length === 0) {
+              if (jsonMode) {
+                outputJson({ success: true, command: "query", domains: [] });
+              } else {
+                console.log(
+                  "No domains configured. Run `mulch add <domain>` to get started.",
+                );
+              }
+              return;
+            }
+          } else if (domain) {
+            if (!config.domains.includes(domain)) {
+              if (jsonMode) {
+                outputJsonError(
+                  "query",
+                  `Domain "${domain}" not found in config. Available domains: ${config.domains.join(", ") || "(none)"}`,
+                );
+              } else {
+                console.error(
+                  `Error: Domain "${domain}" not found in config. Available domains: ${config.domains.join(", ") || "(none)"}`,
+                );
+              }
+              process.exitCode = 1;
+              return;
+            }
+            domainsToQuery.push(domain);
+          } else {
+            if (jsonMode) {
+              outputJsonError(
+                "query",
+                "Please specify a domain or use --all to query all domains.",
+              );
+            } else {
+              console.error(
+                "Error: Please specify a domain or use --all to query all domains.",
+              );
+            }
+            process.exitCode = 1;
+            return;
+          }
+
+          if (jsonMode) {
+            const result: Array<{ domain: string; records: unknown[] }> = [];
+            for (const d of domainsToQuery) {
+              const filePath = getExpertisePath(d);
+              let records = await readExpertiseFile(filePath);
+              if (options.type) {
+                records = filterByType(records, options.type as string);
+              }
+              if (options.classification) {
+                records = filterByClassification(
+                  records,
+                  options.classification as string,
+                );
+              }
+              if (options.file) {
+                records = filterByFile(records, options.file as string);
+              }
+              if (options.outcomeStatus) {
+                records = records.filter((r) =>
+                  r.outcomes?.some(
+                    (o) => o.status === (options.outcomeStatus as string),
+                  ),
+                );
+              }
+              if (options.sortByScore) {
+                records = sortByConfirmationScore(records as ScoredRecord[]);
+              }
+              result.push({ domain: d, records });
+            }
+            outputJson({ success: true, command: "query", domains: result });
+          } else {
+            const sections: string[] = [];
+            for (const d of domainsToQuery) {
+              const filePath = getExpertisePath(d);
+              let records = await readExpertiseFile(filePath);
+              const lastUpdated = await getFileModTime(filePath);
+              if (options.type) {
+                records = filterByType(records, options.type as string);
+              }
+              if (options.classification) {
+                records = filterByClassification(
+                  records,
+                  options.classification as string,
+                );
+              }
+              if (options.file) {
+                records = filterByFile(records, options.file as string);
+              }
+              if (options.outcomeStatus) {
+                records = records.filter((r) =>
+                  r.outcomes?.some(
+                    (o) => o.status === (options.outcomeStatus as string),
+                  ),
+                );
+              }
+              if (options.sortByScore) {
+                records = sortByConfirmationScore(records as ScoredRecord[]);
+              }
+              sections.push(formatDomainExpertise(d, records, lastUpdated));
+            }
+            console.log(sections.join("\n\n"));
+          }
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            if (jsonMode) {
+              outputJsonError(
+                "query",
+                "No .mulch/ directory found. Run `mulch init` first.",
+              );
+            } else {
+              console.error(
+                "Error: No .mulch/ directory found. Run `mulch init` first.",
+              );
+            }
+          } else {
+            if (jsonMode) {
+              outputJsonError("query", (err as Error).message);
+            } else {
+              console.error(`Error: ${(err as Error).message}`);
+            }
+          }
+          process.exitCode = 1;
+        }
+      },
+    );
+}

package/src/commands/ready.ts

@@ -0,0 +1,194 @@
+import chalk from "chalk";
+import type { Command } from "commander";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { readExpertiseFile } from "../utils/expertise.ts";
+import { formatTimeAgo, getRecordSummary } from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+
+interface AnnotatedRecord {
+  domain: string;
+  record: ExpertiseRecord;
+}
+
+function parseDuration(input: string): number {
+  const match = input.match(/^(\d+)(h|d|w)$/);
+  if (!match) {
+    throw new Error(
+      `Invalid duration: "${input}". Use format like "24h", "7d", "2w".`,
+    );
+  }
+  const value = Number.parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case "h":
+      return value * 3600000;
+    case "d":
+      return value * 86400000;
+    case "w":
+      return value * 7 * 86400000;
+    default:
+      throw new Error(`Unknown unit: ${unit}`);
+  }
+}
+
+export function registerReadyCommand(program: Command): void {
+  program
+    .command("ready")
+    .description("Show recently added or updated expertise records")
+    .option("--limit <n>", "maximum number of records to show", "10")
+    .option("--domain <domain>", "limit to a specific domain")
+    .option(
+      "--since <duration>",
+      "show records from the last duration (e.g. 24h, 7d, 2w)",
+    )
+    .action(
+      async (options: { limit: string; domain?: string; since?: string }) => {
+        const jsonMode = program.opts().json === true;
+
+        try {
+          const config = await readConfig();
+          const limit = Number.parseInt(options.limit, 10);
+
+          if (Number.isNaN(limit) || limit < 1) {
+            if (jsonMode) {
+              outputJsonError("ready", "Limit must be a positive integer.");
+            } else {
+              console.error(
+                chalk.red("Error: --limit must be a positive integer."),
+              );
+            }
+            process.exitCode = 1;
+            return;
+          }
+
+          let domainsToCheck: string[];
+          if (options.domain) {
+            if (!config.domains.includes(options.domain)) {
+              if (jsonMode) {
+                outputJsonError(
+                  "ready",
+                  `Domain "${options.domain}" not found in config. Available domains: ${config.domains.join(", ")}`,
+                );
+              } else {
+                console.error(
+                  chalk.red(
+                    `Error: domain "${options.domain}" not found. Available: ${config.domains.join(", ")}`,
+                  ),
+                );
+              }
+              process.exitCode = 1;
+              return;
+            }
+            domainsToCheck = [options.domain];
+          } else {
+            domainsToCheck = config.domains;
+          }
+
+          let sinceMs: number | undefined;
+          if (options.since) {
+            try {
+              sinceMs = parseDuration(options.since);
+            } catch (err) {
+              if (jsonMode) {
+                outputJsonError("ready", (err as Error).message);
+              } else {
+                console.error(chalk.red(`Error: ${(err as Error).message}`));
+              }
+              process.exitCode = 1;
+              return;
+            }
+          }
+
+          // Collect all records with domain annotation
+          const all: AnnotatedRecord[] = [];
+          for (const domain of domainsToCheck) {
+            const filePath = getExpertisePath(domain);
+            const records = await readExpertiseFile(filePath);
+            for (const record of records) {
+              all.push({ domain, record });
+            }
+          }
+
+          // Sort by recorded_at descending
+          all.sort((a, b) => {
+            const aTime = new Date(a.record.recorded_at).getTime();
+            const bTime = new Date(b.record.recorded_at).getTime();
+            return bTime - aTime;
+          });
+
+          // Apply --since filter
+          let filtered = all;
+          if (sinceMs !== undefined) {
+            const cutoff = Date.now() - sinceMs;
+            filtered = all.filter((entry) => {
+              return new Date(entry.record.recorded_at).getTime() >= cutoff;
+            });
+          }
+
+          // Apply limit
+          const entries = filtered.slice(0, limit);
+
+          if (jsonMode) {
+            outputJson({
+              success: true,
+              command: "ready",
+              count: entries.length,
+              entries: entries.map((e) => ({
+                domain: e.domain,
+                id: e.record.id ?? null,
+                type: e.record.type,
+                recorded_at: e.record.recorded_at,
+                summary: getRecordSummary(e.record),
+                record: e.record,
+              })),
+            });
+          } else {
+            if (entries.length === 0) {
+              console.log("No recent expertise records found.");
+              return;
+            }
+
+            const header = options.since
+              ? `Recent Expertise (last ${options.since})`
+              : `Recent Expertise (last ${entries.length} records)`;
+            console.log(header);
+            console.log("");
+
+            for (const entry of entries) {
+              const age = formatTimeAgo(new Date(entry.record.recorded_at));
+              const id = entry.record.id
+                ? chalk.dim(`${entry.record.id}  `)
+                : "";
+              const domain = chalk.cyan(entry.domain.padEnd(14));
+              const type = chalk.yellow(`[${entry.record.type}]`.padEnd(14));
+              const summary = getRecordSummary(entry.record);
+              console.log(
+                `  ${id}${chalk.dim(age.padEnd(10))}${domain}${type}${summary}`,
+              );
+            }
+          }
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            if (jsonMode) {
+              outputJsonError(
+                "ready",
+                "No .mulch/ directory found. Run `mulch init` first.",
+              );
+            } else {
+              console.error(
+                "Error: No .mulch/ directory found. Run `mulch init` first.",
+              );
+            }
+          } else {
+            if (jsonMode) {
+              outputJsonError("ready", (err as Error).message);
+            } else {
+              console.error(`Error: ${(err as Error).message}`);
+            }
+          }
+          process.exitCode = 1;
+        }
+      },
+    );
+}