@jackwener/opencli 1.7.11 → 1.7.12

package/clis/dblp/utils.js

@@ -0,0 +1,290 @@
+/**
+ * DBLP adapter utilities.
+ *
+ * dblp serves a public, unauthenticated API:
+ *   - Publication search (JSON):
+ *     `https://dblp.org/search/publ/api?q=<query>&format=json&h=<limit>`
+ *   - Per-record metadata (XML):
+ *     `https://dblp.org/rec/<key>.xml`
+ *
+ * The search response is well-shaped JSON, but the per-record endpoint is
+ * XML. We parse it with conservative regexes (same pattern as the arxiv
+ * adapter) to avoid pulling in an XML lib for this single endpoint.
+ */
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+export const DBLP_ORIGIN = 'https://dblp.org';
+
+/**
+ * dblp record keys look like `<type>/<venue>/<short>` (e.g.
+ * `conf/nips/VaswaniSPUJGKP17`, `journals/corr/abs-2509-05821`,
+ * `phd/Smith20`). Allow lowercase letter prefixes plus 1+ slash-segments
+ * containing letters / digits / `_` / `.` / `-`.
+ */
+const KEY_PATTERN = /^[a-z]+(?:\/[A-Za-z0-9_.-]+)+$/;
+
+/**
+ * Wraps `fetch` with typed errors. We always set a UA per dblp's
+ * polite-fetch guidance (https://dblp.org/faq/How+to+use+the+dblp+search+API.html).
+ */
+async function dblpFetch(url, label, accept) {
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: {
+                accept,
+                'user-agent': 'opencli-dblp/1.0 (+https://github.com/jackwener/opencli)',
+            },
+        });
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} request failed: ${err?.message ?? err}`, 'Check that dblp.org is reachable from this network.');
+    }
+    if (!res.ok) {
+        if (res.status === 429) {
+            throw new CommandExecutionError(`${label} returned HTTP 429 (rate limited)`, 'dblp throttles clients that fetch too aggressively. Wait a few seconds and retry, or lower --limit.');
+        }
+        if (res.status === 404) {
+            throw new EmptyResultError(label, 'dblp returned 404 — the requested record may not exist.');
+        }
+        throw new CommandExecutionError(`${label} returned HTTP ${res.status}`, 'Inspect the response in a browser at the same URL for more context.');
+    }
+    return res;
+}
+
+export async function dblpFetchJson(path, label) {
+    const res = await dblpFetch(`${DBLP_ORIGIN}${path}`, label, 'application/json');
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    const statusCode = String(body?.result?.status?.['@code'] ?? '').trim();
+    if (!statusCode) {
+        throw new CommandExecutionError(
+            `${label} returned JSON without result.status.@code`,
+            'dblp changed its JSON envelope or returned a partial error payload; inspect the raw response in a browser.',
+        );
+    }
+    if (statusCode !== '200') {
+        const statusText = String(body?.result?.status?.text ?? '').trim();
+        throw new CommandExecutionError(
+            `${label} returned API status ${statusCode}${statusText ? ` (${statusText})` : ''}`,
+            'dblp accepted the HTTP request but reported an API-level failure. Retry later or inspect the same query in a browser.',
+        );
+    }
+    return body;
+}
+
+export async function dblpFetchXml(path, label) {
+    const res = await dblpFetch(`${DBLP_ORIGIN}${path}`, label, 'application/xml');
+    return res.text();
+}
+
+export function coerceInt(value) {
+    if (value === undefined || value === null || value === '') return NaN;
+    const n = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(n) && Number.isInteger(n) ? n : NaN;
+}
+
+export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
+    const raw = value ?? defaultValue;
+    const n = coerceInt(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`dblp ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`dblp ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+export function requireQuery(value, label = 'query') {
+    const q = String(value ?? '').trim();
+    if (!q) {
+        throw new ArgumentError(`dblp ${label} cannot be empty`);
+    }
+    return q;
+}
+
+export function requireRecordKey(value) {
+    const key = String(value ?? '').trim();
+    if (!key) {
+        throw new ArgumentError('dblp paper key is required');
+    }
+    if (!KEY_PATTERN.test(key)) {
+        throw new ArgumentError(`dblp paper key "${value}" is not a valid record key`, 'Expected something like "conf/nips/VaswaniSPUJGKP17" — copy the `key` column from `dblp search`.');
+    }
+    return key;
+}
+
+/** Decode the small set of XML entities dblp emits in record bodies. */
+export function decodeXmlEntities(text) {
+    if (!text) return '';
+    return String(text)
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&apos;/g, "'")
+        .replace(/&quot;/g, '"')
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+        .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(parseInt(d, 10)));
+}
+
+/** Strip dblp's per-author homonym suffixes (`Smith 0001`) → `Smith`. */
+function trimAuthorHomonym(name) {
+    return String(name || '').replace(/\s+\d{4,}$/, '').trim();
+}
+
+/**
+ * Normalize the `info.authors.author` field from a dblp search hit. dblp
+ * collapses single authors into one object instead of a 1-element array.
+ */
+export function normalizeAuthors(authorsField) {
+    if (!authorsField) return [];
+    const raw = authorsField?.author;
+    if (!raw) return [];
+    const list = Array.isArray(raw) ? raw : [raw];
+    return list.map((a) => {
+        if (a && typeof a === 'object') return trimAuthorHomonym(a.text || a['#text'] || '');
+        return trimAuthorHomonym(String(a));
+    }).filter(Boolean);
+}
+
+/**
+ * Project a dblp publication search hit into one row. Drops only the most
+ * volatile fields (e.g. abstract, which dblp does not expose) and keeps
+ * the canonical key as the round-trip handle.
+ */
+export function searchHitToRow(hit, rank) {
+    const info = hit?.info ?? {};
+    const authors = normalizeAuthors(info.authors);
+    const key = String(info.key ?? '').trim();
+    return {
+        rank,
+        key,
+        title: stripTrailingDot(decodeXmlEntities(info.title ?? '')).trim(),
+        authors: authors.join(', '),
+        venue: decodeXmlEntities(info.venue ?? ''),
+        year: String(info.year ?? '').trim(),
+        type: simplifyHitType(info.type),
+        doi: String(info.doi ?? '').trim(),
+        url: String(info.ee ?? info.url ?? '').trim(),
+    };
+}
+
+/** Title strings from dblp end with a period — strip it for cleaner display. */
+function stripTrailingDot(s) {
+    return String(s || '').replace(/\.\s*$/, '');
+}
+
+/** Compress dblp's verbose `type` strings into single-token tags. */
+function simplifyHitType(type) {
+    if (!type) return '';
+    const t = String(type);
+    if (/Conference and Workshop/i.test(t)) return 'conf';
+    if (/Journal Articles/i.test(t)) return 'journal';
+    if (/Books and Theses/i.test(t)) return 'book';
+    if (/Editorship/i.test(t)) return 'editorship';
+    if (/Reference Works/i.test(t)) return 'reference';
+    if (/Informal/i.test(t)) return 'preprint';
+    return t.toLowerCase().split(/\s+/)[0];
+}
+
+/**
+ * Extract a single tag from a dblp record XML blob (regex-based, same
+ * approach as arxiv/utils.js — keeps the dependency surface flat).
+ */
+export function extractFirst(xml, tag) {
+    const m = String(xml || '').match(new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)<\\/${tag}>`));
+    return m ? m[1] : '';
+}
+
+export function extractAll(xml, tag) {
+    const out = [];
+    const re = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)<\\/${tag}>`, 'g');
+    let m;
+    while ((m = re.exec(String(xml || ''))) !== null) out.push(m[1]);
+    return out;
+}
+
+/**
+ * Pick the first `<ee type="oa">` (open-access link) if present, otherwise
+ * fall back to the first `<ee>`.
+ */
+export function extractOpenAccessLink(xml) {
+    const oa = String(xml || '').match(/<ee\b[^>]*type=["']oa["'][^>]*>([\s\S]*?)<\/ee>/);
+    if (oa) return oa[1].trim();
+    const any = String(xml || '').match(/<ee\b[^>]*>([\s\S]*?)<\/ee>/);
+    return any ? any[1].trim() : '';
+}
+
+/** Pull the `key` attribute off the wrapper element regardless of record type. */
+export function extractRecordKey(xml) {
+    const m = String(xml || '').match(/<(?:article|inproceedings|incollection|proceedings|book|phdthesis|mastersthesis)\b[^>]*\bkey="([^"]+)"/);
+    return m ? m[1] : '';
+}
+
+/**
+ * Identify the record type from the wrapper element name. Maps to the
+ * same simplified tag set the search rows use.
+ */
+export function extractRecordType(xml) {
+    const m = String(xml || '').match(/<(article|inproceedings|incollection|proceedings|book|phdthesis|mastersthesis)\b/);
+    if (!m) return '';
+    switch (m[1]) {
+        case 'inproceedings': return 'conf';
+        case 'article': return 'journal';
+        case 'incollection': return 'incollection';
+        case 'proceedings': return 'editorship';
+        case 'book': return 'book';
+        case 'phdthesis': return 'phdthesis';
+        case 'mastersthesis': return 'mastersthesis';
+        default: return m[1];
+    }
+}
+
+/**
+ * Parse a single dblp record XML into the row shape used by `dblp paper`.
+ * Treats every field as optional; throws upstream when the record body
+ * is missing entirely (404 already handled at fetch level).
+ */
+export function recordXmlToRow(xml) {
+    const key = extractRecordKey(xml);
+    const type = extractRecordType(xml);
+    const title = stripTrailingDot(decodeXmlEntities(extractFirst(xml, 'title')));
+    const authors = extractAll(xml, 'author').map((a) => trimAuthorHomonym(decodeXmlEntities(a)));
+    const year = decodeXmlEntities(extractFirst(xml, 'year'));
+    const pages = decodeXmlEntities(extractFirst(xml, 'pages'));
+    const venueRaw = type === 'conf'
+        ? decodeXmlEntities(extractFirst(xml, 'booktitle'))
+        : decodeXmlEntities(extractFirst(xml, 'journal'));
+    const doi = (() => {
+        const m = String(xml || '').match(/<ee\b[^>]*>([^<]*?(?:doi\.org\/|10\.[^"<]+))<\/ee>/i);
+        if (!m) return '';
+        const v = m[1].replace(/^https?:\/\/(?:dx\.)?doi\.org\//i, '');
+        return v.startsWith('10.') ? v : '';
+    })();
+    return {
+        key,
+        type,
+        title,
+        authors: authors.join(', '),
+        venue: venueRaw,
+        year,
+        pages,
+        doi,
+        open_access_url: extractOpenAccessLink(xml),
+        dblp_url: key ? `${DBLP_ORIGIN}/rec/${key}.html` : '',
+    };
+}
+
+export const SEARCH_COLUMNS = [
+    'rank', 'key', 'title', 'authors', 'venue', 'year', 'type', 'doi', 'url',
+];
+
+export const PAPER_COLUMNS = [
+    'key', 'type', 'title', 'authors', 'venue', 'year', 'pages', 'doi', 'open_access_url', 'dblp_url',
+];

package/clis/deepseek/ask.js

@@ -8,6 +8,7 @@ import {
 export const askCommand = cli({
     site: 'deepseek',
     name: 'ask',
+    access: 'write',
     description: 'Send a prompt to DeepSeek and get the response',
     domain: DEEPSEEK_DOMAIN,
     strategy: Strategy.COOKIE,

package/clis/deepseek/history.js

@@ -4,6 +4,7 @@ import { DEEPSEEK_DOMAIN, getConversationList } from './utils.js';
 export const historyCommand = cli({
     site: 'deepseek',
     name: 'history',
+    access: 'read',
     description: 'List conversation history from DeepSeek sidebar',
     domain: DEEPSEEK_DOMAIN,
     strategy: Strategy.COOKIE,

package/clis/deepseek/new.js

@@ -4,6 +4,7 @@ import { DEEPSEEK_DOMAIN, DEEPSEEK_URL } from './utils.js';
 export const newCommand = cli({
     site: 'deepseek',
     name: 'new',
+    access: 'read',
     description: 'Start a new conversation in DeepSeek',
     domain: DEEPSEEK_DOMAIN,
     strategy: Strategy.COOKIE,

package/clis/deepseek/read.js

@@ -4,6 +4,7 @@ import { DEEPSEEK_DOMAIN, ensureOnDeepSeek, getVisibleMessages } from './utils.j
 export const readCommand = cli({
     site: 'deepseek',
     name: 'read',
+    access: 'read',
     description: 'Read the current DeepSeek conversation',
     domain: DEEPSEEK_DOMAIN,
     strategy: Strategy.COOKIE,

package/clis/deepseek/status.js

@@ -4,6 +4,7 @@ import { DEEPSEEK_DOMAIN, ensureOnDeepSeek, getPageState } from './utils.js';
 export const statusCommand = cli({
     site: 'deepseek',
     name: 'status',
+    access: 'read',
     description: 'Check DeepSeek page availability and login state',
     domain: DEEPSEEK_DOMAIN,
     strategy: Strategy.COOKIE,

package/clis/devto/devto.test.js

@@ -0,0 +1,236 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './top.js';
+import './tag.js';
+import './user.js';
+import './read.js';
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('devto listing adapters surface id + reading_time + published_at', () => {
+    it('devto/top has the agent-native column shape and pipeline mapping', () => {
+        const cmd = getRegistry().get('devto/top');
+        expect(cmd?.columns).toEqual([
+            'rank', 'id', 'title', 'author', 'reactions', 'comments',
+            'reading_time', 'published_at', 'tags', 'url',
+        ]);
+        const mapStep = cmd?.pipeline?.find((step) => step.map);
+        expect(mapStep?.map).toMatchObject({
+            id: '${{ item.id }}',
+            reading_time: '${{ item.reading_time_minutes }}',
+            published_at: '${{ item.published_at }}',
+            url: '${{ item.url }}',
+        });
+    });
+
+    it('devto/tag has the agent-native column shape and pipeline mapping', () => {
+        const cmd = getRegistry().get('devto/tag');
+        expect(cmd?.columns).toEqual([
+            'rank', 'id', 'title', 'author', 'reactions', 'comments',
+            'reading_time', 'published_at', 'tags', 'url',
+        ]);
+        const mapStep = cmd?.pipeline?.find((step) => step.map);
+        expect(mapStep?.map).toMatchObject({
+            id: '${{ item.id }}',
+            reading_time: '${{ item.reading_time_minutes }}',
+            published_at: '${{ item.published_at }}',
+        });
+    });
+
+    it('devto/user has the agent-native column shape (no author column, since user-specific)', () => {
+        const cmd = getRegistry().get('devto/user');
+        expect(cmd?.columns).toEqual([
+            'rank', 'id', 'title', 'reactions', 'comments',
+            'reading_time', 'published_at', 'tags', 'url',
+        ]);
+        const mapStep = cmd?.pipeline?.find((step) => step.map);
+        expect(mapStep?.map).toMatchObject({
+            id: '${{ item.id }}',
+            reading_time: '${{ item.reading_time_minutes }}',
+            published_at: '${{ item.published_at }}',
+        });
+    });
+});
+
+describe('devto/read adapter', () => {
+    const cmd = getRegistry().get('devto/read');
+
+    it('registers the article-detail row shape', () => {
+        expect(cmd?.columns).toEqual([
+            'id', 'title', 'author', 'reactions', 'reading_time',
+            'tags', 'published_at', 'body', 'url',
+        ]);
+    });
+
+    it('takes a positional id plus a tunable max-length', () => {
+        const argNames = (cmd?.args || []).map((a) => a.name);
+        expect(argNames).toEqual(['id', '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 dev.to JSON endpoint (no browser, public strategy)', () => {
+        expect(cmd?.browser).toBe(false);
+        expect(cmd?.strategy).toBe('public');
+    });
+
+    it('fails fast with ArgumentError for non-numeric id before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ id: 'not-a-number', 'max-length': 20000 }))
+            .rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('fails fast with ArgumentError for max-length below 100 before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ id: '12345', 'max-length': 50 }))
+            .rejects.toThrow(ArgumentError);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('accepts numeric max-length strings on the direct func path', async () => {
+        const article = {
+            id: 1,
+            title: 't',
+            user: { username: 'u' },
+            public_reactions_count: 0,
+            reading_time_minutes: 1,
+            tag_list: [],
+            published_at: '',
+            body_markdown: 'x'.repeat(150),
+            url: 'https://dev.to/u/t-1',
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(article), { status: 200 })));
+
+        const rows = await cmd.func({ id: '1', 'max-length': '100' });
+        expect(rows[0].body).toBe('x'.repeat(100) + '\n\n... [truncated]');
+    });
+
+    it('fails fast with ArgumentError for invalid max-length strings before fetching', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+
+        await expect(cmd.func({ id: '12345', 'max-length': 'abc' }))
+            .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: '99999999', 'max-length': 20000 }))
+            .rejects.toThrow(EmptyResultError);
+    });
+
+    it('fails fast with CommandExecutionError on non-404 HTTP failures', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('Server error', { status: 500 })));
+
+        await expect(cmd.func({ id: '12345', 'max-length': 20000 }))
+            .rejects.toThrow(CommandExecutionError);
+    });
+
+    it('fails fast with CommandExecutionError on invalid JSON responses', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('not json', { status: 200 })));
+
+        await expect(cmd.func({ id: '12345', 'max-length': 20000 }))
+            .rejects.toThrow(CommandExecutionError);
+    });
+
+    it('fails fast when the full article body is missing instead of returning a summary', async () => {
+        const article = {
+            id: 1,
+            title: 't',
+            user: { username: 'u' },
+            public_reactions_count: 0,
+            reading_time_minutes: 1,
+            tag_list: [],
+            published_at: '',
+            description: 'summary only',
+            url: 'https://dev.to/u/t-1',
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(article), { status: 200 })));
+
+        await expect(cmd.func({ id: '1', 'max-length': 20000 }))
+            .rejects.toThrow(CommandExecutionError);
+    });
+
+    it('returns a single article row with body_markdown extracted', async () => {
+        // Real /api/articles/<id> returns tag_list as a comma string and tags as an array.
+        const article = {
+            id: 3605688,
+            title: 'How to do thing X in Rust',
+            user: { username: 'jdoe' },
+            public_reactions_count: 42,
+            reading_time_minutes: 7,
+            tag_list: 'rust, webdev',
+            tags: ['rust', 'webdev'],
+            published_at: '2026-05-01T00:00:00Z',
+            body_markdown: '# Hello\n\nThis is the article body.',
+            url: 'https://dev.to/jdoe/how-to-do-thing-x-in-rust-1234',
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(article), { status: 200 })));
+
+        const rows = await cmd.func({ id: '3605688', 'max-length': 20000 });
+
+        expect(rows).toEqual([
+            {
+                id: 3605688,
+                title: 'How to do thing X in Rust',
+                author: 'jdoe',
+                reactions: 42,
+                reading_time: 7,
+                tags: 'rust, webdev',
+                published_at: '2026-05-01T00:00:00Z',
+                body: '# Hello\n\nThis is the article body.',
+                url: 'https://dev.to/jdoe/how-to-do-thing-x-in-rust-1234',
+            },
+        ]);
+    });
+
+    it('handles the alternate shape where tag_list is an array (defensive)', async () => {
+        const article = {
+            id: 1,
+            title: 't',
+            user: { username: 'u' },
+            public_reactions_count: 0,
+            reading_time_minutes: 1,
+            tag_list: ['javascript', 'webdev'],
+            published_at: '',
+            body_markdown: 'body',
+            url: 'https://dev.to/u/t-1',
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(article), { status: 200 })));
+
+        const rows = await cmd.func({ id: '1', 'max-length': 20000 });
+        expect(rows[0].tags).toBe('javascript, webdev');
+    });
+
+    it('truncates body when over max-length and appends a marker', async () => {
+        const longBody = 'x'.repeat(500);
+        const article = {
+            id: 1,
+            title: 't',
+            user: { username: 'u' },
+            public_reactions_count: 0,
+            reading_time_minutes: 1,
+            tag_list: [],
+            published_at: '',
+            body_markdown: longBody,
+            url: 'https://dev.to/u/t-1',
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(article), { status: 200 })));
+
+        const rows = await cmd.func({ id: '1', 'max-length': 100 });
+
+        expect(rows[0].body).toBe('x'.repeat(100) + '\n\n... [truncated]');
+    });
+});

package/clis/devto/read.js

@@ -0,0 +1,103 @@
+/**
+ * DEV.to article reader.
+ *
+ * Public API: https://dev.to/api/articles/<id>
+ * Returns the full article including `body_markdown` (and `body_html`).
+ *
+ * The DEV.to API does not currently expose article comments — this reader
+ * therefore emits one row with the article body. If/when comments become
+ * available we can extend to a POST + L0/L1 shape like `hackernews read`.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const DEVTO_ARTICLE_BASE = 'https://dev.to/api/articles';
+
+async function fetchArticle(id) {
+    let res;
+    try {
+        res = await fetch(`${DEVTO_ARTICLE_BASE}/${id}`);
+    } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CommandExecutionError(`DEV.to API request failed for article ${id}`, detail);
+    }
+    if (res.status === 404) {
+        throw new EmptyResultError(`devto/${id}`, 'Article not found');
+    }
+    if (!res.ok) {
+        throw new CommandExecutionError(`DEV.to API HTTP ${res.status} for article ${id}`, 'Check the article id');
+    }
+    try {
+        return await res.json();
+    } catch {
+        throw new CommandExecutionError(`DEV.to API returned invalid JSON for article ${id}`, 'Retry later or open the article URL directly');
+    }
+}
+
+function requireMinInt(value, min, label) {
+    const number = typeof value === 'number' ? value : Number(value);
+    if (!Number.isInteger(number) || number < min) {
+        throw new ArgumentError(`${label} must be an integer >= ${min}`);
+    }
+    return number;
+}
+
+function requireArticleBody(article, id) {
+    if (typeof article.body_markdown === 'string' && article.body_markdown.trim()) {
+        return article.body_markdown;
+    }
+    throw new CommandExecutionError(
+        `DEV.to article ${id} did not include body_markdown`,
+        'DEV.to API response shape may have changed. Open the article URL directly or retry later.',
+    );
+}
+
+cli({
+    site: 'devto',
+    name: 'read',
+    access: 'read',
+    description: 'Read a DEV.to article body by id',
+    domain: 'dev.to',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', required: true, positional: true, help: 'DEV.to article id (numeric, e.g. 3605688)' },
+        { name: 'max-length', type: 'int', default: 20000, help: 'Max characters of body to return (min 100)' },
+    ],
+    columns: ['id', 'title', 'author', 'reactions', 'reading_time', 'tags', 'published_at', 'body', 'url'],
+    func: async (args) => {
+        const id = String(args.id || '').trim();
+        if (!/^\d+$/.test(id)) {
+            throw new ArgumentError(`Invalid DEV.to article id: ${args.id}`, 'Pass a numeric id like 3605688');
+        }
+        const maxLength = requireMinInt(args['max-length'] ?? 20000, 100, 'devto read --max-length');
+
+        const article = await fetchArticle(id);
+        if (!article || !article.id) {
+            throw new EmptyResultError(`devto/${id}`, 'Article not found');
+        }
+
+        const body = requireArticleBody(article, id);
+        const truncated = body.length > maxLength
+            ? body.slice(0, maxLength) + '\n\n... [truncated]'
+            : body;
+
+        // The single-article endpoint returns `tag_list` as a comma-separated
+        // string and `tags` as an array — the opposite of the listing endpoints.
+        // Normalize either shape into a single comma-separated string.
+        const tagsRaw = article.tag_list ?? article.tags ?? '';
+        const tags = Array.isArray(tagsRaw) ? tagsRaw.join(', ') : String(tagsRaw);
+
+        return [{
+            id: article.id,
+            title: article.title || '',
+            author: article.user?.username || '[deleted]',
+            reactions: article.public_reactions_count ?? 0,
+            reading_time: article.reading_time_minutes ?? 0,
+            tags,
+            published_at: article.published_at || '',
+            body: truncated,
+            url: article.url || '',
+        }];
+    },
+});