mulch-cli 0.5.0 → 0.6.0

package/src/commands/status.ts

@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { getExpertisePath, getMulchDir, readConfig } from "../utils/config.ts";
+import {
+  calculateDomainHealth,
+  countRecords,
+  getFileModTime,
+  readExpertiseFile,
+} from "../utils/expertise.ts";
+import { formatStatusOutput } from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+
+export function registerStatusCommand(program: Command): void {
+  program
+    .command("status")
+    .description("Show status of expertise records")
+    .action(async () => {
+      const jsonMode = program.opts().json === true;
+      const mulchDir = getMulchDir();
+
+      if (!existsSync(mulchDir)) {
+        if (jsonMode) {
+          outputJsonError(
+            "status",
+            "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();
+
+      const domainStats = await Promise.all(
+        config.domains.map(async (domain) => {
+          const filePath = getExpertisePath(domain);
+          const records = await readExpertiseFile(filePath);
+          const lastUpdated = await getFileModTime(filePath);
+          const health = calculateDomainHealth(
+            records,
+            config.governance.max_entries,
+            config.classification_defaults.shelf_life,
+          );
+          return {
+            domain,
+            count: countRecords(records),
+            lastUpdated,
+            health,
+            records,
+          };
+        }),
+      );
+
+      if (jsonMode) {
+        outputJson({
+          success: true,
+          command: "status",
+          domains: domainStats.map((s) => ({
+            domain: s.domain,
+            count: s.count,
+            lastUpdated: s.lastUpdated?.toISOString() ?? null,
+            health: s.health,
+          })),
+          governance: config.governance,
+        });
+      } else {
+        const output = formatStatusOutput(
+          domainStats.map((s) => ({
+            domain: s.domain,
+            count: s.count,
+            lastUpdated: s.lastUpdated,
+          })),
+          config.governance,
+        );
+        console.log(output);
+      }
+    });
+}

package/src/commands/sync.ts

@@ -0,0 +1,224 @@
+import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import Ajv from "ajv";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { recordSchema } from "../schemas/record-schema.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+
+function isGitRepo(cwd: string): boolean {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd,
+      stdio: "pipe",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function gitHasChanges(cwd: string): boolean {
+  try {
+    const status = execFileSync("git", ["status", "--porcelain", ".mulch/"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return status.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function gitAdd(cwd: string): void {
+  execFileSync("git", ["add", ".mulch/"], { cwd, stdio: "pipe" });
+}
+
+function gitCommit(cwd: string, message: string): string {
+  return execFileSync("git", ["commit", "-m", message], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+}
+
+interface ValidateResult {
+  valid: boolean;
+  totalRecords: number;
+  errors: Array<{ domain: string; line: number; message: string }>;
+}
+
+async function validateExpertise(cwd?: string): Promise<ValidateResult> {
+  const config = await readConfig(cwd);
+  const domains = config.domains;
+
+  const ajv = new Ajv();
+  const validate = ajv.compile(recordSchema);
+
+  let totalRecords = 0;
+  const errors: Array<{ domain: string; line: number; message: string }> = [];
+
+  for (const domain of domains) {
+    const filePath = getExpertisePath(domain, cwd);
+    let content: string;
+    try {
+      content = await readFile(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (line.length === 0) continue;
+      totalRecords++;
+      const lineNumber = i + 1;
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        errors.push({
+          domain,
+          line: lineNumber,
+          message: "Invalid JSON: failed to parse",
+        });
+        continue;
+      }
+      if (!validate(parsed)) {
+        const schemaErrors = (validate.errors ?? [])
+          .map((err) => `${err.instancePath} ${err.message}`)
+          .join("; ");
+        errors.push({
+          domain,
+          line: lineNumber,
+          message: `Schema validation failed: ${schemaErrors}`,
+        });
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, totalRecords, errors };
+}
+
+export function registerSyncCommand(program: Command): void {
+  program
+    .command("sync")
+    .description("Validate, stage, and commit .mulch/ changes")
+    .option("--message <message>", "custom commit message")
+    .option("--no-validate", "skip validation step")
+    .action(async (options: { message?: string; validate?: boolean }) => {
+      const jsonMode = program.opts().json === true;
+      const cwd = process.cwd();
+
+      // Check if we're in a git repo
+      if (!isGitRepo(cwd)) {
+        if (jsonMode) {
+          outputJsonError(
+            "sync",
+            "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;
+      }
+
+      // Validate (unless --no-validate)
+      if (options.validate !== false) {
+        try {
+          const result = await validateExpertise();
+          if (!result.valid) {
+            if (jsonMode) {
+              outputJson({
+                success: false,
+                command: "sync",
+                validated: false,
+                committed: false,
+                errors: result.errors,
+              });
+            } else {
+              console.error(chalk.red("Validation failed:"));
+              for (const err of result.errors) {
+                console.error(
+                  chalk.red(`  ${err.domain}:${err.line} - ${err.message}`),
+                );
+              }
+              console.error(
+                chalk.red(
+                  "\nFix errors and retry, or use --no-validate to skip.",
+                ),
+              );
+            }
+            process.exitCode = 1;
+            return;
+          }
+          if (!jsonMode) {
+            console.log(
+              chalk.green(`✔ Validated ${result.totalRecords} records`),
+            );
+          }
+        } catch (err) {
+          if (jsonMode) {
+            outputJsonError(
+              "sync",
+              `Validation error: ${(err as Error).message}`,
+            );
+          } else {
+            console.error(
+              chalk.red(`Validation error: ${(err as Error).message}`),
+            );
+          }
+          process.exitCode = 1;
+          return;
+        }
+      }
+
+      // Check for changes
+      if (!gitHasChanges(cwd)) {
+        if (jsonMode) {
+          outputJson({
+            success: true,
+            command: "sync",
+            validated: options.validate !== false,
+            committed: false,
+            message: "No changes to commit",
+          });
+        } else {
+          console.log("No .mulch/ changes to commit.");
+        }
+        return;
+      }
+
+      // Git add + commit
+      const commitMessage = options.message ?? "mulch: update expertise";
+      try {
+        gitAdd(cwd);
+        gitCommit(cwd, commitMessage);
+
+        if (jsonMode) {
+          outputJson({
+            success: true,
+            command: "sync",
+            validated: options.validate !== false,
+            committed: true,
+            message: commitMessage,
+          });
+        } else {
+          console.log(
+            chalk.green(`✔ Committed .mulch/ changes: "${commitMessage}"`),
+          );
+        }
+      } catch (err) {
+        if (jsonMode) {
+          outputJsonError("sync", `Git error: ${(err as Error).message}`);
+        } else {
+          console.error(chalk.red(`Git error: ${(err as Error).message}`));
+        }
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/update.ts

@@ -0,0 +1,112 @@
+import { execSync } from "node:child_process";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import {
+  compareSemver,
+  getCurrentVersion,
+  getLatestVersion,
+} from "../utils/version.ts";
+
+export function registerUpdateCommand(program: Command): void {
+  program
+    .command("update")
+    .description("Check for and install mulch-cli updates")
+    .option("--check", "only check for updates, do not install")
+    .action(async (options: { check?: boolean }) => {
+      const jsonMode = program.opts().json === true;
+      const current = getCurrentVersion();
+      const latest = getLatestVersion();
+
+      if (latest === null) {
+        if (jsonMode) {
+          outputJsonError(
+            "update",
+            "Unable to reach npm registry. Check your internet connection.",
+          );
+        } else {
+          console.error(
+            chalk.red(
+              "Unable to reach npm registry. Check your internet connection.",
+            ),
+          );
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      const cmp = compareSemver(current, latest);
+
+      if (cmp >= 0) {
+        if (jsonMode) {
+          outputJson({
+            success: true,
+            command: "update",
+            current,
+            latest,
+            upToDate: true,
+            updated: false,
+          });
+        } else {
+          console.log(chalk.green(`mulch-cli ${current} is up to date`));
+        }
+        return;
+      }
+
+      if (options.check) {
+        if (jsonMode) {
+          outputJson({
+            success: true,
+            command: "update",
+            current,
+            latest,
+            upToDate: false,
+            updated: false,
+          });
+        } else {
+          console.log(
+            `Update available: ${chalk.yellow(current)} → ${chalk.green(latest)}`,
+          );
+          console.log(`Run ${chalk.cyan("mulch update")} to install.`);
+        }
+        return;
+      }
+
+      if (!jsonMode) {
+        console.log(
+          `Updating mulch-cli: ${chalk.yellow(current)} → ${chalk.green(latest)}`,
+        );
+      }
+
+      try {
+        execSync("npm update -g mulch-cli", {
+          encoding: "utf-8",
+          timeout: 60000,
+          stdio: jsonMode ? ["pipe", "pipe", "pipe"] : "inherit",
+        });
+
+        if (jsonMode) {
+          outputJson({
+            success: true,
+            command: "update",
+            current,
+            latest,
+            upToDate: false,
+            updated: true,
+          });
+        } else {
+          console.log(chalk.green(`Updated to mulch-cli ${latest}`));
+        }
+      } catch (err) {
+        if (jsonMode) {
+          outputJsonError("update", `Update failed: ${(err as Error).message}`);
+        } else {
+          console.error(chalk.red(`Update failed: ${(err as Error).message}`));
+          console.error(
+            chalk.yellow("Try running manually: npm update -g mulch-cli"),
+          );
+        }
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/validate.ts

@@ -0,0 +1,107 @@
+import { readFile } from "node:fs/promises";
+import Ajv from "ajv";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { recordSchema } from "../schemas/record-schema.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+
+export function registerValidateCommand(program: Command): void {
+  program
+    .command("validate")
+    .description("Validate expertise records against schemas")
+    .action(async () => {
+      const jsonMode = program.opts().json === true;
+      const config = await readConfig();
+      const domains = config.domains;
+
+      const ajv = new Ajv();
+      const validate = ajv.compile(recordSchema);
+
+      let totalRecords = 0;
+      let totalErrors = 0;
+      const errors: Array<{ domain: string; line: number; message: string }> =
+        [];
+
+      for (const domain of domains) {
+        const filePath = getExpertisePath(domain);
+        let content: string;
+        try {
+          content = await readFile(filePath, "utf-8");
+        } catch {
+          // File doesn't exist yet, skip
+          continue;
+        }
+
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i].trim();
+          if (line.length === 0) continue;
+
+          totalRecords++;
+          const lineNumber = i + 1;
+
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(line);
+          } catch {
+            totalErrors++;
+            const msg = "Invalid JSON: failed to parse";
+            errors.push({ domain, line: lineNumber, message: msg });
+            if (!jsonMode) {
+              console.error(chalk.red(`${domain}:${lineNumber} - ${msg}`));
+            }
+            continue;
+          }
+
+          if (!validate(parsed)) {
+            totalErrors++;
+            const schemaErrors = (validate.errors ?? [])
+              .map((err) => `${err.instancePath} ${err.message}`)
+              .join("; ");
+            const msg = `Schema validation failed: ${schemaErrors}`;
+            errors.push({ domain, line: lineNumber, message: msg });
+            if (!jsonMode) {
+              console.error(
+                chalk.red(
+                  `${domain}:${lineNumber} - Schema validation failed:`,
+                ),
+              );
+              for (const err of validate.errors ?? []) {
+                console.error(
+                  chalk.red(`  ${err.instancePath} ${err.message}`),
+                );
+              }
+            }
+          }
+        }
+      }
+
+      if (jsonMode) {
+        outputJson({
+          success: totalErrors === 0,
+          command: "validate",
+          valid: totalErrors === 0,
+          totalRecords,
+          totalErrors,
+          errors,
+        });
+      } else if (totalErrors > 0) {
+        console.log(
+          chalk.red(
+            `${totalRecords} records validated, ${totalErrors} errors found`,
+          ),
+        );
+      } else {
+        console.log(
+          chalk.green(
+            `${totalRecords} records validated, ${totalErrors} errors found`,
+          ),
+        );
+      }
+
+      if (totalErrors > 0) {
+        process.exitCode = 1;
+      }
+    });
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+// Type exports
+export type {
+  RecordType,
+  Classification,
+  Evidence,
+  Outcome,
+  ConventionRecord,
+  PatternRecord,
+  FailureRecord,
+  DecisionRecord,
+  ReferenceRecord,
+  GuideRecord,
+  ExpertiseRecord,
+} from "./schemas/index.ts";
+
+export type { MulchConfig } from "./schemas/index.ts";
+export { DEFAULT_CONFIG } from "./schemas/index.ts";
+
+// Schema exports
+export { recordSchema } from "./schemas/record-schema.ts";
+
+// Config utilities
+export { readConfig, getExpertisePath } from "./utils/config.ts";
+
+// Expertise utilities
+export {
+  readExpertiseFile,
+  searchRecords,
+  appendRecord,
+  writeExpertiseFile,
+  findDuplicate,
+  generateRecordId,
+} from "./utils/expertise.ts";
+
+// Programmatic API
+export {
+  recordExpertise,
+  searchExpertise,
+  queryDomain,
+  editRecord,
+} from "./api.ts";
+export type {
+  RecordOptions,
+  RecordResult,
+  SearchOptions,
+  SearchResult,
+  QueryOptions,
+  EditOptions,
+  RecordUpdates,
+} from "./api.ts";

package/src/schemas/config.ts

@@ -0,0 +1,31 @@
+export interface MulchConfig {
+  version: string;
+  domains: string[];
+  governance: {
+    max_entries: number;
+    warn_entries: number;
+    hard_limit: number;
+  };
+  classification_defaults: {
+    shelf_life: {
+      tactical: number;
+      observational: number;
+    };
+  };
+}
+
+export const DEFAULT_CONFIG: MulchConfig = {
+  version: "1",
+  domains: [],
+  governance: {
+    max_entries: 100,
+    warn_entries: 150,
+    hard_limit: 200,
+  },
+  classification_defaults: {
+    shelf_life: {
+      tactical: 14,
+      observational: 30,
+    },
+  },
+};

package/src/schemas/index.ts

@@ -0,0 +1,18 @@
+export type {
+  RecordType,
+  Classification,
+  Evidence,
+  Outcome,
+  ConventionRecord,
+  PatternRecord,
+  FailureRecord,
+  DecisionRecord,
+  ReferenceRecord,
+  GuideRecord,
+  ExpertiseRecord,
+} from "./record.ts";
+
+export type { MulchConfig } from "./config.ts";
+export { DEFAULT_CONFIG } from "./config.ts";
+
+export { recordSchema } from "./record-schema.ts";