@jackwener/opencli 1.5.0 → 1.5.1

package/dist/clis/xiaohongshu/publish.test.js

@@ -43,9 +43,10 @@ describe('xiaohongshu publish', () => {
         const page = createPageMock([
             'https://creator.xiaohongshu.com/publish/publish?from=menu_left',
             { ok: true, target: '上传图文', text: '上传图文' },
-            { hasTitleInput: true, hasImageInput: true, hasVideoSurface: false },
+            { state: 'editor_ready', hasTitleInput: true, hasImageInput: true, hasVideoSurface: false },
             { ok: true, count: 1 },
             false,
+            true, // waitForEditForm: editor appeared
             { ok: true, sel: 'input[maxlength="20"]' },
             { ok: true, sel: '[contenteditable="true"][class*="content"]' },
             true,
@@ -72,17 +73,21 @@ describe('xiaohongshu publish', () => {
     it('fails early with a clear error when still on the video page', async () => {
         const cmd = getRegistry().get('xiaohongshu/publish');
         expect(cmd?.func).toBeTypeOf('function');
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-xhs-publish-'));
+        const imagePath = path.join(tempDir, 'demo.jpg');
+        fs.writeFileSync(imagePath, Buffer.from([0xff, 0xd8, 0xff, 0xd9]));
         const page = createPageMock([
             'https://creator.xiaohongshu.com/publish/publish?from=menu_left',
             { ok: false, visibleTexts: ['上传视频', '上传图文'] },
-            { hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
-            { hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
-            { hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
-            { hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
+            { state: 'video_surface', hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
+            { state: 'video_surface', hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
+            { state: 'video_surface', hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
+            { state: 'video_surface', hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
         ]);
         await expect(cmd.func(page, {
             title: 'DeepSeek别乱问',
             content: '一篇真实一点的小红书正文',
+            images: imagePath,
             topics: '',
             draft: false,
         })).rejects.toThrow('Still on the video publish page after trying to select 图文');
@@ -91,11 +96,17 @@ describe('xiaohongshu publish', () => {
     it('waits for the image-text surface to appear after clicking the tab', async () => {
         const cmd = getRegistry().get('xiaohongshu/publish');
         expect(cmd?.func).toBeTypeOf('function');
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-xhs-publish-'));
+        const imagePath = path.join(tempDir, 'demo.jpg');
+        fs.writeFileSync(imagePath, Buffer.from([0xff, 0xd8, 0xff, 0xd9]));
         const page = createPageMock([
             'https://creator.xiaohongshu.com/publish/publish?from=menu_left',
             { ok: true, target: '上传图文', text: '上传图文' },
-            { hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
-            { hasTitleInput: true, hasImageInput: true, hasVideoSurface: false },
+            { state: 'video_surface', hasTitleInput: false, hasImageInput: false, hasVideoSurface: true },
+            { state: 'editor_ready', hasTitleInput: true, hasImageInput: true, hasVideoSurface: false },
+            { ok: true, count: 1 }, // injectImages
+            false, // waitForUploads: no progress indicator
+            true, // waitForEditForm: editor appeared
             { ok: true, sel: 'input[maxlength="20"]' },
             { ok: true, sel: '[contenteditable="true"][class*="content"]' },
             true,
@@ -105,6 +116,7 @@ describe('xiaohongshu publish', () => {
         const result = await cmd.func(page, {
             title: '延迟切换也能过',
             content: '图文页切换慢一点也继续等',
+            images: imagePath,
             topics: '',
             draft: false,
         });
@@ -112,7 +124,7 @@ describe('xiaohongshu publish', () => {
         expect(result).toEqual([
             {
                 status: '✅ 发布成功',
-                detail: '"延迟切换也能过" · 无图 · 发布成功',
+                detail: '"延迟切换也能过" · 1张图片 · 发布成功',
             },
         ]);
     });

package/dist/clis/xiaohongshu/search.d.ts

@@ -5,4 +5,11 @@
  * the search results page and extracts data from rendered DOM elements.
  * Ref: https://github.com/jackwener/opencli/issues/10
  */
-export {};
+/**
+ * Extract approximate publish date from a Xiaohongshu note URL.
+ * XHS note IDs follow MongoDB ObjectID format where the first 8 hex
+ * characters encode a Unix timestamp (the moment the ID was generated,
+ * which closely matches publish time but is not an official API field).
+ * e.g. "697f6c74..." → 0x697f6c74 = 1769958516 → 2026-02-01
+ */
+export declare function noteIdToDate(url: string): string;

package/dist/clis/xiaohongshu/search.js

@@ -7,6 +7,24 @@
  */
 import { cli, Strategy } from '../../registry.js';
 import { AuthRequiredError } from '../../errors.js';
+/**
+ * Extract approximate publish date from a Xiaohongshu note URL.
+ * XHS note IDs follow MongoDB ObjectID format where the first 8 hex
+ * characters encode a Unix timestamp (the moment the ID was generated,
+ * which closely matches publish time but is not an official API field).
+ * e.g. "697f6c74..." → 0x697f6c74 = 1769958516 → 2026-02-01
+ */
+export function noteIdToDate(url) {
+    const match = url.match(/\/(?:search_result|explore|note)\/([0-9a-f]{24})(?=[?#/]|$)/i);
+    if (!match)
+        return '';
+    const hex = match[1].substring(0, 8);
+    const ts = parseInt(hex, 16);
+    if (!ts || ts < 1_000_000_000 || ts > 4_000_000_000)
+        return '';
+    // Offset by UTC+8 (China Standard Time) so the date matches what XHS users see
+    return new Date((ts + 8 * 3600) * 1000).toISOString().slice(0, 10);
+}
 cli({
     site: 'xiaohongshu',
     name: 'search',
@@ -17,7 +35,7 @@ cli({
         { name: 'query', required: true, positional: true, help: 'Search keyword' },
         { name: 'limit', type: 'int', default: 20, help: 'Number of results' },
     ],
-    columns: ['rank', 'title', 'author', 'likes', 'url'],
+    columns: ['rank', 'title', 'author', 'likes', 'published_at', 'url'],
     func: async (page, kwargs) => {
         const keyword = encodeURIComponent(kwargs.query);
         await page.goto(`https://www.xiaohongshu.com/search_result?keyword=${keyword}&source=web_search_result_notes`);
@@ -89,6 +107,7 @@ cli({
             .map((item, i) => ({
             rank: i + 1,
             ...item,
+            published_at: noteIdToDate(item.url),
         }));
     },
 });

package/dist/clis/xiaohongshu/search.test.d.ts

@@ -1 +1 @@
-import './search.js';
+export {};

package/dist/clis/xiaohongshu/search.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '../../registry.js';
-import './search.js';
+import { noteIdToDate } from './search.js';
 function createPageMock(evaluateResults) {
     const evaluate = vi.fn();
     for (const result of evaluateResults) {
@@ -70,6 +70,7 @@ describe('xiaohongshu search', () => {
                 title: '某鱼买FSD被坑了4万',
                 author: '随风',
                 likes: '261',
+                published_at: '2025-10-10',
                 url: detailUrl,
                 author_url: authorUrl,
             },
@@ -112,3 +113,33 @@ describe('xiaohongshu search', () => {
         expect(result[0]).toMatchObject({ rank: 1, title: 'Result A' });
     });
 });
+describe('noteIdToDate (ObjectID timestamp parsing)', () => {
+    it('parses a known note ID to the correct China-timezone date', () => {
+        // 0x697f6c74 = 1769958516 → 2026-02-01 in UTC+8
+        expect(noteIdToDate('https://www.xiaohongshu.com/search_result/697f6c74000000002103de17')).toBe('2026-02-01');
+        // 0x68e90be8 → 2025-10-10 in UTC+8
+        expect(noteIdToDate('https://www.xiaohongshu.com/explore/68e90be80000000004022e66')).toBe('2025-10-10');
+    });
+    it('returns China date when UTC+8 crosses into the next day', () => {
+        // 0x69b739f0 = 2026-03-15 23:00 UTC = 2026-03-16 07:00 CST
+        // Without UTC+8 offset this would incorrectly return 2026-03-15
+        expect(noteIdToDate('https://www.xiaohongshu.com/search_result/69b739f00000000000000000')).toBe('2026-03-16');
+    });
+    it('handles /note/ path variant', () => {
+        expect(noteIdToDate('https://www.xiaohongshu.com/note/697f6c74000000002103de17')).toBe('2026-02-01');
+    });
+    it('handles URL with query parameters', () => {
+        expect(noteIdToDate('https://www.xiaohongshu.com/search_result/697f6c74000000002103de17?xsec_token=abc')).toBe('2026-02-01');
+    });
+    it('returns empty string for non-matching URLs', () => {
+        expect(noteIdToDate('https://www.xiaohongshu.com/user/profile/635a9c720000000018028b40')).toBe('');
+        expect(noteIdToDate('https://www.xiaohongshu.com/')).toBe('');
+    });
+    it('returns empty string for IDs shorter than 24 hex chars', () => {
+        expect(noteIdToDate('https://www.xiaohongshu.com/search_result/abcdef')).toBe('');
+    });
+    it('returns empty string when timestamp is out of range', () => {
+        // All zeros → ts = 0
+        expect(noteIdToDate('https://www.xiaohongshu.com/search_result/000000000000000000000000')).toBe('');
+    });
+});

package/dist/discovery.js

@@ -127,22 +127,20 @@ async function discoverClisFromFs(dir) {
         const site = entry.name;
         const siteDir = path.join(dir, site);
         const files = await fs.promises.readdir(siteDir);
-        const filePromises = [];
-        for (const file of files) {
+        await Promise.all(files.map(async (file) => {
             const filePath = path.join(siteDir, file);
             if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-                filePromises.push(registerYamlCli(filePath, site));
+                await registerYamlCli(filePath, site);
             }
             else if ((file.endsWith('.js') && !file.endsWith('.d.js')) ||
                 (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts'))) {
                 if (!(await isCliModule(filePath)))
-                    continue;
-                filePromises.push(import(pathToFileURL(filePath).href).catch((err) => {
+                    return;
+                await import(pathToFileURL(filePath).href).catch((err) => {
                     log.warn(`Failed to load module ${filePath}: ${getErrorMessage(err)}`);
-                }));
+                });
             }
-        }
-        await Promise.all(filePromises);
+        }));
     });
     await Promise.all(sitePromises);
 }
@@ -194,11 +192,12 @@ export async function discoverPlugins() {
         return;
     }
     const entries = await fs.promises.readdir(PLUGINS_DIR, { withFileTypes: true });
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        await discoverPluginDir(path.join(PLUGINS_DIR, entry.name), entry.name);
-    }
+    await Promise.all(entries.map(async (entry) => {
+        const pluginDir = path.join(PLUGINS_DIR, entry.name);
+        if (!(await isDiscoverablePluginDir(entry, pluginDir)))
+            return;
+        await discoverPluginDir(pluginDir, entry.name);
+    }));
 }
 /**
  * Flat scan: read yaml/ts files directly in a plugin directory.
@@ -207,32 +206,29 @@ export async function discoverPlugins() {
 async function discoverPluginDir(dir, site) {
     const files = await fs.promises.readdir(dir);
     const fileSet = new Set(files);
-    const promises = [];
-    for (const file of files) {
+    await Promise.all(files.map(async (file) => {
         const filePath = path.join(dir, file);
         if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-            promises.push(registerYamlCli(filePath, site));
+            await registerYamlCli(filePath, site);
         }
         else if (file.endsWith('.js') && !file.endsWith('.d.js')) {
             if (!(await isCliModule(filePath)))
-                continue;
-            promises.push(import(pathToFileURL(filePath).href).catch((err) => {
+                return;
+            await import(pathToFileURL(filePath).href).catch((err) => {
                 log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
-            }));
+            });
         }
         else if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
-            // Skip .ts if a compiled .js sibling exists (production mode can't load .ts)
             const jsFile = file.replace(/\.ts$/, '.js');
+            // Prefer compiled .js — skip the .ts source file
             if (fileSet.has(jsFile))
-                continue;
-            if (!(await isCliModule(filePath)))
-                continue;
-            promises.push(import(pathToFileURL(filePath).href).catch((err) => {
-                log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
-            }));
+                return;
+            // No compiled .js found — cannot import raw .ts in production Node.js.
+            // This typically means esbuild transpilation failed during plugin install.
+            log.warn(`Plugin ${site}/${file}: no compiled .js found. ` +
+                `Run "opencli plugin update ${site}" to re-transpile, or install esbuild.`);
         }
-    }
-    await Promise.all(promises);
+    }));
 }
 async function isCliModule(filePath) {
     try {
@@ -244,3 +240,19 @@ async function isCliModule(filePath) {
         return false;
     }
 }
+async function isDiscoverablePluginDir(entry, pluginDir) {
+    if (entry.isDirectory())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        return (await fs.promises.stat(pluginDir)).isDirectory();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+            log.warn(`Failed to inspect plugin link ${pluginDir}: ${getErrorMessage(err)}`);
+        }
+        return false;
+    }
+}

package/dist/doctor.d.ts

@@ -1,11 +1,10 @@
 /**
- * opencli doctor — diagnose and fix browser connectivity.
+ * opencli doctor — diagnose browser connectivity.
  *
  * Simplified for the daemon-based architecture. No more token management,
  * MCP path discovery, or config file scanning.
  */
 export type DoctorOptions = {
-    fix?: boolean;
     yes?: boolean;
     live?: boolean;
     sessions?: boolean;

package/dist/doctor.js

@@ -1,5 +1,5 @@
 /**
- * opencli doctor — diagnose and fix browser connectivity.
+ * opencli doctor — diagnose browser connectivity.
  *
  * Simplified for the daemon-based architecture. No more token management,
  * MCP path discovery, or config file scanning.
@@ -58,7 +58,7 @@ export async function runBrowserDoctor(opts = {}) {
     if (status.running && !status.extensionConnected) {
         issues.push('Daemon is running but the Chrome extension is not connected.\n' +
             'Please install the opencli Browser Bridge extension:\n' +
-            '  1. Download from GitHub Releases\n' +
+            '  1. Download from https://github.com/jackwener/opencli/releases\n' +
             '  2. Open chrome://extensions/ → Enable Developer Mode\n' +
             '  3. Click "Load unpacked" → select the extension folder');
     }

package/dist/engine.test.js

@@ -75,11 +75,26 @@ cli({
 describe('discoverPlugins', () => {
     const testPluginDir = path.join(PLUGINS_DIR, '__test-plugin__');
     const yamlPath = path.join(testPluginDir, 'greeting.yaml');
+    const symlinkTargetDir = path.join(os.tmpdir(), '__test-plugin-symlink-target__');
+    const symlinkPluginDir = path.join(PLUGINS_DIR, '__test-plugin-symlink__');
+    const brokenSymlinkDir = path.join(PLUGINS_DIR, '__test-plugin-broken__');
     afterEach(async () => {
         try {
             await fs.promises.rm(testPluginDir, { recursive: true });
         }
         catch { }
+        try {
+            await fs.promises.rm(symlinkPluginDir, { recursive: true, force: true });
+        }
+        catch { }
+        try {
+            await fs.promises.rm(symlinkTargetDir, { recursive: true, force: true });
+        }
+        catch { }
+        try {
+            await fs.promises.rm(brokenSymlinkDir, { recursive: true, force: true });
+        }
+        catch { }
     });
     it('discovers YAML plugins from ~/.opencli/plugins/', async () => {
         // Create a simple YAML adapter in the plugins directory
@@ -108,6 +123,33 @@ columns: [message]
         // discoverPlugins should not throw if ~/.opencli/plugins/ does not exist
         await expect(discoverPlugins()).resolves.not.toThrow();
     });
+    it('discovers YAML plugins from symlinked plugin directories', async () => {
+        await fs.promises.mkdir(PLUGINS_DIR, { recursive: true });
+        await fs.promises.mkdir(symlinkTargetDir, { recursive: true });
+        await fs.promises.writeFile(path.join(symlinkTargetDir, 'hello.yaml'), `
+site: __test-plugin-symlink__
+name: hello
+description: Test plugin greeting via symlink
+strategy: public
+browser: false
+
+pipeline:
+  - evaluate: "() => [{ message: 'hello from symlink plugin' }]"
+
+columns: [message]
+`);
+        await fs.promises.symlink(symlinkTargetDir, symlinkPluginDir, 'dir');
+        await discoverPlugins();
+        const cmd = getRegistry().get('__test-plugin-symlink__/hello');
+        expect(cmd).toBeDefined();
+        expect(cmd.description).toBe('Test plugin greeting via symlink');
+    });
+    it('skips broken plugin symlinks without throwing', async () => {
+        await fs.promises.mkdir(PLUGINS_DIR, { recursive: true });
+        await fs.promises.symlink(path.join(os.tmpdir(), '__missing-plugin-target__'), brokenSymlinkDir, 'dir');
+        await expect(discoverPlugins()).resolves.not.toThrow();
+        expect(getRegistry().get('__test-plugin-broken__/hello')).toBeUndefined();
+    });
 });
 describe('executeCommand', () => {
     beforeEach(() => {

package/dist/errors.d.ts

@@ -31,7 +31,7 @@ export declare class AuthRequiredError extends CliError {
     constructor(domain: string, message?: string);
 }
 export declare class TimeoutError extends CliError {
-    constructor(label: string, seconds: number);
+    constructor(label: string, seconds: number, hint?: string);
 }
 export declare class ArgumentError extends CliError {
     constructor(message: string, hint?: string);

package/dist/errors.js

@@ -41,8 +41,8 @@ export class AuthRequiredError extends CliError {
     }
 }
 export class TimeoutError extends CliError {
-    constructor(label, seconds) {
-        super('TIMEOUT', `${label} timed out after ${seconds}s`, 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var');
+    constructor(label, seconds, hint) {
+        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var');
     }
 }
 export class ArgumentError extends CliError {

package/dist/execution.js

@@ -110,6 +110,25 @@ function ensureRequiredEnv(cmd) {
         return;
     throw new CommandExecutionError(`Command ${fullName(cmd)} requires environment variable ${missing.name}.`, missing.help ?? `Set ${missing.name} before running ${fullName(cmd)}.`);
 }
+/**
+ * Check if the browser is already on the target domain, avoiding redundant navigation.
+ * Returns true if current page hostname matches the pre-nav URL hostname.
+ */
+async function isAlreadyOnDomain(page, targetUrl) {
+    if (!page.getCurrentUrl)
+        return false;
+    try {
+        const currentUrl = await page.getCurrentUrl();
+        if (!currentUrl)
+            return false;
+        const currentHost = new URL(currentUrl).hostname;
+        const targetHost = new URL(targetUrl).hostname;
+        return currentHost === targetHost;
+    }
+    catch {
+        return false;
+    }
+}
 export async function executeCommand(cmd, rawKwargs, debug = false) {
     let kwargs;
     try {
@@ -151,13 +170,21 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
             result = await browserSession(BrowserFactory, async (page) => {
                 const preNavUrl = resolvePreNav(cmd);
                 if (preNavUrl) {
-                    try {
-                        await page.goto(preNavUrl);
-                        await page.wait(2);
-                    }
-                    catch (err) {
+                    const skip = await isAlreadyOnDomain(page, preNavUrl);
+                    if (skip) {
                         if (debug)
-                            console.error(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
+                            console.error(`[pre-nav] Already on target domain, skipping navigation`);
+                    }
+                    else {
+                        try {
+                            // goto() already includes smart DOM-settle detection (waitForDomStable).
+                            // No additional fixed sleep needed.
+                            await page.goto(preNavUrl);
+                        }
+                        catch (err) {
+                            if (debug)
+                                console.error(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
+                        }
                     }
                 }
                 return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
@@ -167,7 +194,18 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
             }, { workspace: `site:${cmd.site}` });
         }
         else {
-            result = await runCommand(cmd, null, kwargs, debug);
+            // Non-browser commands: apply timeout only when explicitly configured.
+            const timeout = cmd.timeoutSeconds;
+            if (timeout !== undefined && timeout > 0) {
+                result = await runWithTimeout(runCommand(cmd, null, kwargs, debug), {
+                    timeout,
+                    label: fullName(cmd),
+                    hint: `Increase the adapter's timeoutSeconds setting (currently ${timeout}s)`,
+                });
+            }
+            else {
+                result = await runCommand(cmd, null, kwargs, debug);
+            }
         }
     }
     catch (err) {

package/dist/execution.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/execution.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { executeCommand } from './execution.js';
+import { TimeoutError } from './errors.js';
+import { cli, Strategy } from './registry.js';
+import { withTimeoutMs } from './runtime.js';
+describe('executeCommand — non-browser timeout', () => {
+    it('applies timeoutSeconds to non-browser commands', async () => {
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'non-browser-timeout',
+            description: 'test non-browser timeout',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            timeoutSeconds: 0.01,
+            func: () => new Promise(() => { }),
+        });
+        // Sentinel timeout at 200ms — if the inner 10ms timeout fires first,
+        // the error will be a TimeoutError with the command label, not 'sentinel'.
+        const error = await withTimeoutMs(executeCommand(cmd, {}), 200, 'sentinel timeout')
+            .catch((err) => err);
+        expect(error).toBeInstanceOf(TimeoutError);
+        expect(error).toMatchObject({
+            code: 'TIMEOUT',
+            message: 'test-execution/non-browser-timeout timed out after 0.01s',
+        });
+    });
+    it('skips timeout when timeoutSeconds is 0', async () => {
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'non-browser-zero-timeout',
+            description: 'test zero timeout bypasses wrapping',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            timeoutSeconds: 0,
+            func: () => new Promise(() => { }),
+        });
+        // With timeout guard skipped, the sentinel fires instead.
+        await expect(withTimeoutMs(executeCommand(cmd, {}), 50, 'sentinel timeout')).rejects.toThrow('sentinel timeout');
+    });
+});

package/dist/external.js

@@ -12,7 +12,10 @@ function getUserRegistryPath() {
     const home = os.homedir();
     return path.join(home, '.opencli', 'external-clis.yaml');
 }
+let _cachedExternalClis = null;
 export function loadExternalClis() {
+    if (_cachedExternalClis)
+        return _cachedExternalClis;
     const configs = new Map();
     // 1. Load built-in
     const builtinPath = path.resolve(__dirname, 'external-clis.yaml');
@@ -41,7 +44,8 @@ export function loadExternalClis() {
     catch (err) {
         log.warn(`Failed to parse user external-clis.yaml: ${getErrorMessage(err)}`);
     }
-    return Array.from(configs.values()).sort((a, b) => a.name.localeCompare(b.name));
+    _cachedExternalClis = Array.from(configs.values()).sort((a, b) => a.name.localeCompare(b.name));
+    return _cachedExternalClis;
 }
 export function isBinaryInstalled(binary) {
     try {
@@ -200,5 +204,6 @@ export function registerExternalCli(name, opts) {
     }
     const dump = yaml.dump(items, { indent: 2, sortKeys: true });
     fs.writeFileSync(userPath, dump, 'utf8');
+    _cachedExternalClis = null; // Invalidate cache so next load reflects the change
     console.log(chalk.dim(userPath));
 }

package/dist/main.js

@@ -24,6 +24,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
+// Sequential: plugins must run after built-in discovery so they can override built-in commands.
 await discoverClis(BUILTIN_CLIS, USER_CLIS);
 await discoverPlugins();
 // Register exit hook: notice appears after command output (same as npm/gh/yarn)

package/dist/plugin-scaffold.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Plugin scaffold: generates a ready-to-develop plugin directory.
+ *
+ * Usage: opencli plugin create <name> [--dir <path>]
+ *
+ * Creates:
+ *   <name>/
+ *     opencli-plugin.json   — manifest with name, version, description
+ *     package.json          — ESM package with opencli peer dependency
+ *     hello.yaml            — sample YAML command
+   *     greet.ts              — sample TS command using the current registry API
+ *     README.md             — basic documentation
+ */
+export interface ScaffoldOptions {
+    /** Directory to create the plugin in. Defaults to `./<name>` */
+    dir?: string;
+    /** Plugin description */
+    description?: string;
+}
+export interface ScaffoldResult {
+    name: string;
+    dir: string;
+    files: string[];
+}
+/**
+ * Create a new plugin scaffold directory.
+ */
+export declare function createPluginScaffold(name: string, opts?: ScaffoldOptions): ScaffoldResult;