@jackwener/opencli 1.7.11 → 1.7.13

package/clis/lobsters/domain.js

@@ -0,0 +1,92 @@
+// lobsters domain — list Lobste.rs stories submitted from a specific domain.
+//
+// Hits the public `https://lobste.rs/domains/<domain>.json` endpoint
+// (returns the same per-story shape used by `lobsters tag` / `lobsters
+// hot`). Lets agents ask "what did Lobsters surface from github.com /
+// blog.cloudflare.com / arxiv.org lately?".
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const DOMAIN_PATTERN = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+
+function requireDomain(value) {
+    const s = String(value ?? '').trim().toLowerCase();
+    if (!s) {
+        throw new ArgumentError('lobsters domain is required (e.g. "github.com" or "arxiv.org")');
+    }
+    if (!DOMAIN_PATTERN.test(s)) {
+        throw new ArgumentError(`lobsters domain "${value}" is not a valid hostname`);
+    }
+    return s;
+}
+
+function requireBoundedInt(value, defaultValue, maxValue) {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError('lobsters limit must be a positive integer');
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`lobsters limit must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+cli({
+    site: 'lobsters',
+    name: 'domain',
+    access: 'read',
+    description: 'Lobste.rs stories submitted from a specific domain',
+    domain: 'lobste.rs',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'domain', positional: true, required: true, help: 'Source domain (e.g. github.com, arxiv.org, blog.cloudflare.com)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Number of stories (1-25 — single page)' },
+    ],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'created_at', 'tags', 'submission_url', 'comments_url'],
+    func: async (args) => {
+        const domain = requireDomain(args.domain);
+        const limit = requireBoundedInt(args.limit, 20, 25);
+        const url = `https://lobste.rs/domains/${encodeURIComponent(domain)}.json`;
+        let resp;
+        try {
+            resp = await fetch(url, { headers: { 'user-agent': 'opencli-lobsters-adapter (+https://github.com/jackwener/opencli)' } });
+        }
+        catch (err) {
+            throw new CommandExecutionError(
+                `lobsters domain request failed: ${err?.message ?? err}`,
+                'Check that lobste.rs is reachable from this network.',
+            );
+        }
+        if (resp.status === 404) {
+            throw new EmptyResultError('lobsters domain', `No Lobste.rs stories found for domain "${domain}".`);
+        }
+        if (!resp.ok) {
+            throw new CommandExecutionError(`lobsters domain returned HTTP ${resp.status}`);
+        }
+        let body;
+        try {
+            body = await resp.json();
+        }
+        catch (err) {
+            throw new CommandExecutionError(`lobsters domain returned malformed JSON: ${err?.message ?? err}`);
+        }
+        const list = Array.isArray(body) ? body : [];
+        if (!list.length) {
+            throw new EmptyResultError('lobsters domain', `No Lobste.rs stories found for domain "${domain}".`);
+        }
+        return list.slice(0, limit).map((item, i) => ({
+            rank: i + 1,
+            id: String(item.short_id ?? ''),
+            title: String(item.title ?? ''),
+            score: item.score != null ? Number(item.score) : null,
+            author: String(item.submitter_user ?? ''),
+            comments: item.comment_count != null ? Number(item.comment_count) : null,
+            created_at: String(item.created_at ?? '').slice(0, 10),
+            tags: Array.isArray(item.tags) ? item.tags.join(', ') : '',
+            submission_url: String(item.url ?? ''),
+            comments_url: String(item.comments_url ?? ''),
+        }));
+    },
+});

package/clis/lobsters/hot.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'lobsters',
     name: 'hot',
+    access: 'read',
     description: 'Lobste.rs hottest stories',
     domain: 'lobste.rs',
     strategy: Strategy.PUBLIC,
@@ -9,15 +10,17 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
     ],
-    columns: ['rank', 'title', 'score', 'author', 'comments', 'tags'],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'created_at', 'tags', 'url'],
     pipeline: [
         { fetch: { url: 'https://lobste.rs/hottest.json' } },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.short_id }}',
                 title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 author: '${{ item.submitter_user }}',
                 comments: '${{ item.comment_count }}',
