@jackwener/opencli 1.7.12 → 1.7.13

package/clis/deepseek/send.js

@@ -0,0 +1,140 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import {
+    DEEPSEEK_DOMAIN,
+    MESSAGE_SELECTOR,
+    TEXTAREA_SELECTOR,
+    parseDeepSeekConversationId,
+} from './utils.js';
+
+export const sendCommand = cli({
+    site: 'deepseek',
+    name: 'send',
+    access: 'write',
+    description: 'Send a prompt to a specific DeepSeek conversation by ID, without waiting for a response',
+    domain: DEEPSEEK_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    browserSession: { reuse: 'site' },
+    navigateBefore: false,
+    args: [
+        { name: 'id', required: true, positional: true, help: 'Conversation ID (UUID) or full /a/chat/s/<id> URL' },
+        { name: 'prompt', required: true, positional: true, help: 'Prompt to send' },
+        { name: 'timeout', type: 'int', required: false, default: 60, help: 'Max seconds for the overall command (default: 60)' },
+    ],
+    columns: ['Status', 'InjectedText'],
+    func: async (page, kwargs) => {
+        const id = parseDeepSeekConversationId(kwargs.id);
+        const prompt = kwargs.prompt;
+
+        // Navigate directly to the target conversation. The framework runs
+        // each browser command in an ephemeral per-command workspace (tab),
+        // so there is no shared "current conversation" between commands; the
+        // ID must be explicit. Skipping this navigation lands on the deepseek
+        // root, where the click silently no-ops because React has not bound
+        // the textarea on a freshly-opened tab.
+        await page.goto(`https://chat.deepseek.com/a/chat/s/${id}`);
+        await waitForTextareaReady(page);
+
+        // Focus the textarea via DOM, then drive input through CDP
+        // `Input.insertText`. This mirrors the doubao adapter (#1278) and is
+        // the only reliable path for the React-controlled DeepSeek composer
+        // on a freshly-opened tab: `execCommand('insertText')` plus a
+        // synthesised input event leaves the controlled state desynced and
+        // the resulting send click silently no-ops on the server side.
+        const focusOk = await page.evaluate(`(() => {
+            const box = document.querySelector('${TEXTAREA_SELECTOR}');
+            if (!box) return false;
+            box.focus();
+            return document.activeElement === box;
+        })()`);
+        if (!focusOk) {
+            throw new CommandExecutionError('Could not focus DeepSeek textarea before native input');
+        }
+        if (typeof page.nativeType !== 'function') {
+            throw new CommandExecutionError(
+                'Native CDP input is not available on this page object',
+                'deepseek send relies on Input.insertText; ensure the daemon and extension are up to date.',
+            );
+        }
+        await page.nativeType(prompt);
+        await page.wait(0.6);
+
+        // Submit + wait inside the same eval until the user bubble has
+        // rendered AND remains stable past a 3s settle window. Returning
+        // earlier lets the framework close the per-command workspace
+        // mid-flight, aborting the in-flight chat-completion request before
+        // the server has acknowledged it; the optimistic bubble then never
+        // persists.
+        const promptJson = JSON.stringify(prompt);
+        const result = await page.evaluate(`(async () => {
+            const TEXTAREA = '${TEXTAREA_SELECTOR}';
+            const MESSAGE = '${MESSAGE_SELECTOR}';
+            const expected = ${promptJson};
+            const isUser = (m) => m.className.split(/\\s+/).length > 2;
+            const box = document.querySelector(TEXTAREA);
+            if (!box) return { ok: false, reason: 'textarea not found' };
+            if ((box.value || '').trim() !== expected.trim()) {
+                return { ok: false, reason: 'native input did not populate textarea (got ' + JSON.stringify(box.value) + ')' };
+            }
+            let container = box.parentElement;
+            while (container && !container.querySelector('div[role="button"]')) {
+                container = container.parentElement;
+            }
+            const btns = container ? container.querySelectorAll('div[role="button"]:not(.ds-toggle-button)') : [];
+            const sendBtn = btns[btns.length - 1];
+            if (!sendBtn || sendBtn.querySelectorAll('svg').length === 0) {
+                return { ok: false, reason: 'send button not found' };
+            }
+            if (sendBtn.getAttribute('aria-disabled') !== 'false') {
+                return { ok: false, reason: 'send button stayed disabled after native input' };
+            }
+            sendBtn.click();
+            // Verify the prompt rendered as a user-class bubble that includes
+            // the expected text. Counting bubbles is unreliable under DeepSeek
+            // virtualization (the visible message list is windowed); a text
+            // match on any user bubble is the authoritative signal.
+            const matchesPrompt = (m) => isUser(m) && (m.innerText || '').trim().includes(expected);
+            const findUserBubble = () => Array.from(document.querySelectorAll(MESSAGE)).reverse().find(matchesPrompt);
+            let appeared = false;
+            for (let i = 0; i < 20 && !appeared; i++) {
+                await new Promise(r => setTimeout(r, 500));
+                if (findUserBubble()) appeared = true;
+            }
+            if (!appeared) return { ok: false, reason: 'prompt never rendered as a user bubble within 10s' };
+            // Settle: must still be present after 3s; an optimistic render
+            // that gets rolled back fails this check.
+            for (let i = 0; i < 3; i++) {
+                await new Promise(r => setTimeout(r, 1000));
+                if (!findUserBubble()) {
+                    return { ok: false, reason: 'prompt rendered then disappeared during the 3s settle window' };
+                }
+            }
+            return { ok: true };
+        })()`).catch((err) => {
+            const msg = String(err?.message || err);
+            // SPA navigation after click can collapse the eval context; the
+            // resulting "Promise was collected" only fires after the bubble
+            // settle has already passed, so treat it as a successful submit.
+            if (msg.includes('Promise was collected')) return { ok: true };
+            throw err;
+        });
+
+        if (!result?.ok) {
+            throw new CommandExecutionError(result?.reason || 'Failed to send message');
+        }
+        return [{ Status: 'Success', InjectedText: prompt }];
+    },
+});
+
+/** Poll for the deepseek textarea to mount before driving any input. */
+async function waitForTextareaReady(page) {
+    const probe = `(() => !!document.querySelector('${TEXTAREA_SELECTOR}'))()`;
+    for (let attempt = 0; attempt < 10; attempt++) {
+        if (await page.evaluate(probe)) return;
+        await page.wait(1);
+    }
+    throw new CommandExecutionError(
+        'DeepSeek textarea did not mount within 10s; the conversation page may not have loaded',
+    );
+}

