Version Management

/**
 * Ensure a GitBook version exists, installing if necessary
 * @param bookRoot - Path to GitBook project directory
 * @param version - Version string, tag, or condition (e.g., '2.6.7', 'latest', '*')
 * @param opts - Options for version resolution
 * @returns Promise resolving to version object
 */
function ensure(bookRoot, version, opts): Promise<VersionObject>;

/**
 * Get version information without installing
 * @param bookRoot - Path to GitBook project directory  
 * @param version - Version string, tag, or condition
 * @returns Promise resolving to version object
 */
function get(bookRoot, version): Promise<VersionObject>;

/**
 * Extract GitBook version requirement from book.json
 * @param bookRoot - Path to GitBook project directory
 * @returns Version string from book.json or '*' if not specified
 */
function getBookVersion(bookRoot): string;

/**
 * Ensure version exists and load GitBook instance
 * @param bookRoot - Path to GitBook project directory
 * @param version - Version string, tag, or condition
 * @param opts - Options for version resolution
 * @returns Promise resolving to GitBook instance
 */
function ensureAndLoad(bookRoot, version, opts): Promise<GitBookInstance>;

/**
 * Load GitBook instance for specific version
 * @param version - Version string or version object
 * @returns Promise resolving to GitBook instance
 */
function load(version): Promise<GitBookInstance>;

const manager = require('gitbook-cli');

// Ensure latest version is available
const version = await manager.ensure(process.cwd(), 'latest');
console.log('Using GitBook version:', version.version);

// Get version from book.json without installing
const bookVersion = manager.getBookVersion('./my-book');
console.log('Book requires GitBook:', bookVersion);

// Load GitBook instance
const gitbook = await manager.load('2.6.7');
console.log('Available commands:', gitbook.commands.length);

/**
 * Install GitBook version from NPM registry
 * @param version - Version string, tag, or condition to install
 * @returns Promise resolving to installed version string
 */
function install(version): Promise<string>;

/**
 * Get available versions from NPM registry
 * @returns Promise resolving to available versions object
 */
function available(): Promise<AvailableVersions>;

// Install specific version
const installedVersion = await manager.install('2.6.7');
console.log('Installed GitBook version:', installedVersion);

// Get available versions
const available = await manager.available();
console.log('Latest stable:', available.tags.latest);
console.log('All versions:', available.versions);

/**
 * List all locally installed GitBook versions
 * @returns Array of version objects sorted by version
 */
function versions(): VersionObject[];

/**
 * Remove locally installed GitBook version
 * @param version - Version string or tag to remove
 * @returns Promise resolving when removal is complete
 */
function uninstall(version): Promise<void>;

/**
 * Create alias linking version name to local folder
 * @param name - Alias name for the version
 * @param folder - Local folder path containing GitBook installation
 * @returns Promise resolving when link is created
 */
function link(name, folder): Promise<void>;

// List installed versions
const localVersions = manager.versions();
localVersions.forEach(v => {
  console.log(`${v.name} (${v.version}) at ${v.path}`);
  if (v.link) console.log(`  -> symlinked to ${v.link}`);
});

// Remove version
await manager.uninstall('2.5.0');
console.log('Version 2.5.0 removed');

// Create development alias
await manager.link('dev', '/path/to/local/gitbook');
console.log('Created alias "dev" pointing to local development version');

/**
 * Update to latest version of specified tag
 * @param tag - Release tag to update to (default: 'latest')
 * @returns Promise resolving to new version string or null if no update
 */
function update(tag): Promise<string | null>;

// Update to latest stable version
const newVersion = await manager.update('latest');
if (newVersion) {
  console.log('Updated to GitBook version:', newVersion);
} else {
  console.log('Already on latest version');
}

// Update to latest beta
const betaVersion = await manager.update('beta');

/**
 * Check if a string is a valid tag (latest, pre, beta, alpha)
 * @param version - Version string to check
 * @returns true if version is a recognized tag
 */
function isTag(version): boolean;

/**
 * Validate if version satisfies GitBook CLI requirements (>1.x.x)
 * @param version - Version string to validate
 * @returns true if version is valid for GitBook CLI
 */
function isValid(version): boolean;

/**
 * Sort two versions with proper tag precedence
 * @param a - First version to compare
 * @param b - Second version to compare  
 * @returns -1 if a > b, 1 if a < b, 0 if equal
 */
function sort(a, b): number;

/**
 * Check if version satisfies a condition/range
 * @param version - Version string to check
 * @param condition - Semver condition or tag name
 * @param opts - Options object with acceptTagCondition flag
 * @returns true if version satisfies condition
 */
function satisfies(version, condition, opts): boolean;

/**
 * Extract prerelease tag from version (latest, beta, alpha, etc.)
 * @param version - Version string to analyze
 * @returns Release tag name
 */
function getTag(version): string;

const tags = require('gitbook-cli/lib/tags');

// Validate version
if (tags.isValid('2.6.7')) {
  console.log('Version is valid');
}

// Check if string is a tag
if (tags.isTag('latest')) {
  console.log('This is a release tag');
}

// Check version satisfaction  
if (tags.satisfies('2.6.7', '>2.0.0')) {
  console.log('Version meets requirements');
}

// Get release tag
const tag = tags.getTag('3.0.0-beta.1'); // Returns 'beta'

// Sort versions with proper tag precedence
const versions = ['2.6.7', '3.0.0-beta.1', 'latest'];
versions.sort(tags.sort);

try {
  const version = await manager.ensure(bookRoot, '999.0.0');
} catch (error) {
  if (error.message.includes('No version match')) {
    console.error('Version not found:', error.message);
  } else {
    console.error('Installation failed:', error.message);
  }
}