@jackwener/opencli 1.7.12 → 1.7.14

package/clis/openfda/utils.js

@@ -0,0 +1,67 @@
+// openFDA shared helpers — FDA drug labels + food recall enforcement (no auth, public).
+//
+// Free public tier with anonymous rate limit (~240 req/min, 1000 req/day per IP).
+// API key bumps that to 240 req/min × ~120000 req/day, but is not required for
+// modest read traffic.
+import { ArgumentError, EmptyResultError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+export const OPENFDA_BASE = 'https://api.fda.gov';
+const UA = 'opencli-openfda/1.0';
+
+export function requireString(value, name) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new ArgumentError(`--${name} is required`);
+    }
+    return value.trim();
+}
+
+export function requireBoundedInt(value, def, max, name = 'limit') {
+    const n = value == null || value === '' ? def : Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > max) {
+        throw new ArgumentError(`--${name} must be an integer between 1 and ${max}`);
+    }
+    return n;
+}
+
+export async function openfdaFetch(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}`);
+    }
+    if (resp.status === 404) {
+        // openFDA returns 404 for "no matches" instead of an empty results array.
+        throw new EmptyResultError(label, `${label} returned 404 (no matches).`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(`${label} rate-limited (HTTP 429); back off 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 non-JSON body: ${err.message}`);
+    }
+    return body;
+}
+
+// openFDA returns most string fields as `[string]` arrays — collapse to first
+// element. Preserves `null` (not coerced to empty string) when the slot is
+// missing entirely.
+export function firstOrNull(arr) {
+    if (!Array.isArray(arr) || !arr.length) return null;
+    const v = arr[0];
+    if (typeof v !== 'string') return v ?? null;
+    const trimmed = v.trim();
+    return trimmed.length ? trimmed : null;
+}
+
+// Comma-join an array of strings, preserving null when empty.
+export function joinOrNull(arr, max = 5) {
+    if (!Array.isArray(arr) || !arr.length) return null;
+    return arr.slice(0, max).map(String).join(', ');
+}

package/clis/osv/osv.test.js

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './vulnerability.js';
+import './query.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('osv vulnerability adapter', () => {
+    const cmd = getRegistry().get('osv/vulnerability');
+
+    it('rejects empty / malformed id 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 spaces' })).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({ id: 'GHSA-aaaa-bbbb-cccc' })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('returns flattened affected packages with severity from database_specific', async () => {
+        const vuln = {
+            id: 'GHSA-29mw-wpgm-hmr9',
+            summary: 'ReDoS in lodash',
+            aliases: ['CVE-2020-28500'],
+            published: '2022-01-06T20:30:46Z',
+            modified: '2025-09-29T21:12:31.102523Z',
+            database_specific: { severity: 'MODERATE', cwe_ids: ['CWE-1333', 'CWE-400'] },
+            severity: [{ type: 'CVSS_V3', score: 'CVSS:3.1/...' }],
+            affected: [
+                { package: { name: 'lodash', ecosystem: 'npm' } },
+                { package: { name: 'lodash-rails', ecosystem: 'RubyGems' } },
+            ],
+            references: [{ url: 'https://example' }],
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(vuln), { status: 200 })));
+
+        const rows = await cmd.func({ id: 'GHSA-29mw-wpgm-hmr9' });
+        expect(rows).toEqual([expect.objectContaining({
+            id: 'GHSA-29mw-wpgm-hmr9',
+            severity: 'MODERATE',
+            aliases: 'CVE-2020-28500',
+            affectedPackages: 'npm:lodash, RubyGems:lodash-rails',
+            cwes: 'CWE-1333, CWE-400',
+            referenceCount: 1,
+            modified: '2025-09-29T21:12:31Z',
+        })]);
+    });
+});
+
+describe('osv query adapter', () => {
+    const cmd = getRegistry().get('osv/query');
+
+    it('rejects bad ecosystem and bad limit before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ package: 'lodash', ecosystem: 'foo', limit: 5 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ package: 'django', ecosystem: 'pypi', limit: 5 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ package: 'lodash', ecosystem: 'npm', limit: 0 })).rejects.toThrow(ArgumentError);
+        await expect(cmd.func({ package: '', ecosystem: 'npm', limit: 5 })).rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('maps HTTP 429 to CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('rate limited', { status: 429 })));
+        await expect(cmd.func({ package: 'lodash', ecosystem: 'npm', limit: 5 })).rejects.toThrow(CommandExecutionError);
+    });
+
+    it('throws EmptyResultError when no vulns reported', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({}), { status: 200 })));
+        await expect(cmd.func({ package: 'lodash', ecosystem: 'npm', limit: 5 })).rejects.toThrow(EmptyResultError);
+    });
+
+    it('sorts by published date descending and rows have id round-tripable into osv vulnerability', async () => {
+        const body = {
+            vulns: [
+                { id: 'GHSA-old', summary: 'old', published: '2020-01-01T00:00:00Z', affected: [{ package: { name: 'django', ecosystem: 'PyPI' } }] },
+                { id: 'GHSA-new', summary: 'new', published: '2026-01-01T00:00:00Z', affected: [{ package: { name: 'django', ecosystem: 'PyPI' } }] },
+            ],
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(body), { status: 200 })));
+
+        const rows = await cmd.func({ package: 'django', ecosystem: 'PyPI', limit: 5 });
+        expect(rows[0]).toMatchObject({ rank: 1, id: 'GHSA-new', published: '2026-01-01T00:00:00Z' });
+        expect(rows[1]).toMatchObject({ rank: 2, id: 'GHSA-old' });
+        expect(rows[0].url).toBe('https://osv.dev/vulnerability/GHSA-new');
+    });
+});

package/clis/osv/query.js

@@ -0,0 +1,72 @@
+// osv query — find vulnerabilities affecting a given package (and optional version).
+//
+// Hits `POST https://api.osv.dev/v1/query` with `{package:{name,ecosystem}, version?}`.
+// Returns one row per vulnerability ranked by published date (newest first), so
+// agents can answer "is package X@Y vulnerable?" in one shot.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    OSV_BASE, osvPost, requireBoundedInt, requireEcosystem, requireString, severityLabel, trimDate,
+} from './utils.js';
+
+cli({
+    site: 'osv',
+    name: 'query',
+    access: 'read',
+    description: 'OSV.dev vulnerabilities affecting a package (optionally pinned to a version)',
+    domain: 'osv.dev',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'package', positional: true, type: 'string', required: true, help: 'Package name (e.g. "lodash", "django")' },
+        { name: 'ecosystem', type: 'string', required: true, help: 'OSV ecosystem (npm / PyPI / Go / Maven / NuGet / RubyGems / crates.io / Packagist / ...)' },
+        { name: 'version', type: 'string', required: false, help: 'Pin to a specific version (e.g. "4.17.20"); omit for all known vulns' },
+        { name: 'limit', type: 'int', default: 30, help: 'Max rows to return (1-200)' },
+    ],
+    columns: [
+        'rank', 'id', 'summary', 'severity', 'aliases',
+        'published', 'modified', 'affectedPackages', 'url',
+    ],
+    func: async (args) => {
+        const name = requireString(args.package, 'package');
+        const ecosystem = requireEcosystem(args.ecosystem);
+        const limit = requireBoundedInt(args.limit, 30, 200, 'limit');
+        const payload = { package: { name, ecosystem } };
+        if (args.version != null && String(args.version).trim() !== '') {
+            payload.version = String(args.version).trim();
+        }
+        const body = await osvPost(`${OSV_BASE}/v1/query`, payload, `osv query ${ecosystem}:${name}`);
+        const vulns = Array.isArray(body?.vulns) ? body.vulns : [];
+        if (vulns.length === 0) {
+            throw new EmptyResultError(
+                'osv query',
+                `OSV.dev returned no vulnerabilities for ${ecosystem}:${name}${payload.version ? `@${payload.version}` : ''}.`,
+            );
+        }
+        const sorted = vulns
+            .slice()
+            .sort((a, b) => String(b?.published ?? '').localeCompare(String(a?.published ?? '')))
+            .slice(0, limit);
+        return sorted.map((v, i) => {
+            const affected = Array.isArray(v.affected) ? v.affected : [];
+            const pkgPairs = [];
+            for (const a of affected) {
+                const eco = a?.package?.ecosystem;
+                const aname = a?.package?.name;
+                if (eco && aname) pkgPairs.push(`${eco}:${aname}`);
+            }
+            const aliases = Array.isArray(v.aliases) ? v.aliases.filter(Boolean) : [];
+            return {
+                rank: i + 1,
+                id: String(v.id ?? ''),
+                summary: String(v.summary ?? '').trim(),
+                severity: severityLabel(v),
+                aliases: aliases.join(', '),
+                published: trimDate(v.published),
+                modified: trimDate(v.modified),
+                affectedPackages: pkgPairs.join(', '),
+                url: v.id ? `https://osv.dev/vulnerability/${v.id}` : '',
+            };
+        });
+    },
+});

