@codluv/versionguard 0.4.0 → 0.6.0

package/dist/cli.js

@@ -4,9 +4,11 @@ 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-DeZAx4Le.js";
 import * as p from "@clack/prompts";
 import * as yaml from "js-yaml";
+const ckmRaw = '{\n  "$schema": "https://forge-ts.dev/schemas/ckm/v1.json",\n  "version": "1.0.0",\n  "project": "@codluv/versionguard",\n  "generated": "2026-03-26T20:51:51.376Z",\n  "concepts": [\n    {\n      "id": "concept-ManifestConfig",\n      "name": "ManifestConfig",\n      "what": "Configures the version source manifest.",\n      "properties": [\n        {\n          "name": "source",\n          "type": "ManifestSourceType",\n          "description": "Manifest file to read the version from.  Use `\'auto\'` for file-existence detection or a specific filename."\n        },\n        {\n          "name": "path",\n          "type": "string | undefined",\n          "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."\n        },\n        {\n          "name": "regex",\n          "type": "string | undefined",\n          "description": "Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string."\n        }\n      ]\n    },\n    {\n      "id": "concept-SemVerConfig",\n      "name": "SemVerConfig",\n      "what": "Configures SemVer validation rules.",\n      "properties": [\n        {\n          "name": "allowVPrefix",\n          "type": "boolean",\n          "description": "Tolerates a leading `v` prefix (e.g. `v1.2.3`).  When enabled the prefix is stripped before parsing."\n        },\n        {\n          "name": "allowBuildMetadata",\n          "type": "boolean",\n          "description": "Permits `+build` metadata on version strings."\n        },\n        {\n          "name": "requirePrerelease",\n          "type": "boolean",\n          "description": "Requires every version to carry a prerelease label."\n        }\n      ]\n    },\n    {\n      "id": "concept-CalVerConfig",\n      "name": "CalVerConfig",\n      "what": "Configures CalVer validation rules.",\n      "properties": [\n        {\n          "name": "format",\n          "type": "CalVerFormat",\n          "description": "Calendar format used when parsing and validating versions."\n        },\n        {\n          "name": "preventFutureDates",\n          "type": "boolean",\n          "description": "Rejects versions that point to a future date."\n        },\n        {\n          "name": "strictMutualExclusion",\n          "type": "boolean | undefined",\n          "description": "Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens."\n        }\n      ]\n    },\n    {\n      "id": "concept-SyncConfig",\n      "name": "SyncConfig",\n      "what": "Configures files and patterns that should stay in sync with the canonical version.",\n      "properties": [\n        {\n          "name": "files",\n          "type": "string[]",\n          "description": "File globs or paths that should be scanned for version updates."\n        },\n        {\n          "name": "patterns",\n          "type": "SyncPattern[]",\n          "description": "Replacement patterns applied to matching files."\n        }\n      ]\n    },\n    {\n      "id": "concept-ChangelogConfig",\n      "name": "ChangelogConfig",\n      "what": "Controls changelog validation behavior.",\n      "properties": [\n        {\n          "name": "enabled",\n          "type": "boolean",\n          "description": "Enables changelog validation."\n        },\n        {\n          "name": "file",\n          "type": "string",\n          "description": "Path to the changelog file to inspect."\n        },\n        {\n          "name": "strict",\n          "type": "boolean",\n          "description": "Treats changelog problems as hard failures."\n        },\n        {\n          "name": "requireEntry",\n          "type": "boolean",\n          "description": "Requires an entry for the current version."\n        }\n      ]\n    },\n    {\n      "id": "concept-GitHooksConfig",\n      "name": "GitHooksConfig",\n      "what": "Toggles each supported git hook integration.",\n      "properties": [\n        {\n          "name": "\'pre-commit\'",\n          "type": "boolean",\n          "description": "Enables validation during the `pre-commit` hook."\n        },\n        {\n          "name": "\'pre-push\'",\n          "type": "boolean",\n          "description": "Enables validation during the `pre-push` hook."\n        },\n        {\n          "name": "\'post-tag\'",\n          "type": "boolean",\n          "description": "Enables follow-up tasks after a tag is created."\n        }\n      ]\n    },\n    {\n      "id": "concept-GitConfig",\n      "name": "GitConfig",\n      "what": "Configures git-related enforcement.",\n      "properties": [\n        {\n          "name": "hooks",\n          "type": "GitHooksConfig",\n          "description": "Hook toggles used by the CLI and validation workflow."\n        },\n        {\n          "name": "enforceHooks",\n          "type": "boolean",\n          "description": "Fails validation when required hooks are missing."\n        }\n      ]\n    },\n    {\n      "id": "concept-VersioningConfig",\n      "name": "VersioningConfig",\n      "what": "Configures the active versioning mode.",\n      "properties": [\n        {\n          "name": "type",\n          "type": "VersioningType",\n          "description": "Versioning strategy used for the project."\n        },\n        {\n          "name": "schemeRules",\n          "type": "SchemeRules | undefined",\n          "description": "Scheme-level validation rules applied regardless of versioning type."\n        },\n        {\n          "name": "semver",\n          "type": "SemVerConfig | undefined",\n          "description": "SemVer-specific settings when `type` is `\'semver\'`."\n        },\n        {\n          "name": "calver",\n          "type": "CalVerConfig | undefined",\n          "description": "CalVer-specific settings when `type` is `\'calver\'`."\n        }\n      ]\n    },\n    {\n      "id": "concept-VersionGuardConfig",\n      "name": "VersionGuardConfig",\n      "what": "Top-level configuration consumed by versionguard.",\n      "properties": [\n        {\n          "name": "versioning",\n          "type": "VersioningConfig",\n          "description": "Active versioning settings."\n        },\n        {\n          "name": "manifest",\n          "type": "ManifestConfig",\n          "description": "Version source manifest settings."\n        },\n        {\n          "name": "sync",\n          "type": "SyncConfig",\n          "description": "Synchronization settings for mirrored version strings."\n        },\n        {\n          "name": "changelog",\n          "type": "ChangelogConfig",\n          "description": "Changelog validation settings."\n        },\n        {\n          "name": "git",\n          "type": "GitConfig",\n          "description": "Git enforcement settings."\n        },\n        {\n          "name": "ignore",\n          "type": "string[]",\n          "description": "Files or patterns excluded from validation."\n        }\n      ]\n    },\n    {\n      "id": "concept-ValidationResult",\n      "name": "ValidationResult",\n      "what": "Result returned by version parsing and validation helpers.",\n      "properties": [\n        {\n          "name": "valid",\n          "type": "boolean",\n          "description": "Indicates whether validation completed without errors."\n        },\n        {\n          "name": "errors",\n          "type": "ValidationError[]",\n          "description": "Collected validation issues."\n        },\n        {\n          "name": "version",\n          "type": "ParsedVersion | undefined",\n          "description": "Parsed version details when validation succeeds."\n        }\n      ]\n    },\n    {\n      "id": "concept-SyncResult",\n      "name": "SyncResult",\n      "what": "Reports the result of synchronizing a single file.",\n      "properties": [\n        {\n          "name": "file",\n          "type": "string",\n          "description": "File that was inspected or updated."\n        },\n        {\n          "name": "updated",\n          "type": "boolean",\n          "description": "Indicates whether the file content changed."\n        },\n        {\n          "name": "changes",\n          "type": "SyncChange[]",\n          "description": "Detailed replacements applied within the file."\n        }\n      ]\n    },\n    {\n      "id": "concept-FullValidationResult",\n      "name": "FullValidationResult",\n      "what": "Combined result from a full project validation run.",\n      "properties": [\n        {\n          "name": "valid",\n          "type": "boolean",\n          "description": "Indicates whether all checks passed."\n        },\n        {\n          "name": "version",\n          "type": "string",\n          "description": "Canonical version string used for validation."\n        },\n        {\n          "name": "versionValid",\n          "type": "boolean",\n          "description": "Indicates whether the root version string is valid."\n        },\n        {\n          "name": "syncValid",\n          "type": "boolean",\n          "description": "Indicates whether synchronized files are in sync."\n        },\n        {\n          "name": "changelogValid",\n          "type": "boolean",\n          "description": "Indicates whether changelog checks passed."\n        },\n        {\n          "name": "errors",\n          "type": "string[]",\n          "description": "Human-readable validation failures collected during the run."\n        }\n      ]\n    },\n    {\n      "id": "concept-ChangelogValidationResult",\n      "name": "ChangelogValidationResult",\n      "what": "Describes the outcome of validating a changelog file.",\n      "properties": [\n        {\n          "name": "valid",\n          "type": "boolean",\n          "description": "Indicates whether the changelog satisfies all requested checks."\n        },\n        {\n          "name": "errors",\n          "type": "string[]",\n          "description": "Human-readable validation errors."\n        },\n        {\n          "name": "hasEntryForVersion",\n          "type": "boolean",\n          "description": "Indicates whether the changelog contains an entry for the requested version."\n        }\n      ]\n    },\n    {\n      "id": "concept-CkmConfigEntry",\n      "name": "CkmConfigEntry",\n      "what": "A config schema entry with type, description, and default.",\n      "properties": [\n        {\n          "name": "key",\n          "type": "string",\n          "description": "Dotted key path (e.g., `\'CalVerConfig.format\'`)."\n        },\n        {\n          "name": "type",\n          "type": "string",\n          "description": "TypeScript type."\n        },\n        {\n          "name": "description",\n          "type": "string",\n          "description": "Description from TSDoc."\n        },\n        {\n          "name": "default",\n          "type": "string | undefined",\n          "description": "Default value if specified via `@defaultValue`."\n        }\n      ]\n    },\n    {\n      "id": "concept-FeedbackResult",\n      "name": "FeedbackResult",\n      "what": "Aggregates validation errors with suggested next steps.",\n      "properties": [\n        {\n          "name": "valid",\n          "type": "boolean",\n          "description": "Indicates whether the inspected version state is valid."\n        },\n        {\n          "name": "errors",\n          "type": "ValidationError[]",\n          "description": "Validation errors collected during the check."\n        },\n        {\n          "name": "suggestions",\n          "type": "Suggestion[]",\n          "description": "Suggested next steps for resolving the reported issues."\n        },\n        {\n          "name": "canAutoFix",\n          "type": "boolean",\n          "description": "Indicates whether at least one suggestion can be auto-applied."\n        }\n      ]\n    },\n    {\n      "id": "concept-FixResult",\n      "name": "FixResult",\n      "what": "Fix entry point exports for auto-remediation helpers.",\n      "properties": [\n        {\n          "name": "fixed",\n          "type": "boolean",\n          "description": "Indicates whether the operation changed repository state."\n        },\n        {\n          "name": "message",\n          "type": "string",\n          "description": "Human-readable description of the fix attempt."\n        },\n        {\n          "name": "file",\n          "type": "string | undefined",\n          "description": "Absolute path to the file that was updated, when applicable."\n        }\n      ]\n    },\n    {\n      "id": "concept-ProjectRootResult",\n      "name": "ProjectRootResult",\n      "what": "Result of project root detection.",\n      "properties": [\n        {\n          "name": "found",\n          "type": "boolean",\n          "description": "Whether a project root was found."\n        },\n        {\n          "name": "root",\n          "type": "string",\n          "description": "The resolved project root directory, or the original cwd if not found."\n        },\n        {\n          "name": "marker",\n          "type": "string | undefined",\n          "description": "Which marker file was found."\n        },\n        {\n          "name": "hasConfig",\n          "type": "boolean",\n          "description": "Whether the directory has a VersionGuard config."\n        },\n        {\n          "name": "hasGit",\n          "type": "boolean",\n          "description": "Whether the directory is inside a git repository."\n        },\n        {\n          "name": "hasManifest",\n          "type": "boolean",\n          "description": "Whether a version manifest file exists."\n        }\n      ]\n    },\n    {\n      "id": "concept-InitOptions",\n      "name": "InitOptions",\n      "what": "Options for headless (non-interactive) initialization.",\n      "properties": [\n        {\n          "name": "cwd",\n          "type": "string",\n          "description": "Working directory path."\n        },\n        {\n          "name": "type",\n          "type": "\\"semver\\" | \\"calver\\" | undefined",\n          "description": "Versioning type (semver or calver)."\n        },\n        {\n          "name": "format",\n          "type": "string | undefined",\n          "description": "CalVer format string."\n        },\n        {\n          "name": "allowVPrefix",\n          "type": "boolean | undefined",\n          "description": "Allow v-prefix on SemVer versions."\n        },\n        {\n          "name": "allowBuildMetadata",\n          "type": "boolean | undefined",\n          "description": "Allow build metadata on SemVer versions."\n        },\n        {\n          "name": "requirePrerelease",\n          "type": "boolean | undefined",\n          "description": "Require prerelease labels on SemVer versions."\n        },\n        {\n          "name": "manifest",\n          "type": "string | undefined",\n          "description": "Manifest source type."\n        },\n        {\n          "name": "hooks",\n          "type": "boolean | undefined",\n          "description": "Whether to install git hooks."\n        },\n        {\n          "name": "changelog",\n          "type": "boolean | undefined",\n          "description": "Whether to enable changelog validation."\n        },\n        {\n          "name": "yes",\n          "type": "boolean | undefined",\n          "description": "Accept defaults without prompting."\n        },\n        {\n          "name": "force",\n          "type": "boolean | undefined",\n          "description": "Overwrite existing config."\n        }\n      ]\n    }\n  ],\n  "operations": [\n    {\n      "id": "op-validateModifier",\n      "name": "validateModifier",\n      "what": "Validates a pre-release / modifier tag against the allowed modifiers list.",\n      "inputs": [\n        {\n          "name": "modifier",\n          "type": "unknown",\n          "required": true,\n          "description": "Raw modifier string (e.g. `\\"alpha.1\\"`, `\\"rc2\\"`, `\\"dev\\"`)."\n        },\n        {\n          "name": "schemeRules",\n          "type": "unknown",\n          "required": true,\n          "description": "Scheme rules containing the allowed modifiers list."\n        }\n      ],\n      "outputs": {\n        "text": "A validation error when the modifier is disallowed, otherwise `null`."\n      }\n    },\n    {\n      "id": "op-validate",\n      "name": "validate",\n      "what": "Validates a CalVer string against formatting and date rules.",\n      "inputs": [\n        {\n          "name": "version",\n          "type": "unknown",\n          "required": true,\n          "description": "Version string to validate."\n        },\n        {\n          "name": "calverFormat",\n          "type": "unknown",\n          "required": true,\n          "description": "Format expected for the version string."\n        },\n        {\n          "name": "preventFutureDates",\n          "type": "unknown",\n          "required": true,\n          "description": "Whether future dates should be reported as errors."\n        },\n        {\n          "name": "schemeRules",\n          "type": "unknown",\n          "required": true,\n          "description": "Optional scheme rules for modifier validation and segment count warnings."\n        }\n      ],\n      "outputs": {\n        "text": "A validation result containing any discovered errors and the parsed version on success."\n      }\n    },\n    {\n      "id": "op-validateChangelog",\n      "name": "validateChangelog",\n      "what": "Validates a changelog file for release readiness.",\n      "inputs": [\n        {\n          "name": "changelogPath",\n          "type": "unknown",\n          "required": true,\n          "description": "Path to the changelog file."\n        },\n        {\n          "name": "version",\n          "type": "unknown",\n          "required": true,\n          "description": "Version that must be present in the changelog."\n        },\n        {\n          "name": "strict",\n          "type": "unknown",\n          "required": true,\n          "description": "Whether to require compare links and dated release headings."\n        },\n        {\n          "name": "requireEntry",\n          "type": "unknown",\n          "required": true,\n          "description": "Whether the requested version must already have an entry."\n        }\n      ],\n      "outputs": {\n        "text": "The result of validating the changelog file."\n      }\n    },\n    {\n      "id": "op-createCkmEngine",\n      "name": "createCkmEngine",\n      "what": "Creates a CKM engine from a parsed manifest.",\n      "inputs": [\n        {\n          "name": "manifest",\n          "type": "unknown",\n          "required": true,\n          "description": "Parsed CKM manifest (from forge-ts `ckm.json`)."\n        }\n      ],\n      "outputs": {\n        "text": "A configured CKM engine."\n      }\n    },\n    {\n      "id": "op-checkHardcodedVersions",\n      "name": "checkHardcodedVersions",\n      "what": "Checks configured files for hardcoded version mismatches.",\n      "inputs": [\n        {\n          "name": "expectedVersion",\n          "type": "unknown",\n          "required": true,\n          "description": "Version all matching entries should use."\n        },\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "Sync configuration describing files and replacement patterns."\n        },\n        {\n          "name": "ignorePatterns",\n          "type": "unknown",\n          "required": true,\n          "description": "Glob patterns to exclude while scanning."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Project directory used to resolve file globs."\n        }\n      ],\n      "outputs": {\n        "text": "A list of detected version mismatches."\n      }\n    },\n    {\n      "id": "op-generateHookScript",\n      "name": "generateHookScript",\n      "what": "Generates the shell script content for a Git hook.",\n      "inputs": [\n        {\n          "name": "hookName",\n          "type": "unknown",\n          "required": true,\n          "description": "Name of the Git hook to generate."\n        }\n      ],\n      "outputs": {\n        "text": "Executable shell script contents for the hook."\n      }\n    },\n    {\n      "id": "op-checkHooksPathOverride",\n      "name": "checkHooksPathOverride",\n      "what": "Checks whether git hooks have been redirected away from the repository.",\n      "inputs": [\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory to inspect."\n        }\n      ],\n      "outputs": {\n        "text": "A guard warning when a hooksPath override is detected."\n      }\n    },\n    {\n      "id": "op-checkHuskyBypass",\n      "name": "checkHuskyBypass",\n      "what": "Checks whether the HUSKY environment variable is disabling hooks.",\n      "inputs": [],\n      "outputs": {\n        "text": "A guard warning when the HUSKY bypass is detected."\n      }\n    },\n    {\n      "id": "op-checkHookIntegrity",\n      "name": "checkHookIntegrity",\n      "what": "Verifies that installed hook scripts match the expected content.",\n      "inputs": [\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "VersionGuard configuration that defines which hooks should exist."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory to inspect."\n        }\n      ],\n      "outputs": {\n        "text": "Guard warnings for each hook that has been tampered with."\n      }\n    },\n    {\n      "id": "op-checkEnforceHooksPolicy",\n      "name": "checkEnforceHooksPolicy",\n      "what": "Checks whether hooks are configured as required but not enforced.",\n      "inputs": [\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "VersionGuard configuration to inspect."\n        }\n      ],\n      "outputs": {\n        "text": "A guard warning when hooks are enabled but not enforced."\n      }\n    },\n    {\n      "id": "op-runGuardChecks",\n      "name": "runGuardChecks",\n      "what": "Runs all guard checks and returns a consolidated report.",\n      "inputs": [\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "VersionGuard configuration."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory to inspect."\n        }\n      ],\n      "outputs": {\n        "text": "A guard report with all findings."\n      }\n    },\n    {\n      "id": "op-initConfig",\n      "name": "initConfig",\n      "what": "Initializes a new VersionGuard config file in a project.",\n      "inputs": [\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Project directory where the config should be created."\n        }\n      ],\n      "outputs": {\n        "text": "The path to the created config file."\n      }\n    },\n    {\n      "id": "op-createTag",\n      "name": "createTag",\n      "what": "Creates a release tag and optionally fixes version state first.",\n      "inputs": [\n        {\n          "name": "version",\n          "type": "unknown",\n          "required": true,\n          "description": "Version to embed in the new tag name."\n        },\n        {\n          "name": "message",\n          "type": "unknown",\n          "required": true,\n          "description": "Custom annotated tag message."\n        },\n        {\n          "name": "autoFix",\n          "type": "unknown",\n          "required": true,\n          "description": "Whether to auto-fix version mismatches before tagging."\n        },\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "Loaded VersionGuard configuration used for validation and fixes."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory where git commands should run."\n        }\n      ],\n      "outputs": {\n        "text": "The tagging outcome and any actions performed along the way."\n      }\n    },\n    {\n      "id": "op-validateTagForPush",\n      "name": "validateTagForPush",\n      "what": "Validates that a local tag is safe to push to the default remote.",\n      "inputs": [\n        {\n          "name": "tagName",\n          "type": "unknown",\n          "required": true,\n          "description": "Name of the tag to validate."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory where git commands should run."\n        }\n      ],\n      "outputs": {\n        "text": "A validation result with an optional suggested fix command."\n      }\n    },\n    {\n      "id": "op-validateVersion",\n      "name": "validateVersion",\n      "what": "Validates a version string against the active versioning strategy.",\n      "inputs": [\n        {\n          "name": "version",\n          "type": "unknown",\n          "required": true,\n          "description": "Version string to validate."\n        },\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "VersionGuard configuration that selects the validation rules."\n        }\n      ],\n      "outputs": {\n        "text": "The validation result for the provided version."\n      }\n    },\n    {\n      "id": "op-runWizard",\n      "name": "runWizard",\n      "what": "Runs the interactive setup wizard.",\n      "inputs": [\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Project directory to initialize."\n        }\n      ],\n      "outputs": {\n        "text": "The path to the created config file, or `null` if cancelled."\n      }\n    },\n    {\n      "id": "op-runHeadless",\n      "name": "runHeadless",\n      "what": "Initializes VersionGuard non-interactively using CLI flags.",\n      "inputs": [\n        {\n          "name": "options",\n          "type": "unknown",\n          "required": true,\n          "description": "Headless initialization options."\n        }\n      ],\n      "outputs": {\n        "text": "The path to the created config file."\n      }\n    },\n    {\n      "id": "op-createProgram",\n      "name": "createProgram",\n      "what": "Creates the VersionGuard CLI program definition.",\n      "inputs": [],\n      "outputs": {\n        "text": "A configured Commander program for the VersionGuard CLI."\n      }\n    },\n    {\n      "id": "op-runCli",\n      "name": "runCli",\n      "what": "Parses CLI arguments and executes the matching command.",\n      "inputs": [\n        {\n          "name": "argv",\n          "type": "unknown",\n          "required": true,\n          "description": "Full argument vector to parse."\n        }\n      ]\n    },\n    {\n      "id": "op-createTempProject",\n      "name": "createTempProject",\n      "what": "Creates a temporary project directory with a minimal `package.json` fixture.",\n      "inputs": [],\n      "outputs": {\n        "text": "The absolute path to the temporary project directory."\n      }\n    },\n    {\n      "id": "op-initGitRepo",\n      "name": "initGitRepo",\n      "what": "Initializes a git repository in a fixture directory with a first commit.",\n      "inputs": [\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Absolute path to the fixture repository."\n        }\n      ]\n    },\n    {\n      "id": "op-createBareRemote",\n      "name": "createBareRemote",\n      "what": "Creates a bare git repository to use as a remote in integration tests.",\n      "inputs": [],\n      "outputs": {\n        "text": "The absolute path to the new bare repository."\n      }\n    }\n  ],\n  "constraints": [],\n  "workflows": [],\n  "configSchema": [\n    {\n      "key": "ManifestConfig.source",\n      "type": "ManifestSourceType",\n      "description": "Manifest file to read the version from.  Use `\'auto\'` for file-existence detection or a specific filename.",\n      "default": "\'auto\'"\n    },\n    {\n      "key": "ManifestConfig.path",\n      "type": "string | undefined",\n      "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.",\n      "default": "undefined (uses the provider\'s built-in default)"\n    },\n    {\n      "key": "ManifestConfig.regex",\n      "type": "string | undefined",\n      "description": "Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string.",\n      "default": "undefined"\n    },\n    {\n      "key": "SemVerConfig.allowVPrefix",\n      "type": "boolean",\n      "description": "Tolerates a leading `v` prefix (e.g. `v1.2.3`).  When enabled the prefix is stripped before parsing.",\n      "default": "false"\n    },\n    {\n      "key": "SemVerConfig.allowBuildMetadata",\n      "type": "boolean",\n      "description": "Permits `+build` metadata on version strings.",\n      "default": "true"\n    },\n    {\n      "key": "SemVerConfig.requirePrerelease",\n      "type": "boolean",\n      "description": "Requires every version to carry a prerelease label.",\n      "default": "false"\n    },\n    {\n      "key": "CalVerConfig.format",\n      "type": "CalVerFormat",\n      "description": "Calendar format used when parsing and validating versions."\n    },\n    {\n      "key": "CalVerConfig.preventFutureDates",\n      "type": "boolean",\n      "description": "Rejects versions that point to a future date.",\n      "default": "true"\n    },\n    {\n      "key": "CalVerConfig.strictMutualExclusion",\n      "type": "boolean | undefined",\n      "description": "Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens.",\n      "default": "true"\n    },\n    {\n      "key": "SyncConfig.files",\n      "type": "string[]",\n      "description": "File globs or paths that should be scanned for version updates."\n    },\n    {\n      "key": "SyncConfig.patterns",\n      "type": "SyncPattern[]",\n      "description": "Replacement patterns applied to matching files."\n    },\n    {\n      "key": "ChangelogConfig.enabled",\n      "type": "boolean",\n      "description": "Enables changelog validation.",\n      "default": "false"\n    },\n    {\n      "key": "ChangelogConfig.file",\n      "type": "string",\n      "description": "Path to the changelog file to inspect."\n    },\n    {\n      "key": "ChangelogConfig.strict",\n      "type": "boolean",\n      "description": "Treats changelog problems as hard failures.",\n      "default": "false"\n    },\n    {\n      "key": "ChangelogConfig.requireEntry",\n      "type": "boolean",\n      "description": "Requires an entry for the current version.",\n      "default": "false"\n    },\n    {\n      "key": "GitHooksConfig.\'pre-commit\'",\n      "type": "boolean",\n      "description": "Enables validation during the `pre-commit` hook.",\n      "default": "false"\n    },\n    {\n      "key": "GitHooksConfig.\'pre-push\'",\n      "type": "boolean",\n      "description": "Enables validation during the `pre-push` hook.",\n      "default": "false"\n    },\n    {\n      "key": "GitHooksConfig.\'post-tag\'",\n      "type": "boolean",\n      "description": "Enables follow-up tasks after a tag is created.",\n      "default": "false"\n    },\n    {\n      "key": "GitConfig.hooks",\n      "type": "GitHooksConfig",\n      "description": "Hook toggles used by the CLI and validation workflow."\n    },\n    {\n      "key": "GitConfig.enforceHooks",\n      "type": "boolean",\n      "description": "Fails validation when required hooks are missing.",\n      "default": "false"\n    },\n    {\n      "key": "VersioningConfig.type",\n      "type": "VersioningType",\n      "description": "Versioning strategy used for the project."\n    },\n    {\n      "key": "VersioningConfig.schemeRules",\n      "type": "SchemeRules | undefined",\n      "description": "Scheme-level validation rules applied regardless of versioning type.",\n      "default": "`{ maxNumericSegments: 3, allowedModifiers: [\'dev\', \'alpha\', \'beta\', \'rc\'] }`"\n    },\n    {\n      "key": "VersioningConfig.semver",\n      "type": "SemVerConfig | undefined",\n      "description": "SemVer-specific settings when `type` is `\'semver\'`.",\n      "default": "`{ allowVPrefix: false, allowBuildMetadata: true, requirePrerelease: false }`"\n    },\n    {\n      "key": "VersioningConfig.calver",\n      "type": "CalVerConfig | undefined",\n      "description": "CalVer-specific settings when `type` is `\'calver\'`.",\n      "default": "undefined"\n    },\n    {\n      "key": "VersionGuardConfig.versioning",\n      "type": "VersioningConfig",\n      "description": "Active versioning settings."\n    },\n    {\n      "key": "VersionGuardConfig.manifest",\n      "type": "ManifestConfig",\n      "description": "Version source manifest settings.",\n      "default": "`{ source: \'auto\' }`"\n    },\n    {\n      "key": "VersionGuardConfig.sync",\n      "type": "SyncConfig",\n      "description": "Synchronization settings for mirrored version strings."\n    },\n    {\n      "key": "VersionGuardConfig.changelog",\n      "type": "ChangelogConfig",\n      "description": "Changelog validation settings."\n    },\n    {\n      "key": "VersionGuardConfig.git",\n      "type": "GitConfig",\n      "description": "Git enforcement settings."\n    },\n    {\n      "key": "VersionGuardConfig.ignore",\n      "type": "string[]",\n      "description": "Files or patterns excluded from validation."\n    },\n    {\n      "key": "CkmConfigEntry.key",\n      "type": "string",\n      "description": "Dotted key path (e.g., `\'CalVerConfig.format\'`)."\n    },\n    {\n      "key": "CkmConfigEntry.type",\n      "type": "string",\n      "description": "TypeScript type."\n    },\n    {\n      "key": "CkmConfigEntry.description",\n      "type": "string",\n      "description": "Description from TSDoc."\n    },\n    {\n      "key": "CkmConfigEntry.default",\n      "type": "string | undefined",\n      "description": "Default value if specified via `@defaultValue`."\n    },\n    {\n      "key": "InitOptions.cwd",\n      "type": "string",\n      "description": "Working directory path."\n    },\n    {\n      "key": "InitOptions.type",\n      "type": "\\"semver\\" | \\"calver\\" | undefined",\n      "description": "Versioning type (semver or calver)."\n    },\n    {\n      "key": "InitOptions.format",\n      "type": "string | undefined",\n      "description": "CalVer format string."\n    },\n    {\n      "key": "InitOptions.allowVPrefix",\n      "type": "boolean | undefined",\n      "description": "Allow v-prefix on SemVer versions."\n    },\n    {\n      "key": "InitOptions.allowBuildMetadata",\n      "type": "boolean | undefined",\n      "description": "Allow build metadata on SemVer versions."\n    },\n    {\n      "key": "InitOptions.requirePrerelease",\n      "type": "boolean | undefined",\n      "description": "Require prerelease labels on SemVer versions."\n    },\n    {\n      "key": "InitOptions.manifest",\n      "type": "string | undefined",\n      "description": "Manifest source type."\n    },\n    {\n      "key": "InitOptions.hooks",\n      "type": "boolean | undefined",\n      "description": "Whether to install git hooks."\n    },\n    {\n      "key": "InitOptions.changelog",\n      "type": "boolean | undefined",\n      "description": "Whether to enable changelog validation."\n    },\n    {\n      "key": "InitOptions.yes",\n      "type": "boolean | undefined",\n      "description": "Accept defaults without prompting."\n    },\n    {\n      "key": "InitOptions.force",\n      "type": "boolean | undefined",\n      "description": "Overwrite existing config."\n    }\n  ]\n}\n';
+const llmsRaw = "# @codluv/versionguard\n> Strict versioning enforcement for SemVer and CalVer — language-agnostic manifest support, git hooks, changelog validation, and file sync\n> Version: 0.5.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\n89 functions, 52 types\n\n- getSemVerConfig() — Resolves the SemVer config from a VersionGuard config.\n- getCalVerConfig() — Extracts the CalVer config from a VersionGuard config, throwing if missing.\n- validateModifier() — Validates a pre-release / modifier tag against the allowed modifiers list.\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- createCkmEngine() — Creates a CKM engine from a parsed manifest.\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- 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- SemVerConfig — Configures SemVer validation rules.\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- CkmConcept — A domain concept extracted from an exported interface or type.\n- CkmProperty — A property within a concept.\n- CkmOperation — A user-facing operation extracted from an exported function.\n- CkmInput — A function parameter within an operation.\n- CkmConstraint — A constraint enforced by the tool.\n- CkmWorkflow — A multi-step workflow for a common goal.\n- CkmConfigEntry — A config schema entry with type, description, and default.\n- CkmManifest — The complete Codebase Knowledge Manifest.\n- CkmTopic — An auto-generated topic derived from CKM data.\n- CkmEngine — The CKM engine — provides topic derivation, filtering, and output formatting.\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- 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);
@@ -30,6 +32,9 @@ async function runWizard(cwd) {
     return null;
   }
   let format;
