@jackwener/opencli 1.7.12 → 1.7.14

package/clis/reuters/utils.js

@@ -0,0 +1,159 @@
+/**
+ * Shared helpers for the reuters adapter.
+ */
+import { ArgumentError } from '@jackwener/opencli/errors';
+
+const MIN_LIMIT = 1;
+const MAX_LIMIT = 40;
+
+export function parseLimit(raw, fallback = 10) {
+    if (raw === undefined || raw === null || raw === '') return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+        throw new ArgumentError(`--limit must be an integer between ${MIN_LIMIT} and ${MAX_LIMIT}, got ${JSON.stringify(raw)}`);
+    }
+    if (parsed < MIN_LIMIT || parsed > MAX_LIMIT) {
+        throw new ArgumentError(`--limit must be between ${MIN_LIMIT} and ${MAX_LIMIT}, got ${parsed}`);
+    }
+    return parsed;
+}
+
+/**
+ * Build the in-page IIFE that fetches the Reuters search API.
+ *
+ * Returns a raw envelope `{ ok, status, body, error? }` so that error-handling
+ * lives in node space (not silently swallowed by `catch(e) {}` inside the
+ * browser).
+ */
+export function buildSearchScript(query, count) {
+    return `
+    (async () => {
+      const apiQuery = JSON.stringify({
+        keyword: ${JSON.stringify(query)},
+        offset: 0,
+        orderby: 'display_date:desc',
+        size: ${count},
+        website: 'reuters'
+      });
+      const apiUrl = 'https://www.reuters.com/pf/api/v3/content/fetch/articles-by-search-v2?query=' + encodeURIComponent(apiQuery);
+      try {
+        const resp = await fetch(apiUrl, { credentials: 'include' });
+        const status = resp.status;
+        const statusText = resp.statusText || '';
+        const text = await resp.text();
+        let body = null;
+        let parseError = null;
+        if ((text || '').trim()) {
+          try { body = JSON.parse(text); } catch (e) { parseError = String((e && e.message) || e); }
+        }
+        return { ok: resp.ok, status, statusText, body, parseError, textPreview: (text || '').slice(0, 500) };
+      } catch (e) {
+        return { ok: false, status: 0, body: null, error: String((e && e.message) || e) };
+      }
+    })()
+  `;
+}
+
+/**
+ * In-page IIFE that walks the Reuters article page DOM and surfaces
+ * canonical metadata + body text. Returns a raw `{ ok, body, error? }`
+ * envelope so node-side handling can throw typed errors.
+ */
+export function buildArticleDetailScript() {
+    return `
+    (() => {
+      try {
+        const pageText = document.body ? (document.body.innerText || '') : '';
+        const authRequired = ${looksAuthWallText.toString()}([
+          window.location.href || '',
+          document.title || '',
+          pageText.slice(0, 4000),
+        ].join('\\n')) || Boolean(document.querySelector('[data-testid*="paywall" i], [class*="paywall" i], [id*="paywall" i], [data-testid*="captcha" i], [class*="captcha" i]'));
+        const meta = document.getElementById('fusion-metadata');
+        let fusion = null;
+        if (meta) {
+          try { fusion = JSON.parse(meta.textContent || '{}'); } catch (e) { fusion = null; }
+        }
+        const article = fusion?.globalContent || null;
+        const paragraphs = Array.from(document.querySelectorAll('article [data-testid^="paragraph-"], article p'))
+          .map((p) => (p.textContent || '').trim())
+          .filter(Boolean);
+        const bodyText = paragraphs.length ? paragraphs.join('\\n\\n') : ((document.querySelector('article')?.innerText || '').trim() || null);
+        return { ok: true, authRequired, body: { article, bodyText } };
+      } catch (e) {
+        return { ok: false, error: String((e && e.message) || e) };
+      }
+    })()
+  `;
+}
+
+export function isAuthStatus(status) {
+    return Number(status) === 401 || Number(status) === 403;
+}
+
+export function looksAuthWallText(value) {
+    const text = String(value ?? '').toLowerCase();
+    return /datadome|captcha|verify you are human|human verification|access to this page has been denied|unusual traffic|subscribe to continue|subscription required|sign in to (continue|read|access)|log in to (continue|read|access)/.test(text);
+}
+
+function pickAuthors(a) {
+    if (!Array.isArray(a)) return null;
+    const names = a
+        .map((au) => (typeof au === 'string' ? au : au?.name || au?.byline || ''))
+        .map((s) => String(s).trim())
+        .filter(Boolean);
+    return names.length ? names.join(', ') : null;
+}
+
+function trimOrNull(v) {
+    const s = String(v ?? '').trim();
+    return s ? s : null;
+}
+
+function dateOnly(v) {
+    const s = String(v ?? '').trim();
+    if (!s) return null;
+    return s.split('T')[0];
+}
+
+function articleUrl(canonical) {
+    if (!canonical) return null;
+    const c = String(canonical);
+    if (/^https?:\/\//i.test(c)) return c;
+    return 'https://www.reuters.com' + c;
+}
+
+export function mapSearchArticles(body, limit) {
+    const articles = body?.result?.articles || body?.articles || [];
+    if (!Array.isArray(articles)) return [];
+    return articles
+        .filter((a) => a && typeof a === 'object')
+        .slice(0, limit)
+        .map((a, i) => ({
+            rank: i + 1,
+            title: trimOrNull(a.title || a.headlines?.basic),
+            date: dateOnly(a.display_date || a.published_time),
+            section: trimOrNull(a.taxonomy?.section?.name),
+            section_path: trimOrNull(a.taxonomy?.section?.path),
+            authors: pickAuthors(a.authors),
+            url: articleUrl(a.canonical_url),
+        }))
+        .filter((row) => row.title && row.url);
+}
+
+export function mapArticleDetail(article, bodyText, fallbackUrl = null) {
+    if (!article && !bodyText) return null;
+    return {
+        title: trimOrNull(article?.title || article?.headlines?.basic),
+        date: dateOnly(article?.display_date || article?.published_time),
+        section: trimOrNull(article?.taxonomy?.section?.name),
+        section_path: trimOrNull(article?.taxonomy?.section?.path),
+        authors: pickAuthors(article?.authors),
+        description: trimOrNull(article?.description?.basic || article?.subheadlines?.basic),
+        word_count: Number.isFinite(article?.word_count) ? article.word_count : null,
+        url: articleUrl(article?.canonical_url) || trimOrNull(fallbackUrl),
+        body: trimOrNull(bodyText),
+    };
+}
+
+export const __test__ = { MIN_LIMIT, MAX_LIMIT };

package/clis/rfc/rfc.js

@@ -0,0 +1,52 @@
+// rfc rfc — fetch a single IETF RFC's metadata.
+//
+// Hits `https://datatracker.ietf.org/doc/rfc<N>/doc.json` and projects the
+// agent-useful fields: title, abstract (full text — RFCs don't truncate well),
+// page count, working group, authors, std level, publish date, plus rendered URLs.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { RFC_BASE, requireRfcNumber, rfcFetch, trimDate } from './utils.js';
+
+cli({
+    site: 'rfc',
+    name: 'rfc',
+    access: 'read',
+    description: 'Single IETF RFC metadata (title, abstract, working group, authors, std level)',
+    domain: 'datatracker.ietf.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'number', positional: true, type: 'int', required: true, help: 'RFC number (e.g. 9000, 791, 2616)' },
+    ],
+    columns: [
+        'rfc', 'title', 'state', 'stdLevel', 'group', 'groupType',
+        'pages', 'published', 'authors', 'abstract', 'rfcEditorUrl', 'url',
+    ],
+    func: async (args) => {
+        const number = requireRfcNumber(args.number);
+        const name = `rfc${number}`;
+        const doc = await rfcFetch(`${RFC_BASE}/doc/${name}/doc.json`, `rfc ${number}`);
+        if (!doc || !doc.name) {
+            throw new EmptyResultError('rfc rfc', `IETF datatracker returned no metadata for RFC ${number}.`);
+        }
+        const authors = Array.isArray(doc.authors)
+            ? doc.authors.map((a) => String(a?.name ?? '').trim()).filter(Boolean).join(', ')
+            : '';
+        const groupName = String(doc.group?.name ?? '').trim();
+        const groupType = String(doc.group?.type ?? '').trim();
+        return [{
+            rfc: number,
+            title: String(doc.title ?? '').trim(),
+            state: String(doc.state ?? '').trim(),
+            stdLevel: String(doc.std_level ?? '').trim(),
+            group: groupName,
+            groupType,
+            pages: doc.pages == null ? null : Number(doc.pages),
+            published: trimDate(doc.time),
+            authors,
+            abstract: String(doc.abstract ?? '').trim(),
+            rfcEditorUrl: `https://www.rfc-editor.org/rfc/rfc${number}`,
+            url: `${RFC_BASE}/doc/${name}/`,
+        }];
+    },
+});