package/clis/osv/utils.js

@@ -0,0 +1,169 @@
+// Shared helpers for the OSV.dev (Open Source Vulnerabilities) adapters.
+//
+// OSV.dev publishes a free, unauthenticated REST API at https://api.osv.dev.
+// Docs: https://google.github.io/osv.dev/api/
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const OSV_BASE = 'https://api.osv.dev';
+const UA = 'opencli-osv-adapter (+https://github.com/jackwener/opencli)';
+
+// OSV vulnerability IDs are short tokens like "GHSA-29mw-wpgm-hmr9", "CVE-2020-28500", "PYSEC-2021-1".
+const VULN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+
+// OSV ecosystems we accept on input. The full canonical list is at
+// https://ossf.github.io/osv-schema/#defined-ecosystems — we accept the public
+// ones that map cleanly to package registries opencli already supports.
+export const OSV_ECOSYSTEMS = new Set([
+    'npm',
+    'PyPI',
+    'Go',
+    'Maven',
+    'NuGet',
+    'RubyGems',
+    'crates.io',
+    'Packagist',
+    'Pub',
+    'Hex',
+    'Hackage',
+    'CRAN',
+    'Bitnami',
+    'GitHub Actions',
+    'SwiftURL',
+]);
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`osv ${label} cannot be empty`);
+    return s;
+}
+
+export function requireVulnId(value) {
+    const s = String(value ?? '').trim();
+    if (!s) {
+        throw new ArgumentError(
+            'osv vulnerability id is required (e.g. "GHSA-29mw-wpgm-hmr9", "CVE-2020-28500")',
+            'IDs are listed at https://osv.dev — paste the canonical id from the vulnerability page.',
+        );
+    }
+    if (!VULN_ID.test(s)) {
+        throw new ArgumentError(
+            `osv vulnerability id "${value}" is not a valid OSV id`,
+            'IDs are short ASCII tokens like "GHSA-...", "CVE-...", "PYSEC-...".',
+        );
+    }
+    return s;
+}
+
+export function requireEcosystem(value) {
+    const s = String(value ?? '').trim();
+    if (!s) {
+        throw new ArgumentError(
+            'osv --ecosystem is required when querying by package',
+            `Pick one of: ${[...OSV_ECOSYSTEMS].join(', ')}.`,
+        );
+    }
+    if (!OSV_ECOSYSTEMS.has(s)) {
+        throw new ArgumentError(
+            `osv --ecosystem "${value}" is not a recognised OSV ecosystem`,
+            `Pick one of: ${[...OSV_ECOSYSTEMS].join(', ')}.`,
+        );
+    }
+    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(`osv ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`osv ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+async function readJson(resp, label) {
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}
+
+export async function osvGet(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 api.osv.dev is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `OSV.dev 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}`);
+    }
+    return readJson(resp, label);
+}
+
+export async function osvPost(url, payload, label) {
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method: 'POST',
+            headers: { 'user-agent': UA, accept: 'application/json', 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that api.osv.dev is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `OSV.dev returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(`${label} returned HTTP 429 (rate limited)`);
+    }
+    if (!resp.ok) {
+        const text = await resp.text().catch(() => '');
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}${text ? `: ${text.slice(0, 200)}` : ''}`);
+    }
+    return readJson(resp, label);
+}
+
+// Reduce OSV's `severity` array to a single human-readable label.
+// Returns null when no severity is recorded; never invents a value.
+export function severityLabel(vuln) {
+    const dbSpecific = vuln?.database_specific;
+    if (dbSpecific && typeof dbSpecific.severity === 'string' && dbSpecific.severity.trim()) {
+        return dbSpecific.severity.trim();
+    }
+    const arr = Array.isArray(vuln?.severity) ? vuln.severity : [];
+    for (const entry of arr) {
+        if (entry && typeof entry.score === 'string' && entry.score.trim()) {
+            return entry.score.trim();
+        }
+    }
+    return null;
+}
+
+export function trimDate(value) {
+    const s = String(value ?? '').trim();
+    if (!s) return null;
+    const noFrac = s.replace(/\.\d+/, '');
+    return noFrac.endsWith('Z') ? noFrac : (s.length >= 10 ? s.slice(0, 10) : null);
+}

