@jackwener/opencli 1.4.1 → 1.5.0

package/dist/plugin-manifest.js

@@ -0,0 +1,160 @@
+/**
+ * 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';
+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) {
+    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;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns true when the manifest declares a monorepo (has `plugins` field). */
+export function isMonorepo(manifest) {
+    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) {
+    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) {
+    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) {
+    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, b) {
+    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, constraint) {
+    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 = [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 = [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, range) {
+    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/dist/plugin-manifest.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for plugin manifest: reading, validating, and compatibility checks.
+ */
+export {};

package/dist/plugin-manifest.test.js

@@ -0,0 +1,179 @@
+/**
+ * Tests for plugin manifest: reading, validating, and compatibility checks.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { _readPluginManifest as readPluginManifest, _isMonorepo as isMonorepo, _getEnabledPlugins as getEnabledPlugins, _parseVersion as parseVersion, _satisfiesRange as satisfiesRange, MANIFEST_FILENAME, } from './plugin-manifest.js';
+// ── readPluginManifest ──────────────────────────────────────────────────────
+describe('readPluginManifest', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-test-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('returns null when no manifest file exists', () => {
+        expect(readPluginManifest(tmpDir)).toBeNull();
+    });
+    it('returns null for malformed JSON', () => {
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), 'not json {{{');
+        expect(readPluginManifest(tmpDir)).toBeNull();
+    });
+    it('returns null for non-object JSON (array)', () => {
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), '["a","b"]');
+        expect(readPluginManifest(tmpDir)).toBeNull();
+    });
+    it('returns null for non-object JSON (string)', () => {
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), '"hello"');
+        expect(readPluginManifest(tmpDir)).toBeNull();
+    });
+    it('reads a single-plugin manifest', () => {
+        const manifest = {
+            name: 'polymarket',
+            version: '1.2.0',
+            opencli: '>=1.0.0',
+            description: 'Prediction market analysis',
+        };
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), JSON.stringify(manifest));
+        const result = readPluginManifest(tmpDir);
+        expect(result).toEqual(manifest);
+    });
+    it('reads a monorepo manifest', () => {
+        const manifest = {
+            version: '1.0.0',
+            opencli: '>=0.9.0',
+            description: 'My plugin collection',
+            plugins: {
+                polymarket: {
+                    path: 'packages/polymarket',
+                    description: 'Prediction market',
+                    version: '1.2.0',
+                },
+                defi: {
+                    path: 'packages/defi',
+                    description: 'DeFi data',
+                    version: '0.8.0',
+                    disabled: true,
+                },
+            },
+        };
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), JSON.stringify(manifest));
+        const result = readPluginManifest(tmpDir);
+        expect(result).toEqual(manifest);
+        expect(result.plugins.polymarket.path).toBe('packages/polymarket');
+        expect(result.plugins.defi.disabled).toBe(true);
+    });
+});
+// ── isMonorepo ──────────────────────────────────────────────────────────────
+describe('isMonorepo', () => {
+    it('returns false for single-plugin manifest', () => {
+        expect(isMonorepo({ name: 'test', version: '1.0.0' })).toBe(false);
+    });
+    it('returns false for empty plugins object', () => {
+        expect(isMonorepo({ plugins: {} })).toBe(false);
+    });
+    it('returns true for manifest with plugins', () => {
+        expect(isMonorepo({
+            plugins: {
+                foo: { path: 'packages/foo' },
+            },
+        })).toBe(true);
+    });
+});
+// ── getEnabledPlugins ───────────────────────────────────────────────────────
+describe('getEnabledPlugins', () => {
+    it('returns empty array for no plugins', () => {
+        expect(getEnabledPlugins({ name: 'test' })).toEqual([]);
+    });
+    it('filters out disabled plugins', () => {
+        const manifest = {
+            plugins: {
+                foo: { path: 'packages/foo' },
+                bar: { path: 'packages/bar', disabled: true },
+                baz: { path: 'packages/baz' },
+            },
+        };
+        const result = getEnabledPlugins(manifest);
+        expect(result).toHaveLength(2);
+        expect(result.map((r) => r.name)).toEqual(['baz', 'foo']); // sorted
+    });
+    it('returns all when none disabled', () => {
+        const manifest = {
+            plugins: {
+                charlie: { path: 'packages/charlie' },
+                alpha: { path: 'packages/alpha' },
+            },
+        };
+        const result = getEnabledPlugins(manifest);
+        expect(result).toHaveLength(2);
+        expect(result[0].name).toBe('alpha');
+        expect(result[1].name).toBe('charlie');
+    });
+});
+// ── parseVersion ────────────────────────────────────────────────────────────
+describe('parseVersion', () => {
+    it('parses standard versions', () => {
+        expect(parseVersion('1.2.3')).toEqual([1, 2, 3]);
+        expect(parseVersion('0.0.0')).toEqual([0, 0, 0]);
+        expect(parseVersion('10.20.30')).toEqual([10, 20, 30]);
+    });
+    it('parses versions with prerelease suffix', () => {
+        expect(parseVersion('1.2.3-beta.1')).toEqual([1, 2, 3]);
+    });
+    it('returns null for invalid versions', () => {
+        expect(parseVersion('abc')).toBeNull();
+        expect(parseVersion('')).toBeNull();
+        expect(parseVersion('1.2')).toBeNull();
+    });
+});
+// ── satisfiesRange ──────────────────────────────────────────────────────────
+describe('satisfiesRange', () => {
+    it('handles >= constraint', () => {
+        expect(satisfiesRange('1.4.1', '>=1.0.0')).toBe(true);
+        expect(satisfiesRange('1.0.0', '>=1.0.0')).toBe(true);
+        expect(satisfiesRange('0.9.9', '>=1.0.0')).toBe(false);
+    });
+    it('handles <= constraint', () => {
+        expect(satisfiesRange('1.0.0', '<=1.0.0')).toBe(true);
+        expect(satisfiesRange('0.9.0', '<=1.0.0')).toBe(true);
+        expect(satisfiesRange('1.0.1', '<=1.0.0')).toBe(false);
+    });
+    it('handles > constraint', () => {
+        expect(satisfiesRange('1.0.1', '>1.0.0')).toBe(true);
+        expect(satisfiesRange('1.0.0', '>1.0.0')).toBe(false);
+    });
+    it('handles < constraint', () => {
+        expect(satisfiesRange('0.9.9', '<1.0.0')).toBe(true);
+        expect(satisfiesRange('1.0.0', '<1.0.0')).toBe(false);
+    });
+    it('handles ^ (caret) constraint', () => {
+        expect(satisfiesRange('1.2.0', '^1.2.0')).toBe(true);
+        expect(satisfiesRange('1.9.9', '^1.2.0')).toBe(true);
+        expect(satisfiesRange('2.0.0', '^1.2.0')).toBe(false);
+        expect(satisfiesRange('1.1.0', '^1.2.0')).toBe(false);
+    });
+    it('handles ~ (tilde) constraint', () => {
+        expect(satisfiesRange('1.2.0', '~1.2.0')).toBe(true);
+        expect(satisfiesRange('1.2.9', '~1.2.0')).toBe(true);
+        expect(satisfiesRange('1.3.0', '~1.2.0')).toBe(false);
+    });
+    it('handles exact match', () => {
+        expect(satisfiesRange('1.2.3', '1.2.3')).toBe(true);
+        expect(satisfiesRange('1.2.4', '1.2.3')).toBe(false);
+    });
+    it('handles compound range (AND)', () => {
+        expect(satisfiesRange('1.5.0', '>=1.0.0 <2.0.0')).toBe(true);
+        expect(satisfiesRange('2.0.0', '>=1.0.0 <2.0.0')).toBe(false);
+        expect(satisfiesRange('0.9.0', '>=1.0.0 <2.0.0')).toBe(false);
+    });
+    it('returns true for empty range', () => {
+        expect(satisfiesRange('1.0.0', '')).toBe(true);
+        expect(satisfiesRange('1.0.0', '  ')).toBe(true);
+    });
+    it('returns true for unparseable version', () => {
+        expect(satisfiesRange('dev', '>=1.0.0')).toBe(true);
+    });
+});

package/dist/plugin.d.ts

@@ -2,16 +2,27 @@
  * Plugin management: install, uninstall, and list plugins.
  *
  * Plugins live in ~/.opencli/plugins/<name>/.
- * Install source format: "github:user/repo"
+ * Monorepo clones live in ~/.opencli/monorepos/<repo-name>/.
+ * Install source format: "github:user/repo" or "github:user/repo/subplugin"
  */
 /** Path to the lock file that tracks installed plugin versions. */
 export declare function getLockFilePath(): string;
+/** Monorepo clones directory: ~/.opencli/monorepos/ */
+export declare function getMonoreposDir(): string;
 export declare const LOCK_FILE: string;
+export declare const MONOREPOS_DIR: string;
 export interface LockEntry {
     source: string;
     commitHash: string;
     installedAt: string;
     updatedAt?: string;
+    /** Present when this plugin comes from a monorepo. */
+    monorepo?: {
+        /** Monorepo directory name under ~/.opencli/monorepos/ */
+        name: string;
+        /** Relative path of this sub-plugin within the monorepo. */
+        subPath: string;
+    };
 }
 export interface PluginInfo {
     name: string;
@@ -20,6 +31,10 @@ export interface PluginInfo {
     source?: string;
     version?: string;
     installedAt?: string;
+    /** If from a monorepo, the monorepo name. */
+    monorepoName?: string;
+    /** Description from opencli-plugin.json. */
+    description?: string;
 }
 export interface ValidationResult {
     valid: boolean;
@@ -35,17 +50,33 @@ export declare function getCommitHash(dir: string): string | undefined;
  * package.json if it contains .ts files.
  */
 export declare function validatePluginStructure(pluginDir: string): ValidationResult;
+declare function installDependencies(dir: string): void;
+/**
+ * Monorepo lifecycle: install shared deps once at repo root, then finalize each sub-plugin.
+ */
+declare function postInstallMonorepoLifecycle(repoDir: string, pluginDirs: string[]): void;
 /**
  * Install a plugin from a source.
- * Currently supports "github:user/repo" format (git clone wrapper).
+ * Supports:
+ *   "github:user/repo"            — single plugin or full monorepo
+ *   "github:user/repo/subplugin"  — specific sub-plugin from a monorepo
+ *   "https://github.com/user/repo"
+ *
+ * Returns the installed plugin name(s).
  */
-export declare function installPlugin(source: string): string;
+export declare function installPlugin(source: string): string | string[];
 /**
  * Uninstall a plugin by name.
+ * For monorepo sub-plugins: removes symlink and cleans up the monorepo
+ * directory when no more sub-plugins reference it.
  */
 export declare function uninstallPlugin(name: string): void;
+/** Synchronous check if a path is a symlink. */
+declare function isSymlinkSync(p: string): boolean;
 /**
  * Update a plugin by name (git pull + re-install lifecycle).
+ * For monorepo sub-plugins: pulls the monorepo root and re-runs lifecycle
+ * for all sub-plugins from the same monorepo.
  */
 export declare function updatePlugin(name: string): void;
 export interface UpdateResult {
@@ -60,15 +91,17 @@ export interface UpdateResult {
 export declare function updateAllPlugins(): UpdateResult[];
 /**
  * List all installed plugins.
+ * Reads opencli-plugin.json for description/version when available.
  */
 export declare function listPlugins(): PluginInfo[];
-/** Parse a plugin source string into clone URL and name */
+/** Parse a plugin source string into clone URL, repo name, and optional sub-plugin. */
 declare function parseSource(source: string): {
     cloneUrl: string;
     name: string;
+    subPlugin?: string;
 } | null;
 /**
  * Resolve the path to the esbuild CLI executable with fallback strategies.
  */
 export declare function resolveEsbuildBin(): string | null;
-export { resolveEsbuildBin as _resolveEsbuildBin, getCommitHash as _getCommitHash, parseSource as _parseSource, readLockFile as _readLockFile, updateAllPlugins as _updateAllPlugins, validatePluginStructure as _validatePluginStructure, writeLockFile as _writeLockFile, };
+export { resolveEsbuildBin as _resolveEsbuildBin, getCommitHash as _getCommitHash, installDependencies as _installDependencies, parseSource as _parseSource, postInstallMonorepoLifecycle as _postInstallMonorepoLifecycle, readLockFile as _readLockFile, updateAllPlugins as _updateAllPlugins, validatePluginStructure as _validatePluginStructure, writeLockFile as _writeLockFile, isSymlinkSync as _isSymlinkSync, getMonoreposDir as _getMonoreposDir, };