package/clis/rfc/rfc.test.js

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './rfc.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('rfc rfc adapter', () => {
+    const cmd = getRegistry().get('rfc/rfc');
+
+    it('rejects malformed RFC numbers before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ number: 'abc' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ number: 0 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ number: -5 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ number: 1000000 })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 404 to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('not found', { status: 404 })));
+        await expect(cmd.func({ number: 999998 })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('maps HTTP 429 to CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('rate limited', { status: 429 })));
+        await expect(cmd.func({ number: 9000 })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('flattens authors + group, normalises space-separated date, and emits rfcEditorUrl', async () => {
+        const doc = {
+            name: 'rfc9000',
+            title: 'QUIC: A UDP-Based Multiplexed and Secure Transport',
+            state: 'Published',
+            std_level: 'Proposed Standard',
+            group: { name: 'QUIC', type: 'WG' },
+            pages: 151,
+            time: '2022-02-19 08:46:51',
+            authors: [
+                { name: 'Jana Iyengar', email: 'jri@example' },
+                { name: 'Martin Thomson', email: 'mt@example' },
+            ],
+            abstract: 'This document defines QUIC.',
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(doc), { status: 200 })));
+
+        const rows = await cmd.func({ number: 9000 });
+        expect(rows[0]).toMatchObject({
+            rfc: 9000,
+            title: 'QUIC: A UDP-Based Multiplexed and Secure Transport',
+            stdLevel: 'Proposed Standard',
+            group: 'QUIC',
+            groupType: 'WG',
+            pages: 151,
+            published: '2022-02-19',
+            authors: 'Jana Iyengar, Martin Thomson',
+            rfcEditorUrl: 'https://www.rfc-editor.org/rfc/rfc9000',
+            url: 'https://datatracker.ietf.org/doc/rfc9000/',
+        });
+    });
+
+    it('accepts "rfc<N>" prefix as a courtesy', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            name: 'rfc791', title: 'Internet Protocol', authors: [], group: {},
+        }), { status: 200 })));
+        const rows = await cmd.func({ number: 'rfc791' });
+        expect(rows[0].rfc).toBe(791);
+    });
+});