+                created_at: '${{ item.created_at }}',
                 tags: `\${{ item.tags | join(', ') }}`,
                 url: '${{ item.comments_url }}',
             } },

package/clis/lobsters/lobsters.test.js

@@ -0,0 +1,169 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './hot.js';
+import './active.js';
+import './newest.js';
+import './tag.js';
+import './read.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('lobsters listing adapters expose short_id and created_at', () => {
+    const listings = ['lobsters/hot', 'lobsters/active', 'lobsters/newest', 'lobsters/tag'];
+
+    listings.forEach((key) => {
+        it(`${key} surfaces id (short_id) and created_at on every row`, () => {
+            const cmd = getRegistry().get(key);
+            expect(cmd?.columns).toEqual(['rank', 'id', 'title', 'score', 'author', 'comments', 'created_at', 'tags', 'url']);
+            const mapStep = cmd?.pipeline?.find((step) => step.map);
+            expect(mapStep?.map).toMatchObject({
+                id: '${{ item.short_id }}',
+                created_at: '${{ item.created_at }}',
+                url: '${{ item.comments_url }}',
+            });
+        });
+    });
+});
+
+describe('lobsters/read adapter', () => {
+    const cmd = getRegistry().get('lobsters/read');
+
+    it('registers the comment-thread shape (type/author/score/text)', () => {
+        expect(cmd?.columns).toEqual(['type', 'author', 'score', 'text']);
+    });
+
+    it('takes a positional short_id plus tunable depth/limit/replies/max-length args', () => {
+        const argNames = (cmd?.args || []).map((a) => a.name);
+        expect(argNames).toEqual(['id', 'limit', 'depth', 'replies', 'max-length']);
+        const idArg = cmd?.args?.find((a) => a.name === 'id');
+        expect(idArg?.required).toBe(true);
+        expect(idArg?.positional).toBe(true);
+    });
+
+    it('uses the public lobste.rs JSON endpoint (no browser, public strategy)', () => {
+        expect(cmd?.browser).toBe(false);
+        expect(cmd?.strategy).toBe('public');
+    });
+
+    it('fails fast with ArgumentError for non-alphanumeric short_id before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ id: 'BAD!ID', limit: 5, depth: 2, replies: 5, 'max-length': 2000 }))
+            .rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('fails fast with EmptyResultError on 404', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('Not found', { status: 404 })));
+
+        await expect(cmd.func({ id: 'missing', limit: 5, depth: 2, replies: 5, 'max-length': 2000 }))
+            .rejects.toThrow(EmptyResultError);
+    });
+
+    it('fails fast with ArgumentError when max-length is below the minimum before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ id: 'abc123', limit: 5, depth: 2, replies: 5, 'max-length': 99 }))
+            .rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('fails fast with CommandExecutionError on non-404 HTTP failures', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('oops', { status: 503 })));
+
+        await expect(cmd.func({ id: 'abc123', limit: 5, depth: 2, replies: 5, 'max-length': 2000 }))
+            .rejects.toThrow(CommandExecutionError);
+    });
+
+    it('builds a threaded tree from the flat comments[] using parent_comment', async () => {
+        const story = {
+            short_id: 'abc123',
+            title: 'Hello world',
+            url: 'https://example.com/post',
+            score: 42,
+            submitter_user: 'pg',
+            description_plain: 'Some intro text.',
+            comments_url: 'https://lobste.rs/s/abc123/hello_world',
+            comments: [
+                {
+                    short_id: 'top1',
+                    parent_comment: null,
+                    score: 5,
+                    commenting_user: 'alice',
+                    comment_plain: 'Top one',
+                    is_deleted: false,
+                },
+                {
+                    short_id: 'reply1',
+                    parent_comment: 'top1',
+                    score: 3,
+                    commenting_user: 'bob',
+                    comment_plain: 'A reply',
+                    is_deleted: false,
+                },
+                {
+                    short_id: 'reply2',
+                    parent_comment: 'top1',
+                    score: 1,
+                    commenting_user: 'carol',
+                    comment_plain: 'Another reply',
+                    is_deleted: false,
+                },
+                {
+                    short_id: 'top2',
+                    parent_comment: null,
+                    score: 4,
+                    commenting_user: 'dave',
+                    comment_plain: 'Top two',
+                    is_deleted: false,
+                },
+            ],
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(story), { status: 200 })));
+
+        const rows = await cmd.func({ id: 'abc123', limit: 5, depth: 2, replies: 5, 'max-length': 2000 });
+
+        expect(rows).toEqual([
+            {
+                type: 'POST',
+                author: 'pg',
+                score: 42,
+                text: 'Hello world\nSome intro text.\nhttps://example.com/post',
+            },
+            { type: 'L0', author: 'alice', score: 5, text: 'Top one' },
+            { type: 'L1', author: 'bob', score: 3, text: '  > A reply' },
+            { type: 'L1', author: 'carol', score: 1, text: '  > Another reply' },
+            { type: 'L0', author: 'dave', score: 4, text: 'Top two' },
+        ]);
+    });
+
+    it('emits a "+N more replies" stub when depth cutoff hides children', async () => {
+        const story = {
+            short_id: 'abc123',
+            title: 'Hi',
+            url: '',
+            score: 1,
+            submitter_user: 'u',
+            description_plain: '',
+            comments: [
+                { short_id: 't1', parent_comment: null, commenting_user: 'a', comment_plain: 'top', is_deleted: false },
+                { short_id: 'r1', parent_comment: 't1', commenting_user: 'b', comment_plain: 'r', is_deleted: false },
+            ],
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(story), { status: 200 })));
+
+        const rows = await cmd.func({ id: 'abc123', limit: 5, depth: 1, replies: 5, 'max-length': 2000 });
+
+        expect(rows).toEqual([
+            { type: 'POST', author: 'u', score: 1, text: 'Hi' },
+            { type: 'L0', author: 'a', score: '', text: 'top' },
+            { type: 'L1', author: '', score: '', text: '  [+1 more replies]' },
+        ]);
+    });
+});