+  let allowVPrefix = false;
+  let allowBuildMetadata = true;
+  let requirePrerelease = false;
   if (type === "calver") {
     const selected = await selectCalVerFormat();
     if (!selected) {
@@ -37,6 +42,15 @@ async function runWizard(cwd) {
       return null;
     }
     format = selected;
+  } else {
+    const semverOptions = await selectSemVerOptions();
+    if (!semverOptions) {
+      p.outro("Setup cancelled.");
+      return null;
+    }
+    allowVPrefix = semverOptions.allowVPrefix;
+    allowBuildMetadata = semverOptions.allowBuildMetadata;
+    requirePrerelease = semverOptions.requirePrerelease;
   }
   const manifest = await selectManifest(cwd);
   if (manifest === null) {
@@ -62,6 +76,9 @@ async function runWizard(cwd) {
   const config = buildConfig({
     type,
     format,
+    allowVPrefix,
+    allowBuildMetadata,
+    requirePrerelease,
     manifest: manifest === "auto" ? void 0 : manifest,
     hooks,
     changelog
@@ -73,12 +90,17 @@ 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",
     format: options.format,
+    allowVPrefix: options.allowVPrefix ?? false,
+    allowBuildMetadata: options.allowBuildMetadata ?? true,
+    requirePrerelease: options.requirePrerelease ?? false,
     manifest: options.manifest,
     hooks: options.hooks ?? true,
     changelog: options.changelog ?? true
@@ -118,6 +140,32 @@ async function selectCalVerFormat() {
   }
   return preset;
 }
+async function selectSemVerOptions() {
+  const customize = await p.confirm({
+    message: "Customize SemVer rules? (defaults work for most projects)",
+    initialValue: false
+  });
+  if (p.isCancel(customize)) return null;
+  if (!customize) {
+    return { allowVPrefix: false, allowBuildMetadata: true, requirePrerelease: false };
+  }
+  const allowVPrefix = await p.confirm({
+    message: "Allow v-prefix? (e.g., v1.2.3)",
+    initialValue: false
+  });
+  if (p.isCancel(allowVPrefix)) return null;
+  const allowBuildMetadata = await p.confirm({
+    message: "Allow build metadata? (e.g., 1.2.3+build.123)",
+    initialValue: true
+  });
+  if (p.isCancel(allowBuildMetadata)) return null;
+  const requirePrerelease = await p.confirm({
+    message: "Require prerelease labels? (e.g., 1.2.3-alpha.1)",
+    initialValue: false
+  });
+  if (p.isCancel(requirePrerelease)) return null;
+  return { allowVPrefix, allowBuildMetadata, requirePrerelease };
+}
 async function selectManifest(cwd) {
   const detected = [];
   const checks = [
@@ -149,17 +197,19 @@ async function selectManifest(cwd) {
   return result;
 }
 function buildConfig(input) {
-  const config = {
-    versioning: {
-      type: input.type,
-      ...input.type === "calver" && input.format ? {
-        calver: {
-          format: input.format,
-          preventFutureDates: true
-        }
-      } : {}
+  const versioning = {
+    type: input.type,
+    semver: {
+      allowVPrefix: input.allowVPrefix,
+      allowBuildMetadata: input.allowBuildMetadata,
+      requirePrerelease: input.requirePrerelease
+    },
+    calver: {
+      format: input.format ?? "YYYY.MM.PATCH",
+      preventFutureDates: true
     }
   };
+  const config = { versioning };
   if (input.manifest) {
     config.manifest = { source: input.manifest };
   }
@@ -219,6 +269,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,23 +278,35 @@ 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("--allow-v-prefix", "SemVer: allow v-prefix (e.g., v1.2.3)").option("--no-build-metadata", "SemVer: disallow +build metadata").option("--require-prerelease", "SemVer: require prerelease labels").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;
+        const isHeadless = options.yes || options.type || options.format || options.manifest || options.allowVPrefix || options.buildMetadata === false || options.requirePrerelease;
         let configPath;
         if (isHeadless) {
           configPath = runHeadless({
             cwd: options.cwd,
             type: options.type,
             format: options.format,
+            allowVPrefix: options.allowVPrefix,
+            allowBuildMetadata: options.buildMetadata,
+            requirePrerelease: options.requirePrerelease,
             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 +333,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 +386,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 +478,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 +530,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 +545,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 +586,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 +614,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 +638,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 +674,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 +684,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 +702,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();