@codluv/versionguard 0.4.0 → 0.5.0

package/dist/cli.js

@@ -4,9 +4,1020 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import { Command } from "commander";
-import { i as isValidCalVerFormat, g as getConfig, a as installHooks, b as getPackageVersion, c as getVersionFeedback, v as validate, h as handlePostTag, r as runGuardChecks, d as getSyncFeedback, e as getChangelogFeedback, f as doctor, j as fixAll, k as fixSyncIssues, s as suggestNextVersion, l as setPackageVersion, m as createTag, u as uninstallHooks, n as areHooksInstalled } from "./chunks/index-B3R60bYJ.js";
+import { i as isValidCalVerFormat, c as createCkmEngine, g as getConfig, a as installHooks, b as getPackageVersion, d as getVersionFeedback, v as validate, h as handlePostTag, r as runGuardChecks, e as getSyncFeedback, f as getChangelogFeedback, j as doctor, k as fixAll, l as isChangesetMangled, m as fixChangesetMangling, n as fixSyncIssues, s as suggestNextVersion, o as setPackageVersion, p as createTag, u as uninstallHooks, q as areHooksInstalled, t as findProjectRoot, w as formatNotProjectError } from "./chunks/index-CwOyEn5L.js";
 import * as p from "@clack/prompts";
 import * as yaml from "js-yaml";
