@maccesar/aiskills 1.7.0

package/lib/cleanup.js

@@ -0,0 +1,77 @@
+/**
+ * Cleanup helpers for skills and symlinks
+ */
+
+import {
+  SKILLS,
+  LEGACY_SKILLS,
+  getAgentsSkillsDir,
+} from './config.js';
+import { detectPlatforms } from './platform.js';
+import { existsSync, lstatSync, rmSync } from 'fs';
+import { join } from 'path';
+
+export function getSkillList({ includeLegacy = true, legacyOnly = false } = {}) {
+  if (legacyOnly) return [...LEGACY_SKILLS];
+  return includeLegacy ? [...SKILLS, ...LEGACY_SKILLS] : [...SKILLS];
+}
+
+function removeEntriesAtDir(dir, names, { suffix = '', recursive = true } = {}) {
+  const results = { removed: [], failed: [] };
+  if (!dir || !existsSync(dir)) return results;
+
+  for (const name of names) {
+    const target = join(dir, suffix ? `${name}${suffix}` : name);
+    try {
+      lstatSync(target);
+      rmSync(target, { recursive, force: true });
+      results.removed.push(name);
+    } catch (error) {
+      if (error.code && error.code !== 'ENOENT') {
+        results.failed.push(name);
+      }
+    }
+  }
+
+  return results;
+}
+
+export function removeSkillSymlinks(platformSkillsDir, options = {}) {
+  const skillList = getSkillList(options);
+  return removeEntriesAtDir(platformSkillsDir, skillList, { recursive: true });
+}
+
+export function removeLegacySkillSymlinks(platformSkillsDir) {
+  return removeSkillSymlinks(platformSkillsDir, { legacyOnly: true });
+}
+
+export function removeSkills(baseDir, options = {}) {
+  const skillsDir = getAgentsSkillsDir(baseDir);
+  const skillList = getSkillList(options);
+  return removeEntriesAtDir(skillsDir, skillList, { recursive: true });
+}
+
+export function cleanupLegacyArtifacts(baseDir) {
+  removeSkills(baseDir, { legacyOnly: true });
+
+  const platforms = detectPlatforms(baseDir);
+  for (const platform of platforms) {
+    removeLegacySkillSymlinks(platform.skillsDir);
+  }
+
+  if (baseDir) {
+    removeSkills(undefined, { legacyOnly: true });
+    const globalPlatforms = detectPlatforms();
+    for (const platform of globalPlatforms) {
+      removeLegacySkillSymlinks(platform.skillsDir);
+    }
+  }
+}
+
+export default {
+  getSkillList,
+  removeSkillSymlinks,
+  removeLegacySkillSymlinks,
+  removeSkills,
+  cleanupLegacyArtifacts,
+};

package/lib/commands/auto-update.js

