k0ntext 3.3.1 → 3.5.0

package/src/cli/version/checker.ts

@@ -0,0 +1,172 @@
+/**
+ * Version Checker
+ *
+ * Checks context files for outdated versions.
+ * Integrates with database for efficient caching.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import type { DatabaseClient } from '../../db/client.js';
+import { parseVersion, hasVersionMarker } from './parser.js';
+import { needsUpdate, getUpdateType } from './comparator.js';
+import type {
+  CheckOptions,
+  FileVersionStatus,
+  VersionCheckResult,
+  OutdatedFile
+} from './types.js';
+
+/**
+ * Tool to file path mappings
+ */
+const TOOL_FILES: Record<string, string[]> = {
+  claude: ['AI_CONTEXT.md', 'CLAUDE.md', '.claude/AI_CONTEXT.md'],
+  copilot: ['.github/copilot-instructions.md'],
+  cline: ['.clinerules'],
+  antigravity: ['.agent/README.md'],
+  windsurf: ['.windsurf/rules.md'],
+  aider: ['.aider.conf.yml'],
+  continue: ['.continue/config.json'],
+  cursor: ['.cursorrules'],
+  gemini: ['.gemini/config.md']
+};
+
+/**
+ * Check a single file for version status
+ *
+ * @param filePath - Full path to the file
+ * @param tool - Tool name
+ * @param currentVersion - Current k0ntext version
+ * @param db - Database client (optional, for modification detection)
+ * @returns File version status
+ */
+export async function checkSingleFile(
+  filePath: string,
+  tool: string,
+  currentVersion: string,
+  db?: DatabaseClient
+): Promise<FileVersionStatus> {
+  // Check if file exists
+  let exists = false;
+  let content = '';
+  try {
+    content = await fs.readFile(filePath, 'utf-8');
+    exists = true;
+  } catch {
+    // File doesn't exist
+  }
+
+  // Check for version marker
+  const hasMarker = hasVersionMarker(content);
+  const fileVersion = parseVersion(content);
+
+  // Determine if outdated
+  const isOutdated = fileVersion ? needsUpdate(fileVersion, currentVersion) : false;
+  const updateType = fileVersion ? getUpdateType(fileVersion, currentVersion) : 'none';
+
+  // Check if user modified (from database)
+  let userModified = false;
+  if (db && exists) {
+    const tracked = db.getGeneratedFileInfo(tool, filePath);
+    if (tracked?.userModified) {
+      userModified = true;
+    }
+  }
+
+  return {
+    tool,
+    filePath,
+    exists,
+    fileVersion,
+    hasMarker,
+    isOutdated,
+    updateType,
+    userModified
+  };
+}
+
+/**
+ * Check all context files for version status
+ *
+ * @param options - Check options
+ * @param db - Database client (optional)
+ * @returns Version check result
+ */
+export async function checkContextFiles(
+  options: CheckOptions,
+  db?: DatabaseClient
+): Promise<VersionCheckResult> {
+  const { projectRoot, currentVersion, tools: toolsToCheck } = options;
+
+  const tools = toolsToCheck || Object.keys(TOOL_FILES);
+  const results: VersionCheckResult = {
+    currentVersion,
+    checked: 0,
+    outdated: [],
+    upToDate: [],
+    noVersion: []
+  };
+
+  for (const tool of tools) {
+    const files = TOOL_FILES[tool] || [];
+    const toolName = tool;
+
+    for (const relativePath of files) {
+      const fullPath = path.join(projectRoot, relativePath);
+
+      const status = await checkSingleFile(fullPath, toolName, currentVersion, db);
+      results.checked++;
+
+      if (!status.exists) {
+        continue; // Skip non-existent files
+      }
+
+      if (status.isOutdated) {
+        results.outdated.push({
+          tool: status.tool,
+          filePath: status.filePath,
+          fileVersion: status.fileVersion || 'unknown',
+          currentVersion,
+          updateType: status.updateType,
+          userModified: status.userModified
+        });
+      } else if (status.hasMarker) {
+        results.upToDate.push(status);
+      } else {
+        results.noVersion.push(status);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Get all context file paths for a tool
+ *
+ * @param tool - Tool name
+ * @returns Array of file paths
+ */
+export function getToolFiles(tool: string): string[] {
+  return TOOL_FILES[tool] || [];
+}
+
+/**
+ * Check if a tool is supported
+ *
+ * @param tool - Tool name
+ * @returns True if supported
+ */
+export function isSupportedTool(tool: string): boolean {
+  return tool in TOOL_FILES;
+}
+
+/**
+ * Get all supported tools
+ *
+ * @returns Array of tool names
+ */
+export function getSupportedTools(): string[] {
+  return Object.keys(TOOL_FILES);
+}

package/src/cli/version/comparator.ts

@@ -0,0 +1,106 @@
+/**
+ * Version Comparator
+ *
+ * Semantic version comparison for detecting outdated files.
+ * Reuses logic from UpdateChecker for consistency.
+ */
+
+import type { UpdateType } from './types.js';
+
+/**
+ * Parse semantic version string into components
+ *
+ * @param version - Version string (e.g., "3.3.1")
+ * @returns Object with major, minor, patch components
+ */
+function parseSemver(version: string): { major: number; minor: number; patch: number } {
+  const parts = version.split('.').map(Number);
+
+  return {
+    major: parts[0] || 0,
+    minor: parts[1] || 0,
+    patch: parts[2] || 0
+  };
+}
+
+/**
+ * Compare two version strings
+ *
+ * @param a - First version string
+ * @param b - Second version string
+ * @returns Negative if a < b, positive if a > b, zero if equal
+ */
+export function compareVersions(a: string, b: string): number {
+  const [cMajor, cMinor, cPatch] = a.split('.').map(Number);
+  const [lMajor, lMinor, lPatch] = b.split('.').map(Number);
+
+  if (lMajor !== cMajor) return lMajor - cMajor;
+  if (lMinor !== cMinor) return lMinor - cMinor;
+  return lPatch - cPatch;
+}
+
+/**
+ * Check if a file version needs updating
+ *
+ * @param fileVersion - Version from the file
+ * @param currentVersion - Current k0ntext version
+ * @returns True if file is outdated
+ */
+export function needsUpdate(fileVersion: string, currentVersion: string): boolean {
+  if (fileVersion === currentVersion) return false;
+  return compareVersions(fileVersion, currentVersion) > 0;
+}
+
+/**
+ * Get the type of update needed
+ *
+ * @param fileVersion - Version from the file
+ * @param currentVersion - Current k0ntext version
+ * @returns Type of update: 'major', 'minor', 'patch', or 'none'
+ */
+export function getUpdateType(fileVersion: string, currentVersion: string): UpdateType {
+  if (fileVersion === currentVersion) return 'none';
+
+  const [cMajor, cMinor, cPatch] = fileVersion.split('.').map(Number);
+  const [lMajor, lMinor, lPatch] = currentVersion.split('.').map(Number);
+
+  if (lMajor > cMajor) return 'major';
+  if (lMinor > cMinor) return 'minor';
+  if (lPatch > cPatch) return 'patch';
+
+  return 'none';
+}
+
+/**
+ * Format update type as a human-readable string
+ *
+ * @param type - Update type
+ * @returns Formatted string (e.g., "Major (3.0.0 → 3.1.0)")
+ */
+export function formatUpdateType(type: UpdateType, from: string, to: string): string {
+  const emoji = {
+    major: '🚨',
+    minor: '✨',
+    patch: '🔧',
+    none: '✓'
+  }[type] || '→';
+
+  const label = {
+    major: 'Major',
+    minor: 'Minor',
+    patch: 'Patch',
+    none: 'Current'
+  }[type];
+
+  return `${emoji} ${label} (${from} → ${to})`;
+}
+
+/**
+ * Validate a version string format
+ *
+ * @param version - Version string to validate
+ * @returns True if valid semver format
+ */
+export function isValidVersion(version: string): boolean {
+  return /^\d+\.\d+\.\d+/.test(version);
+}

package/src/cli/version/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Version Detection Module
+ *
+ * Exports all version detection functionality.
+ */
+
+export * from './types.js';
+export * from './parser.js';
+export * from './comparator.js';
+export * from './checker.js';
+export * from './prompt.js';

package/src/cli/version/parser.ts

@@ -0,0 +1,101 @@
+/**
+ * Version Parser
+ *
+ * Parses version strings from generated context files.
+ * Supports multiple version marker formats used by k0ntext.
+ */
+
+/**
+ * Version marker patterns found in generated files
+ */
+const VERSION_PATTERNS = [
+  // Format: *Generated by k0ntext v3.3.1*
+  /\*Generated by k0ntext v(\d+\.\d+\.\d+[^*)]*)\*/,
+  // Format: > **Version:** 3.3.1
+  /\*\*Version:\*\*\s*(\d+\.\d+\.\d+[^,\s]*)/,
+  // Format: > Version: 3.3.1
+  /Version:\s*(\d+\.\d+\.\d+[^,\s]*)/,
+  // Format: "generator_version": "3.3.1"
+  /"generator_version":\s*"(\d+\.\d+\.\d+[^"]*)"/,
+  // Format: <!-- Version: 3.3.1 -->
+  /<!--\s*Version:\s*(\d+\.\d+\.\d+[^-\s]*)/,
+] as const;
+
+/**
+ * Parse version from file content
+ *
+ * @param content - File content to search for version
+ * @returns Version string if found, null otherwise
+ */
+export function parseVersion(content: string): string | null {
+  if (!content || typeof content !== 'string') {
+    return null;
+  }
+
+  for (const pattern of VERSION_PATTERNS) {
+    const match = content.match(pattern);
+    if (match && match[1]) {
+      return match[1].trim();
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if content has any version marker
+ *
+ * @param content - File content to check
+ * @returns True if any version pattern is found
+ */
+export function hasVersionMarker(content: string): boolean {
+  if (!content || typeof content !== 'string') {
+    return false;
+  }
+
+  return VERSION_PATTERNS.some(pattern => pattern.test(content));
+}
+
+/**
+ * Extract version from first N lines of a file
+ * Useful for quick checks without reading entire file
+ *
+ * @param content - File content (or first N lines)
+ * @param lines - Number of lines to check (default: 50)
+ * @returns Version string if found, null otherwise
+ */
+export function parseVersionFromHeader(content: string, lines = 50): string | null {
+  if (!content || typeof content !== 'string') {
+    return null;
+  }
+
+  // Only check first N lines
+  const linesToCheck = content.split('\n').slice(0, lines).join('\n');
+  return parseVersion(linesToCheck);
+}
+
+/**
+ * Get all version markers found in content
+ * Useful for debugging or validation
+ *
+ * @param content - File content to search
+ * @returns Array of found version strings
+ */
+export function findAllVersions(content: string): string[] {
+  if (!content || typeof content !== 'string') {
+    return [];
+  }
+
+  const versions: string[] = [];
+
+  for (const pattern of VERSION_PATTERNS) {
+    const matches = content.matchAll(new RegExp(pattern, 'g'));
+    for (const match of matches) {
+      if (match[1]) {
+        versions.push(match[1].trim());
+      }
+    }
+  }
+
+  return [...new Set(versions)]; // Deduplicate
+}

package/src/cli/version/prompt.ts

@@ -0,0 +1,208 @@
+/**
+ * Version Prompt
+ *
+ * Interactive prompts for version checking and regeneration.
+ */
+
+import chalk from 'chalk';
+import { confirm, select, checkbox } from '@inquirer/prompts';
+import type {
+  VersionCheckResult,
+  RegenerationPromptResult,
+  RegenerationChoice
+} from './types.js';
+import { formatUpdateType } from './comparator.js';
+
+/**
+ * Show a formatted summary of version check results
+ *
+ * @param result - Version check result
+ */
+export function showVersionSummary(result: VersionCheckResult): void {
+  console.log('');
+  console.log(chalk.bold('Context File Version Check'));
+  console.log(chalk.dim('─'.repeat(50)));
+
+  if (result.outdated.length === 0 && result.noVersion.length === 0) {
+    console.log(chalk.green('✓ All context files are up to date!'));
+    console.log(chalk.dim(`Current version: ${result.currentVersion}`));
+    return;
+  }
+
+  // Show outdated files
+  if (result.outdated.length > 0) {
+    console.log('');
+    console.log(chalk.yellow(`⚠ ${result.outdated.length} file(s) need updates:`));
+    console.log('');
+
+    // Table header
+    console.log(
+      chalk.dim('Tool'.padEnd(12)) +
+      chalk.dim('File'.padEnd(30)) +
+      chalk.dim('Version')
+    );
+    console.log(chalk.dim('─'.repeat(54)));
+
+    for (const file of result.outdated) {
+      const toolCol = chalk.cyan(file.tool.padEnd(12));
+      const fileCol = file.filePath.padEnd(30);
+      const versionCol = formatUpdateType(
+        file.updateType,
+        file.fileVersion,
+        file.currentVersion
+      );
+
+      console.log(toolCol + fileCol + versionCol);
+
+      if (file.userModified) {
+        console.log(
+          chalk.dim(' '.repeat(12)) +
+          chalk.yellow('⚠ Has custom modifications')
+        );
+      }
+    }
+  }
+
+  // Show files without version markers
+  if (result.noVersion.length > 0) {
+    console.log('');
+    console.log(chalk.dim(`ℹ ${result.noVersion.length} file(s) without version markers:`));
+    for (const file of result.noVersion) {
+      console.log(chalk.dim(`  ${file.filePath}`));
+    }
+  }
+
+  console.log('');
+}
+
+/**
+ * Prompt user for regeneration choice
+ *
+ * @param outdated - List of outdated files
+ * @returns User's regeneration choice
+ */
+export async function promptRegeneration(
+  outdated: NonNullable<VersionCheckResult['outdated']>
+): Promise<RegenerationPromptResult> {
+  if (outdated.length === 0) {
+    return {
+      choice: 'skip',
+      includeModified: false
+    };
+  }
+
+  const hasModified = outdated.some(f => f.userModified);
+
+  // First prompt: what to update
+  const choice = await select<RegenerationChoice>({
+    message: 'Some context files are outdated. What would you like to do?',
+    choices: [
+      {
+        name: 'Update all files',
+        value: 'all',
+        description: 'Regenerate all outdated files'
+      },
+      {
+        name: 'Select specific files',
+        value: 'select',
+        description: 'Choose which files to update'
+      },
+      {
+        name: 'Skip for now',
+        value: 'skip',
+        description: 'Continue without updating'
+      }
+    ]
+  });
+
+  if (choice === 'skip') {
+    return {
+      choice: 'skip',
+      includeModified: false
+    };
+  }
+
+  // If there are modified files, ask about them
+  let includeModified = false;
+  if (hasModified) {
+    includeModified = await confirm({
+      message: chalk.yellow('⚠ Some files have your custom modifications. Include them?'),
+      default: false
+    });
+
+    if (!includeModified) {
+      console.log(chalk.dim('ℹ Modified files will be skipped.'));
+    }
+  }
+
+  // If user wants to select specific files
+  if (choice === 'select') {
+    const choices = outdated.map(f => {
+      const label = `${f.tool} (${f.fileVersion} → ${f.currentVersion})`;
+      const disabled = f.userModified && !includeModified
+        ? 'Has custom modifications'
+        : undefined;
+
+      return {
+        name: label,
+        value: `${f.tool}:${f.filePath}`,
+        disabled
+      };
+    });
+
+    const selected = await checkbox({
+      message: 'Select files to update:',
+      choices
+    });
+
+    // Extract tool names from selections
+    const selectedTools = selected.map(s => (s as string).split(':')[0]);
+
+    return {
+      choice: 'select',
+      selectedTools,
+      includeModified
+    };
+  }
+
+  return {
+    choice,
+    includeModified
+  };
+}
+
+/**
+ * Show a simple prompt to update outdated files
+ *
+ * @param result - Version check result
+ * @returns True if user wants to update
+ */
+export async function promptToUpdate(result: VersionCheckResult): Promise<boolean> {
+  if (result.outdated.length === 0) {
+    return false;
+  }
+
+  const answer = await confirm({
+    message: `Update ${result.outdated.length} outdated context file(s)?`,
+    default: true
+  });
+
+  return answer;
+}
+
+/**
+ * Format a single file status for display
+ *
+ * @param status - File version status
+ * @returns Formatted string
+ */
+export function formatFileStatus(status: {
+  tool: string;
+  filePath: string;
+  fileVersion: string | null;
+  currentVersion: string;
+  updateType?: string;
+}): string {
+  const version = status.fileVersion || 'unknown';
+  return `${status.tool}: ${version} → ${status.currentVersion}`;
+}

package/src/cli/version/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Version Detection Types
+ *
+ * Type definitions for version detection and checking system.
+ */
+
+/**
+ * Update type classification
+ */
+export type UpdateType = 'major' | 'minor' | 'patch' | 'none';
+
+/**
+ * Single file version status
+ */
+export interface FileVersionStatus {
+  /** Tool name (claude, copilot, etc.) */
+  tool: string;
+  /** Full path to the file */
+  filePath: string;
+  /** Whether the file exists on disk */
+  exists: boolean;
+  /** Version string found in the file (if any) */
+  fileVersion: string | null;
+  /** Whether the file has a version marker */
+  hasMarker: boolean;
+  /** Whether the file is outdated compared to current version */
+  isOutdated: boolean;
+  /** Type of update needed (if outdated) */
+  updateType: UpdateType;
+  /** Whether the file has been modified by the user */
+  userModified: boolean;
+  /** Last time the file was checked */
+  lastChecked?: string;
+}
+
+/**
+ * Outdated file summary for prompting
+ */
+export interface OutdatedFile {
+  tool: string;
+  filePath: string;
+  fileVersion: string;
+  currentVersion: string;
+  updateType: UpdateType;
+  userModified: boolean;
+}
+
+/**
+ * Version check result
+ */
+export interface VersionCheckResult {
+  /** Current k0ntext package version */
+  currentVersion: string;
+  /** Total files checked */
+  checked: number;
+  /** List of outdated files */
+  outdated: OutdatedFile[];
+  /** List of up-to-date files */
+  upToDate: FileVersionStatus[];
+  /** List of files with no version marker */
+  noVersion: FileVersionStatus[];
+}
+
+/**
+ * Version check options
+ */
+export interface CheckOptions {
+  /** Project root directory */
+  projectRoot: string;
+  /** Current k0ntext version */
+  currentVersion: string;
+  /** Specific tools to check (empty = all) */
+  tools?: string[];
+  /** Force re-check even if recently checked */
+  force?: boolean;
+  /** Whether to check file modifications */
+  checkModifications?: boolean;
+}
+
+/**
+ * Regeneration choice from user prompt
+ */
+export type RegenerationChoice = 'all' | 'outdated' | 'select' | 'skip';
+
+/**
+ * Prompt result for regeneration
+ */
+export interface RegenerationPromptResult {
+  /** User's choice */
+  choice: RegenerationChoice;
+  /** Selected tools if choice is 'select' */
+  selectedTools?: string[];
+  /** Whether to include modified files */
+  includeModified: boolean;
+}