@ax-llm/ax 25.4.1 → 25.4.2

package/README.md

@@ -157,6 +157,35 @@ const analyzer = ax(`
 npm install @ax-llm/ax
 ```
 
+Outside CI, installation sets up one Claude Code skill, `ax-llm`, with a compact
+index and bundled guides your agent reads as needed. To disable future automatic
+setup, run `npx @ax-llm/ax skills-auto-install off` from your project root. This
+saves `ax.skills.autoInstall: false` in your project's `package.json`; commit
+that setting to share it with your team. Use `skills-auto-install on` to re-enable
+automatic setup on future installs. Set `AX_SKIP_SKILL_INSTALL=1` to skip setup
+for a single installation; CI and this environment variable take precedence over
+the saved setting.
+
+You can also set the preference before installing Ax for the first time:
+
+```json
+{
+  "ax": {
+    "skills": {
+      "autoInstall": false
+    }
+  }
+}
+```
+
+Merge this field into your existing `package.json`. Manual
+`npx @ax-llm/ax setup-claude` works even when automatic setup is disabled;
+add `--all` to register every specialist or `--skill ax-ai` to install only one.
+Changing the preference leaves installed skills in place, and manual setup or
+removal preserves the saved preference.
+Existing specialists remain installed; use `remove-claude` followed by
+`setup-claude` to switch an older full installation to the compact bundle.
+
 ### Your First AI Feature (2 minutes)
 
 ```typescript

package/cli/index.mjs

@@ -1,294 +1,13 @@
 #!/usr/bin/env node
 
-/**
- * CLI for @ax-llm/ax
- *
- * Commands:
- *   setup-claude [--force]   Install/upgrade Claude Code skills to .claude/skills/<name>/SKILL.md (project-local)
- *   remove-claude            Remove all Claude Code skills
- *
- * Usage:
- *   npx @ax-llm/ax setup-claude           # Install or upgrade if newer version
- *   npx @ax-llm/ax setup-claude --force   # Force overwrite regardless of version
- *   npx @ax-llm/ax remove-claude          # Remove all skills
- */
-
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs';
-import { basename, dirname, join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { setAutoSkillInstall } from '../scripts/skill-config.mjs';
+import { installSkills, removeSkills } from '../scripts/skill-install.mjs';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Skill files directory in the package
-const SKILLS_SOURCE_DIR = join(__dirname, '..', 'skills');
-
-// Base target location for skills in current working directory (project-local)
-const SKILLS_BASE_DIR = join(process.cwd(), '.claude', 'skills');
-
-/**
- * Get all *.md skill files from the source directory
- */
-function getSkillFiles() {
-  if (!existsSync(SKILLS_SOURCE_DIR)) {
-    return [];
-  }
-  return readdirSync(SKILLS_SOURCE_DIR).filter((f) => f.endsWith('.md'));
-}
-
-/**
- * Get the skill name from YAML frontmatter, falling back to filename without .md
- */
-function getSkillName(filePath) {
-  try {
-    const content = readFileSync(filePath, 'utf8');
-    const match = content.match(/^name:\s*["']?([^"'\n\r]+)/m);
-    if (match) return match[1].trim();
-  } catch {
-    // Fall through to fallback
-  }
-  return basename(filePath, '.md');
-}
-
-/**
- * Compare semver versions
- * Returns: 1 if a > b, -1 if a < b, 0 if equal
- */
-function compareSemver(a, b) {
-  const parseVersion = (v) => {
-    const match = v.match(/^(\d+)\.(\d+)\.(\d+)/);
-    if (!match) return [0, 0, 0];
-    return [
-      Number.parseInt(match[1], 10),
-      Number.parseInt(match[2], 10),
-      Number.parseInt(match[3], 10),
-    ];
-  };
-
-  const [aMajor, aMinor, aPatch] = parseVersion(a);
-  const [bMajor, bMinor, bPatch] = parseVersion(b);
-
-  if (aMajor !== bMajor) return aMajor > bMajor ? 1 : -1;
-  if (aMinor !== bMinor) return aMinor > bMinor ? 1 : -1;
-  if (aPatch !== bPatch) return aPatch > bPatch ? 1 : -1;
-  return 0;
-}
-
-/**
- * Get the installed skill version from a file
- */
-function getInstalledVersion(targetPath) {
-  if (!existsSync(targetPath)) {
-    return null;
-  }
-
-  try {
-    const content = readFileSync(targetPath, 'utf8');
-    const match = content.match(/^version:\s*["']?([^"'\n\r]+)/m);
-    return match ? match[1].trim() : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Get the package version from a skill source file
- */
-function getPackageVersion(sourcePath) {
-  if (!existsSync(sourcePath)) {
-    // Fallback: try to read from package.json
-    const packageJsonPath = join(__dirname, '..', 'package.json');
-    if (existsSync(packageJsonPath)) {
-      try {
-        const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-        return pkg.version || null;
-      } catch {
-        return null;
-      }
-    }
-    return null;
-  }
-
-  try {
-    const content = readFileSync(sourcePath, 'utf8');
-    const match = content.match(/^version:\s*["']?([^"'\n\r]+)/m);
-    return match ? match[1].trim() : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Install or upgrade Claude Code skills
- */
-function setupClaude(force = false) {
-  const skillFiles = getSkillFiles();
-
-  if (skillFiles.length === 0) {
-    console.error('Error: No skill files found. The package may be corrupted.');
-    process.exit(1);
-  }
-
-  // Clean up legacy flat file structure (.claude/skills/ax/*.md except SKILL.md)
-  const legacyDir = join(SKILLS_BASE_DIR, 'ax');
-  if (existsSync(legacyDir)) {
-    try {
-      const legacyFiles = readdirSync(legacyDir).filter(
-        (f) => f.endsWith('.md') && f !== 'SKILL.md'
-      );
-      for (const f of legacyFiles) {
-        rmSync(join(legacyDir, f), { force: true });
-      }
-    } catch {
-      // Ignore cleanup errors
-    }
-  }
-
-  let allUpToDate = true;
-
-  for (const file of skillFiles) {
-    const skillSource = join(SKILLS_SOURCE_DIR, file);
-    const skillName = getSkillName(skillSource);
-    const skillDir = join(SKILLS_BASE_DIR, skillName);
-    const skillTarget = join(skillDir, 'SKILL.md');
-
-    const packageVersion = getPackageVersion(skillSource);
-    const installedVersion = getInstalledVersion(skillTarget);
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const [command = 'help', ...flags] = process.argv.slice(2);
 
-    // Determine if we should install
-    let shouldInstall = false;
-    let action = 'Installed';
-
-    if (!existsSync(skillTarget)) {
-      shouldInstall = true;
-    } else if (force) {
-      shouldInstall = true;
-      action = installedVersion ? 'Reinstalled' : 'Installed';
-    } else if (installedVersion && packageVersion) {
-      const comparison = compareSemver(packageVersion, installedVersion);
-      if (comparison > 0) {
-        shouldInstall = true;
-        action = 'Upgraded';
-      } else if (comparison === 0) {
-        console.log(`${skillName} is up to date (v${installedVersion})`);
-        continue;
-      } else {
-        console.log(
-          `${skillName} is already at v${installedVersion} (package has v${packageVersion})`
-        );
-        continue;
-      }
-    } else if (!installedVersion && existsSync(skillTarget)) {
-      shouldInstall = true;
-      action = 'Upgraded';
-    }
-
-    if (!shouldInstall) {
-      console.log(
-        `${skillName} is up to date (v${installedVersion || 'unknown'})`
-      );
-      continue;
-    }
-
-    allUpToDate = false;
-
-    // Create target directory if it doesn't exist
-    if (!existsSync(skillDir)) {
-      mkdirSync(skillDir, { recursive: true });
-    }
-
-    try {
-      const content = readFileSync(skillSource, 'utf8');
-      writeFileSync(skillTarget, content, 'utf8');
-
-      if (action === 'Upgraded' && installedVersion && packageVersion) {
-        console.log(
-          `\u2713 ${action} ${skillName} (v${installedVersion} \u2192 v${packageVersion})`
-        );
-      } else {
-        console.log(
-          `\u2713 ${action} ${skillName} (v${packageVersion || 'unknown'})`
-        );
-      }
-    } catch (err) {
-      console.error(`Error installing ${skillName}: ${err.message}`);
-      process.exit(1);
-    }
-  }
-
-  if (allUpToDate) {
-    console.log('All Ax Claude Code skills are up to date.');
-  }
-}
-
-/**
- * Remove all Claude Code skills
- */
-function removeClaude() {
-  const skillFiles = getSkillFiles();
-
-  if (skillFiles.length === 0) {
-    console.log('No skill definitions found in package.');
-    return;
-  }
-
-  try {
-    let removedCount = 0;
-
-    for (const file of skillFiles) {
-      const skillName = getSkillName(join(SKILLS_SOURCE_DIR, file));
-      const skillDir = join(SKILLS_BASE_DIR, skillName);
-      const skillTarget = join(skillDir, 'SKILL.md');
-
-      if (existsSync(skillTarget)) {
-        rmSync(skillTarget, { force: true });
-        removedCount++;
-
-        // Try to remove the directory if empty
-        try {
-          const remaining = readdirSync(skillDir);
-          if (remaining.length === 0) {
-            rmSync(skillDir, { recursive: true, force: true });
-          }
-        } catch {
-          // Ignore errors when trying to clean up directory
-        }
-      }
-    }
-
-    // Also clean up legacy flat files from old .claude/skills/ax/ structure
-    const legacyDir = join(SKILLS_BASE_DIR, 'ax');
-    if (existsSync(legacyDir)) {
-      const legacyFiles = readdirSync(legacyDir).filter(
-        (f) => f.endsWith('.md') && f !== 'SKILL.md'
-      );
-      for (const f of legacyFiles) {
-        rmSync(join(legacyDir, f), { force: true });
-      }
-    }
-
-    if (removedCount > 0) {
-      const noun = removedCount === 1 ? 'skill' : 'skills';
-      console.log(`\u2713 Removed ${removedCount} Ax Claude Code ${noun}`);
-    } else {
-      console.log('Ax Claude Code skills are not installed.');
-    }
-  } catch (err) {
-    console.error(`Error removing skills: ${err.message}`);
-    process.exit(1);
-  }
-}
-
-/**
- * Show help
- */
 function showHelp() {
   console.log(`
 @ax-llm/ax CLI
@@ -297,42 +16,76 @@ Usage:
   npx @ax-llm/ax <command> [options]
 
 Commands:
-  setup-claude [--force]   Install/upgrade Claude Code skills
-  remove-claude            Remove all Claude Code skills
-  help                     Show this help message
+  setup-claude             Install the Ax entry point and bundled guides locally
+  remove-claude            Remove installed Ax skills and their bundled guides
+  skills-auto-install <on|off>
+                          Save automatic setup preference in project package.json
+  help                     Show this help
 
-Options:
-  --force                  Force reinstall regardless of version
+Options for setup-claude:
+  --all                    Install every specialist as a separate skill too
+  --skill <name>           Install only the named skill (repeatable)
+  --force                  Reinstall even if the installed version is newer
 
 Examples:
-  npx @ax-llm/ax setup-claude           # Install or upgrade
-  npx @ax-llm/ax setup-claude --force   # Force reinstall
-  npx @ax-llm/ax remove-claude          # Remove skills
+  npx @ax-llm/ax setup-claude
+  npx @ax-llm/ax setup-claude --all
+  npx @ax-llm/ax setup-claude --skill ax-ai
+  npx @ax-llm/ax skills-auto-install off
+  npx @ax-llm/ax skills-auto-install on
+
+Automatic setup installs only ax-llm in .claude/skills, outside CI.
+Run skills-auto-install off from your project root to disable future automatic setup.
+This saves ax.skills.autoInstall in package.json; on restores automatic setup.
+Manual setup-claude still works while automatic setup is disabled.
+Set AX_SKIP_SKILL_INSTALL=1 to skip setup for a single package installation.
+Existing specialist installs remain until you run remove-claude.
 `);
 }
 
-// Parse command line arguments
-const args = process.argv.slice(2);
-const command = args[0];
-const flags = args.slice(1);
-
-switch (command) {
-  case 'setup-claude':
-    setupClaude(flags.includes('--force'));
-    break;
-  case 'remove-claude':
-    removeClaude();
-    break;
-  case 'help':
-  case '--help':
-  case '-h':
-    showHelp();
-    break;
-  case undefined:
+try {
+  if (command === 'setup-claude') {
+    const options = { all: false, force: false, names: [] };
+    for (let i = 0; i < flags.length; i++) {
+      const flag = flags[i];
+      if (flag === '--all') options.all = true;
+      else if (flag === '--force') options.force = true;
+      else if (
+        flag === '--skill' &&
+        flags[i + 1] &&
+        !flags[i + 1].startsWith('--')
+      )
+        options.names.push(flags[++i]);
+      else throw new Error(`Unknown or incomplete option: ${flag}`);
+    }
+    if (options.all && options.names.length)
+      throw new Error('Choose --all or --skill.');
+    const installed = installSkills(packageRoot, process.cwd(), options);
+    console.log(
+      installed.length
+        ? `✓ Installed Ax skills: ${installed.join(', ')}`
+        : 'Ax skills are up to date.'
+    );
+  } else if (command === 'remove-claude' && flags.length === 0) {
+    console.log(
+      `✓ Removed ${removeSkills(packageRoot, process.cwd())} Ax skills.`
+    );
+  } else if (command === 'skills-auto-install') {
+    if (flags.length !== 1 || !['on', 'off'].includes(flags[0]))
+      throw new Error('Usage: npx @ax-llm/ax skills-auto-install <on|off>');
+    const enabled = flags[0] === 'on';
+    setAutoSkillInstall(process.cwd(), enabled);
+    console.log(
+      `✓ Automatic Ax skill installation ${enabled ? 'enabled' : 'disabled'} in package.json.`
+    );
+  } else if (['help', '--help', '-h'].includes(command)) {
     showHelp();
-    break;
-  default:
-    console.error(`Unknown command: ${command}`);
-    console.error('Run "npx @ax-llm/ax help" for usage information.');
-    process.exit(1);
+  } else {
+    throw new Error(
+      `Unknown command: ${command}. Run npx @ax-llm/ax help for usage.`
+    );
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "25.4.1",
+  "version": "25.4.2",
   "type": "module",
   "description": "The best library to work with LLMs",
   "repository": {

package/scripts/postinstall.mjs

@@ -1,34 +1,15 @@
 #!/usr/bin/env node
 
-/**
- * Postinstall script for @ax-llm/ax
- *
- * Auto-installs/upgrades the Claude Code skill on package install.
- *
- * Features:
- * - Skips in CI environments (CI, CONTINUOUS_INTEGRATION env vars)
- * - Skips if AX_SKIP_SKILL_INSTALL=1
- * - Silent failure (never breaks package installation)
- * - Cross-platform (macOS, Linux, Windows)
- * - Only logs in interactive terminals (process.stdout.isTTY)
- * - Version-aware upgrades: only upgrades if newer version available
- */
-
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs';
-import { basename, dirname, join, sep } from 'node:path';
+// Register one entry-point skill with bundled guides. Specialist skills are
+// available through the explicit setup command; package installation never
+// adds them individually. Failures must never break dependency installation.
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { autoSkillInstallEnabled } from './skill-config.mjs';
+import { installSkills } from './skill-install.mjs';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Check if we should skip installation
 function shouldSkip() {
   // Skip in CI environments
   if (process.env.CI === 'true' || process.env.CI === '1') {
@@ -73,88 +54,6 @@ function shouldSkip() {
   return false;
 }
 
-// Check if we're in an interactive terminal
-function isInteractive() {
-  return process.stdout.isTTY === true;
-}
-
-/**
- * Compare semver versions
- * Returns: 1 if a > b, -1 if a < b, 0 if equal
- */
-function compareSemver(a, b) {
-  const parseVersion = (v) => {
-    const match = v.match(/^(\d+)\.(\d+)\.(\d+)/);
-    if (!match) return [0, 0, 0];
-    return [
-      Number.parseInt(match[1], 10),
-      Number.parseInt(match[2], 10),
-      Number.parseInt(match[3], 10),
-    ];
-  };
-
-  const [aMajor, aMinor, aPatch] = parseVersion(a);
-  const [bMajor, bMinor, bPatch] = parseVersion(b);
-
-  if (aMajor !== bMajor) return aMajor > bMajor ? 1 : -1;
-  if (aMinor !== bMinor) return aMinor > bMinor ? 1 : -1;
-  if (aPatch !== bPatch) return aPatch > bPatch ? 1 : -1;
-  return 0;
-}
-
-/**
- * Get the installed skill version from the file
- */
-function getInstalledVersion(targetPath) {
-  if (!existsSync(targetPath)) {
-    return null;
-  }
-
-  try {
-    const content = readFileSync(targetPath, 'utf8');
-    const match = content.match(/^version:\s*["']?([^"'\n\r]+)/m);
-    return match ? match[1].trim() : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Get the skill name from YAML frontmatter, falling back to filename without .md
- */
-function getSkillName(filePath) {
-  try {
-    const content = readFileSync(filePath, 'utf8');
-    const match = content.match(/^name:\s*["']?([^"'\n\r]+)/m);
-    if (match) return match[1].trim();
-  } catch {
-    // Fall through to fallback
-  }
-  return basename(filePath, '.md');
-}
-
-/**
- * Get the package version from the skill source file
- */
-function getPackageVersion(sourcePath) {
-  if (!existsSync(sourcePath)) {
-    return null;
-  }
-
-  try {
-    const content = readFileSync(sourcePath, 'utf8');
-    const match = content.match(/^version:\s*["']?([^"'\n\r]+)/m);
-    return match ? match[1].trim() : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Find the project root by using INIT_CWD (set by npm/yarn/pnpm to the
- * directory where `install` was run), falling back to finding the
- * topmost node_modules in __dirname and taking its parent.
- */
 function findProjectRoot() {
   // INIT_CWD is the most reliable — npm, yarn, and pnpm all set it
   if (process.env.INIT_CWD) {
@@ -175,105 +74,20 @@ function findProjectRoot() {
   return join(__dirname, '..', '..', '..', '..');
 }
 
-/**
- * Main installation function
- */
-function install() {
-  // Skip if needed
-  if (shouldSkip()) {
-    return;
-  }
-
+if (!shouldSkip()) {
   try {
-    // Paths
-    const skillsSourceDir = join(__dirname, '..', 'skills');
     const projectRoot = findProjectRoot();
-    const skillsBaseDir = join(projectRoot, '.claude', 'skills');
-
-    // Discover all *.md skill files
-    if (!existsSync(skillsSourceDir)) {
-      return;
-    }
-
-    const skillFiles = readdirSync(skillsSourceDir).filter((f) =>
-      f.endsWith('.md')
-    );
-
-    if (skillFiles.length === 0) {
-      return;
-    }
-
-    // Clean up legacy flat file structure (.claude/skills/ax/*.md except SKILL.md)
-    const legacyDir = join(skillsBaseDir, 'ax');
-    if (existsSync(legacyDir)) {
-      try {
-        const legacyFiles = readdirSync(legacyDir).filter(
-          (f) => f.endsWith('.md') && f !== 'SKILL.md'
-        );
-        for (const f of legacyFiles) {
-          rmSync(join(legacyDir, f), { force: true });
-        }
-      } catch {
-        // Ignore cleanup errors
-      }
-    }
-
-    const results = [];
-
-    for (const file of skillFiles) {
-      const skillSource = join(skillsSourceDir, file);
-      const skillName = getSkillName(skillSource);
-      const skillDir = join(skillsBaseDir, skillName);
-      const skillTarget = join(skillDir, 'SKILL.md');
-
-      const packageVersion = getPackageVersion(skillSource);
-      const installedVersion = getInstalledVersion(skillTarget);
-
-      let shouldInstallFile = false;
-      let action = 'Installed';
-      let versionInfo = '';
-
-      if (!existsSync(skillTarget)) {
-        shouldInstallFile = true;
-        versionInfo = packageVersion ? ` (v${packageVersion})` : '';
-      } else if (installedVersion && packageVersion) {
-        const comparison = compareSemver(packageVersion, installedVersion);
-        if (comparison > 0) {
-          shouldInstallFile = true;
-          action = 'Upgraded';
-          versionInfo = ` (v${installedVersion} \u2192 v${packageVersion})`;
-        }
-      } else if (!installedVersion && existsSync(skillTarget)) {
-        shouldInstallFile = true;
-        action = 'Upgraded';
-        versionInfo = packageVersion ? ` (v${packageVersion})` : '';
-      }
-
-      if (shouldInstallFile) {
-        if (!existsSync(skillDir)) {
-          mkdirSync(skillDir, { recursive: true });
-        }
-
-        const content = readFileSync(skillSource, 'utf8');
-        writeFileSync(skillTarget, content, 'utf8');
-        results.push({ file: skillName, action, versionInfo });
-      }
-    }
-
-    if (results.length > 0 && isInteractive()) {
-      const noun = results.length === 1 ? 'skill' : 'skills';
-      const details = results
-        .map((r) => `${r.action} ${r.file}${r.versionInfo}`)
-        .join(', ');
+    const installed = autoSkillInstallEnabled(projectRoot)
+      ? installSkills(join(__dirname, '..'), projectRoot, {
+          upgradeInstalled: true,
+        })
+      : [];
+    if (installed.length > 0 && process.stdout.isTTY) {
       console.log(
-        `\u2713 ${results.length} Ax Claude Code ${noun}: ${details}`
+        '✓ Ax skills updated; entry point includes local reference guides.'
       );
     }
   } catch {
-    // Silent failure - never break npm install
-    // The CLI command can be used for manual installation
+    // Manual recovery: npx @ax-llm/ax setup-claude
   }
 }
-
-// Run installation
-install();