package/clis/rfc/utils.js

@@ -0,0 +1,72 @@
+// Shared helpers for the IETF RFC adapter.
+//
+// datatracker.ietf.org publishes a free, unauthenticated REST API. The
+// `/doc/<name>/doc.json` endpoint returns rich metadata for any IETF document
+// (RFCs, internet drafts, etc.). Docs: https://datatracker.ietf.org/api/
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const RFC_BASE = 'https://datatracker.ietf.org';
+const UA = 'opencli-rfc-adapter (+https://github.com/jackwener/opencli)';
+
+export function requireRfcNumber(value) {
+    const raw = value;
+    if (raw == null || String(raw).trim() === '') {
+        throw new ArgumentError(
+            'rfc number is required (e.g. 9000, 791, 2616)',
+            'Pass the integer RFC number; do not include the "rfc" prefix.',
+        );
+    }
+    // Accept "9000" or 9000 or "rfc9000" as a courtesy.
+    const s = String(raw).trim().toLowerCase().replace(/^rfc/, '');
+    const n = Number.parseInt(s, 10);
+    if (!Number.isInteger(n) || n <= 0 || String(n) !== s) {
+        throw new ArgumentError(
+            `rfc number "${value}" is not a valid RFC number`,
+            'Pass a positive integer (e.g. 9000, 791, 2616).',
+        );
+    }
+    if (n > 999999) {
+        throw new ArgumentError('rfc number must be <= 999999');
+    }
+    return n;
+}
+
+export async function rfcFetch(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that datatracker.ietf.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `IETF datatracker 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;
+}
+
+// IETF datatracker timestamps are like "2022-02-19 08:46:51" (no T, no Z)
+// or ISO with offset like "2016-07-08T21:03:52+00:00". Normalise to YYYY-MM-DD.
+export function trimDate(value) {
+    const s = String(value ?? '').trim();
+    if (!s) return null;
+    // Take the first 10 chars only if they form a YYYY-MM-DD prefix.
+    if (/^\d{4}-\d{2}-\d{2}/.test(s)) return s.slice(0, 10);
+    return null;
+}

package/clis/rubygems/gem.js

@@ -0,0 +1,42 @@
+// rubygems gem — fetch a single gem's metadata from RubyGems.org.
+//
+// Hits `https://rubygems.org/api/v1/gems/<name>.json`. Returns a one-row
+// projection: latest version + release date, lifetime / version downloads,
+// license(s), author(s), homepage, source, bug tracker, short info.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { GEMS_BASE, gemsFetch, requireGemName, trimDate } from './utils.js';
+
+cli({
+    site: 'rubygems',
+    name: 'gem',
+    access: 'read',
+    description: 'Fetch a RubyGems.org gem\'s metadata (version, downloads, license, links)',
+    domain: 'rubygems.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'Gem name (e.g. "rails", "sidekiq")' },
+    ],
+    columns: ['gem', 'version', 'releasedAt', 'downloads', 'versionDownloads', 'license', 'authors', 'homepage', 'source', 'bugs', 'info', 'url'],
+    func: async (args) => {
+        const name = requireGemName(args.name);
+        const url = `${GEMS_BASE}/gems/${encodeURIComponent(name)}.json`;
+        const body = await gemsFetch(url, 'rubygems gem');
+        const licenses = Array.isArray(body?.licenses) ? body.licenses.filter(Boolean).join(', ') : '';
+        const meta = body?.metadata ?? {};
+        return [{
+            gem: String(body?.name ?? name).trim(),
+            version: String(body?.version ?? '').trim(),
+            releasedAt: trimDate(body?.version_created_at),
+            downloads: body?.downloads != null ? Number(body.downloads) : null,
+            versionDownloads: body?.version_downloads != null ? Number(body.version_downloads) : null,
+            license: licenses,
+            authors: String(body?.authors ?? '').trim(),
+            homepage: String(body?.homepage_uri ?? '').trim(),
+            source: String(body?.source_code_uri ?? meta.source_code_uri ?? '').trim(),
+            bugs: String(body?.bug_tracker_uri ?? meta.bug_tracker_uri ?? '').trim(),
+            info: String(body?.info ?? '').trim(),
+            url: String(body?.project_uri ?? `https://rubygems.org/gems/${name}`).trim(),
+        }];
+    },
+});

