mulch-cli 0.5.0 → 0.6.0

package/src/commands/edit.ts

@@ -0,0 +1,253 @@
+import Ajv from "ajv";
+import chalk from "chalk";
+import { type Command, Option } from "commander";
+import { recordSchema } from "../schemas/record-schema.ts";
+import type { Classification, Outcome } from "../schemas/record.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import {
+  readExpertiseFile,
+  resolveRecordId,
+  writeExpertiseFile,
+} from "../utils/expertise.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { withFileLock } from "../utils/lock.ts";
+
+export function registerEditCommand(program: Command): void {
+  program
+    .command("edit")
+    .argument("<domain>", "expertise domain")
+    .argument("<id>", "record ID (e.g. mx-abc123, abc123, or abc)")
+    .description("Edit an existing expertise record")
+    .addOption(
+      new Option(
+        "--classification <classification>",
+        "update classification",
+      ).choices(["foundational", "tactical", "observational"]),
+    )
+    .option("--content <content>", "update content (convention)")
+    .option("--name <name>", "update name (pattern)")
+    .option("--description <description>", "update description")
+    .option("--resolution <resolution>", "update resolution (failure)")
+    .option("--title <title>", "update title (decision)")
+    .option("--rationale <rationale>", "update rationale (decision)")
+    .option("--files <files>", "update related files (comma-separated)")
+    .option("--relates-to <ids>", "update linked record IDs (comma-separated)")
+    .option(
+      "--supersedes <ids>",
+      "update superseded record IDs (comma-separated)",
+    )
+    .addOption(
+      new Option("--outcome-status <status>", "set outcome status").choices([
+        "success",
+        "failure",
+        "partial",
+      ]),
+    )
+    .option("--outcome-duration <ms>", "set outcome duration in milliseconds")
+    .option("--outcome-test-results <text>", "set outcome test results summary")
+    .option("--outcome-agent <agent>", "set outcome agent name")
+    .action(
+      async (domain: string, id: string, options: Record<string, unknown>) => {
+        const jsonMode = program.opts().json === true;
+        try {
+          const config = await readConfig();
+
+          if (!config.domains.includes(domain)) {
+            if (jsonMode) {
+              outputJsonError(
+                "edit",
+                `Domain "${domain}" not found in config. Available domains: ${config.domains.join(", ") || "(none)"}`,
+              );
+            } else {
+              console.error(
+                chalk.red(`Error: domain "${domain}" not found in config.`),
+              );
+              console.error(
+                chalk.red(
+                  `Available domains: ${config.domains.join(", ") || "(none)"}`,
+                ),
+              );
+            }
+            process.exitCode = 1;
+            return;
+          }
+
+          const filePath = getExpertisePath(domain);
+          await withFileLock(filePath, async () => {
+            const records = await readExpertiseFile(filePath);
+
+            const resolved = resolveRecordId(records, id);
+            if (!resolved.ok) {
+              if (jsonMode) {
+                outputJsonError("edit", resolved.error);
+              } else {
+                console.error(chalk.red(`Error: ${resolved.error}`));
+              }
+              process.exitCode = 1;
+              return;
+            }
+            const targetIndex = resolved.index;
+
+            const record = { ...records[targetIndex] };
+
+            // Apply updates based on record type
+            if (options.classification) {
+              record.classification = options.classification as Classification;
+            }
+            if (typeof options.relatesTo === "string") {
+              record.relates_to = options.relatesTo
+                .split(",")
+                .map((id: string) => id.trim())
+                .filter(Boolean);
+            }
+            if (typeof options.supersedes === "string") {
+              record.supersedes = options.supersedes
+                .split(",")
+                .map((id: string) => id.trim())
+                .filter(Boolean);
+            }
+            if (options.outcomeStatus) {
+              const o: Outcome = {
+                status: options.outcomeStatus as
+                  | "success"
+                  | "failure"
+                  | "partial",
+              };
+              if (options.outcomeDuration !== undefined) {
+                o.duration = Number.parseFloat(
+                  options.outcomeDuration as string,
+                );
+              }
+              if (options.outcomeTestResults) {
+                o.test_results = options.outcomeTestResults as string;
+              }
+              if (options.outcomeAgent) {
+                o.agent = options.outcomeAgent as string;
+              }
+              record.outcomes = [...(record.outcomes ?? []), o];
+            }
+
+            switch (record.type) {
+              case "convention":
+                if (options.content) {
+                  record.content = options.content as string;
+                }
+                break;
+              case "pattern":
+                if (options.name) {
+                  record.name = options.name as string;
+                }
+                if (options.description) {
+                  record.description = options.description as string;
+                }
+                if (typeof options.files === "string") {
+                  record.files = (options.files as string).split(",");
+                }
+                break;
+              case "failure":
+                if (options.description) {
+                  record.description = options.description as string;
+                }
+                if (options.resolution) {
+                  record.resolution = options.resolution as string;
+                }
+                break;
+              case "decision":
+                if (options.title) {
+                  record.title = options.title as string;
+                }
+                if (options.rationale) {
+                  record.rationale = options.rationale as string;
+                }
+                break;
+              case "reference":
+                if (options.name) {
+                  record.name = options.name as string;
+                }
+                if (options.description) {
+                  record.description = options.description as string;
+                }
+                if (typeof options.files === "string") {
+                  record.files = (options.files as string).split(",");
+                }
+                break;
+              case "guide":
+                if (options.name) {
+                  record.name = options.name as string;
+                }
+                if (options.description) {
+                  record.description = options.description as string;
+                }
+                break;
+            }
+
+            // Validate the updated record
+            const ajv = new Ajv();
+            const validate = ajv.compile(recordSchema);
+            if (!validate(record)) {
+              const errors = (validate.errors ?? []).map(
+                (err) => `${err.instancePath} ${err.message}`,
+              );
+              if (jsonMode) {
+                outputJsonError(
+                  "edit",
+                  `Updated record failed schema validation: ${errors.join("; ")}`,
+                );
+              } else {
+                console.error(
+                  chalk.red("Error: updated record failed schema validation:"),
+                );
+                for (const err of validate.errors ?? []) {
+                  console.error(
+                    chalk.red(`  ${err.instancePath} ${err.message}`),
+                  );
+                }
+              }
+              process.exitCode = 1;
+              return;
+            }
+
+            records[targetIndex] = record;
+            await writeExpertiseFile(filePath, records);
+
+            if (jsonMode) {
+              outputJson({
+                success: true,
+                command: "edit",
+                domain,
+                id: record.id ?? null,
+                type: record.type,
+                record,
+              });
+            } else {
+              console.log(
+                chalk.green(
+                  `\u2714 Updated ${record.type} ${record.id ?? ""} in ${domain}`,
+                ),
+              );
+            }
+          });
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            if (jsonMode) {
+              outputJsonError(
+                "edit",
+                "No .mulch/ directory found. Run `mulch init` first.",
+              );
+            } else {
+              console.error(
+                "Error: No .mulch/ directory found. Run `mulch init` first.",
+              );
+            }
+          } else {
+            if (jsonMode) {
+              outputJsonError("edit", (err as Error).message);
+            } else {
+              console.error(`Error: ${(err as Error).message}`);
+            }
+          }
+          process.exitCode = 1;
+        }
+      },
+    );
+}

