@jackwener/opencli 1.7.12 → 1.7.14

package/clis/mdn/search.js

@@ -0,0 +1,97 @@
+// mdn search — search MDN Web Docs.
+//
+// Hits `https://developer.mozilla.org/api/v1/search?q=…&locale=…`. Returns a
+// row per matched doc with title, slug-derived id, summary preview, and the
+// canonical MDN URL.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const MDN_BASE = 'https://developer.mozilla.org';
+const UA = 'opencli-mdn-adapter (+https://github.com/jackwener/opencli)';
+const ALLOWED_LOCALES = new Set(['en-US', 'de', 'es', 'fr', 'ja', 'ko', 'pt-BR', 'ru', 'zh-CN', 'zh-TW']);
+
+function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`mdn ${label} cannot be empty`);
+    return s;
+}
+
+function requireBoundedInt(value, defaultValue, maxValue) {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError('mdn limit must be a positive integer');
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`mdn limit must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+function requireLocale(value) {
+    const s = String(value ?? 'en-US').trim();
+    if (!ALLOWED_LOCALES.has(s)) {
+        throw new ArgumentError(
+            `mdn locale "${value}" is not supported`,
+            `Allowed locales: ${[...ALLOWED_LOCALES].join(' / ')}`,
+        );
+    }
+    return s;
+}
+
+cli({
+    site: 'mdn',
+    name: 'search',
+    access: 'read',
+    description: 'Search MDN Web Docs by keyword',
+    domain: 'developer.mozilla.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword (e.g. "fetch", "flexbox", "Array.prototype.map")' },
+        { name: 'limit', type: 'int', default: 10, help: 'Max results (1-50)' },
+        { name: 'locale', default: 'en-US', help: 'Doc locale (en-US default; de / es / fr / ja / ko / pt-BR / ru / zh-CN / zh-TW)' },
+    ],
+    columns: ['rank', 'title', 'slug', 'locale', 'summary', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 10, 50);
+        const locale = requireLocale(args.locale);
+        const url = `${MDN_BASE}/api/v1/search?q=${encodeURIComponent(query)}&locale=${encodeURIComponent(locale)}&size=${limit}`;
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(`mdn search request failed: ${err?.message ?? err}`);
+        }
+        if (resp.status === 429) {
+            throw new CommandExecutionError(
+                'mdn search returned HTTP 429 (rate limited)',
+                'MDN throttles bursty traffic; wait a few seconds and retry.',
+            );
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`mdn search returned HTTP ${resp.status}`);
+        }
+        let body;
+        try {
+            body = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`mdn search returned malformed JSON: ${err?.message ?? err}`);
+        }
+        const docs = Array.isArray(body?.documents) ? body.documents : [];
+        if (!docs.length) {
+            throw new EmptyResultError('mdn search', `No MDN results matched "${query}" (locale ${locale}).`);
+        }
+        return docs.slice(0, limit).map((doc, i) => ({
+            rank: i + 1,
+            title: String(doc.title ?? ''),
+            slug: String(doc.slug ?? ''),
+            locale: String(doc.locale ?? locale),
+            summary: String(doc.summary ?? '').replace(/\s+/g, ' ').trim(),
+            url: doc.mdn_url ? `${MDN_BASE}${doc.mdn_url}` : '',
+        }));
+    },
+});

package/clis/medium/tag.js

@@ -0,0 +1,135 @@
+// medium tag — Medium articles for a tag, newest first, via the public
+// RSS feed at `https://medium.com/feed/tag/<tag>`.
+//
+// Complements existing `medium feed` (per-publication / per-user) and
+// `medium search` by surfacing topical streams.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/i;
+
+const HTML_ENTITIES = {
+    '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'", '&#39;': "'", '&nbsp;': ' ',
+};
+
+function decodeHtml(value) {
+    return String(value ?? '')
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+        .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(parseInt(d, 10)))
+        .replace(/&(amp|lt|gt|quot|apos|#39|nbsp);/g, (m) => HTML_ENTITIES[m] || m);
+}
+
+function extractTag(block, tag) {
+    const cdata = block.match(new RegExp(`<${tag}[^>]*>\\s*<!\\[CDATA\\[([\\s\\S]*?)\\]\\]>\\s*<\\/${tag}>`));
+    if (cdata) return cdata[1];
+    const plain = block.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`));
+    return plain ? plain[1] : '';
+}
+
+function extractCategories(block) {
+    const out = [];
+    const re = /<category(?:[^>]*)>(?:<!\[CDATA\[([\s\S]*?)\]\]>|([\s\S]*?))<\/category>/g;
+    let m;
+    while ((m = re.exec(block)) !== null) {
+        const v = decodeHtml((m[1] ?? m[2] ?? '').trim());
+        if (v) out.push(v);
+    }
+    return out;
+}
+
+function isoDateFromRfc822(value) {
+    if (!value) return '';
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) return '';
+    return d.toISOString().slice(0, 10);
+}
+
+function stripHtml(value) {
+    return decodeHtml(String(value ?? '').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim());
+}
+
+function requireTag(value) {
+    const s = String(value ?? '').trim().toLowerCase();
+    if (!s) {
+        throw new ArgumentError('medium tag is required (e.g. "programming", "javascript")');
+    }
+    if (!TAG_PATTERN.test(s)) {
+        throw new ArgumentError(
+            `medium tag "${value}" is not valid`,
+            'Tags are lowercase alphanumeric, optionally hyphenated (e.g. "machine-learning").',
+        );
+    }
+    return s;
+}
+
+function requireBoundedInt(value, defaultValue, maxValue) {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError('medium limit must be a positive integer');
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`medium limit must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+cli({
+    site: 'medium',
+    name: 'tag',
+    access: 'read',
+    description: 'Latest Medium articles tagged with a given keyword (RSS feed)',
+    domain: 'medium.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'tag', positional: true, required: true, help: 'Lowercase tag slug (e.g. "programming", "machine-learning")' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max articles (1-25 — single RSS page)' },
+    ],
+    columns: ['rank', 'title', 'author', 'description', 'categories', 'published', 'url'],
+    func: async (args) => {
+        const tag = requireTag(args.tag);
+        const limit = requireBoundedInt(args.limit, 20, 25);
+        const url = `https://medium.com/feed/tag/${tag}`;
+        let resp;
+        try {
+            resp = await fetch(url, {
+                headers: {
+                    'user-agent': 'opencli-medium-adapter (+https://github.com/jackwener/opencli)',
+                    accept: 'application/rss+xml, application/xml',
+                },
+            });
+        }
+        catch (err) {
+            throw new CommandExecutionError(
+                `medium tag request failed: ${err?.message ?? err}`,
+                'Check that medium.com is reachable from this network.',
+            );
+        }
+        if (resp.status === 404) {
+            throw new EmptyResultError('medium tag', `Medium tag "${tag}" does not exist.`);
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`medium tag returned HTTP ${resp.status}`);
+        }
+        const xml = await resp.text();
+        const items = [];
+        const re = /<item[^>]*>([\s\S]*?)<\/item>/g;
+        let m;
+        while ((m = re.exec(xml)) !== null) {
+            items.push(m[1]);
+        }
+        if (!items.length) {
+            throw new EmptyResultError('medium tag', `Medium tag "${tag}" RSS feed has no items.`);
+        }
+        return items.slice(0, limit).map((block, i) => ({
+            rank: i + 1,
+            title: decodeHtml(extractTag(block, 'title')).trim(),
+            author: decodeHtml(extractTag(block, 'dc:creator')).trim(),
+            description: stripHtml(extractTag(block, 'description')),
+            categories: extractCategories(block).join(', '),
+            published: isoDateFromRfc822(decodeHtml(extractTag(block, 'pubDate')).trim()),
+            url: decodeHtml(extractTag(block, 'link')).trim(),
+        }));
+    },
+});