package/clis/rubygems/search.js

@@ -0,0 +1,47 @@
+// rubygems search — search the RubyGems.org public index.
+//
+// Hits `https://rubygems.org/api/v1/search.json?query=…&page=1`. Returns an
+// agent-useful projection: gem name (round-trips into `rubygems gem`), latest
+// version, lifetime downloads, license(s), author(s), short info, project URL.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { GEMS_BASE, gemsFetch, requireBoundedInt, requireString } from './utils.js';
+
+cli({
+    site: 'rubygems',
+    name: 'search',
+    access: 'read',
+    description: 'Search RubyGems.org gems by keyword',
+    domain: 'rubygems.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword (e.g. "rails", "redis")' },
+        { name: 'limit', type: 'int', default: 30, help: 'Max gems (1-100, single RubyGems page)' },
+    ],
+    columns: ['rank', 'gem', 'version', 'downloads', 'license', 'authors', 'info', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 30, 100);
+        const url = `${GEMS_BASE}/search.json?query=${encodeURIComponent(query)}&page=1`;
+        const body = await gemsFetch(url, 'rubygems search');
+        const list = Array.isArray(body) ? body : [];
+        if (!list.length) {
+            throw new EmptyResultError('rubygems search', `No gems matched "${query}".`);
+        }
+        return list.slice(0, limit).map((g, i) => {
+            const name = String(g.name ?? '').trim();
+            const licenses = Array.isArray(g.licenses) ? g.licenses.filter(Boolean).join(', ') : '';
+            return {
+                rank: i + 1,
+                gem: name,
+                version: String(g.version ?? '').trim(),
+                downloads: g.downloads != null ? Number(g.downloads) : null,
+                license: licenses,
+                authors: String(g.authors ?? '').trim(),
+                info: String(g.info ?? '').trim(),
+                url: name ? `https://rubygems.org/gems/${name}` : '',
+            };
+        });
+    },
+});

