@jackwener/opencli 1.7.11 → 1.7.13

package/clis/flathub/search.js

@@ -0,0 +1,80 @@
+// flathub search — keyword search the Flathub app registry.
+//
+// POSTs to `/api/v2/search` with `{query}`. The `appId` column round-trips into
+// `flathub app` for full appstream detail. Note: the search hit's `id` is
+// underscored (e.g. `org_mozilla_firefox`); the actual reverse-DNS appId lives
+// at `app_id`. We surface the dotted form so it round-trips without translation.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    FLATHUB_API_BASE,
+    FLATHUB_APP_BASE,
+    flathubFetch,
+    joinList,
+    requireBoundedInt,
+    requireString,
+} from './utils.js';
+
+cli({
+    site: 'flathub',
+    name: 'search',
+    access: 'read',
+    description: 'Search Flathub apps by keyword',
+    domain: 'flathub.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword' },
+        { name: 'limit', type: 'int', default: 25, help: 'Max apps (1-100)' },
+    ],
+    columns: [
+        'rank',
+        'appId',
+        'name',
+        'summary',
+        'developer',
+        'license',
+        'isFreeLicense',
+        'mainCategories',
+        'installsLastMonth',
+        'updatedAt',
+        'url',
+    ],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 25, 100);
+        const url = `${FLATHUB_API_BASE}/search`;
+        const body = await flathubFetch(url, 'flathub search', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ query, hitsPerPage: limit, page: 1 }),
+        });
+        const list = Array.isArray(body?.hits) ? body.hits : [];
+        if (!list.length) {
+            throw new EmptyResultError('flathub search', `No Flathub apps matched "${query}".`);
+        }
+        return list.slice(0, limit).map((hit, i) => {
+            const appId = typeof hit?.app_id === 'string' ? hit.app_id : null;
+            return {
+                rank: i + 1,
+                appId,
+                name: typeof hit?.name === 'string' ? hit.name : null,
+                summary: typeof hit?.summary === 'string' ? hit.summary : null,
+                developer: typeof hit?.developer_name === 'string' ? hit.developer_name : null,
+                license: typeof hit?.project_license === 'string' ? hit.project_license : null,
+                isFreeLicense: hit?.is_free_license === true,
+                // `main_categories` comes back as a string (single value) on /search, not an array.
+                mainCategories: typeof hit?.main_categories === 'string'
+                    ? hit.main_categories
+                    : joinList(hit?.main_categories),
+                installsLastMonth: typeof hit?.installs_last_month === 'number' ? hit.installs_last_month : null,
+                // /search emits `updated_at` as unix-seconds int; /appstream emits ISO strings.
+                // Normalise to ISO date here so both surfaces look consistent.
+                updatedAt: typeof hit?.updated_at === 'number' && hit.updated_at > 0
+                    ? new Date(hit.updated_at * 1000).toISOString().slice(0, 10)
+                    : (typeof hit?.updated_at === 'string' ? hit.updated_at : null),
+                url: appId ? `${FLATHUB_APP_BASE}/${appId}` : '',
+            };
+        });
+    },
+});

package/clis/flathub/utils.js

