@jackwener/opencli 1.6.8 → 1.6.10

package/dist/src/plugin.test.js

@@ -12,7 +12,7 @@ const { mockExecFileSync, mockExecSync } = vi.hoisted(() => ({
     mockExecFileSync: vi.fn(),
     mockExecSync: vi.fn(),
 }));
-const { _getCommitHash, _installDependencies, _postInstallMonorepoLifecycle, _promoteDir, _replaceDir, installPlugin, listPlugins, _readLockFile, _readLockFileWithWriter, _resolveEsbuildBin, uninstallPlugin, updatePlugin, _parseSource, _updateAllPlugins, _validatePluginStructure, _writeLockFile, _writeLockFileWithFs, _isSymlinkSync, _getMonoreposDir, getLockFilePath, _installLocalPlugin, _isLocalPluginSource, _moveDir, _resolvePluginSource, _resolveStoredPluginSource, _toStoredPluginSource, _toLocalPluginSource, } = pluginModule;
+const { _getCommitHash, _installDependencies, _postInstallMonorepoLifecycle, _promoteDir, _replaceDir, installPlugin, listPlugins, _readLockFile, _readLockFileWithWriter, _resolveEsbuildBin, _resolveHostOpencliRoot, uninstallPlugin, updatePlugin, _parseSource, _updateAllPlugins, _validatePluginStructure, _writeLockFile, _writeLockFileWithFs, _isSymlinkSync, _getMonoreposDir, getLockFilePath, _installLocalPlugin, _isLocalPluginSource, _moveDir, _resolvePluginSource, _resolveStoredPluginSource, _toStoredPluginSource, _toLocalPluginSource, } = pluginModule;
 describe('parseSource', () => {
     it('parses github:user/repo format', () => {
         const result = _parseSource('github:ByteYue/opencli-plugin-github-trending');
@@ -146,11 +146,11 @@ describe('validatePluginStructure', () => {
         expect(res.valid).toBe(false);
         expect(res.errors[0]).toContain('No command files found');
     });
-    it('returns valid for YAML plugin', () => {
+    it('returns invalid for YAML-only plugin (YAML no longer supported)', () => {
         fs.writeFileSync(path.join(testDir, 'cmd.yaml'), 'site: test');
         const res = _validatePluginStructure(testDir);
-        expect(res.valid).toBe(true);
-        expect(res.errors).toHaveLength(0);
+        expect(res.valid).toBe(false);
+        expect(res.errors[0]).toContain('No command files found');
     });
     it('returns valid for JS plugin', () => {
         fs.writeFileSync(path.join(testDir, 'cmd.js'), 'console.log("hi");');
@@ -336,6 +336,21 @@ describe('resolveEsbuildBin', () => {
         expect(binPath).toMatch(/esbuild(\.cmd)?$/);
     });
 });
+describe('resolveHostOpencliRoot', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-host-root-test-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('walks up from compiled dist/src files to the package root', () => {
+        fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({ name: '@jackwener/opencli' }));
+        const distSrcDir = path.join(tmpDir, 'dist', 'src');
+        fs.mkdirSync(distSrcDir, { recursive: true });
+        expect(_resolveHostOpencliRoot(path.join(distSrcDir, 'plugin.js'))).toBe(tmpDir);
+    });
+});
 describe('listPlugins', () => {
     const testDir = path.join(PLUGINS_DIR, '__test-list-plugin__');
     afterEach(() => {
@@ -346,7 +361,7 @@ describe('listPlugins', () => {
     });
     it('lists installed plugins', () => {
         fs.mkdirSync(testDir, { recursive: true });
-        fs.writeFileSync(path.join(testDir, 'hello.yaml'), 'site: test\nname: hello\n');
+        fs.writeFileSync(path.join(testDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
         const plugins = listPlugins();
         const found = plugins.find(p => p.name === '__test-list-plugin__');
         expect(found).toBeDefined();
@@ -354,7 +369,7 @@ describe('listPlugins', () => {
     });
     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');
+        fs.writeFileSync(path.join(testDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
         const lock = _readLockFile();
         lock['__test-list-plugin__'] = {
             source: { kind: 'git', url: 'https://github.com/user/repo.git' },
@@ -378,7 +393,7 @@ describe('listPlugins', () => {
         const localTarget = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-local-list-'));
         const linkPath = path.join(PLUGINS_DIR, '__test-list-plugin__');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
-        fs.writeFileSync(path.join(localTarget, 'hello.yaml'), 'site: test\nname: hello\n');
+        fs.writeFileSync(path.join(localTarget, 'hello.js'), 'cli({ site: "test", name: "hello" })');
         try {
             fs.unlinkSync(linkPath);
         }
@@ -420,13 +435,13 @@ describe('uninstallPlugin', () => {
     });
     it('removes plugin directory', () => {
         fs.mkdirSync(testDir, { recursive: true });
-        fs.writeFileSync(path.join(testDir, 'test.yaml'), 'site: test');
+        fs.writeFileSync(path.join(testDir, 'test.js'), 'cli({ site: "test", name: "test" })');
         uninstallPlugin('__test-uninstall__');
         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');
+        fs.writeFileSync(path.join(testDir, 'test.js'), 'cli({ site: "test", name: "test" })');
         const lock = _readLockFile();
         lock['__test-uninstall__'] = {
             source: { kind: 'git', url: 'https://github.com/user/repo.git' },
@@ -449,7 +464,7 @@ describe('updatePlugin', () => {
         const localTarget = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-local-update-'));
         const linkPath = path.join(PLUGINS_DIR, '__test-local-update__');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
-        fs.writeFileSync(path.join(localTarget, 'hello.yaml'), 'site: test\nname: hello\n');
+        fs.writeFileSync(path.join(localTarget, 'hello.js'), 'cli({ site: "test", name: "hello" })');
         fs.symlinkSync(localTarget, linkPath, 'dir');
         const lock = _readLockFile();
         lock['__test-local-update__'] = {
@@ -525,7 +540,7 @@ describe('postInstallMonorepoLifecycle', () => {
             private: true,
             workspaces: ['packages/*'],
         }));
-        fs.writeFileSync(path.join(subDir, 'hello.yaml'), 'site: test\nname: hello\n');
+        fs.writeFileSync(path.join(subDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
     });
     afterEach(() => {
         fs.rmSync(repoDir, { recursive: true, force: true });
@@ -546,9 +561,9 @@ describe('updateAllPlugins', () => {
         fs.mkdirSync(testDirA, { recursive: true });
         fs.mkdirSync(testDirB, { recursive: true });
         fs.mkdirSync(testDirC, { recursive: true });
-        fs.writeFileSync(path.join(testDirA, 'cmd.yaml'), 'site: a');
-        fs.writeFileSync(path.join(testDirB, 'cmd.yaml'), 'site: b');
-        fs.writeFileSync(path.join(testDirC, 'cmd.yaml'), 'site: c');
+        fs.writeFileSync(path.join(testDirA, 'cmd.js'), 'cli({ site: "a", name: "cmd" })');
+        fs.writeFileSync(path.join(testDirB, 'cmd.js'), 'cli({ site: "b", name: "cmd" })');
+        fs.writeFileSync(path.join(testDirC, 'cmd.js'), 'cli({ site: "c", name: "cmd" })');
         const lock = _readLockFile();
         lock['plugin-a'] = {
             source: { kind: 'git', url: 'https://github.com/user/plugin-a.git' },
@@ -593,7 +608,7 @@ describe('updateAllPlugins', () => {
                 const cloneUrl = String(args[3]);
                 const cloneDir = String(args[4]);
                 fs.mkdirSync(cloneDir, { recursive: true });
-                fs.writeFileSync(path.join(cloneDir, 'cmd.yaml'), 'site: test\nname: hello\n');
+                fs.writeFileSync(path.join(cloneDir, 'cmd.js'), 'cli({ site: "test", name: "hello" })');
                 if (cloneUrl.includes('plugin-b')) {
                     fs.writeFileSync(path.join(cloneDir, 'package.json'), JSON.stringify({ name: 'plugin-b' }));
                 }
@@ -680,7 +695,7 @@ describe('monorepo uninstall with symlink', () => {
         monoDir = path.join(_getMonoreposDir(), '__test-mono__');
         const subDir = path.join(monoDir, 'packages', 'sub');
         fs.mkdirSync(subDir, { recursive: true });
-        fs.writeFileSync(path.join(subDir, 'cmd.yaml'), 'site: test');
+        fs.writeFileSync(path.join(subDir, 'cmd.js'), 'cli({ site: "test", name: "cmd" })');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
         fs.symlinkSync(subDir, pluginDir, 'dir');
         const lock = _readLockFile();
@@ -747,7 +762,7 @@ describe('listPlugins with monorepo metadata', () => {
     const testLink = path.join(PLUGINS_DIR, '__test-mono-list__');
     beforeEach(() => {
         fs.mkdirSync(testSymlinkTarget, { recursive: true });
-        fs.writeFileSync(path.join(testSymlinkTarget, 'hello.yaml'), 'site: test\nname: hello\n');
+        fs.writeFileSync(path.join(testSymlinkTarget, 'hello.js'), 'cli({ site: "test", name: "hello" })');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
         try {
             fs.unlinkSync(testLink);
@@ -794,7 +809,7 @@ describe('installLocalPlugin', () => {
     const pluginName = '__test-local-plugin__';
     beforeEach(() => {
         tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-local-install-'));
-        fs.writeFileSync(path.join(tmpDir, 'hello.yaml'), 'site: test\nname: hello\n');
+        fs.writeFileSync(path.join(tmpDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
     });
     afterEach(() => {
         const linkPath = path.join(PLUGINS_DIR, pluginName);
@@ -992,7 +1007,7 @@ describe('installPlugin transactional staging', () => {
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'clone') {
                 const cloneDir = String(args[args.length - 1]);
                 fs.mkdirSync(cloneDir, { recursive: true });
-                fs.writeFileSync(path.join(cloneDir, 'hello.yaml'), 'site: test\nname: hello\n');
+                fs.writeFileSync(path.join(cloneDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
                 fs.writeFileSync(path.join(cloneDir, 'package.json'), JSON.stringify({ name: standaloneName }));
                 return '';
             }
@@ -1023,7 +1038,7 @@ describe('installPlugin transactional staging', () => {
                         alpha: { path: 'packages/alpha' },
                     },
                 }));
-                fs.writeFileSync(path.join(alphaDir, 'hello.yaml'), 'site: test\nname: hello\n');
+                fs.writeFileSync(path.join(alphaDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
                 return '';
             }
             if (cmd === 'npm' && Array.isArray(args) && args[0] === 'install') {
@@ -1080,7 +1095,7 @@ describe('installPlugin with existing monorepo', () => {
                 [pluginName]: { path: `packages/${pluginName}` },
             },
         }));
-        fs.writeFileSync(path.join(subDir, 'hello.yaml'), 'site: test\nname: hello\n');
+        fs.writeFileSync(path.join(subDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
         mockExecFileSync.mockImplementation((cmd, args) => {
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'clone') {
                 const cloneDir = String(args[4]);
@@ -1139,7 +1154,7 @@ describe('updatePlugin transactional staging', () => {
     });
     it('keeps the existing standalone plugin when staged update preparation fails', () => {
         fs.mkdirSync(standaloneDir, { recursive: true });
-        fs.writeFileSync(path.join(standaloneDir, 'old.yaml'), 'site: old\nname: old\n');
+        fs.writeFileSync(path.join(standaloneDir, 'old.js'), 'cli({ site: "old", name: "old" })');
         const lock = _readLockFile();
         lock[standaloneName] = {
             source: {
@@ -1154,7 +1169,7 @@ describe('updatePlugin transactional staging', () => {
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'clone') {
                 const cloneDir = String(args[4]);
                 fs.mkdirSync(cloneDir, { recursive: true });
-                fs.writeFileSync(path.join(cloneDir, 'hello.yaml'), 'site: test\nname: hello\n');
+                fs.writeFileSync(path.join(cloneDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
                 fs.writeFileSync(path.join(cloneDir, 'package.json'), JSON.stringify({ name: standaloneName }));
                 return '';
             }
@@ -1168,13 +1183,13 @@ describe('updatePlugin transactional staging', () => {
         });
         expect(() => updatePlugin(standaloneName)).toThrow('npm install failed');
         expect(fs.existsSync(standaloneDir)).toBe(true);
-        expect(fs.readFileSync(path.join(standaloneDir, 'old.yaml'), 'utf-8')).toContain('site: old');
+        expect(fs.readFileSync(path.join(standaloneDir, 'old.js'), 'utf-8')).toContain('site: "old"');
         expect(_readLockFile()[standaloneName]?.commitHash).toBe('oldhasholdhasholdhasholdhasholdhasholdh');
     });
     it('keeps the existing monorepo repo and link when staged update preparation fails', () => {
         const subDir = path.join(monorepoRepoDir, 'packages', monorepoPluginName);
         fs.mkdirSync(subDir, { recursive: true });
-        fs.writeFileSync(path.join(subDir, 'old.yaml'), 'site: old\nname: old\n');
+        fs.writeFileSync(path.join(subDir, 'old.js'), 'cli({ site: "old", name: "old" })');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
         fs.symlinkSync(subDir, monorepoLink, 'dir');
         const lock = _readLockFile();
@@ -1203,7 +1218,7 @@ describe('updatePlugin transactional staging', () => {
                         [monorepoPluginName]: { path: `packages/${monorepoPluginName}` },
                     },
                 }));
-                fs.writeFileSync(path.join(alphaDir, 'hello.yaml'), 'site: test\nname: hello\n');
+                fs.writeFileSync(path.join(alphaDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
                 return '';
             }
             if (cmd === 'npm' && Array.isArray(args) && args[0] === 'install') {
@@ -1217,13 +1232,13 @@ describe('updatePlugin transactional staging', () => {
         expect(() => updatePlugin(monorepoPluginName)).toThrow('npm install failed');
         expect(fs.existsSync(monorepoRepoDir)).toBe(true);
         expect(fs.existsSync(monorepoLink)).toBe(true);
-        expect(fs.readFileSync(path.join(subDir, 'old.yaml'), 'utf-8')).toContain('site: old');
+        expect(fs.readFileSync(path.join(subDir, 'old.js'), 'utf-8')).toContain('site: "old"');
         expect(_readLockFile()[monorepoPluginName]?.commitHash).toBe('oldmonooldmonooldmonooldmonooldmonoold');
     });
     it('relinks monorepo plugins when the updated manifest moves their subPath', () => {
         const oldSubDir = path.join(monorepoRepoDir, 'packages', 'old-alpha');
         fs.mkdirSync(oldSubDir, { recursive: true });
-        fs.writeFileSync(path.join(oldSubDir, 'old.yaml'), 'site: old\nname: old\n');
+        fs.writeFileSync(path.join(oldSubDir, 'old.js'), 'cli({ site: "old", name: "old" })');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
         fs.symlinkSync(oldSubDir, monorepoLink, 'dir');
         const lock = _readLockFile();
@@ -1248,7 +1263,7 @@ describe('updatePlugin transactional staging', () => {
                         [monorepoPluginName]: { path: 'packages/moved-alpha' },
                     },
                 }));
-                fs.writeFileSync(path.join(movedDir, 'hello.yaml'), 'site: test\nname: hello\n');
+                fs.writeFileSync(path.join(movedDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
                 return '';
             }
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'rev-parse' && args[1] === 'HEAD') {
@@ -1267,7 +1282,7 @@ describe('updatePlugin transactional staging', () => {
     it('rolls back the monorepo repo swap when relinking fails', () => {
         const oldSubDir = path.join(monorepoRepoDir, 'packages', 'old-alpha');
         fs.mkdirSync(oldSubDir, { recursive: true });
-        fs.writeFileSync(path.join(oldSubDir, 'old.yaml'), 'site: old\nname: old\n');
+        fs.writeFileSync(path.join(oldSubDir, 'old.js'), 'cli({ site: "old", name: "old" })');
         fs.mkdirSync(monorepoLink, { recursive: true });
         fs.writeFileSync(path.join(monorepoLink, 'blocker.txt'), 'not a symlink');
         const lock = _readLockFile();
@@ -1292,7 +1307,7 @@ describe('updatePlugin transactional staging', () => {
                         [monorepoPluginName]: { path: 'packages/moved-alpha' },
                     },
                 }));
-                fs.writeFileSync(path.join(movedDir, 'hello.yaml'), 'site: test\nname: hello\n');
+                fs.writeFileSync(path.join(movedDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
                 return '';
             }
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'rev-parse' && args[1] === 'HEAD') {
@@ -1301,7 +1316,7 @@ describe('updatePlugin transactional staging', () => {
             return '';
         });
         expect(() => updatePlugin(monorepoPluginName)).toThrow('to be a symlink');
-        expect(fs.existsSync(path.join(monorepoRepoDir, 'packages', 'old-alpha', 'old.yaml'))).toBe(true);
+        expect(fs.existsSync(path.join(monorepoRepoDir, 'packages', 'old-alpha', 'old.js'))).toBe(true);
         expect(fs.existsSync(path.join(monorepoRepoDir, 'packages', 'moved-alpha'))).toBe(false);
         expect(fs.readFileSync(path.join(monorepoLink, 'blocker.txt'), 'utf-8')).toBe('not a symlink');
         expect(_readLockFile()[monorepoPluginName]?.source).toMatchObject({

package/dist/src/record.js

@@ -15,7 +15,6 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as readline from 'node:readline';
 import chalk from 'chalk';
-import yaml from 'js-yaml';
 import { sendCommand } from './browser/daemon-client.js';
 import { SEARCH_PARAMS, PAGINATION_PARAMS, FIELD_ROLES } from './constants.js';
 import { urlToPattern, findArrayPath, inferCapabilityName, inferStrategy, detectAuthFromContent, classifyQueryParams, isNoiseUrl, } from './analysis.js';
@@ -454,8 +453,8 @@ export async function recordSession(opts) {
     const pollMs = opts.pollMs ?? 2000;
     const timeoutMs = opts.timeoutMs ?? 60_000;
     const allRequests = [];
-    // Track which tabIds have already had the interceptor injected
-    const injectedTabs = new Set();
+    // Track which pages (targetIds) have already had the interceptor injected
+    const injectedPages = new Set();
     // Infer site name from URL
     const site = opts.site ?? (() => {
         try {
@@ -479,9 +478,10 @@ export async function recordSession(opts) {
         // Inject into initial tab
         const initialTabs = await listTabs(workspace);
         for (const tab of initialTabs) {
-            await injectIntoTab(workspace, tab.tabId, injectedTabs);
+            if (tab.page)
+                await injectIntoPage(workspace, tab.page, injectedPages);
         }
-        console.log(chalk.bold('\n  Recording. Operate the page in the automation window.'));
+        console.log(chalk.bold('\n  Recording. Use the page in the browser automation window.'));
         console.log(chalk.dim(`  Will auto-stop after ${timeoutMs / 1000}s, or press Enter to stop now.\n`));
         // Race: Enter key vs timeout
         let stopped = false;
@@ -500,15 +500,16 @@ export async function recordSession(opts) {
                 // Discover and inject into any new tabs
                 const tabs = await listTabs(workspace);
                 for (const tab of tabs) {
-                    await injectIntoTab(workspace, tab.tabId, injectedTabs);
+                    if (tab.page)
+                        await injectIntoPage(workspace, tab.page, injectedPages);
                 }
-                // Drain captured data from all known tabs
-                for (const tabId of injectedTabs) {
-                    const batch = await execOnTab(workspace, tabId, generateReadRecordedJs());
+                // Drain captured data from all known pages
+                for (const page of injectedPages) {
+                    const batch = await execOnPage(workspace, page, generateReadRecordedJs());
                     if (Array.isArray(batch) && batch.length > 0) {
                         for (const r of batch)
                             allRequests.push(r);
-                        console.log(chalk.dim(`  [tab:${tabId}] +${batch.length} captured — total: ${allRequests.length}`));
+                        console.log(chalk.dim(`  [page:${page.slice(0, 8)}] +${batch.length} captured — total: ${allRequests.length}`));
                     }
                 }
             }
@@ -519,10 +520,10 @@ export async function recordSession(opts) {
         await Promise.race([enterPromise, timeoutPromise]);
         cleanupEnter(); // Always clean up readline to prevent process from hanging
         clearInterval(pollInterval);
-        // Final drain from all known tabs
-        for (const tabId of injectedTabs) {
+        // Final drain from all known pages
+        for (const page of injectedPages) {
             try {
-                const last = await execOnTab(workspace, tabId, generateReadRecordedJs());
+                const last = await execOnPage(workspace, page, generateReadRecordedJs());
                 if (Array.isArray(last) && last.length > 0) {
                     for (const r of last)
                         allRequests.push(r);
@@ -543,25 +544,25 @@ export async function recordSession(opts) {
 async function listTabs(workspace) {
     try {
         const result = await sendCommand('tabs', { op: 'list', workspace });
-        return Array.isArray(result) ? result.filter(t => t.tabId != null) : [];
+        return Array.isArray(result) ? result.filter(t => t.page != null) : [];
     }
     catch {
         return [];
     }
 }
-async function execOnTab(workspace, tabId, code) {
-    return sendCommand('exec', { code, workspace, tabId });
+async function execOnPage(workspace, page, code) {
+    return sendCommand('exec', { code, workspace, page });
 }
-async function injectIntoTab(workspace, tabId, injectedTabs) {
+async function injectIntoPage(workspace, page, injectedPages) {
     try {
-        await execOnTab(workspace, tabId, generateFullCaptureInterceptorJs());
-        if (!injectedTabs.has(tabId)) {
-            injectedTabs.add(tabId);
-            console.log(chalk.green(`  ✓  Interceptor injected into tab:${tabId}`));
+        await execOnPage(workspace, page, generateFullCaptureInterceptorJs());
+        if (!injectedPages.has(page)) {
+            injectedPages.add(page);
+            console.log(chalk.green(`  ✓  Interceptor injected into page:${page.slice(0, 8)}`));
         }
     }
     catch {
-        // Tab not debuggable (e.g. chrome:// pages) — skip silently
+        // Page not debuggable (e.g. chrome:// pages) — skip silently
     }
 }
 /**
@@ -619,10 +620,10 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
         if (usedNames.has(entry.name))
             continue;
         usedNames.add(entry.name);
-        const filePath = path.join(candidatesDir, `${entry.name}.yaml`);
-        fs.writeFileSync(filePath, yaml.dump(entry.yaml, { sortKeys: false, lineWidth: 120 }));
+        const filePath = path.join(candidatesDir, `${entry.name}.json`);
+        fs.writeFileSync(filePath, JSON.stringify(entry.yaml, null, 2));
         candidates.push({ name: entry.name, path: filePath, strategy: entry.strategy });
-        console.log(chalk.green(`  ✓ Generated: ${chalk.bold(entry.name)}.yaml  [${entry.strategy}]`));
+        console.log(chalk.green(`  ✓ Generated: ${chalk.bold(entry.name)}.json  [${entry.strategy}]`));
         console.log(chalk.dim(`    → ${filePath}`));
     }
     if (candidates.length === 0) {

package/dist/src/runtime-detect.js

@@ -10,19 +10,15 @@
  */
 export function detectRuntime() {
     // Bun always exposes globalThis.Bun (including Bun.version)
-    if (typeof globalThis.Bun !== 'undefined')
-        return 'bun';
-    return 'node';
+    return globalThis.Bun !== undefined ? 'bun' : 'node';
 }
 /**
  * Return a human-readable version string for the current runtime.
  * Examples: "v22.13.0" (Node), "1.1.42" (Bun)
  */
 export function getRuntimeVersion() {
-    if (detectRuntime() === 'bun') {
-        return globalThis.Bun.version;
-    }
-    return process.version; // e.g. "v22.13.0"
+    const bun = globalThis.Bun;
+    return bun ? bun.version : process.version;
 }
 /**
  * Return a combined label like "node v22.13.0" or "bun 1.1.42".

package/dist/src/scripts/framework.d.ts

@@ -1,4 +1,7 @@
 /**
  * Injected script for detecting frontend frameworks (Vue, React, Next, Nuxt, etc.)
+ *
+ * Serialized via `.toString()` and evaluated in the page context. Types here are
+ * only for the TS boundary — see scripts/store.ts for the same pattern.
  */
 export declare function detectFramework(): Record<string, boolean>;

package/dist/src/scripts/framework.js

@@ -1,16 +1,20 @@
 /**
  * Injected script for detecting frontend frameworks (Vue, React, Next, Nuxt, etc.)
+ *
+ * Serialized via `.toString()` and evaluated in the page context. Types here are
+ * only for the TS boundary — see scripts/store.ts for the same pattern.
  */
 export function detectFramework() {
     const r = {};
     try {
         const app = document.querySelector('#app');
+        const w = window;
         r.vue3 = !!(app && app.__vue_app__);
         r.vue2 = !!(app && app.__vue__);
-        r.react = !!window.__REACT_DEVTOOLS_GLOBAL_HOOK__ || !!document.querySelector('[data-reactroot]');
-        r.nextjs = !!window.__NEXT_DATA__;
-        r.nuxt = !!window.__NUXT__;
-        if (r.vue3 && app.__vue_app__) {
+        r.react = !!w.__REACT_DEVTOOLS_GLOBAL_HOOK__ || !!document.querySelector('[data-reactroot]');
+        r.nextjs = !!w.__NEXT_DATA__;
+        r.nuxt = !!w.__NUXT__;
+        if (r.vue3 && app?.__vue_app__) {
             const gp = app.__vue_app__.config?.globalProperties;
             r.pinia = !!(gp && gp.$pinia);
             r.vuex = !!(gp && gp.$store);

package/dist/src/scripts/store.d.ts

@@ -1,5 +1,9 @@
 /**
- * Injected script for discovering Pinia or Vuex stores and their actions/state representations
+ * Injected script for discovering Pinia or Vuex stores and their actions/state representations.
+ *
+ * This function is serialized via `.toString()` and evaluated inside the page context,
+ * so the types below only exist at the TS boundary — the runtime shapes are whatever
+ * Pinia/Vuex put on the Vue app. We use narrow structural types for the fields we touch.
  */
 export declare function discoverStores(): {
     type: string;

package/dist/src/scripts/store.js

@@ -1,5 +1,9 @@
 /**
- * Injected script for discovering Pinia or Vuex stores and their actions/state representations
+ * Injected script for discovering Pinia or Vuex stores and their actions/state representations.
+ *
+ * This function is serialized via `.toString()` and evaluated inside the page context,
+ * so the types below only exist at the TS boundary — the runtime shapes are whatever
+ * Pinia/Vuex put on the Vue app. We use narrow structural types for the fields we touch.
  */
 export function discoverStores() {
     const stores = [];

package/dist/src/skill-generate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Generate skill: thin wrapper over generateVerifiedFromUrl.
+ *
+ * Maps GenerateOutcome → SkillOutput.
+ * Used by `opencli generate <url>` (automated path in opencli-explorer workflow).
+ *
+ * Design:
+ *   - Input: url + goal? (user intent, not execution strategy)
+ *   - Output: machine-readable decision fields + human-readable message
+ *   - Single source of truth: P1 GenerateOutcome
+ *   - No re-orchestration, no auto-escalation to browser
+ */
+import { type GenerateOutcome, type StopReason, type EscalationReason, type SuggestedAction, type Reusability } from './generate-verified.js';
+import type { IBrowserFactory } from './runtime.js';
+export interface SkillInput {
+    url: string;
+    goal?: string;
+}
+export interface SkillOutput {
+    conclusion: 'success' | 'blocked' | 'needs-human-check';
+    reason?: StopReason | EscalationReason;
+    suggested_action?: SuggestedAction;
+    reusability?: Reusability;
+    command?: string;
+    strategy?: string;
+    path?: string;
+    message: string;
+}
+export declare function mapOutcomeToSkillOutput(outcome: GenerateOutcome): SkillOutput;
+export declare function executeGenerateSkill(input: SkillInput, BrowserFactory: new () => IBrowserFactory): Promise<SkillOutput>;

package/dist/src/skill-generate.js

@@ -0,0 +1,75 @@
+/**
+ * Generate skill: thin wrapper over generateVerifiedFromUrl.
+ *
+ * Maps GenerateOutcome → SkillOutput.
+ * Used by `opencli generate <url>` (automated path in opencli-explorer workflow).
+ *
+ * Design:
+ *   - Input: url + goal? (user intent, not execution strategy)
+ *   - Output: machine-readable decision fields + human-readable message
+ *   - Single source of truth: P1 GenerateOutcome
+ *   - No re-orchestration, no auto-escalation to browser
+ */
+import { generateVerifiedFromUrl, } from './generate-verified.js';
+// ── Message Templates ────────────────────────────────────────────────────────
+const BLOCKED_MESSAGES = {
+    'no-viable-api-surface': '该站点没有发现可用的 JSON API 接口，无法自动生成 CLI',
+    'auth-too-complex': '所有接口都需要超出自动化能力的认证方式（如 signature/bearer），无法自动生成',
+    'no-viable-candidate': '发现了 API 接口，但未能合成有效的 CLI 候选',
+    'execution-environment-unavailable': '浏览器未连接，请先运行 opencli doctor 检查环境',
+};
+const ESCALATION_MESSAGES = {
+    'unsupported-required-args': () => '候选需要用户提供必填参数的示例值后重试',
+    'empty-result': () => '候选验证返回空结果，建议用 opencli-browser 检查',
+    'sparse-fields': () => '候选验证结果字段不足，建议人工检查',
+    'non-array-result': () => '返回结果不是数组格式，建议用 opencli-browser 检查接口返回结构',
+    'timeout': () => '验证超时，建议用 opencli-browser 手动检查接口响应',
+    'selector-mismatch': () => '数据路径不匹配，建议用 opencli-browser 检查实际返回结构',
+    'verify-inconclusive': (ctx) => ctx?.path
+        ? `验证结果不确定，候选已保存在 ${ctx.path}，需要人工审查`
+        : '验证结果不确定，需要人工审查',
+};
+// ── Core Mapping ─────────────────────────────────────────────────────────────
+export function mapOutcomeToSkillOutput(outcome) {
+    switch (outcome.status) {
+        case 'success':
+            return {
+                conclusion: 'success',
+                reusability: outcome.reusability ?? 'verified-artifact',
+                command: outcome.adapter?.command,
+                strategy: outcome.adapter?.strategy,
+                path: outcome.adapter?.path,
+                message: `已生成 ${outcome.adapter?.command ?? 'unknown'}，可直接使用。策略: ${outcome.adapter?.strategy ?? 'unknown'}`,
+            };
+        case 'blocked':
+            return {
+                conclusion: 'blocked',
+                reason: outcome.reason,
+                message: BLOCKED_MESSAGES[outcome.reason] ?? outcome.message ?? '生成被阻断',
+            };
+        case 'needs-human-check': {
+            const escalation = outcome.escalation;
+            const reason = escalation?.reason;
+            const candidatePath = escalation?.candidate?.path ?? undefined;
+            const messageFn = reason ? ESCALATION_MESSAGES[reason] : undefined;
+            return {
+                conclusion: 'needs-human-check',
+                reason,
+                suggested_action: escalation?.suggested_action,
+                reusability: outcome.reusability,
+                path: candidatePath ?? undefined,
+                message: outcome.message ?? messageFn?.({ path: candidatePath ?? undefined }) ?? '需要人工检查',
+            };
+        }
+    }
+}
+// ── Skill Entry Point ────────────────────────────────────────────────────────
+export async function executeGenerateSkill(input, BrowserFactory) {
+    const opts = {
+        url: input.url,
+        BrowserFactory,
+        goal: input.goal ?? null,
+    };
+    const outcome = await generateVerifiedFromUrl(opts);
+    return mapOutcomeToSkillOutput(outcome);
+}

package/dist/src/skill-generate.test.d.ts

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