package/clis/rubygems/utils.js

@@ -0,0 +1,86 @@
+// Shared helpers for the RubyGems.org adapters.
+//
+// Hits the public, unauthenticated `rubygems.org/api/v1` REST endpoints. No
+// auth required for read-only metadata; the API is friendly to anonymous CLI
+// traffic. Gem names follow the RubyGems convention: lowercase ASCII +
+// `-_.`, 1-100 chars, must start with a letter or digit.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const GEMS_BASE = 'https://rubygems.org/api/v1';
+const UA = 'opencli-rubygems-adapter (+https://github.com/jackwener/opencli)';
+
+// RubyGems gem name pattern (mirrors the rubygems-server validation).
+const GEM_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`rubygems ${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(`rubygems ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`rubygems ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requireGemName(value) {
+    const s = String(value ?? '').trim();
+    if (!s) {
+        throw new ArgumentError('rubygems gem name is required (e.g. "rails", "sidekiq")');
+    }
+    if (s.length > 100 || !GEM_NAME.test(s)) {
+        throw new ArgumentError(
+            `rubygems gem "${value}" is not a valid gem name`,
+            'Use letters / digits / "._-", starting with a letter or digit (max 100 chars).',
+        );
+    }
+    return s;
+}
+
+export async function gemsFetch(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that rubygems.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `RubyGems returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'RubyGems throttles bursts; wait a few seconds and retry.',
+        );
+    }
+    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;
+}
+
+/** Trim "2026-03-24T20:27:42.098Z" → "2026-03-24T20:27:42Z" so timestamps share a uniform precision. */
+export function trimDate(value) {
+    const s = String(value ?? '').trim();
+    if (!s) return null;
+    const noFrac = s.replace(/\.\d+/, '');
+    return noFrac.endsWith('Z') ? noFrac : `${noFrac}Z`;
+}

package/clis/stackoverflow/related.js