package/src/commands/init.ts

@@ -0,0 +1,33 @@
+import { existsSync } from "node:fs";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { getMulchDir, initMulchDir } from "../utils/config.ts";
+import { outputJson } from "../utils/json-output.ts";
+
+export function registerInitCommand(program: Command): void {
+  program
+    .command("init")
+    .description("Initialize .mulch/ in the current project")
+    .action(async () => {
+      const jsonMode = program.opts().json === true;
+      const mulchDir = getMulchDir();
+      const alreadyExists = existsSync(mulchDir);
+
+      await initMulchDir();
+
+      if (jsonMode) {
+        outputJson({
+          success: true,
+          command: "init",
+          created: !alreadyExists,
+          path: mulchDir,
+        });
+      } else if (alreadyExists) {
+        console.log(
+          chalk.green("Updated .mulch/ — filled in any missing artifacts."),
+        );
+      } else {
+        console.log(chalk.green(`Initialized .mulch/ in ${process.cwd()}`));
+      }
+    });
+}

package/src/commands/learn.ts

@@ -0,0 +1,170 @@
+import chalk from "chalk";
+import type { Command } from "commander";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { readExpertiseFile } from "../utils/expertise.ts";
+import { getChangedFiles, isGitRepo } from "../utils/git.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+
+interface DomainMatch {
+  domain: string;
+  matchedFiles: string[];
+}
+
+export async function matchFilesToDomains(
+  changedFiles: string[],
+  cwd?: string,
+): Promise<{ matches: DomainMatch[]; unmatched: string[] }> {
+  const config = await readConfig(cwd);
+  const matched = new Set<string>();
+  const matches: DomainMatch[] = [];
+
+  for (const domain of config.domains) {
+    const filePath = getExpertisePath(domain, cwd);
+    const records = await readExpertiseFile(filePath);
+
+    // Collect all file paths from pattern and reference records
+    const domainFiles = new Set<string>();
+    for (const record of records) {
+      if (
+        (record.type === "pattern" || record.type === "reference") &&
+        record.files
+      ) {
+        for (const f of record.files) {
+          domainFiles.add(f);
+        }
+      }
+    }
+
+    // Match changed files against domain file paths
+    const domainMatched: string[] = [];
+    for (const changedFile of changedFiles) {
+      for (const domainFile of domainFiles) {
+        if (
+          changedFile === domainFile ||
+          changedFile.endsWith(domainFile) ||
+          domainFile.endsWith(changedFile)
+        ) {
+          domainMatched.push(changedFile);
+          matched.add(changedFile);
+          break;
+        }
+      }
+    }
+
+    if (domainMatched.length > 0) {
+      matches.push({ domain, matchedFiles: domainMatched });
+    }
+  }
+
+  // Sort by match count descending
+  matches.sort((a, b) => b.matchedFiles.length - a.matchedFiles.length);
+
+  const unmatched = changedFiles.filter((f) => !matched.has(f));
+  return { matches, unmatched };
+}
+
+export function registerLearnCommand(program: Command): void {
+  program
+    .command("learn")
+    .description(
+      "Show changed files and suggest domains for recording learnings",
+    )
+    .option("--since <ref>", "git ref to diff against", "HEAD~1")
+    .action(async (options: { since: string }) => {
+      const jsonMode = program.opts().json === true;
+      const cwd = process.cwd();
+
+      if (!isGitRepo(cwd)) {
+        if (jsonMode) {
+          outputJsonError(
+            "learn",
+            "Not in a git repository. Run this command from within a git repository.",
+          );
+        } else {
+          console.error(chalk.red("Error: not in a git repository."));
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      try {
+        const changedFiles = getChangedFiles(cwd, options.since);
+
+        if (changedFiles.length === 0) {
+          if (jsonMode) {
+            outputJson({
+              success: true,
+              command: "learn",
+              changedFiles: [],
+              suggestedDomains: [],
+              unmatchedFiles: [],
+              message: "No changed files found",
+            });
+          } else {
+            console.log("No changed files found. Nothing to learn from.");
+          }
+          return;
+        }
+
+        const { matches, unmatched } = await matchFilesToDomains(changedFiles);
+
+        if (jsonMode) {
+          outputJson({
+            success: true,
+            command: "learn",
+            changedFiles,
+            suggestedDomains: matches.map((m) => ({
+              domain: m.domain,
+              matchCount: m.matchedFiles.length,
+              files: m.matchedFiles,
+            })),
+            unmatchedFiles: unmatched,
+          });
+          return;
+        }
+
+        // Plain text output
+        console.log(chalk.bold("\nSession learnings check\n"));
+
+        console.log(chalk.cyan(`Changed files (${changedFiles.length}):`));
+        for (const f of changedFiles) {
+          console.log(`  ${f}`);
+        }
+
+        if (matches.length > 0) {
+          console.log(chalk.cyan("\nSuggested domains:"));
+          for (const m of matches) {
+            const label =
+              m.matchedFiles.length === 1 ? "file matches" : "files match";
+            console.log(
+              `  ${chalk.bold(m.domain)} (${m.matchedFiles.length} ${label} existing records)`,
+            );
+          }
+        }
+
+        if (unmatched.length > 0) {
+          console.log(
+            chalk.yellow("\nUnmatched files (no domain association):"),
+          );
+          for (const f of unmatched) {
+            console.log(`  ${f}`);
+          }
+        }
+
+        console.log(chalk.dim("\nRecord learnings with:"));
+        console.log(
+          chalk.dim(
+            '  mulch record <domain> --type <type> --description "..."',
+          ),
+        );
+        console.log();
+      } catch (err) {
+        if (jsonMode) {
+          outputJsonError("learn", (err as Error).message);
+        } else {
+          console.error(`Error: ${(err as Error).message}`);
+        }
+        process.exitCode = 1;
+      }
+    });
+}