opencode-agent-kit 1.0.18 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 defuj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,7 +4,7 @@
 
 # Agent Kit — Setup Guide
 
-Complete setup guide for the **Agent Kit** — a portable multi-stack AI agent system for OpenCode. Includes 13 specialized agents, 62 skill playbooks, 37 slash commands, and 7 MCP servers.
+Complete setup guide for the **Agent Kit** — a portable multi-stack AI agent system for OpenCode. Includes 13 specialized agents, 63 skill playbooks, 39 slash commands, and 8 MCP servers.
 
 ```bash
 npx opencode-agent-kit init    # One command. Full team.
@@ -191,6 +191,10 @@ After installing `.opencode/`, the following slash commands are available:
 
 # Quality
 /sonarqube-scan [options]             # SonarQube quality scan (issues, security, coverage)
+
+# Memory
+/recall [query]                       # Search past observations and lessons
+/remember [text]                      # Save insight/decision to persistent memory
 ```
 
 ## Using the `.opencode/` Folder
@@ -340,6 +344,7 @@ Skills are stored in `.opencode/skills/` (local in the repo) — no need to sear
 | SEO Specialist             | frontend-patterns, web-design-guidelines, nuxt-ui                                                                                                                                                                                              |
 | **Android Developer**      | coding-standards, android-jetpack-compose, edge-to-edge, navigation-3, firebase-basics, play-billing, camera1-to-camerax, r8-analyzer, migrate-xml-views-to-jetpack-compose, gpc-setup, gpc-release-flow, gpc-preflight, gpc-vitals-monitoring |
 | **Flutter Developer**      | coding-standards, flutter (patterns), 10 Flutter skills, 9 Dart skills, firebase-basics                                                                                                                                                        |
+| **All Agents**             | agentmemory (persistent cross-session memory, 53 MCP tools)                                                                                                                                                                                   |
 
 ### Skills Not Required for Core Stack
 
@@ -363,6 +368,7 @@ These can be kept if your team uses multi-stack, but are optional.
 - `verification-loop` — Agent verification cycle
 - `nutrient-document-processing` — Document processing API
 - `project-guidelines-example` — Project guidelines example
+- `agentmemory` — Persistent cross-session memory with 53 MCP tools
 
 ## Skill Locations
 
@@ -431,8 +437,9 @@ From `.opencode/config.json`, agents use the following MCP servers:
 | `nuxt-ui`    | remote | enabled  | Nuxt UI component docs & examples                    |
 | `playwright` | stdio  | enabled  | Browser automation & E2E testing                     |
 | `postman`    | remote | enabled  | Postman API management (collections, requests, docs) |
-| `figma`      | stdio  | disabled | Figma design file access (optional)                  |
+| `figma`      | remote | disabled | Figma design file access (optional)                  |
 | `stitch`     | remote | disabled | Google Stitch AI design generation (optional)        |
+| `agentmemory`| local  | enabled  | Persistent cross-session memory (53 memory tools)    |
 
 To enable Figma MCP:
 