package/clis/lobsters/newest.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'lobsters',
     name: 'newest',
+    access: 'read',
     description: 'Lobste.rs newest stories',
     domain: 'lobste.rs',
     strategy: Strategy.PUBLIC,
@@ -9,15 +10,17 @@ cli({
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
     ],
-    columns: ['rank', 'title', 'score', 'author', 'comments', 'tags'],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'created_at', 'tags', 'url'],
     pipeline: [
         { fetch: { url: 'https://lobste.rs/newest.json' } },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.short_id }}',
                 title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 author: '${{ item.submitter_user }}',
                 comments: '${{ item.comment_count }}',
+                created_at: '${{ item.created_at }}',
                 tags: `\${{ item.tags | join(', ') }}`,
                 url: '${{ item.comments_url }}',
             } },

package/clis/lobsters/read.js

@@ -0,0 +1,196 @@
+/**
+ * Lobste.rs story reader with threaded comment tree.
+ *
+ * Mirrors `hackernews read` semantics. The lobsters JSON endpoint:
+ *   https://lobste.rs/s/<short_id>.json
+ * already returns the story plus a flat `comments[]` array where each entry
+ * carries `parent_comment` (short_id of parent or null) and `depth` — so we
+ * just need one HTTP call, then build a children map and DFS.
+ *
+ * Output rows:
+ *   - first row is the story itself (`type=POST`)
+ *   - each subsequent row is a comment, indented by depth (`L0`, `L1`, …)
+ *   - `[+N more replies]` summary rows whenever depth/limit cuts in
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const LOBSTERS_STORY_BASE = 'https://lobste.rs/s';
+
+async function fetchStory(shortId) {
+    const res = await fetch(`${LOBSTERS_STORY_BASE}/${shortId}.json`);
+    if (res.status === 404) {
+        throw new EmptyResultError(`lobsters/${shortId}`, 'Story not found');
+    }
+    if (!res.ok) {
+        throw new CommandExecutionError(`Lobsters API HTTP ${res.status} for story ${shortId}`, 'Check the short id');
+    }
+    return res.json();
+}
+
+function requirePositiveInt(value, label) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new ArgumentError(`${label} must be a positive integer`);
+    }
+    return value;
+}
+
+function requireMinInt(value, min, label) {
+    if (!Number.isInteger(value) || value < min) {
+        throw new ArgumentError(`${label} must be an integer >= ${min}`);
+    }
+    return value;
+}
+
+/** Lobsters returns comment text as a small HTML subset — convert to plain text. */
+function htmlToText(html) {
+    if (!html) return '';
+    return String(html)
+        .replace(/<p>/gi, '\n\n')
+        .replace(/<\/p>/gi, '')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<i>(.*?)<\/i>/gi, '$1')
+        .replace(/<em>(.*?)<\/em>/gi, '$1')
+        .replace(/<strong>(.*?)<\/strong>/gi, '$1')
+        .replace(/<a[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi, '$2 ($1)')
+        .replace(/<pre><code>([\s\S]*?)<\/code><\/pre>/gi, '\n$1\n')
+        .replace(/<code>(.*?)<\/code>/gi, '`$1`')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&#x27;/g, "'")
+        .replace(/&apos;/g, "'")
+        .replace(/&quot;/g, '"')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&#x2F;/g, '/')
+        .trim();
+}
+
+function indentLines(text, depth) {
+    if (depth === 0) return text;
+    const indent = '  '.repeat(depth);
+    const prefix = `${indent}> `;
+    return text.split('\n').map((line) => prefix + line).join('\n');
+}
+
+function moreRepliesIndent(depth) {
+    return '  '.repeat(depth + 1);
+}
+
+cli({
+    site: 'lobsters',
+    name: 'read',
+    access: 'read',
+    description: 'Read a Lobste.rs story and its comment tree',
+    domain: 'lobste.rs',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', required: true, positional: true, help: 'Lobste.rs short_id (e.g. 6cmh6h)' },
+        { name: 'limit', type: 'int', default: 25, help: 'Max top-level comments' },
+        { name: 'depth', type: 'int', default: 2, help: 'Max reply depth (1=no replies, 2=one level of replies, etc.)' },
+        { name: 'replies', type: 'int', default: 5, help: 'Max replies shown per comment at each level' },
+        { name: 'max-length', type: 'int', default: 2000, help: 'Max characters per comment body (min 100)' },
+    ],
+    columns: ['type', 'author', 'score', 'text'],
+    func: async (args) => {
+        const shortId = String(args.id || '').trim();
+        if (!/^[a-z0-9]+$/.test(shortId)) {
+            throw new ArgumentError(`Invalid Lobsters short_id: ${args.id}`, 'Pass a lowercase alphanumeric id like 6cmh6h');
+        }
+        const limit = requirePositiveInt(args.limit ?? 25, 'lobsters read --limit');
+        const maxDepth = requirePositiveInt(args.depth ?? 2, 'lobsters read --depth');
+        const maxReplies = requirePositiveInt(args.replies ?? 5, 'lobsters read --replies');
+        const maxLength = requireMinInt(args['max-length'] ?? 2000, 100, 'lobsters read --max-length');
+
+        const story = await fetchStory(shortId);
+        if (!story || !story.short_id) {
+            throw new EmptyResultError(`lobsters/${shortId}`, 'Story not found');
+        }
+
+        const results = [];
+
+        // Story header — title, body (description_plain, often empty for link posts), then external url.
+        const storyBodyRaw = (story.description_plain || htmlToText(story.description || '')).trim();
+        const storyBody = storyBodyRaw.length > maxLength
+            ? storyBodyRaw.slice(0, maxLength) + '\n... [truncated]'
+            : storyBodyRaw;
+        const storyParts = [story.title || ''];
+        if (storyBody) storyParts.push('\n' + storyBody);
+        if (story.url) storyParts.push('\n' + story.url);
+        results.push({
+            type: 'POST',
+            author: story.submitter_user || '[deleted]',
+            score: story.score ?? 0,
+            text: storyParts.join('').trim(),
+        });
+
+        // Build a map: parent_comment -> [child comments in order]. Top-level keyed by null.
+        const allComments = Array.isArray(story.comments) ? story.comments : [];
+        const childrenMap = new Map();
+        for (const c of allComments) {
+            const parent = c.parent_comment || null;
+            if (!childrenMap.has(parent)) childrenMap.set(parent, []);
+            childrenMap.get(parent).push(c);
+        }
+
+        function emit(comment, depth) {
+            if (!comment || comment.is_deleted || comment.is_moderated) return;
+            const bodyRaw = (comment.comment_plain || htmlToText(comment.comment || '')).trim();
+            const truncated = bodyRaw.length > maxLength
+                ? bodyRaw.slice(0, maxLength) + '...'
+                : bodyRaw;
+
+            results.push({
+                type: depth === 0 ? 'L0' : `L${depth}`,
+                author: comment.commenting_user || '[deleted]',
+                score: comment.score ?? '',
+                text: indentLines(truncated, depth),
+            });
+
+            const kids = childrenMap.get(comment.short_id) || [];
+            // At depth cutoff: don't recurse, but show a "+N more replies" stub if any.
+            if (depth + 1 >= maxDepth) {
+                if (kids.length > 0) {
+                    results.push({
+                        type: `L${depth + 1}`,
+                        author: '',
+                        score: '',
+                        text: `${moreRepliesIndent(depth)}[+${kids.length} more replies]`,
+                    });
+                }
+                return;
+            }
+
+            const toShow = kids.slice(0, maxReplies);
+            for (const kid of toShow) emit(kid, depth + 1);
+
+            const hidden = kids.length - toShow.length;
+            if (hidden > 0) {
+                results.push({
+                    type: `L${depth + 1}`,
+                    author: '',
+                    score: '',
+                    text: `${moreRepliesIndent(depth)}[+${hidden} more replies]`,
+                });
+            }
+        }
+
+        const topLevel = childrenMap.get(null) || [];
+        const topToShow = topLevel.slice(0, limit);
+        for (const top of topToShow) emit(top, 0);
+
+        const hiddenTopLevel = topLevel.length - topToShow.length;
+        if (hiddenTopLevel > 0) {
+            results.push({
+                type: '',
+                author: '',
+                score: '',
+                text: `[+${hiddenTopLevel} more top-level comments]`,
+            });
+        }
+
+        return results;
+    },
+});

