### runWizard - Interactive Setup

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/SKILL-versionguard/references/API-REFERENCE.md

Runs the interactive setup wizard for VersionGuard.

```APIDOC
## `runWizard`

### Description
Runs the interactive setup wizard.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const configPath = await runWizard(process.cwd());
```

### Response
#### Success Response (string | null)
- **configPath** (string | null) - The path to the created config file, or `null` if cancelled.

#### Response Example
```json
"/path/to/versionguard.config.json"
```
```

--------------------------------

### Run Example Blocks as Tests with Forge-TS

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/faq.mdx

This command executes the example blocks within your project as tests using the forge-ts CLI. Ensure forge-ts is installed and configured in your project.

```bash
npx forge-ts test
```

--------------------------------

### Install and Initialize VersionGuard

Source: https://github.com/kryptobaseddev/versionguard/blob/main/README.md

Commands to install the VersionGuard package and initialize the project configuration and git hooks.

```bash
npm install -D @codluv/versionguard@latest
vg init
vg hooks install
```

--------------------------------

### Run Setup Wizard and Headless Initialization

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Provides methods to run an interactive setup wizard or initialize VersionGuard non-interactively using configuration objects.

```typescript
const configPath = await runWizard(process.cwd());
const headlessConfig = runHeadless({ cwd: process.cwd(), type: 'calver', format: 'YYYY.M.MICRO' });
```

--------------------------------

### Configure package.json prepare script

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Examples of how to add the VersionGuard hook installation to the npm prepare script, either as a standalone command or chained with existing build processes.

```json
{
  "scripts": {
    "prepare": "versionguard hooks install"
  }
}
```

```json
{
  "scripts": {
    "prepare": "npm run build && versionguard hooks install"
  }
}
```

--------------------------------

### Project Validation and Setup Functions

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/index.mdx

Functions for validating project state, running setup wizards, and initializing the CLI.

```APIDOC
## POST /api/validate

### Description
Validates the current project state against the supplied configuration.

### Method
POST

### Endpoint
/api/validate

### Parameters
#### Request Body
- **configuration** (object) - Optional - The configuration object to validate against.

### Request Example
{
  "configuration": {
    "versioningStrategy": "semver"
  }
}

### Response
#### Success Response (200)
- **isValid** (boolean) - Indicates if the project state is valid.
- **errors** (array) - A list of validation errors, if any.

#### Response Example
{
  "isValid": false,
  "errors": ["Missing versioning strategy in configuration"]
}

## POST /api/runWizard

### Description
Runs the interactive setup wizard.

### Method
POST

### Endpoint
/api/runWizard

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the wizard has run.

#### Response Example
{
  "message": "Setup wizard completed successfully."
}

## POST /api/runHeadless

### Description
Initializes VersionGuard non-interactively using CLI flags.

### Method
POST

### Endpoint
/api/runHeadless

### Parameters
#### Request Body
- **cliFlags** (object) - Required - An object containing CLI flags and their values.

### Request Example
{
  "cliFlags": {
    "--strategy": "semver",
    "--init": true
  }
}

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating non-interactive initialization.

#### Response Example
{
  "message": "VersionGuard initialized non-interactively."
}
```

--------------------------------

### Initialize VersionGuard and Install Hooks

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Commands to install VersionGuard as a development dependency and initialize the configuration and Git hooks in a project.

```bash
npm install -D @codluv/versionguard
npx versionguard init
```

--------------------------------

### runWizard()

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Runs the interactive setup wizard.

```APIDOC
## runWizard()

### Description
Runs the interactive setup wizard.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
- **cwd** (string) - Required - The current working directory.

### Request Example
```typescript
const configPath = await runWizard(process.cwd());
```

### Response
#### Success Response (200)
- **configPath** (string) - The path to the generated configuration file.

#### Response Example
```json
"/path/to/.versionguard.json"
```
```

--------------------------------

### Install @codluv/versionguard

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/getting-started.mdx

Installs the @codluv/versionguard package as a development dependency using npm.

```bash
npm install -D @codluv/versionguard
```

--------------------------------

### POST /init-wizard/config

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.mdx

Configures the initialization parameters for the VersionGuard project setup.

```APIDOC
## POST /init-wizard/config

### Description
Configures the project versioning strategy and initialization preferences.

### Method
POST

### Endpoint
/init-wizard/config

### Parameters
#### Request Body
- **type** (string) - Optional - Versioning type (semver or calver).
- **format** (string) - Optional - CalVer format string.
- **allowVPrefix** (boolean) - Optional - Allow v-prefix on SemVer versions.
- **allowBuildMetadata** (boolean) - Optional - Allow build metadata on SemVer versions.
- **requirePrerelease** (boolean) - Optional - Require prerelease labels on SemVer versions.
- **manifest** (string) - Optional - Manifest source type.
- **hooks** (boolean) - Optional - Whether to install git hooks.
- **changelog** (boolean) - Optional - Whether to enable changelog validation.
- **yes** (boolean) - Optional - Accept defaults without prompting.
- **force** (boolean) - Optional - Overwrite existing config.

