@jackwener/opencli 1.7.11 → 1.7.13

package/clis/nowcoder/jobs.js

@@ -3,6 +3,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'jobs',
+    access: 'read',
     description: 'Career category listing',
     domain: 'www.nowcoder.com',
     strategy: Strategy.PUBLIC,

package/clis/nowcoder/notifications.js

@@ -3,6 +3,7 @@ import { cli } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'notifications',
+    access: 'read',
     description: 'Unread message summary',
     domain: 'www.nowcoder.com',
     args: [],

package/clis/nowcoder/papers.js

@@ -3,6 +3,7 @@ import { cli } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'papers',
+    access: 'read',
     description: 'Interview question bank by company and job',
     domain: 'www.nowcoder.com',
     args: [

package/clis/nowcoder/practice.js

@@ -3,6 +3,7 @@ import { cli } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'practice',
+    access: 'read',
     description: 'Categorized practice questions with progress',
     domain: 'www.nowcoder.com',
     args: [

package/clis/nowcoder/recommend.js

@@ -3,6 +3,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'recommend',
+    access: 'read',
     description: 'Recommended feed',
     domain: 'www.nowcoder.com',
     strategy: Strategy.PUBLIC,

package/clis/nowcoder/referral.js

@@ -3,6 +3,7 @@ import { cli } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'referral',
+    access: 'read',
     description: 'Internal referral posts',
     domain: 'www.nowcoder.com',
     args: [

package/clis/nowcoder/salary.js

@@ -3,6 +3,7 @@ import { cli } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'salary',
+    access: 'read',
     description: 'Salary disclosure posts',
     domain: 'www.nowcoder.com',
     args: [

package/clis/nowcoder/search.js

@@ -3,6 +3,7 @@ import { cli } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'search',
+    access: 'read',
     description: 'Full-text search',
     domain: 'www.nowcoder.com',
     args: [

package/clis/nowcoder/suggest.js

@@ -3,6 +3,7 @@ import { cli } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'suggest',
+    access: 'read',
     description: 'Search suggestions',
     domain: 'www.nowcoder.com',
     args: [

package/clis/nowcoder/topics.js

@@ -3,6 +3,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'topics',
+    access: 'read',
     description: 'Hot discussion topics',
     domain: 'www.nowcoder.com',
     strategy: Strategy.PUBLIC,

package/clis/nowcoder/trending.js

@@ -3,6 +3,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'nowcoder',
     name: 'trending',
+    access: 'read',
     description: 'Trending posts',
     domain: 'www.nowcoder.com',
     strategy: Strategy.PUBLIC,

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);
+    });
+});

package/clis/nuget/package.js

@@ -0,0 +1,101 @@
+// nuget package — full version history for a NuGet package id.
+//
+// Hits the registration index `api.nuget.org/v3/registration5-semver1/<id>/index.json`.
+// The id path segment must be lowercase per NuGet's CDN routing.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { NUGET_REGISTRATION_BASE, joinAuthors, joinTags, nugetFetch, requirePackageId } from './utils.js';
+
+cli({
+    site: 'nuget',
+    name: 'package',
+    access: 'read',
+    description: 'Full NuGet package version history (catalogEntry per release)',
+    domain: 'api.nuget.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'NuGet package id (e.g. "Newtonsoft.Json", case-insensitive)' },
+    ],
+    columns: [
+        'rank',
+        'id',
+        'version',
+        'title',
+        'authors',
+        'tags',
+        'language',
+        'licenseExpression',
+        'projectUrl',
+        'published',
+        'listed',
+        'url',
+    ],
+    func: async (args) => {
+        const id = requirePackageId(args.id);
+        const url = `${NUGET_REGISTRATION_BASE}/${encodeURIComponent(id.toLowerCase())}/index.json`;
+        const body = await nugetFetch(url, 'nuget package');
+        const pages = Array.isArray(body?.items) ? body.items : [];
+        // Each page can be inline (with `items`) or a stub that needs another fetch
+        // for older packages. Inline is the common case for everything published in
+        // the last few years. We follow stub pages once each — at most ~5 round-trips.
+        const allEntries = [];
+        for (const [pageIndex, page] of pages.entries()) {
+            let pageItems = Array.isArray(page?.items) ? page.items : null;
+            if (!pageItems) {
+                // Stub page → fetch the leaf.
+                const pageUrl = typeof page?.['@id'] === 'string' ? page['@id'] : null;
+                if (!pageUrl) {
+                    throw new CommandExecutionError(
+                        `nuget package registration page ${pageIndex + 1} is missing @id for package "${id}"`,
+                    );
+                }
+                const leaf = await nugetFetch(pageUrl, 'nuget package page');
+                if (!Array.isArray(leaf?.items)) {
+                    throw new CommandExecutionError(
+                        `nuget package registration leaf ${pageUrl} did not include an items array`,
+                    );
+                }
+                pageItems = leaf.items;
+            }
+            for (const it of pageItems) {
+                if (!it || typeof it !== 'object' || !it.catalogEntry || typeof it.catalogEntry !== 'object') {
+                    throw new CommandExecutionError(
+                        `nuget package registration page ${pageIndex + 1} contains a malformed version entry`,
+                    );
+                }
+                allEntries.push(it);
+            }
+        }
+        if (!allEntries.length) {
+            throw new EmptyResultError('nuget package', `No published versions found for NuGet package "${id}".`);
+        }
+        // Sort by published desc; ties broken by version string descending.
+        const sorted = [...allEntries].sort((a, b) => {
+            const ap = a?.catalogEntry?.published ?? '';
+            const bp = b?.catalogEntry?.published ?? '';
+            if (ap !== bp) return bp.localeCompare(ap);
+            const av = a?.catalogEntry?.version ?? '';
+            const bv = b?.catalogEntry?.version ?? '';
+            return bv.localeCompare(av);
+        });
+        return sorted.map((entry, i) => {
+            const cat = entry?.catalogEntry ?? {};
+            return {
+                rank: i + 1,
+                id: typeof cat?.id === 'string' ? cat.id : id,
+                version: typeof cat?.version === 'string' ? cat.version : null,
+                title: typeof cat?.title === 'string' ? cat.title : null,
+                authors: joinAuthors(cat?.authors),
+                tags: joinTags(cat?.tags),
+                language: typeof cat?.language === 'string' ? cat.language : null,
+                licenseExpression: typeof cat?.licenseExpression === 'string' ? cat.licenseExpression : null,
+                projectUrl: typeof cat?.projectUrl === 'string' ? cat.projectUrl : null,
+                published: typeof cat?.published === 'string' ? cat.published : null,
+                listed: typeof cat?.listed === 'boolean' ? cat.listed : null,
+                url: typeof cat?.id === 'string' && typeof cat?.version === 'string'
+                    ? `https://www.nuget.org/packages/${cat.id}/${cat.version}` : '',
+            };
+        });
+    },
+});