package/clis/lobsters/tag.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
     site: 'lobsters',
     name: 'tag',
+    access: 'read',
     description: 'Lobste.rs stories by tag',
     domain: 'lobste.rs',
     strategy: Strategy.PUBLIC,
@@ -15,15 +16,17 @@ cli({
         },
         { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
     ],
-    columns: ['rank', 'title', 'score', 'author', 'comments', 'tags'],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'created_at', 'tags', 'url'],
     pipeline: [
         { fetch: { url: 'https://lobste.rs/t/${{ args.tag }}.json' } },
         { map: {
                 rank: '${{ index + 1 }}',
+                id: '${{ item.short_id }}',
                 title: '${{ item.title }}',
                 score: '${{ item.score }}',
                 author: '${{ item.submitter_user }}',
                 comments: '${{ item.comment_count }}',
+                created_at: '${{ item.created_at }}',
                 tags: `\${{ item.tags | join(', ') }}`,
                 url: '${{ item.comments_url }}',
             } },

package/clis/maimai/search-talents.js

@@ -7,6 +7,7 @@ import { cli, Strategy } from '@jackwener/opencli/registry';
 cli({
   site: 'maimai',
   name: 'search-talents',
+    access: 'read',
   description: 'Search for candidates on Maimai with multi-dimensional filters',
   domain: 'maimai.cn',
   strategy: Strategy.COOKIE,

package/clis/maven/artifact.js

@@ -0,0 +1,49 @@
+// maven artifact — fetch a Maven Central artifact's recent version history.
+//
+// Hits Solr's `gav` core (`q=g:<groupId>+AND+a:<artifactId>` with
+// `core=gav`) which returns one row per published version, newest first.
+// Returns the agent-useful projection: each version + publish timestamp +
+// packaging. If a specific `:version` is supplied, only that version is
+// returned.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { MAVEN_BASE, mavenFetch, epochMsToIso, requireBoundedInt, requireCoord } from './utils.js';
+
+cli({
+    site: 'maven',
+    name: 'artifact',
+    access: 'read',
+    description: 'Fetch a Maven Central artifact\'s version history (groupId:artifactId[:version])',
+    domain: 'search.maven.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'coordinate', positional: true, required: true, help: 'Maven coord "groupId:artifactId" or "groupId:artifactId:version"' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max versions (1-200, ignored when version is pinned)' },
+    ],
+    columns: ['groupId', 'artifactId', 'version', 'packaging', 'publishedAt', 'tags', 'url'],
+    func: async (args) => {
+        const { groupId, artifactId, version } = requireCoord(args.coordinate);
+        const limit = requireBoundedInt(args.limit, 20, 200);
+        const filters = [`g:${groupId}`, `a:${artifactId}`];
+        if (version) filters.push(`v:${version}`);
+        const q = filters.join(' AND ');
+        const rows = version ? 1 : limit;
+        const url = `${MAVEN_BASE}?q=${encodeURIComponent(q)}&core=gav&rows=${rows}&wt=json`;
+        const body = await mavenFetch(url, 'maven artifact');
+        const docs = Array.isArray(body?.response?.docs) ? body.response.docs : [];
+        const coordLabel = version ? `${groupId}:${artifactId}:${version}` : `${groupId}:${artifactId}`;
+        if (!docs.length) {
+            throw new EmptyResultError('maven artifact', `Maven Central has no published versions for ${coordLabel}.`);
+        }
+        return docs.map((d) => ({
+            groupId: String(d.g ?? groupId).trim(),
+            artifactId: String(d.a ?? artifactId).trim(),
+            version: String(d.v ?? '').trim(),
+            packaging: String(d.p ?? '').trim(),
+            publishedAt: epochMsToIso(d.timestamp),
+            tags: Array.isArray(d.tags) ? d.tags.filter(Boolean).join(', ') : '',
+            url: `https://central.sonatype.com/artifact/${groupId}/${artifactId}/${d.v ?? ''}`.replace(/\/$/, ''),
+        }));
+    },
+});

package/clis/maven/search.js

@@ -0,0 +1,51 @@
+// maven search — search Maven Central by free-text keyword.
+//
+// Hits the Solr endpoint at `https://search.maven.org/solrsearch/select`.
+// Returns the agent-useful projection: `groupId:artifactId` (round-trips
+// into `maven artifact`), latest version, packaging, version count, last
+// publish timestamp, repository.
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import { MAVEN_BASE, mavenFetch, epochMsToIso, requireBoundedInt, requireString } from './utils.js';
+
+cli({
+    site: 'maven',
+    name: 'search',
+    access: 'read',
+    description: 'Search Maven Central by keyword (artifact name, groupId, tag)',
+    domain: 'search.maven.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', positional: true, required: true, help: 'Search keyword (e.g. "jackson", "guava", "ai.koog")' },
+        { name: 'limit', type: 'int', default: 30, help: 'Max artifacts (1-200)' },
+    ],
+    columns: ['rank', 'coordinate', 'groupId', 'artifactId', 'latestVersion', 'packaging', 'versions', 'lastPublished', 'repository', 'url'],
+    func: async (args) => {
+        const query = requireString(args.query, 'query');
+        const limit = requireBoundedInt(args.limit, 30, 200);
+        const url = `${MAVEN_BASE}?q=${encodeURIComponent(query)}&rows=${limit}&wt=json`;
+        const body = await mavenFetch(url, 'maven search');
+        const docs = Array.isArray(body?.response?.docs) ? body.response.docs : [];
+        if (!docs.length) {
+            throw new EmptyResultError('maven search', `No Maven Central artifacts matched "${query}".`);
+        }
+        return docs.slice(0, limit).map((d, i) => {
+            const groupId = String(d.g ?? '').trim();
+            const artifactId = String(d.a ?? '').trim();
+            const coord = groupId && artifactId ? `${groupId}:${artifactId}` : '';
+            return {
+                rank: i + 1,
+                coordinate: coord,
+                groupId,
+                artifactId,
+                latestVersion: String(d.latestVersion ?? '').trim(),
+                packaging: String(d.p ?? '').trim(),
+                versions: d.versionCount != null ? Number(d.versionCount) : null,
+                lastPublished: epochMsToIso(d.timestamp),
+                repository: String(d.repositoryId ?? '').trim(),
+                url: coord ? `https://central.sonatype.com/artifact/${groupId}/${artifactId}` : '',
+            };
+        });
+    },
+});