+const ckmRaw = `{
+  "$schema": "https://forge-ts.dev/schemas/ckm/v1.json",
+  "version": "1.0.0",
+  "project": "@codluv/versionguard",
+  "generated": "2026-03-26T15:45:30.788Z",
+  "concepts": [
+    {
+      "id": "concept-ManifestConfig",
+      "name": "ManifestConfig",
+      "what": "Configures the version source manifest.",
+      "properties": [
+        {
+          "name": "source",
+          "type": "ManifestSourceType",
+          "description": "Manifest file to read the version from.  Use \`'auto'\` for file-existence detection or a specific filename."
+        },
+        {
+          "name": "path",
+          "type": "string | undefined",
+          "description": "Dotted key path to the version field within the manifest.  For example \`'version'\` for package.json, \`'package.version'\` for Cargo.toml, or \`'project.version'\` for pyproject.toml."
+        },
+        {
+          "name": "regex",
+          "type": "string | undefined",
+          "description": "Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string."
+        }
+      ]
+    },
+    {
+      "id": "concept-CalVerConfig",
+      "name": "CalVerConfig",
+      "what": "Configures CalVer validation rules.",
+      "properties": [
+        {
+          "name": "format",
+          "type": "CalVerFormat",
+          "description": "Calendar format used when parsing and validating versions."
+        },
+        {
+          "name": "preventFutureDates",
+          "type": "boolean",
+          "description": "Rejects versions that point to a future date."
+        },
+        {
+          "name": "strictMutualExclusion",
+          "type": "boolean | undefined",
+          "description": "Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens."
+        }
+      ]
+    },
+    {
+      "id": "concept-SyncConfig",
+      "name": "SyncConfig",
+      "what": "Configures files and patterns that should stay in sync with the canonical version.",
+      "properties": [
+        {
+          "name": "files",
+          "type": "string[]",
+          "description": "File globs or paths that should be scanned for version updates."
+        },
+        {
+          "name": "patterns",
+          "type": "SyncPattern[]",
+          "description": "Replacement patterns applied to matching files."
+        }
+      ]
+    },
+    {
+      "id": "concept-ChangelogConfig",
+      "name": "ChangelogConfig",
+      "what": "Controls changelog validation behavior.",
+      "properties": [
+        {
+          "name": "enabled",
+          "type": "boolean",
+          "description": "Enables changelog validation."
+        },
+        {
+          "name": "file",
+          "type": "string",
+          "description": "Path to the changelog file to inspect."
+        },
+        {
+          "name": "strict",
+          "type": "boolean",
+          "description": "Treats changelog problems as hard failures."
+        },
+        {
+          "name": "requireEntry",
+          "type": "boolean",
+          "description": "Requires an entry for the current version."
+        }
+      ]
+    },
+    {
+      "id": "concept-GitHooksConfig",
+      "name": "GitHooksConfig",
+      "what": "Toggles each supported git hook integration.",
+      "properties": [
+        {
+          "name": "'pre-commit'",
+          "type": "boolean",
+          "description": "Enables validation during the \`pre-commit\` hook."
+        },
+        {
+          "name": "'pre-push'",
+          "type": "boolean",
+          "description": "Enables validation during the \`pre-push\` hook."
+        },
+        {
+          "name": "'post-tag'",
+          "type": "boolean",
+          "description": "Enables follow-up tasks after a tag is created."
+        }
+      ]
+    },
+    {
+      "id": "concept-GitConfig",
+      "name": "GitConfig",
+      "what": "Configures git-related enforcement.",
+      "properties": [
+        {
+          "name": "hooks",
+          "type": "GitHooksConfig",
+          "description": "Hook toggles used by the CLI and validation workflow."
+        },
+        {
+          "name": "enforceHooks",
+          "type": "boolean",
+          "description": "Fails validation when required hooks are missing."
+        }
+      ]
+    },
+    {
+      "id": "concept-VersioningConfig",
+      "name": "VersioningConfig",
+      "what": "Configures the active versioning mode.",
+      "properties": [
+        {
+          "name": "type",
+          "type": "VersioningType",
+          "description": "Versioning strategy used for the project."
+        },
+        {
+          "name": "schemeRules",
+          "type": "SchemeRules | undefined",
+          "description": "Scheme-level validation rules applied regardless of versioning type."
+        },
+        {
+          "name": "calver",
+          "type": "CalVerConfig | undefined",
+          "description": "CalVer-specific settings when \`type\` is \`'calver'\`."
+        }
+      ]
+    },
+    {
+      "id": "concept-VersionGuardConfig",
+      "name": "VersionGuardConfig",
+      "what": "Top-level configuration consumed by versionguard.",
+      "properties": [
+        {
+          "name": "versioning",
+          "type": "VersioningConfig",
+          "description": "Active versioning settings."
+        },
+        {
+          "name": "manifest",
+          "type": "ManifestConfig",
+          "description": "Version source manifest settings."
+        },
+        {
+          "name": "sync",
+          "type": "SyncConfig",
+          "description": "Synchronization settings for mirrored version strings."
+        },
+        {
+          "name": "changelog",
+          "type": "ChangelogConfig",
+          "description": "Changelog validation settings."
+        },
+        {
+          "name": "git",
+          "type": "GitConfig",
+          "description": "Git enforcement settings."
+        },
+        {
+          "name": "ignore",
+          "type": "string[]",
+          "description": "Files or patterns excluded from validation."
+        }
+      ]
+    },
+    {
+      "id": "concept-ValidationResult",
+      "name": "ValidationResult",
+      "what": "Result returned by version parsing and validation helpers.",
+      "properties": [
+        {
+          "name": "valid",
+          "type": "boolean",
+          "description": "Indicates whether validation completed without errors."
+        },
+        {
+          "name": "errors",
+          "type": "ValidationError[]",
+          "description": "Collected validation issues."
+        },
+        {
+          "name": "version",
+          "type": "ParsedVersion | undefined",
+          "description": "Parsed version details when validation succeeds."
+        }
+      ]
+    },
+    {
+      "id": "concept-SyncResult",
+      "name": "SyncResult",
+      "what": "Reports the result of synchronizing a single file.",
+      "properties": [
+        {
+          "name": "file",
+          "type": "string",
+          "description": "File that was inspected or updated."
+        },
+        {
+          "name": "updated",
+          "type": "boolean",
+          "description": "Indicates whether the file content changed."
+        },
+        {
+          "name": "changes",
+          "type": "SyncChange[]",
+          "description": "Detailed replacements applied within the file."
+        }
+      ]
+    },
+    {
+      "id": "concept-FullValidationResult",
+      "name": "FullValidationResult",
+      "what": "Combined result from a full project validation run.",
+      "properties": [
+        {
+          "name": "valid",
+          "type": "boolean",
+          "description": "Indicates whether all checks passed."
+        },
+        {
+          "name": "version",
+          "type": "string",
+          "description": "Canonical version string used for validation."
+        },
+        {
+          "name": "versionValid",
+          "type": "boolean",
+          "description": "Indicates whether the root version string is valid."
+        },
+        {
+          "name": "syncValid",
+          "type": "boolean",
+          "description": "Indicates whether synchronized files are in sync."
+        },
+        {
+          "name": "changelogValid",
+          "type": "boolean",
+          "description": "Indicates whether changelog checks passed."
+        },
+        {
+          "name": "errors",
+          "type": "string[]",
+          "description": "Human-readable validation failures collected during the run."
+        }
+      ]
+    },
+    {
+      "id": "concept-ChangelogValidationResult",
+      "name": "ChangelogValidationResult",
+      "what": "Describes the outcome of validating a changelog file.",
+      "properties": [
+        {
+          "name": "valid",
+          "type": "boolean",
+          "description": "Indicates whether the changelog satisfies all requested checks."
+        },
+        {
+          "name": "errors",
+          "type": "string[]",
+          "description": "Human-readable validation errors."
+        },
+        {
+          "name": "hasEntryForVersion",
+          "type": "boolean",
+          "description": "Indicates whether the changelog contains an entry for the requested version."
+        }
+      ]
+    },
+    {
+      "id": "concept-FeedbackResult",
+      "name": "FeedbackResult",
+      "what": "Aggregates validation errors with suggested next steps.",
+      "properties": [
+        {
+          "name": "valid",
+          "type": "boolean",
+          "description": "Indicates whether the inspected version state is valid."
+        },
+        {
+          "name": "errors",
+          "type": "ValidationError[]",
+          "description": "Validation errors collected during the check."
+        },
+        {
+          "name": "suggestions",
+          "type": "Suggestion[]",
+          "description": "Suggested next steps for resolving the reported issues."
+        },
+        {
+          "name": "canAutoFix",
+          "type": "boolean",
+          "description": "Indicates whether at least one suggestion can be auto-applied."
+        }
+      ]
+    },
+    {
+      "id": "concept-FixResult",
+      "name": "FixResult",
+      "what": "Fix entry point exports for auto-remediation helpers.",
+      "properties": [
+        {
+          "name": "fixed",
+          "type": "boolean",
+          "description": "Indicates whether the operation changed repository state."
+        },
+        {
+          "name": "message",
+          "type": "string",
+          "description": "Human-readable description of the fix attempt."
+        },
+        {
+          "name": "file",
+          "type": "string | undefined",
+          "description": "Absolute path to the file that was updated, when applicable."
+        }
+      ]
+    },
+    {
+      "id": "concept-ProjectRootResult",
+      "name": "ProjectRootResult",
+      "what": "Result of project root detection.",
+      "properties": [
+        {
+          "name": "found",
+          "type": "boolean",
+          "description": "Whether a project root was found."
+        },
+        {
+          "name": "root",
+          "type": "string",
+          "description": "The resolved project root directory, or the original cwd if not found."
+        },
+        {
+          "name": "marker",
+          "type": "string | undefined",
+          "description": "Which marker file was found."
+        },
+        {
+          "name": "hasConfig",
+          "type": "boolean",
+          "description": "Whether the directory has a VersionGuard config."
+        },
+        {
+          "name": "hasGit",
+          "type": "boolean",
+          "description": "Whether the directory is inside a git repository."
+        },
+        {
+          "name": "hasManifest",
+          "type": "boolean",
+          "description": "Whether a version manifest file exists."
+        }
+      ]
+    },
+    {
+      "id": "concept-InitOptions",
+      "name": "InitOptions",
+      "what": "Options for headless (non-interactive) initialization.",
+      "properties": [
+        {
+          "name": "cwd",
+          "type": "string",
+          "description": "Working directory path."
+        },
+        {
+          "name": "type",
+          "type": "\\"semver\\" | \\"calver\\" | undefined",
+          "description": "Versioning type (semver or calver)."
+        },
+        {
+          "name": "format",
+          "type": "string | undefined",
+          "description": "CalVer format string."
+        },
+        {
+          "name": "manifest",
+          "type": "string | undefined",
+          "description": "Manifest source type."
+        },
+        {
+          "name": "hooks",
+          "type": "boolean | undefined",
+          "description": "Whether to install git hooks."
+        },
+        {
+          "name": "changelog",
+          "type": "boolean | undefined",
+          "description": "Whether to enable changelog validation."
+        },
+        {
+          "name": "yes",
+          "type": "boolean | undefined",
+          "description": "Accept defaults without prompting."
+        },
+        {
+          "name": "force",
+          "type": "boolean | undefined",
+          "description": "Overwrite existing config."
+        }
+      ]
+    }
+  ],
+  "operations": [
+    {
+      "id": "op-validate",
+      "name": "validate",
+      "what": "Validates a CalVer string against formatting and date rules.",
+      "inputs": [
+        {
+          "name": "version",
+          "type": "unknown",
+          "required": true,
+          "description": "Version string to validate."
+        },
+        {
+          "name": "calverFormat",
+          "type": "unknown",
+          "required": true,
+          "description": "Format expected for the version string."
+        },
+        {
+          "name": "preventFutureDates",
+          "type": "unknown",
+          "required": true,
+          "description": "Whether future dates should be reported as errors."
+        },
+        {
+          "name": "schemeRules",
+          "type": "unknown",
+          "required": true,
+          "description": "Optional scheme rules for modifier validation and segment count warnings."
+        }
+      ],
+      "outputs": {
+        "text": "A validation result containing any discovered errors and the parsed version on success."
+      }
+    },
+    {
+      "id": "op-validateChangelog",
+      "name": "validateChangelog",
+      "what": "Validates a changelog file for release readiness.",
+      "inputs": [
+        {
+          "name": "changelogPath",
+          "type": "unknown",
+          "required": true,
+          "description": "Path to the changelog file."
+        },
+        {
+          "name": "version",
+          "type": "unknown",
+          "required": true,
+          "description": "Version that must be present in the changelog."
+        },
+        {
+          "name": "strict",
+          "type": "unknown",
+          "required": true,
+          "description": "Whether to require compare links and dated release headings."
+        },
+        {
+          "name": "requireEntry",
+          "type": "unknown",
+          "required": true,
+          "description": "Whether the requested version must already have an entry."
+        }
+      ],
+      "outputs": {
+        "text": "The result of validating the changelog file."
+      }
+    },
+    {
+      "id": "op-checkHardcodedVersions",
+      "name": "checkHardcodedVersions",
+      "what": "Checks configured files for hardcoded version mismatches.",
+      "inputs": [
+        {
+          "name": "expectedVersion",
+          "type": "unknown",
+          "required": true,
+          "description": "Version all matching entries should use."
+        },
+        {
+          "name": "config",
+          "type": "unknown",
+          "required": true,
+          "description": "Sync configuration describing files and replacement patterns."
+        },
+        {
+          "name": "ignorePatterns",
+          "type": "unknown",
+          "required": true,
+          "description": "Glob patterns to exclude while scanning."
+        },
+        {
+          "name": "cwd",
+          "type": "unknown",
+          "required": true,
+          "description": "Project directory used to resolve file globs."
+        }
+      ],
+      "outputs": {
+        "text": "A list of detected version mismatches."
+      }
+    },
+    {
+      "id": "op-generateHookScript",
+      "name": "generateHookScript",
+      "what": "Generates the shell script content for a Git hook.",
+      "inputs": [
+        {
+          "name": "hookName",
+          "type": "unknown",
+          "required": true,
+          "description": "Name of the Git hook to generate."
+        }
+      ],
+      "outputs": {
+        "text": "Executable shell script contents for the hook."
+      }
+    },
+    {
+      "id": "op-checkHooksPathOverride",
+      "name": "checkHooksPathOverride",
+      "what": "Checks whether git hooks have been redirected away from the repository.",
+      "inputs": [
+        {
+          "name": "cwd",
+          "type": "unknown",
+          "required": true,
+          "description": "Repository directory to inspect."
+        }
+      ],
+      "outputs": {
+        "text": "A guard warning when a hooksPath override is detected."
+      }
+    },
+    {
+      "id": "op-checkHuskyBypass",
+      "name": "checkHuskyBypass",
+      "what": "Checks whether the HUSKY environment variable is disabling hooks.",
+      "inputs": [],
+      "outputs": {
+        "text": "A guard warning when the HUSKY bypass is detected."
+      }
+    },
+    {
+      "id": "op-checkHookIntegrity",
+      "name": "checkHookIntegrity",
+      "what": "Verifies that installed hook scripts match the expected content.",
+      "inputs": [
+        {
+          "name": "config",
+          "type": "unknown",
+          "required": true,
+          "description": "VersionGuard configuration that defines which hooks should exist."
+        },
+        {
+          "name": "cwd",
+          "type": "unknown",
+          "required": true,
+          "description": "Repository directory to inspect."
+        }
+      ],
+      "outputs": {
+        "text": "Guard warnings for each hook that has been tampered with."
+      }
+    },
+    {
+      "id": "op-checkEnforceHooksPolicy",
+      "name": "checkEnforceHooksPolicy",
+      "what": "Checks whether hooks are configured as required but not enforced.",
+      "inputs": [
+        {
+          "name": "config",
+          "type": "unknown",
+          "required": true,
+          "description": "VersionGuard configuration to inspect."
+        }
+      ],
+      "outputs": {
+        "text": "A guard warning when hooks are enabled but not enforced."
+      }
+    },
+    {
+      "id": "op-runGuardChecks",
+      "name": "runGuardChecks",
+      "what": "Runs all guard checks and returns a consolidated report.",
+      "inputs": [
+        {
+          "name": "config",
+          "type": "unknown",
+          "required": true,
+          "description": "VersionGuard configuration."
+        },
+        {
+          "name": "cwd",
+          "type": "unknown",
+          "required": true,
+          "description": "Repository directory to inspect."
+        }
+      ],
+      "outputs": {
+        "text": "A guard report with all findings."
+      }
+    },
+    {
+      "id": "op-initConfig",
+      "name": "initConfig",
+      "what": "Initializes a new VersionGuard config file in a project.",
+      "inputs": [
+        {
+          "name": "cwd",
+          "type": "unknown",
+          "required": true,
+          "description": "Project directory where the config should be created."
+        }
+      ],
+      "outputs": {
+        "text": "The path to the created config file."
+      }
+    },
+    {
+      "id": "op-createTag",
+      "name": "createTag",
+      "what": "Creates a release tag and optionally fixes version state first.",
+      "inputs": [
+        {
+          "name": "version",
+          "type": "unknown",
+          "required": true,
+          "description": "Version to embed in the new tag name."
+        },
+        {
+          "name": "message",
+          "type": "unknown",
+          "required": true,
+          "description": "Custom annotated tag message."
+        },
+        {
+          "name": "autoFix",
+          "type": "unknown",
+          "required": true,
+          "description": "Whether to auto-fix version mismatches before tagging."
+        },
+        {
+          "name": "config",
+          "type": "unknown",
+          "required": true,
+          "description": "Loaded VersionGuard configuration used for validation and fixes."
+        },
+        {
+          "name": "cwd",
+          "type": "unknown",
+          "required": true,
+          "description": "Repository directory where git commands should run."
+        }
+      ],
+      "outputs": {
+        "text": "The tagging outcome and any actions performed along the way."
+      }
+    },
+    {
+      "id": "op-validateTagForPush",
+      "name": "validateTagForPush",
+      "what": "Validates that a local tag is safe to push to the default remote.",
+      "inputs": [
+        {
+          "name": "tagName",
+          "type": "unknown",
+          "required": true,
+          "description": "Name of the tag to validate."
+        },
+        {
+          "name": "cwd",
+          "type": "unknown",
+          "required": true,
+          "description": "Repository directory where git commands should run."
+        }
+      ],
+      "outputs": {
+        "text": "A validation result with an optional suggested fix command."
+      }
+    },
+    {
+      "id": "op-validateVersion",
+      "name": "validateVersion",
+      "what": "Validates a version string against the active versioning strategy.",
+      "inputs": [
+        {
+          "name": "version",
+          "type": "unknown",
+          "required": true,
+          "description": "Version string to validate."
+        },
+        {
+          "name": "config",
+          "type": "unknown",
+          "required": true,
+          "description": "VersionGuard configuration that selects the validation rules."
+        }
+      ],
+      "outputs": {
+        "text": "The validation result for the provided version."
+      }
+    },
+    {
+      "id": "op-runWizard",
+      "name": "runWizard",
+      "what": "Runs the interactive setup wizard.",
+      "inputs": [
+        {
+          "name": "cwd",
+          "type": "unknown",
+          "required": true,
+          "description": "Project directory to initialize."
+        }
+      ],
+      "outputs": {
+        "text": "The path to the created config file, or \`null\` if cancelled."
+      }
+    },
+    {
+      "id": "op-runHeadless",
+      "name": "runHeadless",
+      "what": "Initializes VersionGuard non-interactively using CLI flags.",
+      "inputs": [
+        {
+          "name": "options",
+          "type": "unknown",
+          "required": true,
+          "description": "Headless initialization options."
+        }
+      ],
+      "outputs": {
+        "text": "The path to the created config file."
+      }
+    },
+    {
+      "id": "op-createProgram",
+      "name": "createProgram",
+      "what": "Creates the VersionGuard CLI program definition.",
+      "inputs": [],
+      "outputs": {
+        "text": "A configured Commander program for the VersionGuard CLI."
+      }
+    },
+    {
+      "id": "op-runCli",
+      "name": "runCli",
+      "what": "Parses CLI arguments and executes the matching command.",
+      "inputs": [
+        {
+          "name": "argv",
+          "type": "unknown",
+          "required": true,
+          "description": "Full argument vector to parse."
+        }
+      ]
+    },
+    {
+      "id": "op-createTempProject",
+      "name": "createTempProject",
+      "what": "Creates a temporary project directory with a minimal \`package.json\` fixture.",
+      "inputs": [],
+      "outputs": {
+        "text": "The absolute path to the temporary project directory."
+      }
+    },
+    {
+      "id": "op-initGitRepo",
+      "name": "initGitRepo",
+      "what": "Initializes a git repository in a fixture directory with a first commit.",
+      "inputs": [
+        {
+          "name": "cwd",
+          "type": "unknown",
+          "required": true,
+          "description": "Absolute path to the fixture repository."
+        }
+      ]
+    },
+    {
+      "id": "op-createBareRemote",
+      "name": "createBareRemote",
+      "what": "Creates a bare git repository to use as a remote in integration tests.",
+      "inputs": [],
+      "outputs": {
+        "text": "The absolute path to the new bare repository."
+      }
+    }
+  ],
+  "constraints": [],
+  "workflows": [],
+  "configSchema": [
+    {
+      "key": "ManifestConfig.source",
+      "type": "ManifestSourceType",
+      "description": "Manifest file to read the version from.  Use \`'auto'\` for file-existence detection or a specific filename.",
+      "default": "'auto'"
+    },
+    {
+      "key": "ManifestConfig.path",
+      "type": "string | undefined",
+      "description": "Dotted key path to the version field within the manifest.  For example \`'version'\` for package.json, \`'package.version'\` for Cargo.toml, or \`'project.version'\` for pyproject.toml.",
+      "default": "undefined (uses the provider's built-in default)"
+    },
+    {
+      "key": "ManifestConfig.regex",
+      "type": "string | undefined",
+      "description": "Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string.",
+      "default": "undefined"
+    },
+    {
+      "key": "CalVerConfig.format",
+      "type": "CalVerFormat",
+      "description": "Calendar format used when parsing and validating versions."
+    },
+    {
+      "key": "CalVerConfig.preventFutureDates",
+      "type": "boolean",
+      "description": "Rejects versions that point to a future date.",
+      "default": "true"
+    },
+    {
+      "key": "CalVerConfig.strictMutualExclusion",
+      "type": "boolean | undefined",
+      "description": "Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens.",
+      "default": "true"
+    },
+    {
+      "key": "SyncConfig.files",
+      "type": "string[]",
+      "description": "File globs or paths that should be scanned for version updates."
+    },
+    {
+      "key": "SyncConfig.patterns",
+      "type": "SyncPattern[]",
+      "description": "Replacement patterns applied to matching files."
+    },
+    {
+      "key": "ChangelogConfig.enabled",
+      "type": "boolean",
+      "description": "Enables changelog validation.",
+      "default": "false"
+    },
+    {
+      "key": "ChangelogConfig.file",
+      "type": "string",
+      "description": "Path to the changelog file to inspect."
+    },
+    {
+      "key": "ChangelogConfig.strict",
+      "type": "boolean",
+      "description": "Treats changelog problems as hard failures.",
+      "default": "false"
+    },
+    {
+      "key": "ChangelogConfig.requireEntry",
+      "type": "boolean",
+      "description": "Requires an entry for the current version.",
+      "default": "false"
+    },
+    {
+      "key": "GitHooksConfig.'pre-commit'",
+      "type": "boolean",
+      "description": "Enables validation during the \`pre-commit\` hook.",
+      "default": "false"
+    },
+    {
+      "key": "GitHooksConfig.'pre-push'",
+      "type": "boolean",
+      "description": "Enables validation during the \`pre-push\` hook.",
+      "default": "false"
+    },
+    {
+      "key": "GitHooksConfig.'post-tag'",
+      "type": "boolean",
+      "description": "Enables follow-up tasks after a tag is created.",
+      "default": "false"
+    },
+    {
+      "key": "GitConfig.hooks",
+      "type": "GitHooksConfig",
+      "description": "Hook toggles used by the CLI and validation workflow."
+    },
+    {
+      "key": "GitConfig.enforceHooks",
+      "type": "boolean",
+      "description": "Fails validation when required hooks are missing.",
+      "default": "false"
+    },
+    {
+      "key": "VersioningConfig.type",
+      "type": "VersioningType",
+      "description": "Versioning strategy used for the project."
+    },
+    {
+      "key": "VersioningConfig.schemeRules",
+      "type": "SchemeRules | undefined",
+      "description": "Scheme-level validation rules applied regardless of versioning type.",
+      "default": "\`{ maxNumericSegments: 3, allowedModifiers: ['dev', 'alpha', 'beta', 'rc'] }\`"
+    },
+    {
+      "key": "VersioningConfig.calver",
+      "type": "CalVerConfig | undefined",
+      "description": "CalVer-specific settings when \`type\` is \`'calver'\`.",
+      "default": "undefined"
+    },
+    {
+      "key": "VersionGuardConfig.versioning",
+      "type": "VersioningConfig",
+      "description": "Active versioning settings."
+    },
+    {
+      "key": "VersionGuardConfig.manifest",
+      "type": "ManifestConfig",
+      "description": "Version source manifest settings.",
+      "default": "\`{ source: 'auto' }\`"
+    },
+    {
+      "key": "VersionGuardConfig.sync",
+      "type": "SyncConfig",
+      "description": "Synchronization settings for mirrored version strings."
+    },
+    {
+      "key": "VersionGuardConfig.changelog",
+      "type": "ChangelogConfig",
+      "description": "Changelog validation settings."
+    },
+    {
+      "key": "VersionGuardConfig.git",
+      "type": "GitConfig",
+      "description": "Git enforcement settings."
+    },
+    {
+      "key": "VersionGuardConfig.ignore",
+      "type": "string[]",
+      "description": "Files or patterns excluded from validation."
+    },
+    {
+      "key": "InitOptions.cwd",
+      "type": "string",
+      "description": "Working directory path."
+    },
+    {
+      "key": "InitOptions.type",
+      "type": "\\"semver\\" | \\"calver\\" | undefined",
+      "description": "Versioning type (semver or calver)."
+    },
+    {
+      "key": "InitOptions.format",
+      "type": "string | undefined",
+      "description": "CalVer format string."
+    },
+    {
+      "key": "InitOptions.manifest",
+      "type": "string | undefined",
+      "description": "Manifest source type."
+    },
+    {
+      "key": "InitOptions.hooks",
+      "type": "boolean | undefined",
+      "description": "Whether to install git hooks."
+    },
+    {
+      "key": "InitOptions.changelog",
+      "type": "boolean | undefined",
+      "description": "Whether to enable changelog validation."
+    },
+    {
+      "key": "InitOptions.yes",
+      "type": "boolean | undefined",
+      "description": "Accept defaults without prompting."
+    },
+    {
+      "key": "InitOptions.force",
+      "type": "boolean | undefined",
+      "description": "Overwrite existing config."
+    }
+  ]
+}
+`;
+const llmsRaw = "# @codluv/versionguard\n> Strict versioning enforcement for SemVer and CalVer with git hooks, changelog validation, and file sync from package.json\n> Version: 0.4.0\n\n## Install\n\n```bash\nnpm install -D @codluv/versionguard\n```\n\n## Documentation\n\n- [API Reference](./api-reference.mdx): Full API documentation (MDX)\n- [Full Context](./llms-full.txt): Complete symbol documentation for deep LLM consumption\n\n## Packages\n\n### main\n90 functions, 42 types\n\n- getCalVerConfig() — Extracts the CalVer config from a VersionGuard config, throwing if missing.\n- isValidCalVerFormat() — Validates that a CalVer format string is composed of valid tokens and follows structural rules.\n- parseFormat() — Breaks a CalVer format string into its component tokens.\n- getRegexForFormat() — Builds a regular expression that matches a supported CalVer format.\n- parse() — Parses a CalVer string using the supplied format.\n- validate() — Validates a CalVer string against formatting and date rules.\n- format() — Formats a parsed CalVer object back into a version string.\n- getCurrentVersion() — Creates the current CalVer string for a format.\n- compare() — Compares two CalVer strings using a shared format.\n- increment() — Increments a CalVer string.\n- getNextVersions() — Returns the most likely next CalVer candidates.\n- validateChangelog() — Validates a changelog file for release readiness.\n- getLatestVersion() — Gets the most recent released version from a changelog.\n- addVersionEntry() — Inserts a new version entry beneath the `[Unreleased]` section.\n- isChangesetMangled() — Detects whether a changelog has been mangled by Changesets.\n- fixChangesetMangling() — Fixes a Changesets-mangled changelog into proper Keep a Changelog format.\n- parse() — Parses a semantic version string.\n- validate() — Validates that a string is a supported semantic version.\n- compare() — Compares two semantic version strings.\n- gt() — Checks whether one semantic version is greater than another.\n- lt() — Checks whether one semantic version is less than another.\n- eq() — Checks whether two semantic versions are equal in precedence.\n- increment() — Increments a semantic version string by release type.\n- format() — Formats a parsed semantic version object.\n- getVersionFeedback() — Generates actionable feedback for a version string.\n- getSyncFeedback() — Generates suggestions for version sync mismatches in a file.\n- getChangelogFeedback() — Generates suggestions for changelog-related validation issues.\n- getTagFeedback() — Generates suggestions for git tag mismatches.\n- getNestedValue() — Traverses a nested object using a dotted key path.\n- setNestedValue() — Sets a value at a dotted key path, throwing if intermediate segments are missing.\n- escapeRegExp() — Escapes special regex characters in a string for safe use in `new RegExp()`.\n- resolveVersionSource() — Resolves the version source provider for a project.\n- detectManifests() — Detects all manifest files present in a project directory.\n- getPackageJsonPath() — Gets the `package.json` path for a project directory.\n- readPackageJson() — Reads and parses a project's `package.json` file.\n- writePackageJson() — Writes a `package.json` document back to disk.\n- getPackageVersion() — Gets the version string from the project manifest.  When a `manifest` config is provided, uses the configured version source provider (auto-detection or explicit). Falls back to `package.json` for backwards compatibility when no config is provided.\n- setPackageVersion() — Sets the version field in the project manifest.  When a `manifest` config is provided, uses the configured version source provider. Falls back to `package.json` for backwards compatibility when no config is provided.\n- getVersionSource() — Resolves the version source provider for a project.\n- syncVersion() — Synchronizes configured files to a single version string.\n- syncFile() — Synchronizes a single file to a target version.\n- checkHardcodedVersions() — Checks configured files for hardcoded version mismatches.\n- fixPackageVersion() — Updates the `package.json` version field when needed.\n- fixSyncIssues() — Synchronizes configured files to the package version.\n- fixChangelog() — Ensures the changelog contains an entry for a version.\n- fixAll() — Runs all configured auto-fix operations.\n- suggestNextVersion() — Suggests candidate next versions for a release.\n- installHooks() — Installs VersionGuard-managed Git hooks in a repository.\n- uninstallHooks() — Removes VersionGuard-managed Git hooks from a repository.\n- findGitDir() — Finds the nearest `.git` directory by walking up from a starting directory.\n- areHooksInstalled() — Checks whether all VersionGuard-managed hooks are installed.\n- generateHookScript() — Generates the shell script content for a Git hook.\n- checkHooksPathOverride() — Checks whether git hooks have been redirected away from the repository.\n- checkHuskyBypass() — Checks whether the HUSKY environment variable is disabling hooks.\n- checkHookIntegrity() — Verifies that installed hook scripts match the expected content.\n- checkEnforceHooksPolicy() — Checks whether hooks are configured as required but not enforced.\n- runGuardChecks() — Runs all guard checks and returns a consolidated report.\n- getTopicIndex() — Returns the topic index listing.\n- getTopicContent() — Returns help content for a specific topic.\n- getLlmContext() — Returns the full API context for LLM consumption.\n- getHelpJson() — Returns the topic index as a JSON structure for machine parsing.\n- getDefaultConfig() — Returns a deep-cloned copy of the built-in VersionGuard configuration.\n- findConfig() — Finds the first supported VersionGuard config file in a directory.\n- loadConfig() — Loads a VersionGuard config file from disk.\n- getConfig() — Resolves the active VersionGuard configuration for a project.\n- initConfig() — Initializes a new VersionGuard config file in a project.\n- findProjectRoot() — Walks up from `startDir` to find the nearest project root.\n- formatNotProjectError() — Formats a helpful error message when a command can't find a project.\n- getLatestTag() — Returns the most recent reachable git tag for a repository.\n- getAllTags() — Lists all tags in a repository.\n- createTag() — Creates a release tag and optionally fixes version state first.\n- handlePostTag() — Runs post-tag validation and sync checks.\n- validateTagForPush() — Validates that a local tag is safe to push to the default remote.\n- suggestTagMessage() — Suggests an annotated tag message from changelog content.\n- validateVersion() — Validates a version string against the active versioning strategy.\n- validate() — Validates the current project state against the supplied configuration.\n- doctor() — Runs an extended readiness check for a project.\n- sync() — Synchronizes configured files to the current package version.\n- canBump() — Determines whether a project can move from one version to another.\n- runWizard() — Runs the interactive setup wizard.\n- runHeadless() — Initializes VersionGuard non-interactively using CLI flags.\n- createProgram() — Creates the VersionGuard CLI program definition.\n- runCli() — Parses CLI arguments and executes the matching command.\n- shouldRunCli() — Determines whether the current module is the invoked CLI entry point.\n- createTempProject() — Creates a temporary project directory with a minimal `package.json` fixture.\n- initGitRepo() — Initializes a git repository in a fixture directory with a first commit.\n- writeTextFile() — Writes a text fixture file relative to a temporary project directory.\n- createBareRemote() — Creates a bare git repository to use as a remote in integration tests.\n- addGitRemote() — Adds a local bare repository as the `origin` remote for a fixture repo.\n- commitAll() — Stages all changes and creates a commit in a fixture repository.\n\n- VersioningType — Supported versioning strategies.\n- ManifestSourceType — Supported manifest source types for version extraction.\n- ManifestConfig — Configures the version source manifest.\n- CalVerToken — Valid CalVer token names for building format strings.\n- CalVerFormat — A CalVer format string composed of dot-separated tokens.\n- SchemeRules — Configures scheme-level validation rules applied regardless of versioning type.\n- CalVerConfig — Configures CalVer validation rules.\n- SyncPattern — Describes a search-and-replace pattern used during version synchronization.\n- SyncConfig — Configures files and patterns that should stay in sync with the canonical version.\n- ChangelogConfig — Controls changelog validation behavior.\n- GitHooksConfig — Toggles each supported git hook integration.\n- GitConfig — Configures git-related enforcement.\n- VersioningConfig — Configures the active versioning mode.\n- VersionGuardConfig — Top-level configuration consumed by versionguard.\n- SemVer — Parsed semantic version components.\n- CalVer — Parsed calendar version components.\n- ParsedSemVer — Parsed semantic version result wrapper.\n- ParsedCalVer — Parsed calendar version result wrapper.\n- ParsedVersion — Union of supported parsed version payloads.\n- ValidationError — Describes a single validation problem.\n- ValidationResult — Result returned by version parsing and validation helpers.\n- SyncChange — Describes a single in-file version replacement.\n- SyncResult — Reports the result of synchronizing a single file.\n- VersionMismatch — Reports a discovered version mismatch.\n- FullValidationResult — Combined result from a full project validation run.\n- DoctorReport — Reports whether a project is ready to pass VersionGuard checks.\n- ParsedCalVerFormat — Parsed token layout for a supported CalVer format string.\n- ChangelogValidationResult — Describes the outcome of validating a changelog file.\n- Suggestion — Feedback entry point exports for suggestion and guidance helpers.\n- FeedbackResult — Aggregates validation errors with suggested next steps.\n- VersionSourceProvider — Abstraction for reading and writing a version string from any manifest format.\n- PackageJsonValue — JSON-compatible scalar, array, or object value used by package metadata.\n- PackageJsonArray — Recursive array type used for arbitrary JSON-compatible package values.\n- PackageJsonObject — Recursive object type used for arbitrary JSON-compatible package values.\n- PackageJson — Minimal shape of a `package.json` document used by VersionGuard.\n- FixResult — Fix entry point exports for auto-remediation helpers.\n- GuardWarning — Describes a single guard finding.\n- GuardReport — Result of a full guard check pass.\n- HelpTopic — Embedded help topics for the CLI help system.\n- ProjectRootResult — Result of project root detection.\n- TagInfo — Tag entry point exports for release-tag management helpers.\n- InitOptions — Options for headless (non-interactive) initialization.\n";
 async function runWizard(cwd) {
   p.intro("VersionGuard Setup");
   const existingConfig = findExistingConfig(cwd);
@@ -73,8 +1084,10 @@ async function runWizard(cwd) {
 }
 function runHeadless(options) {
   const existingConfig = findExistingConfig(options.cwd);
-  if (existingConfig && !options.yes) {
-    throw new Error(`Config already exists: ${existingConfig}. Use --yes to overwrite.`);
+  if (existingConfig && !options.force && !options.yes) {
+    throw new Error(
+      `Config already exists: ${existingConfig}. Use --force to overwrite or --yes to accept defaults.`
+    );
   }
   const config = buildConfig({
     type: options.type ?? "semver",
@@ -219,6 +1232,7 @@ function findExistingConfig(cwd) {
 }
 const CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CLI_VERSION = JSON.parse(fs.readFileSync(path.join(CLI_DIR, "..", "package.json"), "utf-8")).version;
+const ckmEngine = createCkmEngine(JSON.parse(ckmRaw));
 const styles = {
   error: chalk.red,
   warning: chalk.yellow,
@@ -227,10 +1241,18 @@ const styles = {
   dim: chalk.gray,
   bold: chalk.bold
 };
+function requireProject(cwd, command) {
+  const result = findProjectRoot(cwd);
+  if (!result.found) {
+    console.error(styles.error(formatNotProjectError(cwd, command)));
+    process.exit(1);
+  }
+  return result.root;
+}
 function createProgram() {
   const program = new Command();
   program.name("versionguard").description("Strict versioning enforcement for SemVer and CalVer").version(CLI_VERSION);
-  program.command("init").description("Initialize VersionGuard configuration (interactive wizard or headless)").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-t, --type <type>", "Versioning type: semver or calver").option("-f, --format <format>", "CalVer format tokens (e.g., YYYY.M.MICRO)").option("--manifest <source>", "Manifest source (e.g., Cargo.toml, pyproject.toml, auto)").option("--hooks", "Install git hooks (default: true)").option("--no-hooks", "Skip git hooks").option("--changelog", "Enable changelog validation (default: true)").option("--no-changelog", "Disable changelog validation").option("-y, --yes", "Accept all defaults, no prompts").action(
+  program.command("init").description("Initialize VersionGuard configuration (interactive wizard or headless)").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-t, --type <type>", "Versioning type: semver or calver").option("-f, --format <format>", "CalVer format tokens (e.g., YYYY.M.MICRO)").option("--manifest <source>", "Manifest source (e.g., Cargo.toml, pyproject.toml, auto)").option("--hooks", "Install git hooks (default: true)").option("--no-hooks", "Skip git hooks").option("--changelog", "Enable changelog validation (default: true)").option("--no-changelog", "Disable changelog validation").option("-y, --yes", "Accept all defaults, no prompts").option("--force", "Overwrite existing config file").action(
     async (options) => {
       try {
         const isHeadless = options.yes || options.type || options.format || options.manifest;
@@ -243,7 +1265,8 @@ function createProgram() {
             manifest: options.manifest,
             hooks: options.hooks,
             changelog: options.changelog,
-            yes: options.yes
+            yes: options.yes,
+            force: options.force
           });
           console.log(styles.success(`✓ Created ${path.relative(options.cwd, configPath)}`));
         } else {
@@ -270,6 +1293,7 @@ function createProgram() {
   );
   program.command("check").description("Check the current version with actionable feedback").option("-c, --cwd <path>", "Working directory", process.cwd()).option("--prev <version>", "Previous version for comparison").option("--json", "Print machine-readable JSON output").action((options) => {
     try {
+      options.cwd = requireProject(options.cwd, "check");
       const config = getConfig(options.cwd);
       const version = getPackageVersion(options.cwd, config.manifest);
       const result = getVersionFeedback(version, config, options.prev);
@@ -322,6 +1346,7 @@ function createProgram() {
   });
   program.command("validate").description("Run full validation with smart feedback").option("-c, --cwd <path>", "Working directory", process.cwd()).option("--hook <name>", "Running as git hook").option("--json", "Print machine-readable JSON output").option("--strict", "Run guard checks and fail on any policy gap or bypass").action((options) => {
     try {
+      options.cwd = requireProject(options.cwd, "validate");
       const config = getConfig(options.cwd);
       const version = getPackageVersion(options.cwd, config.manifest);
       const result = validate(config, options.cwd);
@@ -413,6 +1438,7 @@ function createProgram() {
   });
   program.command("doctor").description("Report repository readiness in one pass").option("-c, --cwd <path>", "Working directory", process.cwd()).option("--json", "Print machine-readable JSON output").option("--strict", "Include guard checks for bypass detection").action((options) => {
     try {
+      options.cwd = requireProject(options.cwd, "doctor");
       const config = getConfig(options.cwd);
       const report = doctor(config, options.cwd);
       const guardReport = options.strict ? runGuardChecks(config, options.cwd) : void 0;
@@ -464,6 +1490,7 @@ function createProgram() {
   });
   program.command("fix").description("Auto-fix detected issues").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
     try {
+      options.cwd = requireProject(options.cwd, "fix");
       const config = getConfig(options.cwd);
       const version = getPackageVersion(options.cwd, config.manifest);
       const results = fixAll(config, version, options.cwd);
@@ -478,8 +1505,31 @@ function createProgram() {
       process.exit(1);
     }
   });
+  program.command("fix-changelog").description("Fix Changesets-mangled changelog into Keep a Changelog format").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
+    try {
+      options.cwd = requireProject(options.cwd, "fix-changelog");
+      const config = getConfig(options.cwd);
+      const changelogPath = path.join(options.cwd, config.changelog.file);
+      if (!isChangesetMangled(changelogPath)) {
+        console.log(styles.dim("• Changelog is not mangled — no fix needed"));
+        return;
+      }
+      const fixed = fixChangesetMangling(changelogPath);
+      if (fixed) {
+        console.log(
+          styles.success(`✓ Restructured ${config.changelog.file} to Keep a Changelog format`)
+        );
+      } else {
+        console.log(styles.dim("• Could not auto-fix changelog structure"));
+      }
+    } catch (error) {
+      console.error(styles.error(`✗ ${error.message}`));
+      process.exit(1);
+    }
+  });
   program.command("sync").description("Sync version to all configured files").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
     try {
+      options.cwd = requireProject(options.cwd, "sync");
       const config = getConfig(options.cwd);
       const version = getPackageVersion(options.cwd, config.manifest);
       const results = fixSyncIssues(config, options.cwd);
@@ -496,6 +1546,7 @@ function createProgram() {
   program.command("bump").description("Suggest and optionally apply the next version").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-t, --type <type>", "Bump type (major, minor, patch, auto)").option("--apply", "Apply the first suggested version").action(
     (options) => {
       try {
+        options.cwd = requireProject(options.cwd, "bump");
         const config = getConfig(options.cwd);
         const currentVersion = getPackageVersion(options.cwd, config.manifest);
         const suggestions = suggestNextVersion(currentVersion, config, options.type);
@@ -523,6 +1574,7 @@ function createProgram() {
   program.command("tag").description("Create a git tag with automation").argument("[version]", "Version to tag (defaults to manifest version)").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-m, --message <msg>", "Tag message").option("--no-fix", "Skip auto-fixing files before tagging").action(
     (version, options) => {
       try {
+        options.cwd = requireProject(options.cwd, "tag");
         const config = getConfig(options.cwd);
         const tagVersion = version || getPackageVersion(options.cwd, config.manifest);
         const result = createTag(
@@ -546,9 +1598,32 @@ function createProgram() {
       }
     }
   );
+  program.command("ckm [topic]").description("Codebase Knowledge Manifest — auto-generated docs and help").option("--json", "Machine-readable CKM output for LLM agents").option("--llm", "Full API context (forge-ts llms.txt)").action((topic, options) => {
+    if (options.llm) {
+      console.log(llmsRaw);
+      return;
+    }
+    if (options.json) {
+      console.log(JSON.stringify(ckmEngine.getTopicJson(topic), null, 2));
+      return;
+    }
+    if (topic) {
+      const content = ckmEngine.getTopicContent(topic);
+      if (!content) {
+        console.error(styles.error(`Unknown topic: ${topic}`));
+        console.log("");
+        console.log(ckmEngine.getTopicIndex("versionguard"));
+        process.exit(1);
+      }
+      console.log(content);
+    } else {
+      console.log(ckmEngine.getTopicIndex("versionguard"));
+    }
+  });
   const hooksCommand = program.command("hooks").description("Manage git hooks");
   hooksCommand.command("install").description("Install git hooks").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
     try {
+      options.cwd = requireProject(options.cwd, "hooks install");
       const config = getConfig(options.cwd);
       installHooks(config.git, options.cwd);
       console.log(styles.success("✓ Git hooks installed"));
@@ -559,6 +1634,7 @@ function createProgram() {
   });
   hooksCommand.command("uninstall").description("Uninstall git hooks").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
     try {
+      options.cwd = requireProject(options.cwd, "hooks uninstall");
       uninstallHooks(options.cwd);
       console.log(styles.success("✓ Git hooks uninstalled"));
     } catch (error) {
@@ -568,6 +1644,7 @@ function createProgram() {
   });
   hooksCommand.command("status").description("Check if hooks are installed").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
     try {
+      options.cwd = requireProject(options.cwd, "hooks status");
       if (areHooksInstalled(options.cwd)) {
         console.log(styles.success("✓ VersionGuard hooks are installed"));
         return;
@@ -585,8 +1662,14 @@ async function runCli(argv = process.argv) {
   await createProgram().parseAsync(argv);
 }
 function shouldRunCli(argv = process.argv, metaUrl = import.meta.url) {
-  const entryPath = argv[1] ? path.resolve(argv[1]) : null;
-  return entryPath === fileURLToPath(metaUrl);
+  if (!argv[1]) return false;
+  const metaPath = fileURLToPath(metaUrl);
+  const resolved = path.resolve(argv[1]);
+  try {
+    return fs.realpathSync(resolved) === metaPath;
+  } catch {
+    return resolved === metaPath;
+  }
 }
 if (shouldRunCli()) {
   void runCli();