package/clis/nuget/search.js

@@ -0,0 +1,69 @@
+// nuget search — full-text search the NuGet package index.
+//
+// Hits `azuresearch-usnc.nuget.org/query?q=…&take=…&prerelease=false`. The `id`
+// column round-trips into `nuget package` for full version history.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    NUGET_SEARCH_BASE,
+    joinAuthors,
+    joinTags,
+    nugetFetch,
+    requireBoundedInt,
+    requireString,
+} from './utils.js';
+
+cli({
+    site: 'nuget',
+    name: 'search',
+    access: 'read',
+    description: 'Search NuGet packages by keyword',
+    domain: 'api.nuget.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max packages (1-1000)' },
+        { name: 'prerelease', type: 'boolean', default: false, help: 'Include prerelease versions' },
+    ],
+    columns: [
+        'rank',
+        'id',
+        'version',
+        'title',
+        'description',
+        'authors',
+        'tags',
+        'totalDownloads',
+        'verified',
+        'projectUrl',
+        'url',
+    ],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 20, 1000);
+        const prerelease = args.prerelease === true ? 'true' : 'false';
+        const url = `${NUGET_SEARCH_BASE}/query?q=${encodeURIComponent(query)}&take=${limit}&prerelease=${prerelease}`;
+        const body = await nugetFetch(url, 'nuget search');
+        const list = Array.isArray(body?.data) ? body.data : [];
+        if (!list.length) {
+            throw new EmptyResultError('nuget search', `No NuGet packages matched "${query}".`);
+        }
+        return list.slice(0, limit).map((pkg, i) => {
+            const id = typeof pkg?.id === 'string' ? pkg.id : '';
+            return {
+                rank: i + 1,
+                id,
+                version: typeof pkg?.version === 'string' ? pkg.version : null,
+                title: typeof pkg?.title === 'string' ? pkg.title : null,
+                description: typeof pkg?.description === 'string' ? pkg.description : null,
+                authors: joinAuthors(pkg?.authors),
+                tags: joinTags(pkg?.tags),
+                totalDownloads: typeof pkg?.totalDownloads === 'number' ? pkg.totalDownloads : null,
+                verified: pkg?.verified === true,
+                projectUrl: typeof pkg?.projectUrl === 'string' ? pkg.projectUrl : null,
+                url: id ? `https://www.nuget.org/packages/${id}` : '',
+            };
+        });
+    },
+});