@codluv/versionguard 0.3.0 → 0.5.0

package/dist/chunks/{index-BrZJDWya.js → index-CwOyEn5L.js}

@@ -6,38 +6,83 @@ import { parse as parse$2 } from "smol-toml";
 import * as yaml from "js-yaml";
 import { globSync } from "glob";
 import { fileURLToPath } from "node:url";
+const VALID_TOKENS = /* @__PURE__ */ new Set([
+  "YYYY",
+  "YY",
+  "0Y",
+  "MM",
+  "M",
+  "0M",
+  "WW",
+  "0W",
+  "DD",
+  "D",
+  "0D",
+  "MICRO",
+  "PATCH"
+]);
+const YEAR_TOKENS = /* @__PURE__ */ new Set(["YYYY", "YY", "0Y"]);
+const MONTH_TOKENS = /* @__PURE__ */ new Set(["MM", "M", "0M"]);
+const WEEK_TOKENS = /* @__PURE__ */ new Set(["WW", "0W"]);
+const DAY_TOKENS = /* @__PURE__ */ new Set(["DD", "D", "0D"]);
+const COUNTER_TOKENS = /* @__PURE__ */ new Set(["MICRO", "PATCH"]);
+function isValidCalVerFormat(formatStr) {
+  const tokens = formatStr.split(".");
+  if (tokens.length < 2) return false;
+  if (!tokens.every((t) => VALID_TOKENS.has(t))) return false;
+  if (!YEAR_TOKENS.has(tokens[0])) return false;
+  const hasWeek = tokens.some((t) => WEEK_TOKENS.has(t));
+  const hasMonthOrDay = tokens.some((t) => MONTH_TOKENS.has(t) || DAY_TOKENS.has(t));
+  if (hasWeek && hasMonthOrDay) return false;
+  const counterIndex = tokens.findIndex((t) => COUNTER_TOKENS.has(t));
+  if (counterIndex !== -1 && counterIndex !== tokens.length - 1) return false;
+  return true;
+}
 function parseFormat(calverFormat) {
-  const parts = calverFormat.split(".");
+  const tokens = calverFormat.split(".");
   const result = {
-    year: parts[0],
-    month: parts[1]
+    year: tokens[0]
   };
-  if (parts[2] === "PATCH") {
-    result.patch = "PATCH";
-  } else if (parts[2]) {
-    result.day = parts[2];
-  }
-  if (parts[3] === "PATCH") {
-    result.patch = "PATCH";
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (MONTH_TOKENS.has(token)) {
+      result.month = token;
+    } else if (WEEK_TOKENS.has(token)) {
+      result.week = token;
+    } else if (DAY_TOKENS.has(token)) {
+      result.day = token;
+    } else if (COUNTER_TOKENS.has(token)) {
+      result.counter = token;
+    }
   }
   return result;
 }