package/clis/npm/downloads.js

@@ -0,0 +1,59 @@
+// npm downloads — fetch download counts for a single npm package over a window.
+//
+// Hits `api.npmjs.org/downloads/range/<period>/<pkg>`. Default window is the
+// last 7 days (one row per day). Use `--period last-month` for 30 days, or
+// pass a custom `YYYY-MM-DD:YYYY-MM-DD` range.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import { NPM_API, npmFetch, requirePackageName } from './utils.js';
+
+const FIXED_PERIODS = new Set(['last-day', 'last-week', 'last-month', 'last-year']);
+const RANGE_PATTERN = /^(\d{4}-\d{2}-\d{2}):(\d{4}-\d{2}-\d{2})$/;
+
+function requirePeriod(value) {
+    const s = String(value ?? 'last-week').trim();
+    if (FIXED_PERIODS.has(s)) return s;
+    const m = RANGE_PATTERN.exec(s);
+    if (m) {
+        const [, start, end] = m;
+        if (new Date(start) > new Date(end)) {
+            throw new ArgumentError(`npm downloads period start ${start} is after end ${end}`);
+        }
+        return `${start}:${end}`;
+    }
+    throw new ArgumentError(
+        `npm downloads period "${value}" is invalid`,
+        'Use last-day / last-week (default) / last-month / last-year, or YYYY-MM-DD:YYYY-MM-DD.',
+    );
+}
+
+cli({
+    site: 'npm',
+    name: 'downloads',
+    access: 'read',
+    description: 'Daily download counts for an npm package over a window',
+    domain: 'api.npmjs.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'npm package name (e.g. "react", "@vercel/og")' },
+        { name: 'period', default: 'last-week', help: 'last-day / last-week / last-month / last-year, or YYYY-MM-DD:YYYY-MM-DD' },
+    ],
+    columns: ['rank', 'package', 'day', 'downloads'],
+    func: async (args) => {
+        const name = requirePackageName(args.name);
+        const period = requirePeriod(args.period);
+        const url = `${NPM_API}/downloads/range/${period}/${name}`;
+        const body = await npmFetch(url, `npm downloads ${name}`);
+        const days = Array.isArray(body?.downloads) ? body.downloads : [];
+        if (!days.length) {
+            throw new EmptyResultError('npm downloads', `npm has no download stats for "${name}" in window ${period}.`);
+        }
+        return days.map((row, i) => ({
+            rank: i + 1,
+            package: String(body.package ?? name),
+            day: String(row.day ?? ''),
+            downloads: row.downloads != null ? Number(row.downloads) : null,
+        }));
+    },
+});

