@jackwener/opencli 1.4.0 → 1.5.0

package/src/plugin-manifest.ts

@@ -0,0 +1,206 @@
+/**
+ * Plugin manifest: reads and validates opencli-plugin.json files.
+ *
+ * Supports two modes:
+ * 1. Single plugin: repo root IS the plugin directory.
+ * 2. Monorepo: repo contains multiple plugins declared in `plugins` field.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PKG_VERSION } from './version.js';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface SubPluginEntry {
+  /** Relative path from repo root to the sub-plugin directory. */
+  path: string;
+  version?: string;
+  description?: string;
+  /** Semver range for opencli compatibility (overrides top-level). */
+  opencli?: string;
+  /** When true, this sub-plugin is skipped during install. */
+  disabled?: boolean;
+}
+
+export interface PluginManifest {
+  /** Plugin name (single-plugin mode). */
+  name?: string;
+  /** Semantic version of the plugin (single-plugin mode). */
+  version?: string;
+  /** Semver range for opencli compatibility, e.g. ">=1.0.0". */
+  opencli?: string;
+  /** Human-readable description. */
+  description?: string;
+  /** Monorepo sub-plugins. Key = logical plugin name. */
+  plugins?: Record<string, SubPluginEntry>;
+}
+
+export const MANIFEST_FILENAME = 'opencli-plugin.json';
+
+// ── Read / Validate ─────────────────────────────────────────────────────────
+
+/**
+ * Read and parse opencli-plugin.json from a directory.
+ * Returns null if the file does not exist or is unparseable.
+ */
+export function readPluginManifest(dir: string): PluginManifest | null {
+  const manifestPath = path.join(dir, MANIFEST_FILENAME);
+  try {
+    const raw = fs.readFileSync(manifestPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as PluginManifest;
+  } catch {
+    return null;
+  }
+}
+
+/** Returns true when the manifest declares a monorepo (has `plugins` field). */
+export function isMonorepo(manifest: PluginManifest): boolean {
+  return (
+    manifest.plugins !== undefined &&
+    manifest.plugins !== null &&
+    typeof manifest.plugins === 'object' &&
+    Object.keys(manifest.plugins).length > 0
+  );
+}
+
+/**
+ * Get the list of enabled sub-plugins from a monorepo manifest.
+ * Returns entries sorted by key name.
+ */
+export function getEnabledPlugins(
+  manifest: PluginManifest,
+): Array<{ name: string; entry: SubPluginEntry }> {
+  if (!manifest.plugins) return [];
+  return Object.entries(manifest.plugins)
+    .filter(([, entry]) => !entry.disabled)
+    .map(([name, entry]) => ({ name, entry }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// ── Version compatibility ───────────────────────────────────────────────────
+
+/**
+ * Check if the current opencli version satisfies a semver range string.
+ *
+ * Supports a simplified subset of semver ranges:
+ *   ">=1.0.0"   – greater than or equal
+ *   "<=1.5.0"   – less than or equal
+ *   ">1.0.0"    – strictly greater
+ *   "<2.0.0"    – strictly less
+ *   "^1.2.0"    – compatible (>=1.2.0 and <2.0.0)
+ *   "~1.2.0"    – patch-level (>=1.2.0 and <1.3.0)
+ *   "1.2.0"     – exact match
+ *   ">=1.0.0 <2.0.0" – multiple constraints (space-separated, all must match)
+ *
+ * Returns true if compatible, false if not, and true for empty/undefined
+ * ranges (no constraint = always compatible).
+ */
+export function checkCompatibility(range: string | undefined): boolean {
+  if (!range || range.trim() === '') return true;
+  return satisfiesRange(PKG_VERSION, range);
+}
+
+/** Parse a version string ("1.2.3") into [major, minor, patch]. */
+export function parseVersion(version: string): [number, number, number] | null {
+  const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+}
+
+/** Compare two version tuples: -1 if a<b, 0 if equal, 1 if a>b. */
+function compareVersions(
+  a: [number, number, number],
+  b: [number, number, number],
+): -1 | 0 | 1 {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] < b[i]) return -1;
+    if (a[i] > b[i]) return 1;
+  }
+  return 0;
+}
+
+/** Check if a version satisfies a single constraint like ">=1.2.0". */
+function satisfiesSingleConstraint(
+  version: [number, number, number],
+  constraint: string,
+): boolean {
+  const trimmed = constraint.trim();
+  if (!trimmed) return true;
+
+  // ^1.2.0 → >=1.2.0 <2.0.0
+  if (trimmed.startsWith('^')) {
+    const target = parseVersion(trimmed.slice(1));
+    if (!target) return true;
+    const upper: [number, number, number] = [target[0] + 1, 0, 0];
+    return compareVersions(version, target) >= 0 && compareVersions(version, upper) < 0;
+  }
+
+  // ~1.2.0 → >=1.2.0 <1.3.0
+  if (trimmed.startsWith('~')) {
+    const target = parseVersion(trimmed.slice(1));
+    if (!target) return true;
+    const upper: [number, number, number] = [target[0], target[1] + 1, 0];
+    return compareVersions(version, target) >= 0 && compareVersions(version, upper) < 0;
+  }
+
+  // >=, <=, >, <, =
+  if (trimmed.startsWith('>=')) {
+    const target = parseVersion(trimmed.slice(2));
+    if (!target) return true;
+    return compareVersions(version, target) >= 0;
+  }
+  if (trimmed.startsWith('<=')) {
+    const target = parseVersion(trimmed.slice(2));
+    if (!target) return true;
+    return compareVersions(version, target) <= 0;
+  }
+  if (trimmed.startsWith('>')) {
+    const target = parseVersion(trimmed.slice(1));
+    if (!target) return true;
+    return compareVersions(version, target) > 0;
+  }
+  if (trimmed.startsWith('<')) {
+    const target = parseVersion(trimmed.slice(1));
+    if (!target) return true;
+    return compareVersions(version, target) < 0;
+  }
+  if (trimmed.startsWith('=')) {
+    const target = parseVersion(trimmed.slice(1));
+    if (!target) return true;
+    return compareVersions(version, target) === 0;
+  }
+
+  // Exact match
+  const target = parseVersion(trimmed);
+  if (!target) return true;
+  return compareVersions(version, target) === 0;
+}
+
+/**
+ * Check if a version string satisfies a range expression.
+ * Space-separated constraints are ANDed together.
+ */
+export function satisfiesRange(versionStr: string, range: string): boolean {
+  const version = parseVersion(versionStr);
+  if (!version) return true; // Can't parse our own version → assume ok
+
+  // Split on whitespace for multi-constraint ranges (e.g. ">=1.0.0 <2.0.0")
+  const constraints = range.trim().split(/\s+/);
+  return constraints.every((c) => satisfiesSingleConstraint(version, c));
+}
+
+// ── Exports for testing ─────────────────────────────────────────────────────
+
+export {
+  readPluginManifest as _readPluginManifest,
+  isMonorepo as _isMonorepo,
+  getEnabledPlugins as _getEnabledPlugins,
+  checkCompatibility as _checkCompatibility,
+  parseVersion as _parseVersion,
+  satisfiesRange as _satisfiesRange,
+};

package/src/plugin.test.ts

@@ -10,9 +10,16 @@ import { PLUGINS_DIR } from './discovery.js';
 import type { LockEntry } from './plugin.js';
 import * as pluginModule from './plugin.js';
 
+const { mockExecFileSync, mockExecSync } = vi.hoisted(() => ({
+  mockExecFileSync: vi.fn(),
+  mockExecSync: vi.fn(),
+}));
+
 const {
   LOCK_FILE,
   _getCommitHash,
+  _installDependencies,
+  _postInstallMonorepoLifecycle,
   listPlugins,
   _readLockFile,
   _resolveEsbuildBin,
@@ -22,6 +29,8 @@ const {
   _updateAllPlugins,
   _validatePluginStructure,
   _writeLockFile,
+  _isSymlinkSync,
+  _getMonoreposDir,
 } = pluginModule;
 
 describe('parseSource', () => {
@@ -283,7 +292,7 @@ describe('updatePlugin', () => {
 
 vi.mock('node:child_process', () => {
   return {
-    execFileSync: vi.fn((_cmd, args, opts) => {
+    execFileSync: mockExecFileSync.mockImplementation((_cmd, args, opts) => {
       if (Array.isArray(args) && args[0] === 'rev-parse' && args[1] === 'HEAD') {
         if (opts?.cwd === os.tmpdir()) {
           throw new Error('not a git repository');
@@ -295,10 +304,63 @@ vi.mock('node:child_process', () => {
       }
       return '';
     }),
-    execSync: vi.fn(() => ''),
+    execSync: mockExecSync.mockImplementation(() => ''),
   };
 });
 
+describe('installDependencies', () => {
+  beforeEach(() => {
+    mockExecFileSync.mockClear();
+    mockExecSync.mockClear();
+  });
+
+  it('throws when npm install fails', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-plugin-b-'));
+    const failingDir = path.join(tmpDir, 'plugin-b');
+    fs.mkdirSync(failingDir, { recursive: true });
+    fs.writeFileSync(path.join(failingDir, 'package.json'), JSON.stringify({ name: 'plugin-b' }));
+
+    expect(() => _installDependencies(failingDir)).toThrow('npm install failed');
+
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+});
+
+describe('postInstallMonorepoLifecycle', () => {
+  let repoDir: string;
+  let subDir: string;
+
+  beforeEach(() => {
+    mockExecFileSync.mockClear();
+    mockExecSync.mockClear();
+    repoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-monorepo-'));
+    subDir = path.join(repoDir, 'packages', 'alpha');
+    fs.mkdirSync(subDir, { recursive: true });
+    fs.writeFileSync(path.join(repoDir, 'package.json'), JSON.stringify({
+      name: 'opencli-plugins',
+      private: true,
+      workspaces: ['packages/*'],
+    }));
+    fs.writeFileSync(path.join(subDir, 'hello.yaml'), 'site: test\nname: hello\n');
+  });
+
+  afterEach(() => {
+    fs.rmSync(repoDir, { recursive: true, force: true });
+  });
+
+  it('installs dependencies once at the monorepo root, not in each sub-plugin', () => {
+    _postInstallMonorepoLifecycle(repoDir, [subDir]);
+
+    const npmCalls = mockExecFileSync.mock.calls.filter(
+      ([cmd, args]) => cmd === 'npm' && Array.isArray(args) && args[0] === 'install',
+    );
+
+    expect(npmCalls).toHaveLength(1);
+    expect(npmCalls[0][2]).toMatchObject({ cwd: repoDir });
+    expect(npmCalls.some(([, , opts]) => opts?.cwd === subDir)).toBe(false);
+  });
+});
+
 describe('updateAllPlugins', () => {
   const testDirA = path.join(PLUGINS_DIR, 'plugin-a');
   const testDirB = path.join(PLUGINS_DIR, 'plugin-b');
@@ -338,3 +400,185 @@ describe('updateAllPlugins', () => {
     expect(resC!.success).toBe(true);
   });
 });
+
+// ── Monorepo-specific tests ─────────────────────────────────────────────────
+
+describe('parseSource with monorepo subplugin', () => {
+  it('parses github:user/repo/subplugin format', () => {
+    const result = _parseSource('github:ByteYue/opencli-plugins/polymarket');
+    expect(result).toEqual({
+      cloneUrl: 'https://github.com/ByteYue/opencli-plugins.git',
+      name: 'opencli-plugins',
+      subPlugin: 'polymarket',
+    });
+  });
+
+  it('strips opencli-plugin- prefix from repo name in subplugin format', () => {
+    const result = _parseSource('github:user/opencli-plugin-collection/defi');
+    expect(result!.name).toBe('collection');
+    expect(result!.subPlugin).toBe('defi');
+  });
+
+  it('still parses github:user/repo without subplugin', () => {
+    const result = _parseSource('github:user/my-repo');
+    expect(result).toEqual({
+      cloneUrl: 'https://github.com/user/my-repo.git',
+      name: 'my-repo',
+    });
+    expect(result!.subPlugin).toBeUndefined();
+  });
+});
+
+describe('isSymlinkSync', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-symlink-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns false for a regular directory', () => {
+    const dir = path.join(tmpDir, 'regular');
+    fs.mkdirSync(dir);
+    expect(_isSymlinkSync(dir)).toBe(false);
+  });
+
+  it('returns true for a symlink', () => {
+    const target = path.join(tmpDir, 'target');
+    const link = path.join(tmpDir, 'link');
+    fs.mkdirSync(target);
+    fs.symlinkSync(target, link, 'dir');
+    expect(_isSymlinkSync(link)).toBe(true);
+  });
+
+  it('returns false for non-existent path', () => {
+    expect(_isSymlinkSync(path.join(tmpDir, 'nope'))).toBe(false);
+  });
+});
+
+describe('monorepo uninstall with symlink', () => {
+  let tmpDir: string;
+  let pluginDir: string;
+  let monoDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-mono-uninstall-'));
+    // We need to use the real PLUGINS_DIR for uninstallPlugin() to work
+    pluginDir = path.join(PLUGINS_DIR, '__test-mono-sub__');
+    monoDir = path.join(_getMonoreposDir(), '__test-mono__');
+
+    // Set up monorepo structure
+    const subDir = path.join(monoDir, 'packages', 'sub');
+    fs.mkdirSync(subDir, { recursive: true });
+    fs.writeFileSync(path.join(subDir, 'cmd.yaml'), 'site: test');
+
+    // Create symlink in plugins dir
+    fs.mkdirSync(PLUGINS_DIR, { recursive: true });
+    fs.symlinkSync(subDir, pluginDir, 'dir');
+
+    // Set up lock file with monorepo entry
+    const lock = _readLockFile();
+    lock['__test-mono-sub__'] = {
+      source: 'https://github.com/user/test.git',
+      commitHash: 'abc123',
+      installedAt: '2025-01-01T00:00:00.000Z',
+      monorepo: { name: '__test-mono__', subPath: 'packages/sub' },
+    };
+    _writeLockFile(lock);
+  });
+
+  afterEach(() => {
+    try { fs.unlinkSync(pluginDir); } catch {}
+    try { fs.rmSync(pluginDir, { recursive: true, force: true }); } catch {}
+    try { fs.rmSync(monoDir, { recursive: true, force: true }); } catch {}
+    // Clean up lock entry
+    const lock = _readLockFile();
+    delete lock['__test-mono-sub__'];
+    _writeLockFile(lock);
+  });
+
+  it('removes symlink but keeps monorepo if other sub-plugins reference it', () => {
+    // Add another sub-plugin referencing the same monorepo
+    const lock = _readLockFile();
+    lock['__test-mono-other__'] = {
+      source: 'https://github.com/user/test.git',
+      commitHash: 'abc123',
+      installedAt: '2025-01-01T00:00:00.000Z',
+      monorepo: { name: '__test-mono__', subPath: 'packages/other' },
+    };
+    _writeLockFile(lock);
+
+    uninstallPlugin('__test-mono-sub__');
+
+    // Symlink removed
+    expect(fs.existsSync(pluginDir)).toBe(false);
+    // Monorepo dir still exists (other sub-plugin references it)
+    expect(fs.existsSync(monoDir)).toBe(true);
+    // Lock entry removed
+    expect(_readLockFile()['__test-mono-sub__']).toBeUndefined();
+    // Other lock entry still present
+    expect(_readLockFile()['__test-mono-other__']).toBeDefined();
+
+    // Clean up the other entry
+    const finalLock = _readLockFile();
+    delete finalLock['__test-mono-other__'];
+    _writeLockFile(finalLock);
+  });
+
+  it('removes symlink AND monorepo dir when last sub-plugin is uninstalled', () => {
+    uninstallPlugin('__test-mono-sub__');
+
+    // Symlink removed
+    expect(fs.existsSync(pluginDir)).toBe(false);
+    // Monorepo dir also removed (no more references)
+    expect(fs.existsSync(monoDir)).toBe(false);
+    // Lock entry removed
+    expect(_readLockFile()['__test-mono-sub__']).toBeUndefined();
+  });
+});
+
+describe('listPlugins with monorepo metadata', () => {
+  const testSymlinkTarget = path.join(os.tmpdir(), 'opencli-list-mono-target');
+  const testLink = path.join(PLUGINS_DIR, '__test-mono-list__');
+
+  beforeEach(() => {
+    // Create a target dir with a command file
+    fs.mkdirSync(testSymlinkTarget, { recursive: true });
+    fs.writeFileSync(path.join(testSymlinkTarget, 'hello.yaml'), 'site: test\nname: hello\n');
+
+    // Create symlink
+    fs.mkdirSync(PLUGINS_DIR, { recursive: true });
+    try { fs.unlinkSync(testLink); } catch {}
+    fs.symlinkSync(testSymlinkTarget, testLink, 'dir');
+
+    // Set up lock file with monorepo entry
+    const lock = _readLockFile();
+    lock['__test-mono-list__'] = {
+      source: 'https://github.com/user/test-mono.git',
+      commitHash: 'def456def456def456def456def456def456def4',
+      installedAt: '2025-01-01T00:00:00.000Z',
+      monorepo: { name: 'test-mono', subPath: 'packages/list' },
+    };
+    _writeLockFile(lock);
+  });
+
+  afterEach(() => {
+    try { fs.unlinkSync(testLink); } catch {}
+    try { fs.rmSync(testSymlinkTarget, { recursive: true, force: true }); } catch {}
+    const lock = _readLockFile();
+    delete lock['__test-mono-list__'];
+    _writeLockFile(lock);
+  });
+
+  it('lists symlinked plugins with monorepoName', () => {
+    const plugins = listPlugins();
+    const found = plugins.find(p => p.name === '__test-mono-list__');
+    expect(found).toBeDefined();
+    expect(found!.monorepoName).toBe('test-mono');
+    expect(found!.commands).toContain('hello');
+    expect(found!.source).toBe('https://github.com/user/test-mono.git');
+  });
+});