From affcad332daf183c9e528d2657278761d7d7cde9 Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Fri, 21 Aug 2026 18:58:30 +0530
Subject: [PATCH 01/11] feat(npm): add versions command, test suite, and
 expanded README

- Add webcmd npm versions <name> command that lists all published
  versions of a package newest-first, with publishedAt, isLatest flag,
  and a direct npmjs.com URL per version. Mirrors the pypi releases cmd.

- Add optional 
equest parameter to
pmFetch in utils.js so commands
  can inject a fake fetch function in tests without patching globals
  (matches the pattern used in the pypi plugin).

- Add test/npm.test.js with 14 tests covering all four commands:
  package, versions, downloads, search. Includes happy paths, empty
  result / 404 handling, input validation, and a contract test asserting
  browser: false for every registered command.

- Expand README.md with a full command table (including the new versions
  command), argument descriptions, and copy-paste examples for all four
  commands.
---
 plugins/npm/README.md        |  35 ++++-
 plugins/npm/test/npm.test.js | 263 +++++++++++++++++++++++++++++++++++
 plugins/npm/utils.js         |   4 +-
 plugins/npm/versions.js      |  50 +++++++
 4 files changed, 346 insertions(+), 6 deletions(-)
 create mode 100644 plugins/npm/test/npm.test.js
 create mode 100644 plugins/npm/versions.js

diff --git a/plugins/npm/README.md b/plugins/npm/README.md
index 43e11f87..ad541345 100644
--- a/plugins/npm/README.md
+++ b/plugins/npm/README.md
@@ -1,6 +1,7 @@
 # webcmd-plugin-npm
 
-Webcmd commands for npm.
+Inspect public npm package metadata, download stats, version history, and
+search results. No login or API key is required.
 
 ## Install
 
@@ -12,6 +13,32 @@ webcmd plugin install github:agentrhq/webcmd/npm
 
 | Command | Description |
 | --- | --- |
-| `webcmd npm downloads` | Daily download counts for an npm package over a window |
-| `webcmd npm package` | Single npm package metadata (latest version, license, homepage, repository). Use `npm downloads` for stats. |
-| `webcmd npm search` | Search the public npm registry by keyword |
+| `webcmd npm package <name>` | Latest metadata: version, license, homepage, repository, maintainers |
+| `webcmd npm versions <name>` | Published version history, newest first |
+| `webcmd npm downloads <name>` | Daily download counts over a time window |
+| `webcmd npm search <query>` | Search the public registry by keyword |
+
+## Examples
+
+```bash
+# Package metadata
+webcmd npm package react
+webcmd npm package @vercel/og
+
+# Version history
+webcmd npm versions typescript
+webcmd npm versions react --limit 5
+
+# Download stats (defaults to last week, one row per day)
+webcmd npm downloads express
+webcmd npm downloads express --period last-month
+webcmd npm downloads express --period last-year
+webcmd npm downloads express --period 2026-01-01:2026-06-30
+
+# Search
+webcmd npm search "graphql client"
+webcmd npm search vite --limit 5
+```
+
+Use this plugin when an agent needs deterministic package metadata before
+installing, upgrading, or comparing JavaScript tools.
diff --git a/plugins/npm/test/npm.test.js b/plugins/npm/test/npm.test.js
new file mode 100644
index 00000000..b642cd75
--- /dev/null
+++ b/plugins/npm/test/npm.test.js
@@ -0,0 +1,263 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { afterAll, test } from 'vitest';
+import { fileURLToPath } from 'node:url';
+
+const pluginRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const repoRoot = path.resolve(pluginRoot, '..', '..');
+const peerScopeDir = path.join(pluginRoot, 'node_modules', '@agentrhq');
+const peerLink = path.join(peerScopeDir, 'webcmd');
+
+let createdPeerLink = false;
+if (!fs.existsSync(peerLink)) {
+    fs.mkdirSync(peerScopeDir, { recursive: true });
+    // On Windows, directory junctions don't require elevated privileges.
+    const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+    fs.symlinkSync(repoRoot, peerLink, linkType);
+    createdPeerLink = true;
+}
+
+afterAll(() => {
+    if (!createdPeerLink) return;
+    fs.rmSync(peerLink, { force: true, recursive: true });
+    for (const dir of [peerScopeDir, path.dirname(peerScopeDir)]) {
+        try { fs.rmdirSync(dir); } catch { /* leave unrelated local state alone */ }
+    }
+});
+
+const { getRegistry } = await import('@agentrhq/webcmd/registry');
+const [{ versionsNpm }] = await Promise.all([
+    import('../versions.js'),
+    import('../package.js'),
+    import('../downloads.js'),
+    import('../search.js'),
+]);
+
+// ---------------------------------------------------------------------------
+// Shared fixture — a minimal registry payload for a fictional package "exlib"
+// ---------------------------------------------------------------------------
+const REGISTRY_PAYLOAD = {
+    name: 'exlib',
+    description: 'An example library',
+    'dist-tags': { latest: '2.1.0' },
+    versions: {
+        '2.1.0': {
+            description: 'An example library',
+            license: 'MIT',
+            homepage: 'https://exlib.dev',
+            repository: { type: 'git', url: 'git+https://github.com/example/exlib.git' },
+            bugs: { url: 'https://github.com/example/exlib/issues' },
+            keywords: ['example', 'lib'],
+        },
+        '2.0.0': {
+            description: 'An example library',
+            license: 'MIT',
+        },
+    },
+    maintainers: [{ name: 'alice', email: 'alice@example.com' }],
+    time: {
+        created:  '2024-01-01T00:00:00.000Z',
+        modified: '2026-06-15T12:00:00.000Z',
+        '2.0.0':  '2025-03-10T08:00:00.000Z',
+        '2.1.0':  '2026-06-15T12:00:00.000Z',
+    },
+};
+
+const DOWNLOADS_PAYLOAD = {
+    package: 'exlib',
+    downloads: [
+        { day: '2026-06-09', downloads: 1200 },
+        { day: '2026-06-10', downloads: 1350 },
+        { day: '2026-06-11', downloads: 980 },
+    ],
+};
+
+const SEARCH_PAYLOAD = {
+    objects: [
+        {
+            package: {
+                name: 'exlib',
+                version: '2.1.0',
+                description: 'An example library',
+                license: 'MIT',
+                publisher: { username: 'alice' },
+                links: { npm: 'https://www.npmjs.com/package/exlib' },
+            },
+            downloads: { weekly: 50000 },
+            dependents: 120,
+            updated: '2026-06-15T12:00:00.000Z',
+        },
+    ],
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function fakeRequest(payload, { ok = true, status = 200 } = {}) {
+    const req = async (url, _opts) => {
+        req.calls.push(String(url));
+        return { ok, status, json: async () => payload };
+    };
+    req.calls = [];
+    return req;
+}
+
+function withFetch(payload, fn, { ok = true, status = 200 } = {}) {
+    const original = globalThis.fetch;
+    globalThis.fetch = fakeRequest(payload, { ok, status });
+    return fn().finally(() => { globalThis.fetch = original; });
+}
+
+// ---------------------------------------------------------------------------
+// npm package
+// ---------------------------------------------------------------------------
+test('npm package returns latest metadata', () =>
+    withFetch(REGISTRY_PAYLOAD, async () => {
+        const rows = await getRegistry().get('npm/package').func({ name: 'exlib' });
+        assert.equal(rows.length, 1);
+        const [row] = rows;
+        assert.equal(row.name, 'exlib');
+        assert.equal(row.latestVersion, '2.1.0');
+        assert.equal(row.description, 'An example library');
+        assert.equal(row.license, 'MIT');
+        assert.equal(row.homepage, 'https://exlib.dev');
+        assert.equal(row.repository, 'https://github.com/example/exlib');
+        assert.equal(row.bugs, 'https://github.com/example/exlib/issues');
+        assert.equal(row.maintainers, 'alice');
+        assert.equal(row.keywords, 'example, lib');
+        assert.equal(row.created, '2024-01-01');
+        assert.equal(row.modified, '2026-06-15');
+        assert.equal(row.url, 'https://www.npmjs.com/package/exlib');
+    }),
+);
+
+test('npm package hits the correct registry URL', () => {
+    const req = fakeRequest(REGISTRY_PAYLOAD);
+    const original = globalThis.fetch;
+    globalThis.fetch = req;
+    return getRegistry().get('npm/package').func({ name: 'exlib' })
+        .then(() => {
+            assert.ok(req.calls[0].startsWith('https://registry.npmjs.org/'));
+        })
+        .finally(() => { globalThis.fetch = original; });
+});
+
+test('npm package rejects invalid package names', async () => {
+    await assert.rejects(
+        () => getRegistry().get('npm/package').func({ name: '' }),
+        /required/,
+    );
+    await assert.rejects(
+        () => getRegistry().get('npm/package').func({ name: '../etc/passwd' }),
+        /valid/,
+    );
+});
+
+test('npm package throws EmptyResultError on 404', () =>
+    withFetch({}, async () => {
+        await assert.rejects(
+            () => getRegistry().get('npm/package').func({ name: 'no-such-pkg-xyz' }),
+            (err) => err.code === 'EMPTY_RESULT',
+        );
+    }, { ok: false, status: 404 }),
+);
+
+// ---------------------------------------------------------------------------
+// npm versions
+// ---------------------------------------------------------------------------
+test('npm versions returns rows newest first', async () => {
+    const req = fakeRequest(REGISTRY_PAYLOAD);
+    const rows = await versionsNpm({ name: 'exlib', limit: 10 }, req);
+    assert.equal(rows.length, 2);
+    assert.equal(rows[0].version, '2.1.0');
+    assert.equal(rows[0].publishedAt, '2026-06-15');
+    assert.equal(rows[0].isLatest, true);
+    assert.ok(rows[0].url.includes('2.1.0'));
+    assert.equal(rows[1].version, '2.0.0');
+    assert.equal(rows[1].isLatest, false);
+});
+
+test('npm versions strips created/modified bookkeeping keys', async () => {
+    const req = fakeRequest(REGISTRY_PAYLOAD);
+    const rows = await versionsNpm({ name: 'exlib', limit: 50 }, req);
+    assert.ok(rows.every((r) => r.version !== 'created' && r.version !== 'modified'));
+});
+
+test('npm versions respects --limit', async () => {
+    const req = fakeRequest(REGISTRY_PAYLOAD);
+    const rows = await versionsNpm({ name: 'exlib', limit: 1 }, req);
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].version, '2.1.0');
+});
+
+test('npm versions rejects out-of-range limit', async () => {
+    await assert.rejects(
+        () => versionsNpm({ name: 'exlib', limit: 51 }, fakeRequest(REGISTRY_PAYLOAD)),
+        /50/,
+    );
+});
+
+// ---------------------------------------------------------------------------
+// npm downloads
+// ---------------------------------------------------------------------------
+test('npm downloads returns one row per day', () =>
+    withFetch(DOWNLOADS_PAYLOAD, async () => {
+        const rows = await getRegistry().get('npm/downloads').func({ name: 'exlib', period: 'last-week' });
+        assert.equal(rows.length, 3);
+        assert.equal(rows[0].rank, 1);
+        assert.equal(rows[0].package, 'exlib');
+        assert.equal(rows[0].day, '2026-06-09');
+        assert.equal(rows[0].downloads, 1200);
+    }),
+);
+
+test('npm downloads rejects invalid period', async () => {
+    await assert.rejects(
+        () => getRegistry().get('npm/downloads').func({ name: 'exlib', period: 'bad-period' }),
+        /invalid/,
+    );
+});
+
+test('npm downloads rejects date range where start is after end', async () => {
+    await assert.rejects(
+        () => getRegistry().get('npm/downloads').func({ name: 'exlib', period: '2026-06-15:2026-01-01' }),
+        /after end/,
+    );
+});
+
+// ---------------------------------------------------------------------------
+// npm search
+// ---------------------------------------------------------------------------
+test('npm search returns ranked results', () =>
+    withFetch(SEARCH_PAYLOAD, async () => {
+        const rows = await getRegistry().get('npm/search').func({ query: 'exlib', limit: 20 });
+        assert.equal(rows.length, 1);
+        const [row] = rows;
+        assert.equal(row.rank, 1);
+        assert.equal(row.name, 'exlib');
+        assert.equal(row.version, '2.1.0');
+        assert.equal(row.weeklyDownloads, 50000);
+        assert.equal(row.dependents, 120);
+        assert.equal(row.url, 'https://www.npmjs.com/package/exlib');
+    }),
+);
+
+test('npm search rejects empty query', async () => {
+    await assert.rejects(
+        () => getRegistry().get('npm/search').func({ query: '', limit: 20 }),
+        /empty/,
+    );
+});
+
+// ---------------------------------------------------------------------------
+// All registered commands are browser: false
+// ---------------------------------------------------------------------------
+test('all npm commands are browser-free', () => {
+    const registry = getRegistry();
+    for (const name of ['npm/package', 'npm/downloads', 'npm/search', 'npm/versions']) {
+        const cmd = registry.get(name);
+        assert.ok(cmd, `command ${name} not registered`);
+        assert.equal(cmd.browser, false, `${name} should not require a browser`);
+    }
+});
diff --git a/plugins/npm/utils.js b/plugins/npm/utils.js
index fd2aaaed..f041cd87 100644
--- a/plugins/npm/utils.js
+++ b/plugins/npm/utils.js
@@ -42,10 +42,10 @@ export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit'
     return n;
 }
 