package/clis/npm/package.js

@@ -0,0 +1,70 @@
+// npm package — fetch a single package's registry metadata.
+//
+// Hits `https://registry.npmjs.org/<pkg>` and projects the fields most useful
+// for an agent: name, latest version, description, license, homepage,
+// repository, bug tracker, maintainers, last-modified time. Download stats
+// are intentionally separate (see `npm downloads`) so failure modes don't get
+// silently folded into a registry-metadata response.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { NPM_REGISTRY, npmFetch, requirePackageName } from './utils.js';
+
+function repoUrl(repo) {
+    if (!repo) return '';
+    if (typeof repo === 'string') return repo;
+    if (typeof repo === 'object' && typeof repo.url === 'string') {
+        return repo.url.replace(/^git\+/, '').replace(/\.git$/, '');
+    }
+    return '';
+}
+
+function bugUrl(bugs) {
+    if (!bugs) return '';
+    if (typeof bugs === 'string') return bugs;
+    if (typeof bugs === 'object' && typeof bugs.url === 'string') return bugs.url;
+    return '';
+}
+
+cli({
+    site: 'npm',
+    name: 'package',
+    access: 'read',
+    description: 'Single npm package metadata (latest version, license, homepage, repository). Use `npm downloads` for stats.',
+    domain: 'registry.npmjs.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'npm package name (e.g. "react", "@vercel/og")' },
+    ],
+    columns: [
+        'name', 'latestVersion', 'description', 'license', 'homepage', 'repository',
+        'bugs', 'maintainers', 'keywords', 'created', 'modified', 'url',
+    ],
+    func: async (args) => {
+        const name = requirePackageName(args.name);
+        const body = await npmFetch(`${NPM_REGISTRY}/${name.split('/').map(encodeURIComponent).join('/')}`, `npm package ${name}`);
+        const latest = body?.['dist-tags']?.latest;
+        if (!latest) {
+            throw new EmptyResultError('npm package', `npm registry has no latest version for "${name}".`);
+        }
+        const v = body?.versions?.[latest] ?? {};
+        const maintainers = Array.isArray(body.maintainers)
+            ? body.maintainers.map((m) => (typeof m === 'object' && m ? m.name || m.email || '' : String(m))).filter(Boolean).join(', ')
+            : '';
+        const keywords = Array.isArray(v.keywords) ? v.keywords.join(', ') : '';
+        return [{
+            name: String(body.name ?? name),
+            latestVersion: String(latest),
+            description: String(v.description ?? body.description ?? ''),
+            license: typeof v.license === 'string' ? v.license : (v.license?.type ?? ''),
+            homepage: String(v.homepage ?? ''),
+            repository: repoUrl(v.repository),
+            bugs: bugUrl(v.bugs),
+            maintainers,
+            keywords,
+            created: String(body.time?.created ?? '').slice(0, 10),
+            modified: String(body.time?.modified ?? '').slice(0, 10),
+            url: `https://www.npmjs.com/package/${name}`,
+        }];
+    },
+});