@@ -0,0 +1,114 @@
+// Shared helpers for the Flathub adapters (https://flathub.org).
+//
+// Flathub is the canonical Linux flatpak app registry. Public REST API at
+// `flathub.org/api/v2`, no auth, no key. Two endpoints we surface:
+//   • POST /search      → keyword search, returns app metadata
+//   • GET  /appstream/<appId> → full appstream metadata for one app
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const FLATHUB_API_BASE = 'https://flathub.org/api/v2';
+export const FLATHUB_APP_BASE = 'https://flathub.org/apps';
+const UA = 'opencli-flathub-adapter/1.0 (+https://github.com/jackwener/opencli; mailto:opencli@example.com)';
+
+// AppStream IDs are reverse-DNS (e.g. "org.gnome.Calculator"); the spec allows
+// letters, digits, `.`, `_`, `-`. Min two segments separated by `.`.
+const APP_ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_][A-Za-z0-9_-]*){1,}$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`flathub ${label} cannot be empty`);
+    return s;
+}
+
+export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`flathub ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`flathub ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requireAppId(value) {
+    const raw = String(value ?? '').trim();
+    if (!raw) throw new ArgumentError('flathub appId is required (e.g. "org.mozilla.firefox")');
+    if (!APP_ID_PATTERN.test(raw)) {
+        throw new ArgumentError(
+            `flathub appId "${value}" is not a valid AppStream identifier`,
+            'AppStream IDs use reverse-DNS like "org.mozilla.firefox" — letters/digits/`._-` with at least one dot.',
+        );
+    }
+    return raw;
+}
+
+export async function flathubFetch(url, label, init) {
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method: init?.method ?? 'GET',
+            headers: { 'user-agent': UA, accept: 'application/json', ...(init?.headers ?? {}) },
+            body: init?.body,
+        });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that flathub.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `Flathub returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(`${label} returned HTTP 429 (rate limited)`);
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}
+
+export function joinList(value, max = 10) {
+    if (!Array.isArray(value)) return '';
+    const items = value.filter((v) => typeof v === 'string' && v.trim());
+    if (items.length === 0) return '';
+    if (items.length > max) return [...items.slice(0, max), `(+${items.length - max})`].join(', ');
+    return items.join(', ');
+}
+
+// Coerce flathub's `timestamp` field (sometimes int, sometimes numeric string).
+function timestampNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'string' && /^\d+$/.test(value.trim())) return Number(value.trim());
+    return 0;
+}
+
+/** Pick the most recent appstream `releases[].version` if present. */
+export function pickLatestRelease(releases) {
+    if (!Array.isArray(releases) || releases.length === 0) return { version: null, date: null };
+    // releases[].timestamp is unix-seconds; flathub returns either int or numeric string.
+    const sorted = [...releases].filter((r) => r && typeof r === 'object').sort((a, b) => {
+        return timestampNumber(b?.timestamp) - timestampNumber(a?.timestamp);
+    });
+    const top = sorted[0];
+    if (!top) return { version: null, date: null };
+    let date = null;
+    const ts = timestampNumber(top.timestamp);
+    if (ts > 0) {
+        const d = new Date(ts * 1000);
+        if (!Number.isNaN(d.getTime())) date = d.toISOString().slice(0, 10);
+    }
+    // Fallback: appstream emits `date` as ISO string ("2024-12-09") for some apps.
+    if (!date && typeof top.date === 'string' && top.date.trim()) date = top.date.trim();
+    return { version: typeof top.version === 'string' ? top.version : null, date };
+}

package/clis/gemini/ask.js

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
 import { GEMINI_DOMAIN, readGeminiSnapshot, sendGeminiMessage, startNewGeminiChat, waitForGeminiResponse, waitForGeminiSubmission } from './utils.js';
 function normalizeBooleanFlag(value) {
     if (typeof value === 'boolean')
@@ -10,22 +11,26 @@ const NO_RESPONSE_PREFIX = '[NO RESPONSE]';
 export const askCommand = cli({
     site: 'gemini',
     name: 'ask',
+    access: 'write',
     description: 'Send a prompt to Gemini and return only the assistant response',
     domain: GEMINI_DOMAIN,
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     navigateBefore: false,
     defaultFormat: 'plain',
-    timeoutSeconds: 180,
     args: [
         { name: 'prompt', required: true, positional: true, help: 'Prompt to send' },
-        { name: 'timeout', required: false, help: 'Max seconds to wait (default: 60)', default: '60' },
+        { name: 'timeout', type: 'int', required: false, help: 'Max seconds to wait (default: 60)', default: 60 },
         { name: 'new', required: false, help: 'Start a new chat first (true/false, default: false)', default: 'false' },
     ],
     columns: ['response'],
     func: async (page, kwargs) => {
         const prompt = kwargs.prompt;
-        const timeout = parseInt(kwargs.timeout, 10) || 60;
+        const timeout = kwargs.timeout;
+        if (!Number.isInteger(timeout) || timeout < 1) {
+            throw new ArgumentError('--timeout must be a positive integer (seconds)');
+        }
         const startFresh = normalizeBooleanFlag(kwargs.new);
         if (startFresh)
             await startNewGeminiChat(page);

package/clis/gemini/ask.test.js

@@ -79,7 +79,7 @@ describe('gemini ask orchestration', () => {
         mocks.sendGeminiMessage.mockResolvedValueOnce('button');
         mocks.waitForGeminiSubmission.mockResolvedValueOnce(submission);
         mocks.waitForGeminiResponse.mockResolvedValueOnce('OK');
-        const result = await askCommand.func(page, { prompt: '请只回复：OK', timeout: '20', new: 'false' });
+        const result = await askCommand.func(page, { prompt: '请只回复：OK', timeout: 20, new: 'false' });
         expect(mocks.readGeminiSnapshot).toHaveBeenCalledWith(page);
         expect(mocks.waitForGeminiSubmission).toHaveBeenCalledWith(page, baseline, 20);
         expect(mocks.waitForGeminiResponse).toHaveBeenCalledWith(page, submission, '请只回复：OK', 18);
@@ -94,7 +94,7 @@ describe('gemini ask orchestration', () => {
         mocks.sendGeminiMessage.mockResolvedValueOnce('button');
         mocks.waitForGeminiSubmission.mockResolvedValueOnce(submission);
         mocks.waitForGeminiResponse.mockResolvedValueOnce('');
-        await askCommand.func(page, { prompt: '请只回复：OK', timeout: '20', new: 'false' });
+        await askCommand.func(page, { prompt: '请只回复：OK', timeout: 20, new: 'false' });
         expect(mocks.waitForGeminiResponse).toHaveBeenCalledWith(page, submission, '请只回复：OK', 0);
     });
 });

package/clis/gemini/deep-research-result.js

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
 import { GEMINI_DOMAIN, clickGeminiConversationByTitle, exportGeminiDeepResearchReport, getLatestGeminiAssistantResponse, getGeminiPageState, parseGeminiConversationUrl, parseGeminiTitleMatchMode, readGeminiSnapshot, resolveGeminiConversationForQuery, waitForGeminiTranscript, getGeminiConversationList, } from './utils.js';
 const DEEP_RESEARCH_WAITING_MESSAGE = 'Deep Research is still running. Please wait and retry later.';
 const DEEP_RESEARCH_NO_DOCS_MESSAGE = 'No Docs URL found. Please check Share & Export -> Export to Docs in Gemini UI.';
@@ -38,10 +39,12 @@ async function resolveDeepResearchExportResponse(page, timeoutSeconds) {
 export const deepResearchResultCommand = cli({
     site: 'gemini',
     name: 'deep-research-result',
+    access: 'read',
     description: 'Export Deep Research report URL from a Gemini conversation',
     domain: GEMINI_DOMAIN,
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     navigateBefore: false,
     defaultFormat: 'plain',
     args: [
@@ -53,8 +56,10 @@ export const deepResearchResultCommand = cli({
     func: async (page, kwargs) => {
         const query = String(kwargs.query ?? '').trim();
         const matchMode = parseGeminiTitleMatchMode(kwargs.match);
-        const timeoutRaw = Number.parseInt(String(kwargs.timeout ?? ''), 10);
-        const timeoutSeconds = Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 120;
+        const timeoutSeconds = kwargs.timeout;
+        if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1) {
+            throw new ArgumentError('--timeout must be a positive integer (seconds)');
+        }
         if (!matchMode) {
             return [{ response: 'Invalid match mode. Use contains or exact.' }];
         }

package/clis/gemini/deep-research-result.test.js

@@ -53,52 +53,53 @@ describe('gemini/deep-research-result', () => {
             structuredTurnsTrusted: true,
         });
     });
+    const runCommand = (kwargs) => deepResearchResultCommand.func(page, { timeout: 120, ...kwargs });
     it('uses latest conversation when query is empty', async () => {
-        const result = await deepResearchResultCommand.func(page, { query: '   ' });
+        const result = await runCommand({ query: '   ' });
         expect(page.goto).toHaveBeenCalledWith('https://gemini.google.com/app/abc', { waitUntil: 'load', settleMs: 2500 });
         expect(result).toEqual([{ response: 'https://files.example.com/report.md' }]);
     });
     it('falls back to current page response when query is empty and sidebar has no conversations', async () => {
         mockGetGeminiConversationList.mockResolvedValue([]);
         mockResolveGeminiConversationForQuery.mockReturnValue(null);
-        const result = await deepResearchResultCommand.func(page, { query: '' });
+        const result = await runCommand({ query: '' });
         expect(page.goto).not.toHaveBeenCalled();
         expect(result).toEqual([{ response: 'https://files.example.com/report.md' }]);
     });
     it('returns a validation message when match mode is invalid', async () => {
-        const result = await deepResearchResultCommand.func(page, { query: 'A', match: 'prefix' });
+        const result = await runCommand({ query: 'A', match: 'prefix' });
         expect(result).toEqual([{ response: 'Invalid match mode. Use contains or exact.' }]);
     });
     it('returns a signed-out message when Gemini page state indicates logged out', async () => {
         mockGetGeminiPageState.mockResolvedValue({ isSignedIn: false });
-        const result = await deepResearchResultCommand.func(page, { query: 'A' });
+        const result = await runCommand({ query: 'A' });
         expect(result).toEqual([{ response: 'Not signed in to Gemini.' }]);
     });
     it('opens matched conversation by URL and returns exported report url', async () => {
-        const result = await deepResearchResultCommand.func(page, { query: 'A title', match: 'exact' });
+        const result = await runCommand({ query: 'A title', match: 'exact' });
         expect(page.goto).toHaveBeenCalledWith('https://gemini.google.com/app/abc', { waitUntil: 'load', settleMs: 2500 });
         expect(result).toEqual([{ response: 'https://files.example.com/report.md' }]);
     });
     it('accepts a direct conversation URL and reads response from that page', async () => {
         const url = 'https://gemini.google.com/app/direct-id';
-        const result = await deepResearchResultCommand.func(page, { query: url, match: 'contains' });
+        const result = await runCommand({ query: url, match: 'contains' });
         expect(page.goto).toHaveBeenCalledWith(url, { waitUntil: 'load', settleMs: 2500 });
         expect(result).toEqual([{ response: 'https://files.example.com/report.md' }]);
     });
     it('passes query and mode into resolveGeminiConversationForQuery', async () => {
-        const result = await deepResearchResultCommand.func(page, { query: 'title', match: 'contains' });
+        const result = await runCommand({ query: 'title', match: 'contains' });
         expect(mockResolveGeminiConversationForQuery).toHaveBeenCalledWith([{ Title: 'A title', Url: 'https://gemini.google.com/app/abc' }], 'title', 'contains');
         expect(result).toEqual([{ response: 'https://files.example.com/report.md' }]);
     });
     it('falls back to click-by-title and returns not-found when click fails', async () => {
         mockResolveGeminiConversationForQuery.mockReturnValue(null);
         mockClickGeminiConversationByTitle.mockResolvedValue(false);
-        const result = await deepResearchResultCommand.func(page, { query: 'missing', match: 'contains' });
+        const result = await runCommand({ query: 'missing', match: 'contains' });
         expect(result).toEqual([{ response: 'No conversation matched: missing' }]);
     });
     it('returns pending message when export url is unavailable and completion is not confirmed', async () => {
         mockExportGeminiDeepResearchReport.mockResolvedValue({ url: '', source: 'none' });
-        const result = await deepResearchResultCommand.func(page, { query: 'A title' });
+        const result = await runCommand({ query: 'A title' });
         expect(result).toEqual([{ response: 'Deep Research may still be running or preparing export. Please wait and retry later.' }]);
     });
     it('returns waiting message when deep research is still generating', async () => {
@@ -110,13 +111,13 @@ describe('gemini/deep-research-result', () => {
             isGenerating: true,
             structuredTurnsTrusted: true,
         });
-        const result = await deepResearchResultCommand.func(page, { query: 'A title' });
+        const result = await runCommand({ query: 'A title' });
         expect(result).toEqual([{ response: 'Deep Research is still running. Please wait and retry later.' }]);
     });
     it('returns waiting message when assistant response indicates research in progress', async () => {
         mockExportGeminiDeepResearchReport.mockResolvedValue({ url: '', source: 'none' });
         mockGetLatestGeminiAssistantResponse.mockResolvedValue('正在研究中，请稍候。');
-        const result = await deepResearchResultCommand.func(page, { query: 'A title' });
+        const result = await runCommand({ query: 'A title' });
         expect(result).toEqual([{ response: 'Deep Research is still running. Please wait and retry later.' }]);
     });
     it('returns waiting message when transcript indicates in-progress status', async () => {
@@ -129,7 +130,7 @@ describe('gemini/deep-research-result', () => {
             isGenerating: false,
             structuredTurnsTrusted: true,
         });
-        const result = await deepResearchResultCommand.func(page, { query: 'A title' });
+        const result = await runCommand({ query: 'A title' });
         expect(result).toEqual([{ response: 'Deep Research is still running. Please wait and retry later.' }]);
     });
     it('returns no-docs message when text indicates completed state', async () => {
@@ -142,13 +143,13 @@ describe('gemini/deep-research-result', () => {
             isGenerating: false,
             structuredTurnsTrusted: true,
         });
-        const result = await deepResearchResultCommand.func(page, { query: 'A title' });
+        const result = await runCommand({ query: 'A title' });
         expect(result).toEqual([{ response: 'No Docs URL found. Please check Share & Export -> Export to Docs in Gemini UI.' }]);
     });
     it('returns pending message when assistant response is empty', async () => {
         mockExportGeminiDeepResearchReport.mockResolvedValue({ url: '', source: 'none' });
         mockGetLatestGeminiAssistantResponse.mockResolvedValue('');
-        const result = await deepResearchResultCommand.func(page, { query: 'A title' });
+        const result = await runCommand({ query: 'A title' });
         expect(result).toEqual([{ response: 'Deep Research may still be running or preparing export. Please wait and retry later.' }]);
     });
 });

package/clis/gemini/deep-research.js

@@ -1,5 +1,6 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { GEMINI_DEEP_RESEARCH_DEFAULT_CONFIRM_LABELS, GEMINI_DEEP_RESEARCH_DEFAULT_TOOL_LABELS, GEMINI_APP_URL, GEMINI_DOMAIN, getCurrentGeminiUrl, getLatestGeminiAssistantResponse, parseGeminiPositiveInt, readGeminiSnapshot, resolveGeminiLabels, selectGeminiTool, sendGeminiMessage, startNewGeminiChat, waitForGeminiSubmission, waitForGeminiConfirmButton, } from './utils.js';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { GEMINI_DEEP_RESEARCH_DEFAULT_CONFIRM_LABELS, GEMINI_DEEP_RESEARCH_DEFAULT_TOOL_LABELS, GEMINI_APP_URL, GEMINI_DOMAIN, getCurrentGeminiUrl, getLatestGeminiAssistantResponse, readGeminiSnapshot, resolveGeminiLabels, selectGeminiTool, sendGeminiMessage, startNewGeminiChat, waitForGeminiSubmission, waitForGeminiConfirmButton, } from './utils.js';
 function isGeminiRootAppUrl(url) {
     try {
         const parsed = new URL(url);
@@ -17,23 +18,27 @@ function parseDeepResearchProgress(text) {
 export const deepResearchCommand = cli({
     site: 'gemini',
     name: 'deep-research',
+    access: 'write',
     description: 'Start a Gemini Deep Research run and confirm it',
     domain: GEMINI_DOMAIN,
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     navigateBefore: false,
     defaultFormat: 'plain',
-    timeoutSeconds: 180,
     args: [
         { name: 'prompt', positional: true, required: true, help: 'Prompt to send' },
-        { name: 'timeout', type: 'int', required: false, help: 'Max seconds to wait for confirm (default: 30)', default: 30 },
+        { name: 'timeout', type: 'int', required: false, help: 'Max seconds for the overall command (default: 180; confirm-wait clamps internally to 6-20s)', default: 180 },
         { name: 'tool', required: false, help: 'Override tool label (default: Deep Research)' },
         { name: 'confirm', required: false, help: 'Override confirm button label (default: Start research)' },
     ],
     columns: ['status', 'url'],
     func: async (page, kwargs) => {
         const prompt = kwargs.prompt;
-        const timeout = parseGeminiPositiveInt(kwargs.timeout, 30);
+        const timeout = kwargs.timeout;
+        if (!Number.isInteger(timeout) || timeout < 1) {
+            throw new ArgumentError('--timeout must be a positive integer (seconds)');
+        }
         const submitTimeout = Math.min(Math.max(timeout, 6), 20);
         await startNewGeminiChat(page);
         const toolLabels = resolveGeminiLabels(kwargs.tool, GEMINI_DEEP_RESEARCH_DEFAULT_TOOL_LABELS);

package/clis/gemini/deep-research.test.js

@@ -28,10 +28,6 @@ vi.mock('./utils.js', () => ({
         '\u751f\u6210\u7814\u7a76\u8ba1\u5212',
         '\u751f\u6210\u8c03\u7814\u8ba1\u5212',
     ],
-    parseGeminiPositiveInt: (value, fallback) => {
-        const parsed = Number.parseInt(String(value ?? ''), 10);
-        return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-    },
     resolveGeminiLabels: (value, fallback) => {
         const label = String(value ?? '').trim();
         return label ? [label] : fallback;
@@ -48,6 +44,7 @@ vi.mock('./utils.js', () => ({
 import { deepResearchCommand } from './deep-research.js';
 describe('gemini/deep-research', () => {
     const page = {};
+    const runCommand = (kwargs) => deepResearchCommand.func(page, { timeout: 180, ...kwargs });
     beforeEach(() => {
         vi.clearAllMocks();
         mockGetCurrentGeminiUrl.mockResolvedValue('https://gemini.google.com/app/chat');
@@ -71,17 +68,17 @@ describe('gemini/deep-research', () => {
         mockGetLatestGeminiAssistantResponse.mockResolvedValue('');
     });
     it('starts a new chat by default, then sends prompt and confirms deep research', async () => {
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic' });
+        const result = await runCommand({ prompt: 'research this topic' });
         expect(mockStartNewGeminiChat).toHaveBeenCalledTimes(1);
         expect(mockSelectGeminiTool).toHaveBeenCalledTimes(1);
         expect(mockSendGeminiMessage).toHaveBeenCalledWith(page, 'research this topic');
         expect(mockWaitForGeminiSubmission).toHaveBeenCalledTimes(1);
-        expect(mockWaitForGeminiConfirmButton).toHaveBeenCalledWith(page, expect.arrayContaining(['Start research', 'Start deep research', 'Generate research plan', '\u751f\u6210\u7814\u7a76\u8ba1\u5212']), 30);
+        expect(mockWaitForGeminiConfirmButton).toHaveBeenCalledWith(page, expect.arrayContaining(['Start research', 'Start deep research', 'Generate research plan', '\u751f\u6210\u7814\u7a76\u8ba1\u5212']), 180);
         expect(result).toEqual([{ status: 'started', url: 'https://gemini.google.com/app/chat' }]);
     });
     it('returns tool-not-found when the tool cannot be selected', async () => {
         mockSelectGeminiTool.mockResolvedValue('');
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic' });
+        const result = await runCommand({ prompt: 'research this topic' });
         expect(result).toEqual([{ status: 'tool-not-found', url: 'https://gemini.google.com/app/chat' }]);
         expect(mockSendGeminiMessage).not.toHaveBeenCalled();
         expect(mockWaitForGeminiSubmission).not.toHaveBeenCalled();
@@ -94,7 +91,7 @@ describe('gemini/deep-research', () => {
             userAnchorTurn: null,
             reason: 'user_turn',
         });
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic' });
+        const result = await runCommand({ prompt: 'research this topic' });
         expect(mockSelectGeminiTool).toHaveBeenCalledTimes(2);
         expect(mockReadGeminiSnapshot).toHaveBeenCalledTimes(2);
         expect(mockSendGeminiMessage).toHaveBeenCalledTimes(2);
@@ -103,7 +100,7 @@ describe('gemini/deep-research', () => {
     });
     it('returns submit-not-found when submission cannot be confirmed after retry', async () => {
         mockWaitForGeminiSubmission.mockResolvedValue(null);
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic' });
+        const result = await runCommand({ prompt: 'research this topic' });
         expect(mockSelectGeminiTool).toHaveBeenCalledTimes(2);
         expect(mockSendGeminiMessage).toHaveBeenCalledTimes(2);
         expect(mockWaitForGeminiConfirmButton).not.toHaveBeenCalled();
@@ -111,27 +108,27 @@ describe('gemini/deep-research', () => {
     });
     it('returns confirm-not-found when no confirm button is found', async () => {
         mockWaitForGeminiConfirmButton.mockResolvedValue('');
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic' });
+        const result = await runCommand({ prompt: 'research this topic' });
         expect(result).toEqual([{ status: 'confirm-not-found', url: 'https://gemini.google.com/app/chat' }]);
     });
     it('returns started when confirm is missing but research appears to be running', async () => {
         mockWaitForGeminiConfirmButton.mockResolvedValue('');
         mockGetCurrentGeminiUrl.mockResolvedValue('https://gemini.google.com/app/abc123');
         mockGetLatestGeminiAssistantResponse.mockResolvedValue('Researching websites now');
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic' });
+        const result = await runCommand({ prompt: 'research this topic' });
         expect(result).toEqual([{ status: 'started', url: 'https://gemini.google.com/app/abc123' }]);
     });
     it('does not treat conversation url alone as started when confirm is missing', async () => {
         mockWaitForGeminiConfirmButton.mockResolvedValue('');
         mockGetCurrentGeminiUrl.mockResolvedValue('https://gemini.google.com/app/abc999');
         mockGetLatestGeminiAssistantResponse.mockResolvedValue('I drafted a plan. Start research');
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic' });
+        const result = await runCommand({ prompt: 'research this topic' });
         expect(result).toEqual([{ status: 'confirm-not-found', url: 'https://gemini.google.com/app/abc999' }]);
     });
     it('retries once when stuck on root app URL and starts successfully on second confirm', async () => {
         mockWaitForGeminiConfirmButton.mockResolvedValueOnce('').mockResolvedValueOnce('Start research');
         mockGetCurrentGeminiUrl.mockResolvedValueOnce('https://gemini.google.com/app').mockResolvedValueOnce('https://gemini.google.com/app/retry123');
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic', timeout: '20' });
+        const result = await runCommand({ prompt: 'research this topic', timeout: 20 });
         expect(mockSelectGeminiTool).toHaveBeenCalledTimes(2);
         expect(mockSendGeminiMessage).toHaveBeenCalledTimes(1);
         expect(mockWaitForGeminiConfirmButton).toHaveBeenCalledTimes(2);
@@ -140,7 +137,7 @@ describe('gemini/deep-research', () => {
     it('treats root-url confirm as false-positive and retries', async () => {
         mockWaitForGeminiConfirmButton.mockResolvedValueOnce('Start research').mockResolvedValueOnce('Start research');
         mockGetCurrentGeminiUrl.mockResolvedValueOnce('https://gemini.google.com/app').mockResolvedValueOnce('https://gemini.google.com/app/retry456');
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic', timeout: '20' });
+        const result = await runCommand({ prompt: 'research this topic', timeout: 20 });
         expect(mockSelectGeminiTool).toHaveBeenCalledTimes(2);
         expect(mockSendGeminiMessage).toHaveBeenCalledTimes(1);
         expect(result).toEqual([{ status: 'started', url: 'https://gemini.google.com/app/retry456' }]);
@@ -149,7 +146,7 @@ describe('gemini/deep-research', () => {
         mockWaitForGeminiConfirmButton.mockResolvedValueOnce('Start research').mockResolvedValueOnce('');
         mockGetCurrentGeminiUrl.mockResolvedValueOnce('https://gemini.google.com/app').mockResolvedValueOnce('https://gemini.google.com/app');
         mockGetLatestGeminiAssistantResponse.mockResolvedValue('');
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic', timeout: '20' });
+        const result = await runCommand({ prompt: 'research this topic', timeout: 20 });
         expect(mockSelectGeminiTool).toHaveBeenCalledTimes(2);
         expect(mockSendGeminiMessage).toHaveBeenCalledTimes(1);
         expect(mockWaitForGeminiConfirmButton).toHaveBeenCalledTimes(2);
@@ -165,18 +162,18 @@ describe('gemini/deep-research', () => {
         mockGetLatestGeminiAssistantResponse
             .mockResolvedValueOnce('I drafted a plan. Start research')
             .mockResolvedValueOnce('Researching websites now');
-        const result = await deepResearchCommand.func(page, { prompt: 'research this topic', timeout: '20' });
+        const result = await runCommand({ prompt: 'research this topic', timeout: 20 });
         expect(mockWaitForGeminiConfirmButton).toHaveBeenCalledTimes(2);
         expect(mockWaitForGeminiConfirmButton).toHaveBeenNthCalledWith(2, page, expect.arrayContaining(['Start research', 'Start deep research', '开始研究', '开始深度研究']), 8);
         expect(mockSendGeminiMessage).toHaveBeenCalledTimes(1);
         expect(result).toEqual([{ status: 'started', url: 'https://gemini.google.com/app/xyz123' }]);
     });
     it('uses custom tool/confirm labels when provided', async () => {
-        await deepResearchCommand.func(page, {
+        await runCommand({
             prompt: 'research this topic',
             tool: 'Custom Tool',
             confirm: 'Custom Confirm',
-            timeout: '42',
+            timeout: 42,
         });
         expect(mockSelectGeminiTool).toHaveBeenCalledWith(page, ['Custom Tool']);
         expect(mockWaitForGeminiConfirmButton).toHaveBeenCalledWith(page, ['Custom Confirm'], 42);

package/clis/gemini/image.js

@@ -2,6 +2,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { saveBase64ToFile } from '@jackwener/opencli/utils';
+import { ArgumentError } from '@jackwener/opencli/errors';
 import { GEMINI_DOMAIN, exportGeminiImages, getGeminiVisibleImageUrls, sendGeminiMessage, startNewGeminiChat, waitForGeminiImages } from './utils.js';
 function extFromMime(mime) {
     if (mime.includes('png'))
@@ -46,19 +47,21 @@ async function currentGeminiLink(page) {
 export const imageCommand = cli({
     site: 'gemini',
     name: 'image',
+    access: 'write',
     description: 'Generate images with Gemini web and save them locally',
     domain: GEMINI_DOMAIN,
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     navigateBefore: false,
     defaultFormat: 'plain',
-    timeoutSeconds: 240,
     args: [
         { name: 'prompt', positional: true, required: true, help: 'Image prompt to send to Gemini' },
         { name: 'rt', default: '1:1', help: 'Ratio shorthand for aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3)' },
         { name: 'st', default: '', help: 'Style shorthand, e.g. anime, icon, watercolor' },
         { name: 'op', default: '~/tmp/gemini-images', help: 'Output directory shorthand' },
         { name: 'sd', type: 'boolean', default: false, help: 'Skip download shorthand; only show Gemini page link' },
+        { name: 'timeout', type: 'int', required: false, default: 240, help: 'Max seconds for the overall command (default: 240)' },
     ],
     columns: ['status', 'file', 'link'],
     func: async (page, kwargs) => {
@@ -66,7 +69,10 @@ export const imageCommand = cli({
         const ratio = normalizeRatio(String(kwargs.rt ?? '1:1'));
         const style = String(kwargs.st ?? '').trim();
         const outputDir = kwargs.op || path.join(os.homedir(), 'tmp', 'gemini-images');
-        const timeout = 120;
+        const timeout = kwargs.timeout;
+        if (!Number.isInteger(timeout) || timeout < 1) {
+            throw new ArgumentError('--timeout must be a positive integer (seconds)');
+        }
         const startFresh = true;
         const skipDownloadRaw = kwargs.sd;
         const skipDownload = skipDownloadRaw === '' || skipDownloadRaw === true || normalizeBooleanFlag(skipDownloadRaw);

package/clis/gemini/new.js

@@ -3,10 +3,12 @@ import { GEMINI_DOMAIN, startNewGeminiChat } from './utils.js';
 export const newCommand = cli({
     site: 'gemini',
     name: 'new',
+    access: 'read',
     description: 'Start a new conversation in Gemini web chat',
     domain: GEMINI_DOMAIN,
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     navigateBefore: false,
     args: [],
     columns: ['Status', 'Action'],

package/clis/gemini/utils.js

@@ -78,10 +78,6 @@ export function resolveGeminiLabels(value, fallback) {
     const label = String(value ?? '').trim();
     return label ? [label] : fallback;
 }
-export function parseGeminiPositiveInt(value, fallback) {
-    const parsed = Number.parseInt(String(value ?? ''), 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-}
 export function parseGeminiTitleMatchMode(value, fallback = 'contains') {
     const raw = String(value ?? fallback).trim().toLowerCase();
     if (raw === 'contains' || raw === 'exact')

package/clis/gitee/search.js

@@ -64,6 +64,7 @@ function normalizeUrl(value) {
 cli({
     site: 'gitee',
     name: 'search',
+    access: 'read',
     description: 'Search repositories on Gitee',
     domain: 'gitee.com',
     strategy: Strategy.PUBLIC,