linchpin-cli 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# Linchpin
+
+**The "Don't Break My App" Tool**
+
+AI-powered dependency management for solo founders who code but aren't DevOps experts.
+
+## The Problem
+
+You built your app 6 months ago. Now your dependencies are showing red warnings everywhere. You're afraid to touch anything because:
+
+- "If I run `npm install`, will my app stop working?"
+- "ChatGPT told me to install X, but now Y is broken"
+- Big companies have DevOps teams. You have... anxiety.
+
+## The Solution
+
+Linchpin scans your project and tells you what's safe to update in **plain English**.
+
+```bash
+npx linchpin-cli
+```
+
+That's it. One command. No installation required.
+
+## What You Get
+
+```
+🔍 Linchpin: Scanning dependencies...
+
+┌────────────────────┬───────────────┬───────────────┬────────────┐
+│ Package            │ Current       │ Latest        │ Status     │
+├────────────────────┼───────────────┼───────────────┼────────────┤
+│ chalk              │ ^4.1.2        │ 5.6.2         │ ⚠ MAJOR    │
+│ dotenv             │ ^17.2.3       │ 17.2.3        │ OK         │
+│ typescript         │ ^5.3.2        │ 5.9.3         │ MINOR      │
+└────────────────────┴───────────────┴───────────────┴────────────┘
+
+📊 Summary: 1 major · 1 minor · 0 patch
+```
+
+## Commands
+
+```bash
+# Scan your project (free - uses npm registry)
+npx linchpin-cli
+
+# Deep scan with AI risk analysis (requires API key)
+npx linchpin-cli --deep
+
+# Get plain-English explanation of upgrade risks
+npx linchpin-cli explain chalk
+
+# Safely upgrade a package (creates backup first)
+npx linchpin-cli align chalk
+
+# Batch upgrade all packages interactively
+npx linchpin-cli align --all
+```
+
+## Features
+
+### Plain English Mode (Default)
+
+Instead of jargon like "ESM-only breaking CommonJS", you get:
+
+```
+🎯 Risk Level: Medium
+💡 Plain English: This update changes how files talk to each other.
+   It will break your app unless you spend ~2 hours fixing code.
+✅ Recommendation: Skip for now.
+```
+
+### Auto-Backup (Panic Button)
+
+Before any upgrade, Linchpin creates a git snapshot:
+
+```
+💾 Created restore point. If things break, run: git reset --hard HEAD~1
+```
+
+### Two-Layer Safety
+
+1. **SemVer Gate**: Major version jumps are flagged automatically
+2. **AI Gate**: Deep analysis explains the actual risk
+
+## Setup (Optional)
+
+The basic scan is **free** and uses the npm registry directly.
+
+For AI-powered features (`--deep`, `explain`), add a Perplexity API key:
+
+```bash
+# Create .env file in your project
+echo "PERPLEXITY_API_KEY=your-key-here" > .env
+```
+
+Get a key at: https://www.perplexity.ai/settings/api
+
+## For Experienced Devs
+
+Add `--technical` for the old-school output:
+
+```bash
+npx linchpin-cli explain chalk --technical
+```
+
+## License
+
+MIT

package/dist/bin/vm.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const dotenv_1 = __importDefault(require("dotenv"));
+dotenv_1.default.config(); // Load env vars once at entry point
+const commander_1 = require("commander");
+const check_1 = require("../src/commands/check");
+const explain_1 = require("../src/commands/explain");
+const align_1 = require("../src/commands/align");
+const program = new commander_1.Command();
+program
+    .name('linchpin')
+    .description("Linchpin: The 'Don't Break My App' Tool")
+    .version('0.1.0');
+program
+    .command('check', { isDefault: true })
+    .description('Scan your project for outdated dependencies')
+    .option('-d, --deep', 'Deep scan with AI risk analysis')
+    .option('-t, --technical', 'Technical output for experienced devs')
+    .action((options) => (0, check_1.checkCommand)(options));
+program
+    .command('explain <package>')
+    .description('Get a plain-English breakdown of upgrade risks')
+    .option('-t, --technical', 'Technical output for experienced devs')
+    .action((pkg, options) => (0, explain_1.explainCommand)(pkg, options));
+program
+    .command('align [package]')
+    .description('Safely update packages with auto-backup')
+    .option('-a, --all', 'Update all outdated packages interactively')
+    .action((pkgName, options) => (0, align_1.alignCommand)(pkgName, options));
+program.parse(process.argv);