@@ -0,0 +1,131 @@
+/**
+ * Auto-update command
+ * Full pipeline: check npm -> update CLI -> sync skills
+ * Designed to run silently from hooks or manually with progress
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { execFile as execFileCb } from 'child_process';
+import { promisify } from 'util';
+
+const execFile = promisify(execFileCb);
+import { existsSync } from 'fs';
+import { join } from 'path';
+import {
+  PACKAGE_VERSION,
+  SKILLS,
+  getConfigDir,
+} from '../config.js';
+import {
+  shouldCheckForUpdate as shouldCheck,
+  writeLastCheck,
+} from '../cache.js';
+import {
+  checkForUpdate,
+  fetchLatestNpmVersion,
+} from '../downloader.js';
+import {
+  installSkills,
+  getLocalRepoDir,
+} from '../installer.js';
+import { createSkillSymlinks } from '../symlink.js';
+import { detectPlatforms } from '../platform.js';
+import { cleanupLegacyArtifacts, getSkillList } from '../cleanup.js';
+
+function isDevMode() {
+  const repoDir = getLocalRepoDir();
+  if (!repoDir) return false;
+  return existsSync(join(repoDir, '.git'));
+}
+
+function noopSpinner() {
+  const noop = () => noopSpinner;
+  return { start: noop, succeed: noop, fail: noop, warn: noop, info: noop };
+}
+
+export async function autoUpdateCommand(options) {
+  const silent = !!options.silent;
+  const log = silent ? () => {} : console.log;
+  const spinner = silent ? noopSpinner() : ora();
+
+  const cacheDir = getConfigDir();
+
+  // Step 1: Check cache
+  if (!shouldCheck(cacheDir)) {
+    log(chalk.green('✔'), `Up to date (v${PACKAGE_VERSION})`);
+    return;
+  }
+
+  // Step 2: Check npm for latest version
+  spinner.start('Checking for updates...');
+
+  let latestVersion;
+  try {
+    latestVersion = await fetchLatestNpmVersion();
+  } catch {
+    if (!silent) spinner.fail('Could not reach npm registry');
+    return;
+  }
+
+  // Step 3: Write cache
+  try {
+    writeLastCheck(cacheDir, latestVersion);
+  } catch {
+    // Cache write failed — continue anyway
+  }
+
+  // Step 4: Compare versions
+  const hasUpdate = await checkForUpdate(PACKAGE_VERSION);
+
+  if (!hasUpdate) {
+    spinner.succeed(`Up to date (v${PACKAGE_VERSION})`);
+    return;
+  }
+
+  // Step 5: Update CLI (skip in dev mode)
+  spinner.succeed(`Update available: v${PACKAGE_VERSION} → ${latestVersion}`);
+
+  if (isDevMode()) {
+    spinner.info(`Dev mode — skipping npm update`);
+  } else {
+    spinner.start(`Downloading and installing v${latestVersion}...`);
+    try {
+      await execFile('npm', ['update', '-g', '@maccesar/aiskills'], {
+        timeout: 60000,
+      });
+      spinner.succeed(`Updated to v${latestVersion}`);
+    } catch (error) {
+      spinner.fail(`npm update failed: ${error.message}`);
+      return;
+    }
+  }
+
+  // Step 6: Sync skills and refresh symlinks
+  const repoDir = getLocalRepoDir();
+  if (repoDir) {
+    spinner.start('Syncing skills...');
+    try {
+      await installSkills(repoDir);
+      cleanupLegacyArtifacts();
+
+      const detectedPlatforms = detectPlatforms();
+      const skillList = getSkillList({ includeLegacy: false });
+      for (const platform of detectedPlatforms) {
+        const hasSymlinks = skillList.some((skill) =>
+          existsSync(join(platform.skillsDir, skill))
+        );
+        if (hasSymlinks) {
+          await createSkillSymlinks(platform.skillsDir, SKILLS);
+        }
+      }
+      spinner.succeed('Skills synced');
+    } catch (error) {
+      spinner.fail(`Skill sync failed: ${error.message}`);
+    }
+  }
+
+  log('');
+}
+
+export default autoUpdateCommand;

package/lib/commands/doctor.js

@@ -0,0 +1,139 @@
+/**
+ * Doctor command
+ * Diagnoses installation health (read-only)
+ */
+
+import chalk from 'chalk';
+import { existsSync, lstatSync } from 'fs';
+import { join } from 'path';
+import os from 'os';
+import {
+  SKILLS,
+  PACKAGE_VERSION,
+  getAgentsSkillsDir,
+  getConfigDir,
+  getPlatforms,
+} from '../config.js';
+import { hasHook } from '../hooks.js';
+import { readLastCheck } from '../cache.js';
+
+const CHECK = chalk.green('✓');
+const CROSS = chalk.red('✗');
+const WARN = chalk.yellow('⚠');
+
+export async function doctorCommand() {
+  const homeDir = os.homedir();
+  const skillsDir = getAgentsSkillsDir(homeDir);
+  const claudeDir = join(homeDir, '.claude');
+  const cacheDir = getConfigDir();
+
+  let issues = 0;
+  const symlinkIssues = [];
+
+  console.log('');
+  console.log(chalk.bold('AI Skills Doctor'));
+  console.log('');
+  console.log('  Checking installation health...');
+  console.log('');
+
+  // CLI version
+  console.log(`  ${CHECK} CLI version: v${PACKAGE_VERSION}`);
+
+  // Skills check
+  const missingSkills = [];
+  for (const skill of SKILLS) {
+    if (!existsSync(join(skillsDir, skill))) {
+      missingSkills.push(skill);
+    }
+  }
+  const installedCount = SKILLS.length - missingSkills.length;
+  if (missingSkills.length === 0) {
+    console.log(`  ${CHECK} Skills: ${installedCount}/${SKILLS.length} installed in ~/.agents/skills/`);
+  } else {
+    console.log(`  ${CROSS} Skills: ${installedCount}/${SKILLS.length} installed in ~/.agents/skills/ (missing: ${missingSkills.join(', ')})`);
+    issues += missingSkills.length;
+  }
+
+  // Hook check
+  if (hasHook(claudeDir)) {
+    console.log(`  ${CHECK} Hook: SessionStart configured`);
+  } else {
+    console.log(`  ${CROSS} Hook: SessionStart not configured`);
+    issues++;
+  }
+
+  // Cache check
+  const lastCheck = readLastCheck(cacheDir);
+  if (lastCheck) {
+    const hoursAgo = Math.round((Date.now() - lastCheck.lastCheck) / (1000 * 60 * 60));
+    const timeLabel = hoursAgo < 1 ? 'less than an hour ago' : `${hoursAgo} hour${hoursAgo === 1 ? '' : 's'} ago`;
+    console.log(`  ${CHECK} Cache: last check ${timeLabel}`);
+  } else {
+    console.log(`  ${WARN} Cache: no check recorded`);
+  }
+
+  // Platforms
+  console.log('');
+  console.log('  Platforms:');
+  const platforms = getPlatforms(homeDir);
+  for (const platform of platforms) {
+    const missing = [];
+    const broken = [];
+
+    for (const skill of SKILLS) {
+      const linkPath = join(platform.skillsDir, skill);
+      try {
+        const stat = lstatSync(linkPath);
+        if (stat.isSymbolicLink()) {
+          // Check if target exists
+          if (!existsSync(linkPath)) {
+            broken.push(skill);
+          }
+        }
+        // exists (symlink or directory), count as linked
+      } catch {
+        missing.push(skill);
+      }
+    }
+
+    const linkedCount = SKILLS.length - missing.length - broken.length;
+
+    if (missing.length === 0 && broken.length === 0) {
+      console.log(`    ${CHECK} ${platform.displayName}: ${SKILLS.length}/${SKILLS.length} skills linked`);
+    } else {
+      const problems = [];
+      if (missing.length > 0) problems.push(`missing: ${missing.join(', ')}`);
+      if (broken.length > 0) problems.push(`broken: ${broken.join(', ')}`);
+      console.log(`    ${CROSS} ${platform.displayName}: ${linkedCount}/${SKILLS.length} skills linked (${problems.join('; ')})`);
+      issues += missing.length + broken.length;
+
+      // Collect symlink issues for detailed report
+      for (const skill of broken) {
+        symlinkIssues.push(`${CROSS} ~/${platform.name === 'claude' ? '.claude' : `.${platform.name}`}/skills/${skill} → broken symlink (target missing)`);
+      }
+      for (const skill of missing) {
+        symlinkIssues.push(`${CROSS} ~/${platform.name === 'claude' ? '.claude' : `.${platform.name}`}/skills/${skill} → not found`);
+      }
+    }
+  }
+
+  // Symlink issues detail
+  if (symlinkIssues.length > 0) {
+    console.log('');
+    console.log(`  ${WARN} Symlink issues:`);
+    for (const issue of symlinkIssues) {
+      console.log(`    ${issue}`);
+    }
+  }
+
+  // Summary
+  console.log('');
+  if (issues === 0) {
+    console.log(chalk.green(`  No issues found.`));
+  } else {
+    console.log(chalk.yellow(`  ${issues} issue${issues === 1 ? '' : 's'} found. Run 'aiskills install' to fix.`));
+  }
+  console.log('');
+}
+
+export default { doctorCommand };