package/clis/osv/vulnerability.js

@@ -0,0 +1,54 @@
+// osv vulnerability — fetch a single OSV vulnerability by id.
+//
+// Hits `https://api.osv.dev/v1/vulns/<id>`. Returns one row with the canonical
+// id, summary, severity, aliases (CVE / GHSA mappings), publish / modify dates,
+// and the affected packages (flattened to a comma-separated "ecosystem:name" list).
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { OSV_BASE, osvGet, requireVulnId, severityLabel, trimDate } from './utils.js';
+
+cli({
+    site: 'osv',
+    name: 'vulnerability',
+    access: 'read',
+    description: 'Single OSV.dev vulnerability detail (severity, affected packages, CVE/GHSA aliases)',
+    domain: 'osv.dev',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, type: 'string', required: true, help: 'OSV vulnerability id (e.g. "GHSA-29mw-wpgm-hmr9", "CVE-2020-28500")' },
+    ],
+    columns: [
+        'id', 'summary', 'severity', 'aliases', 'published', 'modified',
+        'affectedPackages', 'cwes', 'referenceCount', 'url',
+    ],
+    func: async (args) => {
+        const id = requireVulnId(args.id);
+        const vuln = await osvGet(`${OSV_BASE}/v1/vulns/${encodeURIComponent(id)}`, `osv vulnerability ${id}`);
+        if (!vuln || !vuln.id) {
+            throw new EmptyResultError('osv vulnerability', `OSV.dev returned no record for "${id}".`);
+        }
+        const affected = Array.isArray(vuln.affected) ? vuln.affected : [];
+        const pkgPairs = [];
+        for (const a of affected) {
+            const eco = a?.package?.ecosystem;
+            const name = a?.package?.name;
+            if (eco && name) pkgPairs.push(`${eco}:${name}`);
+        }
+        const aliases = Array.isArray(vuln.aliases) ? vuln.aliases.filter(Boolean) : [];
+        const cwes = Array.isArray(vuln?.database_specific?.cwe_ids) ? vuln.database_specific.cwe_ids : [];
+        const refs = Array.isArray(vuln.references) ? vuln.references : [];
+        return [{
+            id: String(vuln.id),
+            summary: String(vuln.summary ?? '').trim(),
+            severity: severityLabel(vuln),
+            aliases: aliases.join(', '),
+            published: trimDate(vuln.published),
+            modified: trimDate(vuln.modified),
+            affectedPackages: pkgPairs.join(', '),
+            cwes: cwes.join(', '),
+            referenceCount: refs.length,
+            url: `https://osv.dev/vulnerability/${vuln.id}`,
+        }];
+    },
+});

