@jackwener/opencli 1.7.12 → 1.7.13

package/clis/grok/utils.js

@@ -0,0 +1,326 @@
+import { htmlToMarkdown } from '@jackwener/opencli/utils';
+import { ArgumentError, AuthRequiredError } from '@jackwener/opencli/errors';
+
+export const GROK_DOMAIN = 'grok.com';
+export const GROK_URL = 'https://grok.com/';
+
+export const IS_VISIBLE_JS = `
+  const isVisible = (node) => {
+    if (!(node instanceof Element)) return false;
+    const style = window.getComputedStyle(node);
+    if (style.visibility === 'hidden' || style.display === 'none') return false;
+    const rect = node.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  };
+`;
+
+export function authRequired(detail) {
+    return new AuthRequiredError(
+        GROK_DOMAIN,
+        detail || 'Sign in to grok.com in your browser, then retry.',
+    );
+}
+
+export function normalizeBooleanFlag(value, fallback = false) {
+    if (typeof value === 'boolean') return value;
+    if (value == null || value === '') return fallback;
+    const normalized = String(value).trim().toLowerCase();
+    return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
+}
+
+// UUID v4-shape: 8-4-4-4-12 hex with dashes (the format Grok uses for /c/<id>)
+const GROK_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function parseGrokSessionId(input) {
+    const raw = String(input ?? '').trim();
+    if (!raw) {
+        throw new ArgumentError('id', 'must be a non-empty session ID or grok.com chat URL');
+    }
+    let candidate = raw;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+        let parsed;
+        try {
+            parsed = new URL(raw);
+        } catch {
+            throw new ArgumentError('id', `not a valid Grok URL (got "${input}")`);
+        }
+        const host = parsed.hostname.toLowerCase();
+        const pathMatch = parsed.pathname.match(
+            /^\/c\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/?$/i,
+        );
+        if (parsed.protocol !== 'https:' || (host !== 'grok.com' && !host.endsWith('.grok.com')) || !pathMatch) {
+            throw new ArgumentError(
+                'id',
+                `not a valid Grok conversation URL (got "${input}"); expected https://grok.com/c/<id>`,
+            );
+        }
+        candidate = pathMatch[1];
+    }
+    if (!GROK_SESSION_ID_RE.test(candidate)) {
+        throw new ArgumentError(
+            'id',
+            `not a valid Grok session ID (got "${input}"); expected a UUID like "7c4197f2-10a1-4ebb-a84a-fea89f4f1d06" or a full https://grok.com/c/<id> URL`,
+        );
+    }
+    return candidate.toLowerCase();
+}
+
+export async function isOnGrok(page) {
+    const url = await page.evaluate('window.location.href').catch(() => '');
+    if (typeof url !== 'string' || !url) return false;
+    try {
+        const hostname = new URL(url).hostname;
+        return hostname === 'grok.com' || hostname.endsWith('.grok.com');
+    } catch {
+        return false;
+    }
+}
+
+export async function ensureOnGrok(page) {
+    if (await isOnGrok(page)) return;
+    await page.goto(GROK_URL);
+    await page.wait(2);
+}
+
+export async function isLoggedIn(page) {
+    // Composer presence is the most reliable signed-in marker — when the user
+    // is signed out, grok.com renders a sign-in CTA in place of the chat
+    // composer rather than the TipTap editor.
+    const result = await page.evaluate(`(() => {
+    ${IS_VISIBLE_JS}
+    const composer = document.querySelector('.ProseMirror[contenteditable="true"]');
+    if (composer && isVisible(composer)) {
+      const signInCta = Array.from(document.querySelectorAll('button, a'))
+        .some((node) => isVisible(node) && /^(sign in|log in)$/i.test((node.textContent || '').trim()));
+      return !signInCta;
+    }
+    return false;
+  })()`);
+    return Boolean(result);
+}
+
+export async function getCurrentSessionId(page) {
+    const url = await page.evaluate('window.location.href').catch(() => '');
+    if (typeof url !== 'string') return '';
+    const match = url.match(/\/c\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+    return match ? match[1].toLowerCase() : '';
+}
+
+export async function getModelLabel(page) {
+    const result = await page.evaluate(`(() => {
+    ${IS_VISIBLE_JS}
+    const trigger = Array.from(document.querySelectorAll('button[aria-label="Model select"]'))
+      .find((node) => isVisible(node));
+    if (!trigger) return '';
+    return (trigger.innerText || trigger.textContent || '').trim().split('\\n')[0].trim();
+  })()`);
+    return typeof result === 'string' ? result : '';
+}
+
+export async function getMessageBubbles(page) {
+    // Grok marks each turn with `[data-testid="user-message"]` or
+    // `[data-testid="assistant-message"]`. Their nearest ancestor with an
+    // `id="response-<uuid>"` is a stable per-turn ID we can use for polling
+    // dedupe. The older `div.message-bubble` selector still matches but does
+    // not distinguish role on its own.
+    const result = await page.evaluate(`(() => {
+    ${IS_VISIBLE_JS}
+    const findResponseId = (node) => {
+      let parent = node.parentElement;
+      while (parent && parent !== document.body) {
+        const id = parent.getAttribute('id') || '';
+        if (id.startsWith('response-')) return id.slice('response-'.length);
+        parent = parent.parentElement;
+      }
+      return '';
+    };
+    const bubbles = Array.from(document.querySelectorAll('[data-testid="user-message"], [data-testid="assistant-message"]'))
+      .filter((node) => node instanceof HTMLElement && isVisible(node));
+    const out = [];
+    let positional = 0;
+    for (const node of bubbles) {
+      const isAssistant = node.getAttribute('data-testid') === 'assistant-message';
+      const responseId = findResponseId(node);
+      const baseId = responseId || ('pos-' + positional);
+      const id = baseId + (isAssistant ? '-assistant' : '-user');
+      positional += 1;
+      const html = node.innerHTML || '';
+      const text = (node.innerText || node.textContent || '').replace(/\\s+/g, ' ').trim();
+      out.push({ id, role: isAssistant ? 'Assistant' : 'User', text, html });
+    }
+    return out;
+  })()`);
+    if (!Array.isArray(result)) return [];
+    return result
+        .map((item) => ({
+            id: String(item?.id || ''),
+            role: item?.role === 'Assistant' ? 'Assistant' : 'User',
+            text: String(item?.text || '').trim(),
+            html: String(item?.html || ''),
+        }))
+        // User turns are always non-empty; an Assistant turn may legitimately
+        // hold only an image / non-text widget (text empty, html populated).
+        // Keep entries with either text OR html so image-only turns are not
+        // silently dropped from `read` / `detail`.
+        .filter((item) => item.id && (item.text || item.html));
+}
+
+export function bubbleHtmlToMarkdown(html) {
+    try {
+        return htmlToMarkdown(html).trim();
+    } catch {
+        return (html || '').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    }
+}
+
+export async function getHistoryFromSidebar(page, limit) {
+    const result = await page.evaluate(`(() => {
+    ${IS_VISIBLE_JS}
+    const re = /^\\/c\\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+    const seen = new Set();
+    const out = [];
+    const anchors = Array.from(document.querySelectorAll('a[href^="/c/"]'));
+    for (const a of anchors) {
+      if (!(a instanceof HTMLElement) || !isVisible(a)) continue;
+      const href = a.getAttribute('href') || '';
+      const m = href.match(re);
+      if (!m) continue;
+      const id = m[1].toLowerCase();
+      if (seen.has(id)) continue;
+      const title = (a.innerText || a.textContent || '').trim();
+      // Sidebar renders the conversation title in one anchor and a separate
+      // icon-only anchor for hover affordances. Keep the first occurrence with
+      // a non-empty title; if the icon anchor wins the DOM order, fall back to
+      // the second pass below.
+      seen.add(id);
+      out.push({ id, title });
+    }
+    // Second pass: backfill empty titles from later anchors with the same id.
+    const titleById = new Map(out.map((entry) => [entry.id, entry.title]));
+    for (const a of anchors) {
+      if (!(a instanceof HTMLElement) || !isVisible(a)) continue;
+      const href = a.getAttribute('href') || '';
+      const m = href.match(re);
+      if (!m) continue;
+      const id = m[1].toLowerCase();
+      const title = (a.innerText || a.textContent || '').trim();
+      if (title && !titleById.get(id)) {
+        titleById.set(id, title);
+      }
+    }
+    return out.map((entry) => ({ id: entry.id, title: titleById.get(entry.id) || entry.title }));
+  })()`);
+    if (!Array.isArray(result)) return [];
+    const sliced = result.slice(0, limit);
+    return sliced.map((item) => ({
+        id: String(item?.id || ''),
+        title: String(item?.title || ''),
+    }));
+}
+
+export async function startNewChat(page) {
+    // Grok's "new chat" path is just a navigation back to the homepage —
+    // there is no dedicated button in the current UI.
+    await page.goto(GROK_URL);
+    await page.wait(2);
+}
+
+export async function sendMessage(page, prompt) {
+    const promptJson = JSON.stringify(prompt);
+    return await page.evaluate(`(async () => {
+    const waitFor = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    const composerSelector = '.ProseMirror[contenteditable="true"]';
+    let composer = null;
+    for (let attempt = 0; attempt < 12; attempt += 1) {
+      const candidate = document.querySelector(composerSelector);
+      if (candidate instanceof HTMLElement) { composer = candidate; break; }
+      await waitFor(500);
+    }
+    if (!(composer instanceof HTMLElement)) {
+      return { ok: false, reason: 'Grok composer (.ProseMirror) was not found on grok.com.' };
+    }
+    const editor = composer.editor;
+    if (!editor || !editor.commands || typeof editor.commands.focus !== 'function' || typeof editor.commands.insertContent !== 'function') {
+      return { ok: false, reason: 'Grok composer editor API was unavailable (page may still be loading).' };
+    }
+    try {
+      if (typeof editor.commands.clearContent === 'function') editor.commands.clearContent();
+      editor.commands.focus();
+      editor.commands.insertContent(${promptJson});
+    } catch (error) {
+      return {
+        ok: false,
+        reason: 'Failed to insert the prompt into the Grok composer.',
+        detail: error instanceof Error ? error.message : String(error),
+      };
+    }
+    const isClickableSubmit = (node) => {
+      if (!(node instanceof HTMLButtonElement)) return false;
+      if (node.disabled) return false;
+      const style = window.getComputedStyle(node);
+      if (style.visibility === 'hidden' || style.display === 'none') return false;
+      const rect = node.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0;
+    };
+    let submit = null;
+    for (let attempt = 0; attempt < 12; attempt += 1) {
+      const candidate = Array.from(document.querySelectorAll('button[aria-label="Submit"]')).find(isClickableSubmit);
+      if (candidate instanceof HTMLButtonElement) { submit = candidate; break; }
+      await waitFor(500);
+    }
+    if (!(submit instanceof HTMLButtonElement)) {
+      return { ok: false, reason: 'Grok submit button did not reach a clickable state after prompt insertion.' };
+    }
+    submit.click();
+    return { ok: true };
+  })()`);
+}
+
+const POLL_INTERVAL_SECONDS = 2;
+const MIN_WAIT_MS = 6_000;
+const STABLE_POLLS_REQUIRED = 2;
+
+function stripNoise(text) {
+    return (text || '')
+        .replace(/\u00a0/g, ' ')
+        .trim();
+}
+
+export async function waitForAnswer(page, prompt, timeoutSeconds, baselineLastAssistantId) {
+    const startTime = Date.now();
+    let previousText = '';
+    let stableCount = 0;
+    let lastCandidate = '';
+    while (Date.now() - startTime < timeoutSeconds * 1000) {
+        await page.wait(POLL_INTERVAL_SECONDS);
+        const bubbles = await getMessageBubbles(page);
+        const lastAssistant = [...bubbles].reverse().find((b) => b.role === 'Assistant');
+        if (!lastAssistant) continue;
+        // Skip stale assistant turns from before our send: if the latest
+        // assistant ID matches the baseline, the new reply hasn't arrived yet.
+        if (baselineLastAssistantId && lastAssistant.id === baselineLastAssistantId) continue;
+        const text = stripNoise(lastAssistant.text);
+        if (!text || text === prompt.trim()) continue;
+        lastCandidate = text;
+        const waitedLongEnough = Date.now() - startTime >= MIN_WAIT_MS;
+        if (text === previousText) {
+            stableCount += 1;
+            if (waitedLongEnough && stableCount >= STABLE_POLLS_REQUIRED) {
+                return { status: 'ok', assistant: lastAssistant };
+            }
+        } else {
+            previousText = text;
+            stableCount = 0;
+        }
+    }
+    if (lastCandidate) {
+        const bubbles = await getMessageBubbles(page);
+        const lastAssistant = [...bubbles].reverse().find((b) => b.role === 'Assistant');
+        return { status: 'partial', assistant: lastAssistant };
+    }
+    return { status: 'timeout' };
+}
+
+export const __test__ = {
+    GROK_SESSION_ID_RE,
+};

package/clis/grok/utils.test.js

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { isOnGrok, normalizeBooleanFlag, parseGrokSessionId } from './utils.js';
+
+describe('grok parseGrokSessionId', () => {
+    const id = '7c4197f2-10a1-4ebb-a84a-fea89f4f1d06';
+
+    it('returns a bare UUID unchanged', () => {
+        expect(parseGrokSessionId(id)).toBe(id);
+    });
+
+    it('lowercases an upper-case ID', () => {
+        expect(parseGrokSessionId(id.toUpperCase())).toBe(id);
+    });
+
+    it('extracts the session ID from a full grok.com chat URL', () => {
+        expect(parseGrokSessionId(`https://grok.com/c/${id}`)).toBe(id);
+        expect(parseGrokSessionId(`https://grok.com/c/${id}/`)).toBe(id);
+        expect(parseGrokSessionId(`https://grok.com/c/${id}?rid=abc`)).toBe(id);
+        expect(parseGrokSessionId(`https://x.grok.com/c/${id}`)).toBe(id);
+    });
+
+    it('throws ArgumentError on empty input', () => {
+        expect(() => parseGrokSessionId('')).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(null)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(undefined)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId('   ')).toThrow(ArgumentError);
+    });
+
+    it('throws ArgumentError on non-UUID input', () => {
+        expect(() => parseGrokSessionId('not-an-id')).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId('123')).toThrow(ArgumentError);
+        // 32 hex chars (no dashes) — not the Grok UUID shape
+        expect(() => parseGrokSessionId('7c4197f210a14ebba84afea89f4f1d06')).toThrow(ArgumentError);
+        // UUID-shaped but bad hex
+        expect(() => parseGrokSessionId('zc4197f2-10a1-4ebb-a84a-fea89f4f1d06')).toThrow(ArgumentError);
+        // Bare-ID mode must not accept URL/query suffixes.
+        expect(() => parseGrokSessionId(`${id}?next=abc`)).toThrow(ArgumentError);
+        // URL with the wrong path shape must not silently fall through.
+        expect(() => parseGrokSessionId('https://grok.com/somewhere/else')).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`http://grok.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://evil.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://fakegrok.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://grok.com.evil.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://evil.com/?next=https://grok.com/c/${id}`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://grok.com/c/${id}/extra`)).toThrow(ArgumentError);
+        // URL embedding extra hex tail after the UUID must not silently truncate
+        // and open the wrong conversation.
+        expect(() => parseGrokSessionId(`https://grok.com/c/${id}0`)).toThrow(ArgumentError);
+        expect(() => parseGrokSessionId(`https://grok.com/c/${id}-extra`)).toThrow(ArgumentError);
+    });
+});
+
+describe('grok isOnGrok', () => {
+    const fakePage = (url) => ({
+        evaluate: () => url instanceof Error ? Promise.reject(url) : Promise.resolve(url),
+    });
+
+    it('returns true for grok.com URLs', async () => {
+        expect(await isOnGrok(fakePage('https://grok.com/'))).toBe(true);
+        expect(await isOnGrok(fakePage('https://grok.com/c/abc'))).toBe(true);
+    });
+
+    it('returns true for grok.com subdomains', async () => {
+        expect(await isOnGrok(fakePage('https://api.grok.com/v1'))).toBe(true);
+    });
+
+    it('returns false for non-grok domains and rejects substring matches', async () => {
+        expect(await isOnGrok(fakePage('https://fakegrok.com/'))).toBe(false);
+        expect(await isOnGrok(fakePage('https://example.com/?next=grok.com'))).toBe(false);
+        expect(await isOnGrok(fakePage('about:blank'))).toBe(false);
+    });
+
+    it('returns false when evaluate throws (detached tab)', async () => {
+        expect(await isOnGrok(fakePage(new Error('detached')))).toBe(false);
+    });
+});
+
+describe('grok normalizeBooleanFlag', () => {
+    it('passes through actual booleans', () => {
+        expect(normalizeBooleanFlag(true)).toBe(true);
+        expect(normalizeBooleanFlag(false)).toBe(false);
+    });
+
+    it('returns the fallback for null/empty input', () => {
+        expect(normalizeBooleanFlag(null)).toBe(false);
+        expect(normalizeBooleanFlag(undefined)).toBe(false);
+        expect(normalizeBooleanFlag('')).toBe(false);
+        expect(normalizeBooleanFlag(null, true)).toBe(true);
+    });
+
+    it('parses common truthy strings', () => {
+        for (const v of ['true', 'TRUE', '1', 'yes', 'on', ' Yes ']) {
+            expect(normalizeBooleanFlag(v)).toBe(true);
+        }
+    });
+
+    it('treats anything else as falsy', () => {
+        for (const v of ['no', 'off', '0', 'false', 'random']) {
+            expect(normalizeBooleanFlag(v)).toBe(false);
+        }
+    });
+});