+const MODIFIER_PATTERN = "(?:-([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?";
 function tokenPattern(token) {
   switch (token) {
     case "YYYY":
-      return "(\\d{4})";
+      return "([1-9]\\d{3})";
     case "YY":
-      return "(\\d{2})";
-    case "0M":
-    case "0D":
-      return "(\\d{2})";
+      return "(\\d{1,3})";
+    case "0Y":
+      return "(\\d{2,3})";
     case "MM":
-    case "DD":
     case "M":
+      return "([1-9]|1[0-2])";
+    case "0M":
+      return "(0[1-9]|1[0-2])";
+    case "WW":
+      return "([1-9]|[1-4]\\d|5[0-3])";
+    case "0W":
+      return "(0[1-9]|[1-4]\\d|5[0-3])";
+    case "DD":
     case "D":
-      return "(\\d{1,2})";
+      return "([1-9]|[12]\\d|3[01])";
+    case "0D":
+      return "(0[1-9]|[12]\\d|3[01])";
+    case "MICRO":
     case "PATCH":
-      return "(\\d+)";
+      return "(0|[1-9]\\d*)";
     default:
       throw new Error(`Unsupported CalVer token: ${token}`);
   }
@@ -45,7 +90,7 @@ function tokenPattern(token) {
 function getRegexForFormat(calverFormat) {
   const tokens = calverFormat.split(".");
   const pattern = tokens.map(tokenPattern).join("\\.");
-  return new RegExp(`^${pattern}$`);
+  return new RegExp(`^${pattern}${MODIFIER_PATTERN}$`);
 }
 function parse$1(version, calverFormat) {
   const match = version.match(getRegexForFormat(calverFormat));
@@ -53,28 +98,44 @@ function parse$1(version, calverFormat) {
     return null;
   }
   const definition = parseFormat(calverFormat);
-  const year = definition.year === "YYYY" ? Number.parseInt(match[1], 10) : 2e3 + Number.parseInt(match[1], 10);
-  const month = Number.parseInt(match[2], 10);
-  let cursor = 3;
+  const yearToken = definition.year;
+  let year = Number.parseInt(match[1], 10);
+  if (yearToken === "YY" || yearToken === "0Y") {
+    year = 2e3 + year;
+  }
+  let cursor = 2;
+  let month;
   let day;
   let patch;
+  if (definition.month) {
+    month = Number.parseInt(match[cursor], 10);
+    cursor += 1;
+  }
+  if (definition.week) {
+    month = Number.parseInt(match[cursor], 10);
+    cursor += 1;
+  }
   if (definition.day) {
     day = Number.parseInt(match[cursor], 10);
     cursor += 1;
   }
-  if (definition.patch) {
+  if (definition.counter) {
     patch = Number.parseInt(match[cursor], 10);
+    cursor += 1;
   }
+  const modifierGroup = match[cursor];
+  const modifier = modifierGroup || void 0;
   return {
     year,
-    month,
+    month: month ?? 1,
     day,
     patch,
+    modifier,
     format: calverFormat,
     raw: version
   };
 }
-function validate$2(version, calverFormat, preventFutureDates = true) {
+function validate$2(version, calverFormat, preventFutureDates = true, schemeRules) {
   const errors = [];
   const parsed = parse$1(version, calverFormat);
   if (!parsed) {
@@ -88,19 +149,26 @@ function validate$2(version, calverFormat, preventFutureDates = true) {
       ]
     };
   }
-  if (parsed.month < 1 || parsed.month > 12) {
+  const definition = parseFormat(calverFormat);
+  if (definition.month && (parsed.month < 1 || parsed.month > 12)) {
     errors.push({
       message: `Invalid month: ${parsed.month}. Must be between 1 and 12.`,
       severity: "error"
     });
   }
+  if (definition.week && (parsed.month < 1 || parsed.month > 53)) {
+    errors.push({
+      message: `Invalid week: ${parsed.month}. Must be between 1 and 53.`,
+      severity: "error"
+    });
+  }
   if (parsed.day !== void 0) {
     if (parsed.day < 1 || parsed.day > 31) {
       errors.push({
         message: `Invalid day: ${parsed.day}. Must be between 1 and 31.`,
         severity: "error"
       });
-    } else {
+    } else if (definition.month) {
       const daysInMonth = new Date(parsed.year, parsed.month, 0).getDate();
       if (parsed.day > daysInMonth) {
         errors.push({
@@ -120,56 +188,83 @@ function validate$2(version, calverFormat, preventFutureDates = true) {
         message: `Future year not allowed: ${parsed.year}. Current year is ${currentYear}.`,
         severity: "error"
       });
-    } else if (parsed.year === currentYear && parsed.month > currentMonth) {
+    } else if (definition.month && parsed.year === currentYear && parsed.month > currentMonth) {
       errors.push({
         message: `Future month not allowed: ${parsed.year}.${parsed.month}. Current month is ${currentMonth}.`,
         severity: "error"
       });
-    } else if (parsed.year === currentYear && parsed.month === currentMonth && parsed.day !== void 0 && parsed.day > currentDay) {
+    } else if (definition.month && parsed.year === currentYear && parsed.month === currentMonth && parsed.day !== void 0 && parsed.day > currentDay) {
       errors.push({
         message: `Future day not allowed: ${parsed.year}.${parsed.month}.${parsed.day}. Current day is ${currentDay}.`,
         severity: "error"
       });
     }
   }
+  if (parsed.modifier && schemeRules?.allowedModifiers) {
+    const baseModifier = parsed.modifier.replace(/[\d.]+$/, "") || parsed.modifier;
+    if (!schemeRules.allowedModifiers.includes(baseModifier)) {
+      errors.push({
+        message: `Modifier "${parsed.modifier}" is not allowed. Allowed: ${schemeRules.allowedModifiers.join(", ")}`,
+        severity: "error"
+      });
+    }
+  }
+  if (schemeRules?.maxNumericSegments) {
+    const segmentCount = calverFormat.split(".").length;
+    if (segmentCount > schemeRules.maxNumericSegments) {
+      errors.push({
+        message: `Format has ${segmentCount} segments, convention recommends ${schemeRules.maxNumericSegments} or fewer`,
+        severity: "warning"
+      });
+    }
+  }
   return {
-    valid: errors.length === 0,
+    valid: errors.filter((e) => e.severity === "error").length === 0,
     errors,
     version: { type: "calver", version: parsed }
   };
 }
 function formatToken(token, value) {
-  if (token === "0M" || token === "0D") {
-    return String(value).padStart(2, "0");
-  }
-  if (token === "YY") {
-    return String(value % 100).padStart(2, "0");
+  switch (token) {
+    case "0M":
+    case "0D":
+    case "0W":
+    case "0Y":
+      return String(token === "0Y" ? value % 100 : value).padStart(2, "0");
+    case "YY":
+      return String(value % 100).padStart(2, "0");
+    default:
+      return String(value);
   }
-  return String(value);
 }
 function format$1(version) {
-  const tokens = version.format.split(".");
-  const values = [version.year, version.month];
-  if (tokens.includes("DD") || tokens.includes("D") || tokens.includes("0D")) {
-    values.push(version.day ?? 1);
+  const definition = parseFormat(version.format);
+  const parts = [formatToken(definition.year, version.year)];
+  if (definition.month) {
+    parts.push(formatToken(definition.month, version.month));
   }
-  if (tokens.includes("PATCH")) {
-    values.push(version.patch ?? 0);
+  if (definition.week) {
+    parts.push(formatToken(definition.week, version.month));
   }
-  return tokens.map((token, index) => formatToken(token, values[index])).join(".");
+  if (definition.day) {
+    parts.push(formatToken(definition.day, version.day ?? 1));
+  }
+  if (definition.counter) {
+    parts.push(formatToken(definition.counter, version.patch ?? 0));
+  }
+  const base = parts.join(".");
+  return version.modifier ? `${base}-${version.modifier}` : base;
 }
 function getCurrentVersion(calverFormat, now = /* @__PURE__ */ new Date()) {
   const definition = parseFormat(calverFormat);
-  const currentDay = now.getDate();
   const base = {
     year: now.getFullYear(),
     month: now.getMonth() + 1,
-    day: definition.day ? currentDay : void 0,
-    patch: definition.patch ? 0 : void 0
+    day: definition.day ? now.getDate() : void 0,
+    patch: definition.counter ? 0 : void 0,
+    format: calverFormat
   };
-  const day = base.day ?? currentDay;
-  const patch = base.patch ?? 0;
-  return formatToken(definition.year, base.year).concat(`.${formatToken(definition.month, base.month)}`).concat(definition.day ? `.${formatToken(definition.day, day)}` : "").concat(definition.patch ? `.${patch}` : "");
+  return format$1(base);
 }
 function compare$1(a, b, calverFormat) {
   const left = parse$1(a, calverFormat);
@@ -195,12 +290,11 @@ function increment$1(version, calverFormat) {
   const next = {
     ...parsed
   };
-  if (definition.patch) {
-    const patch = parsed.patch ?? 0;
-    next.patch = patch + 1;
+  if (definition.counter) {
+    next.patch = (parsed.patch ?? 0) + 1;
   } else {
     next.patch = 0;
-    next.format = `${calverFormat}.PATCH`;
+    next.format = `${calverFormat}.MICRO`;
   }
   return format$1(next);
 }
@@ -215,6 +309,7 @@ const calver = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProper
   getNextVersions,
   getRegexForFormat,
   increment: increment$1,
+  isValidCalVerFormat,
   parse: parse$1,
   parseFormat,
   validate: validate$2
@@ -246,7 +341,7 @@ function validateChangelog(changelogPath, version, strict = true, requireEntry =
       errors.push("Changelog should include compare links at the bottom");
     }
     const versionHeaderMatch = content.match(
-      new RegExp(`## \\[${escapeRegExp$2(version)}\\] - ([^\r
+      new RegExp(`## \\[${escapeRegExp$1(version)}\\] - ([^\r
 ]+)`)
     );
     if (requireEntry && hasEntryForVersion) {
@@ -286,10 +381,109 @@ function addVersionEntry(changelogPath, version, date = (/* @__PURE__ */ new Dat
   const updated = `${content.slice(0, insertIndex)}${block}${content.slice(insertIndex)}`;
   fs.writeFileSync(changelogPath, updated, "utf-8");
 }
-function escapeRegExp$2(value) {
+function isChangesetMangled(changelogPath) {
+  if (!fs.existsSync(changelogPath)) return false;
+  const content = fs.readFileSync(changelogPath, "utf-8");
+  return /^## \d+\.\d+/m.test(content) && content.includes("## [Unreleased]");
+}
+const SECTION_MAP = {
+  "Major Changes": "Changed",
+  "Minor Changes": "Added",
+  "Patch Changes": "Fixed"
+};
+function fixChangesetMangling(changelogPath, date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)) {
+  if (!fs.existsSync(changelogPath)) return false;
+  const content = fs.readFileSync(changelogPath, "utf-8");
+  const versionMatch = content.match(/^## (\d+\.\d+\.\d+[^\n]*)\n/m);
+  if (!versionMatch || versionMatch.index === void 0) return false;
+  const fullHeader = versionMatch[0];
+  if (fullHeader.includes("[")) return false;
+  const version = versionMatch[1].trim();
+  if (content.includes(`## [${version}]`)) return false;
+  const startIndex = versionMatch.index;
+  const preambleMatch = content.indexOf("All notable changes", startIndex);
+  const unreleasedMatch = content.indexOf("## [Unreleased]", startIndex);
+  let endIndex;
+  if (preambleMatch !== -1 && preambleMatch < unreleasedMatch) {
+    endIndex = preambleMatch;
+  } else if (unreleasedMatch !== -1) {
+    endIndex = unreleasedMatch;
+  } else {
+    return false;
+  }
+  const changesetsBlock = content.slice(startIndex + fullHeader.length, endIndex).trim();
+  const transformedSections = transformChangesetsContent(changesetsBlock);
+  const newEntry = `## [${version}] - ${date}
+
+${transformedSections}
+
+`;
+  const beforeChangesets = content.slice(0, startIndex);
+  const afterChangesets = content.slice(endIndex);
+  const unreleasedInAfter = afterChangesets.indexOf("## [Unreleased]");
+  if (unreleasedInAfter === -1) {
+    const rebuilt2 = `${beforeChangesets}${newEntry}${afterChangesets}`;
+    fs.writeFileSync(changelogPath, rebuilt2, "utf-8");
+    return true;
+  }
+  const unreleasedLineEnd = afterChangesets.indexOf("\n", unreleasedInAfter);
+  const afterUnreleased = unreleasedLineEnd !== -1 ? afterChangesets.slice(0, unreleasedLineEnd + 1) : afterChangesets;
+  const rest = unreleasedLineEnd !== -1 ? afterChangesets.slice(unreleasedLineEnd + 1) : "";
+  const rebuilt = `${beforeChangesets}${afterUnreleased}
+${newEntry}${rest}`;
+  const withLinks = updateCompareLinks(rebuilt, version);
+  fs.writeFileSync(changelogPath, withLinks, "utf-8");
+  return true;
+}
+function transformChangesetsContent(block) {
+  const lines = block.split("\n");
+  const result = [];
+  for (const line of lines) {
+    const sectionMatch = line.match(/^### (.+)/);
+    if (sectionMatch) {
+      const mapped = SECTION_MAP[sectionMatch[1]] ?? sectionMatch[1];
+      result.push(`### ${mapped}`);
+      continue;
+    }
+    const entryMatch = line.match(
+      /^(\s*-\s+)[a-f0-9]{7,}: (?:feat|fix|chore|docs|refactor|perf|test|ci|build|style)(?:\([^)]*\))?: (.+)/
+    );
+    if (entryMatch) {
+      result.push(`${entryMatch[1]}${entryMatch[2]}`);
+      continue;
+    }
+    const simpleHashMatch = line.match(/^(\s*-\s+)[a-f0-9]{7,}: (.+)/);
+    if (simpleHashMatch) {
+      result.push(`${simpleHashMatch[1]}${simpleHashMatch[2]}`);
+      continue;
+    }
+    result.push(line);
+  }
+  return result.join("\n");
+}
+function updateCompareLinks(content, version) {
+  const unreleasedLinkRegex = /\[Unreleased\]: (https:\/\/[^\s]+\/compare\/v)([\d.]+)(\.\.\.HEAD)/;
+  const match = content.match(unreleasedLinkRegex);
+  if (match) {
+    const baseUrl = match[1].replace(/v$/, "");
+    const previousVersion = match[2];
+    const newUnreleasedLink = `[Unreleased]: ${baseUrl}v${version}...HEAD`;
+    const newVersionLink = `[${version}]: ${baseUrl}v${previousVersion}...v${version}`;
+    let updated = content.replace(unreleasedLinkRegex, newUnreleasedLink);
+    if (!updated.includes(`[${version}]:`)) {
+      updated = updated.replace(newUnreleasedLink, `${newUnreleasedLink}
+${newVersionLink}`);
+    }
+    return updated;
+  }
+  return content;
+}
+function escapeRegExp$1(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 const HOOK_NAMES$1 = ["pre-commit", "pre-push", "post-tag"];
+const VG_BLOCK_START = "# >>> versionguard >>>";
+const VG_BLOCK_END = "# <<< versionguard <<<";
 function installHooks(config, cwd = process.cwd()) {
   const gitDir = findGitDir(cwd);
   if (!gitDir) {
@@ -300,7 +494,36 @@ function installHooks(config, cwd = process.cwd()) {
   for (const hookName of HOOK_NAMES$1) {
     if (config.hooks[hookName]) {
       const hookPath = path.join(hooksDir, hookName);
-      fs.writeFileSync(hookPath, generateHookScript(hookName), { encoding: "utf-8", mode: 493 });
+      const vgBlock = generateHookBlock(hookName);
+      if (fs.existsSync(hookPath)) {
+        const existing = fs.readFileSync(hookPath, "utf-8");
+        if (existing.includes(VG_BLOCK_START)) {
+          const updated = replaceVgBlock(existing, vgBlock);
+          fs.writeFileSync(hookPath, updated, { encoding: "utf-8", mode: 493 });
+        } else if (isLegacyVgHook(existing)) {
+          fs.writeFileSync(hookPath, `#!/bin/sh
+
+${vgBlock}
+`, {
+            encoding: "utf-8",
+            mode: 493
+          });
+        } else {
+          const appended = `${existing.trimEnd()}
+
+${vgBlock}
+`;
+          fs.writeFileSync(hookPath, appended, { encoding: "utf-8", mode: 493 });
+        }
+      } else {
+        fs.writeFileSync(hookPath, `#!/bin/sh
+
+${vgBlock}
+`, {
+          encoding: "utf-8",
+          mode: 493
+        });
+      }
     }
   }
 }
@@ -312,7 +535,21 @@ function uninstallHooks(cwd = process.cwd()) {
   const hooksDir = path.join(gitDir, "hooks");
   for (const hookName of HOOK_NAMES$1) {
     const hookPath = path.join(hooksDir, hookName);
-    if (fs.existsSync(hookPath) && fs.readFileSync(hookPath, "utf-8").includes("versionguard")) {
+    if (!fs.existsSync(hookPath)) continue;
+    const content = fs.readFileSync(hookPath, "utf-8");
+    if (!content.includes("versionguard")) continue;
+    if (content.includes(VG_BLOCK_START)) {
+      const cleaned = removeVgBlock(content);
+      const trimmed = cleaned.trim();
+      if (!trimmed || trimmed === "#!/bin/sh") {
+        fs.unlinkSync(hookPath);
+      } else if (isLegacyVgHook(trimmed)) {
+        fs.unlinkSync(hookPath);
+      } else {
+        fs.writeFileSync(hookPath, `${trimmed}
+`, { encoding: "utf-8", mode: 493 });
+      }
+    } else if (isLegacyVgHook(content)) {
       fs.unlinkSync(hookPath);
     }
   }
@@ -341,9 +578,8 @@ function areHooksInstalled(cwd = process.cwd()) {
     return fs.existsSync(hookPath) && fs.readFileSync(hookPath, "utf-8").includes("versionguard");
   });
 }
-function generateHookScript(hookName) {
-  return `#!/bin/sh
-# versionguard
+function generateHookBlock(hookName) {
+  return `${VG_BLOCK_START}
 # VersionGuard ${hookName} hook
 # --no-install prevents accidentally downloading an unscoped package
 # if @codluv/versionguard is not installed locally
@@ -353,11 +589,47 @@ if [ $status -ne 0 ]; then
   echo "VersionGuard validation failed."
   exit $status
 fi
+${VG_BLOCK_END}`;
+}
+function generateHookScript(hookName) {
+  return `#!/bin/sh
+
+${generateHookBlock(hookName)}
 `;
 }
+function isLegacyVgHook(content) {
+  if (!content.includes("versionguard validate")) return false;
+  if (content.includes(VG_BLOCK_START)) return false;
+  if (content.includes("husky")) return false;
+  if (content.includes("lefthook")) return false;
+  if (content.includes("pre-commit run")) return false;
+  return true;
+}
+function replaceVgBlock(content, newBlock) {
+  const startIdx = content.indexOf(VG_BLOCK_START);
+  const endIdx = content.indexOf(VG_BLOCK_END);
+  if (startIdx === -1 || endIdx === -1) return content;
+  return content.slice(0, startIdx) + newBlock + content.slice(endIdx + VG_BLOCK_END.length);
+}
+function removeVgBlock(content) {
+  const startIdx = content.indexOf(VG_BLOCK_START);
+  const endIdx = content.indexOf(VG_BLOCK_END);
+  if (startIdx === -1 || endIdx === -1) return content;
+  const before = content.slice(0, startIdx).replace(/\n\n$/, "\n");
+  const after = content.slice(endIdx + VG_BLOCK_END.length).replace(/^\n\n/, "\n");
+  return before + after;
+}
 class GitTagSource {
+  /** Human-readable provider name. */
   name = "git-tag";
+  /** Empty string since git-tag has no manifest file. */
   manifestFile = "";
+  /**
+   * Returns `true` when `cwd` is inside a Git repository.
+   *
+   * @param cwd - Project directory to check.
+   * @returns Whether a Git repository is found.
+   */
   exists(cwd) {
     try {
       execFileSync("git", ["rev-parse", "--git-dir"], {
@@ -369,87 +641,167 @@ class GitTagSource {
       return false;
     }
   }
+  /**
+   * Reads the version string from the latest Git tag.
+   *
+   * @param cwd - Project directory containing the Git repository.
+   * @returns The version string extracted from the latest version tag.
+   */
   getVersion(cwd) {
     try {
-      const tag = execFileSync("git", ["describe", "--tags", "--abbrev=0"], {
-        cwd,
-        encoding: "utf-8",
-        stdio: ["pipe", "pipe", "ignore"]
-      }).trim();
+      const tag = this.describeVersionTag(cwd);
       return tag.replace(/^v/, "");
     } catch {
-      throw new Error("No git tags found. Create a tag first (e.g., git tag v0.1.0)");
+      throw new Error("No version tags found. Create a tag first (e.g., git tag v0.1.0)");
     }
   }
+  /**
+   * Creates a new annotated Git tag for the given version.
+   *
+   * @param version - Version string to tag.
+   * @param cwd - Project directory containing the Git repository.
+   */
   setVersion(version, cwd) {
-    const tagName = `v${version}`;
+    const prefix = this.detectPrefix(cwd);
+    const tagName = `${prefix}${version}`;
     execFileSync("git", ["tag", "-a", tagName, "-m", `Release ${version}`], {
       cwd,
       stdio: ["pipe", "pipe", "ignore"]
     });
   }
+  /** Try version-like tag patterns, fall back to any tag. */
+  describeVersionTag(cwd) {
+    try {
+      return execFileSync("git", ["describe", "--tags", "--abbrev=0", "--match", "v[0-9]*"], {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+    try {
+      return execFileSync("git", ["describe", "--tags", "--abbrev=0", "--match", "[0-9]*"], {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "ignore"]
+      }).trim();
+    } catch {
+      throw new Error("No version tags found");
+    }
+  }
+  /** Detect whether existing tags use a `v` prefix or not. */
+  detectPrefix(cwd) {
+    try {
+      const tag = this.describeVersionTag(cwd);
+      return tag.startsWith("v") ? "v" : "";
+    } catch {
+      return "v";
+    }
+  }
+}
+function getNestedValue(obj, dotPath) {
+  let current = obj;
+  for (const key of dotPath.split(".")) {
+    if (current === null || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[key];
+  }
+  return current;
+}
+function setNestedValue(obj, dotPath, value) {
+  const keys = dotPath.split(".");
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const next = current[keys[i]];
+    if (typeof next !== "object" || next === null) {
+      throw new Error(`Missing intermediate key '${keys.slice(0, i + 1).join(".")}' in manifest`);
+    }
+    current = next;
+  }
+  current[keys[keys.length - 1]] = value;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 class JsonVersionSource {
+  /** Human-readable provider name. */
   name;
+  /** Filename of the JSON manifest (e.g. `'package.json'`). */
   manifestFile;
+  /** Dotted key path to the version field within the JSON document. */
   versionPath;
+  /**
+   * Creates a new JSON version source.
+   *
+   * @param manifestFile - JSON manifest filename.
+   * @param versionPath - Dotted key path to the version field.
+   */
   constructor(manifestFile = "package.json", versionPath = "version") {
     this.name = manifestFile;
     this.manifestFile = manifestFile;
     this.versionPath = versionPath;
   }
+  /**
+   * Returns `true` when the manifest file exists in `cwd`.
+   *
+   * @param cwd - Project directory to check.
+   * @returns Whether the manifest file exists.
+   */
   exists(cwd) {
     return fs.existsSync(path.join(cwd, this.manifestFile));
   }
+  /**
+   * Reads the version string from the JSON manifest.
+   *
+   * @param cwd - Project directory containing the manifest.
+   * @returns The version string extracted from the manifest.
+   */
   getVersion(cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
       throw new Error(`${this.manifestFile} not found in ${cwd}`);
     }
     const content = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-    const version = getNestedValue$1(content, this.versionPath);
+    const version = getNestedValue(content, this.versionPath);
     if (typeof version !== "string" || version.length === 0) {
       throw new Error(`No version field in ${this.manifestFile}`);
     }
     return version;
   }
+  /**
+   * Writes a version string to the JSON manifest, preserving indentation.
+   *
+   * @param version - Version string to write.
+   * @param cwd - Project directory containing the manifest.
+   */
   setVersion(version, cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
       throw new Error(`${this.manifestFile} not found in ${cwd}`);
     }
-    const content = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const indentMatch = raw.match(/^(\s+)"/m);
+    const indent = indentMatch?.[1]?.length ?? 2;
+    const content = JSON.parse(raw);
     setNestedValue(content, this.versionPath, version);
-    fs.writeFileSync(filePath, `${JSON.stringify(content, null, 2)}
+    fs.writeFileSync(filePath, `${JSON.stringify(content, null, indent)}
 `, "utf-8");
   }
 }
-function getNestedValue$1(obj, dotPath) {
-  let current = obj;
-  for (const key of dotPath.split(".")) {
-    if (current === null || typeof current !== "object") {
-      return void 0;
-    }
-    current = current[key];
-  }
-  return current;
-}
-function setNestedValue(obj, dotPath, value) {
-  const keys = dotPath.split(".");
-  let current = obj;
-  for (let i = 0; i < keys.length - 1; i++) {
-    const key = keys[i];
-    if (typeof current[key] !== "object" || current[key] === null) {
-      current[key] = {};
-    }
-    current = current[key];
-  }
-  current[keys[keys.length - 1]] = value;
-}
 class RegexVersionSource {
+  /** Human-readable provider name. */
   name;
+  /** Filename of the source manifest (e.g. `'setup.py'`). */
   manifestFile;
+  /** Compiled regex used to locate the version string. */
   versionRegex;
+  /**
+   * Creates a new regex version source.
+   *
+   * @param manifestFile - Source manifest filename.
+   * @param versionRegex - Regex string with at least one capture group for the version.
+   */
   constructor(manifestFile, versionRegex) {
     this.name = manifestFile;
     this.manifestFile = manifestFile;
@@ -462,9 +814,21 @@ class RegexVersionSource {
       throw new Error(`Version regex for ${manifestFile} must contain at least one capture group`);
     }
   }
+  /**
+   * Returns `true` when the manifest file exists in `cwd`.
+   *
+   * @param cwd - Project directory to check.
+   * @returns Whether the manifest file exists.
+   */
   exists(cwd) {
     return fs.existsSync(path.join(cwd, this.manifestFile));
   }
+  /**
+   * Reads the version string from the source manifest using regex extraction.
+   *
+   * @param cwd - Project directory containing the manifest.
+   * @returns The version string captured by group 1 of the regex.
+   */
   getVersion(cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
@@ -477,6 +841,12 @@ class RegexVersionSource {
     }
     return match[1];
   }
+  /**
+   * Writes a version string to the source manifest using position-based replacement.
+   *
+   * @param version - Version string to write.
+   * @param cwd - Project directory containing the manifest.
+   */
   setVersion(version, cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
@@ -494,17 +864,38 @@ class RegexVersionSource {
   }
 }
 class TomlVersionSource {
+  /** Human-readable provider name. */
   name;
+  /** Filename of the TOML manifest (e.g. `'Cargo.toml'`). */
   manifestFile;
+  /** Dotted key path to the version field within the TOML document. */
   versionPath;
+  /**
+   * Creates a new TOML version source.
+   *
+   * @param manifestFile - TOML manifest filename.
+   * @param versionPath - Dotted key path to the version field.
+   */
   constructor(manifestFile = "Cargo.toml", versionPath = "package.version") {
     this.name = manifestFile;
     this.manifestFile = manifestFile;
     this.versionPath = versionPath;
   }
+  /**
+   * Returns `true` when the manifest file exists in `cwd`.
+   *
+   * @param cwd - Project directory to check.
+   * @returns Whether the manifest file exists.
+   */
   exists(cwd) {
     return fs.existsSync(path.join(cwd, this.manifestFile));
   }
+  /**
+   * Reads the version string from the TOML manifest.
+   *
+   * @param cwd - Project directory containing the manifest.
+   * @returns The version string extracted from the manifest.
+   */
   getVersion(cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
@@ -518,6 +909,12 @@ class TomlVersionSource {
     }
     return version;
   }
+  /**
+   * Writes a version string to the TOML manifest, preserving formatting.
+   *
+   * @param version - Version string to write.
+   * @param cwd - Project directory containing the manifest.
+   */
   setVersion(version, cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
@@ -531,6 +928,11 @@ class TomlVersionSource {
     }
     fs.writeFileSync(filePath, updated, "utf-8");
   }
+  /**
+   * Splits the dotted version path into a TOML section name and key name.
+   *
+   * @returns An object with `section` and `key` components.
+   */
   getSectionKey() {
     const parts = this.versionPath.split(".");
     if (parts.length === 1) {
@@ -542,21 +944,32 @@ class TomlVersionSource {
     };
   }
 }
-function getNestedValue(obj, dotPath) {
-  let current = obj;
-  for (const key of dotPath.split(".")) {
-    if (current === null || typeof current !== "object") {
-      return void 0;
-    }
-    current = current[key];
+function replaceTomlVersion(content, target, newVersion) {
+  const result = replaceInSection(content, target, newVersion);
+  if (result !== content) return result;
+  if (target.section) {
+    const dottedRegex = new RegExp(
+      `^(\\s*${escapeRegExp(target.section)}\\.${escapeRegExp(target.key)}\\s*=\\s*)(["'])([^"']*)(\\2)`,
+      "m"
+    );
+    const dottedResult = content.replace(dottedRegex, `$1$2${newVersion}$4`);
+    if (dottedResult !== content) return dottedResult;
   }
-  return current;
+  if (target.section) {
+    const inlineRegex = new RegExp(
+      `^(\\s*${escapeRegExp(target.section)}\\s*=\\s*\\{[^}]*${escapeRegExp(target.key)}\\s*=\\s*)(["'])([^"']*)(\\2)`,
+      "m"
+    );
+    const inlineResult = content.replace(inlineRegex, `$1$2${newVersion}$4`);
+    if (inlineResult !== content) return inlineResult;
+  }
+  return content;
 }
-function replaceTomlVersion(content, target, newVersion) {
+function replaceInSection(content, target, newVersion) {
   const lines = content.split("\n");
   const sectionHeader = target.section ? `[${target.section}]` : null;
   let inSection = sectionHeader === null;
-  const versionRegex = new RegExp(`^(\\s*${escapeRegExp$1(target.key)}\\s*=\\s*)(["'])([^"']*)(\\2)`);
+  const versionRegex = new RegExp(`^(\\s*${escapeRegExp(target.key)}\\s*=\\s*)(["'])([^"']*)(\\2)`);
   for (let i = 0; i < lines.length; i++) {
     const trimmed = lines[i].trim();
     if (sectionHeader !== null) {
@@ -579,30 +992,56 @@ function replaceTomlVersion(content, target, newVersion) {
   }
   return content;
 }
-function escapeRegExp$1(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 class VersionFileSource {
+  /** Human-readable provider name. */
   name;
+  /** Filename of the version file (e.g. `'VERSION'`). */
   manifestFile;
+  /**
+   * Creates a new plain text version file source.
+   *
+   * @param manifestFile - Version filename.
+   */
   constructor(manifestFile = "VERSION") {
     this.name = manifestFile;
     this.manifestFile = manifestFile;
   }
+  /**
+   * Returns `true` when the version file exists in `cwd`.
+   *
+   * @param cwd - Project directory to check.
+   * @returns Whether the version file exists.
+   */
   exists(cwd) {
     return fs.existsSync(path.join(cwd, this.manifestFile));
   }
+  /**
+   * Reads the version string from the plain text version file.
+   *
+   * @param cwd - Project directory containing the version file.
+   * @returns The version string from the first line of the file.
+   */
   getVersion(cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
       throw new Error(`${this.manifestFile} not found in ${cwd}`);
     }
-    const version = fs.readFileSync(filePath, "utf-8").trim();
+    const raw = fs.readFileSync(filePath, "utf-8");
+    if (raw.includes("\0")) {
+      throw new Error(`${this.manifestFile} appears to be a binary file`);
+    }
+    const version = raw.split("\n")[0].trim();
     if (version.length === 0) {
       throw new Error(`${this.manifestFile} is empty`);
     }
     return version;
   }
+  /**
+   * Writes a version string to the plain text version file.
+   *
+   * @param version - Version string to write.
+   * @param cwd - Project directory containing the version file.
+   */
   setVersion(version, cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
@@ -613,17 +1052,38 @@ class VersionFileSource {
   }
 }
 class YamlVersionSource {
+  /** Human-readable provider name. */
   name;
+  /** Filename of the YAML manifest (e.g. `'pubspec.yaml'`). */
   manifestFile;
+  /** Dotted key path to the version field within the YAML document. */
   versionKey;
+  /**
+   * Creates a new YAML version source.
+   *
+   * @param manifestFile - YAML manifest filename.
+   * @param versionKey - Dotted key path to the version field.
+   */
   constructor(manifestFile = "pubspec.yaml", versionKey = "version") {
     this.name = manifestFile;
     this.manifestFile = manifestFile;
     this.versionKey = versionKey;
   }
+  /**
+   * Returns `true` when the manifest file exists in `cwd`.
+   *
+   * @param cwd - Project directory to check.
+   * @returns Whether the manifest file exists.
+   */
   exists(cwd) {
     return fs.existsSync(path.join(cwd, this.manifestFile));
   }
+  /**
+   * Reads the version string from the YAML manifest.
+   *
+   * @param cwd - Project directory containing the manifest.
+   * @returns The version string extracted from the manifest.
+   */
   getVersion(cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
@@ -634,7 +1094,7 @@ class YamlVersionSource {
     if (!parsed || typeof parsed !== "object") {
       throw new Error(`Failed to parse ${this.manifestFile}`);
     }
-    const version = parsed[this.versionKey];
+    const version = getNestedValue(parsed, this.versionKey);
     if (typeof version !== "string" || version.length === 0) {
       if (typeof version === "number") {
         return String(version);
@@ -643,13 +1103,21 @@ class YamlVersionSource {
     }
     return version;
   }
+  /**
+   * Writes a version string to the YAML manifest, preserving formatting.
+   *
+   * @param version - Version string to write.
+   * @param cwd - Project directory containing the manifest.
+   */
   setVersion(version, cwd) {
     const filePath = path.join(cwd, this.manifestFile);
     if (!fs.existsSync(filePath)) {
       throw new Error(`${this.manifestFile} not found in ${cwd}`);
     }
+    const keyParts = this.versionKey.split(".");
+    const leafKey = keyParts[keyParts.length - 1];
     const content = fs.readFileSync(filePath, "utf-8");
-    const regex = new RegExp(`^(${escapeRegExp(this.versionKey)}:\\s*)(["']?)(.+?)\\2\\s*$`, "m");
+    const regex = new RegExp(`^(\\s*${escapeRegExp(leafKey)}:\\s*)(["']?)(.+?)\\2\\s*$`, "m");
     const updated = content.replace(regex, `$1$2${version}$2`);
     if (updated === content) {
       throw new Error(`Could not find version field to update in ${this.manifestFile}`);
@@ -657,9 +1125,6 @@ class YamlVersionSource {
     fs.writeFileSync(filePath, updated, "utf-8");
   }
 }
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 const VALID_SOURCES = /* @__PURE__ */ new Set([
   "auto",
   "package.json",
@@ -765,7 +1230,10 @@ function resolveVersionSource(config, cwd = process.cwd()) {
       return provider;
     }
   }
-  return new JsonVersionSource("package.json", "version");
+  const supported = DETECTION_TABLE.map((e) => e.file).join(", ");
+  throw new Error(
+    `No supported manifest file found in ${cwd}. Looked for: ${supported}. Set manifest.source explicitly in .versionguard.yml or create a supported manifest file.`
+  );
 }
 function detectManifests(cwd = process.cwd()) {
   const detected = [];
@@ -1059,6 +1527,169 @@ function checkHardcodedVersions(expectedVersion, config, ignorePatterns, cwd = p
   }
   return mismatches;
 }
+function getCalVerConfig(config) {
+  if (!config.versioning.calver) {
+    throw new Error('CalVer configuration is required when versioning.type is "calver"');
+  }
+  return config.versioning.calver;
+}
+function deriveTopicSlug(conceptName) {
+  return conceptName.replace(/Config$/, "").replace(/Result$/, "").replace(/Options$/, "").toLowerCase();
+}
+function isTopicConcept(name) {
+  return name.endsWith("Config") && name !== "VersionGuardConfig";
+}
+function operationMatchesTopic(op, topicSlug, conceptNames) {
+  const haystack = `${op.name} ${op.what}`.toLowerCase();
+  if (haystack.includes(topicSlug)) return true;
+  return conceptNames.some((n) => haystack.includes(n.toLowerCase()));
+}
+function createCkmEngine(manifest) {
+  const topics = deriveTopics(manifest);
+  return {
+    topics,
+    getTopicIndex: (toolName = "tool") => formatTopicIndex(topics, toolName),
+    getTopicContent: (name) => formatTopicContent(topics, name),
+    getTopicJson: (name) => buildTopicJson(topics, manifest, name),
+    getManifest: () => manifest
+  };
+}
+function deriveTopics(manifest) {
+  const topics = [];
+  for (const concept of manifest.concepts) {
+    if (!isTopicConcept(concept.name)) continue;
+    const slug = deriveTopicSlug(concept.name);
+    const conceptNames = [concept.name];
+    const relatedConcepts = manifest.concepts.filter(
+      (c) => c.name !== concept.name && (c.name.toLowerCase().includes(slug) || slug.includes(deriveTopicSlug(c.name)))
+    );
+    conceptNames.push(...relatedConcepts.map((c) => c.name));
+    const operations = manifest.operations.filter(
+      (op) => operationMatchesTopic(op, slug, conceptNames)
+    );
+    const configSchema = manifest.configSchema.filter(
+      (c) => conceptNames.some((n) => c.key?.startsWith(n))
+    );
+    const constraints = manifest.constraints.filter(
+      (c) => conceptNames.some((n) => c.enforcedBy?.includes(n)) || operations.some((o) => c.enforcedBy?.includes(o.name))
+    );
+    topics.push({
+      name: slug,
+      summary: concept.what,
+      concepts: [concept, ...relatedConcepts],
+      operations,
+      configSchema,
+      constraints
+    });
+  }
+  return topics;
+}
+function formatTopicIndex(topics, toolName) {
+  const lines = [
+    `${toolName} CKM — Codebase Knowledge Manifest`,
+    "",
+    `Usage: ${toolName} ckm [topic] [--json] [--llm]`,
+    "",
+    "Topics:"
+  ];
+  const maxName = Math.max(...topics.map((t) => t.name.length));
+  for (const topic of topics) {
+    lines.push(`  ${topic.name.padEnd(maxName + 2)}${topic.summary}`);
+  }
+  lines.push("");
+  lines.push("Flags:");
+  lines.push("  --json    Machine-readable CKM output (concepts, operations, config schema)");
+  lines.push("  --llm     Full API context for LLM agents (forge-ts llms.txt)");
+  return lines.join("\n");
+}
+function formatTopicContent(topics, topicName) {
+  const topic = topics.find((t) => t.name === topicName);
+  if (!topic) return null;
+  const lines = [`# ${topic.summary}`, ""];
+  if (topic.concepts.length > 0) {
+    lines.push("## Concepts", "");
+    for (const c of topic.concepts) {
+      lines.push(`  ${c.name} — ${c.what}`);
+      if (c.properties) {
+        for (const p of c.properties) {
+          const def = findDefault(topic.configSchema, c.name, p.name);
+          lines.push(`    ${p.name}: ${p.type}${def ? ` = ${def}` : ""}`);
+          if (p.description) {
+            lines.push(`      ${p.description}`);
+          }
+        }
+      }
+      lines.push("");
+    }
+  }
+  if (topic.operations.length > 0) {
+    lines.push("## Operations", "");
+    for (const o of topic.operations) {
+      lines.push(`  ${o.name}() — ${o.what}`);
+      if (o.inputs) {
+        for (const i of o.inputs) {
+          lines.push(`    @param ${i.name}: ${i.description}`);
+        }
+      }
+      lines.push("");
+    }
+  }
+  if (topic.configSchema.length > 0) {
+    lines.push("## Config Fields", "");
+    for (const c of topic.configSchema) {
+      lines.push(`  ${c.key}: ${c.type}${c.default ? ` = ${c.default}` : ""}`);
+      if (c.description) {
+        lines.push(`    ${c.description}`);
+      }
+    }
+    lines.push("");
+  }
+  if (topic.constraints.length > 0) {
+    lines.push("## Constraints", "");
+    for (const c of topic.constraints) {
+      lines.push(`  [${c.id}] ${c.rule}`);
+      lines.push(`    Enforced by: ${c.enforcedBy}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function findDefault(schema, conceptName, propName) {
+  return schema.find((c) => c.key === `${conceptName}.${propName}`)?.default;
+}
+function buildTopicJson(topics, manifest, topicName) {
+  if (!topicName) {
+    return {
+      topics: topics.map((t) => ({
+        name: t.name,
+        summary: t.summary,
+        concepts: t.concepts.length,
+        operations: t.operations.length,
+        configFields: t.configSchema.length,
+        constraints: t.constraints.length
+      })),
+      ckm: {
+        concepts: manifest.concepts.length,
+        operations: manifest.operations.length,
+        constraints: manifest.constraints.length,
+        workflows: manifest.workflows.length,
+        configSchema: manifest.configSchema.length
+      }
+    };
+  }
+  const topic = topics.find((t) => t.name === topicName);
+  if (!topic) {
+    return { error: `Unknown topic: ${topicName}`, topics: topics.map((t) => t.name) };
+  }
+  return {
+    topic: topic.name,
+    summary: topic.summary,
+    concepts: topic.concepts,
+    operations: topic.operations,
+    configSchema: topic.configSchema,
+    constraints: topic.constraints
+  };
+}
 const CONFIG_FILE_NAMES = [
   ".versionguard.yml",
   ".versionguard.yaml",
@@ -1068,9 +1699,14 @@ const CONFIG_FILE_NAMES = [
 const DEFAULT_CONFIG = {
   versioning: {
     type: "semver",
+    schemeRules: {
+      maxNumericSegments: 3,
+      allowedModifiers: ["dev", "alpha", "beta", "rc"]
+    },
     calver: {
       format: "YYYY.MM.PATCH",
-      preventFutureDates: true
+      preventFutureDates: true,
+      strictMutualExclusion: true
     }
   },
   manifest: {
@@ -1196,13 +1832,7 @@ function getVersionFeedback(version, config, previousVersion) {
   if (config.versioning.type === "semver") {
     return getSemVerFeedback(version, previousVersion);
   }
-  return getCalVerFeedback(version, getCalVerConfig$2(config), previousVersion);
-}
-function getCalVerConfig$2(config) {
-  if (!config.versioning.calver) {
-    throw new Error('CalVer configuration is required when versioning.type is "calver"');
-  }
-  return config.versioning.calver;
+  return getCalVerFeedback(version, getCalVerConfig(config), previousVersion);
 }
 function getSemVerFeedback(version, previousVersion) {
   const errors = [];
@@ -1218,7 +1848,7 @@ function getSemVerFeedback(version, previousVersion) {
       });
       suggestions.push({
         message: `Remove the 'v' prefix`,
-        fix: `npm version ${cleanVersion}`,
+        fix: `npx versionguard fix --version ${cleanVersion}`,
         autoFixable: true
       });
     } else if (version.split(".").length === 2) {
@@ -1228,7 +1858,7 @@ function getSemVerFeedback(version, previousVersion) {
       });
       suggestions.push({
         message: `Add patch number (e.g., ${version}.0)`,
-        fix: `npm version ${version}.0`,
+        fix: `npx versionguard fix --version ${version}.0`,
         autoFixable: true
       });
     } else if (/^\d+\.\d+\.\d+\.\d+$/.test(version)) {
@@ -1278,7 +1908,7 @@ function getSemVerFeedback(version, previousVersion) {
         });
         suggestions.push({
           message: `Version must be greater than ${previousVersion}`,
-          fix: `npm version ${increment(previousVersion, "patch")}`,
+          fix: `npx versionguard fix --version ${increment(previousVersion, "patch")}`,
           autoFixable: true
         });
       } else if (comparison === 0) {
@@ -1288,7 +1918,7 @@ function getSemVerFeedback(version, previousVersion) {
         });
         suggestions.push({
           message: `Bump the version`,
-          fix: `npm version ${increment(previousVersion, "patch")}`,
+          fix: `npx versionguard fix --version ${increment(previousVersion, "patch")}`,
           autoFixable: true
         });
       } else {
@@ -1358,21 +1988,21 @@ function getCalVerFeedback(version, calverConfig, previousVersion) {
   if (preventFutureDates && parsed.year > now.getFullYear()) {
     suggestions.push({
       message: `Use current year (${now.getFullYear()}) or a past year`,
-      fix: `npm version ${formatCalVerVersion({ ...parsed, year: now.getFullYear() })}`,
+      fix: `npx versionguard fix --version ${formatCalVerVersion({ ...parsed, year: now.getFullYear() })}`,
       autoFixable: true
     });
   }
   if (preventFutureDates && parsed.year === now.getFullYear() && parsed.month > now.getMonth() + 1) {
     suggestions.push({
       message: `Current month is ${now.getMonth() + 1}`,
-      fix: `npm version ${formatCalVerVersion({ ...parsed, month: now.getMonth() + 1 })}`,
+      fix: `npx versionguard fix --version ${formatCalVerVersion({ ...parsed, month: now.getMonth() + 1 })}`,
       autoFixable: true
     });
   }
   if (preventFutureDates && parsed.year === now.getFullYear() && parsed.month === now.getMonth() + 1 && parsed.day !== void 0 && parsed.day > now.getDate()) {
     suggestions.push({
       message: `Current day is ${now.getDate()}`,
-      fix: `npm version ${formatCalVerVersion({ ...parsed, day: now.getDate() })}`,
+      fix: `npx versionguard fix --version ${formatCalVerVersion({ ...parsed, day: now.getDate() })}`,
       autoFixable: true
     });
   }
@@ -1386,7 +2016,7 @@ function getCalVerFeedback(version, calverConfig, previousVersion) {
         });
         suggestions.push({
           message: `CalVer must increase over time`,
-          fix: `npm version ${increment$1(previousVersion, format2)}`,
+          fix: `npx versionguard fix --version ${increment$1(previousVersion, format2)}`,
           autoFixable: true
         });
       }
@@ -1566,6 +2196,17 @@ function fixAll(config, targetVersion, cwd = process.cwd()) {
   const syncResults = fixSyncIssues(config, cwd);
   results.push(...syncResults);
   if (config.changelog.enabled) {
+    const changelogPath = path.join(cwd, config.changelog.file);
+    if (isChangesetMangled(changelogPath)) {
+      const fixed = fixChangesetMangling(changelogPath);
+      if (fixed) {
+        results.push({
+          fixed: true,
+          message: `Restructured ${config.changelog.file} from Changesets format to Keep a Changelog`,
+          file: changelogPath
+        });
+      }
+    }
     const changelogResult = fixChangelog(version, config, cwd);
     if (changelogResult.fixed) {
       results.push(changelogResult);
@@ -1595,7 +2236,7 @@ function suggestNextVersion(currentVersion, config, changeType) {
       });
     }
   } else {
-    const format2 = getCalVerConfig$1(config).format;
+    const format2 = getCalVerConfig(config).format;
     const currentCal = getCurrentVersion(format2);
     suggestions.push({
       version: currentCal,
@@ -1608,12 +2249,6 @@ function suggestNextVersion(currentVersion, config, changeType) {
   }
   return suggestions;
 }
-function getCalVerConfig$1(config) {
-  if (!config.versioning.calver) {
-    throw new Error('CalVer configuration is required when versioning.type is "calver"');
-  }
-  return config.versioning.calver;
-}
 const HOOK_NAMES = ["pre-commit", "pre-push", "post-tag"];
 function checkHooksPathOverride(cwd) {
   try {
@@ -1730,6 +2365,92 @@ function runGuardChecks(config, cwd) {
     warnings
   };
 }
+const PROJECT_MARKERS = [
+  ".versionguard.yml",
+  ".versionguard.yaml",
+  "versionguard.yml",
+  "versionguard.yaml",
+  ".git",
+  "package.json",
+  "Cargo.toml",
+  "pyproject.toml",
+  "pubspec.yaml",
+  "composer.json",
+  "pom.xml",
+  "go.mod",
+  "mix.exs",
+  "Gemfile",
+  ".csproj"
+];
+function findProjectRoot(startDir) {
+  let current = path.resolve(startDir);
+  while (true) {
+    for (const marker of PROJECT_MARKERS) {
+      if (marker.startsWith(".") && marker !== ".git" && !marker.startsWith(".version")) {
+        try {
+          const files = fs.readdirSync(current);
+          if (files.some((f) => f.endsWith(marker))) {
+            return buildResult(current, marker);
+          }
+        } catch {
+        }
+      } else if (fs.existsSync(path.join(current, marker))) {
+        return buildResult(current, marker);
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return {
+        found: false,
+        root: path.resolve(startDir),
+        hasConfig: false,
+        hasGit: false,
+        hasManifest: false
+      };
+    }
+    current = parent;
+  }
+}
+function buildResult(root, marker) {
+  const configNames = [
+    ".versionguard.yml",
+    ".versionguard.yaml",
+    "versionguard.yml",
+    "versionguard.yaml"
+  ];
+  return {
+    found: true,
+    root,
+    marker,
+    hasConfig: configNames.some((c) => fs.existsSync(path.join(root, c))),
+    hasGit: fs.existsSync(path.join(root, ".git")),
+    hasManifest: [
+      "package.json",
+      "Cargo.toml",
+      "pyproject.toml",
+      "pubspec.yaml",
+      "composer.json",
+      "pom.xml",
+      "VERSION"
+    ].some((m) => fs.existsSync(path.join(root, m)))
+  };
+}
+function formatNotProjectError(cwd, command) {
+  const dir = path.basename(cwd) || cwd;
+  const lines = [
+    `Not a VersionGuard project: ${dir}`,
+    "",
+    "No .versionguard.yml, .git directory, or manifest file found.",
+    "",
+    "To get started:",
+    "  versionguard init          Set up a new project interactively",
+    "  versionguard init --yes    Set up with defaults",
+    "",
+    "Or run from a project root directory:",
+    `  cd /path/to/project && versionguard ${command}`
+  ];
+  return lines.join("\n");
+}
 function runGit(cwd, args, encoding) {
   return childProcess.execFileSync("git", args, {
     cwd,
@@ -1897,7 +2618,8 @@ function getTagPreflightError(config, cwd, expectedVersion, allowAutoFix = false
   const versionResult = config.versioning.type === "semver" ? validate$1(version) : validate$2(
     version,
     config.versioning.calver?.format ?? "YYYY.MM.PATCH",
-    config.versioning.calver?.preventFutureDates ?? true
+    config.versioning.calver?.preventFutureDates ?? true,
+    config.versioning.schemeRules
   );
   if (!versionResult.valid) {
     return versionResult.errors[0]?.message ?? `Invalid version: ${version}`;
@@ -1981,7 +2703,12 @@ function validateVersion(version, config) {
     return validate$1(version);
   }
   const calverConfig = getCalVerConfig(config);
-  return validate$2(version, calverConfig.format, calverConfig.preventFutureDates);
+  return validate$2(
+    version,
+    calverConfig.format,
+    calverConfig.preventFutureDates,
+    config.versioning.schemeRules
+  );
 }
 function validate(config, cwd = process.cwd()) {
   const errors = [];
@@ -2093,12 +2820,6 @@ function canBump(currentVersion, newVersion, config) {
   }
   return { canBump: true };
 }
-function getCalVerConfig(config) {
-  if (!config.versioning.calver) {
-    throw new Error('CalVer configuration is required when versioning.type is "calver"');
-  }
-  return config.versioning.calver;
-}
 function isWorktreeClean(cwd) {
   try {
     return execSync("git status --porcelain", { cwd, encoding: "utf-8" }).trim().length === 0;
@@ -2107,51 +2828,58 @@ function isWorktreeClean(cwd) {
   }
 }
 export {
-  fixChangelog as A,
-  fixPackageVersion as B,
-  getAllTags as C,
-  getLatestTag as D,
-  getTagFeedback as E,
-  getVersionSource as F,
+  checkHardcodedVersions as A,
+  checkHookIntegrity as B,
+  checkHooksPathOverride as C,
+  checkHuskyBypass as D,
+  detectManifests as E,
+  fixChangelog as F,
   GitTagSource as G,
-  resolveVersionSource as H,
-  semver as I,
+  fixPackageVersion as H,
+  getAllTags as I,
   JsonVersionSource as J,
-  suggestTagMessage as K,
-  sync as L,
-  syncVersion as M,
-  validateChangelog as N,
-  validateTagForPush as O,
-  validateVersion as P,
+  getCalVerConfig as K,
+  getLatestTag as L,
+  getTagFeedback as M,
+  getVersionSource as N,
+  initConfig as O,
+  resolveVersionSource as P,
+  semver as Q,
   RegexVersionSource as R,
+  suggestTagMessage as S,
   TomlVersionSource as T,
+  sync as U,
   VersionFileSource as V,
+  syncVersion as W,
+  validateChangelog as X,
   YamlVersionSource as Y,
+  validateTagForPush as Z,
+  validateVersion as _,
   installHooks as a,
   getPackageVersion as b,
-  getVersionFeedback as c,
-  getSyncFeedback as d,
-  getChangelogFeedback as e,
-  doctor as f,
+  createCkmEngine as c,
+  getVersionFeedback as d,
+  getSyncFeedback as e,
+  getChangelogFeedback as f,
   getConfig as g,
   handlePostTag as h,
-  initConfig as i,
-  fixAll as j,
-  fixSyncIssues as k,
-  setPackageVersion as l,
-  createTag as m,
-  areHooksInstalled as n,
-  calver as o,
-  canBump as p,
-  checkEnforceHooksPolicy as q,
+  isValidCalVerFormat as i,
+  doctor as j,
+  fixAll as k,
+  isChangesetMangled as l,
+  fixChangesetMangling as m,
+  fixSyncIssues as n,
+  setPackageVersion as o,
+  createTag as p,
+  areHooksInstalled as q,
   runGuardChecks as r,
   suggestNextVersion as s,
-  checkHardcodedVersions as t,
+  findProjectRoot as t,
   uninstallHooks as u,
   validate as v,
-  checkHookIntegrity as w,
-  checkHooksPathOverride as x,
-  checkHuskyBypass as y,
-  detectManifests as z
+  formatNotProjectError as w,
+  calver as x,
+  canBump as y,
+  checkEnforceHooksPolicy as z
 };
-//# sourceMappingURL=index-BrZJDWya.js.map
+//# sourceMappingURL=index-CwOyEn5L.js.map