package/clis/packagist/package.js

@@ -0,0 +1,49 @@
+// packagist package — fetch a single Packagist package's metadata.
+//
+// Hits `https://packagist.org/packages/<vendor>/<package>.json`. Returns
+// one row: latest stable version + release time, license, repository,
+// description, lifetime / monthly / daily downloads, github stars, favers.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { PACKAGIST_BASE, packagistFetch, pickStableVersion, requirePackageName, trimDate } from './utils.js';
+
+cli({
+    site: 'packagist',
+    name: 'package',
+    access: 'read',
+    description: 'Fetch a Packagist package\'s metadata (version, downloads, license, repo, GitHub stars)',
+    domain: 'packagist.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'name', positional: true, required: true, help: 'Composer package "<vendor>/<package>" (e.g. "symfony/console", "monolog/monolog")' },
+    ],
+    columns: ['package', 'version', 'releasedAt', 'license', 'description', 'repository', 'githubStars', 'favers', 'downloads', 'monthlyDownloads', 'dailyDownloads', 'url'],
+    func: async (args) => {
+        const { full } = requirePackageName(args.name);
+        const url = `${PACKAGIST_BASE}/packages/${full}.json`;
+        const body = await packagistFetch(url, 'packagist package');
+        const pkg = body?.package;
+        if (!pkg || typeof pkg !== 'object') {
+            throw new CommandExecutionError(`packagist package returned no "package" object for ${full}.`);
+        }
+        const versionKey = pickStableVersion(pkg.versions);
+        const versionEntry = versionKey ? pkg.versions?.[versionKey] : null;
+        const license = Array.isArray(versionEntry?.license) ? versionEntry.license.filter(Boolean).join(', ') : '';
+        const downloads = pkg.downloads ?? {};
+        return [{
+            package: String(pkg.name ?? full).trim(),
+            version: versionKey ? String(versionKey) : '',
+            releasedAt: trimDate(versionEntry?.time),
+            license,
+            description: String(pkg.description ?? '').trim(),
+            repository: String(pkg.repository ?? '').trim(),
+            githubStars: pkg.github_stars != null ? Number(pkg.github_stars) : null,
+            favers: pkg.favers != null ? Number(pkg.favers) : null,
+            downloads: downloads.total != null ? Number(downloads.total) : null,
+            monthlyDownloads: downloads.monthly != null ? Number(downloads.monthly) : null,
+            dailyDownloads: downloads.daily != null ? Number(downloads.daily) : null,
+            url: `https://packagist.org/packages/${full}`,
+        }];
+    },
+});