package/clis/hf/datasets.js

@@ -0,0 +1,88 @@
+// hf datasets — list top Hugging Face datasets.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    ArgumentError,
+    CommandExecutionError,
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+
+const SORT_OPTIONS = ['downloads', 'likes', 'trending', 'created_at', 'last_modified'];
+const SORT_ALIAS = { lastmodified: 'last_modified', createdat: 'created_at' };
+
+cli({
+    site: 'hf',
+    name: 'datasets',
+    access: 'read',
+    description: 'Top Hugging Face datasets (downloads / likes / trending / freshness).',
+    domain: 'huggingface.co',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'sort', type: 'string', default: 'downloads', help: `Sort key: ${SORT_OPTIONS.join(', ')}` },
+        { name: 'search', type: 'string', required: false, help: 'Optional name/owner substring filter.' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max datasets (max 100; one API page).' },
+    ],
+    columns: ['rank', 'id', 'author', 'downloads', 'likes', 'tags', 'lastModified', 'url'],
+    func: async (args) => {
+        const sortRaw = String(args.sort ?? 'downloads').toLowerCase();
+        const sort = SORT_ALIAS[sortRaw] ?? sortRaw;
+        if (!SORT_OPTIONS.includes(sort)) {
+            throw new ArgumentError(`hf datasets sort must be one of ${SORT_OPTIONS.join(', ')}`);
+        }
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('hf datasets limit must be a positive integer');
+        }
+        if (limit > 100) {
+            throw new ArgumentError('hf datasets limit must be <= 100');
+        }
+
+        const url = new URL('https://huggingface.co/api/datasets');
+        url.searchParams.set('sort', sort);
+        url.searchParams.set('direction', '-1');
+        url.searchParams.set('limit', String(limit));
+        url.searchParams.set('full', 'true');
+        if (args.search) url.searchParams.set('search', String(args.search));
+
+        let resp;
+        try {
+            resp = await fetch(url, {
+                headers: {
+                    'Accept': 'application/json',
+                    'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)',
+                },
+            });
+        } catch (error) {
+            throw new CommandExecutionError(`hf datasets request failed: ${error?.message || error}`);
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`hf datasets failed: HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        } catch (error) {
+            throw new CommandExecutionError(`hf datasets returned malformed JSON: ${error?.message || error}`);
+        }
+        const list = Array.isArray(data) ? data : [];
+        if (list.length === 0) {
+            throw new EmptyResultError('hf datasets', 'No matching datasets on huggingface.co.');
+        }
+        return list.slice(0, limit).map((d, i) => {
+            const id = d.id || '';
+            const slashIdx = id.indexOf('/');
+            const author = slashIdx > 0 ? id.slice(0, slashIdx) : '';
+            const tags = Array.isArray(d.tags) ? d.tags.filter(t => !t.startsWith('license:')).slice(0, 10).join(', ') : '';
+            return {
+                rank: i + 1,
+                id,
+                author,
+                downloads: d.downloads ?? 0,
+                likes: d.likes ?? 0,
+                tags,
+                lastModified: d.lastModified ? String(d.lastModified).slice(0, 10) : '',
+                url: id ? `https://huggingface.co/datasets/${id}` : '',
+            };
+        });
+    },
+});