package/clis/deepseek/send.test.js

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+
+import './send.js';
+
+describe('deepseek send', () => {
+  const command = getRegistry().get('deepseek/send');
+  const id = '749e6bbd-6a45-4440-beaa-ae5238bf06d8';
+
+  function createPage(overrides = {}) {
+    return {
+      goto: vi.fn().mockResolvedValue(undefined),
+      wait: vi.fn().mockResolvedValue(undefined),
+      evaluate: vi.fn(),
+      nativeType: vi.fn().mockResolvedValue(undefined),
+      screenshot: vi.fn().mockResolvedValue(''),
+      ...overrides,
+    };
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('registers as a cookie-browser write command with id + prompt positional args', () => {
+    expect(command).toBeDefined();
+    expect(command.browser).toBe(true);
+    expect(command.strategy).toBe('cookie');
+    expect(command.access).toBe('write');
+    expect(command.columns).toEqual(['Status', 'InjectedText']);
+    expect(command.args.map((a) => a.name)).toEqual(['id', 'prompt', 'timeout']);
+    expect(command.args.find((a) => a.name === 'timeout')).toMatchObject({ type: 'int', default: 60 });
+  });
+
+  it('rejects malformed conversation IDs before any browser navigation', async () => {
+    const page = createPage();
+    await expect(command.func(page, { id: 'not-a-uuid', prompt: 'hi' })).rejects.toThrow(ArgumentError);
+    expect(page.goto).not.toHaveBeenCalled();
+    expect(page.nativeType).not.toHaveBeenCalled();
+  });
+
+  it('navigates to the conversation, drives input through nativeType, and verifies the bubble', async () => {
+    const page = createPage();
+    page.evaluate
+      .mockResolvedValueOnce(true)             // waitForTextareaReady probe
+      .mockResolvedValueOnce(true)             // focus check
+      .mockResolvedValueOnce({ ok: true });    // submit + verify IIFE
+
+    const rows = await command.func(page, { id, prompt: 'hello' });
+
+    expect(rows).toEqual([{ Status: 'Success', InjectedText: 'hello' }]);
+    expect(page.goto).toHaveBeenCalledWith(`https://chat.deepseek.com/a/chat/s/${id}`);
+    expect(page.nativeType).toHaveBeenCalledWith('hello');
+  });
+
+  it('throws when the textarea never mounts within the readiness timeout', async () => {
+    const page = createPage();
+    page.evaluate.mockResolvedValue(false);    // probe always fails
+
+    await expect(command.func(page, { id, prompt: 'hi' })).rejects.toThrow(CommandExecutionError);
+    expect(page.nativeType).not.toHaveBeenCalled();
+  });
+
+  it('throws when nativeType is not exposed on the page object', async () => {
+    const page = createPage({ nativeType: undefined });
+    page.evaluate
+      .mockResolvedValueOnce(true)             // waitForTextareaReady
+      .mockResolvedValueOnce(true);            // focus
+
+    await expect(command.func(page, { id, prompt: 'hi' })).rejects.toThrow(CommandExecutionError);
+  });
+
+  it('throws when the focus probe reports the textarea did not take focus', async () => {
+    const page = createPage();
+    page.evaluate
+      .mockResolvedValueOnce(true)             // waitForTextareaReady
+      .mockResolvedValueOnce(false);           // focus failed
+
+    await expect(command.func(page, { id, prompt: 'hi' })).rejects.toThrow(CommandExecutionError);
+    expect(page.nativeType).not.toHaveBeenCalled();
+  });
+
+  it('translates the IIFE failure reason into a CommandExecutionError', async () => {
+    const page = createPage();
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ ok: false, reason: 'send button stayed disabled after native input' });
+
+    await expect(command.func(page, { id, prompt: 'hi' })).rejects.toThrow(
+      new CommandExecutionError('send button stayed disabled after native input'),
+    );
+  });
+
+  it('treats "Promise was collected" from the IIFE as a successful submit', async () => {
+    const page = createPage();
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(true)
+      .mockRejectedValueOnce(new Error('{"code":-32000,"message":"Promise was collected"}'));
+
+    const rows = await command.func(page, { id, prompt: 'hi' });
+
+    expect(rows).toEqual([{ Status: 'Success', InjectedText: 'hi' }]);
+  });
+});