package/clis/npm/search.js

@@ -0,0 +1,49 @@
+// npm search — search the public npm registry by free-text query.
+//
+// Hits `https://registry.npmjs.org/-/v1/search?text=…`. Returns enough per-row
+// to feed back into `npm package` / `npm downloads`: name (round-trips as id),
+// description, version, weekly downloads, dependents count, license, links.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { NPM_REGISTRY, npmFetch, requireBoundedInt, requireString } from './utils.js';
+
+cli({
+    site: 'npm',
+    name: 'search',
+    access: 'read',
+    description: 'Search the public npm registry by keyword',
+    domain: 'registry.npmjs.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword (e.g. "react", "graphql client")' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max results (1-250)' },
+    ],
+    columns: ['rank', 'name', 'version', 'description', 'weeklyDownloads', 'dependents', 'license', 'publisher', 'updated', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 20, 250);
+        const url = `${NPM_REGISTRY}/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`;
+        const body = await npmFetch(url, 'npm search');
+        const objects = Array.isArray(body?.objects) ? body.objects : [];
+        if (!objects.length) {
+            throw new EmptyResultError('npm search', `No npm packages matched "${query}".`);
+        }
+        return objects.slice(0, limit).map((obj, i) => {
+            const pkg = obj?.package ?? {};
+            const dl = obj?.downloads ?? {};
+            return {
+                rank: i + 1,
+                name: String(pkg.name ?? ''),
+                version: String(pkg.version ?? ''),
+                description: String(pkg.description ?? ''),
+                weeklyDownloads: dl.weekly != null ? Number(dl.weekly) : null,
+                dependents: obj.dependents != null ? Number(obj.dependents) : null,
+                license: String(pkg.license ?? ''),
+                publisher: String(pkg.publisher?.username ?? ''),
+                updated: String(obj.updated ?? '').slice(0, 10),
+                url: pkg.links?.npm ? String(pkg.links.npm) : (pkg.name ? `https://www.npmjs.com/package/${pkg.name}` : ''),
+            };
+        });
+    },
+});

package/clis/npm/utils.js