package/clis/packagist/search.js

@@ -0,0 +1,43 @@
+// packagist search — search Packagist's PHP / Composer package registry.
+//
+// Hits `https://packagist.org/search.json?q=…&per_page=…`. Returns the
+// agent-useful projection: vendor/package (round-trips into `packagist
+// package`), description, lifetime download count, GitHub-stars-style favers,
+// repository URL.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { PACKAGIST_BASE, packagistFetch, requireBoundedInt, requireString } from './utils.js';
+
+cli({
+    site: 'packagist',
+    name: 'search',
+    access: 'read',
+    description: 'Search Packagist (PHP / Composer) packages by keyword',
+    domain: 'packagist.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword (e.g. "symfony", "laravel http")' },
+        { name: 'limit', type: 'int', default: 30, help: 'Max packages (1-100, single Packagist page)' },
+    ],
+    columns: ['rank', 'package', 'description', 'downloads', 'favers', 'repository', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 30, 100);
+        const url = `${PACKAGIST_BASE}/search.json?q=${encodeURIComponent(query)}&per_page=${limit}`;
+        const body = await packagistFetch(url, 'packagist search');
+        const list = Array.isArray(body?.results) ? body.results : [];
+        if (!list.length) {
+            throw new EmptyResultError('packagist search', `No Packagist packages matched "${query}".`);
+        }
+        return list.slice(0, limit).map((row, i) => ({
+            rank: i + 1,
+            package: String(row.name ?? '').trim(),
+            description: String(row.description ?? '').trim(),
+            downloads: row.downloads != null ? Number(row.downloads) : null,
+            favers: row.favers != null ? Number(row.favers) : null,
+            repository: String(row.repository ?? '').trim(),
+            url: String(row.url ?? '').trim(),
+        }));
+    },
+});

