@jackwener/opencli 1.7.11 → 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/hackernews/ask.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'hackernews',
     name: 'ask',
+    access: 'read',
     description: 'Hacker News Ask HN posts',
     domain: 'news.ycombinator.com',
     strategy: Strategy.PUBLIC,
@@ -9,7 +10,7 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
     ],
-    columns: ['rank', 'title', 'score', 'author', 'comments'],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
     pipeline: [
         { fetch: { url: 'https://hacker-news.firebaseio.com/v0/askstories.json' } },
         { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
@@ -18,6 +19,7 @@ cli({
         { filter: 'item.title && !item.deleted && !item.dead' },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
                 title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 author: '${{ item.by }}',

package/clis/hackernews/best.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'hackernews',
     name: 'best',
+    access: 'read',
     description: 'Hacker News best stories',
     domain: 'news.ycombinator.com',
     strategy: Strategy.PUBLIC,
@@ -9,7 +10,7 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
     ],
-    columns: ['rank', 'title', 'score', 'author', 'comments'],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
     pipeline: [
         { fetch: { url: 'https://hacker-news.firebaseio.com/v0/beststories.json' } },
         { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
@@ -18,6 +19,7 @@ cli({
         { filter: 'item.title && !item.deleted && !item.dead' },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
                 title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 author: '${{ item.by }}',

package/clis/hackernews/hackernews.test.js

@@ -0,0 +1,132 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import './top.js';
+import './best.js';
+import './ask.js';
+import './new.js';
+import './show.js';
+import './jobs.js';
+import './search.js';
+import './read.js';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('hackernews listing adapters expose item id', () => {
+  const storyCommands = ['hackernews/top', 'hackernews/best', 'hackernews/ask', 'hackernews/new', 'hackernews/show'];
+
+  storyCommands.forEach((key) => {
+    it(`${key} surfaces id alongside title/score/author/comments/url`, () => {
+      const cmd = getRegistry().get(key);
+      expect(cmd?.columns).toEqual(['rank', 'id', 'title', 'score', 'author', 'comments', 'url']);
+      expect(cmd?.pipeline?.[5]?.map).toMatchObject({
+        id: '${{ item.id }}',
+        url: '${{ item.url }}',
+      });
+    });
+  });
+
+  it('hackernews/jobs surfaces id alongside title/author/url', () => {
+    const cmd = getRegistry().get('hackernews/jobs');
+    expect(cmd?.columns).toEqual(['rank', 'id', 'title', 'author', 'url']);
+    expect(cmd?.pipeline?.[5]?.map).toMatchObject({
+      id: '${{ item.id }}',
+      url: '${{ item.url }}',
+    });
+  });
+
+  it('hackernews/search surfaces id (algolia objectID) alongside the existing columns', () => {
+    const cmd = getRegistry().get('hackernews/search');
+    expect(cmd?.columns).toEqual(['rank', 'id', 'title', 'score', 'author', 'comments', 'url']);
+    expect(cmd?.pipeline?.[2]?.map).toMatchObject({
+      id: '${{ item.objectID }}',
+    });
+  });
+});
+
+describe('hackernews/read adapter', () => {
+  const cmd = getRegistry().get('hackernews/read');
+
+  it('registers the comment-thread shape (type/author/score/text)', () => {
+    expect(cmd?.columns).toEqual(['type', 'author', 'score', 'text']);
+  });
+
+  it('takes a positional id plus tunable depth/limit/replies/max-length args', () => {
+    const argNames = (cmd?.args || []).map((a) => a.name);
+    expect(argNames).toEqual(['id', 'limit', 'depth', 'replies', 'max-length']);
+    const idArg = cmd?.args?.find((a) => a.name === 'id');
+    expect(idArg?.required).toBe(true);
+    expect(idArg?.positional).toBe(true);
+  });
+
+  it('uses the public Firebase API (no browser, public strategy)', () => {
+    expect(cmd?.browser).toBe(false);
+    expect(cmd?.strategy).toBe('public');
+  });
+
+  it('fails fast with ArgumentError for non-numeric ids before hitting fetch', async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(cmd.func({ id: 'abc', limit: 5, depth: 2, replies: 5, 'max-length': 2000 })).rejects.toThrow(ArgumentError);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('fails fast with EmptyResultError when the story is missing', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(null), { status: 200 })));
+
+    await expect(cmd.func({ id: '99999999', limit: 5, depth: 2, replies: 5, 'max-length': 2000 })).rejects.toThrow(EmptyResultError);
+  });
+
+  it('renders story body, anchor text, and hidden-replies stubs from the public API tree', async () => {
+    const items = new Map([
+      ['123', {
+        id: 123,
+        type: 'story',
+        by: 'pg',
+        score: 42,
+        title: 'Ask HN: Example',
+        text: '<p>Hello <a href=\"https://example.com\">world</a></p>',
+        url: 'https://news.ycombinator.com/item?id=123',
+        kids: [456],
+      }],
+      ['456', {
+        id: 456,
+        type: 'comment',
+        by: 'sama',
+        text: '<p>Top level</p>',
+        kids: [789],
+      }],
+    ]);
+    vi.stubGlobal('fetch', vi.fn(async (url) => {
+      const id = String(url).match(/item\/(\d+)\.json$/)?.[1];
+      return new Response(JSON.stringify(items.get(id) ?? null), { status: 200 });
+    }));
+
+    const rows = await cmd.func({ id: '123', limit: 5, depth: 1, replies: 5, 'max-length': 2000 });
+
+    expect(rows).toEqual([
+      {
+        type: 'POST',
+        author: 'pg',
+        score: 42,
+        text: 'Ask HN: Example\nHello world (https://example.com)\nhttps://news.ycombinator.com/item?id=123',
+      },
+      {
+        type: 'L0',
+        author: 'sama',
+        score: '',
+        text: 'Top level',
+      },
+      {
+        type: 'L1',
+        author: '',
+        score: '',
+        text: '  [+1 more replies]',
+      },
+    ]);
+  });
+});

package/clis/hackernews/jobs.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'hackernews',
     name: 'jobs',
+    access: 'read',
     description: 'Hacker News job postings',
     domain: 'news.ycombinator.com',
     strategy: Strategy.PUBLIC,
@@ -9,7 +10,7 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of job postings' },
     ],
-    columns: ['rank', 'title', 'author', 'url'],
+    columns: ['rank', 'id', 'title', 'author', 'url'],
     pipeline: [
         { fetch: { url: 'https://hacker-news.firebaseio.com/v0/jobstories.json' } },
         { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
@@ -18,6 +19,7 @@ cli({
         { filter: 'item.title && !item.deleted && !item.dead' },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
                 title: '${{ item.title }}',
                 author: '${{ item.by }}',
                 url: '${{ item.url }}',

package/clis/hackernews/new.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'hackernews',
     name: 'new',
+    access: 'read',
     description: 'Hacker News newest stories',
     domain: 'news.ycombinator.com',
     strategy: Strategy.PUBLIC,
@@ -9,7 +10,7 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
     ],
-    columns: ['rank', 'title', 'score', 'author', 'comments'],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
     pipeline: [
         { fetch: { url: 'https://hacker-news.firebaseio.com/v0/newstories.json' } },
         { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
@@ -18,6 +19,7 @@ cli({
         { filter: 'item.title && !item.deleted && !item.dead' },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
                 title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 author: '${{ item.by }}',