-export async function npmFetch(url, label) {
+export async function npmFetch(url, label, request = fetch) {
     let resp;
     try {
-        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+        resp = await request(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
     }
     catch (err) {
         throw new CommandExecutionError(
diff --git a/plugins/npm/versions.js b/plugins/npm/versions.js
new file mode 100644
index 00000000..56693e35
--- /dev/null
+++ b/plugins/npm/versions.js
@@ -0,0 +1,50 @@
+// npm versions — list published versions for a package, newest first.
+//
+// Hits `https://registry.npmjs.org/<pkg>` and projects `time` entries so
+// agents can answer "when was X released?" or "what's the latest stable?".
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { EmptyResultError } from '@agentrhq/webcmd/errors';
+import { NPM_REGISTRY, npmFetch, requireBoundedInt, requirePackageName } from './utils.js';
+
+export async function versionsNpm(args, request = fetch) {
+    const name = requirePackageName(args.name);
+    const limit = requireBoundedInt(args.limit ?? 10, 10, 50);
+    const url = `${NPM_REGISTRY}/${name.split('/').map(encodeURIComponent).join('/')}`;
+    const body = await npmFetch(url, `npm versions ${name}`, request);
+
+    const timeMap = body?.time && typeof body.time === 'object' ? body.time : {};
+    const latest = body?.['dist-tags']?.latest ?? '';
+
+    const rows = Object.entries(timeMap)
+        // skip internal bookkeeping keys that npm puts in time
+        .filter(([version]) => version !== 'created' && version !== 'modified')
+        .map(([version, publishedAt]) => ({
+            version,
+            publishedAt: String(publishedAt ?? '').slice(0, 10),
+            isLatest: version === latest,
+            url: `https://www.npmjs.com/package/${name}/v/${version}`,
+        }))
+        .sort((a, b) => String(b.publishedAt).localeCompare(String(a.publishedAt)))
+        .slice(0, limit);
+
+    if (!rows.length) {
+        throw new EmptyResultError('npm versions', `npm registry has no version history for "${name}".`);
+    }
+    return rows;
+}
+
+cli({
+    site: 'npm',
+    name: 'versions',
+    access: 'read',
+    description: 'List published versions of an npm package, newest first',
+    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")' },
+        { name: 'limit', type: 'int', default: 10, help: 'Maximum versions to return (1-50)' },
+    ],
+    columns: ['version', 'publishedAt', 'isLatest', 'url'],
+    func: (args) => versionsNpm(args),
+});

From 69faaaa961972f4f8a8d0e71f1f728a4b6a163a8 Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Fri, 21 Aug 2026 19:09:25 +0530
Subject: [PATCH 02/11] fix(npm): sort versions by full ISO timestamp before
 formatting

Slicing publishedAt to 10 chars before sorting caused versions
published on the same calendar date to lose sub-day precision,
producing non-deterministic newest-first ordering.

Fix: sort on the raw full timestamp first, then format to date-only
inside .map(). Add a regression test with two versions sharing the
same date (08:00 and 14:00) to pin the correct ordering.
---
 plugins/npm/test/npm.test.js | 24 ++++++++++++++++++++++++
 plugins/npm/versions.js      |  8 +++++---
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/plugins/npm/test/npm.test.js b/plugins/npm/test/npm.test.js
index b642cd75..0ddc2c11 100644
--- a/plugins/npm/test/npm.test.js
+++ b/plugins/npm/test/npm.test.js
@@ -191,6 +191,30 @@ test('npm versions respects --limit', async () => {
     assert.equal(rows[0].version, '2.1.0');
 });
 
+test('npm versions sorts correctly when two versions share the same date', async () => {
+    // Regression: sort must use the full ISO timestamp, not the truncated
+    // date-only string, so same-day releases still come out newest-first.
+    const sameDayPayload = {
+        name: 'exlib',
+        'dist-tags': { latest: '2.1.1' },
+        time: {
+            created:  '2026-06-15T08:00:00.000Z',
+            modified: '2026-06-15T14:00:00.000Z',
+            '2.1.0':  '2026-06-15T08:00:00.000Z',  // earlier on same day
+            '2.1.1':  '2026-06-15T14:00:00.000Z',  // later on same day
+        },
+    };
+    const req = fakeRequest(sameDayPayload);
+    const rows = await versionsNpm({ name: 'exlib', limit: 10 }, req);
+    assert.equal(rows.length, 2);
+    // 2.1.1 published at 14:00 must come before 2.1.0 published at 08:00
+    assert.equal(rows[0].version, '2.1.1');
+    assert.equal(rows[1].version, '2.1.0');
+    // Both format to the same date string
+    assert.equal(rows[0].publishedAt, '2026-06-15');
+    assert.equal(rows[1].publishedAt, '2026-06-15');
+});
+
 test('npm versions rejects out-of-range limit', async () => {
     await assert.rejects(
         () => versionsNpm({ name: 'exlib', limit: 51 }, fakeRequest(REGISTRY_PAYLOAD)),
diff --git a/plugins/npm/versions.js b/plugins/npm/versions.js
index 56693e35..4fe7c88d 100644
--- a/plugins/npm/versions.js
+++ b/plugins/npm/versions.js
@@ -18,14 +18,16 @@ export async function versionsNpm(args, request = fetch) {
     const rows = Object.entries(timeMap)
         // skip internal bookkeeping keys that npm puts in time
         .filter(([version]) => version !== 'created' && version !== 'modified')
+        // sort on the raw full ISO timestamp BEFORE formatting so that two
+        // versions published on the same calendar date still sort correctly
+        .sort(([, left], [, right]) => String(right ?? '').localeCompare(String(left ?? '')))
+        .slice(0, limit)
         .map(([version, publishedAt]) => ({
             version,
             publishedAt: String(publishedAt ?? '').slice(0, 10),
             isLatest: version === latest,
             url: `https://www.npmjs.com/package/${name}/v/${version}`,
-        }))
-        .sort((a, b) => String(b.publishedAt).localeCompare(String(a.publishedAt)))
-        .slice(0, limit);
+        }));
 
     if (!rows.length) {
         throw new EmptyResultError('npm versions', `npm registry has no version history for "${name}".`);

From 5a2f02adbed805f62eb9bddeedbd46feb1b5acd4 Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Fri, 21 Aug 2026 19:18:17 +0530
Subject: [PATCH 03/11] fix(npm): filter versions by body.versions to exclude
 time-only ghost entries

A version key can exist in body.time without a matching entry in
body.versions (e.g. yanked or unpublished releases). The previous code
returned bogus rows for those keys with an invalid URL and misleading
date.

Fix: cross-filter timeMap entries against body.versions so only keys
that exist in both are returned. Also guard that the timestamp is a
string before sorting.

Update the same-day regression fixture to include matching body.versions
entries and add a time-only ghost key (0.0.1-ghost) to assert it is
excluded from results.
---
 plugins/npm/test/npm.test.js | 17 +++++++++++++----
 plugins/npm/versions.js      |  4 ++++
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/plugins/npm/test/npm.test.js b/plugins/npm/test/npm.test.js
index 0ddc2c11..7697b4ae 100644
--- a/plugins/npm/test/npm.test.js
+++ b/plugins/npm/test/npm.test.js
@@ -197,15 +197,22 @@ test('npm versions sorts correctly when two versions share the same date', async
     const sameDayPayload = {
         name: 'exlib',
         'dist-tags': { latest: '2.1.1' },
+        versions: {
+            '2.1.0': { description: 'v2.1.0' },
+            '2.1.1': { description: 'v2.1.1' },
+            // '0.0.1-ghost' intentionally absent — time-only entry below must be excluded
+        },
         time: {
-            created:  '2026-06-15T08:00:00.000Z',
-            modified: '2026-06-15T14:00:00.000Z',
-            '2.1.0':  '2026-06-15T08:00:00.000Z',  // earlier on same day
-            '2.1.1':  '2026-06-15T14:00:00.000Z',  // later on same day
+            created:       '2026-06-15T08:00:00.000Z',
+            modified:      '2026-06-15T14:00:00.000Z',
+            '2.1.0':       '2026-06-15T08:00:00.000Z',  // earlier on same day
+            '2.1.1':       '2026-06-15T14:00:00.000Z',  // later on same day
+            '0.0.1-ghost': '2026-06-15T06:00:00.000Z',  // time-only, no body.versions entry
         },
     };
     const req = fakeRequest(sameDayPayload);
     const rows = await versionsNpm({ name: 'exlib', limit: 10 }, req);
+    // ghost entry must be excluded
     assert.equal(rows.length, 2);
     // 2.1.1 published at 14:00 must come before 2.1.0 published at 08:00
     assert.equal(rows[0].version, '2.1.1');
@@ -213,6 +220,8 @@ test('npm versions sorts correctly when two versions share the same date', async
     // Both format to the same date string
     assert.equal(rows[0].publishedAt, '2026-06-15');
     assert.equal(rows[1].publishedAt, '2026-06-15');
+    // ghost must not appear at all
+    assert.ok(rows.every((r) => r.version !== '0.0.1-ghost'));
 });
 
 test('npm versions rejects out-of-range limit', async () => {
diff --git a/plugins/npm/versions.js b/plugins/npm/versions.js
index 4fe7c88d..2eee020f 100644
--- a/plugins/npm/versions.js
+++ b/plugins/npm/versions.js
@@ -13,11 +13,15 @@ export async function versionsNpm(args, request = fetch) {
     const body = await npmFetch(url, `npm versions ${name}`, request);
 
     const timeMap = body?.time && typeof body.time === 'object' ? body.time : {};
+    const versionsMap = body?.versions && typeof body.versions === 'object' ? body.versions : {};
     const latest = body?.['dist-tags']?.latest ?? '';
 
     const rows = Object.entries(timeMap)
         // skip internal bookkeeping keys that npm puts in time
         .filter(([version]) => version !== 'created' && version !== 'modified')
+        // only keep versions that actually exist in body.versions — time-only
+        // keys (e.g. unpublished entries) have no real release and must be omitted
+        .filter(([version, publishedAt]) => version in versionsMap && typeof publishedAt === 'string')
         // sort on the raw full ISO timestamp BEFORE formatting so that two
         // versions published on the same calendar date still sort correctly
         .sort(([, left], [, right]) => String(right ?? '').localeCompare(String(left ?? '')))

From c267318af4eafc0d4de78fffb8518ba37c51162d Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Sat, 22 Aug 2026 10:08:35 +0530
Subject: [PATCH 04/11] feat(omnisearch): add Reddit as a 7th research source
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reddit is one of the most valuable developer discussion platforms
(r/programming, r/webdev, r/javascript, r/rust, r/python, etc.) but
was missing from the omnisearch aggregator entirely.

- Add redditSearch() to sources.js using the free public JSON search
  API (reddit.com/search.json, no auth or key required). Returns
  normalized rows: platform/title/author/score/commentCount/createdAt/
  url/text — matching the shared schema used by all other sources.
  Falls back to permalink when the url field is absent (self posts).

- Wire redditSearch into research.js: added to the fetchers map and
  included in the default sources string so every agent using
  webcmd omnisearch research gets Reddit results automatically.

- Wire redditSearch into verdict.js so community sentiment analysis
  now includes Reddit engagement alongside HN, SO, GitHub, arXiv,
  Dev.to, and Lobsters.

- Expand test/research.test.js from 1 test to 8 tests:
  - redditSearch: normalized rows, permalink fallback, empty results,
    correct endpoint URL
  - research command: Reddit rows returned, default sources includes
    reddit, Reddit failure isolated via Promise.allSettled
  - Original HN limit regression test preserved
---
 plugins/omnisearch/research.js           |   6 +-
 plugins/omnisearch/sources.js            |  30 ++++
 plugins/omnisearch/test/research.test.js | 183 ++++++++++++++++++++++-
 plugins/omnisearch/verdict.js            |   3 +-
 4 files changed, 212 insertions(+), 10 deletions(-)

diff --git a/plugins/omnisearch/research.js b/plugins/omnisearch/research.js
index ef636f5f..31c9dc8d 100644
--- a/plugins/omnisearch/research.js
+++ b/plugins/omnisearch/research.js
@@ -15,6 +15,7 @@ import {
   devtoSearch,
   githubSearch,
   arxivSearch,
+  redditSearch,
 } from './sources.js';
 
 function requireQuery(value) {
@@ -28,7 +29,7 @@ cli({
   name: 'research',
   tags: ['search'],
   access: 'read',
-  description: "Aggregate results about a topic across all public platforms (Hacker News, Lobsters, Stack Overflow, Dev.to, GitHub, arXiv)",
+  description: "Aggregate results about a topic across all public platforms (Hacker News, Lobsters, Stack Overflow, Dev.to, GitHub, arXiv, Reddit)",
   strategy: Strategy.PUBLIC,
   browser: false,
   args: [
@@ -36,7 +37,7 @@ cli({
     { name: 'limit', type: 'int', default: 20, help: 'Maximum total results' },
     {
       name: 'sources',
-      default: 'hn,lobsters,stackoverflow,devto,github,arxiv',
+      default: 'hn,lobsters,stackoverflow,devto,github,arxiv,reddit',
       help: 'Comma-separated sources to query (default: all)',
     },
   ],
@@ -61,6 +62,7 @@ cli({
       devto: () => devtoSearch(query, perPlatform),
       github: () => githubSearch(query, perPlatform),
       arxiv: () => arxivSearch(query, perPlatform),
+      reddit: () => redditSearch(query, perPlatform),
     };
 
     const selected = wanted.length ? wanted.filter((s) => fetchers[s]) : Object.keys(fetchers);
diff --git a/plugins/omnisearch/sources.js b/plugins/omnisearch/sources.js
index 5fedf25a..f7381a67 100644
--- a/plugins/omnisearch/sources.js
+++ b/plugins/omnisearch/sources.js
@@ -192,3 +192,33 @@ export async function blueskyPosts(handle, limit) {
     };
   });
 }
+
+// --- Reddit (public JSON search API, no auth) ---
+export async function redditSearch(query, limit) {
+  const url = new URL('https://www.reddit.com/search.json');
+  url.searchParams.set('q', query);
+  url.searchParams.set('sort', 'relevance');
+  url.searchParams.set('type', 'link');
+  url.searchParams.set('limit', String(Math.min(limit, 100)));
+  const res = await get(url, {
+    headers: { 'User-Agent': 'Mozilla/5.0 (compatible; OmniSearch/0.1; +https://github.com/agentrhq/webcmd)' },
+  }, { source: 'Reddit' });
+  const json = await res.json();
+  const children = Array.isArray(json?.data?.children) ? json.data.children : [];
+  return children.slice(0, limit).map((child) => {
+    const d = child?.data ?? {};
+    return {
+      platform: 'reddit',
+      title: String(d.title ?? '').trim(),
+      author: String(d.author ?? ''),
+      score: d.score ?? 0,
+      commentCount: d.num_comments ?? 0,
+      createdAt: d.created_utc
+        ? new Date(d.created_utc * 1000).toISOString()
+        : '',
+      url: d.url ? String(d.url) : `https://www.reddit.com${d.permalink ?? ''}`,
+      text: String(d.selftext ?? '').slice(0, 200),
+    };
+  });
+}
+
diff --git a/plugins/omnisearch/test/research.test.js b/plugins/omnisearch/test/research.test.js
index 699fe6cb..0104e79a 100644
--- a/plugins/omnisearch/test/research.test.js
+++ b/plugins/omnisearch/test/research.test.js
@@ -1,17 +1,188 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@agentrhq/webcmd/registry';
 import '../research.js';
+import '../verdict.js';
 
 afterEach(() => vi.unstubAllGlobals());
 
-describe('omnisearch research', () => {
+// ---------------------------------------------------------------------------
+// Fake fetch helpers
+// ---------------------------------------------------------------------------
+
+/** Reddit JSON API shape */
+function redditResponse(posts) {
+  return {
+    data: {
+      children: posts.map((p) => ({ kind: 't3', data: p })),
+    },
+  };
+}
+
+/** HN Algolia shape */
+function hnResponse(hits) {
+  return { hits };
+}
+
+/** Generic 200 OK stub */
+function stubFetch(handler) {
+  vi.stubGlobal('fetch', async (input) => {
+    const body = await handler(String(input));
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// redditSearch (via sources.js)
+// ---------------------------------------------------------------------------
+
+describe('redditSearch', () => {
+  it('returns normalized rows from Reddit JSON API', async () => {
+    const { redditSearch } = await import('../sources.js');
+
+    stubFetch(() =>
+      redditResponse([
+        {
+          title: 'Why Rust is fast',
+          author: 'rustacean',
+          score: 420,
+          num_comments: 87,
+          created_utc: 1700000000,
+          url: 'https://example.com/rust-fast',
+          selftext: '',
+          permalink: '/r/rust/comments/abc/why_rust_is_fast/',
+        },
+      ]),
+    );
+
+    const rows = await redditSearch('rust', 5);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].platform).toBe('reddit');
+    expect(rows[0].title).toBe('Why Rust is fast');
+    expect(rows[0].author).toBe('rustacean');
+    expect(rows[0].score).toBe(420);
+    expect(rows[0].commentCount).toBe(87);
+    expect(rows[0].url).toBe('https://example.com/rust-fast');
+    expect(rows[0].createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  it('falls back to permalink when url field is absent', async () => {
+    const { redditSearch } = await import('../sources.js');
+
+    stubFetch(() =>
+      redditResponse([
+        {
+          title: 'A self post',
+          author: 'op',
+          score: 10,
+          num_comments: 2,
+          created_utc: 1700000000,
+          url: null,
+          selftext: 'Some body text',
+          permalink: '/r/programming/comments/xyz/a_self_post/',
+        },
+      ]),
+    );
+
+    const rows = await redditSearch('selfpost', 5);
+    expect(rows[0].url).toBe('https://www.reddit.com/r/programming/comments/xyz/a_self_post/');
+  });
+
+  it('returns empty array when Reddit returns no children', async () => {
+    const { redditSearch } = await import('../sources.js');
+    stubFetch(() => ({ data: { children: [] } }));
+    const rows = await redditSearch('xyzzy-no-results', 5);
+    expect(rows).toHaveLength(0);
+  });
+
+  it('hits the correct Reddit search endpoint', async () => {
+    const { redditSearch } = await import('../sources.js');
+    const calls = [];
+    vi.stubGlobal('fetch', async (input) => {
+      calls.push(String(input));
+      return new Response(JSON.stringify({ data: { children: [] } }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    });
+
+    await redditSearch('browser automation', 10);
+    expect(calls[0]).toContain('reddit.com/search.json');
+    expect(calls[0]).toContain('browser+automation');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// omnisearch research — Reddit integration
+// ---------------------------------------------------------------------------
+
+describe('omnisearch research with reddit source', () => {
+  it('returns Reddit rows when sources=reddit', async () => {
+    const command = getRegistry().get('omnisearch/research');
+
+    stubFetch(() =>
+      redditResponse([
+        {
+          title: 'Playwright vs Puppeteer',
+          author: 'tester',
+          score: 300,
+          num_comments: 45,
+          created_utc: 1700000000,
+          url: 'https://example.com/pw-vs-pp',
+          selftext: '',
+          permalink: '/r/webdev/comments/pw-vs-pp/',
+        },
+      ]),
+    );
+
+    const rows = await command.func({ query: 'playwright', limit: 5, sources: 'reddit' });
+    expect(rows.length).toBeGreaterThan(0);
+    expect(rows[0].platform).toBe('reddit');
+    expect(rows[0].title).toBe('Playwright vs Puppeteer');
+  });
+
+  it('includes reddit in default sources', () => {
+    const command = getRegistry().get('omnisearch/research');
+    const sourcesArg = command.args.find((a) => a.name === 'sources');
+    expect(sourcesArg.default).toContain('reddit');
+  });
+
+  it('handles reddit failure gracefully when other sources succeed', async () => {
+    const command = getRegistry().get('omnisearch/research');
+
+    vi.stubGlobal('fetch', async (input) => {
+      if (String(input).includes('reddit.com')) {
+        return new Response('Service Unavailable', { status: 503 });
+      }
+      // HN succeeds
+      return new Response(
+        JSON.stringify(hnResponse([
+          { objectID: '1', title: 'HN result', author: 'a', points: 10, num_comments: 2, created_at: '2026-01-01T00:00:00Z', url: 'https://example.com' },
+        ])),
+        { status: 200, headers: { 'content-type': 'application/json' } },
+      );
+    });
+
+    // Should not throw — Reddit failure is isolated via Promise.allSettled
+    const rows = await command.func({ query: 'test', limit: 5, sources: 'hn,reddit' });
+    expect(rows.some((r) => r.platform === 'hackernews')).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Original limit test (kept for regression)
+// ---------------------------------------------------------------------------
+
+describe('omnisearch research — limit enforcement', () => {
   it('honors the total limit when research is narrowed to one source', async () => {
     const hits = [
-      { objectID: '1', title: 'One', author: 'a', points: 5, num_comments: 1, created_at: '2026-01-01T00:00:00Z', url: 'https://example.com/1' },
-      { objectID: '2', title: 'Two', author: 'b', points: 4, num_comments: 2, created_at: '2026-01-02T00:00:00Z', url: 'https://example.com/2' },
+      { objectID: '1', title: 'One',   author: 'a', points: 5, num_comments: 1, created_at: '2026-01-01T00:00:00Z', url: 'https://example.com/1' },
+      { objectID: '2', title: 'Two',   author: 'b', points: 4, num_comments: 2, created_at: '2026-01-02T00:00:00Z', url: 'https://example.com/2' },
       { objectID: '3', title: 'Three', author: 'c', points: 3, num_comments: 3, created_at: '2026-01-03T00:00:00Z', url: 'https://example.com/3' },
-      { objectID: '4', title: 'Four', author: 'd', points: 2, num_comments: 4, created_at: '2026-01-04T00:00:00Z', url: 'https://example.com/4' },
-      { objectID: '5', title: 'Five', author: 'e', points: 1, num_comments: 5, created_at: '2026-01-05T00:00:00Z', url: 'https://example.com/5' },
+      { objectID: '4', title: 'Four',  author: 'd', points: 2, num_comments: 4, created_at: '2026-01-04T00:00:00Z', url: 'https://example.com/4' },
+      { objectID: '5', title: 'Five',  author: 'e', points: 1, num_comments: 5, created_at: '2026-01-05T00:00:00Z', url: 'https://example.com/5' },
     ];
     vi.stubGlobal('fetch', async (input) => {
       const count = Number(new URL(input).searchParams.get('hitsPerPage'));
@@ -21,9 +192,7 @@ describe('omnisearch research', () => {
       });
     });
     const command = getRegistry().get('omnisearch/research');
-
     const rows = await command.func({ query: 'webcmd', limit: 5, sources: 'hn' });
-
     expect(rows.map((row) => row.title)).toEqual(['One', 'Two', 'Three', 'Four', 'Five']);
   });
 });
diff --git a/plugins/omnisearch/verdict.js b/plugins/omnisearch/verdict.js
index b37b7a06..f0094285 100644
--- a/plugins/omnisearch/verdict.js
+++ b/plugins/omnisearch/verdict.js
@@ -7,7 +7,7 @@
  */
 import { cli, Strategy } from '@agentrhq/webcmd/registry';
 import { ArgumentError, CommandExecutionError, EmptyResultError } from '@agentrhq/webcmd/errors';
-import { hnSearch, lobstersSearch, stackoverflowSearch, githubSearch, arxivSearch, devtoSearch } from './sources.js';
+import { hnSearch, lobstersSearch, stackoverflowSearch, githubSearch, arxivSearch, devtoSearch, redditSearch } from './sources.js';
 
 function requireQuery(value) {
   const s = String(value ?? '').trim();
@@ -41,6 +41,7 @@ cli({
       () => arxivSearch(topic, perSource),
       () => devtoSearch(topic, perSource),
       () => lobstersSearch(topic, perSource),
+      () => redditSearch(topic, perSource),
     ];
 
     let results;

From 7934049ec2779b91aa15a5f32f2b046fb86c03be Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Sat, 22 Aug 2026 10:17:49 +0530
Subject: [PATCH 05/11] fix(omnisearch): guard against invalid created_utc in
 redditSearch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A non-numeric or out-of-range created_utc value would cause
new Date(...).toISOString() to throw, rejecting the entire Reddit
result set for that query.

Fix: construct the Date object first, then check Number.isNaN on
getTime() before calling toISOString() — returning empty string
for malformed timestamps so one bad post never kills the whole fetch.

Add regression test: a post with created_utc='not-a-number' must
produce createdAt='' without throwing.
---
 plugins/omnisearch/sources.js            |  5 ++---
 plugins/omnisearch/test/research.test.js | 22 ++++++++++++++++++++++
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/plugins/omnisearch/sources.js b/plugins/omnisearch/sources.js
index f7381a67..02562dbe 100644
--- a/plugins/omnisearch/sources.js
+++ b/plugins/omnisearch/sources.js
@@ -207,15 +207,14 @@ export async function redditSearch(query, limit) {
   const children = Array.isArray(json?.data?.children) ? json.data.children : [];
   return children.slice(0, limit).map((child) => {
     const d = child?.data ?? {};
+    const createdAt = new Date(d.created_utc ? Number(d.created_utc) * 1000 : NaN);
     return {
       platform: 'reddit',
       title: String(d.title ?? '').trim(),
       author: String(d.author ?? ''),
       score: d.score ?? 0,
       commentCount: d.num_comments ?? 0,
-      createdAt: d.created_utc
-        ? new Date(d.created_utc * 1000).toISOString()
-        : '',
+      createdAt: Number.isNaN(createdAt.getTime()) ? '' : createdAt.toISOString(),
       url: d.url ? String(d.url) : `https://www.reddit.com${d.permalink ?? ''}`,
       text: String(d.selftext ?? '').slice(0, 200),
     };
diff --git a/plugins/omnisearch/test/research.test.js b/plugins/omnisearch/test/research.test.js
index 0104e79a..9efb4d78 100644
--- a/plugins/omnisearch/test/research.test.js
+++ b/plugins/omnisearch/test/research.test.js
@@ -97,6 +97,28 @@ describe('redditSearch', () => {
     expect(rows).toHaveLength(0);
   });
 
+  it('returns empty string for createdAt when created_utc is invalid', async () => {
+    const { redditSearch } = await import('../sources.js');
+    stubFetch(() =>
+      redditResponse([
+        {
+          title: 'Malformed post',
+          author: 'op',
+          score: 1,
+          num_comments: 0,
+          created_utc: 'not-a-number',
+          url: 'https://example.com/post',
+          selftext: '',
+          permalink: '/r/test/comments/abc/',
+        },
+      ]),
+    );
+    // Must not throw — one bad timestamp returns '' not an exception
+    const rows = await redditSearch('test', 5);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].createdAt).toBe('');
+  });
+
   it('hits the correct Reddit search endpoint', async () => {
     const { redditSearch } = await import('../sources.js');
     const calls = [];

From 9c33fd272ba838fd63a4a76ced019006287f5f2e Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Sat, 22 Aug 2026 10:24:00 +0530
Subject: [PATCH 06/11] fix(omnisearch): drop null/data-less Reddit children
 before normalization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

child?.data ?? {} silently converted null entries and entries missing
a data object into fake normalized rows, which downstream research
could count or render as real Reddit results.

Fix: filter children to only those where child.data is a non-null
object before slice/map. Add regression test: a mix of null, no-data,
and null-data children alongside one valid entry — only the valid
entry must appear in results.
---
 plugins/omnisearch/sources.js            |  5 +++-
 plugins/omnisearch/test/research.test.js | 30 ++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/plugins/omnisearch/sources.js b/plugins/omnisearch/sources.js
index 02562dbe..8efca5b9 100644
--- a/plugins/omnisearch/sources.js
+++ b/plugins/omnisearch/sources.js
@@ -205,7 +205,10 @@ export async function redditSearch(query, limit) {
   }, { source: 'Reddit' });
   const json = await res.json();
   const children = Array.isArray(json?.data?.children) ? json.data.children : [];
-  return children.slice(0, limit).map((child) => {
+  return children
+    .filter((child) => child?.data && typeof child.data === 'object')
+    .slice(0, limit)
+    .map((child) => {
     const d = child?.data ?? {};
     const createdAt = new Date(d.created_utc ? Number(d.created_utc) * 1000 : NaN);
     return {
diff --git a/plugins/omnisearch/test/research.test.js b/plugins/omnisearch/test/research.test.js
index 9efb4d78..06de88d7 100644
--- a/plugins/omnisearch/test/research.test.js
+++ b/plugins/omnisearch/test/research.test.js
@@ -119,6 +119,36 @@ describe('redditSearch', () => {
     expect(rows[0].createdAt).toBe('');
   });
 
+  it('drops null or data-less children before normalization', async () => {
+    const { redditSearch } = await import('../sources.js');
+    stubFetch(() => ({
+      data: {
+        children: [
+          null,
+          { kind: 't3' },           // no data field
+          { kind: 't3', data: null }, // data is null not object
+          {
+            kind: 't3',
+            data: {
+              title: 'Valid post',
+              author: 'op',
+              score: 5,
+              num_comments: 1,
+              created_utc: 1700000000,
+              url: 'https://example.com/valid',
+              selftext: '',
+              permalink: '/r/test/comments/valid/',
+            },
+          },
+        ],
+      },
+    }));
+    const rows = await redditSearch('test', 10);
+    // Only the valid entry should appear
+    expect(rows).toHaveLength(1);
+    expect(rows[0].title).toBe('Valid post');
+  });
+
   it('hits the correct Reddit search endpoint', async () => {
     const { redditSearch } = await import('../sources.js');
     const calls = [];

From 89073d7ed03aa178687494e86de7da8cd653786b Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Sat, 22 Aug 2026 10:30:30 +0530
Subject: [PATCH 07/11] fix(omnisearch): reject array-shaped child.data in
 redditSearch

typeof [] === 'object' is true in JavaScript, so {data:[]} passed the
previous filter and mapped to a fake row that could displace a valid
result when limit was applied after slicing.

Fix: add !Array.isArray(child.data) to the filter so only plain objects
are accepted as valid post data.

Add regression test: one array-data entry + one valid entry with limit=1
asserts the valid result is returned, not the array-shaped fake.
---
 plugins/omnisearch/sources.js            |  2 +-
 plugins/omnisearch/test/research.test.js | 27 ++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/plugins/omnisearch/sources.js b/plugins/omnisearch/sources.js
index 8efca5b9..12f7d262 100644
--- a/plugins/omnisearch/sources.js
+++ b/plugins/omnisearch/sources.js
@@ -206,7 +206,7 @@ export async function redditSearch(query, limit) {
   const json = await res.json();
   const children = Array.isArray(json?.data?.children) ? json.data.children : [];
   return children
-    .filter((child) => child?.data && typeof child.data === 'object')
+    .filter((child) => child?.data && typeof child.data === 'object' && !Array.isArray(child.data))
     .slice(0, limit)
     .map((child) => {
     const d = child?.data ?? {};
diff --git a/plugins/omnisearch/test/research.test.js b/plugins/omnisearch/test/research.test.js
index 06de88d7..98e9a3dc 100644
--- a/plugins/omnisearch/test/research.test.js
+++ b/plugins/omnisearch/test/research.test.js
@@ -149,6 +149,33 @@ describe('redditSearch', () => {
     expect(rows[0].title).toBe('Valid post');
   });
 
+  it('excludes children with array-shaped data that would displace valid results', async () => {
+    const { redditSearch } = await import('../sources.js');
+    stubFetch(() => ({
+      data: {
+        children: [
+          { kind: 't3', data: [] },   // array passes typeof 'object' — must be rejected
+          {
+            kind: 't3',
+            data: {
+              title: 'Real result',
+              author: 'op',
+              score: 10,
+              num_comments: 2,
+              created_utc: 1700000000,
+              url: 'https://example.com/real',
+              selftext: '',
+              permalink: '/r/test/comments/real/',
+            },
+          },
+        ],
+      },
+    }));
+    const rows = await redditSearch('test', 1);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].title).toBe('Real result');
+  });
+
   it('hits the correct Reddit search endpoint', async () => {
     const { redditSearch } = await import('../sources.js');
     const calls = [];

From 8c93f2f0a185abafec70e23fbcf1887a6988f906 Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Sat, 22 Aug 2026 10:36:18 +0530
Subject: [PATCH 08/11] fix(omnisearch): bound Reddit requests with a 10-second
 AbortSignal timeout

Without a timeout, a slow or stalled Reddit connection could keep the
fetch pending indefinitely, blocking the entire research aggregation.

Fix: pass AbortSignal.timeout(10_000) in the get() init options so the
request is automatically aborted after 10 seconds. The existing headers
and response handling are preserved.
---
 plugins/omnisearch/sources.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/plugins/omnisearch/sources.js b/plugins/omnisearch/sources.js
index 12f7d262..72ab7cbe 100644
--- a/plugins/omnisearch/sources.js
+++ b/plugins/omnisearch/sources.js
@@ -202,6 +202,7 @@ export async function redditSearch(query, limit) {
   url.searchParams.set('limit', String(Math.min(limit, 100)));
   const res = await get(url, {
     headers: { 'User-Agent': 'Mozilla/5.0 (compatible; OmniSearch/0.1; +https://github.com/agentrhq/webcmd)' },
+    signal: AbortSignal.timeout(10_000),
   }, { source: 'Reddit' });
   const json = await res.json();
   const children = Array.isArray(json?.data?.children) ? json.data.children : [];

From eef96ea8bc686c48b2e0063518ac00b2fba093fe Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Mon, 24 Aug 2026 18:19:01 +0530
Subject: [PATCH 09/11] fix(npm): address maintainer review feedback for npm
 versions command

- Drop the 
equest parameter from
pmFetch and ersionsNpm. Instead, use withFetch in tests to stub the global etch.
- Filter out pre-release and build versions by default. Add a --prereleases boolean flag (default alse) to allow including them when requested.
- Update and expand tests in 	est/npm.test.js to cover the new pre-release filtering behavior and verify that the --prereleases flag works correctly.
---
 plugins/npm/test/npm.test.js | 119 +++++++++++++++++++++++------------
 plugins/npm/utils.js         |   4 +-
 plugins/npm/versions.js      |   7 ++-
 3 files changed, 86 insertions(+), 44 deletions(-)

diff --git a/plugins/npm/test/npm.test.js b/plugins/npm/test/npm.test.js
index 7697b4ae..932232a6 100644
--- a/plugins/npm/test/npm.test.js
+++ b/plugins/npm/test/npm.test.js
@@ -166,32 +166,35 @@ test('npm package throws EmptyResultError on 404', () =>
 // ---------------------------------------------------------------------------
 // npm versions
 // ---------------------------------------------------------------------------
-test('npm versions returns rows newest first', async () => {
-    const req = fakeRequest(REGISTRY_PAYLOAD);
-    const rows = await versionsNpm({ name: 'exlib', limit: 10 }, req);
-    assert.equal(rows.length, 2);
-    assert.equal(rows[0].version, '2.1.0');
-    assert.equal(rows[0].publishedAt, '2026-06-15');
-    assert.equal(rows[0].isLatest, true);
-    assert.ok(rows[0].url.includes('2.1.0'));
-    assert.equal(rows[1].version, '2.0.0');
-    assert.equal(rows[1].isLatest, false);
-});
+test('npm versions returns rows newest first', () =>
+    withFetch(REGISTRY_PAYLOAD, async () => {
+        const rows = await versionsNpm({ name: 'exlib', limit: 10 });
+        assert.equal(rows.length, 2);
+        assert.equal(rows[0].version, '2.1.0');
+        assert.equal(rows[0].publishedAt, '2026-06-15');
+        assert.equal(rows[0].isLatest, true);
+        assert.ok(rows[0].url.includes('2.1.0'));
+        assert.equal(rows[1].version, '2.0.0');
+        assert.equal(rows[1].isLatest, false);
+    }),
+);
 
-test('npm versions strips created/modified bookkeeping keys', async () => {
-    const req = fakeRequest(REGISTRY_PAYLOAD);
-    const rows = await versionsNpm({ name: 'exlib', limit: 50 }, req);
-    assert.ok(rows.every((r) => r.version !== 'created' && r.version !== 'modified'));
-});
+test('npm versions strips created/modified bookkeeping keys', () =>
+    withFetch(REGISTRY_PAYLOAD, async () => {
+        const rows = await versionsNpm({ name: 'exlib', limit: 50 });
+        assert.ok(rows.every((r) => r.version !== 'created' && r.version !== 'modified'));
+    }),
+);
 
-test('npm versions respects --limit', async () => {
-    const req = fakeRequest(REGISTRY_PAYLOAD);
-    const rows = await versionsNpm({ name: 'exlib', limit: 1 }, req);
-    assert.equal(rows.length, 1);
-    assert.equal(rows[0].version, '2.1.0');
-});
+test('npm versions respects --limit', () =>
+    withFetch(REGISTRY_PAYLOAD, async () => {
+        const rows = await versionsNpm({ name: 'exlib', limit: 1 });
+        assert.equal(rows.length, 1);
+        assert.equal(rows[0].version, '2.1.0');
+    }),
+);
 
-test('npm versions sorts correctly when two versions share the same date', async () => {
+test('npm versions sorts correctly when two versions share the same date', () => {
     // Regression: sort must use the full ISO timestamp, not the truncated
     // date-only string, so same-day releases still come out newest-first.
     const sameDayPayload = {
@@ -210,27 +213,63 @@ test('npm versions sorts correctly when two versions share the same date', async
             '0.0.1-ghost': '2026-06-15T06:00:00.000Z',  // time-only, no body.versions entry
         },
     };
-    const req = fakeRequest(sameDayPayload);
-    const rows = await versionsNpm({ name: 'exlib', limit: 10 }, req);
-    // ghost entry must be excluded
-    assert.equal(rows.length, 2);
-    // 2.1.1 published at 14:00 must come before 2.1.0 published at 08:00
-    assert.equal(rows[0].version, '2.1.1');
-    assert.equal(rows[1].version, '2.1.0');
-    // Both format to the same date string
-    assert.equal(rows[0].publishedAt, '2026-06-15');
-    assert.equal(rows[1].publishedAt, '2026-06-15');
-    // ghost must not appear at all
-    assert.ok(rows.every((r) => r.version !== '0.0.1-ghost'));
+    return withFetch(sameDayPayload, async () => {
+        const rows = await versionsNpm({ name: 'exlib', limit: 10 });
+        // ghost entry must be excluded
+        assert.equal(rows.length, 2);
+        // 2.1.1 published at 14:00 must come before 2.1.0 published at 08:00
+        assert.equal(rows[0].version, '2.1.1');
+        assert.equal(rows[1].version, '2.1.0');
+        // Both format to the same date string
+        assert.equal(rows[0].publishedAt, '2026-06-15');
+        assert.equal(rows[1].publishedAt, '2026-06-15');
+        // ghost must not appear at all
+        assert.ok(rows.every((r) => r.version !== '0.0.1-ghost'));
+    });
 });
 
-test('npm versions rejects out-of-range limit', async () => {
-    await assert.rejects(
-        () => versionsNpm({ name: 'exlib', limit: 51 }, fakeRequest(REGISTRY_PAYLOAD)),
-        /50/,
-    );
+test('npm versions filters out prereleases by default and includes them with flag', () => {
+    const prereleasePayload = {
+        name: 'exlib',
+        'dist-tags': { latest: '2.1.0' },
+        versions: {
+            '2.0.0': { description: 'v2.0.0' },
+            '2.1.0': { description: 'v2.1.0' },
+            '2.2.0-beta.0': { description: 'v2.2.0-beta.0' },
+        },
+        time: {
+            created:        '2025-01-01T00:00:00.000Z',
+            modified:       '2026-07-01T00:00:00.000Z',
+            '2.0.0':        '2025-03-10T08:00:00.000Z',
+            '2.1.0':        '2026-06-15T12:00:00.000Z',
+            '2.2.0-beta.0': '2026-07-01T00:00:00.000Z',
+        },
+    };
+    return withFetch(prereleasePayload, async () => {
+        // By default, prerelease (2.2.0-beta.0) is filtered out
+        const defaultRows = await versionsNpm({ name: 'exlib', limit: 10 });
+        assert.equal(defaultRows.length, 2);
+        assert.equal(defaultRows[0].version, '2.1.0');
+        assert.equal(defaultRows[1].version, '2.0.0');
+
+        // With prereleases: true flag, prereleases are returned
+        const allRows = await versionsNpm({ name: 'exlib', limit: 10, prereleases: true });
+        assert.equal(allRows.length, 3);
+        assert.equal(allRows[0].version, '2.2.0-beta.0');
+        assert.equal(allRows[1].version, '2.1.0');
+        assert.equal(allRows[2].version, '2.0.0');
+    });
 });
 
+test('npm versions rejects out-of-range limit', () =>
+    withFetch(REGISTRY_PAYLOAD, async () => {
+        await assert.rejects(
+            () => versionsNpm({ name: 'exlib', limit: 51 }),
+            /50/,
+        );
+    }),
+);
+
 // ---------------------------------------------------------------------------
 // npm downloads
 // ---------------------------------------------------------------------------
diff --git a/plugins/npm/utils.js b/plugins/npm/utils.js
index f041cd87..fd2aaaed 100644
--- a/plugins/npm/utils.js
+++ b/plugins/npm/utils.js
@@ -42,10 +42,10 @@ export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit'
     return n;
 }
 
-export async function npmFetch(url, label, request = fetch) {
+export async function npmFetch(url, label) {
     let resp;
     try {
-        resp = await request(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
     }
     catch (err) {
         throw new CommandExecutionError(
diff --git a/plugins/npm/versions.js b/plugins/npm/versions.js
index 2eee020f..659a48d8 100644
--- a/plugins/npm/versions.js
+++ b/plugins/npm/versions.js
@@ -6,11 +6,11 @@ import { cli, Strategy } from '@agentrhq/webcmd/registry';
 import { EmptyResultError } from '@agentrhq/webcmd/errors';
 import { NPM_REGISTRY, npmFetch, requireBoundedInt, requirePackageName } from './utils.js';
 
-export async function versionsNpm(args, request = fetch) {
+export async function versionsNpm(args) {
     const name = requirePackageName(args.name);
     const limit = requireBoundedInt(args.limit ?? 10, 10, 50);
     const url = `${NPM_REGISTRY}/${name.split('/').map(encodeURIComponent).join('/')}`;
-    const body = await npmFetch(url, `npm versions ${name}`, request);
+    const body = await npmFetch(url, `npm versions ${name}`);
 
     const timeMap = body?.time && typeof body.time === 'object' ? body.time : {};
     const versionsMap = body?.versions && typeof body.versions === 'object' ? body.versions : {};
@@ -22,6 +22,8 @@ export async function versionsNpm(args, request = fetch) {
         // only keep versions that actually exist in body.versions — time-only
         // keys (e.g. unpublished entries) have no real release and must be omitted
         .filter(([version, publishedAt]) => version in versionsMap && typeof publishedAt === 'string')
+        // filter out prereleases by default (they contain a hyphen, e.g. 19.0.0-rc.0)
+        .filter(([version]) => args.prereleases || !version.includes('-'))
         // sort on the raw full ISO timestamp BEFORE formatting so that two
         // versions published on the same calendar date still sort correctly
         .sort(([, left], [, right]) => String(right ?? '').localeCompare(String(left ?? '')))
@@ -50,6 +52,7 @@ cli({
     args: [
         { name: 'name', positional: true, required: true, help: 'npm package name (e.g. "react", "@vercel/og")' },
         { name: 'limit', type: 'int', default: 10, help: 'Maximum versions to return (1-50)' },
+        { name: 'prereleases', type: 'boolean', default: false, help: 'Include prerelease and build versions (e.g. alpha, beta, rc, canary)' },
     ],
     columns: ['version', 'publishedAt', 'isLatest', 'url'],
     func: (args) => versionsNpm(args),

From ad518747037f3675f084cb180159503ce865eaf7 Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Mon, 24 Aug 2026 18:31:46 +0530
Subject: [PATCH 10/11] feat(omnisearch): implement Universal Package Search
 (omnisearch packages)

- Create plugins/omnisearch/packages.js to query npm, crates.io, NuGet, RubyGems, Packagist, and Maven Central in parallel using Promise.allSettled for failure isolation.
- Add support for --limit and --registries options to customize the search.
- Normalize search results to a unified schema: registry, name, version, description, and url.
- Create plugins/omnisearch/test/packages.test.js to cover all happy paths, filtering, limits, failure isolation, and browserless compliance.
- Re-compile the plugin command manifest to register the new command.
---
 plugin-command-manifest.json             |  85 ++++++++++
 plugins/omnisearch/packages.js           | 196 ++++++++++++++++++++++
 plugins/omnisearch/test/packages.test.js | 199 +++++++++++++++++++++++
 3 files changed, 480 insertions(+)
 create mode 100644 plugins/omnisearch/packages.js
 create mode 100644 plugins/omnisearch/test/packages.test.js

diff --git a/plugin-command-manifest.json b/plugin-command-manifest.json
index a6b9eef6..23e9c9dd 100644
--- a/plugin-command-manifest.json
+++ b/plugin-command-manifest.json
@@ -17191,6 +17191,47 @@
     "modulePath": "plugins/npm/search.js",
     "sourceFile": "plugins/npm/search.js"
   },
+  {
+    "site": "npm",
+    "name": "versions",
+    "description": "List published versions of an npm package, newest first",
+    "access": "read",
+    "domain": "registry.npmjs.org",
+    "strategy": "public",
+    "browser": false,
+    "args": [
+      {
+        "name": "name",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "npm package name (e.g. \"react\", \"@vercel/og\")"
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 10,
+        "required": false,
+        "help": "Maximum versions to return (1-50)"
+      },
+      {
+        "name": "prereleases",
+        "type": "boolean",
+        "default": false,
+        "required": false,
+        "help": "Include prerelease and build versions (e.g. alpha, beta, rc, canary)"
+      }
+    ],
+    "columns": [
+      "version",
+      "publishedAt",
+      "isLatest",
+      "url"
+    ],
+    "type": "js",
+    "modulePath": "plugins/npm/versions.js",
+    "sourceFile": "plugins/npm/versions.js"
+  },
   {
     "site": "nuget",
     "name": "package",
@@ -17607,6 +17648,50 @@
     "modulePath": "plugins/omnisearch/lobsters.js",
     "sourceFile": "plugins/omnisearch/lobsters.js"
   },
+  {
+    "site": "omnisearch",
+    "name": "packages",
+    "description": "Search across 6 major package registries simultaneously (npm, Crates.io, NuGet, RubyGems, Packagist, Maven Central)",
+    "access": "read",
+    "strategy": "public",
+    "browser": false,
+    "args": [
+      {
+        "name": "query",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Library name or search keyword"
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 10,
+        "required": false,
+        "help": "Maximum total results to return"
+      },
+      {
+        "name": "registries",
+        "type": "str",
+        "default": "npm,crates,nuget,rubygems,packagist,maven",
+        "required": false,
+        "help": "Comma-separated registries to query (default: all)"
+      }
+    ],
+    "columns": [
+      "registry",
+      "name",
+      "version",
+      "description",
+      "url"
+    ],
+    "tags": [
+      "search"
+    ],
+    "type": "js",
+    "modulePath": "plugins/omnisearch/packages.js",
+    "sourceFile": "plugins/omnisearch/packages.js"
+  },
   {
     "site": "omnisearch",
     "name": "research",
diff --git a/plugins/omnisearch/packages.js b/plugins/omnisearch/packages.js
new file mode 100644
index 00000000..20138153
--- /dev/null
+++ b/plugins/omnisearch/packages.js
@@ -0,0 +1,196 @@
+/**
+ * omnisearch packages — aggregate library searches across package registries.
+ *
+ * Parallel-queries npm, crates.io, NuGet, RubyGems, Packagist, and Maven Central.
+ * Returns normalized rows. Useful for agents checking library support/availability.
+ */
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@agentrhq/webcmd/errors';
+
+const UA = 'webcmd-omnisearch-packages (+https://github.com/agentrhq/webcmd)';
+
+async function get(url, init, { source } = {}) {
+  let res;
+  try {
+    res = await fetch(url, {
+      ...init,
+      headers: {
+        'user-agent': UA,
+        accept: 'application/json',
+        ...(init?.headers ?? {}),
+      },
+    });
+  } catch (err) {
+    throw new CommandExecutionError(
+      `OmniSearch: ${source} request failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (!res.ok) {
+    throw new CommandExecutionError(`OmniSearch: ${source} HTTP ${res.status}`);
+  }
+  return res;
+}
+
+// Fetchers
+async function npmSearch(query, limit) {
+  const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`;
+  const res = await get(url, {}, { source: 'npm' });
+  const body = await res.json();
+  const list = Array.isArray(body?.objects) ? body.objects : [];
+  return list.slice(0, limit).map((item) => {
+    const pkg = item?.package ?? {};
+    return {
+      registry: 'npm',
+      name: String(pkg.name ?? ''),
+      version: String(pkg.version ?? ''),
+      description: String(pkg.description ?? '').trim(),
+      url: pkg.links?.npm ? String(pkg.links.npm) : (pkg.name ? `https://www.npmjs.com/package/${pkg.name}` : ''),
+    };
+  });
+}
+
+async function cratesSearch(query, limit) {
+  const url = `https://crates.io/api/v1/crates?q=${encodeURIComponent(query)}&per_page=${limit}`;
+  const res = await get(url, {}, { source: 'crates' });
+  const body = await res.json();
+  const list = Array.isArray(body?.crates) ? body.crates : [];
+  return list.slice(0, limit).map((c) => ({
+    registry: 'crates',
+    name: String(c.name ?? c.id ?? ''),
+    version: String(c.newest_version ?? c.max_stable_version ?? c.max_version ?? ''),
+    description: String(c.description ?? '').trim(),
+    url: c.name ? `https://crates.io/crates/${c.name}` : '',
+  }));
+}
+
+async function nugetSearch(query, limit) {
+  const url = `https://azuresearch-usnc.nuget.org/query?q=${encodeURIComponent(query)}&take=${limit}&prerelease=false`;
+  const res = await get(url, {}, { source: 'nuget' });
+  const body = await res.json();
+  const list = Array.isArray(body?.data) ? body.data : [];
+  return list.slice(0, limit).map((pkg) => ({
+    registry: 'nuget',
+    name: String(pkg.id ?? ''),
+    version: String(pkg.version ?? ''),
+    description: String(pkg.description ?? '').trim(),
+    url: pkg.id ? `https://www.nuget.org/packages/${pkg.id}` : '',
+  }));
+}
+
+async function rubygemsSearch(query, limit) {
+  const url = `https://rubygems.org/api/v1/search.json?query=${encodeURIComponent(query)}&page=1`;
+  const res = await get(url, {}, { source: 'rubygems' });
+  const body = await res.json();
+  const list = Array.isArray(body) ? body : [];
+  return list.slice(0, limit).map((g) => {
+    const name = String(g.name ?? '').trim();
+    return {
+      registry: 'rubygems',
+      name,
+      version: String(g.version ?? '').trim(),
+      description: String(g.info ?? '').trim(),
+      url: name ? `https://rubygems.org/gems/${name}` : '',
+    };
+  });
+}
+
+async function packagistSearch(query, limit) {
+  const url = `https://packagist.org/search.json?q=${encodeURIComponent(query)}&per_page=${limit}`;
+  const res = await get(url, {}, { source: 'packagist' });
+  const body = await res.json();
+  const list = Array.isArray(body?.results) ? body.results : [];
+  return list.slice(0, limit).map((row) => ({
+    registry: 'packagist',
+    name: String(row.name ?? '').trim(),
+    version: '',
+    description: String(row.description ?? '').trim(),
+    url: String(row.url ?? '').trim(),
+  }));
+}
+
+async function mavenSearch(query, limit) {
+  const url = `https://search.maven.org/solrsearch/select?q=${encodeURIComponent(query)}&rows=${limit}&wt=json`;
+  const res = await get(url, {}, { source: 'maven' });
+  const body = await res.json();
+  const list = Array.isArray(body?.response?.docs) ? body.response.docs : [];
+  return list.slice(0, limit).map((d) => {
+    const groupId = String(d.g ?? '').trim();
+    const artifactId = String(d.a ?? '').trim();
+    const coord = groupId && artifactId ? `${groupId}:${artifactId}` : '';
+    return {
+      registry: 'maven',
+      name: coord,
+      version: String(d.latestVersion ?? '').trim(),
+      description: `${d.p ?? ''} package`,
+      url: coord ? `https://central.sonatype.com/artifact/${groupId}/${artifactId}` : '',
+    };
+  });
+}
+
+function requireQuery(value) {
+  const s = String(value ?? '').trim();
+  if (!s) throw new ArgumentError('a search query is required');
+  return s;
+}
+
+cli({
+  site: 'omnisearch',
+  name: 'packages',
+  tags: ['search'],
+  access: 'read',
+  description: 'Search across 6 major package registries simultaneously (npm, Crates.io, NuGet, RubyGems, Packagist, Maven Central)',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'query', positional: true, required: true, help: 'Library name or search keyword' },
+    { name: 'limit', type: 'int', default: 10, help: 'Maximum total results to return' },
+    {
+      name: 'registries',
+      default: 'npm,crates,nuget,rubygems,packagist,maven',
+      help: 'Comma-separated registries to query (default: all)',
+    },
+  ],
+  columns: ['registry', 'name', 'version', 'description', 'url'],
+  func: async (kwargs) => {
+    const query = requireQuery(kwargs.query);
+    const raw = Number(kwargs.limit ?? 10);
+    if (!Number.isInteger(raw) || raw <= 0) {
+      throw new ArgumentError('limit must be a positive integer');
+    }
+    const limit = Math.min(raw, 50);
+
+    const wanted = String(kwargs.registries ?? '')
+      .split(',')
+      .map((s) => s.trim().toLowerCase())
+      .filter(Boolean);
+
+    const fetchers = {
+      npm: () => npmSearch(query, perRegistry),
+      crates: () => cratesSearch(query, perRegistry),
+      nuget: () => nugetSearch(query, perRegistry),
+      rubygems: () => rubygemsSearch(query, perRegistry),
+      packagist: () => packagistSearch(query, perRegistry),
+      maven: () => mavenSearch(query, perRegistry),
+    };
+
+    const selected = wanted.length ? wanted.filter((s) => fetchers[s]) : Object.keys(fetchers);
+    const perRegistry = Math.ceil(limit / Math.max(selected.length, 1));
+
+    let rows = [];
+    try {
+      // Failure isolation: one rate-limited or erroring registry must not wipe out the others.
+      const outcomes = await Promise.allSettled(selected.map((key) => fetchers[key]()));
+      rows = outcomes
+        .filter((o) => o.status === 'fulfilled')
+        .flatMap((o) => o.value);
+    } catch (err) {
+      throw new CommandExecutionError(`packages aggregation failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    if (!rows.length) {
+      throw new EmptyResultError('omnisearch/packages', `no packages found across registries for "${query}"`);
+    }
+
+    return rows.slice(0, limit);
+  },
+});
diff --git a/plugins/omnisearch/test/packages.test.js b/plugins/omnisearch/test/packages.test.js
new file mode 100644
index 00000000..683e97ba
--- /dev/null
+++ b/plugins/omnisearch/test/packages.test.js
@@ -0,0 +1,199 @@
+import assert from 'node:assert/strict';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@agentrhq/webcmd/registry';
+import '../packages.js';
+
+afterEach(() => vi.unstubAllGlobals());
+
+// Mock payloads
+const NPM_PAYLOAD = {
+  objects: [
+    {
+      package: {
+        name: 'lodash',
+        version: '4.17.21',
+        description: 'Lodash utilities',
+        links: { npm: 'https://www.npmjs.com/package/lodash' },
+      },
+    },
+  ],
+};
+
+const CRATES_PAYLOAD = {
+  crates: [
+    {
+      name: 'serde',
+      max_version: '1.0.152',
+      description: 'A generic serialization/deserialization framework',
+    },
+  ],
+};
+
+const NUGET_PAYLOAD = {
+  data: [
+    {
+      id: 'Newtonsoft.Json',
+      version: '13.0.1',
+      description: 'Json.NET is a popular high-performance JSON framework',
+    },
+  ],
+};
+
+const RUBYGEMS_PAYLOAD = [
+  {
+    name: 'rails',
+    version: '7.0.4',
+    info: 'Ruby on Rails is a full-stack web framework',
+  },
+];
+
+const PACKAGIST_PAYLOAD = {
+  results: [
+    {
+      name: 'monolog/monolog',
+      description: 'Sends your logs to files, sockets, inboxes, databases',
+      url: 'https://packagist.org/packages/monolog/monolog',
+    },
+  ],
+};
+
+const MAVEN_PAYLOAD = {
+  response: {
+    docs: [
+      {
+        g: 'com.google.guava',
+        a: 'guava',
+        latestVersion: '31.1-jre',
+        p: 'jar',
+      },
+    ],
+  },
+};
+
+function stubRegistryFetch(handler) {
+  vi.stubGlobal('fetch', async (url) => {
+    const resBody = handler(String(url));
+    if (!resBody) {
+      return new Response('Not Found', { status: 404 });
+    }
+    return new Response(JSON.stringify(resBody), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  });
+}
+
+describe('omnisearch packages integration', () => {
+  it('queries all registries and returns a unified schema by default', async () => {
+    stubRegistryFetch((url) => {
+      if (url.includes('registry.npmjs.org')) return NPM_PAYLOAD;
+      if (url.includes('crates.io')) return CRATES_PAYLOAD;
+      if (url.includes('nuget.org')) return NUGET_PAYLOAD;
+      if (url.includes('rubygems.org')) return RUBYGEMS_PAYLOAD;
+      if (url.includes('packagist.org')) return PACKAGIST_PAYLOAD;
+      if (url.includes('search.maven.org')) return MAVEN_PAYLOAD;
+      return null;
+    });
+
+    const command = getRegistry().get('omnisearch/packages');
+    const rows = await command.func({ query: 'test', limit: 6 });
+
+    expect(rows).toHaveLength(6);
+
+    // npm
+    const npmRow = rows.find((r) => r.registry === 'npm');
+    expect(npmRow).toBeDefined();
+    expect(npmRow.name).toBe('lodash');
+    expect(npmRow.version).toBe('4.17.21');
+    expect(npmRow.description).toBe('Lodash utilities');
+    expect(npmRow.url).toBe('https://www.npmjs.com/package/lodash');
+
+    // crates
+    const cratesRow = rows.find((r) => r.registry === 'crates');
+    expect(cratesRow).toBeDefined();
+    expect(cratesRow.name).toBe('serde');
+    expect(cratesRow.version).toBe('1.0.152');
+    expect(cratesRow.description).toContain('serialization');
+    expect(cratesRow.url).toBe('https://crates.io/crates/serde');
+
+    // nuget
+    const nugetRow = rows.find((r) => r.registry === 'nuget');
+    expect(nugetRow).toBeDefined();
+    expect(nugetRow.name).toBe('Newtonsoft.Json');
+    expect(nugetRow.version).toBe('13.0.1');
+    expect(nugetRow.url).toBe('https://www.nuget.org/packages/Newtonsoft.Json');
+
+    // rubygems
+    const rubygemsRow = rows.find((r) => r.registry === 'rubygems');
+    expect(rubygemsRow).toBeDefined();
+    expect(rubygemsRow.name).toBe('rails');
+    expect(rubygemsRow.version).toBe('7.0.4');
+
+    // packagist
+    const packagistRow = rows.find((r) => r.registry === 'packagist');
+    expect(packagistRow).toBeDefined();
+    expect(packagistRow.name).toBe('monolog/monolog');
+    expect(packagistRow.url).toBe('https://packagist.org/packages/monolog/monolog');
+
+    // maven
+    const mavenRow = rows.find((r) => r.registry === 'maven');
+    expect(mavenRow).toBeDefined();
+    expect(mavenRow.name).toBe('com.google.guava:guava');
+    expect(mavenRow.version).toBe('31.1-jre');
+  });
+
+  it('respects the registries filter', async () => {
+    stubRegistryFetch((url) => {
+      if (url.includes('registry.npmjs.org')) return NPM_PAYLOAD;
+      if (url.includes('crates.io')) return CRATES_PAYLOAD;
+      return null;
+    });
+
+    const command = getRegistry().get('omnisearch/packages');
+    const rows = await command.func({ query: 'json', limit: 10, registries: 'npm,crates' });
+
+    expect(rows).toHaveLength(2);
+    expect(rows.map((r) => r.registry).sort()).toEqual(['crates', 'npm']);
+  });
+
+  it('respects total limit', async () => {
+    stubRegistryFetch((url) => {
+      if (url.includes('registry.npmjs.org')) return NPM_PAYLOAD;
+      if (url.includes('crates.io')) return CRATES_PAYLOAD;
+      return null;
+    });
+
+    const command = getRegistry().get('omnisearch/packages');
+    const rows = await command.func({ query: 'json', limit: 1, registries: 'npm,crates' });
+
+    expect(rows).toHaveLength(1);
+  });
+
+  it('tolerates failure of one or more registries (failure isolation)', async () => {
+    vi.stubGlobal('fetch', async (url) => {
+      if (url.includes('registry.npmjs.org')) {
+        return new Response('Rate Limited', { status: 429 });
+      }
+      if (url.includes('crates.io')) {
+        return new Response(JSON.stringify(CRATES_PAYLOAD), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+      return new Response('Not Found', { status: 404 });
+    });
+
+    const command = getRegistry().get('omnisearch/packages');
+    // Even though npm failed (429), crates.io succeeded, so we still get results
+    const rows = await command.func({ query: 'json', limit: 5, registries: 'npm,crates' });
+    expect(rows).toHaveLength(1);
+    expect(rows[0].registry).toBe('crates');
+    expect(rows[0].name).toBe('serde');
+  });
+
+  it('is registered as browser: false', () => {
+    const command = getRegistry().get('omnisearch/packages');
+    expect(command).toBeDefined();
+    expect(command.browser).toBe(false);
+  });
+});

From b19a1900dc0207b08a1b39e95104186a7834a23e Mon Sep 17 00:00:00 2001
From: Sreeram Akhil <akhilsreeram663@gmail.com>
Date: Tue, 25 Aug 2026 18:33:55 +0530
Subject: [PATCH 11/11] fix(omnisearch,npm): add fetch timeouts and resolve
 closure initialization order

---
 plugins/npm/test/npm.test.js             | 17 ++++++++++++++++-
 plugins/npm/utils.js                     |  5 ++++-
 plugins/omnisearch/packages.js           | 15 ++++++++-------
 plugins/omnisearch/research.js           | 16 ++++++++--------
 plugins/omnisearch/sources.js            |  5 ++++-
 plugins/omnisearch/test/packages.test.js | 16 ++++++++++++++++
 plugins/omnisearch/test/research.test.js | 21 +++++++++++++++++++++
 7 files changed, 77 insertions(+), 18 deletions(-)

diff --git a/plugins/npm/test/npm.test.js b/plugins/npm/test/npm.test.js
index 1ea7d96d..4f921ea7 100644
--- a/plugins/npm/test/npm.test.js
+++ b/plugins/npm/test/npm.test.js
@@ -95,11 +95,13 @@ const SEARCH_PAYLOAD = {
 // Helpers
 // ---------------------------------------------------------------------------
 function fakeRequest(payload, { ok = true, status = 200 } = {}) {
-    const req = async (url, _opts) => {
+    const req = async (url, opts) => {
         req.calls.push(String(url));
+        req.opts.push(opts);
         return { ok, status, json: async () => payload };
     };
     req.calls = [];
+    req.opts = [];
     return req;
 }
 
@@ -371,3 +373,16 @@ test('all npm commands are browser-free', () => {
         assert.equal(cmd.browser, false, `${name} should not require a browser`);
     }
 });
+
+test('npm commands pass a 10-second timeout AbortSignal to fetch requests', async () => {
+    const req = fakeRequest(REGISTRY_PAYLOAD);
+    const original = globalThis.fetch;
+    globalThis.fetch = req;
+    try {
+        await versionsNpm({ name: 'exlib' });
+        assert.equal(req.opts.length, 1);
+        assert.ok(req.opts[0].signal instanceof AbortSignal);
+    } finally {
+        globalThis.fetch = original;
+    }
+});
diff --git a/plugins/npm/utils.js b/plugins/npm/utils.js
index fd2aaaed..8e0c4f2b 100644
--- a/plugins/npm/utils.js
+++ b/plugins/npm/utils.js
@@ -45,7 +45,10 @@ export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit'
 export async function npmFetch(url, label) {
     let resp;
     try {
-        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+        resp = await fetch(url, {
+            headers: { 'user-agent': UA, accept: 'application/json' },
+            signal: AbortSignal.timeout(10_000),
+        });
     }
     catch (err) {
         throw new CommandExecutionError(
diff --git a/plugins/omnisearch/packages.js b/plugins/omnisearch/packages.js
index 20138153..9f11b9f4 100644
--- a/plugins/omnisearch/packages.js
+++ b/plugins/omnisearch/packages.js
@@ -13,6 +13,7 @@ async function get(url, init, { source } = {}) {
   let res;
   try {
     res = await fetch(url, {
+      signal: AbortSignal.timeout(10_000),
       ...init,
       headers: {
         'user-agent': UA,
@@ -165,12 +166,12 @@ cli({
       .filter(Boolean);
 
     const fetchers = {
-      npm: () => npmSearch(query, perRegistry),
-      crates: () => cratesSearch(query, perRegistry),
-      nuget: () => nugetSearch(query, perRegistry),
-      rubygems: () => rubygemsSearch(query, perRegistry),
-      packagist: () => packagistSearch(query, perRegistry),
-      maven: () => mavenSearch(query, perRegistry),
+      npm: (lim) => npmSearch(query, lim),
+      crates: (lim) => cratesSearch(query, lim),
+      nuget: (lim) => nugetSearch(query, lim),
+      rubygems: (lim) => rubygemsSearch(query, lim),
+      packagist: (lim) => packagistSearch(query, lim),
+      maven: (lim) => mavenSearch(query, lim),
     };
 
     const selected = wanted.length ? wanted.filter((s) => fetchers[s]) : Object.keys(fetchers);
@@ -179,7 +180,7 @@ cli({
     let rows = [];
     try {
       // Failure isolation: one rate-limited or erroring registry must not wipe out the others.
-      const outcomes = await Promise.allSettled(selected.map((key) => fetchers[key]()));
+      const outcomes = await Promise.allSettled(selected.map((key) => fetchers[key](perRegistry)));
       rows = outcomes
         .filter((o) => o.status === 'fulfilled')
         .flatMap((o) => o.value);
diff --git a/plugins/omnisearch/research.js b/plugins/omnisearch/research.js
index 31c9dc8d..684f91cb 100644
--- a/plugins/omnisearch/research.js
+++ b/plugins/omnisearch/research.js
@@ -56,13 +56,13 @@ cli({
       .filter(Boolean);
 
     const fetchers = {
-      hn: () => hnSearch(query, perPlatform),
-      lobsters: () => lobstersSearch(query, perPlatform),
-      stackoverflow: () => stackoverflowSearch(query, perPlatform),
-      devto: () => devtoSearch(query, perPlatform),
-      github: () => githubSearch(query, perPlatform),
-      arxiv: () => arxivSearch(query, perPlatform),
-      reddit: () => redditSearch(query, perPlatform),
+      hn: (lim) => hnSearch(query, lim),
+      lobsters: (lim) => lobstersSearch(query, lim),
+      stackoverflow: (lim) => stackoverflowSearch(query, lim),
+      devto: (lim) => devtoSearch(query, lim),
+      github: (lim) => githubSearch(query, lim),
+      arxiv: (lim) => arxivSearch(query, lim),
+      reddit: (lim) => redditSearch(query, lim),
     };
 
     const selected = wanted.length ? wanted.filter((s) => fetchers[s]) : Object.keys(fetchers);
@@ -71,7 +71,7 @@ cli({
     let rows;
     try {
       // Failure isolation: one rate-limited/erroring source must not wipe out the rest.
-      const outcomes = await Promise.allSettled(selected.map((key) => fetchers[key]()));
+      const outcomes = await Promise.allSettled(selected.map((key) => fetchers[key](perPlatform)));
       rows = outcomes
         .filter((o) => o.status === 'fulfilled')
         .flatMap((o) => o.value);
diff --git a/plugins/omnisearch/sources.js b/plugins/omnisearch/sources.js
index 72ab7cbe..93d23095 100644
--- a/plugins/omnisearch/sources.js
+++ b/plugins/omnisearch/sources.js
@@ -10,7 +10,10 @@ import { CommandExecutionError } from '@agentrhq/webcmd/errors';
 async function get(url, init, { source } = {}) {
   let res;
   try {
-    res = await fetch(url, init);
+    res = await fetch(url, {
+      signal: AbortSignal.timeout(10_000),
+      ...init,
+    });
   } catch (err) {
     throw new CommandExecutionError(
       `OmniSearch: ${source} request failed: ${err instanceof Error ? err.message : String(err)}`,
diff --git a/plugins/omnisearch/test/packages.test.js b/plugins/omnisearch/test/packages.test.js
index 683e97ba..c0e894ef 100644
--- a/plugins/omnisearch/test/packages.test.js
+++ b/plugins/omnisearch/test/packages.test.js
@@ -196,4 +196,20 @@ describe('omnisearch packages integration', () => {
     expect(command).toBeDefined();
     expect(command.browser).toBe(false);
   });
+
+  it('passes a 10-second timeout AbortSignal to fetch', async () => {
+    let passedSignal = null;
+    vi.stubGlobal('fetch', async (url, init) => {
+      passedSignal = init?.signal;
+      return new Response(JSON.stringify(NPM_PAYLOAD), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    });
+
+    const command = getRegistry().get('omnisearch/packages');
+    await command.func({ query: 'lodash', limit: 1, registries: 'npm' });
+
+    expect(passedSignal).toBeInstanceOf(AbortSignal);
+  });
 });
diff --git a/plugins/omnisearch/test/research.test.js b/plugins/omnisearch/test/research.test.js
index 98e9a3dc..bbf08302 100644
--- a/plugins/omnisearch/test/research.test.js
+++ b/plugins/omnisearch/test/research.test.js
@@ -274,4 +274,25 @@ describe('omnisearch research — limit enforcement', () => {
     const rows = await command.func({ query: 'webcmd', limit: 5, sources: 'hn' });
     expect(rows.map((row) => row.title)).toEqual(['One', 'Two', 'Three', 'Four', 'Five']);
   });
+
+  it('passes a 10-second timeout AbortSignal to all fetch requests', async () => {
+    let passedSignals = [];
+    vi.stubGlobal('fetch', async (url, init) => {
+      passedSignals.push(init?.signal);
+      return new Response(JSON.stringify(hnResponse([])), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    });
+
+    const command = getRegistry().get('omnisearch/research');
+    try {
+      await command.func({ query: 'test', limit: 1, sources: 'hn' });
+    } catch (err) {
+      // Ignore EmptyResultError if empty results returned
+    }
+
+    expect(passedSignals.length).toBeGreaterThan(0);
+    expect(passedSignals[0]).toBeInstanceOf(AbortSignal);
+  });
 });