### Request Example
{
  "type": "semver",
  "allowVPrefix": true,
  "hooks": true,
  "yes": true
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of configuration application.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### VersionGuard CLI Hooks Install (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Implements the 'versionguard hooks install' CLI command. It reads the VersionGuard configuration and invokes the installHooks function to set up the git hooks.

```typescript
function installHooksCommand(argv) {
  // Reads config, calls `installHooks()`
  // ... implementation details ...
}
```

--------------------------------

### Install Git Hooks with installHooks()

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Installs VersionGuard-managed Git hooks in a repository. This function uses the default configuration for Git hooks and the current working directory.

```typescript
import { getDefaultConfig, installHooks } from 'versionguard';

installHooks(getDefaultConfig().git, process.cwd());
```

--------------------------------

### Forge TS Configuration

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/configuration.mdx

Example of how to set up the forge-ts.config.ts file in your project root.

```APIDOC
## forge-ts.config.ts

Create a `forge-ts.config.ts` file in your project root:

```typescript
import { defineConfig } from "@forge-ts/core";

export default defineConfig({
  rootDir: ".",
  outDir: "docs/generated",
});
```
```

--------------------------------

### Install VersionGuard Git Hooks

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.mdx

The `installHooks` function installs VersionGuard-managed Git hooks into a specified repository directory. It requires Git configuration that defines which hooks to install.

```typescript
import { getDefaultConfig, installHooks, GitConfig } from 'versionguard';

const gitConfig: GitConfig = getDefaultConfig().git;
installHooks(gitConfig, process.cwd());
```

--------------------------------

### VersionGuard Configuration Example

Source: https://github.com/kryptobaseddev/versionguard/blob/main/README.md

A sample YAML configuration file demonstrating SemVer/CalVer settings, file synchronization patterns, and changelog enforcement rules.

```yaml
versioning:
  type: semver
  semver:
    allowVPrefix: false
    allowBuildMetadata: true
    requirePrerelease: false
  calver:
    format: "YYYY.MM.PATCH"
    preventFutureDates: true

sync:
  files:
    - "README.md"
    - "CHANGELOG.md"
  patterns:
    - regex: '(version\s*[=:]\s*["'])(.+?)(["'])'
      template: '$1{{version}}$3'
    - regex: '(##\s*\[)(.+?)(\])'
      template: '$1{{version}}$3'

changelog:
  enabled: true
  file: "CHANGELOG.md"
  strict: true
  requireEntry: true
  enforceStructure: false
  sections:
    - Added
    - Changed
    - Deprecated
    - Removed
    - Fixed
    - Security

scan:
  enabled: false
  allowlist: []

git:
  hooks:
    pre-commit: true
    pre-push: true
    post-tag: true
  enforceHooks: true

ignore:
  - "node_modules/**"
  - "dist/**"
  - ".git/**"
  - "*.lock"
```

--------------------------------

### Version Management

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/index.mdx

Functions related to determining version compatibility and running setup wizards.

```APIDOC
## canBump()

### Description
Determines whether a project can move from one version to another.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
canBump()
```

### Response
#### Success Response (200)
Type: Boolean

#### Response Example
```json
{
  "canBump": true
}
```
```

```APIDOC
## runWizard()

### Description
Runs the interactive setup wizard.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
runWizard()
```

### Response
#### Success Response (200)
Type: N/A (Function execution result)

#### Response Example
N/A
```

--------------------------------

### installHooks

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/functions.mdx

Installs VersionGuard-managed Git hooks in a repository.

```APIDOC
## installHooks(config, cwd)

### Description
Installs VersionGuard-managed Git hooks in a repository.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **config** (GitConfig) - Required - Git configuration that selects which hooks to install.
- **cwd** (string) - Optional - Repository directory where hooks should be installed.

### Request Example
```typescript
import { getDefaultConfig, installHooks } from 'versionguard';

installHooks(getDefaultConfig().git, process.cwd());
```

### Response
#### Success Response (200)
Void

#### Response Example
N/A
```

--------------------------------

### Install Git Hooks (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Installs VersionGuard git hooks by writing the generated hook scripts to the .git/hooks/ directory for each enabled hook. This function is part of the core hook infrastructure.

```typescript
function installHooks(config, cwd) {
  // Writes hook scripts to .git/hooks/ for each enabled hook
  // ... implementation details ...
}
```

--------------------------------

### Initialize Configuration File

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/llms-full.txt

Creates a new VersionGuard configuration file in the project directory. It writes either a bundled example or a generated default configuration.

```APIDOC
## initConfig()

### Description
Initializes a new VersionGuard config file in a project. This writes `.versionguard.yml` using the bundled example when available, otherwise it writes a generated default configuration.

### Parameters
- **cwd** (string) - Optional - Project directory where the config should be created.

### Returns
string - The path to the created config file.

### Example
```javascript
import { initConfig } from 'versionguard';

const configPath = initConfig(process.cwd());
```
```

--------------------------------

### Temporary Project and Git Setup (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/versionguard/api/functions.mdx

Functions for creating temporary project environments, initializing Git repositories, and setting up remotes. These are useful for testing and development.

```typescript
createTempProject() => string
initGitRepo(cwd: string) => void
createBareRemote() => string
addGitRemote(cwd: string, remotePath: string) => void
```

--------------------------------

### Configure VersionGuard Hooks

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Example configuration for the .versionguard.yml file to control which Git hooks are active and whether to enforce their presence.

```yaml
git:
  hooks:
    pre-commit: true
    pre-push: false
    post-tag: false
  enforceHooks: true
```

--------------------------------

### Example Usage of getVersionFeedback

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/getting-started.mdx

An example of how to use the getVersionFeedback function, likely part of the versionguard package, to check version compatibility. It takes current version, configuration, and previous version as input.

```typescript
const feedbackResult = getVersionFeedback('1.2.3', config, '1.2.2');
console.log(feedbackResult.valid);
```

--------------------------------

### Install Git Hooks (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/llms-full.txt

Installs VersionGuard-managed Git hooks into a repository. It safely appends VersionGuard's validation block to existing hooks from other tools, ensuring idempotency and clean removal. Requires Git configuration and an optional current working directory.

```typescript
import { GitConfig, getDefaultConfig, installHooks } from 'versionguard';

const config: GitConfig = getDefaultConfig().git;
const cwd: string = process.cwd();
installHooks(config, cwd);
```

--------------------------------

### Manage Git Hooks

Source: https://context7.com/kryptobaseddev/versionguard/llms.txt

CLI commands to install, uninstall, or verify the status of git hooks managed by VersionGuard.

```bash
npx versionguard hooks install
npx versionguard hooks uninstall
npx versionguard hooks status
```

--------------------------------

### Get Default Configuration with getDefaultConfig()

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Returns a deep-cloned copy of the built-in VersionGuard configuration. This provides a starting point for custom configurations.

```typescript
import { getDefaultConfig } from 'versionguard';

const config = getDefaultConfig();
```

--------------------------------

### Run Interactive Setup Wizard - TypeScript

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.mdx

Launches an interactive command-line wizard to set up VersionGuard for a project. It requires the current working directory as input and returns a Promise that resolves to the path of the created configuration file, or null if the wizard is cancelled.

```typescript
const configPath = await runWizard(process.cwd());
```

--------------------------------

### VersionGuard CLI Doctor (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Implements the 'versionguard doctor' CLI command, which provides a readiness report for the VersionGuard setup. It includes checks for the installation status of git hooks.

```typescript
function doctorCommand(argv) {
  // Readiness report including `hooksInstalled` status
  // ... implementation details ...
}
```

--------------------------------

### Update CLI Init Action to Auto-Install Hooks

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Modifies the CLI init command to automatically trigger hook installation if the project is a Git repository. It includes error handling for non-Git environments and updates the console output to guide users on setting up the 'prepare' lifecycle script.

```typescript
.action((options: { cwd: string }) => {
  try {
    const configPath = versionguard.initConfig(options.cwd);
    console.log(styles.success(`Created ${path.relative(options.cwd, configPath)}`));

    // Auto-install hooks if in a git repo
    const config = versionguard.getConfig(options.cwd);
    try {
      versionguard.installHooks(config.git, options.cwd);
      const enabledHooks = Object.entries(config.git.hooks)
        .filter(([, enabled]) => enabled)
        .map(([name]) => name);
      console.log(styles.success(`Git hooks installed (${enabledHooks.join(', ')})`));
    } catch {
      console.log(styles.dim('Skipped hook installation (not a git repository)'));
    }

    console.log('');
    console.log(styles.info('Next steps:'));
    console.log('  1. Edit .versionguard.yml to set your versioning type');
    console.log('  2. Add to package.json scripts: "prepare": "versionguard hooks install"');
    console.log('  3. Run: npx versionguard check');
  } catch (error) {
    console.error(styles.error(`${(error as Error).message}`));
    process.exit(1);
  }
});
```

--------------------------------

### Run versionguard CLI Help

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/SKILL-versionguard/SKILL.md

Executes the versionguard command-line interface to display its help message, showing available commands and options.

```bash
npx versionguard --help
```

--------------------------------

### VersionGuard CLI Initialization (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Handles the 'versionguard init' command. It creates the .versionguard.yml configuration file and provides instructions to the user on the next steps, including manually running 'hooks install'.

```typescript
function initCommand(argv) {
  // Creates .versionguard.yml, prints "next steps" telling user to manually run `hooks install`
  // ... implementation details ...
}
```

--------------------------------

### Get Version Source (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Resolves the version source provider for a project, similar to `resolveVersionSource` but specifically for getting the source object with a `getVersion` method.

```typescript
import { getVersionSource } from 'versionguard';

const source = getVersionSource({ source: 'package.json' }, process.cwd());
const version = source.getVersion(process.cwd());
```

--------------------------------

### Get Package.json Path (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Gets the `package.json` path for a given project directory. This is a utility function for locating the primary package manifest file.

```typescript
import { getPackageJsonPath } from 'versionguard';

const packagePath = getPackageJsonPath(process.cwd());
```

--------------------------------

### Initialization and CLI API

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/llms-full.txt

Functions for initializing VersionGuard, either interactively or non-interactively, and for running the CLI.

```APIDOC
## runWizard()

### Description
Runs the interactive setup wizard.
Walks the user through versioning type, CalVer format, manifest source, git hooks, and changelog configuration. Writes `.versionguard.yml` when done.

### Method
N/A (Helper Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const configPath = await runWizard(process.cwd());
```

### Response
#### Success Response (string | null)
- **configPath** (string | null) - The path to the created config file, or `null` if cancelled.

#### Response Example
```json
".versionguard.yml"
```
```

```APIDOC
## runHeadless()

### Description
Initializes VersionGuard non-interactively using CLI flags.
When `--yes` is passed, all defaults are used without prompting. Individual flags override specific defaults.

### Method
N/A (Helper Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const configPath = runHeadless({ cwd: process.cwd(), type: 'calver', format: 'YYYY.M.MICRO' });
```

### Response
#### Success Response (string)
- **configPath** (string) - The path to the created config file.

#### Response Example
```json
".versionguard.yml"
```
```

```APIDOC
## createProgram()

### Description
Creates the VersionGuard CLI program definition.
This function wires all commands, options, and handlers onto a fresh Commander program instance without parsing arguments yet.

### Method
N/A (Helper Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const program = createProgram();
console.log(program.name());
```

### Response
#### Success Response (Command)
- **program** (Command) - A configured Commander program for the VersionGuard CLI.

#### Response Example
```json
{
  "name": "versionguard"
}
```
```

```APIDOC
## runCli()

### Description
Parses CLI arguments and executes the matching command.
This helper delegates argument parsing to the Commander program created by `createProgram`. It resolves when the selected command finishes.

### Method
N/A (Helper Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const argv = ['node', 'versionguard', 'check'];
await runCli(argv);
```

### Response
#### Success Response (Promise<void>)
This function returns a Promise that resolves when the command execution is complete.

#### Response Example
N/A
```

--------------------------------

### Get Package Version (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Gets the version string from the project manifest. It supports auto-detection or explicit manifest sources, falling back to `package.json` for compatibility.

```typescript
import { getPackageVersion } from 'versionguard';

// Read from package.json (legacy fallback)
const version = getPackageVersion(process.cwd());

// Read from a configured manifest source
const versionAlt = getPackageVersion(process.cwd(), { source: 'Cargo.toml' });
```

--------------------------------

### Check Git Hook Installation with areHooksInstalled()

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Checks whether all VersionGuard-managed Git hooks are currently installed in the repository. It requires the current working directory to perform the check.

```typescript
import { areHooksInstalled } from 'versionguard';

const installed = areHooksInstalled(process.cwd());
```

--------------------------------

### initConfig()

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Initializes a new VersionGuard config file in a project.

```APIDOC
## initConfig()

### Description
Initializes a new VersionGuard config file in a project.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
- **process.cwd()** (string) - Required - The current working directory.

### Request Example
```typescript
import { initConfig } from 'versionguard';

const configPath = initConfig(process.cwd());
```

### Response
#### Success Response (200)
- **configPath** (string) - The path to the newly created config file.

#### Response Example
```json
"/path/to/.versionguard.json"
```
```

--------------------------------

### Development and Testing Commands

Source: https://github.com/kryptobaseddev/versionguard/blob/main/README.md

Standard commands for building, linting, and testing the project. Includes specific commands for running individual test files or specific test cases.

```bash
npm run lint
npm test
npm run build
npx vitest run src/__tests__/semver.test.ts
npx vitest run src/__tests__/calver.test.ts -t "increments patch-based versions"
```

--------------------------------

### Check if VersionGuard Git Hooks are Installed

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.mdx

The `areHooksInstalled` function verifies if all VersionGuard-managed Git hooks are currently installed in the specified repository directory. It returns `true` if all hooks are present.

```typescript
import { areHooksInstalled } from 'versionguard';

const installed: boolean = areHooksInstalled(process.cwd());
console.log(`Hooks installed: ${installed}`);
```

--------------------------------

### Check if Git Hooks are Installed (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Verifies if all managed VersionGuard git hooks are present and contain the 'versionguard' identifier in the .git/hooks/ directory. Returns a boolean indicating their installation status.

```typescript
function areHooksInstalled(cwd) {
  // Returns true if all managed hooks exist and contain "versionguard"
  // ... implementation details ...
}
```

--------------------------------

### CLI and Test Utilities

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.md

Helper functions for bootstrapping the CLI program and setting up test environments, including git repository initialization and file manipulation.

```typescript
createProgram(): Command;
runCli(argv?: string[]): Promise<void>;
createTempProject(): string;
initGitRepo(cwd: string): void;
writeTextFile(cwd: string, relativePath: string, content: string): string;
```

--------------------------------

### Initialize VersionGuard Configuration

Source: https://context7.com/kryptobaseddev/versionguard/llms.txt

Initializes a .versionguard.yml file using the CLI. Supports interactive wizards, headless CI modes, and specific versioning types like SemVer or CalVer.

```bash
npx versionguard init
npx versionguard init --type semver --hooks --changelog --yes
npx versionguard init --type calver --format "YYYY.M.MICRO" --yes
```

--------------------------------

### Project Initialization API

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/functions.mdx

APIs for initializing VersionGuard, either interactively or non-interactively.

```APIDOC
## runWizard(cwd)

### Description
Runs the interactive setup wizard for VersionGuard.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **cwd** (string) - Required - Project directory to initialize.

### Request Example
```ts
const configPath = await runWizard(process.cwd());
```

### Response
#### Success Response (200)
- **string** - The path to the created config file.
- **null** - If the wizard was cancelled.

#### Response Example
```json
"/path/to/versionguard.config.json"
```

## runHeadless(options)

### Description
Initializes VersionGuard non-interactively using provided options.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **options** (InitOptions) - Required - Headless initialization options.

### Request Example
```ts
const configPath = runHeadless({ cwd: process.cwd(), type: 'calver', format: 'YYYY.M.MICRO' });
```

### Response
#### Success Response (200)
- **string** - The path to the created config file.

#### Response Example
```json
"/path/to/versionguard.config.json"
```
```

--------------------------------

### Git Hook Management

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.md

Functions for managing Git hooks within a project. This includes installing and uninstalling hooks, checking if hooks are installed, finding the Git directory, and generating hook scripts for pre-commit, pre-push, and post-tag actions.

```typescript
installHooks(config: GitConfig, cwd?: string) => void
```

```typescript
uninstallHooks(cwd?: string) => void
```

```typescript
findGitDir(cwd: string) => string | null
```

```typescript
areHooksInstalled(cwd?: string) => boolean
```

```typescript
generateHookScript(hookName: "pre-commit" | "pre-push" | "post-tag") => string
```

--------------------------------

### Managing Git Hooks with TypeScript

Source: https://context7.com/kryptobaseddev/versionguard/llms.txt

Provides utilities for installing, uninstalling, and checking the status of git hooks within a project. These functions rely on the project's git configuration and the current working directory to manage hook installations.

```typescript
import {
  installHooks,
  uninstallHooks,
  areHooksInstalled,
  getConfig
} from '@codluv/versionguard';

const config = getConfig(process.cwd());

// Check if hooks are installed
console.log(areHooksInstalled(process.cwd())); // true/false

// Install hooks based on config
installHooks(config.git, process.cwd());

// Uninstall hooks
uninstallHooks(process.cwd());
```

--------------------------------

### runHeadless()

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/examples.mdx

Initializes VersionGuard non-interactively using CLI flags.

```APIDOC
## runHeadless()

### Description
Initializes VersionGuard non-interactively using CLI flags.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Request Body
- **options** (object) - Required - Options for headless initialization.
  - **cwd** (string) - Required - The current working directory.
  - **type** (string) - Required - The versioning strategy type (e.g., 'calver').
  - **format** (string) - Required - The version format string.

### Request Example
```typescript
const configPath = runHeadless({ cwd: process.cwd(), type: 'calver', format: 'YYYY.M.MICRO' });
```

### Response
#### Success Response (200)
- **configPath** (string) - The path to the generated configuration file.

#### Response Example
```json
"/path/to/.versionguard.json"
```
```

--------------------------------

### areHooksInstalled

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/functions.mdx

Checks whether all VersionGuard-managed hooks are installed.

```APIDOC
## areHooksInstalled(cwd)

### Description
Checks whether all VersionGuard-managed hooks are installed.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cwd** (string) - Optional - Repository directory to inspect.

### Request Example
```typescript
import { areHooksInstalled } from 'versionguard';

const installed = areHooksInstalled(process.cwd());
```

### Response
#### Success Response (200)
- **installed** (boolean) - `true` when every managed hook is installed.

#### Response Example
```json
true
```
```

--------------------------------

### Integrate VersionGuard in CI

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/git-hooks-integration-research.md

Example GitHub Actions workflow step to run VersionGuard in strict mode, ensuring all guard checks and policy enforcements are validated during CI.

```yaml
- run: npx versionguard validate --strict
```

--------------------------------

### getLatestVersion()

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.mdx

Gets the most recent released version from a changelog.

```APIDOC
## getLatestVersion()

### Description
Gets the most recent released version from a changelog.

### Parameters
- **changelogPath** (string) - Required - Path to the changelog file.

### Response
- **string | null** - The latest released version, or null.
```

--------------------------------

### Run Verification Commands - Bash

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/FEATURES.md

A sequence of bash commands to install dependencies, lint, test, build, and perform various checks for the VersionGuard project. These commands are crucial for validating the codebase and ensuring it meets the project's standards.

```bash
npm install
npm run lint
npm test
npm run build
npm run forge:check
npm run forge:doctor
node dist/cli.js validate
```

--------------------------------

### Find Git Directory (TypeScript)

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/llms-full.txt

Locates the nearest `.git` directory by traversing up the file system from a given starting directory. Returns the path to the `.git` directory or `null` if the root is reached without finding a repository. Requires the starting directory path.

```typescript
import { findGitDir } from 'versionguard';

const gitDir = findGitDir(process.cwd());
if (gitDir) {
  console.log(`Found Git directory: ${gitDir}`);
}
```

--------------------------------

### Regex Version Extraction for Python setup.py

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/research/language-agnostic-version-extraction.md

Extracts version strings from legacy Python setup.py files using regular expressions. This avoids executing arbitrary code, which is a security best practice.

```python
import re

def get_version(file_content):
    match = re.search(r"version\s*=\s*['\"]([^'\"]+)['\"]", file_content)
    return match.group(1) if match else None
```

--------------------------------

### InitOptions

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/guides/configuration.mdx

Options for initializing VersionGuard in a non-interactive (headless) mode.

```APIDOC
## InitOptions

Options for headless (non-interactive) initialization.

### Properties
- **cwd** (string) - Working directory path.
- **type** ('semver' | 'calver' | undefined) - Versioning type (semver or calver).
- **format** (string | undefined) - CalVer format string.
- **allowVPrefix** (boolean | undefined) - Allow v-prefix on SemVer versions.
- **allowBuildMetadata** (boolean | undefined) - Allow build metadata on SemVer versions.
- **requirePrerelease** (boolean | undefined) - Require prerelease labels on SemVer versions.
- **manifest** (string | undefined) - Manifest source type.
- **hooks** (boolean | undefined) - Whether to install git hooks.
- **changelog** (boolean | undefined) - Whether to enable changelog validation.
- **yes** (boolean | undefined) - Accept defaults without prompting.
- **force** (boolean | undefined) - Overwrite existing config.
```

--------------------------------

### Configuration and Utility Functions

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.mdx

Functions for loading, initializing, and managing VersionGuard configuration, along with other utility functions.

```APIDOC
## Configuration and Utility Functions

### Description
Provides functions for managing VersionGuard configuration, finding project roots, and handling errors.

### Functions

- **`getDefaultConfig()`**: Gets the default configuration.
- **`findConfig()`**: Finds the VersionGuard configuration file.
- **`loadConfig(filePath)`**: Loads configuration from a file path.
- **`getConfig()`**: Retrieves the current configuration.
- **`initConfig()`**: Initializes the configuration.
- **`findProjectRoot()`**: Finds the project root directory.
- **`formatNotProjectError(error)`**: Formats an error message for non-project scenarios.
- **`parse(version)`**: Parses a version string.
- **`validate(version)`**: Validates a version string.
- **`compare(versionA, versionB)`**: Compares two version strings.
- **`gt(versionA, versionB)`**: Checks if versionA is greater than versionB.
- **`lt(versionA, versionB)`**: Checks if versionA is less than versionB.
- **`eq(versionA, versionB)`**: Checks if versionA is equal to versionB.
- **`increment(version, releaseType)`**: Increments a version string.
- **`format(versionObject)`**: Formats a version object into a string.
- **`doctor()`**: Runs the doctor command to check project health.
- **`sync()`**: Synchronizes versions across the project.
- **`canBump()`**: Checks if a version bump is allowed.
- **`runWizard()`**: Starts the interactive versioning wizard.
- **`runHeadless()`**: Runs VersionGuard in headless mode.
- **`createProgram()`**: Creates the CLI program instance.
- **`runCli()`**: Runs the CLI application.
- **`shouldRunCli()`**: Determines if the CLI should run.
- **`getPackageJsonPath()`**: Gets the path to the package.json file.
- **`readPackageJson(filePath)`**: Reads and parses a package.json file.
- **`writePackageJson(filePath, data)`**: Writes data to a package.json file.
- **`getPackageVersion(packageJsonPath)`**: Gets the version from a package.json file.
- **`setPackageVersion(packageJsonPath, version)`**: Sets the version in a package.json file.
- **`getVersionSource(sourceConfig)`**: Gets a version source based on configuration.
- **`resolveVersionSource(versionSource)`**: Resolves a version source.
- **`detectManifests(dir)`**: Detects manifest files in a directory.
- **`validateVersion(version)`**: Validates a version string.
- **`validate(version)`**: Validates a version string.
- **`validateChangelog()`**: Validates the changelog file.
- **`getLatestVersion()`**: Gets the latest version from Git tags.
- **`addVersionEntry(entry)`**: Adds an entry to the changelog.
- **`isChangesetMangled(changeset)`**: Checks if a changeset is mangled.
- **`fixChangesetMangling(changeset)`**: Fixes mangled changesets.
- **`createCkmEngine()`**: Creates a CKM engine instance.
```

--------------------------------

### findGitDir

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/functions.mdx

Finds the nearest .git directory by walking up from a starting directory.

```APIDOC
## findGitDir(cwd)

### Description
Finds the nearest `.git` directory by walking up from a starting directory.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **cwd** (string) - Required - Directory to start searching from.

### Request Example
```typescript
import { findGitDir } from 'versionguard';

const gitDir = findGitDir(process.cwd());
```

### Response
#### Success Response (200)
- **gitDir** (string | null) - The resolved `.git` directory path, or `null` when none is found.

#### Response Example
```json
"/path/to/.git"
```
```

--------------------------------

### initGitRepo - Initialize Git Repository

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/SKILL-versionguard/references/API-REFERENCE.md

Initializes a Git repository in a specified directory and creates an initial commit.

```APIDOC
## `initGitRepo`

### Description
Initializes a git repository in a fixture directory with a first commit.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cwd** (string) - Required. Absolute path to the directory where the Git repository should be initialized.

### Request Example
```typescript
initGitRepo(cwd);
```

### Response
#### Success Response (void)
This function does not return a value upon successful execution.

#### Response Example
(No response body for void functions)
```

--------------------------------

### Git Hooks Management

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.md

Functions for installing, uninstalling, and managing Git hooks.

```APIDOC
## `installHooks()`

### Description
Installs the necessary Git hooks for the project.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **void** - Indicates successful installation.

#### Response Example
N/A
```

```APIDOC
## `uninstallHooks()`

### Description
Uninstalls the Git hooks previously installed by VersionGuard.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **void** - Indicates successful uninstallation.

#### Response Example
N/A
```

```APIDOC
## `findGitDir()`

### Description
Finds the root directory of the Git repository.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **string | null** - The path to the Git directory, or null if not found.

#### Response Example
N/A
```

```APIDOC
## `areHooksInstalled()`

### Description
Checks if the VersionGuard Git hooks are currently installed.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** - True if hooks are installed, false otherwise.

#### Response Example
N/A
```

```APIDOC
## `generateHookScript()`

### Description
Generates the script content for a specific Git hook.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **string** - The generated script content for the Git hook.

#### Response Example
N/A
```

--------------------------------

### CLI and Program Initialization

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/index.mdx

Functions for running VersionGuard non-interactively and creating CLI program definitions.

```APIDOC
## runHeadless()

### Description
Initializes VersionGuard non-interactively using CLI flags.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
runHeadless()
```

### Response
#### Success Response (200)
Type: N/A (Function execution result)

#### Response Example
N/A
```

```APIDOC
## createProgram()

### Description
Creates the VersionGuard CLI program definition.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
createProgram()
```

### Response
#### Success Response (200)
Type: N/A (Program definition object)

#### Response Example
N/A
```

--------------------------------

### Generate test fixtures with createTempProject, initGitRepo, and writeTextFile

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/functions.mdx

Helper functions for creating temporary project environments, initializing git repositories, and writing files for testing purposes.

```typescript
const cwd = createTempProject();
initGitRepo(cwd);
writeTextFile(cwd, 'README.md', '# Fixture');
```

--------------------------------

### findConfig

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/functions.mdx

Searches for the nearest VersionGuard configuration file starting from the specified directory.

```APIDOC
## findConfig(cwd)

### Description
Finds the first supported VersionGuard config file in a directory.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { findConfig } from 'versionguard';

const configPath = findConfig(process.cwd());
```

### Response
#### Success Response (string | null)
The absolute path to the found config file, or `null` if no config file is found.

#### Response Example
```json
"/path/to/your/project/.versionguard.yml"
```
```

--------------------------------

### checkHookIntegrity

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/functions.mdx

Verifies that installed hook scripts match the expected content defined in the configuration.

```APIDOC
## checkHookIntegrity(config, cwd)

### Description
Verifies that installed hook scripts match the expected content.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { checkHookIntegrity } from './guard';

const warnings = checkHookIntegrity(config, process.cwd());
for (const w of warnings) console.warn(w.code, w.message);
```

### Response
#### Success Response (GuardWarning[])
An array of `GuardWarning` objects for each hook that has been tampered with.

#### Response Example
```json
[
  {
    "code": "HOOK_TAMPERED",
    "message": "Hook 'pre-commit' has been modified."
  }
]
```
```

--------------------------------

### Git Hooks Management

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/index.mdx

Functions for installing, uninstalling, and checking the status of Git hooks.

```APIDOC
## installHooks()

### Description
Installs VersionGuard-managed Git hooks in a repository.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
installHooks();
```

### Response
N/A (Function Execution)

## uninstallHooks()

### Description
Removes VersionGuard-managed Git hooks from a repository.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
uninstallHooks();
```

### Response
N/A (Function Execution)

## areHooksInstalled()

### Description
Checks whether all VersionGuard-managed hooks are installed.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
areHooksInstalled();
```

### Response
N/A (Function Execution)

## generateHookScript(hookName: string)

### Description
Generates the shell script content for a Git hook.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
- **hookName** (string) - Required - The name of the Git hook (e.g., 'commit-msg').

### Request Example
```javascript
generateHookScript('pre-commit');
```

### Response
N/A (Function Execution)

## checkHooksPathOverride()

### Description
Checks whether git hooks have been redirected away from the repository.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
checkHooksPathOverride();
```

### Response
N/A (Function Execution)

## checkHuskyBypass()

### Description
Checks whether the HUSKY environment variable is disabling hooks.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
checkHuskyBypass();
```

### Response
N/A (Function Execution)

## checkHookIntegrity()

### Description
Verifies that installed hook scripts match the expected content.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
checkHookIntegrity();
```

### Response
N/A (Function Execution)

## checkEnforceHooksPolicy()

### Description
Checks whether hooks are configured as required but not enforced.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
checkEnforceHooksPolicy();
```

### Response
N/A (Function Execution)
```

--------------------------------

### Initialize VersionGuard with runWizard or runHeadless

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/packages/api/functions.mdx

Provides methods to initialize VersionGuard either interactively via a wizard or non-interactively using configuration options. Both functions return the path to the generated configuration file.

```typescript
const configPath = await runWizard(process.cwd());
const headlessPath = runHeadless({ cwd: process.cwd(), type: 'calver', format: 'YYYY.M.MICRO' });
```

--------------------------------

### Manifest Version Management

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/llms-full.txt

Utilities for getting and setting project versions from manifest files.

```APIDOC
## getPackageVersion()

### Description
Gets the version string from the project manifest. Falls back to `package.json` if no manifest config is provided. Throws if the manifest file does not exist or lacks a version field.

### Method
`getPackageVersion(cwd?: string, manifest?: ManifestConfig) => string`

### Parameters
#### Path Parameters
- **cwd** (string) - Optional - Project directory containing the manifest.
- **manifest** (ManifestConfig) - Optional - Manifest configuration for language-agnostic support.

### Response
#### Success Response (string)
- **string** - The project version string.

### Request Example
```javascript
import { getPackageVersion } from 'versionguard';

// Read from package.json (legacy fallback)
const version = getPackageVersion(process.cwd());

// Read from a configured manifest source
const versionAlt = getPackageVersion(process.cwd(), { source: 'Cargo.toml' });
```

## setPackageVersion()

### Description
Sets the version field in the project manifest. Falls back to `package.json` if no manifest config is provided. Reads the existing document, replaces the version, and writes the file back.

### Method
`setPackageVersion(version: string, cwd?: string, manifest?: ManifestConfig) => void`

### Parameters
#### Path Parameters
- **version** (string) - Required - Version string to persist.
- **cwd** (string) - Optional - Project directory containing the manifest.
- **manifest** (ManifestConfig) - Optional - Manifest configuration for language-agnostic support.

### Request Example
```javascript
import { setPackageVersion } from 'versionguard';

// Write to package.json (legacy fallback)
setPackageVersion('1.2.3', process.cwd());

// Write to a configured manifest source
setPackageVersion('1.2.3', process.cwd(), { source: 'Cargo.toml' });
```
```

--------------------------------

### Run Headless Initialization - TypeScript

Source: https://github.com/kryptobaseddev/versionguard/blob/main/docs/api-reference.mdx

Initializes VersionGuard non-interactively using provided options, typically from CLI flags. This function takes an options object, including the project directory and versioning type/format, and returns the path to the created configuration file.

```typescript
const configPath = runHeadless({ cwd: process.cwd(), type: 'calver', format: 'YYYY.M.MICRO' });
```