package/lib/commands/list.js

@@ -0,0 +1,77 @@
+/**
+ * List command
+ * Shows available skills with their descriptions
+ */
+
+import chalk from 'chalk';
+import { SKILLS } from '../config.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function parseSkillDescription(skillName) {
+  try {
+    const skillPath = join(__dirname, '..', '..', 'skills', skillName, 'SKILL.md');
+    const content = readFileSync(skillPath, 'utf8');
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+
+    const frontmatter = match[1];
+
+    // Extract name
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    const name = nameMatch ? nameMatch[1].trim() : skillName;
+
+    // Extract description (handles multi-line YAML >)
+    let description = '';
+    const descMatch = frontmatter.match(/description:\s*>\s*\n([\s\S]*?)(?=\n\w+:|$)/);
+    if (descMatch) {
+      description = descMatch[1]
+        .split('\n')
+        .map(line => line.trim())
+        .filter(Boolean)
+        .join(' ');
+    } else {
+      const singleMatch = frontmatter.match(/^description:\s*(.+)$/m);
+      if (singleMatch) {
+        description = singleMatch[1].trim();
+      }
+    }
+
+    // Trim long descriptions
+    const maxLen = 80;
+    if (description.length > maxLen) {
+      description = description.substring(0, maxLen - 1).trimEnd() + '…';
+    }
+
+    return { name, description };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List command handler
+ */
+export async function listCommand() {
+  console.log('');
+  console.log(chalk.bold.blue('Available Skills'));
+  console.log('');
+
+  const maxNameLen = Math.max(...SKILLS.map(s => s.length));
+
+  for (const skill of SKILLS) {
+    const info = parseSkillDescription(skill);
+    const name = chalk.cyan(skill.padEnd(maxNameLen));
+    const desc = info?.description ? chalk.gray(info.description) : chalk.gray('(no description)');
+    console.log(`  ${name}  ${desc}`);
+  }
+
+  console.log('');
+  console.log(chalk.gray(`${SKILLS.length} skill${SKILLS.length !== 1 ? 's' : ''} available`));
+  console.log('');
+}
+
+export default listCommand;

package/lib/commands/skills.js

@@ -0,0 +1,263 @@
+/**
+ * Skills command
+ * Installs and manages skills in AI coding assistant directories
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import {
+  SKILLS,
+  getPlatforms,
+  getAgentsSkillsDir,
+} from '../config.js';
+import select from '../prompts/selectCancel.js';
+import checkbox, { Separator } from '../prompts/checkboxCancel.js';
+import {
+  detectPlatforms,
+  detectOS,
+} from '../platform.js';
+import {
+  getSkillList,
+  removeSkillSymlinks,
+  removeLegacySkillSymlinks,
+  removeSkills,
+} from '../cleanup.js';
+import {
+  installSkills,
+  getLocalRepoDir,
+} from '../installer.js';
+import { downloadRepoArchive } from '../downloader.js';
+import { createSkillSymlinks } from '../symlink.js';
+import { installHook } from '../hooks.js';
+import { mkdtemp } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { tmpdir } from 'os';
+
+function hasAnySkillSymlink(platformSkillsDir) {
+  if (!platformSkillsDir || !existsSync(platformSkillsDir)) return false;
+  const skillList = getSkillList();
+  return skillList.some((skill) => existsSync(join(platformSkillsDir, skill)));
+}
+
+/**
+ * Skills command handler
+ * @param {Object} options - Command options
+ */
+export async function skillsCommand(options) {
+  console.log('');
+  console.log(chalk.bold.blue('AI Skills Manager'));
+  console.log('');
+
+  const isLocal = options.local;
+  const customPath = options.path;
+
+  // Determine base directory (Local vs Global)
+  const baseDir = isLocal ? process.cwd() : (customPath ? resolve(customPath) : undefined);
+
+  if (isLocal) {
+    console.log(chalk.cyan('Mode: Local installation (current project)'));
+  } else if (customPath) {
+    console.log(chalk.cyan(`Mode: Custom path (${baseDir})`));
+  } else {
+    console.log(chalk.cyan('Mode: Global installation (user home)'));
+  }
+  console.log('');
+
+  // Detect installed platforms at the target base directory
+  const localPlatforms = detectPlatforms(baseDir);
+  const globalPlatforms = detectPlatforms();
+  let detectedPlatforms = localPlatforms;
+
+  if (isLocal || options.path) {
+    const localNames = new Set(localPlatforms.map((platform) => platform.name));
+    const globalNames = new Set(globalPlatforms.map((platform) => platform.name));
+    const allPlatforms = getPlatforms(baseDir);
+    const merged = [...localPlatforms];
+    for (const platform of allPlatforms) {
+      if (globalNames.has(platform.name) && !localNames.has(platform.name)) {
+        merged.push(platform);
+      }
+    }
+    detectedPlatforms = merged;
+  }
+
+  if (detectedPlatforms.length === 0 && !options.path && !isLocal) {
+    console.log(chalk.yellow('No AI coding assistants detected globally.'));
+    console.log('Install one of: Claude Code, Gemini CLI, or Codex CLI');
+    console.log('Or use: aiskills install --local');
+    process.exit(1);
+  }
+
+  // Show detected platforms
+  if (detectedPlatforms.length > 0) {
+    for (const platform of detectedPlatforms) {
+      console.log(chalk.green('✓'), `${platform.displayName} detected`);
+    }
+    console.log('');
+  } else if (isLocal) {
+    detectedPlatforms = getPlatforms(baseDir);
+  }
+
+  // Select platforms to install
+  let selectedPlatforms = [];
+
+  if (options.path) {
+    selectedPlatforms = detectedPlatforms;
+  } else if (options.all) {
+    selectedPlatforms = detectedPlatforms;
+  } else {
+    try {
+      const platformChoices = await checkbox({
+        message: 'Select platforms to sync:',
+        choices: [
+          ...detectedPlatforms.map((p) => ({
+            name: p.displayName,
+            value: p.name,
+            checked: hasAnySkillSymlink(p.skillsDir),
+          })),
+          new Separator(' ')
+        ],
+        shortcuts: { invert: null },
+        theme: {
+          style: {
+            renderSelectedChoices: () => '',
+            prefix: () => chalk.cyan('?'),
+          },
+        },
+      });
+
+      if (platformChoices.includes('cancel')) {
+        console.log('Cancelled.');
+        process.exit(0);
+      }
+
+      selectedPlatforms = detectedPlatforms.filter((p) =>
+        platformChoices.includes(p.name)
+      );
+    } catch (error) {
+      console.log('\nCancelled.');
+      process.exit(0);
+    }
+  }
+
+  const removeOnly = selectedPlatforms.length === 0;
+  if (removeOnly) {
+    console.log(chalk.yellow('No platforms selected. Removing all platform symlinks.'));
+  }
+
+  // Get repository directory (local or download)
+  const spinner = ora();
+  let repoDir = null;
+  let tempDir = null;
+
+  if (!removeOnly) {
+    repoDir = getLocalRepoDir();
+
+    if (!repoDir) {
+      spinner.start('Downloading from GitHub...');
+      try {
+        tempDir = await mkdtemp(join(tmpdir(), 'aiskills-'));
+        repoDir = await downloadRepoArchive(tempDir);
+        spinner.succeed('Downloaded from GitHub');
+      } catch (error) {
+        spinner.fail('Failed to download');
+        console.error(chalk.red(error.message));
+        process.exit(1);
+      }
+    } else {
+      console.log(chalk.green('Using local repository'));
+    }
+  }
+
+  const selectedPlatformNames = new Set(selectedPlatforms.map((platform) => platform.name));
+
+  try {
+    if (!removeOnly) {
+      // Install skills
+      spinner.start('Installing skills...');
+      const skillsResult = await installSkills(repoDir, baseDir);
+      spinner.succeed(`${SKILLS.length} skill${SKILLS.length !== 1 ? 's' : ''} installed`);
+
+      // Create symlinks for selected platforms
+      for (const platform of selectedPlatforms) {
+        removeLegacySkillSymlinks(platform.skillsDir);
+        spinner.start(`Linking ${platform.displayName}...`);
+        const symlinkResult = await createSkillSymlinks(
+          platform.skillsDir,
+          SKILLS,
+          baseDir
+        );
+        if (symlinkResult.linked.length === SKILLS.length) {
+          spinner.succeed(`${platform.displayName}: Skills linked`);
+        } else {
+          spinner.warn(
+            `${platform.displayName}: ${symlinkResult.linked.length}/${SKILLS.length} skills linked`
+          );
+        }
+      }
+    } else {
+      const skillsResult = removeSkills(baseDir);
+      const platformResults = detectedPlatforms.map((platform) => {
+        const symlinkResult = removeSkillSymlinks(platform.skillsDir);
+        return {
+          displayName: platform.displayName,
+          removedCount: symlinkResult.removed.length,
+        };
+      });
+
+      if (skillsResult.removed.length > 0) {
+        console.log(chalk.green('✓'), `${skillsResult.removed.length} skills removed`);
+      } else {
+        console.log(chalk.gray('ℹ'), 'No skills to remove');
+      }
+
+      for (const result of platformResults) {
+        if (result.removedCount > 0) {
+          console.log(chalk.green('✓'), `${result.displayName}: Skills unlinked`);
+        } else {
+          console.log(chalk.gray('ℹ'), `${result.displayName}: No symlinks found`);
+        }
+      }
+    }
+
+    // Install SessionStart hook for Claude Code auto-update
+    if (!removeOnly && selectedPlatformNames.has('claude')) {
+      const claudePlatform = selectedPlatforms.find((p) => p.name === 'claude');
+      if (claudePlatform) {
+        installHook(claudePlatform.configDir);
+      }
+    }
+
+    // Remove symlinks for unselected detected platforms
+    if (!removeOnly) {
+      for (const platform of detectedPlatforms) {
+        if (selectedPlatformNames.has(platform.name)) continue;
+        spinner.start(`Unlinking ${platform.displayName}...`);
+        const symlinkResult = removeSkillSymlinks(platform.skillsDir);
+        if (symlinkResult.removed.length > 0) {
+          spinner.succeed(`${platform.displayName}: Skills unlinked`);
+        } else {
+          spinner.info(`${platform.displayName}: No symlinks found`);
+        }
+      }
+    }
+
+    // Summary
+    console.log('');
+    console.log(chalk.green('✓ Skills sync complete!'));
+    console.log('');
+
+    if (!removeOnly && !isLocal && detectOS() === 'windows') {
+      console.log(chalk.yellow('▸'), 'Windows: Ensure ~/bin is in your PATH');
+      console.log('');
+    }
+
+  } finally {
+    if (tempDir) {
+      await import('fs-extra').then(({ remove }) => remove(tempDir));
+    }
+  }
+}
+
+export default skillsCommand;