@@ -0,0 +1,76 @@
+// Shared helpers for the npm adapters that hit the public npm registry
+// (registry.npmjs.org) and download stats API (api.npmjs.org).
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const NPM_REGISTRY = 'https://registry.npmjs.org';
+export const NPM_API = 'https://api.npmjs.org';
+const UA = 'opencli-npm-adapter (+https://github.com/jackwener/opencli)';
+
+// npm package names: 1-214 chars, lowercase letters/numbers/-._ , scoped form `@scope/name`.
+const PKG_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`npm ${label} cannot be empty`);
+    return s;
+}
+
+export function requirePackageName(value) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError('npm package name is required (e.g. "react", "@vercel/og")');
+    if (s.length > 214) {
+        throw new ArgumentError(`npm package name "${value}" is too long (max 214 chars)`);
+    }
+    if (!PKG_NAME.test(s)) {
+        throw new ArgumentError(
+            `npm package name "${value}" is not a valid registry name`,
+            'Names are 1–214 chars of lowercase a-z / 0-9 / "-._" (scoped form: "@scope/name").',
+        );
+    }
+    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(`npm ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`npm ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export async function npmFetch(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 registry.npmjs.org / api.npmjs.org are reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `npm registry returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'npm throttles unauthenticated 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;
+}

package/clis/nuget/nuget.test.js

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './search.js';
+import './package.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('nuget search adapter', () => {
+    const cmd = getRegistry().get('nuget/search');
+
+    it('rejects bad args before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(cmd.func({ query: '' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ query: 'foo', limit: 99999 })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 429 to CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('throttled', { status: 429 })));
+        await expect(cmd.func({ query: 'newtonsoft' })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('throws EmptyResultError on empty data list', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({ data: [] }), { status: 200 })));
+        await expect(cmd.func({ query: 'no-such-package' })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('round-trips package id into nuget.org URL', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            data: [{
+                id: 'Newtonsoft.Json', version: '13.0.3',
+                title: 'Json.NET', description: 'Json.NET is a popular high-performance JSON framework for .NET',
+                authors: ['James Newton-King'], tags: ['json'], totalDownloads: 1000000, verified: true,
+                projectUrl: 'https://www.newtonsoft.com/json',
+            }],
+        }), { status: 200 })));
+        const rows = await cmd.func({ query: 'json', limit: 5 });
+        expect(rows[0]).toMatchObject({
+            rank: 1, id: 'Newtonsoft.Json', version: '13.0.3', verified: true,
+            authors: 'James Newton-King', tags: 'json',
+            url: 'https://www.nuget.org/packages/Newtonsoft.Json',
+        });
+    });
+});
+
+describe('nuget package adapter', () => {
+    const cmd = getRegistry().get('nuget/package');
+
+    it('rejects malformed package ids before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(cmd.func({ id: '' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ id: 'has space' })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ id: '.starts-with-dot' })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 404 to EmptyResultError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('missing', { status: 404 })));
+        await expect(cmd.func({ id: 'No.Such.Package.1234' })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('flattens inline registration pages and sorts versions newest-first', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            items: [
+                {
+                    items: [
+                        { catalogEntry: { id: 'Newtonsoft.Json', version: '13.0.3', authors: ['JNK'], tags: ['json'], licenseExpression: 'MIT', published: '2023-03-08T20:00:00Z', listed: true } },
+                        { catalogEntry: { id: 'Newtonsoft.Json', version: '12.0.0', authors: ['JNK'], tags: ['json'], licenseExpression: 'MIT', published: '2018-01-17T20:00:00Z', listed: true } },
+                    ],
+                },
+            ],
+        }), { status: 200 })));
+        const rows = await cmd.func({ id: 'Newtonsoft.Json' });
+        expect(rows.map((r) => r.version)).toEqual(['13.0.3', '12.0.0']);
+        expect(rows[0]).toMatchObject({
+            rank: 1, id: 'Newtonsoft.Json', version: '13.0.3', authors: 'JNK', tags: 'json',
+            licenseExpression: 'MIT', listed: true,
+            url: 'https://www.nuget.org/packages/Newtonsoft.Json/13.0.3',
+        });
+    });
+
+    it('follows registration stub pages instead of silently dropping old versions', async () => {
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce(new Response(JSON.stringify({
+                items: [{ '@id': 'https://api.nuget.org/v3/registration5-semver1/newtonsoft.json/page/1.json' }],
+            }), { status: 200 }))
+            .mockResolvedValueOnce(new Response(JSON.stringify({
+                items: [
+                    { catalogEntry: { id: 'Newtonsoft.Json', version: '1.0.0', published: '2010-01-01T00:00:00Z' } },
+                    { catalogEntry: { id: 'Newtonsoft.Json', version: '2.0.0', published: '2011-01-01T00:00:00Z' } },
+                ],
+            }), { status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const rows = await cmd.func({ id: 'Newtonsoft.Json' });
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(rows.map((r) => r.version)).toEqual(['2.0.0', '1.0.0']);
+    });
+
+    it('fails fast on malformed stub pages to avoid partial version history', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({
+            items: [{ lower: '1.0.0', upper: '2.0.0' }],
+        }), { status: 200 })));
+        await expect(cmd.func({ id: 'Newtonsoft.Json' })).rejects.toThrow(CommandExecutionError);
+    });
+});