@@ -440,6 +447,15 @@ To enable Figma MCP:
 export FIGMA_ACCESS_TOKEN="your-token"
 ```
 
+To enable agentmemory:
+
+```bash
+npm install -g @agentmemory/agentmemory
+agentmemory                    # Start the memory server on :3111
+```
+
+Open `http://localhost:3113` for the real-time memory viewer.
+
 To enable Google Stitch MCP:
 
 ```bash

package/bin/commands/doctor.mjs

@@ -0,0 +1,164 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+
+const PKG_NAME = 'opencode-agent-kit';
+
+function check(condition, passMsg, failMsg) {
+  if (condition) {
+    console.log(`  ✓ ${passMsg}`);
+    return true;
+  }
+  console.log(`  ✗ ${failMsg}`);
+  return false;
+}
+
+function warn(msg) {
+  console.log(`  ⚠ ${msg}`);
+}
+
+export async function doctor(options) {
+  const targetDir = options.dir || process.cwd();
+  const { fix } = options;
+
+  console.log(`\n  ${PKG_NAME} doctor`);
+  console.log(`  ${'─'.repeat(50)}`);
+  console.log(`  Target: ${targetDir}\n`);
+
+  let allGood = true;
+
+  // 1. Check Node.js version
+  const nodeVersion = process.version;
+  const major = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  allGood &= check(
+    major >= 18,
+    `Node.js ${nodeVersion} (>= 18)`,
+    `Node.js ${nodeVersion} — need >= 18`,
+  );
+
+  // 2. Check package.json exists
+  const pkgPath = join(targetDir, 'package.json');
+  allGood &= check(
+    existsSync(pkgPath),
+    'package.json found',
+    'package.json not found',
+  );
+
+  // 3. Check opencode.json
+  const configPath = join(targetDir, 'opencode.json');
+  const hasConfig = existsSync(configPath);
+  allGood &= check(hasConfig, 'opencode.json found', 'opencode.json not found');
+
+  if (hasConfig) {
+    try {
+      JSON.parse(readFileSync(configPath, 'utf-8'));
+      check(true, 'opencode.json is valid JSON', '');
+    } catch {
+      allGood = false;
+      console.log('  ✗ opencode.json is not valid JSON');
+    }
+  }
+
+  // 4. Check .opencode directory
+  const opencodeDir = join(targetDir, '.opencode');
+  const hasOpencode = existsSync(opencodeDir);
+  allGood &= check(hasOpencode, '.opencode/ directory found', '.opencode/ directory not found');
+
+  if (hasOpencode) {
+    // 4a. Check agents
+    const agentsDir = join(opencodeDir, 'agents');
+    check(
+      existsSync(agentsDir),
+      '.opencode/agents/ found',
+      '.opencode/agents/ missing',
+    );
+
+    // 4b. Check instructions
+    const instrDir = join(opencodeDir, 'instructions');
+    check(
+      existsSync(instrDir),
+      '.opencode/instructions/ found',
+      '.opencode/instructions/ missing',
+    );
+
+    // 4c. Check skills
+    const skillsDir = join(opencodeDir, 'skills');
+    check(
+      existsSync(skillsDir),
+      '.opencode/skills/ found',
+      '.opencode/skills/ missing',
+    );
+
+    // 4d. Count agents
+    if (existsSync(agentsDir)) {
+      const agents = readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+      check(
+        agents.length >= 10,
+        `${agents.length} agent prompts found (expected 14)`,
+        `Only ${agents.length} agent prompts found (expected 14)`,
+      );
+    }
+
+    // 4e. Check kit-version
+    const versionFile = join(opencodeDir, '.kit-version');
+    if (existsSync(versionFile)) {
+      const installedVersion = readFileSync(versionFile, 'utf-8').trim();
+      try {
+        const latest = execSync(`npm view ${PKG_NAME} version`, {
+          encoding: 'utf-8',
+          timeout: 5000,
+        }).trim();
+        if (installedVersion !== latest) {
+          warn(`Kit v${installedVersion} installed, v${latest} available`);
+          if (fix) {
+            console.log('     → Run `npx opencode-agent-kit upgrade` to update');
+          }
+        } else {
+          check(true, `Kit version v${installedVersion} (up to date)`, '');
+        }
+      } catch {
+        warn('Could not check latest version (npm registry unreachable)');
+      }
+    } else {
+      warn('.kit-version not found');
+    }
+  }
+
+  // 5. Check .gitignore
+  const gitignorePath = join(targetDir, '.gitignore');
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, 'utf-8');
+    check(
+      content.includes('.opencode') || content.includes('opencode.json'),
+      '.gitignore covers .opencode/ files',
+      '.gitignore may not cover .opencode/ files',
+    );
+  } else {
+    warn('.gitignore not found');
+    if (fix) {
+      console.log('     → Run `opencode-agent-kit init` to create one');
+    }
+  }
+
+  // 6. Check global agentmemory
+  try {
+    execSync('agentmemory --version', { stdio: 'pipe', timeout: 3000 });
+    check(true, 'agentmemory (global) is installed', '');
+  } catch {
+    warn('agentmemory not installed globally');
+    if (fix) {
+      console.log('     → Run: npm install -g @agentmemory/agentmemory');
+    }
+  }
+
+  // Summary
+  console.log(`\n  ${'─'.repeat(50)}`);
+  if (allGood) {
+    console.log(`\n  ✅ All checks passed. Your setup looks good!\n`);
+  } else {
+    console.log(`\n  ⚠  Some checks failed. Review the issues above.\n`);
+    if (!fix) {
+      console.log(`  Tip: Run with --fix to enable actionable suggestions.\n`);
+    }
+  }
+}

package/bin/commands/init.mjs

@@ -6,15 +6,43 @@ import {
   writeFileSync,
   readdirSync,
   appendFileSync,
-} from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-import { execSync } from "child_process";
+} from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PKG_ROOT = join(__dirname, "..", "..");
-const TEMPLATE_DIR = join(PKG_ROOT, "template");
+const PKG_ROOT = join(__dirname, '..', '..');
+const TEMPLATE_DIR = join(PKG_ROOT, 'template');
+const PKG_NAME = 'opencode-agent-kit';
+
+// ANSI colors
+const C = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+};
+
+function info(msg) {
+  console.log(`  ${C.cyan}→${C.reset} ${msg}`);
+}
+
+function success(msg) {
+  console.log(`  ${C.green}✓${C.reset} ${msg}`);
+}
+
+function warn(msg) {
+  console.log(`  ${C.yellow}⚠${C.reset} ${msg}`);
+}
+
+function error(msg) {
+  console.log(`  ${C.red}✗${C.reset} ${msg}`);
+}
 
 function copyRecursive(src, dest) {
   if (!existsSync(src)) return;
@@ -146,130 +174,130 @@ export async function init(options) {
   const force = options.force;
   const skipInstall = options.skipInstall;
 
-  console.log(`\n  opencode-agent-kit init`);
+  console.log(`\n  ${C.bold}${PKG_NAME} init${C.reset}`);
+  console.log(`  ${C.dim}${'─'.repeat(50)}${C.reset}`);
 
   // 1. Validate target
   if (!existsSync(targetDir)) {
     console.error(`  ✗ Target directory does not exist: ${targetDir}`);
+    error(`Target directory does not exist: ${targetDir}`);
     process.exit(1);
   }
 
   // 2. Check if .opencode already exists
-  const opencodeDir = join(targetDir, ".opencode");
-  const userConfigPath = join(targetDir, "opencode.json");
+  const opencodeDir = join(targetDir, '.opencode');
+  const userConfigPath = join(targetDir, 'opencode.json');
 
   if (existsSync(opencodeDir) && !force) {
-    console.log(`  \n  ⚠  .opencode/ already exists in ${targetDir}`);
-    const rl = await import("readline/promises");
+    warn(`.opencode/ already exists in ${targetDir}`);
+    const rl = await import('readline/promises');
     const readline = rl.createInterface({
       input: process.stdin,
       output: process.stdout,
     });
-    const answer = await readline.question(
-      `  ? Overwrite existing files? [y/N] `,
-    );
+    const answer = await readline.question(`  ? Overwrite existing files? [y/N] `);
     readline.close();
-    if (answer.toLowerCase() !== "y") {
-      console.log(`  ✗ Aborted.`);
+    if (answer.toLowerCase() !== 'y') {
+      error('Aborted.');
       process.exit(0);
     }
   }
 
   // 3. Validate template exists
   if (!existsSync(TEMPLATE_DIR)) {
-    console.error(`  ✗ Template directory not found at ${TEMPLATE_DIR}`);
-    console.error(`    This is a bug. Please reinstall the package.`);
+    error(`Template directory not found at ${TEMPLATE_DIR}`);
+    error('This is a bug. Please reinstall the package.');
     process.exit(1);
   }
 
   // 4. Copy .opencode/ from template
-  console.log(`  \n  📁 Copying .opencode/ configuration...`);
-  copyRecursive(join(TEMPLATE_DIR, ".opencode"), opencodeDir);
+  info('Copying .opencode/ configuration...');
+  copyRecursive(join(TEMPLATE_DIR, '.opencode'), opencodeDir);
 
   // 5. Merge opencode.json
-  const templateConfigPath = join(TEMPLATE_DIR, "opencode.json");
+  const templateConfigPath = join(TEMPLATE_DIR, 'opencode.json');
   if (existsSync(templateConfigPath)) {
-    console.log(`  📝 Merging opencode.json...`);
-    const merged = mergeOencodeConfig(
-      templateConfigPath,
-      userConfigPath,
-      force,
-    );
-    writeFileSync(
-      userConfigPath,
-      JSON.stringify(merged, null, 2) + "\n",
-      "utf-8",
-    );
+    info('Merging opencode.json...');
+    const merged = mergeOencodeConfig(templateConfigPath, userConfigPath, force);
+    writeFileSync(userConfigPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
   }
 
   // 6. Copy opencode.example.json
-  const exampleSrc = join(TEMPLATE_DIR, "opencode.example.json");
-  const exampleDest = join(targetDir, "opencode.example.json");
+  const exampleSrc = join(TEMPLATE_DIR, 'opencode.example.json');
+  const exampleDest = join(targetDir, 'opencode.example.json');
   if (existsSync(exampleSrc)) {
-    console.log(`  📄 Copying opencode.example.json...`);
+    info('Copying opencode.example.json...');
     copyFileSync(exampleSrc, exampleDest);
   }
 
   // 7. Install dependencies
   if (!skipInstall) {
     const pm = detectPackageManager(opencodeDir);
-    console.log(`  📦 Installing .opencode/ dependencies with ${pm}...`);
+    info(`Installing .opencode/ dependencies with ${pm}...`);
     try {
-      execSync(`${pm} install`, { cwd: opencodeDir, stdio: "pipe" });
+      execSync(`${pm} install`, { cwd: opencodeDir, stdio: 'pipe' });
+      success('.opencode/ dependencies installed');
     } catch (err) {
-      console.error(`  ⚠  Dependency install failed: ${err.message}`);
-      console.error(`    You can run "${pm} install" manually in .opencode/`);
+      warn(`Dependency install failed: ${err.message}`);
+      warn(`You can run "${pm} install" manually in .opencode/`);
     }
   }
 
-  // 8. Update .gitignore
-  const gitignorePath = join(targetDir, ".gitignore");
-  const gitignoreEntries = [
-    ".opencode/*",
-    "opencode.json",
-    "opencode.example.json",
-  ];
+  // 8. Install agentmemory globally
+  if (!skipInstall) {
+    info('Setting up agentmemory (persistent memory)...');
+    try {
+      execSync('agentmemory --version', { stdio: 'pipe' });
+      success('agentmemory already installed');
+    } catch {
+      try {
+        execSync('npm install -g @agentmemory/agentmemory', {
+          stdio: 'pipe',
+          timeout: 60000,
+        });
+        success('agentmemory installed globally');
+      } catch (err) {
+        warn(`agentmemory global install failed: ${err.message}`);
+        warn('Run "npm install -g @agentmemory/agentmemory" manually');
+      }
+    }
+  }
+
+  // 9. Update .gitignore
+  const gitignorePath = join(targetDir, '.gitignore');
+  const gitignoreEntries = ['.opencode/*', 'opencode.json', 'opencode.example.json', 'data/'];
   if (!existsSync(gitignorePath)) {
-    writeFileSync(gitignorePath, gitignoreEntries.join("\n") + "\n", "utf-8");
-    console.log(`  📄 Created .gitignore...`);
+    writeFileSync(gitignorePath, gitignoreEntries.join('\n') + '\n', 'utf-8');
+    success('Created .gitignore');
   } else {
-    const gitignoreContent = readFileSync(gitignorePath, "utf-8");
+    const gitignoreContent = readFileSync(gitignorePath, 'utf-8');
     let appended = false;
     for (const entry of gitignoreEntries) {
       if (!gitignoreContent.includes(entry)) {
-        appendFileSync(gitignorePath, entry + "\n", "utf-8");
+        appendFileSync(gitignorePath, entry + '\n', 'utf-8');
         appended = true;
       }
     }
-    if (appended) {
-      console.log(`  📄 Updated .gitignore...`);
-    }
+    if (appended) success('Updated .gitignore');
   }
 
-  // 9. Write .kit-version for agent update checking
-  const pkgJson = JSON.parse(
-    readFileSync(join(PKG_ROOT, "package.json"), "utf-8"),
-  );
-  const versionFile = join(opencodeDir, ".kit-version");
-  writeFileSync(versionFile, pkgJson.version + "\n", "utf-8");
-
-  // 10. Done
-  console.log(`\n  ✅ opencode-agent-kit v${pkgJson.version} installed!\n`);
-  console.log(`     Location: ${targetDir}`);
-  console.log(`     What you got:`);
-  console.log(
-    `       • opencode.json              — 13 agents config with MCP servers`,
-  );
-  console.log(
-    `       • opencode.example.json      — Example config for reference`,
-  );
-  console.log(`       • .opencode/agents    — 14 agent prompt files`);
-  console.log(`       • .opencode/skills/    — 60+ skill playbooks`);
-  console.log(`       • .opencode/commands/  — 35+ slash commands`);
-  console.log(`       • .opencode/rules/     — Scoped coding rules`);
-  console.log(`       • .opencode/contexts/  — Dev/review/research contexts`);
-  console.log(`       • .opencode/docs/— Agent documentation`);
-  console.log(`\n     Next steps:`);
-  console.log(`       cd ${targetDir}`);
-  console.log(`       opencode\n`);
+  // 10. Write .kit-version for agent update checking
+  const pkgJson = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8'));
+  const versionFile = join(opencodeDir, '.kit-version');
+  writeFileSync(versionFile, pkgJson.version + '\n', 'utf-8');
+
+  // 11. Done — summary
+  console.log(`\n  ${C.bold}${C.green}✅ opencode-agent-kit v${pkgJson.version} installed!${C.reset}\n`);
+  console.log(`  ${C.dim}Location:${C.reset} ${targetDir}`);
+  console.log(`  ${C.dim}${'─'.repeat(30)}${C.reset}`);
+  console.log(`  ${C.bold}What you got:${C.reset}`);
+  console.log(`    • ${C.cyan}opencode.json${C.reset}          — 13 agents + MCP servers`);
+  console.log(`    • ${C.cyan}.opencode/agents/${C.reset}      — 14 agent prompt files`);
+  console.log(`    • ${C.cyan}.opencode/skills/${C.reset}      — 60+ skill playbooks`);
+  console.log(`    • ${C.cyan}.opencode/commands/${C.reset}    — 35+ slash commands`);
+  console.log(`    • ${C.cyan}.opencode/rules/${C.reset}       — Scoped coding rules`);
+  console.log(`    • ${C.cyan}.opencode/hooks/${C.reset}       — Automation hooks`);
+  console.log(`    • ${C.cyan}.opencode/docs/${C.reset}        — Agent documentation`);
+  console.log(`    • ${C.cyan}agentmemory${C.reset} (global)  — Persistent memory`);
+  console.log(`\n  ${C.bold}${C.green}→${C.reset} Next step: run ${C.cyan}opencode${C.reset} to start\n`);
 }

package/bin/commands/uninstall.mjs

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, unlinkSync, rmSync } from 'fs';
+import { join } from 'path';
+import { createInterface } from 'readline/promises';
+
+const PKG_NAME = 'opencode-agent-kit';
+
+export async function uninstall(options) {
+  const targetDir = options.dir || process.cwd();
+  const force = options.force;
+
+  console.log(`\n  ${PKG_NAME} uninstall`);
+  console.log(`  ${'─'.repeat(50)}`);
+  console.log(`  Target: ${targetDir}\n`);
+
+  if (!force) {
+    const readline = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await readline.question(
+      `  ⚠  This will remove .opencode/ and opencode.json from\n      ${targetDir}\n\n  ? Continue? [y/N] `,
+    );
+    readline.close();
+    if (answer.toLowerCase() !== 'y') {
+      console.log(`  ✗ Aborted.\n`);
+      process.exit(0);
+    }
+  }
+
+  // Remove .opencode/
+  const opencodeDir = join(targetDir, '.opencode');
+  if (existsSync(opencodeDir)) {
+    console.log(`  Removing .opencode/ ...`);
+    rmSync(opencodeDir, { recursive: true, force: true });
+    console.log(`  ✓ .opencode/ removed`);
+  } else {
+    console.log(`  - .opencode/ not found, skipping`);
+  }
+
+  // Remove opencode.json
+  const configPath = join(targetDir, 'opencode.json');
+  if (existsSync(configPath)) {
+    console.log(`  Removing opencode.json ...`);
+    unlinkSync(configPath);
+    console.log(`  ✓ opencode.json removed`);
+  } else {
+    console.log(`  - opencode.json not found, skipping`);
+  }
+
+  // Remove opencode.example.json
+  const examplePath = join(targetDir, 'opencode.example.json');
+  if (existsSync(examplePath)) {
+    console.log(`  Removing opencode.example.json ...`);
+    unlinkSync(examplePath);
+    console.log(`  ✓ opencode.example.json removed`);
+  }
+
+  // Clean up .gitignore entries (remove lines containing these patterns)
+  const gitignorePath = join(targetDir, '.gitignore');
+  if (existsSync(gitignorePath)) {
+    const entriesToRemove = ['.opencode/', 'opencode.json', 'opencode.example.json'];
+    const content = readFileSync(gitignorePath, 'utf-8');
+    const lines = content.split('\n').filter(line => {
+      return !entriesToRemove.some(e => line.trim().startsWith(e));
+    });
+    const newContent = lines.join('\n');
+    if (newContent !== content) {
+      // Write back without these entries
+      const { writeFileSync } = await import('fs');
+      writeFileSync(gitignorePath, newContent, 'utf-8');
+      console.log(`  ✓ .gitignore cleaned`);
+    }
+  }
+
+  // Clean .kit-version
+  const versionFile = join(opencodeDir, '.kit-version');
+  if (existsSync(versionFile)) {
+    unlinkSync(versionFile);
+  }
+
+  console.log(`\n  ✅ opencode-agent-kit has been removed from ${targetDir}\n`);
+}

package/bin/commands/upgrade.mjs

@@ -0,0 +1,65 @@
+import { execSync } from 'child_process';
+import { readFileSync } from 'fs';
+const PKG_NAME = 'opencode-agent-kit';
+
+/**
+ * Get the currently installed version from package.json
+ */
+function getCurrentVersion() {
+  const pkgPath = new globalThis.URL('../../package.json', import.meta.url);
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  return pkg.version;
+}
+
+/**
+ * Get the latest available version from npm
+ */
+function getLatestVersion() {
+  try {
+    return execSync(`npm view ${PKG_NAME} version`, {
+      encoding: 'utf-8',
+      timeout: 10000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function upgrade(options) {
+  const { verbose } = options;
+
+  console.log(`\n  ${PKG_NAME} upgrade`);
+  console.log(`  ${'─'.repeat(50)}\n`);
+
+  const current = getCurrentVersion();
+  console.log(`  Current version: v${current}`);
+
+  console.log(`  Checking npm registry...`);
+  const latest = getLatestVersion();
+
+  if (!latest) {
+    console.error(`  \n  ✗ Could not reach npm registry.`);
+    console.error(`    Check your internet connection and try again.`);
+    process.exit(1);
+  }
+
+  console.log(`  Latest version:  v${latest}`);
+
+  if (current === latest) {
+    console.log(`\n  ✓ You're up to date (v${current}).\n`);
+    return;
+  }
+
+  console.log(`\n  → Upgrading from v${current} to v${latest}...`);
+  try {
+    execSync(`npm install -g ${PKG_NAME}@latest`, {
+      stdio: verbose ? 'inherit' : 'pipe',
+      timeout: 60000,
+    });
+    console.log(`  ✓ Upgraded to v${latest}\n`);
+  } catch (err) {
+    console.error(`  ✗ Upgrade failed: ${err.message}`);
+    console.error(`    Try: npm install -g ${PKG_NAME}@latest`);
+    process.exit(1);
+  }
+}