package/clis/packagist/utils.js

@@ -0,0 +1,113 @@
+// Shared helpers for the Packagist (PHP / Composer) adapters.
+//
+// Hits the public, unauthenticated `packagist.org` JSON endpoints. Composer's
+// canonical package registry. Package names are `<vendor>/<package>`,
+// lowercase letters / digits / `_-.`, with each segment 1-100 chars.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const PACKAGIST_BASE = 'https://packagist.org';
+const UA = 'opencli-packagist-adapter (+https://github.com/jackwener/opencli)';
+
+// Each segment of a Composer package name (`vendor` and `package`).
+const SEGMENT = /^[a-z0-9]([_.-]?[a-z0-9]+)*$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`packagist ${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(`packagist ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`packagist ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requirePackageName(value) {
+    const raw = String(value ?? '').trim().toLowerCase();
+    if (!raw) {
+        throw new ArgumentError('packagist package name is required (e.g. "symfony/console", "monolog/monolog")');
+    }
+    const slash = raw.indexOf('/');
+    if (slash <= 0 || slash === raw.length - 1) {
+        throw new ArgumentError(
+            `packagist package "${value}" must be "<vendor>/<package>"`,
+            'Both segments are required (Composer convention).',
+        );
+    }
+    const vendor = raw.slice(0, slash);
+    const pkg = raw.slice(slash + 1);
+    if (vendor.length > 100 || pkg.length > 100 || !SEGMENT.test(vendor) || !SEGMENT.test(pkg)) {
+        throw new ArgumentError(
+            `packagist package "${value}" is not a valid Composer name`,
+            'Use lowercase letters / digits / "_-.", segments separated by single "_-." chars (max 100 chars each).',
+        );
+    }
+    return { vendor, package: pkg, full: `${vendor}/${pkg}` };
+}
+
+export async function packagistFetch(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 packagist.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `Packagist returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'Packagist 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-05-05T17:32:01+00:00" → "2026-05-05T17:32:01Z" so timestamps are uniform. */
+export function trimDate(value) {
+    const s = String(value ?? '').trim();
+    if (!s) return null;
+    const noFrac = s.replace(/\.\d+/, '');
+    return noFrac.replace(/(?:[+-]\d{2}:?\d{2}|Z)?$/, 'Z');
+}
+
+/**
+ * Pick the newest stable (non-dev / non-prerelease) version key from a
+ * Packagist `versions` map. Packagist returns keys ordered newest-first.
+ * Falls back to the first key if no stable found.
+ */
+export function pickStableVersion(versions) {
+    if (!versions || typeof versions !== 'object') return null;
+    const keys = Object.keys(versions);
+    if (!keys.length) return null;
+    const PRE = /(?:^|[._\-+])(?:dev|alpha|beta|rc|pre|nightly)(?:[._\-+\d]|$)/i;
+    const DEV_SUFFIX = /\.x-dev$|-dev$/i;
+    for (const k of keys) {
+        if (DEV_SUFFIX.test(k)) continue;
+        if (PRE.test(k)) continue;
+        return k;
+    }
+    return keys[0];
+}