package/clis/deepseek/status.js

@@ -9,6 +9,7 @@ export const statusCommand = cli({
     domain: DEEPSEEK_DOMAIN,
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     navigateBefore: false,
     args: [],
     columns: ['Status', 'Login', 'Url'],

package/clis/deepseek/utils.js

@@ -1,7 +1,33 @@
+import { ArgumentError } from '@jackwener/opencli/errors';
+
 export const DEEPSEEK_DOMAIN = 'chat.deepseek.com';
 export const DEEPSEEK_URL = 'https://chat.deepseek.com/';
 export const TEXTAREA_SELECTOR = 'textarea[placeholder*="DeepSeek"]';
 export const MESSAGE_SELECTOR = '.ds-message';
+const CONVERSATION_ID_RE = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+
+/**
+ * Normalize a DeepSeek conversation ID. Accepts a bare UUID or any URL that
+ * embeds one (`/a/chat/s/<id>` or full chat URL).
+ *
+ * Throws ArgumentError when the input does not contain a UUID-shaped id, so
+ * `detail` fails before any browser navigation happens.
+ */
+export function parseDeepSeekConversationId(input) {
+    const raw = String(input ?? '').trim();
+    if (!raw) {
+        throw new ArgumentError('id', 'must be a non-empty conversation ID or URL');
+    }
+    const urlMatch = raw.match(/\/a\/chat\/s\/([a-f0-9-]+)/i);
+    const candidate = urlMatch ? urlMatch[1] : raw;
+    if (!CONVERSATION_ID_RE.test(candidate)) {
+        throw new ArgumentError(
+            'id',
+            `not a valid DeepSeek conversation ID (got "${input}"); expected a UUID like "749e6bbd-6a45-4440-beaa-ae5238bf06d8" or a full /a/chat/s/<id> URL`,
+        );
+    }
+    return candidate.toLowerCase();
+}
 
 export async function isOnDeepSeek(page) {
     const url = await page.evaluate('window.location.href').catch(() => '');
@@ -274,6 +300,46 @@ export async function getConversationList(page) {
     return [];
 }
 
+/**
+ * Pick the URL of the most recent non-pinned conversation, or the first overall
+ * if every visible conversation is pinned.
+ *
+ * Used by `ask` when the workspace was recycled and we need to resume an
+ * existing thread instead of opening a new chat. Polls the sidebar for up to
+ * 10s and returns null if no conversation links surface in time, so callers
+ * can fail fast instead of silently navigating to a fresh page.
+ *
+ * Pinned detection is text-based on the section header ("置顶" / "Pinned"),
+ * because DeepSeek's CSS-module class names are randomized per build.
+ */
+export async function pickResumeUrl(page) {
+    await page.evaluate(`(() => {
+        if (document.querySelectorAll('a[href*="/a/chat/s/"]').length === 0) {
+            const btn = document.querySelector('div[tabindex="0"][role="button"]');
+            if (btn) btn.click();
+        }
+    })()`);
+    for (let attempt = 0; attempt < 5; attempt++) {
+        await page.wait(2);
+        const url = await page.evaluate(`(() => {
+            const links = document.querySelectorAll('a[href*="/a/chat/s/"]');
+            if (links.length === 0) return null;
+            const PINNED_HEADER = /^\\s*(置\\s*顶|Pinned)\\s*$/i;
+            const isPinned = (link) => {
+                const section = link.parentElement;
+                const header = section && section.firstElementChild;
+                if (!header || header === link) return false;
+                return PINNED_HEADER.test((header.innerText || header.textContent || '').trim());
+            };
+            const target = Array.from(links).find((l) => !isPinned(l)) || links[0];
+            const href = target.getAttribute('href') || '';
+            return href ? 'https://chat.deepseek.com' + href : null;
+        })()`);
+        if (url) return url;
+    }
+    return null;
+}
+
 async function waitForFilePreview(page, fileName) {
     for (let attempt = 0; attempt < 8; attempt++) {
         await page.wait(2);

package/clis/deepseek/utils.test.js

@@ -2,7 +2,46 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { selectModel, sendWithFile, parseThinkingResponse } from './utils.js';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import {
+  selectModel,
+  sendWithFile,
+  parseThinkingResponse,
+  parseDeepSeekConversationId,
+  pickResumeUrl,
+} from './utils.js';
+
+describe('deepseek parseDeepSeekConversationId', () => {
+  const id = '749e6bbd-6a45-4440-beaa-ae5238bf06d8';
+
+  it('returns a bare UUID unchanged', () => {
+    expect(parseDeepSeekConversationId(id)).toBe(id);
+  });
+
+  it('lowercases an upper-case UUID', () => {
+    expect(parseDeepSeekConversationId(id.toUpperCase())).toBe(id);
+  });
+
+  it('extracts the UUID from a full /a/chat/s/<id> URL', () => {
+    expect(parseDeepSeekConversationId(`https://chat.deepseek.com/a/chat/s/${id}`)).toBe(id);
+    expect(parseDeepSeekConversationId(`https://chat.deepseek.com/a/chat/s/${id}?from=share`)).toBe(id);
+    expect(parseDeepSeekConversationId(`/a/chat/s/${id}`)).toBe(id);
+  });
+
+  it('throws ArgumentError on empty input', () => {
+    expect(() => parseDeepSeekConversationId('')).toThrow(ArgumentError);
+    expect(() => parseDeepSeekConversationId(null)).toThrow(ArgumentError);
+    expect(() => parseDeepSeekConversationId(undefined)).toThrow(ArgumentError);
+    expect(() => parseDeepSeekConversationId('   ')).toThrow(ArgumentError);
+  });
+
+  it('throws ArgumentError on non-UUID input', () => {
+    expect(() => parseDeepSeekConversationId('not-an-id')).toThrow(ArgumentError);
+    expect(() => parseDeepSeekConversationId('123')).toThrow(ArgumentError);
+    // URL with the wrong path shape must not silently fall through to "use raw input".
+    expect(() => parseDeepSeekConversationId('https://chat.deepseek.com/somewhere/else')).toThrow(ArgumentError);
+  });
+});
 
 describe('deepseek parseThinkingResponse', () => {
   it('returns plain response when no thinking header is present', () => {
@@ -262,3 +301,70 @@ describe('deepseek sendWithFile Not allowed fallback', () => {
     expect(page.evaluate.mock.calls[1][0]).not.toContain("aria-disabled') === 'false'");
   });
 });
+
+describe('deepseek pickResumeUrl', () => {
+  function createPage() {
+    return {
+      wait: vi.fn().mockResolvedValue(undefined),
+      evaluate: vi.fn(),
+    };
+  }
+
+  it('returns the URL on the first attempt when the sidebar is already populated', async () => {
+    const page = createPage();
+    // First evaluate is the sidebar-expand no-op; subsequent ones look up the resume URL.
+    page.evaluate
+      .mockResolvedValueOnce(undefined)
+      .mockResolvedValueOnce('https://chat.deepseek.com/a/chat/s/recent-id');
+
+    const url = await pickResumeUrl(page);
+
+    expect(url).toBe('https://chat.deepseek.com/a/chat/s/recent-id');
+    // Sidebar expand + one resume lookup. No retry needed.
+    expect(page.evaluate).toHaveBeenCalledTimes(2);
+    expect(page.wait).toHaveBeenCalledTimes(1);
+  });
+
+  it('polls until the sidebar finishes loading and returns the late URL', async () => {
+    const page = createPage();
+    page.evaluate
+      .mockResolvedValueOnce(undefined)               // sidebar-expand
+      .mockResolvedValueOnce(null)                    // attempt 1: nothing
+      .mockResolvedValueOnce(null)                    // attempt 2: nothing
+      .mockResolvedValueOnce('https://chat.deepseek.com/a/chat/s/late-id'); // attempt 3: ready
+
+    const url = await pickResumeUrl(page);
+
+    expect(url).toBe('https://chat.deepseek.com/a/chat/s/late-id');
+    expect(page.evaluate).toHaveBeenCalledTimes(4);
+    expect(page.wait).toHaveBeenCalledTimes(3);
+  });
+
+  it('returns null after exhausting all retries instead of falling through silently', async () => {
+    const page = createPage();
+    // Sidebar expand + 5 polling attempts, each returning null.
+    page.evaluate.mockResolvedValue(null);
+
+    const url = await pickResumeUrl(page);
+
+    expect(url).toBeNull();
+    expect(page.evaluate).toHaveBeenCalledTimes(6);
+    expect(page.wait).toHaveBeenCalledTimes(5);
+  });
+
+  it('embeds the pinned-section text matcher inside the resume lookup', async () => {
+    const page = createPage();
+    page.evaluate.mockResolvedValue(null);
+
+    await pickResumeUrl(page);
+
+    const lookupSrc = page.evaluate.mock.calls
+      .map(([js]) => js)
+      .find((js) => js.includes('firstElementChild'));
+    expect(lookupSrc, 'expected a resume-lookup evaluate call').toBeDefined();
+    // Pinned detection must be text-based on the section header (CSS-module class names are randomized per build).
+    expect(lookupSrc).toContain('置');
+    expect(lookupSrc).toContain('Pinned');
+    expect(lookupSrc).toContain('firstElementChild');
+  });
+});

package/clis/defillama/defillama.test.js

@@ -0,0 +1,99 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './protocols.js';
+import './protocol.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('defillama protocols adapter', () => {
+    const cmd = getRegistry().get('defillama/protocols');
+
+    it('rejects bad limit before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ limit: 0 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ limit: 1000 })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 429 to CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('rate limited', { status: 429 })));
+        await expect(cmd.func({ limit: 5 })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('throws EmptyResultError when API returns no protocols', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify([]), { status: 200 })));
+        await expect(cmd.func({ limit: 5 })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('returns rows whose slug round-trips into defillama protocol <slug>', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify([
+            { name: 'Aave V3', slug: 'aave-v3', tvl: 1000, mcap: 500, category: 'Lending', chains: ['Ethereum', 'Polygon'], change_1d: 1, change_7d: 2, listedAt: 1668170565 },
+            { name: 'Lido', slug: 'lido', tvl: 800, mcap: 200, category: 'Liquid Staking', chains: ['Ethereum'], change_1d: 0.5, change_7d: 1, listedAt: 1640000000 },
+        ]), { status: 200 })));
+
+        const rows = await cmd.func({ limit: 10 });
+        expect(rows).toHaveLength(2);
+        expect(rows[0]).toMatchObject({
+            rank: 1, slug: 'aave-v3', name: 'Aave V3', category: 'Lending', tvl: 1000,
+            chains: 'Ethereum, Polygon', url: 'https://defillama.com/protocol/aave-v3',
+        });
+        // slug is the round-trip key into defillama protocol
+        expect(rows[0].slug).toMatch(/^[a-z0-9][a-z0-9._-]*$/);
+    });
+});
+
+describe('defillama protocol adapter', () => {
+    const cmd = getRegistry().get('defillama/protocol');
+
+    it('rejects empty / malformed slug before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ slug: '' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ slug: 'BAD SLUG' })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 400 "Protocol not found" to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('Protocol not found', { status: 400 })));
+        await expect(cmd.func({ slug: 'no-such-thing' })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('parent protocols aggregate chains from children in /protocols', async () => {
+        const detail = {
+            id: 'parent#aave',
+            name: 'Aave',
+            isParentProtocol: true,
+            chains: [],
+            tvl: [{ date: 1700000000, totalLiquidityUSD: 12345 }],
+            mcap: 1e9,
+            twitter: 'aave',
+            github: ['aave'],
+            description: 'lending',
+            url: 'https://aave.com',
+        };
+        const list = [
+            { name: 'Aave V3', slug: 'aave-v3', parentProtocol: 'parent#aave', chains: ['Ethereum', 'Polygon'], category: 'Lending' },
+            { name: 'Aave V2', slug: 'aave-v2', parentProtocol: 'parent#aave', chains: ['Ethereum'], category: 'Lending' },
+            { name: 'Other', slug: 'other', chains: ['Solana'] },
+        ];
+        const fetchMock = vi.fn()
+            .mockImplementationOnce(() => Promise.resolve(new Response(JSON.stringify(detail), { status: 200 })))
+            .mockImplementationOnce(() => Promise.resolve(new Response(JSON.stringify(list), { status: 200 })));
+        vi.stubGlobal('fetch', fetchMock);
+
+        const rows = await cmd.func({ slug: 'aave' });
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toMatchObject({
+            slug: 'aave', name: 'Aave', isParent: true, tvl: 12345, tvlAt: '2023-11-14',
+        });
+        // chains should include Ethereum + Polygon (children) but not Solana (unrelated)
+        expect(rows[0].chains.split(', ').sort()).toEqual(['Ethereum', 'Polygon']);
+    });
+});

package/clis/defillama/protocol.js

@@ -0,0 +1,84 @@
+// defillama protocol — single DeFi protocol details by slug.
+//
+// Hits `https://api.llama.fi/protocol/<slug>`. The endpoint returns a rich
+// object that includes a `tvl` time-series array; we project the latest entry
+// as the current TVL plus identifying metadata (category from /protocols since
+// the per-protocol endpoint omits it).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { LLAMA_BASE, llamaFetch, requireSlug, unixToDate } from './utils.js';
+
+cli({
+    site: 'defillama',
+    name: 'protocol',
+    access: 'read',
+    description: 'Single DefiLlama protocol details (current TVL, mcap, chains, twitter, github, description)',
+    domain: 'defillama.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'slug', positional: true, type: 'string', required: true, help: 'DefiLlama protocol slug (e.g. "aave", "lido")' },
+    ],
+    columns: [
+        'slug', 'name', 'category', 'isParent', 'tvl', 'tvlAt', 'mcap',
+        'chains', 'twitter', 'github', 'audits', 'listedAt',
+        'description', 'website', 'url',
+    ],
+    func: async (args) => {
+        const slug = requireSlug(args.slug, 'slug');
+        // Per-protocol detail endpoint
+        const detail = await llamaFetch(`${LLAMA_BASE}/protocol/${encodeURIComponent(slug)}`, `defillama protocol ${slug}`);
+        if (!detail || !detail.name) {
+            throw new EmptyResultError('defillama protocol', `DefiLlama returned no metadata for "${slug}".`);
+        }
+        // Latest TVL from the time-series array (per-protocol endpoint omits a scalar tvl).
+        const tvlSeries = Array.isArray(detail.tvl) ? detail.tvl : [];
+        const lastPoint = tvlSeries.length ? tvlSeries[tvlSeries.length - 1] : null;
+        const tvl = lastPoint && Number.isFinite(Number(lastPoint.totalLiquidityUSD))
+            ? Number(lastPoint.totalLiquidityUSD)
+            : null;
+        const tvlAt = lastPoint ? unixToDate(lastPoint.date) : null;
+        // /protocols carries category + chains. Parent protocols (isParentProtocol=true)
+        // do NOT appear in /protocols themselves — only their children do — so we union
+        // child chains and leave category empty for parents.
+        const isParent = detail.isParentProtocol === true;
+        let category = '';
+        const chainsSet = new Set(Array.isArray(detail.chains) ? detail.chains : []);
+        const list = await llamaFetch(`${LLAMA_BASE}/protocols`, `defillama protocol ${slug} list lookup`);
+        if (Array.isArray(list)) {
+            if (!isParent) {
+                const match = list.find((p) => p && p.slug === slug);
+                if (match && typeof match.category === 'string') category = match.category;
+                if (match && Array.isArray(match.chains)) {
+                    for (const c of match.chains) chainsSet.add(c);
+                }
+            }
+            else {
+                // Aggregate chains across child protocols of this parent.
+                for (const p of list) {
+                    if (p && p.parentProtocol === detail.id && Array.isArray(p.chains)) {
+                        for (const c of p.chains) chainsSet.add(c);
+                    }
+                }
+            }
+        }
+        const githubArr = Array.isArray(detail.github) ? detail.github : [];
+        return [{
+            slug,
+            name: String(detail.name).trim(),
+            category,
+            isParent,
+            tvl,
+            tvlAt,
+            mcap: detail.mcap == null ? null : Number(detail.mcap),
+            chains: [...chainsSet].join(', '),
+            twitter: String(detail.twitter ?? '').trim(),
+            github: githubArr.join(', '),
+            audits: String(detail.audits ?? '').trim(),
+            listedAt: unixToDate(detail.listedAt),
+            description: String(detail.description ?? '').trim(),
+            website: String(detail.url ?? '').trim(),
+            url: `https://defillama.com/protocol/${slug}`,
+        }];
+    },
+});