antikit 1.12.6 → 1.12.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antikit",
-  "version": "1.12.6",
+  "version": "1.12.7",
   "description": "CLI tool to manage AI agent skills from Anti Gravity skills repository",
   "type": "module",
   "main": "src/index.js",
@@ -8,7 +8,9 @@
     "antikit": "src/index.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "release": "commit-and-tag-version",
     "prepare": "husky",
     "format": "prettier --write ."
@@ -57,9 +59,11 @@
   "devDependencies": {
     "@commitlint/cli": "^20.3.1",
     "@commitlint/config-conventional": "^20.3.1",
+    "@vitest/coverage-v8": "^3.0.0",
     "commit-and-tag-version": "^12.6.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
-    "prettier": "^3.7.4"
+    "prettier": "^3.7.4",
+    "vitest": "^3.0.0"
   }
 }

package/src/commands/install.js

@@ -1,11 +1,15 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import { execSync } from 'child_process';
-import { existsSync, mkdirSync, cpSync, rmSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, cpSync, rmSync, writeFileSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { getOrCreateSkillsDir, skillExists } from '../utils/local.js';
 import { fetchRemoteSkills, getSkillCloneUrl } from '../utils/github.js';
+import { DEFAULT_VERSION, parseVersionFromContent } from '../utils/version.js';
+import { METADATA_FILE, SKILL_MD } from '../utils/constants.js';
+import { debug } from '../utils/logger.js';
+import { AntikitError, ErrorCodes } from '../utils/errors.js';
 
 const CACHE_DIR = join(homedir(), '.antikit');
 
@@ -81,10 +85,8 @@ export async function installSkill(skillName, options = {}) {
 
     // --- Check dependencies ---
     try {
-      const mdPath = join(sourcePath, 'SKILL.md');
+      const mdPath = join(sourcePath, SKILL_MD);
       if (existsSync(mdPath)) {
-        // Import locally to avoid cluttering top imports if possible, or just use fs
-        const { readFileSync } = await import('fs');
         const content = readFileSync(mdPath, 'utf-8');
 
         // Parse frontmatter dependencies
@@ -136,7 +138,7 @@ export async function installSkill(skillName, options = {}) {
       }
     } catch (e) {
       // Dep check failed, but continue installing main skill
-      // console.error(e);
+      debug('Dependency check failed:', e.message);
     }
 
     if (options.force && existsSync(destPath)) {
@@ -147,15 +149,11 @@ export async function installSkill(skillName, options = {}) {
 
     // Save skill metadata for future upgrades
     try {
-      let version = '0.0.0';
-      const mdPath = join(destPath, 'SKILL.md');
+      let version = DEFAULT_VERSION;
+      const mdPath = join(destPath, SKILL_MD);
       if (existsSync(mdPath)) {
-        // We likely already imported readFileSync if inside try block,
-        // but for safety use dynamic import or assume imported
-        const { readFileSync } = await import('fs');
         const content = readFileSync(mdPath, 'utf-8');
-        const vMatch = content.match(/^version:\s*(.+)/m);
-        if (vMatch) version = vMatch[1].trim();
+        version = parseVersionFromContent(content);
       }
 
       const metadata = {
@@ -168,9 +166,9 @@ export async function installSkill(skillName, options = {}) {
         version,
         installedAt: Date.now()
       };
-      writeFileSync(join(destPath, '.antikit-skill.json'), JSON.stringify(metadata, null, 2));
+      writeFileSync(join(destPath, METADATA_FILE), JSON.stringify(metadata, null, 2));
     } catch (e) {
-      // Ignore metadata write error, not critical
+      debug('Failed to write metadata:', e.message);
     }
 
     // Cleanup temp

package/src/commands/list.js

@@ -7,17 +7,8 @@ import { skillExists, getOrCreateSkillsDir } from '../utils/local.js';
 import { installSkill } from './install.js';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-
-function compareVersions(v1, v2) {
-  if (!v1 || !v2) return 0;
-  const p1 = v1.split('.').map(Number);
-  const p2 = v2.split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    if ((p1[i] || 0) > (p2[i] || 0)) return 1;
-    if ((p1[i] || 0) < (p2[i] || 0)) return -1;
-  }
-  return 0;
-}
+import { compareVersions, DEFAULT_VERSION } from '../utils/version.js';
+import { METADATA_FILE, OFFICIAL_SOURCE } from '../utils/constants.js';
 
 export async function listRemoteSkills(options) {
   const sourceName = options.source || null;
@@ -49,7 +40,7 @@ export async function listRemoteSkills(options) {
     const skillsWithInfo = await Promise.all(
       skills.map(async skill => {
         let description = skill.description;
-        let remoteVersion = skill.version || '0.0.0';
+        let remoteVersion = skill.version || DEFAULT_VERSION;
 
         // Only fetch info if not already fetched (REST fallback)
         if (description === undefined || description === null) {
@@ -62,19 +53,19 @@ export async function listRemoteSkills(options) {
             skill.branch
           );
           description = info ? info.description : null;
-          remoteVersion = info ? info.version : '0.0.0';
+          remoteVersion = info ? info.version : DEFAULT_VERSION;
         }
 
         const installed = skillExists(skill.name);
         let updateAvailable = false;
-        let localVersion = '0.0.0';
+        let localVersion = DEFAULT_VERSION;
 
         if (installed) {
           try {
-            const metaPath = join(skillsDir, skill.name, '.antikit-skill.json');
+            const metaPath = join(skillsDir, skill.name, METADATA_FILE);
             if (existsSync(metaPath)) {
               const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
-              localVersion = meta.version || '0.0.0';
+              localVersion = meta.version || DEFAULT_VERSION;
               updateAvailable = compareVersions(remoteVersion, localVersion) > 0;
             }
           } catch {}
@@ -118,8 +109,8 @@ function displaySkillsList(skills) {
 
   // Sort: Official first, then Source, then Name
   skills.sort((a, b) => {
-    if (a.source === 'official' && b.source !== 'official') return -1;
-    if (b.source === 'official' && a.source !== 'official') return 1;
+    if (a.source === OFFICIAL_SOURCE && b.source !== OFFICIAL_SOURCE) return -1;
+    if (b.source === OFFICIAL_SOURCE && a.source !== OFFICIAL_SOURCE) return 1;
     if (a.source !== b.source) return a.source.localeCompare(b.source);
     return a.name.localeCompare(b.name);
   });
@@ -130,7 +121,7 @@ function displaySkillsList(skills) {
       status = skill.updateAvailable ? chalk.yellow('Update') : chalk.green('Installed');
     }
 
-    let versionDisplay = skill.remoteVersion || '0.0.0';
+    let versionDisplay = skill.remoteVersion || DEFAULT_VERSION;
     if (skill.installed && skill.localVersion) {
       if (skill.updateAvailable) {
         versionDisplay = `${chalk.dim(skill.localVersion)}→${chalk.yellow(skill.remoteVersion)}`;
@@ -159,8 +150,8 @@ function displaySkillsList(skills) {
 async function interactiveInstall(skills) {
   // Sort skills by Source (Official first) then Name
   skills.sort((a, b) => {
-    if (a.source === 'official' && b.source !== 'official') return -1;
-    if (b.source === 'official' && a.source !== 'official') return 1;
+    if (a.source === OFFICIAL_SOURCE && b.source !== OFFICIAL_SOURCE) return -1;
+    if (b.source === OFFICIAL_SOURCE && a.source !== OFFICIAL_SOURCE) return 1;
     if (a.source !== b.source) return a.source.localeCompare(b.source);
     return a.name.localeCompare(b.name);
   });

package/src/utils/configManager.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+import { OFFICIAL_SOURCE, DEFAULT_BRANCH } from './constants.js';
 
 const CONFIG_DIR = join(homedir(), '.antikit');
 const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
@@ -8,24 +9,24 @@ const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
 const DEFAULT_CONFIG = {
   sources: [
     {
-      name: 'official',
+      name: OFFICIAL_SOURCE,
       owner: 'vunamhung',
       repo: 'antiskills',
-      branch: 'main',
+      branch: DEFAULT_BRANCH,
       default: true
     },
     {
       name: 'claudekit',
       owner: 'mrgoonie',
       repo: 'claudekit-skills',
-      branch: 'main',
+      branch: DEFAULT_BRANCH,
       path: '.claude/skills'
     },
     {
       name: 'ui-ux-pro',
       owner: 'nextlevelbuilder',
       repo: 'ui-ux-pro-max-skill',
-      branch: 'main',
+      branch: DEFAULT_BRANCH,
       path: '.claude/skills'
     }
   ]
@@ -76,8 +77,8 @@ export function getSources() {
 
   // Enforce 'official' source always at the top
   return sources.sort((a, b) => {
-    if (a.name === 'official') return -1;
-    if (b.name === 'official') return 1;
+    if (a.name === OFFICIAL_SOURCE) return -1;
+    if (b.name === OFFICIAL_SOURCE) return 1;
     return 0;
   });
 }
@@ -85,7 +86,7 @@ export function getSources() {
 /**
  * Add a new source
  */
-export function addSource(name, owner, repo, branch = 'main', path = null) {
+export function addSource(name, owner, repo, branch = DEFAULT_BRANCH, path = null) {
   const config = loadConfig();
 
   // Check if source with same name exists

package/src/utils/constants.js

@@ -0,0 +1,36 @@
+/**
+ * Shared constants for antikit
+ * Eliminates magic strings throughout the codebase
+ */
+
+// Source names
+export const OFFICIAL_SOURCE = 'official';
+
+// File names
+export const SKILL_MD = 'SKILL.md';
+export const METADATA_FILE = '.antikit-skill.json';
+
+// Directory names
+export const SKILLS_DIR = '.agent/skills';
+
+// Cache settings
+export const CACHE_TTL = 1000 * 60 * 60; // 1 hour
+export const UPDATE_CHECK_INTERVAL = 1000 * 60 * 60 * 6; // 6 hours
+
+// API endpoints
+export const GITHUB_API = 'https://api.github.com';
+export const GITHUB_GRAPHQL = 'https://api.github.com/graphql';
+export const GITHUB_RAW = 'https://raw.githubusercontent.com';
+
+// Default branch
+export const DEFAULT_BRANCH = 'main';
+
+// Status indicators
+export const STATUS = {
+  INSTALLED: 'installed',
+  UPDATE_AVAILABLE: 'update',
+  NOT_INSTALLED: 'not_installed'
+};
+
+// Max limits
+export const MAX_DIRECTORY_DEPTH = 50;

package/src/utils/errors.js

@@ -0,0 +1,107 @@
+/**
+ * Custom error classes for antikit
+ * Provides structured error handling with error codes
+ */
+
+/**
+ * Base error class for antikit
+ */
+export class AntikitError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {string} code - Error code (e.g., 'SKILL_NOT_FOUND')
+   * @param {Object} [context] - Additional context data
+   */
+  constructor(message, code, context = {}) {
+    super(message);
+    this.name = 'AntikitError';
+    this.code = code;
+    this.context = context;
+  }
+}
+
+/**
+ * Error codes enum
+ */
+export const ErrorCodes = {
+  // Skill errors
+  SKILL_NOT_FOUND: 'SKILL_NOT_FOUND',
+  SKILL_ALREADY_EXISTS: 'SKILL_ALREADY_EXISTS',
+  SKILL_INVALID_METADATA: 'SKILL_INVALID_METADATA',
+  SKILL_MISSING_METADATA: 'SKILL_MISSING_METADATA',
+
+  // Source errors
+  SOURCE_NOT_FOUND: 'SOURCE_NOT_FOUND',
+  SOURCE_ALREADY_EXISTS: 'SOURCE_ALREADY_EXISTS',
+  SOURCE_CANNOT_REMOVE_DEFAULT: 'SOURCE_CANNOT_REMOVE_DEFAULT',
+
+  // GitHub errors
+  GITHUB_RATE_LIMIT: 'GITHUB_RATE_LIMIT',
+  GITHUB_NOT_FOUND: 'GITHUB_NOT_FOUND',
+  GITHUB_AUTH_FAILED: 'GITHUB_AUTH_FAILED',
+  GITHUB_NETWORK_ERROR: 'GITHUB_NETWORK_ERROR',
+
+  // Config errors
+  CONFIG_INVALID: 'CONFIG_INVALID',
+  CONFIG_NOT_FOUND: 'CONFIG_NOT_FOUND',
+
+  // Git errors
+  GIT_CLONE_FAILED: 'GIT_CLONE_FAILED',
+  GIT_NOT_INSTALLED: 'GIT_NOT_INSTALLED',
+
+  // General errors
+  INVALID_INPUT: 'INVALID_INPUT',
+  DIRECTORY_NOT_FOUND: 'DIRECTORY_NOT_FOUND',
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+  UNKNOWN: 'UNKNOWN'
+};
+
+/**
+ * Create a skill not found error
+ */
+export function skillNotFoundError(skillName, source = null) {
+  return new AntikitError(
+    `Skill "${skillName}" not found${source ? ` in source "${source}"` : ''}`,
+    ErrorCodes.SKILL_NOT_FOUND,
+    { skillName, source }
+  );
+}
+
+/**
+ * Create a rate limit error
+ */
+export function rateLimitError() {
+  return new AntikitError(
+    'GitHub API rate limit exceeded. Configure a token to increase limits.',
+    ErrorCodes.GITHUB_RATE_LIMIT
+  );
+}
+
+/**
+ * Create a source not found error
+ */
+export function sourceNotFoundError(sourceName) {
+  return new AntikitError(`Source "${sourceName}" not found.`, ErrorCodes.SOURCE_NOT_FOUND, {
+    sourceName
+  });
+}
+
+/**
+ * Wrap an unknown error with context
+ */
+export function wrapError(error, context = {}) {
+  if (error instanceof AntikitError) {
+    return error;
+  }
+  return new AntikitError(error.message || 'Unknown error occurred', ErrorCodes.UNKNOWN, {
+    ...context,
+    originalError: error
+  });
+}
+
+/**
+ * Check if error is a specific type
+ */
+export function isErrorCode(error, code) {
+  return error instanceof AntikitError && error.code === code;
+}

package/src/utils/github.js

@@ -1,7 +1,8 @@
 import chalk from 'chalk';
 import { getSources, getToken } from './configManager.js';
-
-const GITHUB_API = 'https://api.github.com';
+import { debug } from './logger.js';
+import { GITHUB_API, GITHUB_GRAPHQL, GITHUB_RAW, DEFAULT_BRANCH } from './constants.js';
+import { DEFAULT_VERSION } from './version.js';
 
 // Global flag to prevent duplicate rate limit logs
 let hasLoggedRateLimit = false;
@@ -64,11 +65,11 @@ async function fetchSkillsViaGraphQL(source, token) {
     }
     `;
 
-  const branch = source.branch || 'main';
+  const branch = source.branch || DEFAULT_BRANCH;
   const expression = source.path ? `${branch}:${source.path}` : `${branch}:`;
 
   try {
-    const response = await fetch('https://api.github.com/graphql', {
+    const response = await fetch(GITHUB_GRAPHQL, {
       method: 'POST',
       headers: {
         Authorization: `token ${token}`,
@@ -96,7 +97,7 @@ async function fetchSkillsViaGraphQL(source, token) {
       .filter(item => item.type === 'tree' && !item.name.startsWith('.'))
       .map(item => {
         let description = null;
-        let version = '0.0.0';
+        let version = DEFAULT_VERSION;
 
         const skillFile = item.object.file && item.object.file[0];
         if (skillFile && skillFile.object && skillFile.object.text) {
@@ -118,14 +119,15 @@ async function fetchSkillsViaGraphQL(source, token) {
           source: source.name,
           owner: source.owner,
           repo: source.repo,
-          branch: source.branch || 'main',
+          branch: source.branch || DEFAULT_BRANCH,
           basePath: source.path,
           description,
           version
         };
       });
   } catch (e) {
-    return null; // Fallback
+    debug('GraphQL fetch failed:', e.message);
+    return null; // Fallback to REST
   }
 }
 
@@ -153,8 +155,8 @@ async function fetchSkillsFromSource(source) {
   if (!response.ok) {
     const data = await response.json().catch(() => ({}));
 
-    // Check for rate limit
-    if (response.status === 403 && data.message.includes('rate limit')) {
+    // Check for rate limit (with null-safe access)
+    if (response.status === 403 && data.message?.includes('rate limit')) {
       logRateLimitError();
     }
 
@@ -182,7 +184,7 @@ async function fetchSkillsFromSource(source) {
       source: source.name,
       owner: source.owner,
       repo: source.repo,
-      branch: source.branch || 'main',
+      branch: source.branch || DEFAULT_BRANCH,
       basePath: source.path
     }));
 
@@ -225,7 +227,7 @@ export async function fetchSkillInfo(skillName, owner, repo, path = null, branch
 
   // Optimized: Use Raw URL if branch is known
   if (branch) {
-    let rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}`;
+    let rawUrl = `${GITHUB_RAW}/${owner}/${repo}/${branch}`;
     if (path) rawUrl += `/${path}`;
     rawUrl += `/${skillName}/SKILL.md`;
 
@@ -236,7 +238,9 @@ export async function fetchSkillInfo(skillName, owner, repo, path = null, branch
       if (res.ok) {
         content = await res.text();
       }
-    } catch (e) {}
+    } catch (e) {
+      debug('Raw URL fetch failed:', e.message);
+    }
   }
 
   // Fallback: Use API
@@ -258,8 +262,10 @@ export async function fetchSkillInfo(skillName, owner, repo, path = null, branch
         // But simpler just to ignore or log if we strictly check msg
         try {
           const d = await response.json();
-          if (d.message.includes('rate limit')) logRateLimitError();
-        } catch {}
+          if (d.message?.includes('rate limit')) logRateLimitError();
+        } catch (e) {
+          debug('Rate limit check failed:', e.message);
+        }
       }
       return null;
     }
@@ -276,12 +282,12 @@ export async function fetchSkillInfo(skillName, owner, repo, path = null, branch
 
     return {
       description: descMatch ? descMatch[1].trim() : null,
-      version: versionMatch ? versionMatch[1].trim() : '0.0.0',
+      version: versionMatch ? versionMatch[1].trim() : DEFAULT_VERSION,
       content // Return raw content
     };
   }
 
-  return { description: null, version: '0.0.0', content };
+  return { description: null, version: DEFAULT_VERSION, content };
 }
 
 /**

package/src/utils/local.js

@@ -1,19 +1,28 @@
 import { existsSync, readdirSync, readFileSync, rmSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { CONFIG } from '../config.js';
+import { MAX_DIRECTORY_DEPTH, SKILL_MD } from './constants.js';
+import { debug } from './logger.js';
 
 /**
  * Find local skills directory by traversing up from cwd
+ * Limited to MAX_DIRECTORY_DEPTH to prevent potential infinite loops
  */
 export function findLocalSkillsDir() {
   let dir = process.cwd();
+  let depth = 0;
 
-  while (dir !== '/') {
+  while (dir !== '/' && depth < MAX_DIRECTORY_DEPTH) {
     const skillsPath = join(dir, CONFIG.LOCAL_SKILLS_DIR);
     if (existsSync(skillsPath)) {
       return skillsPath;
     }
     dir = join(dir, '..');
+    depth++;
+  }
+
+  if (depth >= MAX_DIRECTORY_DEPTH) {
+    debug('Max directory depth reached while searching for skills directory');
   }
 
   return null;
@@ -51,7 +60,7 @@ export function getLocalSkills() {
     .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'))
     .map(entry => {
       const skillPath = join(skillsDir, entry.name);
-      const skillMdPath = join(skillPath, 'SKILL.md');
+      const skillMdPath = join(skillPath, SKILL_MD);
 
       let description = null;
       if (existsSync(skillMdPath)) {

package/src/utils/logger.js

@@ -0,0 +1,61 @@
+/**
+ * Simple logging utility with debug support
+ * Enable debug logs with DEBUG=antikit environment variable
+ */
+
+import chalk from 'chalk';
+
+const DEBUG = process.env.DEBUG === 'antikit' || process.env.DEBUG === '*';
+
+/**
+ * Log debug message (only when DEBUG=antikit)
+ */
+export function debug(...args) {
+  if (DEBUG) {
+    console.error(chalk.dim('[debug]'), ...args);
+  }
+}
+
+/**
+ * Log info message
+ */
+export function info(...args) {
+  console.log(chalk.blue('ℹ'), ...args);
+}
+
+/**
+ * Log warning message
+ */
+export function warn(...args) {
+  console.warn(chalk.yellow('⚠'), ...args);
+}
+
+/**
+ * Log error message
+ */
+export function error(...args) {
+  console.error(chalk.red('✖'), ...args);
+}
+
+/**
+ * Log success message
+ */
+export function success(...args) {
+  console.log(chalk.green('✓'), ...args);
+}
+
+/**
+ * Create a scoped logger
+ */
+export function createLogger(scope) {
+  const prefix = chalk.dim(`[${scope}]`);
+  return {
+    debug: (...args) => debug(prefix, ...args),
+    info: (...args) => info(prefix, ...args),
+    warn: (...args) => warn(prefix, ...args),
+    error: (...args) => error(prefix, ...args),
+    success: (...args) => success(prefix, ...args)
+  };
+}
+
+export default { debug, info, warn, error, success, createLogger };

package/src/utils/updateNotifier.js

@@ -4,6 +4,8 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
 import chalk from 'chalk';
+import { compareVersions } from './version.js';
+import { debug } from './logger.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = join(homedir(), '.antikit');
@@ -13,17 +15,12 @@ const UPDATE_CHECK_FILE = join(CONFIG_DIR, 'update-check.json');
 const CHECK_INTERVAL = 1000 * 60 * 60 * 6;
 
 /**
- * Compare semantic versions
+ * Ensure config directory exists
  */
-function compareVersions(v1, v2) {
-  const parts1 = v1.split('.').map(Number);
-  const parts2 = v2.split('.').map(Number);
-
-  for (let i = 0; i < 3; i++) {
-    if (parts1[i] > parts2[i]) return 1;
-    if (parts1[i] < parts2[i]) return -1;
+function ensureConfigDir() {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
   }
-  return 0;
 }
 
 /**
@@ -33,7 +30,45 @@ function loadUpdateCache() {
   try {
     if (!existsSync(UPDATE_CHECK_FILE)) return null;
     return JSON.parse(readFileSync(UPDATE_CHECK_FILE, 'utf-8'));
-  } catch {
+  } catch (e) {
+    debug('Failed to load update cache:', e.message);
+    return null;
+  }
+}
+
+/**
+ * Save update cache data
+ */
+function saveUpdateCache(data) {
+  try {
+    ensureConfigDir();
+    writeFileSync(UPDATE_CHECK_FILE, JSON.stringify(data, null, 2));
+  } catch (e) {
+    debug('Failed to save update cache:', e.message);
+  }
+}
+
+/**
+ * Fetch latest version from npm registry
+ * @param {string} packageName
+ * @returns {Promise<string|null>}
+ */
+async function fetchLatestVersion(packageName) {
+  try {
+    const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(5000)
+    });
+
+    if (!response.ok) {
+      debug('NPM registry returned non-ok status:', response.status);
+      return null;
+    }
+
+    const data = await response.json();
+    return data.version || null;
+  } catch (e) {
+    debug('Failed to fetch latest version:', e.message);
     return null;
   }
 }
@@ -103,8 +138,8 @@ export function checkForUpdates(packageName, currentVersion) {
         stdio: 'ignore'
       });
       child.unref();
-    } catch {
-      // Ignore spawn errors
+    } catch (e) {
+      debug('Failed to spawn update checker:', e.message);
     }
   }
 }

package/src/utils/version.js

@@ -0,0 +1,48 @@
+/**
+ * Version utilities for antikit
+ * Centralized version comparison and constants
+ */
+
+export const DEFAULT_VERSION = '0.0.0';
+
+/**
+ * Compare two semantic versions
+ * @param {string} v1 - First version (e.g., '1.2.3')
+ * @param {string} v2 - Second version (e.g., '1.2.4')
+ * @returns {number} 1 if v1 > v2, -1 if v1 < v2, 0 if equal
+ */
+export function compareVersions(v1, v2) {
+  if (!v1 || !v2) return 0;
+
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 > p2) return 1;
+    if (p1 < p2) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Check if version string is valid semantic version
+ * @param {string} version
+ * @returns {boolean}
+ */
+export function isValidVersion(version) {
+  if (!version || typeof version !== 'string') return false;
+  return /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/.test(version);
+}
+
+/**
+ * Parse version from SKILL.md frontmatter content
+ * @param {string} content - SKILL.md content
+ * @returns {string} version or DEFAULT_VERSION
+ */
+export function parseVersionFromContent(content) {
+  if (!content) return DEFAULT_VERSION;
+  const match = content.match(/^version:\s*(.+)/m);
+  return match ? match[1].trim() : DEFAULT_VERSION;
+}