package/clis/hf/hf.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './top.js';
+import './paper.js';
+
+describe('hf adapter registry contracts', () => {
+    it('declares hf top columns so paper ids round-trip into hf paper', () => {
+        const top = getRegistry().get('hf/top');
+        const paper = getRegistry().get('hf/paper');
+
+        expect(top).toBeDefined();
+        expect(paper).toBeDefined();
+        expect(top.columns).toEqual(['rank', 'id', 'title', 'upvotes', 'authors']);
+        expect(paper.columns).toContain('id');
+    });
+});

package/clis/hf/models.js

@@ -0,0 +1,91 @@
+// hf models — list top Hugging Face models (by downloads / likes / trending).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    ArgumentError,
+    CommandExecutionError,
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+
+const SORT_OPTIONS = ['downloads', 'likes', 'trending', 'created_at', 'last_modified'];
+const SORT_ALIAS = { lastmodified: 'last_modified', createdat: 'created_at' };
+
+cli({
+    site: 'hf',
+    name: 'models',
+    access: 'read',
+    description: 'Top Hugging Face models (downloads / likes / trending / freshness).',
+    domain: 'huggingface.co',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'sort', type: 'string', default: 'downloads', help: `Sort key: ${SORT_OPTIONS.join(', ')}` },
+        { name: 'search', type: 'string', required: false, help: 'Optional name/owner substring filter (e.g. "llama", "mistralai/")' },
+        { name: 'pipeline', type: 'string', required: false, help: 'Filter by pipeline tag (e.g. text-generation, image-classification)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max models (max 100; one API page).' },
+    ],
+    columns: ['rank', 'id', 'author', 'pipelineTag', 'downloads', 'likes', 'tags', 'lastModified', 'url'],
+    func: async (args) => {
+        const sortRaw = String(args.sort ?? 'downloads').toLowerCase();
+        const sort = SORT_ALIAS[sortRaw] ?? sortRaw;
+        if (!SORT_OPTIONS.includes(sort)) {
+            throw new ArgumentError(`hf models sort must be one of ${SORT_OPTIONS.join(', ')}`);
+        }
+        const limit = Number(args.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('hf models limit must be a positive integer');
+        }
+        if (limit > 100) {
+            throw new ArgumentError('hf models limit must be <= 100');
+        }
+
+        const url = new URL('https://huggingface.co/api/models');
+        url.searchParams.set('sort', sort);
+        url.searchParams.set('direction', '-1');
+        url.searchParams.set('limit', String(limit));
+        url.searchParams.set('full', 'true');
+        if (args.search) url.searchParams.set('search', String(args.search));
+        if (args.pipeline) url.searchParams.set('pipeline_tag', String(args.pipeline));
+
+        let resp;
+        try {
+            resp = await fetch(url, {
+                headers: {
+                    'Accept': 'application/json',
+                    'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)',
+                },
+            });
+        } catch (error) {
+            throw new CommandExecutionError(`hf models request failed: ${error?.message || error}`);
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`hf models failed: HTTP ${resp.status}`);
+        }
+        let data;
+        try {
+            data = await resp.json();
+        } catch (error) {
+            throw new CommandExecutionError(`hf models returned malformed JSON: ${error?.message || error}`);
+        }
+        const list = Array.isArray(data) ? data : [];
+        if (list.length === 0) {
+            throw new EmptyResultError('hf models', 'No matching models on huggingface.co.');
+        }
+        return list.slice(0, limit).map((m, i) => {
+            const id = m.id || m.modelId || '';
+            const slashIdx = id.indexOf('/');
+            const author = slashIdx > 0 ? id.slice(0, slashIdx) : '';
+            const tags = Array.isArray(m.tags) ? m.tags.filter(t => !t.startsWith('license:')).slice(0, 10).join(', ') : '';
+            return {
+                rank: i + 1,
+                id,
+                author,
+                pipelineTag: m.pipeline_tag || m.pipelineTag || '',
+                downloads: m.downloads ?? 0,
+                likes: m.likes ?? 0,
+                tags,
+                lastModified: m.lastModified ? String(m.lastModified).slice(0, 10) : '',
+                url: id ? `https://huggingface.co/${id}` : '',
+            };
+        });
+    },
+});