review: scope plugin lock tracking cleanly (#362)

Co-authored-by: jackwener <jakevingoo@gmail.com>

Author: ByteYue

README.md

@@ -294,6 +294,8 @@ opencli plugin update --all                                 # Update all install
 opencli plugin uninstall my-tool                            # Remove
 ```
 
+`opencli plugin list` also shows the tracked short commit hash when a plugin version is recorded in `~/.opencli/plugins.lock.json`.
+
 | Plugin | Type | Description |
 |--------|------|-------------|
 | [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | YAML | GitHub Trending repositories |

README.zh-CN.md

@@ -296,6 +296,8 @@ opencli plugin update --all                                 # 更新全部已安
 opencli plugin uninstall my-tool                            # 卸载
 ```
 
+当 plugin 的版本被记录到 `~/.opencli/plugins.lock.json` 后，`opencli plugin list` 也会显示对应的短 commit hash。
+
 | 插件 | 类型 | 描述 |
 |------|------|------|
 | [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | YAML | GitHub Trending 仓库 |

docs/guide/plugins.md

@@ -37,6 +37,10 @@ opencli plugin install https://github.com/user/repo
 
 The repo name prefix `opencli-plugin-` is automatically stripped for the local directory name. For example, `opencli-plugin-hot-digest` becomes `hot-digest`.
 
+## Version Tracking
+
+OpenCLI records installed plugin versions in `~/.opencli/plugins.lock.json`. Each entry stores the plugin source, current git commit hash, install time, and last update time. `opencli plugin list` shows the short commit hash when version metadata is available.
+
 ## Creating a Plugin
 
 ### Option 1: YAML Plugin (Simplest)

docs/zh/guide/plugins.md

@@ -37,6 +37,10 @@ opencli plugin install https://github.com/user/repo
 
 如果仓库名带 `opencli-plugin-` 前缀，本地目录会自动去掉这个前缀。例如 `opencli-plugin-hot-digest` 会变成 `hot-digest`。
 
+## 版本追踪
+
+OpenCLI 会把已安装 plugin 的版本记录到 `~/.opencli/plugins.lock.json`。每条记录会保存 plugin source、当前 git commit hash、安装时间，以及最近一次更新时间。只要有这份元数据，`opencli plugin list` 就会显示对应的短 commit hash。
+
 ## YAML plugin 示例
 
 ```text

src/cli.ts

@@ -368,9 +368,10 @@ export function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void {
       console.log(chalk.bold('  Installed plugins'));
       console.log();
       for (const p of plugins) {
+        const version = p.version ? chalk.green(` @${p.version}`) : '';
         const cmds = p.commands.length > 0 ? chalk.dim(` (${p.commands.join(', ')})`) : '';
         const src = p.source ? chalk.dim(` ← ${p.source}`) : '';
-        console.log(`  ${chalk.cyan(p.name)}${cmds}${src}`);
+        console.log(`  ${chalk.cyan(p.name)}${version}${cmds}${src}`);
       }
       console.log();
       console.log(chalk.dim(`  ${plugins.length} plugin(s) installed`));

src/plugin.test.ts

@@ -1,20 +1,25 @@
 /**
- * Tests for plugin management: install, uninstall, list.
+ * Tests for plugin management: install, uninstall, list, and lock file support.
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { PLUGINS_DIR } from './discovery.js';
+import type { LockEntry } from './plugin.js';
 import * as pluginModule from './plugin.js';
 
 const {
+  LOCK_FILE,
+  _getCommitHash,
   listPlugins,
+  _readLockFile,
   uninstallPlugin,
   updatePlugin,
   _parseSource,
   _updateAllPlugins,
   _validatePluginStructure,
+  _writeLockFile,
 } = pluginModule;
 
 describe('parseSource', () => {
@@ -111,6 +116,70 @@ describe('validatePluginStructure', () => {
   });
 });
 
+describe('lock file', () => {
+  const backupPath = `${LOCK_FILE}.test-backup`;
+  let hadOriginal = false;
+
+  beforeEach(() => {
+    hadOriginal = fs.existsSync(LOCK_FILE);
+    if (hadOriginal) {
+      fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+      fs.copyFileSync(LOCK_FILE, backupPath);
+    }
+  });
+
+  afterEach(() => {
+    if (hadOriginal) {
+      fs.copyFileSync(backupPath, LOCK_FILE);
+      fs.unlinkSync(backupPath);
+      return;
+    }
+    try { fs.unlinkSync(LOCK_FILE); } catch {}
+  });
+
+  it('reads empty lock when file does not exist', () => {
+    try { fs.unlinkSync(LOCK_FILE); } catch {}
+    expect(_readLockFile()).toEqual({});
+  });
+
+  it('round-trips lock entries', () => {
+    const entries: Record<string, LockEntry> = {
+      'test-plugin': {
+        source: 'https://github.com/user/repo.git',
+        commitHash: 'abc1234567890def',
+        installedAt: '2025-01-01T00:00:00.000Z',
+      },
+      'another-plugin': {
+        source: 'https://github.com/user/another.git',
+        commitHash: 'def4567890123abc',
+        installedAt: '2025-02-01T00:00:00.000Z',
+        updatedAt: '2025-03-01T00:00:00.000Z',
+      },
+    };
+
+    _writeLockFile(entries);
+    expect(_readLockFile()).toEqual(entries);
+  });
+
+  it('handles malformed lock file gracefully', () => {
+    fs.mkdirSync(path.dirname(LOCK_FILE), { recursive: true });
+    fs.writeFileSync(LOCK_FILE, 'not valid json');
+    expect(_readLockFile()).toEqual({});
+  });
+});
+
+describe('getCommitHash', () => {
+  it('returns a hash for a git repo', () => {
+    const hash = _getCommitHash(process.cwd());
+    expect(hash).toBeDefined();
+    expect(hash).toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it('returns undefined for non-git directory', () => {
+    expect(_getCommitHash('/tmp')).toBeUndefined();
+  });
+});
+
 describe('listPlugins', () => {
   const testDir = path.join(PLUGINS_DIR, '__test-list-plugin__');
 
@@ -128,6 +197,28 @@ describe('listPlugins', () => {
     expect(found!.commands).toContain('hello');
   });
 
+  it('includes version metadata from the lock file', () => {
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(path.join(testDir, 'hello.yaml'), 'site: test\nname: hello\n');
+
+    const lock = _readLockFile();
+    lock['__test-list-plugin__'] = {
+      source: 'https://github.com/user/repo.git',
+      commitHash: 'abcdef1234567890abcdef1234567890abcdef12',
+      installedAt: '2025-01-01T00:00:00.000Z',
+    };
+    _writeLockFile(lock);
+
+    const plugins = listPlugins();
+    const found = plugins.find(p => p.name === '__test-list-plugin__');
+    expect(found).toBeDefined();
+    expect(found!.version).toBe('abcdef1');
+    expect(found!.installedAt).toBe('2025-01-01T00:00:00.000Z');
+
+    delete lock['__test-list-plugin__'];
+    _writeLockFile(lock);
+  });
+
   it('returns empty array when no plugins dir', () => {
     // listPlugins should handle missing dir gracefully
     const plugins = listPlugins();
@@ -150,6 +241,22 @@ describe('uninstallPlugin', () => {
     expect(fs.existsSync(testDir)).toBe(false);
   });
 
+  it('removes lock entry on uninstall', () => {
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(path.join(testDir, 'test.yaml'), 'site: test');
+
+    const lock = _readLockFile();
+    lock['__test-uninstall__'] = {
+      source: 'https://github.com/user/repo.git',
+      commitHash: 'abc123',
+      installedAt: '2025-01-01T00:00:00.000Z',
+    };
+    _writeLockFile(lock);
+
+    uninstallPlugin('__test-uninstall__');
+    expect(_readLockFile()['__test-uninstall__']).toBeUndefined();
+  });
+
   it('throws for non-existent plugin', () => {
     expect(() => uninstallPlugin('__nonexistent__')).toThrow('not installed');
   });
@@ -163,7 +270,13 @@ describe('updatePlugin', () => {
 
 vi.mock('node:child_process', () => {
   return {
-    execFileSync: vi.fn((_cmd, _args, opts) => {
+    execFileSync: vi.fn((_cmd, args, opts) => {
+      if (Array.isArray(args) && args[0] === 'rev-parse' && args[1] === 'HEAD') {
+        if (opts?.cwd === '/tmp') {
+          throw new Error('not a git repository');
+        }
+        return '1234567890abcdef1234567890abcdef12345678\n';
+      }
       if (opts && opts.cwd && String(opts.cwd).endsWith('plugin-b')) {
         throw new Error('Network error');
       }

src/plugin.ts

@@ -6,17 +6,30 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
-import { execSync, execFileSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { PLUGINS_DIR } from './discovery.js';
 import { getErrorMessage } from './errors.js';
 import { log } from './logger.js';
 
+/** Path to the lock file that tracks installed plugin versions. */
+export const LOCK_FILE = path.join(os.homedir(), '.opencli', 'plugins.lock.json');
+
+export interface LockEntry {
+  source: string;
+  commitHash: string;
+  installedAt: string;
+  updatedAt?: string;
+}
+
 export interface PluginInfo {
   name: string;
   path: string;
   commands: string[];
   source?: string;
+  version?: string;
+  installedAt?: string;
 }
 
 // ── Validation helpers ──────────────────────────────────────────────────────
@@ -26,6 +39,35 @@ export interface ValidationResult {
   errors: string[];
 }
 
+// ── Lock file helpers ───────────────────────────────────────────────────────
+
+export function readLockFile(): Record<string, LockEntry> {
+  try {
+    const raw = fs.readFileSync(LOCK_FILE, 'utf-8');
+    return JSON.parse(raw) as Record<string, LockEntry>;
+  } catch {
+    return {};
+  }
+}
+
+export function writeLockFile(lock: Record<string, LockEntry>): void {
+  fs.mkdirSync(path.dirname(LOCK_FILE), { recursive: true });
+  fs.writeFileSync(LOCK_FILE, JSON.stringify(lock, null, 2) + '\n');
+}
+
+/** Get the HEAD commit hash of a git repo directory. */
+export function getCommitHash(dir: string): string | undefined {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: dir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Validate that a downloaded plugin directory is a structurally valid plugin.
  * Checks for at least one command file (.yaml, .yml, .ts, .js) and a valid
@@ -134,6 +176,18 @@ export function installPlugin(source: string): string {
   }
 
   postInstallLifecycle(targetDir);
+
+  const commitHash = getCommitHash(targetDir);
+  if (commitHash) {
+    const lock = readLockFile();
+    lock[name] = {
+      source: cloneUrl,
+      commitHash,
+      installedAt: new Date().toISOString(),
+    };
+    writeLockFile(lock);
+  }
+
   return name;
 }
 
@@ -146,6 +200,12 @@ export function uninstallPlugin(name: string): void {
     throw new Error(`Plugin "${name}" is not installed.`);
   }
   fs.rmSync(targetDir, { recursive: true, force: true });
+
+  const lock = readLockFile();
+  if (lock[name]) {
+    delete lock[name];
+    writeLockFile(lock);
+  }
 }
 
 /**
@@ -173,6 +233,19 @@ export function updatePlugin(name: string): void {
   }
 
   postInstallLifecycle(targetDir);
+
+  const commitHash = getCommitHash(targetDir);
+  if (commitHash) {
+    const lock = readLockFile();
+    const existing = lock[name];
+    lock[name] = {
+      source: existing?.source ?? getPluginSource(targetDir) ?? '',
+      commitHash,
+      installedAt: existing?.installedAt ?? new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    writeLockFile(lock);
+  }
 }
 
 export interface UpdateResult {
@@ -207,19 +280,23 @@ export function listPlugins(): PluginInfo[] {
   if (!fs.existsSync(PLUGINS_DIR)) return [];
 
   const entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+  const lock = readLockFile();
   const plugins: PluginInfo[] = [];
 
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const pluginDir = path.join(PLUGINS_DIR, entry.name);
     const commands = scanPluginCommands(pluginDir);
     const source = getPluginSource(pluginDir);
+    const lockEntry = lock[entry.name];
 
     plugins.push({
       name: entry.name,
       path: pluginDir,
       commands,
       source,
+      version: lockEntry?.commitHash?.slice(0, 7),
+      installedAt: lockEntry?.installedAt,
     });
   }
 
@@ -361,7 +438,10 @@ function transpilePluginTs(pluginDir: string): void {
 }
 
 export {
+  getCommitHash as _getCommitHash,
   parseSource as _parseSource,
+  readLockFile as _readLockFile,
   updateAllPlugins as _updateAllPlugins,
   validatePluginStructure as _validatePluginStructure,
+  writeLockFile as _writeLockFile,
 };