@jackwener/opencli 1.3.2 → 1.4.0

package/dist/pipeline/template.test.js

@@ -51,6 +51,31 @@ describe('evalExpr', () => {
     it('evaluates || with truthy left', () => {
         expect(evalExpr("item.name || 'N/A'", { item: { name: 'Alice' } })).toBe('Alice');
     });
+    it('evaluates chained || fallback (issue #303)', () => {
+        // When first two are falsy, should evaluate through to the string literal
+        expect(evalExpr("item.a || item.b || 'default'", { item: {} })).toBe('default');
+    });
+    it('evaluates chained || with middle value truthy', () => {
+        expect(evalExpr("item.a || item.b || 'default'", { item: { b: 'middle' } })).toBe('middle');
+    });
+    it('evaluates chained || with first value truthy', () => {
+        expect(evalExpr("item.a || item.b || 'default'", { item: { a: 'first', b: 'middle' } })).toBe('first');
+    });
+    it('evaluates || with 0 as falsy left (JS semantics)', () => {
+        expect(evalExpr("item.count || 'N/A'", { item: { count: 0 } })).toBe('N/A');
+    });
+    it('evaluates || with empty string as falsy left', () => {
+        expect(evalExpr("item.name || 'unknown'", { item: { name: '' } })).toBe('unknown');
+    });
+    it('evaluates || with numeric fallback returning number type', () => {
+        expect(evalExpr('item.a || 42', { item: {} })).toBe(42);
+    });
+    it('evaluates 4-way chained ||', () => {
+        expect(evalExpr("item.a || item.b || item.c || 'last'", { item: { c: 'third' } })).toBe('third');
+    });
+    it('handles || combined with pipe filter', () => {
+        expect(evalExpr("item.a || item.b | upper", { item: { b: 'hello' } })).toBe('HELLO');
+    });
     it('resolves simple path', () => {
         expect(evalExpr('item.title', { item: { title: 'Test' } })).toBe('Test');
     });
@@ -63,6 +88,9 @@ describe('evalExpr', () => {
     it('evaluates method calls on values', () => {
         expect(evalExpr("args.username.startsWith('@') ? args.username : '@' + args.username", { args: { username: 'alice' } })).toBe('@alice');
     });
+    it('rejects constructor-based sandbox escapes', () => {
+        expect(evalExpr("args['cons' + 'tructor']['constructor']('return process')()", { args: {} })).toBeUndefined();
+    });
     it('applies join filter', () => {
         expect(evalExpr('item.tags | join(,)', { item: { tags: ['a', 'b', 'c'] } })).toBe('a,b,c');
     });

package/dist/pipeline/transform.test.js

@@ -85,6 +85,24 @@ describe('stepSort', () => {
         await stepSort(null, 'score', SAMPLE_DATA, {});
         expect(SAMPLE_DATA).toEqual(original);
     });
+    it('sorts string-encoded numbers naturally by default', async () => {
+        const data = [
+            { name: 'A', volume: '99' },
+            { name: 'B', volume: '1000' },
+            { name: 'C', volume: '250' },
+        ];
+        const result = await stepSort(null, { by: 'volume', order: 'desc' }, data, {});
+        expect(result.map((r) => r.name)).toEqual(['B', 'C', 'A']);
+    });
+    it('handles missing fields gracefully', async () => {
+        const data = [
+            { name: 'A', value: '10' },
+            { name: 'B' },
+            { name: 'C', value: '5' },
+        ];
+        const result = await stepSort(null, { by: 'value', order: 'asc' }, data, {});
+        expect(result.map((r) => r.name)).toEqual(['B', 'C', 'A']);
+    });
 });
 describe('stepLimit', () => {
     it('limits array to N items', async () => {

package/dist/plugin.d.ts

@@ -4,12 +4,37 @@
  * Plugins live in ~/.opencli/plugins/<name>/.
  * Install source format: "github:user/repo"
  */
+/** Path to the lock file that tracks installed plugin versions. */
+export declare function getLockFilePath(): string;
+export declare const LOCK_FILE: string;
+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;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
 }
+export declare function readLockFile(): Record<string, LockEntry>;
+export declare function writeLockFile(lock: Record<string, LockEntry>): void;
+/** Get the HEAD commit hash of a git repo directory. */
+export declare function getCommitHash(dir: string): string | 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
+ * package.json if it contains .ts files.
+ */
+export declare function validatePluginStructure(pluginDir: string): ValidationResult;
 /**
  * Install a plugin from a source.
  * Currently supports "github:user/repo" format (git clone wrapper).
@@ -23,6 +48,16 @@ export declare function uninstallPlugin(name: string): void;
  * Update a plugin by name (git pull + re-install lifecycle).
  */
 export declare function updatePlugin(name: string): void;
+export interface UpdateResult {
+    name: string;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Update all installed plugins.
+ * Continues even if individual plugin updates fail.
+ */
+export declare function updateAllPlugins(): UpdateResult[];
 /**
  * List all installed plugins.
  */
@@ -32,4 +67,8 @@ declare function parseSource(source: string): {
     cloneUrl: string;
     name: string;
 } | null;
-export { parseSource as _parseSource };
+/**
+ * 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, };

package/dist/plugin.js

@@ -5,10 +5,88 @@
  * Install source format: "github:user/repo"
  */
 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 { fileURLToPath } from 'node:url';
 import { PLUGINS_DIR } from './discovery.js';
+import { getErrorMessage } from './errors.js';
 import { log } from './logger.js';
+const isWindows = process.platform === 'win32';
+/** Get home directory, respecting HOME environment variable for test isolation. */
+function getHomeDir() {
+    return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+/** Path to the lock file that tracks installed plugin versions. */
+export function getLockFilePath() {
+    return path.join(getHomeDir(), '.opencli', 'plugins.lock.json');
+}
+// Legacy const for backward compatibility (computed at load time)
+export const LOCK_FILE = path.join(os.homedir(), '.opencli', 'plugins.lock.json');
+// ── Lock file helpers ───────────────────────────────────────────────────────
+export function readLockFile() {
+    try {
+        const raw = fs.readFileSync(getLockFilePath(), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function writeLockFile(lock) {
+    const lockPath = getLockFilePath();
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
+}
+/** Get the HEAD commit hash of a git repo directory. */
+export function getCommitHash(dir) {
+    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
+ * package.json if it contains .ts files.
+ */
+export function validatePluginStructure(pluginDir) {
+    const errors = [];
+    if (!fs.existsSync(pluginDir)) {
+        return { valid: false, errors: ['Plugin directory does not exist'] };
+    }
+    const files = fs.readdirSync(pluginDir);
+    const hasYaml = files.some(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+    const hasTs = files.some(f => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts'));
+    const hasJs = files.some(f => f.endsWith('.js') && !f.endsWith('.d.js'));
+    if (!hasYaml && !hasTs && !hasJs) {
+        errors.push(`No command files found in plugin directory. A plugin must contain at least one .yaml, .ts, or .js command file.`);
+    }
+    if (hasTs) {
+        const pkgJsonPath = path.join(pluginDir, 'package.json');
+        if (!fs.existsSync(pkgJsonPath)) {
+            errors.push(`Plugin contains .ts files but no package.json. A package.json with "type": "module" and "@jackwener/opencli" peer dependency is required for TS plugins.`);
+        }
+        else {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+                if (pkg.type !== 'module') {
+                    errors.push(`Plugin package.json must have "type": "module" for TypeScript plugins.`);
+                }
+            }
+            catch {
+                errors.push(`Plugin package.json is malformed or invalid JSON.`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
 /**
  * Shared post-install lifecycle: npm install → host symlink → TS transpile.
  * Called by both installPlugin() and updatePlugin().
@@ -22,10 +100,11 @@ function postInstallLifecycle(pluginDir) {
             cwd: pluginDir,
             encoding: 'utf-8',
             stdio: ['pipe', 'pipe', 'pipe'],
+            ...(isWindows && { shell: true }),
         });
     }
-    catch {
-        // Non-fatal: npm install may fail if no real deps
+    catch (err) {
+        console.error(`[plugin] npm install failed in ${pluginDir}: ${err instanceof Error ? err.message : err}`);
     }
     // Symlink host opencli so TS plugins resolve '@jackwener/opencli/registry'
     // against the running host, not a stale npm-published version.
@@ -59,9 +138,25 @@ export function installPlugin(source) {
         });
     }
     catch (err) {
-        throw new Error(`Failed to clone plugin: ${err.message}`);
+        throw new Error(`Failed to clone plugin: ${getErrorMessage(err)}`);
+    }
+    const validation = validatePluginStructure(targetDir);
+    if (!validation.valid) {
+        // If validation fails, clean up the cloned directory and abort
+        fs.rmSync(targetDir, { recursive: true, force: true });
+        throw new Error(`Invalid plugin structure:\n- ${validation.errors.join('\n- ')}`);
     }
     postInstallLifecycle(targetDir);
+    const commitHash = getCommitHash(targetDir);
+    if (commitHash) {
+        const lock = readLockFile();
+        lock[name] = {
+            source: cloneUrl,
+            commitHash,
+            installedAt: new Date().toISOString(),
+        };
+        writeLockFile(lock);
+    }
     return name;
 }
 /**
@@ -73,6 +168,11 @@ export function uninstallPlugin(name) {
         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);
+    }
 }
 /**
  * Update a plugin by name (git pull + re-install lifecycle).
@@ -90,9 +190,44 @@ export function updatePlugin(name) {
         });
     }
     catch (err) {
-        throw new Error(`Failed to update plugin: ${err.message}`);
+        throw new Error(`Failed to update plugin: ${getErrorMessage(err)}`);
+    }
+    const validation = validatePluginStructure(targetDir);
+    if (!validation.valid) {
+        log.warn(`Plugin "${name}" updated, but structure is now invalid:\n- ${validation.errors.join('\n- ')}`);
     }
     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);
+    }
+}
+/**
+ * Update all installed plugins.
+ * Continues even if individual plugin updates fail.
+ */
+export function updateAllPlugins() {
+    return listPlugins().map((plugin) => {
+        try {
+            updatePlugin(plugin.name);
+            return { name: plugin.name, success: true };
+        }
+        catch (err) {
+            return {
+                name: plugin.name,
+                success: false,
+                error: getErrorMessage(err),
+            };
+        }
+    });
 }
 /**
  * List all installed plugins.
@@ -101,6 +236,7 @@ export function listPlugins() {
     if (!fs.existsSync(PLUGINS_DIR))
         return [];
     const entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+    const lock = readLockFile();
     const plugins = [];
     for (const entry of entries) {
         if (!entry.isDirectory())
@@ -108,11 +244,14 @@ export function listPlugins() {
         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,
         });
     }
     return plugins;
@@ -135,7 +274,7 @@ function scanPluginCommands(dir) {
 /** Get git remote origin URL */
 function getPluginSource(dir) {
     try {
-        return execSync('git config --get remote.origin.url', {
+        return execFileSync('git', ['config', '--get', 'remote.origin.url'], {
             cwd: dir,
             encoding: 'utf-8',
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -179,7 +318,7 @@ function linkHostOpencli(pluginDir) {
         // Determine the host opencli package root from this module's location.
         // Both dev (tsx src/plugin.ts) and prod (node dist/plugin.js) are one level
         // deep, so path.dirname + '..' always gives us the package root.
-        const thisFile = new URL(import.meta.url).pathname;
+        const thisFile = fileURLToPath(import.meta.url);
         const hostRoot = path.resolve(path.dirname(thisFile), '..');
         const targetLink = path.join(pluginDir, 'node_modules', '@jackwener', 'opencli');
         // Remove existing (npm-installed copy or stale symlink)
@@ -188,13 +327,73 @@ function linkHostOpencli(pluginDir) {
         }
         // Ensure parent directory exists
         fs.mkdirSync(path.dirname(targetLink), { recursive: true });
-        // Create symlink
-        fs.symlinkSync(hostRoot, targetLink, 'dir');
+        // Use 'junction' on Windows (doesn't require admin privileges),
+        // 'dir' symlink on other platforms.
+        const linkType = isWindows ? 'junction' : 'dir';
+        fs.symlinkSync(hostRoot, targetLink, linkType);
         log.debug(`Linked host opencli into plugin: ${targetLink} → ${hostRoot}`);
     }
     catch (err) {
-        log.warn(`Failed to link host opencli into plugin: ${err.message}`);
+        log.warn(`Failed to link host opencli into plugin: ${getErrorMessage(err)}`);
+    }
+}
+/**
+ * Resolve the path to the esbuild CLI executable with fallback strategies.
+ */
+export function resolveEsbuildBin() {
+    const thisFile = fileURLToPath(import.meta.url);
+    const hostRoot = path.resolve(path.dirname(thisFile), '..');
+    // Strategy 1 (Windows): prefer the .cmd wrapper which is executable via shell
+    if (isWindows) {
+        const cmdPath = path.join(hostRoot, 'node_modules', '.bin', 'esbuild.cmd');
+        if (fs.existsSync(cmdPath)) {
+            return cmdPath;
+        }
+    }
+    // Strategy 2: resolve esbuild binary via import.meta.resolve
+    // (On Unix, shebang scripts are directly executable; on Windows they are not,
+    //  so this strategy is skipped on Windows in favour of the .cmd wrapper above.)
+    if (!isWindows) {
+        try {
+            const pkgUrl = import.meta.resolve('esbuild/package.json');
+            if (pkgUrl.startsWith('file://')) {
+                const pkgPath = fileURLToPath(pkgUrl);
+                const pkgRaw = fs.readFileSync(pkgPath, 'utf8');
+                const pkg = JSON.parse(pkgRaw);
+                if (pkg.bin && typeof pkg.bin === 'object' && pkg.bin.esbuild) {
+                    const binPath = path.resolve(path.dirname(pkgPath), pkg.bin.esbuild);
+                    if (fs.existsSync(binPath))
+                        return binPath;
+                }
+                else if (typeof pkg.bin === 'string') {
+                    const binPath = path.resolve(path.dirname(pkgPath), pkg.bin);
+                    if (fs.existsSync(binPath))
+                        return binPath;
+                }
+            }
+        }
+        catch {
+            // ignore package resolution failures
+        }
+    }
+    // Strategy 3: fallback to node_modules/.bin/esbuild (Unix)
+    const binFallback = path.join(hostRoot, 'node_modules', '.bin', 'esbuild');
+    if (fs.existsSync(binFallback)) {
+        return binFallback;
     }
+    // Strategy 4: global esbuild in PATH
+    try {
+        const lookupCmd = isWindows ? 'where esbuild' : 'which esbuild';
+        // `where` on Windows may return multiple lines; take only the first match.
+        const globalBin = execSync(lookupCmd, { encoding: 'utf-8', stdio: 'pipe' }).trim().split('\n')[0].trim();
+        if (globalBin && fs.existsSync(globalBin)) {
+            return globalBin;
+        }
+    }
+    catch {
+        // ignore PATH lookup failures
+    }
+    return null;
 }
 /**
  * Transpile TS plugin files to JS so they work in production mode.
@@ -202,12 +401,9 @@ function linkHostOpencli(pluginDir) {
  */
 function transpilePluginTs(pluginDir) {
     try {
-        // Resolve esbuild binary from the host opencli's node_modules
-        const thisFile = new URL(import.meta.url).pathname;
-        const hostRoot = path.resolve(path.dirname(thisFile), '..');
-        const esbuildBin = path.join(hostRoot, 'node_modules', '.bin', 'esbuild');
-        if (!fs.existsSync(esbuildBin)) {
-            log.debug('esbuild not found in host node_modules, skipping TS transpilation');
+        const esbuildBin = resolveEsbuildBin();
+        if (!esbuildBin) {
+            log.debug('esbuild not found in host node_modules, via resolve, or in PATH, skipping TS transpilation');
             return;
         }
         const files = fs.readdirSync(pluginDir);
@@ -223,11 +419,12 @@ function transpilePluginTs(pluginDir) {
                     cwd: pluginDir,
                     encoding: 'utf-8',
                     stdio: ['pipe', 'pipe', 'pipe'],
+                    ...(isWindows && { shell: true }),
                 });
                 log.debug(`Transpiled plugin file: ${tsFile} → ${jsFile}`);
             }
             catch (err) {
-                log.warn(`Failed to transpile ${tsFile}: ${err.message}`);
+                log.warn(`Failed to transpile ${tsFile}: ${getErrorMessage(err)}`);
             }
         }
     }
@@ -235,4 +432,4 @@ function transpilePluginTs(pluginDir) {
         // Non-fatal: skip transpilation if anything goes wrong
     }
 }
-export { parseSource as _parseSource };
+export { resolveEsbuildBin as _resolveEsbuildBin, getCommitHash as _getCommitHash, parseSource as _parseSource, readLockFile as _readLockFile, updateAllPlugins as _updateAllPlugins, validatePluginStructure as _validatePluginStructure, writeLockFile as _writeLockFile, };

package/dist/plugin.test.d.ts

@@ -1,4 +1,4 @@
 /**
- * Tests for plugin management: install, uninstall, list.
+ * Tests for plugin management: install, uninstall, list, and lock file support.
  */
 export {};