@@ -0,0 +1,66 @@
+// stackoverflow related — find Stack Overflow questions related to a given question id.
+//
+// Hits the public `/questions/{id}/related` endpoint. Useful for follow-up
+// research from a single SO question — agents can read one question with
+// `stackoverflow read`, then expand the search to related/duplicate threads
+// without rerunning a free-text search.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import {
+    seFetch,
+    normalizeLimit,
+    epochToDate,
+    ensureItems,
+    decodeHtmlEntities,
+} from './utils.js';
+
+const SORT_OPTIONS = ['rank', 'activity', 'votes', 'creation'];
+
+cli({
+    site: 'stackoverflow',
+    name: 'related',
+    access: 'read',
+    description: 'List Stack Overflow questions related to a given question id.',
+    domain: 'stackoverflow.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, type: 'string', help: 'Stack Overflow question id (numeric, e.g. 79935770).' },
+        { name: 'sort', type: 'string', default: 'rank', help: `Sort key: ${SORT_OPTIONS.join(', ')} (rank = SO relevance default).` },
+        { name: 'limit', type: 'int', default: 20, help: 'Max related questions (1-100).' },
+    ],
+    columns: ['rank', 'id', 'title', 'score', 'answers', 'views', 'isAnswered', 'tags', 'author', 'createdAt', 'lastActivityAt', 'url'],
+    func: async (args) => {
+        const id = String(args.id ?? '').trim();
+        if (!/^\d+$/.test(id)) {
+            throw new ArgumentError(`stackoverflow related id must be a numeric question id, got ${JSON.stringify(args.id)}`);
+        }
+        const sort = String(args.sort ?? 'rank').toLowerCase();
+        if (!SORT_OPTIONS.includes(sort)) {
+            throw new ArgumentError(`stackoverflow related sort must be one of ${SORT_OPTIONS.join(', ')}`);
+        }
+        const limit = normalizeLimit(args.limit, 20, 100, 'limit');
+        const data = await seFetch(`/questions/${encodeURIComponent(id)}/related`, {
+            searchParams: {
+                order: 'desc',
+                sort,
+                pagesize: limit,
+            },
+        });
+        const items = ensureItems(data, `stackoverflow related ${id}`);
+        return items.slice(0, limit).map((q, i) => ({
+            rank: i + 1,
+            id: q.question_id,
+            title: decodeHtmlEntities(q.title || ''),
+            score: q.score ?? 0,
+            answers: q.answer_count ?? 0,
+            views: q.view_count ?? 0,
+            isAnswered: Boolean(q.is_answered),
+            tags: Array.isArray(q.tags) ? q.tags.join(', ') : '',
+            author: decodeHtmlEntities(q.owner?.display_name || ''),
+            createdAt: epochToDate(q.creation_date),
+            lastActivityAt: epochToDate(q.last_activity_date),
+            url: q.link || (q.question_id ? `https://stackoverflow.com/questions/${q.question_id}` : ''),
+        }));
+    },
+});

package/clis/stackoverflow/stackoverflow.test.js

@@ -6,6 +6,8 @@ import './search.js';
 import './unanswered.js';
 import './bounties.js';
 import './read.js';
+import './tag.js';
+import './user.js';
 
 afterEach(() => {
     vi.unstubAllGlobals();
@@ -63,6 +65,62 @@ describe('stackoverflow listing adapters surface question_id/tags/views/owner',
             bounty: '${{ item.bounty_amount }}',
         });
     });
+
+    it('stackoverflow/tag exposes id so rows round-trip into read <id>', async () => {
+        const cmd = getRegistry().get('stackoverflow/tag');
+        expect(cmd?.columns).toEqual([
+            'rank', 'id', 'title', 'score', 'answers', 'views',
+            'isAnswered', 'tags', 'author', 'createdAt', 'lastActivityAt', 'url',
+        ]);
+
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
+            new Response(JSON.stringify({
+                items: [{
+                    question_id: 123,
+                    title: 'Rust &amp; async',
+                    score: 5,
+                    answer_count: 2,
+                    view_count: 100,
+                    is_answered: true,
+                    tags: ['rust', 'async'],
+                    owner: { display_name: 'Ferris&#39;s friend' },
+                    creation_date: 1700000000,
+                    last_activity_date: 1700003600,
+                    link: 'https://stackoverflow.com/questions/123/rust-async',
+                }],
+            }), { status: 200 }),
+        ));
+
+        const rows = await cmd.func({ tag: 'rust', sort: 'activity', limit: 1 });
+
+        expect(rows).toEqual([expect.objectContaining({
+            id: 123,
+            title: 'Rust & async',
+            author: "Ferris's friend",
+            url: 'https://stackoverflow.com/questions/123/rust-async',
+        })]);
+        expect(rows[0]).not.toHaveProperty('questionId');
+    });
+
+    it('stackoverflow/tag rejects bad sort and limit before fetching', async () => {
+        const cmd = getRegistry().get('stackoverflow/tag');
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ tag: 'rust', sort: 'invalid', limit: 1 }))
+            .rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ tag: 'rust', sort: 'activity', limit: 101 }))
+            .rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('stackoverflow/user exposes userId profile rows without pretending they feed read <id>', async () => {
+        const cmd = getRegistry().get('stackoverflow/user');
+        expect(cmd?.columns).toEqual([
+            'userId', 'displayName', 'reputation', 'goldBadges', 'silverBadges',
+            'bronzeBadges', 'location', 'createdAt', 'lastAccessAt', 'url',
+        ]);
+    });
 });
 
 describe('stackoverflow/read adapter', () => {