@jackwener/opencli 1.7.12 → 1.7.13

package/clis/linkedin/search.test.js

@@ -0,0 +1,222 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError } from '@jackwener/opencli/errors';
+import { __test__ } from './search.js';
+
+const {
+    parseCsvArg,
+    parseIntegerArg,
+    mapFilterValues,
+    decodeLinkedinRedirect,
+    looksLinkedInAuthWallText,
+    enrichJobDetails,
+    EXPERIENCE_LEVELS,
+    JOB_TYPES,
+    DATE_POSTED,
+    REMOTE_TYPES,
+} = __test__;
+
+const getSearchCommand = () => getRegistry().get('linkedin/search');
+
+describe('linkedin parseCsvArg', () => {
+    it('returns empty array for empty / null / undefined', () => {
+        expect(parseCsvArg(undefined)).toEqual([]);
+        expect(parseCsvArg(null)).toEqual([]);
+        expect(parseCsvArg('')).toEqual([]);
+    });
+
+    it('splits and trims comma-separated values', () => {
+        expect(parseCsvArg('full-time, contract')).toEqual(['full-time', 'contract']);
+        expect(parseCsvArg(' a , b , , c ')).toEqual(['a', 'b', 'c']);
+    });
+});
+
+describe('linkedin mapFilterValues', () => {
+    it('maps known values to upstream codes and dedupes', () => {
+        expect(mapFilterValues('full-time, contract, full', JOB_TYPES, 'job_type')).toEqual(['F', 'C']);
+        expect(mapFilterValues('remote, hybrid', REMOTE_TYPES, 'remote')).toEqual(['2', '3']);
+    });
+
+    it('throws ArgumentError on unknown filter values (no silent drop)', () => {
+        expect(() => mapFilterValues('martian', JOB_TYPES, 'job_type')).toThrow(ArgumentError);
+        expect(() => mapFilterValues('full-time, ufo', JOB_TYPES, 'job_type')).toThrow(ArgumentError);
+    });
+
+    it('returns empty array for empty input', () => {
+        expect(mapFilterValues('', EXPERIENCE_LEVELS, 'experience_level')).toEqual([]);
+        expect(mapFilterValues(undefined, DATE_POSTED, 'date_posted')).toEqual([]);
+    });
+});
+
+describe('linkedin argument validation', () => {
+    it('rejects --limit outside 1..100 instead of silently clamping', () => {
+        expect(() => parseIntegerArg(0, '--limit', 10, 1, 100)).toThrow(ArgumentError);
+        expect(() => parseIntegerArg(101, '--limit', 10, 1, 100)).toThrow(ArgumentError);
+        expect(() => parseIntegerArg('10.5', '--limit', 10, 1, 100)).toThrow(ArgumentError);
+    });
+
+    it('rejects negative --start instead of silently clamping to zero', () => {
+        expect(() => parseIntegerArg(-1, '--start', 0, 0)).toThrow(ArgumentError);
+        expect(parseIntegerArg(undefined, '--start', 0, 0)).toBe(0);
+        expect(parseIntegerArg('25', '--start', 0, 0)).toBe(25);
+    });
+
+    it('validates command args before browser navigation', async () => {
+        const command = getSearchCommand();
+        const page = { goto: vi.fn(), wait: vi.fn(), evaluate: vi.fn() };
+
+        await expect(command.func(page, { query: 'engineer', limit: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func(page, { query: 'engineer', start: -1 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+});
+
+describe('linkedin auth wall detection', () => {
+    it('recognizes login/authwall signals', () => {
+        expect(looksLinkedInAuthWallText('https://www.linkedin.com/authwall?trk=guest Sign in to continue')).toBe(true);
+        expect(looksLinkedInAuthWallText('LinkedIn Login, Sign in')).toBe(true);
+        expect(looksLinkedInAuthWallText('About the job Senior infrastructure engineer')).toBe(false);
+    });
+
+    it('throws AuthRequiredError when search lands on a login wall', async () => {
+        const command = getSearchCommand();
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue(true),
+        };
+
+        await expect(command.func(page, { query: 'engineer', limit: 5 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+});
+
+describe('linkedin decodeLinkedinRedirect', () => {
+    it('extracts the underlying url from a /redir/redirect/ wrapper', () => {
+        const target = 'https://example.com/jobs/apply?id=42';
+        const wrapped = `https://www.linkedin.com/redir/redirect/?url=${encodeURIComponent(target)}&source=jobs`;
+        expect(decodeLinkedinRedirect(wrapped)).toBe(target);
+    });
+
+    it('returns the input unchanged for non-redirect urls', () => {
+        const direct = 'https://example.com/jobs/42/';
+        expect(decodeLinkedinRedirect(direct)).toBe(direct);
+    });
+
+    it('returns empty string for falsy input', () => {
+        expect(decodeLinkedinRedirect('')).toBe('');
+        expect(decodeLinkedinRedirect(null)).toBe('');
+    });
+});
+
+describe('linkedin enrichJobDetails (silent failure fix)', () => {
+    function makeFakePage({ evaluateResults = [], gotoFails = [], evaluateFails = [] } = {}) {
+        let evalCall = 0;
+        let gotoCall = 0;
+        return {
+            goto: vi.fn(async () => {
+                if (gotoFails[gotoCall++]) {
+                    throw new Error(gotoFails[gotoCall - 1]);
+                }
+            }),
+            wait: vi.fn(async () => undefined),
+            evaluate: vi.fn(async () => {
+                const idx = evalCall++;
+                if (evaluateFails[idx]) throw new Error(evaluateFails[idx]);
+                return evaluateResults[idx];
+            }),
+        };
+    }
+
+    it('surfaces detail_error="no url" when row has no URL (instead of silent empty string)', async () => {
+        const page = makeFakePage();
+        const out = await enrichJobDetails(page, [
+            { rank: 1, title: 'No URL Job', company: 'X', url: '' },
+        ]);
+        expect(out).toHaveLength(1);
+        expect(out[0]).toMatchObject({
+            description: null,
+            apply_url: null,
+            detail_error: 'no url',
+        });
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('surfaces detail_error="fetch failed: ..." when goto throws (no silent swallow)', async () => {
+        const page = makeFakePage({ gotoFails: ['network down'] });
+        const out = await enrichJobDetails(page, [
+            { rank: 1, title: 'Fetch Fail', company: 'X', url: 'https://www.linkedin.com/jobs/view/1' },
+        ]);
+        expect(out).toHaveLength(1);
+        expect(out[0].description).toBeNull();
+        expect(out[0].apply_url).toBeNull();
+        expect(out[0].detail_error).toMatch(/^fetch failed: .*network down/);
+    });
+
+    it('surfaces detail_error="missing description" on empty description (signals upstream gap, not crash)', async () => {
+        const page = makeFakePage({
+            evaluateResults: [
+                false, // auth wall probe
+                undefined, // expand-show-more click result (ignored)
+                { description: '', applyUrl: '' },
+            ],
+        });
+        const out = await enrichJobDetails(page, [
+            { rank: 1, title: 'Empty Desc', company: 'X', url: 'https://www.linkedin.com/jobs/view/2' },
+        ]);
+        expect(out[0].description).toBeNull();
+        expect(out[0].apply_url).toBeNull();
+        expect(out[0].detail_error).toBe('missing description');
+    });
+
+    it('surfaces detail_error=null on a fully successful enrichment', async () => {
+        const page = makeFakePage({
+            evaluateResults: [
+                false, // auth wall probe
+                undefined,
+                { description: '  An interesting role  ', applyUrl: 'https://example.com/apply' },
+            ],
+        });
+        const out = await enrichJobDetails(page, [
+            { rank: 1, title: 'OK', company: 'X', url: 'https://www.linkedin.com/jobs/view/3' },
+        ]);
+        expect(out[0]).toMatchObject({
+            description: 'An interesting role',
+            apply_url: 'https://example.com/apply',
+            detail_error: null,
+        });
+    });
+
+    it('processes multiple rows with mixed outcomes without aborting the batch', async () => {
+        const page = makeFakePage({
+            evaluateResults: [
+                // Row 1 (success)
+                false,
+                undefined,
+                { description: 'Good', applyUrl: 'https://a.example/' },
+                // Row 3 (success — row 2 had no URL so didn't navigate)
+                false,
+                undefined,
+                { description: 'Also good', applyUrl: 'https://b.example/' },
+            ],
+        });
+        const out = await enrichJobDetails(page, [
+            { rank: 1, title: 'A', company: 'X', url: 'https://www.linkedin.com/jobs/view/10' },
+            { rank: 2, title: 'B', company: 'X', url: '' },
+            { rank: 3, title: 'C', company: 'X', url: 'https://www.linkedin.com/jobs/view/30' },
+        ]);
+        expect(out).toHaveLength(3);
+        expect(out[0].detail_error).toBeNull();
+        expect(out[1].detail_error).toBe('no url');
+        expect(out[2].detail_error).toBeNull();
+        // Goto was only called for rows with URL (1 and 3)
+        expect(page.goto).toHaveBeenCalledTimes(2);
+    });
+
+    it('throws AuthRequiredError on detail auth wall instead of burying it in detail_error', async () => {
+        const page = makeFakePage({ evaluateResults: [true] });
+
+        await expect(enrichJobDetails(page, [
+            { rank: 1, title: 'Needs Auth', company: 'X', url: 'https://www.linkedin.com/jobs/view/4' },
+        ])).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+});

package/clis/linux-do/feed.js

@@ -355,16 +355,13 @@ export const LINUX_DO_FEED_ARGS = [
         choices: ['all', 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'],
     },
 ];
-export async function executeLinuxDoFeed(page, kwargs) {
+async function runLinuxDoFeed(page, kwargs) {
     const limit = (kwargs.limit || 20);
     await ensureLinuxDoHome(page);
     const request = await resolveFeedRequest(page, kwargs);
     const data = await fetchLinuxDoJson(page, request.url, { skipNavigate: true });
     return topicListRichFromJson(data, limit);
 }
-export function buildLinuxDoCompatFooter(replacement) {
-    return `Deprecated compatibility command. Prefer: ${replacement}`;
-}
 cli({
     site: 'linux-do',
     name: 'feed',
@@ -375,7 +372,7 @@ cli({
     browser: true,
     columns: ['title', 'replies', 'created', 'likes', 'views', 'url'],
     args: LINUX_DO_FEED_ARGS,
-    func: executeLinuxDoFeed,
+    func: runLinuxDoFeed,
 });
 export const __test__ = {
     resetMetadataCaches() {

package/clis/linux-do/feed.test.js

@@ -7,6 +7,21 @@ describe('linux-do feed metadata resolution', () => {
     afterEach(() => {
         __test__.resetMetadataCaches();
     });
+    it('builds the replacement URL for legacy latest', async () => {
+        const request = await __test__.resolveFeedRequest(null, {
+            view: 'latest',
+            limit: 20,
+        });
+        expect(request.url).toBe('/latest.json?per_page=20');
+    });
+    it('builds the replacement URL for legacy hot weekly', async () => {
+        const request = await __test__.resolveFeedRequest(null, {
+            view: 'top',
+            period: 'weekly',
+            limit: 20,
+        });
+        expect(request.url).toBe('/top.json?per_page=20&period=weekly');
+    });
     it('prefers live tag metadata over the bundled snapshot', async () => {
         __test__.setLiveMetadataForTests({
             tags: [{ id: 9999, slug: 'fresh-tag', name: 'Fresh Tag' }],
@@ -86,6 +101,26 @@ describe('linux-do feed metadata resolution', () => {
         });
         expect(request.url).toBe('/c/parent/fresh-child/11.json?per_page=20');
     });
+    it('builds the replacement URL for legacy category id', async () => {
+        __test__.setLiveMetadataForTests({
+            categories: [
+                {
+                    id: 4,
+                    name: '开发调优',
+                    description: '',
+                    slug: 'develop',
+                    parentCategoryId: null,
+                    parent: null,
+                },
+            ],
+        });
+        const request = await __test__.resolveFeedRequest(null, {
+            category: '4',
+            view: 'latest',
+            limit: 20,
+        });
+        expect(request.url).toBe('/c/develop/4.json?per_page=20');
+    });
     it('falls back to cached metadata when live metadata is unavailable', async () => {
         const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-linux-do-cache-'));
         __test__.setCacheDirForTests(cacheDir);

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/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}` : '',
+            };
+        });
+    },
+});

package/clis/maven/utils.js

@@ -0,0 +1,110 @@
+// Shared helpers for the Maven Central (search.maven.org) adapter.
+//
+// Hits the public, unauthenticated `search.maven.org/solrsearch/select` Solr
+// endpoint that powers the Maven Central search UI. No auth required for
+// read-only queries.
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const MAVEN_BASE = 'https://search.maven.org/solrsearch/select';
+export const MAVEN_REPO_BASE = 'https://repo1.maven.org/maven2';
+const UA = 'opencli-maven-adapter (+https://github.com/jackwener/opencli)';
+
+// Maven groupId / artifactId tokens — Java-package-ish (letters / digits /
+// `_-.`), 1-200 chars; reverse-DNS dots are allowed in groupId.
+const COORD_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function requireString(value, label) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError(`maven ${label} cannot be empty`);
+    return s;
+}
+
+export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`maven ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`maven ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+/**
+ * Parse a Maven coordinate `groupId:artifactId[:version]` into segments.
+ * groupId / artifactId are required; version is optional.
+ */
+export function requireCoord(value) {
+    const raw = String(value ?? '').trim();
+    if (!raw) {
+        throw new ArgumentError('maven coordinate is required (e.g. "com.fasterxml.jackson.core:jackson-databind")');
+    }
+    const parts = raw.split(':');
+    if (parts.length < 2 || parts.length > 3) {
+        throw new ArgumentError(
+            `maven coordinate "${value}" must be "groupId:artifactId" or "groupId:artifactId:version"`,
+        );
+    }
+    const [groupId, artifactId, version] = parts;
+    if (!groupId || !artifactId) {
+        throw new ArgumentError(`maven coordinate "${value}" is missing groupId or artifactId`);
+    }
+    if (groupId.length > 200 || !COORD_TOKEN.test(groupId)) {
+        throw new ArgumentError(
+            `maven groupId "${groupId}" is not a valid token`,
+            'Use letters / digits / "_-." (max 200 chars), starting with a letter or digit.',
+        );
+    }
+    if (artifactId.length > 200 || !COORD_TOKEN.test(artifactId)) {
+        throw new ArgumentError(
+            `maven artifactId "${artifactId}" is not a valid token`,
+            'Use letters / digits / "_-." (max 200 chars), starting with a letter or digit.',
+        );
+    }
+    if (version != null && version.length > 200) {
+        throw new ArgumentError(`maven version "${version}" is too long (max 200 chars).`);
+    }
+    return { groupId, artifactId, version: version ?? null };
+}
+
+export async function mavenFetch(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' } });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that search.maven.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404) {
+        throw new EmptyResultError(label, `Maven Central returned 404 for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(
+            `${label} returned HTTP 429 (rate limited)`,
+            'Maven Central throttles bursts; wait a few seconds and retry.',
+        );
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}
+
+/** Convert epoch-ms (Maven Solr `timestamp`) to ISO-8601 UTC. Returns null for falsy/invalid. */
+export function epochMsToIso(value) {
+    if (value == null) return null;
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n) || n <= 0) return null;
+    return new Date(n).toISOString().replace(/\.\d+Z$/, 'Z');
+}