@codluv/versionguard 0.4.0 → 0.5.0

package/dist/calver.d.ts

@@ -154,6 +154,7 @@ export declare function parse(version: string, calverFormat: CalVerFormat): CalV
  * @param version - Version string to validate.
  * @param calverFormat - Format expected for the version string.
  * @param preventFutureDates - Whether future dates should be reported as errors.
+ * @param schemeRules - Optional scheme rules for modifier validation and segment count warnings.
  * @returns A validation result containing any discovered errors and the parsed version on success.
  *
  * @example

package/dist/calver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calver.d.ts","sourceRoot":"","sources":["../src/calver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,YAAY,EAEZ,WAAW,EAEX,gBAAgB,EACjB,MAAM,SAAS,CAAC;AA8BjB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,IAAI,YAAY,CAoBhF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAE3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAE1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEnB;;;;OAIG;IACH,GAAG,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAExB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,YAAY,GAAG,kBAAkB,CAoB1E;AAyCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAKpE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAqDhF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,kBAAkB,GAAE,OAAc,EAClC,WAAW,CAAC,EAAE,WAAW,GACxB,gBAAgB,CA6GlB;AAgBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAsB9C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAY5F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAiBhF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAqB7E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAE5F"}
+{"version":3,"file":"calver.d.ts","sourceRoot":"","sources":["../src/calver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,YAAY,EAEZ,WAAW,EAEX,gBAAgB,EACjB,MAAM,SAAS,CAAC;AA8BjB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,IAAI,YAAY,CAoBhF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAE3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAE1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEnB;;;;OAIG;IACH,GAAG,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAExB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,YAAY,GAAG,kBAAkB,CAoB1E;AAyCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAKpE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAqDhF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,kBAAkB,GAAE,OAAc,EAClC,WAAW,CAAC,EAAE,WAAW,GACxB,gBAAgB,CA6GlB;AAgBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAsB9C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAY5F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAiBhF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAqB7E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAE5F"}

package/dist/changelog.d.ts

@@ -80,4 +80,56 @@ export declare function getLatestVersion(changelogPath: string): string | null;
  * ```
  */
 export declare function addVersionEntry(changelogPath: string, version: string, date?: string): void;
+/**
+ * Detects whether a changelog has been mangled by Changesets.
+ *
+ * @remarks
+ * Changesets prepends version content above the Keep a Changelog preamble,
+ * producing `## 0.4.0` (no brackets, no date) before the "All notable changes"
+ * paragraph. This function detects that pattern.
+ *
+ * @param changelogPath - Path to the changelog file.
+ * @returns `true` when the changelog appears to be mangled by Changesets.
+ *
+ * @example
+ * ```ts
+ * import { isChangesetMangled } from 'versionguard';
+ *
+ * if (isChangesetMangled('CHANGELOG.md')) {
+ *   fixChangesetMangling('CHANGELOG.md');
+ * }
+ * ```
+ *
+ * @public
+ * @since 0.4.0
+ */
+export declare function isChangesetMangled(changelogPath: string): boolean;
+/**
+ * Fixes a Changesets-mangled changelog into proper Keep a Changelog format.
+ *
+ * @remarks
+ * This function:
+ * 1. Extracts the version number and content prepended by Changesets
+ * 2. Converts Changesets section names (Minor Changes, Patch Changes) to
+ *    Keep a Changelog names (Added, Fixed)
+ * 3. Strips commit hashes from entry lines
+ * 4. Adds the date and brackets to the version header
+ * 5. Inserts the entry after `## [Unreleased]` in the correct position
+ * 6. Restores the preamble to its proper location
+ *
+ * @param changelogPath - Path to the changelog file to fix.
+ * @param date - Release date in `YYYY-MM-DD` format.
+ * @returns `true` when the file was modified, `false` when no fix was needed.
+ *
+ * @example
+ * ```ts
+ * import { fixChangesetMangling } from 'versionguard';
+ *
+ * const fixed = fixChangesetMangling('CHANGELOG.md');
+ * ```
+ *
+ * @public
+ * @since 0.4.0
+ */
+export declare function fixChangesetMangling(changelogPath: string, date?: string): boolean;
 //# sourceMappingURL=changelog.d.ts.map

package/dist/changelog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../src/changelog.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;OAEG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAc,EACtB,YAAY,GAAE,OAAc,GAC3B,yBAAyB,CAgD3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQrE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAA8C,GACnD,IAAI,CAmBN"}
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../src/changelog.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;OAEG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAc,EACtB,YAAY,GAAE,OAAc,GAC3B,yBAAyB,CAgD3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQrE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAA8C,GACnD,IAAI,CAmBN;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAMjE;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,MAA8C,GACnD,OAAO,CAoET"}

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

@@ -381,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 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) {
@@ -395,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
+        });
+      }
     }
   }
 }
@@ -407,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);
     }
   }
@@ -436,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
@@ -448,8 +589,36 @@ 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";
@@ -1364,6 +1533,163 @@ function getCalVerConfig(config) {
   }
   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",
@@ -1870,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);
@@ -2028,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,
@@ -2405,53 +2828,58 @@ function isWorktreeClean(cwd) {
   }
 }
 export {
-  fixChangelog as A,
-  fixPackageVersion as B,
-  getAllTags as C,
-  getCalVerConfig as D,
-  getLatestTag as E,
-  getTagFeedback as F,
+  checkHardcodedVersions as A,
+  checkHookIntegrity as B,
+  checkHooksPathOverride as C,
+  checkHuskyBypass as D,
+  detectManifests as E,
+  fixChangelog as F,
   GitTagSource as G,
-  getVersionSource as H,
-  initConfig as I,
+  fixPackageVersion as H,
+  getAllTags as I,
   JsonVersionSource as J,
-  resolveVersionSource as K,
-  semver as L,
-  suggestTagMessage as M,
-  sync as N,
-  syncVersion as O,
-  validateChangelog as P,
-  validateTagForPush as Q,
+  getCalVerConfig as K,
+  getLatestTag as L,
+  getTagFeedback as M,
+  getVersionSource as N,
+  initConfig as O,
+  resolveVersionSource as P,
+  semver as Q,
   RegexVersionSource as R,
-  validateVersion as S,
+  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,
   isValidCalVerFormat 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,
+  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-B3R60bYJ.js.map
+//# sourceMappingURL=index-CwOyEn5L.js.map