package/dist/src/commands/align.js

@@ -0,0 +1,242 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alignCommand = alignCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const child_process_1 = require("child_process");
+const files_1 = require("../lib/files");
+const ai_1 = require("../lib/ai");
+const npm_1 = require("../lib/npm");
+// Helper: Returns true if the major version changed (e.g. "4.1.2" -> "5.0.0")
+function isMajorUpgrade(current, latest) {
+    const cleanCurrent = current.replace(/[^0-9.]/g, '');
+    const currentMajor = parseInt(cleanCurrent.split('.')[0]);
+    const latestMajor = parseInt(latest.split('.')[0]);
+    return latestMajor > currentMajor;
+}
+// Helper: Check if we're in a git repo
+function isGitRepo() {
+    try {
+        (0, child_process_1.execSync)('git rev-parse --is-inside-work-tree', { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Helper: Create a restore point before upgrades
+function createRestorePoint() {
+    if (!isGitRepo()) {
+        return false;
+    }
+    try {
+        // Stage package files
+        (0, child_process_1.execSync)('git add package.json package-lock.json 2>nul || git add package.json', { stdio: 'pipe' });
+        // Create backup commit
+        const timestamp = new Date().toISOString().slice(0, 19).replace('T', ' ');
+        (0, child_process_1.execSync)(`git commit -m "linchpin: pre-update snapshot (${timestamp})" --allow-empty`, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function alignCommand(pkgNameOrOptions, options) {
+    // Handle both: pin align <package> and pin align --all
+    if (typeof pkgNameOrOptions === 'object' || options?.all) {
+        await alignAllPackages();
+    }
+    else if (pkgNameOrOptions) {
+        await alignSinglePackage(pkgNameOrOptions);
+    }
+    else {
+        console.log(chalk_1.default.yellow('Usage: pin align <package> or pin align --all'));
+    }
+}
+async function alignSinglePackage(pkgName) {
+    const useAI = (0, npm_1.hasApiKey)();
+    console.log(chalk_1.default.blue.bold(`\n🔧 Linchpin: Aligning ${pkgName}...\n`));
+    const pkg = await (0, files_1.getPackageJson)();
+    if (!pkg) {
+        console.log(chalk_1.default.red('❌ No package.json found!'));
+        return;
+    }
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const currentVer = allDeps[pkgName];
+    if (!currentVer) {
+        console.log(chalk_1.default.red(`❌ Package "${pkgName}" not found.`));
+        return;
+    }
+    process.stdout.write(chalk_1.default.yellow('  Finding ideal version...'));
+    // Use npm registry (free) or AI depending on API key
+    const latestVer = useAI ? await (0, ai_1.getLatestVersion)(pkgName) : (0, npm_1.getRegistryVersion)(pkgName);
+    console.log(chalk_1.default.green(` Found ${latestVer}`));
+    const cleanCurrent = currentVer.replace(/^[\^~]/, '');
+    if (cleanCurrent === latestVer) {
+        console.log(chalk_1.default.green('  ✅ Already up to date.'));
+        return;
+    }
+    console.log(chalk_1.default.gray(`\n  Current: ${currentVer}`));
+    console.log(chalk_1.default.cyan(`  Target:  ${latestVer}`));
+    // --- SAFETY LOGIC: Check for major version jump ---
+    const majorChange = isMajorUpgrade(currentVer, latestVer);
+    if (majorChange) {
+        console.log(chalk_1.default.bgRed.white.bold(`\n  ⚠️  MAJOR VERSION JUMP DETECTED (${cleanCurrent} → ${latestVer})`));
+        if (useAI) {
+            console.log(chalk_1.default.yellow('\n  Checking for breaking changes with AI...'));
+            const risk = await (0, ai_1.getUpgradeRisks)(pkgName, currentVer, latestVer);
+            console.log(chalk_1.default.gray('\n  ------------------------------------------------'));
+            console.log(risk);
+            console.log(chalk_1.default.gray('  ------------------------------------------------\n'));
+        }
+        else {
+            console.log(chalk_1.default.yellow('\n  ℹ️  Set PERPLEXITY_API_KEY for AI risk analysis.'));
+            console.log(chalk_1.default.gray('     Get one at: https://www.perplexity.ai/settings/api\n'));
+        }
+    }
+    const answers = await inquirer_1.default.prompt([
+        {
+            type: 'confirm',
+            name: 'confirm',
+            message: majorChange
+                ? chalk_1.default.red(`⚠️  This looks risky. Are you SURE you want to upgrade ${pkgName}?`)
+                : `Safe to upgrade ${pkgName} to ${latestVer}?`,
+            default: !majorChange // Default No if risky, Yes if safe
+        }
+    ]);
+    if (!answers.confirm) {
+        console.log(chalk_1.default.yellow('\n  🛡️  Upgrade blocked. Smart move.'));
+        return;
+    }
+    // Create restore point before installing
+    const hasBackup = createRestorePoint();
+    if (hasBackup) {
+        console.log(chalk_1.default.gray('\n  💾 Created restore point. If things break, run: git reset --hard HEAD~1'));
+    }
+    console.log(chalk_1.default.blue('\n  🚀 Installing...'));
+    try {
+        (0, child_process_1.execSync)(`npm install ${pkgName}@${latestVer}`, { stdio: 'inherit' });
+        console.log(chalk_1.default.green(`\n  ✅ Success! ${pkgName} is now at ${latestVer}`));
+    }
+    catch (error) {
+        console.log(chalk_1.default.red('\n  ❌ Update failed. Check the npm errors above.'));
+        if (hasBackup) {
+            console.log(chalk_1.default.yellow('  💡 To undo: git reset --hard HEAD~1'));
+        }
+    }
+}
+async function alignAllPackages() {
+    const useAI = (0, npm_1.hasApiKey)();
+    const source = useAI ? 'AI' : 'npm registry';
+    console.log(chalk_1.default.blue.bold('\n🔧 Linchpin: Scanning for updates...\n'));
+    const pkg = await (0, files_1.getPackageJson)();
+    if (!pkg) {
+        console.log(chalk_1.default.red('❌ No package.json found!'));
+        return;
+    }
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const depEntries = Object.entries(allDeps);
+    if (depEntries.length === 0) {
+        console.log(chalk_1.default.yellow('⚠️  No dependencies found.'));
+        return;
+    }
+    console.log(chalk_1.default.yellow(`  Checking ${depEntries.length} packages via ${source}...\n`));
+    const updates = [];
+    for (const [name, currentVersion] of depEntries) {
+        if (process.stdout.isTTY) {
+            process.stdout.write(`  Checking ${name}... `);
+        }
+        // Use npm registry (free) or AI depending on API key
+        const latestVersion = useAI ? await (0, ai_1.getLatestVersion)(name) : (0, npm_1.getRegistryVersion)(name);
+        if (process.stdout.isTTY && process.stdout.clearLine && process.stdout.cursorTo) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        const cleanCurrent = currentVersion.replace(/^[\^~]/, '');
+        if (cleanCurrent !== latestVersion && latestVersion !== 'Error' && latestVersion !== 'Unknown') {
+            const isRisky = isMajorUpgrade(currentVersion, latestVersion);
+            updates.push({
+                name,
+                current: currentVersion,
+                latest: latestVersion,
+                risky: isRisky
+            });
+        }
+    }
+    if (updates.length === 0) {
+        console.log(chalk_1.default.green('  ✅ All packages are up to date!'));
+        return;
+    }
+    console.log(chalk_1.default.cyan(`\n  Found ${updates.length} packages with updates available:\n`));
+    const answers = await inquirer_1.default.prompt([
+        {
+            type: 'checkbox',
+            name: 'selected',
+            message: 'Select packages to update (risky ones unchecked by default):',
+            pageSize: 15,
+            choices: updates.map(u => {
+                const label = u.risky
+                    ? chalk_1.default.red(`⚠️  ${u.name} (${u.current} → ${u.latest}) - MAJOR`)
+                    : chalk_1.default.green(`✓ ${u.name} (${u.current} → ${u.latest})`);
+                return {
+                    name: label,
+                    value: { name: u.name, version: u.latest, risky: u.risky },
+                    checked: !u.risky // Uncheck risky ones by default
+                };
+            })
+        }
+    ]);
+    const selected = answers.selected;
+    if (selected.length === 0) {
+        console.log(chalk_1.default.yellow('\n  🚫 No packages selected. No changes made.'));
+        return;
+    }
+    // Warn if any risky packages were selected
+    const riskySelected = selected.filter(s => s.risky);
+    if (riskySelected.length > 0) {
+        console.log(chalk_1.default.bgRed.white.bold(`\n  ⚠️  You selected ${riskySelected.length} risky package(s)!`));
+        const confirmRisky = await inquirer_1.default.prompt([
+            {
+                type: 'confirm',
+                name: 'proceed',
+                message: chalk_1.default.red('Are you SURE you want to proceed with major upgrades?'),
+                default: false
+            }
+        ]);
+        if (!confirmRisky.proceed) {
+            console.log(chalk_1.default.yellow('\n  🛡️  Upgrade cancelled. Smart move.'));
+            return;
+        }
+    }
+    // Create restore point before installing
+    const hasBackup = createRestorePoint();
+    if (hasBackup) {
+        console.log(chalk_1.default.gray('\n  💾 Created restore point. If things break, run: git reset --hard HEAD~1'));
+    }
+    console.log(chalk_1.default.blue(`\n  🚀 Installing ${selected.length} package(s)...\n`));
+    let successCount = 0;
+    let failCount = 0;
+    for (const pkg of selected) {
+        try {
+            console.log(chalk_1.default.gray(`  Installing ${pkg.name}@${pkg.version}...`));
+            (0, child_process_1.execSync)(`npm install ${pkg.name}@${pkg.version}`, { stdio: 'pipe' });
+            successCount++;
+        }
+        catch (error) {
+            console.log(chalk_1.default.red(`  ❌ Failed: ${pkg.name}`));
+            failCount++;
+        }
+    }
+    console.log(chalk_1.default.green(`\n  ✅ Done! ${successCount} updated, ${failCount} failed.`));
+    // Show restore hint if any failures
+    if (failCount > 0 && hasBackup) {
+        console.log(chalk_1.default.yellow('  💡 To undo all changes: git reset --hard HEAD~1'));
+    }
+    // Mode indicator
+    if (!useAI) {
+        console.log(chalk_1.default.gray('\n  ℹ️  Free mode (npm registry). Set PERPLEXITY_API_KEY for AI risk analysis.'));
+    }
+}

package/dist/src/commands/check.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCommand = checkCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const cli_table3_1 = __importDefault(require("cli-table3"));
+const files_1 = require("../lib/files");
+const ai_1 = require("../lib/ai");
+const npm_1 = require("../lib/npm");
+// Helper: Determine upgrade type (MAJOR, MINOR, PATCH)
+function getUpgradeType(current, latest) {
+    const cleanCurrent = current.replace(/[^0-9.]/g, '');
+    const cleanLatest = latest.replace(/[^0-9.]/g, '');
+    const [curMajor, curMinor] = cleanCurrent.split('.').map(Number);
+    const [latMajor, latMinor] = cleanLatest.split('.').map(Number);
+    if (latMajor > curMajor)
+        return 'MAJOR';
+    if (latMinor > curMinor)
+        return 'MINOR';
+    if (cleanCurrent !== cleanLatest)
+        return 'PATCH';
+    return 'OK';
+}
+// Helper: Color status by severity
+function colorStatus(type) {
+    switch (type) {
+        case 'MAJOR': return chalk_1.default.red.bold('⚠ MAJOR');
+        case 'MINOR': return chalk_1.default.yellow('MINOR');
+        case 'PATCH': return chalk_1.default.green('PATCH');
+        case 'OK': return chalk_1.default.green('OK');
+    }
+}
+async function checkCommand(options = {}) {
+    const isDeep = options.deep || false;
+    const isTechnical = options.technical || false;
+    const useAI = (0, npm_1.hasApiKey)();
+    // Deep scan requires API key
+    if (isDeep && !useAI) {
+        console.log(chalk_1.default.red('\n❌ Deep scan requires an API key.'));
+        console.log(chalk_1.default.yellow('   Set PERPLEXITY_API_KEY in your .env file'));
+        console.log(chalk_1.default.gray('   Get one at: https://www.perplexity.ai/settings/api\n'));
+        return;
+    }
+    const scanType = isDeep ? 'Deep scanning' : 'Scanning';
+    const source = useAI ? 'AI' : 'npm registry';
+    console.log(chalk_1.default.blue.bold(`\n🔍 Linchpin: ${scanType} dependencies...\n`));
+    const pkg = await (0, files_1.getPackageJson)();
+    if (!pkg) {
+        console.log(chalk_1.default.red('❌ No package.json found!'));
+        console.log(chalk_1.default.yellow('   Make sure you are in the root of your project.'));
+        return;
+    }
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const depEntries = Object.entries(allDeps);
+    if (depEntries.length === 0) {
+        console.log(chalk_1.default.yellow('⚠️  Found package.json, but no dependencies listed.'));
+        return;
+    }
+    console.log(chalk_1.default.yellow(`⚡ Checking ${depEntries.length} packages via ${source}...\n`));
+    // Collect version info
+    const packageData = [];
+    for (const [name, currentVersion] of depEntries) {
+        if (process.stdout.isTTY) {
+            process.stdout.write(`  Checking ${name}... `);
+        }
+        // Use npm registry (free) or AI depending on API key
+        const latestVersion = useAI
+            ? await (0, ai_1.getLatestVersion)(name)
+            : (0, npm_1.getRegistryVersion)(name);
+        if (process.stdout.isTTY && process.stdout.clearLine && process.stdout.cursorTo) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        packageData.push({ name, current: currentVersion, latest: latestVersion });
+    }
+    // Get risk analysis if deep scan (requires API key)
+    let riskMap = new Map();
+    if (isDeep && useAI) {
+        const modeLabel = isTechnical ? 'technical' : 'plain English';
+        console.log(chalk_1.default.yellow(`\n🧠 Analyzing upgrade risks (${modeLabel} mode)...\n`));
+        const risks = await (0, ai_1.getBatchRiskAnalysis)(packageData, isTechnical);
+        risks.forEach(r => riskMap.set(r.name, r));
+    }
+    // Build table
+    const tableHead = isDeep
+        ? ['Package', 'Current', 'Latest', 'Status', 'Safe Ver', 'Risk']
+        : ['Package', 'Current', 'Latest', 'Status'];
+    const colWidths = isDeep
+        ? [18, 12, 12, 12, 12, 24]
+        : [20, 15, 15, 12];
+    const table = new cli_table3_1.default({
+        head: tableHead,
+        colWidths,
+        style: {
+            head: ['white', 'bold'],
+            border: ['gray']
+        },
+        wordWrap: true
+    });
+    let majorCount = 0;
+    let minorCount = 0;
+    let patchCount = 0;
+    for (const { name, current, latest } of packageData) {
+        const upgradeType = getUpgradeType(current, latest);
+        const status = colorStatus(upgradeType);
+        // Track counts for summary
+        if (upgradeType === 'MAJOR')
+            majorCount++;
+        if (upgradeType === 'MINOR')
+            minorCount++;
+        if (upgradeType === 'PATCH')
+            patchCount++;
+        const displayName = chalk_1.default.bold(name);
+        if (isDeep) {
+            const risk = riskMap.get(name);
+            const safeVer = risk?.safeVersion || (upgradeType !== 'OK' ? '—' : latest);
+            const riskText = risk?.risk || (upgradeType !== 'OK' ? '—' : '');
+            const riskColor = risk?.risk === 'Safe' || upgradeType === 'OK'
+                ? chalk_1.default.green(riskText)
+                : chalk_1.default.yellow(riskText);
+            table.push([displayName, current, latest, status, safeVer, riskColor]);
+        }
+        else {
+            table.push([displayName, current, latest, status]);
+        }
+    }
+    console.log(table.toString());
+    // Summary footer
+    const totalUpdates = majorCount + minorCount + patchCount;
+    if (totalUpdates > 0) {
+        console.log(chalk_1.default.gray('\n  ─────────────────────────────────────────────'));
+        console.log(`  📊 Summary: ` +
+            chalk_1.default.red(`${majorCount} major`) + ` · ` +
+            chalk_1.default.yellow(`${minorCount} minor`) + ` · ` +
+            chalk_1.default.green(`${patchCount} patch`));
+    }
+    // Mode indicator
+    if (!useAI) {
+        console.log(chalk_1.default.gray('\n  ℹ️  Free mode (npm registry). Set PERPLEXITY_API_KEY for AI features.'));
+    }
+    // Action hints
+    console.log(chalk_1.default.gray('\n  💡 Actions:'));
+    if (!isDeep && useAI) {
+        console.log(chalk_1.default.gray('     linchpin --deep        Full risk analysis'));
+    }
+    console.log(chalk_1.default.gray('     linchpin explain <pkg> Detailed breakdown'));
+    console.log(chalk_1.default.gray('     linchpin align <pkg>   Safe upgrade wizard'));
+    console.log(chalk_1.default.gray('     linchpin align --all   Batch upgrade mode\n'));
+}

package/dist/src/commands/explain.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainCommand = explainCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const files_1 = require("../lib/files");
+const ai_1 = require("../lib/ai");
+const npm_1 = require("../lib/npm");
+async function explainCommand(pkgName, options = {}) {
+    const isTechnical = options.technical || false;
+    // Explain requires API key for risk analysis
+    if (!(0, npm_1.hasApiKey)()) {
+        console.log(chalk_1.default.red('\n❌ The explain command requires an API key for AI analysis.'));
+        console.log(chalk_1.default.yellow('   Set PERPLEXITY_API_KEY in your .env file'));
+        console.log(chalk_1.default.gray('   Get one at: https://www.perplexity.ai/settings/api\n'));
+        console.log(chalk_1.default.gray('   Tip: Use "pin check" (free) to see version differences.\n'));
+        return;
+    }
+    console.log(chalk_1.default.blue.bold(`\n🕵️  Investigating ${pkgName}...\n`));
+    // 1. Get current version from local file
+    const pkg = await (0, files_1.getPackageJson)();
+    if (!pkg) {
+        console.log(chalk_1.default.red('❌ No package.json found!'));
+        return;
+    }
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const currentVer = allDeps[pkgName];
+    if (!currentVer) {
+        console.log(chalk_1.default.red(`❌ Package "${pkgName}" not found in your package.json`));
+        return;
+    }
+    // 2. Get real latest version (use registry for speed, AI not needed here)
+    process.stdout.write(chalk_1.default.yellow('  Checking latest version...'));
+    const latestVer = (0, npm_1.getRegistryVersion)(pkgName) || await (0, ai_1.getLatestVersion)(pkgName);
+    console.log(chalk_1.default.green(` Found ${latestVer}`));
+    // Strip ^ or ~ for comparison
+    const cleanCurrent = currentVer.replace(/^[\^~]/, '');
+    if (cleanCurrent === latestVer) {
+        console.log(chalk_1.default.green('\n✅ You are already on the latest version!'));
+        return;
+    }
+    // 3. Ask the AI for the risk analysis
+    const modeLabel = isTechnical ? 'technical' : 'plain English';
+    console.log(chalk_1.default.yellow(`\n🧠 Analyzing changelogs (${modeLabel} mode)...`));
+    const riskAnalysis = await (0, ai_1.getUpgradeRisks)(pkgName, currentVer, latestVer, isTechnical);
+    // 4. Print the report
+    console.log(chalk_1.default.bold('\n┌─────────────────── RISK REPORT ───────────────────┐'));
+    console.log(riskAnalysis);
+    console.log(chalk_1.default.bold('└───────────────────────────────────────────────────┘'));
+    // Action hint
+    console.log(chalk_1.default.gray(`\n  💡 To upgrade: linchpin align ${pkgName}\n`));
+}

package/dist/src/lib/ai.js

@@ -0,0 +1,149 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLatestVersion = getLatestVersion;
+exports.getUpgradeRisks = getUpgradeRisks;
+exports.getBatchRiskAnalysis = getBatchRiskAnalysis;
+const openai_1 = __importDefault(require("openai"));
+let client = null;
+function getClient() {
+    if (!client) {
+        const apiKey = process.env.PERPLEXITY_API_KEY;
+        if (!apiKey) {
+            throw new Error('Missing PERPLEXITY_API_KEY in .env file');
+        }
+        client = new openai_1.default({
+            apiKey: apiKey,
+            baseURL: 'https://api.perplexity.ai'
+        });
+    }
+    return client;
+}
+async function getLatestVersion(packageName) {
+    try {
+        const response = await getClient().chat.completions.create({
+            model: 'sonar-pro',
+            messages: [
+                {
+                    role: 'system',
+                    content: 'You are a precise JSON-only API. You output ONLY valid JSON.'
+                },
+                {
+                    role: 'user',
+                    content: `Find the absolute latest stable release version for the npm package "${packageName}". Return a JSON object with a single key "version". Example: {"version": "18.2.0"}. Do not include any other text.`
+                }
+            ]
+        });
+        const content = response.choices[0].message.content || '{}';
+        // Clean up if the AI adds markdown blocks like ```json ... ```
+        const cleanJson = content.replace(/```json|```/g, '').trim();
+        const data = JSON.parse(cleanJson);
+        return data.version || 'Unknown';
+    }
+    catch (error) {
+        if (process.env.DEBUG) {
+            console.error('AI Error:', error instanceof Error ? error.message : error);
+        }
+        return 'Error';
+    }
+}
+async function getUpgradeRisks(pkgName, currentVer, latestVer, technical = false) {
+    // Plain English (default) - for solopreneurs/founders
+    const founderPrompt = {
+        system: `You are a friendly tech advisor explaining things to a solo founder who codes but isn't a DevOps expert.
+No jargon. Simple language. Be reassuring but honest.
+Format your response like this:
+🎯 Risk Level: [Low/Medium/High]
+💡 Plain English: [What this means for your app in 1-2 sentences]
+⏱️ Effort: [How much work to fix if something breaks]
+✅ Recommendation: [Should they update or skip?]`,
+        user: `I'm a solo founder and I want to update "${pkgName}" from ${currentVer} to ${latestVer}.
+Will this break my app? Is it worth the headache? Give me the honest truth in plain English.`
+    };
+    // Technical mode - for experienced devs
+    const technicalPrompt = {
+        system: 'You are a senior DevOps engineer. Be concise. Bullet points only.',
+        user: `I am upgrading the npm package "${pkgName}" from ${currentVer} to ${latestVer}. What are the major breaking changes or risks? If there are none, say "Safe to upgrade."`
+    };
+    const prompt = technical ? technicalPrompt : founderPrompt;
+    try {
+        const response = await getClient().chat.completions.create({
+            model: 'sonar-pro',
+            messages: [
+                { role: 'system', content: prompt.system },
+                { role: 'user', content: prompt.user }
+            ]
+        });
+        return response.choices[0].message.content || 'No info found.';
+    }
+    catch (error) {
+        console.error('AI Error:', error instanceof Error ? error.message : error);
+        return 'Could not fetch risks.';
+    }
+}
+async function getBatchRiskAnalysis(packages, technical = false) {
+    const outdatedPkgs = packages.filter(p => {
+        const cleanCurrent = p.current.replace(/^[\^~]/, '');
+        return cleanCurrent !== p.latest && p.latest !== 'Error' && p.latest !== 'Unknown';
+    });
+    if (outdatedPkgs.length === 0) {
+        return [];
+    }
+    const pkgList = outdatedPkgs
+        .map(p => `- ${p.name}: ${p.current} → ${p.latest}`)
+        .join('\n');
+    // Plain English (default) - for solopreneurs
+    const founderPrompt = `Analyze these npm package upgrades for a solo founder who isn't a DevOps expert:
+${pkgList}
+
+Return a JSON array. For each package, explain the risk in PLAIN ENGLISH (no jargon).
+{
+  "name": "package-name",
+  "safeVersion": "recommended version",
+  "risk": "Plain English risk (e.g., 'Will break your app' or 'Safe to update' or 'Skip - not worth the headache')"
+}
+
+Example: [{"name":"chalk","safeVersion":"4.1.2","risk":"Skip - v5 breaks older setups"},{"name":"dotenv","safeVersion":"17.0.0","risk":"Safe to update"}]`;
+    // Technical mode - for experienced devs
+    const technicalPrompt = `Analyze these npm package upgrades for breaking changes:
+${pkgList}
+
+Return a JSON array with objects for each package:
+{
+  "name": "package-name",
+  "safeVersion": "recommended safe version (latest if safe, or last stable major)",
+  "risk": "brief risk (10 words max) or 'Safe' if no breaking changes"
+}
+
+Example: [{"name":"chalk","safeVersion":"4.1.2","risk":"ESM-only in v5"},{"name":"dotenv","safeVersion":"17.0.0","risk":"Safe"}]`;
+    try {
+        const response = await getClient().chat.completions.create({
+            model: 'sonar-pro',
+            messages: [
+                {
+                    role: 'system',
+                    content: 'You are a precise JSON-only API. Output ONLY valid JSON array, no markdown.'
+                },
+                {
+                    role: 'user',
+                    content: technical ? technicalPrompt : founderPrompt
+                }
+            ]
+        });
+        const content = response.choices[0].message.content || '[]';
+        const cleanJson = content.replace(/```json|```/g, '').trim();
+        return JSON.parse(cleanJson);
+    }
+    catch (error) {
+        if (process.env.DEBUG) {
+            console.error('AI Error:', error instanceof Error ? error.message : error);
+        }
+        return outdatedPkgs.map(p => ({
+            name: p.name,
+            safeVersion: p.latest,
+            risk: 'Analysis failed'
+        }));
+    }
+}

package/dist/src/lib/files.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPackageJson = getPackageJson;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+async function getPackageJson(dir = process.cwd()) {
+    const packagePath = (0, path_1.join)(dir, 'package.json');
+    try {
+        const content = await (0, promises_1.readFile)(packagePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        console.error('Error reading package.json:', error instanceof Error ? error.message : error);
+        return null;
+    }
+}

package/dist/src/lib/npm.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRegistryVersion = getRegistryVersion;
+exports.getRegistryVersions = getRegistryVersions;
+exports.hasApiKey = hasApiKey;
+const child_process_1 = require("child_process");
+/**
+ * Get latest version from npm registry (FREE, no API key needed)
+ * Falls back gracefully on error
+ */
+function getRegistryVersion(pkgName) {
+    try {
+        const result = (0, child_process_1.execSync)(`npm view ${pkgName} version`, {
+            encoding: 'utf-8',
+            timeout: 10000,
+            stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+        });
+        return result.trim();
+    }
+    catch (error) {
+        return 'Unknown';
+    }
+}
+/**
+ * Get multiple versions in parallel (batch optimization)
+ */
+async function getRegistryVersions(packages) {
+    const results = new Map();
+    // Run in parallel batches of 5 to avoid overwhelming npm
+    const batchSize = 5;
+    for (let i = 0; i < packages.length; i += batchSize) {
+        const batch = packages.slice(i, i + batchSize);
+        const promises = batch.map(async (pkg) => {
+            const version = getRegistryVersion(pkg);
+            results.set(pkg, version);
+        });
+        await Promise.all(promises);
+    }
+    return results;
+}
+/**
+ * Check if Perplexity API key is configured
+ */
+function hasApiKey() {
+    return !!process.env.PERPLEXITY_API_KEY;
+}

package/dist/src/utils/logger.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+// ANSI color codes for terminal output
+const colors = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    white: '\x1b[37m',
+};
+exports.logger = {
+    info: (message) => {
+        console.log(`${colors.blue}[INFO]${colors.reset} ${message}`);
+    },
+    success: (message) => {
+        console.log(`${colors.green}[SUCCESS]${colors.reset} ${message}`);
+    },
+    warn: (message) => {
+        console.log(`${colors.yellow}[WARN]${colors.reset} ${message}`);
+    },
+    error: (message) => {
+        console.log(`${colors.red}[ERROR]${colors.reset} ${message}`);
+    },
+    debug: (message) => {
+        if (process.env.DEBUG) {
+            console.log(`${colors.magenta}[DEBUG]${colors.reset} ${message}`);
+        }
+    },
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "linchpin-cli",
+  "version": "0.1.0",
+  "description": "Linchpin: The 'Don't Break My App' Tool - AI-powered dependency management for solo founders",
+  "main": "dist/src/index.js",
+  "bin": {
+    "linchpin": "./dist/bin/vm.js",
+    "pin": "./dist/bin/vm.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "ts-node bin/vm.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "dependency",
+    "npm",
+    "update",
+    "upgrade",
+    "ai",
+    "cli",
+    "devops",
+    "package-manager",
+    "security"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^11.1.0",
+    "dotenv": "^17.2.3",
+    "inquirer": "^8.2.6",
+    "openai": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^20.10.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.2"
+  }
+}