chore: import upstream snapshot with attribution

clis/hackernews/ask.js

@@ -0,0 +1,31 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+cli({
+    site: 'hackernews',
+    name: 'ask',
+    access: 'read',
+    description: 'Hacker News Ask HN posts',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
+    ],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
+    pipeline: [
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/askstories.json' } },
+        { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
+        { map: { id: '${{ item }}' } },
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/item/${{ item.id }}.json' } },
+        { filter: 'item.title && !item.deleted && !item.dead' },
+        { map: {
+                rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
+                title: '${{ item.title }}',
+                score: '${{ item.score }}',
+                author: '${{ item.by }}',
+                comments: '${{ item.descendants }}',
+                url: '${{ item.url }}',
+            } },
+        { limit: '${{ args.limit }}' },
+    ],
+});

clis/hackernews/best.js

@@ -0,0 +1,31 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+cli({
+    site: 'hackernews',
+    name: 'best',
+    access: 'read',
+    description: 'Hacker News best stories',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
+    ],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
+    pipeline: [
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/beststories.json' } },
+        { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
+        { map: { id: '${{ item }}' } },
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/item/${{ item.id }}.json' } },
+        { filter: 'item.title && !item.deleted && !item.dead' },
+        { map: {
+                rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
+                title: '${{ item.title }}',
+                score: '${{ item.score }}',
+                author: '${{ item.by }}',
+                comments: '${{ item.descendants }}',
+                url: '${{ item.url }}',
+            } },
+        { limit: '${{ args.limit }}' },
+    ],
+});

clis/hackernews/hackernews.test.js

@@ -0,0 +1,132 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import './top.js';
+import './best.js';
+import './ask.js';
+import './new.js';
+import './show.js';
+import './jobs.js';
+import './search.js';
+import './read.js';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('hackernews listing adapters expose item id', () => {
+  const storyCommands = ['hackernews/top', 'hackernews/best', 'hackernews/ask', 'hackernews/new', 'hackernews/show'];
+
+  storyCommands.forEach((key) => {
+    it(`${key} surfaces id alongside title/score/author/comments/url`, () => {
+      const cmd = getRegistry().get(key);
+      expect(cmd?.columns).toEqual(['rank', 'id', 'title', 'score', 'author', 'comments', 'url']);
+      expect(cmd?.pipeline?.[5]?.map).toMatchObject({
+        id: '${{ item.id }}',
+        url: '${{ item.url }}',
+      });
+    });
+  });
+
+  it('hackernews/jobs surfaces id alongside title/author/url', () => {
+    const cmd = getRegistry().get('hackernews/jobs');
+    expect(cmd?.columns).toEqual(['rank', 'id', 'title', 'author', 'url']);
+    expect(cmd?.pipeline?.[5]?.map).toMatchObject({
+      id: '${{ item.id }}',
+      url: '${{ item.url }}',
+    });
+  });
+
+  it('hackernews/search surfaces id (algolia objectID) alongside the existing columns', () => {
+    const cmd = getRegistry().get('hackernews/search');
+    expect(cmd?.columns).toEqual(['rank', 'id', 'title', 'score', 'author', 'comments', 'url']);
+    expect(cmd?.pipeline?.[2]?.map).toMatchObject({
+      id: '${{ item.objectID }}',
+    });
+  });
+});
+
+describe('hackernews/read adapter', () => {
+  const cmd = getRegistry().get('hackernews/read');
+
+  it('registers the comment-thread shape (type/author/score/text)', () => {
+    expect(cmd?.columns).toEqual(['type', 'author', 'score', 'text']);
+  });
+
+  it('takes a positional 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 Firebase API (no browser, public strategy)', () => {
+    expect(cmd?.browser).toBe(false);
+    expect(cmd?.strategy).toBe('public');
+  });
+
+  it('fails fast with ArgumentError for non-numeric ids before hitting fetch', async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(cmd.func({ id: 'abc', limit: 5, depth: 2, replies: 5, 'max-length': 2000 })).rejects.toThrow(ArgumentError);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('fails fast with EmptyResultError when the story is missing', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify(null), { status: 200 })));
+
+    await expect(cmd.func({ id: '99999999', limit: 5, depth: 2, replies: 5, 'max-length': 2000 })).rejects.toThrow(EmptyResultError);
+  });
+
+  it('renders story body, anchor text, and hidden-replies stubs from the public API tree', async () => {
+    const items = new Map([
+      ['123', {
+        id: 123,
+        type: 'story',
+        by: 'pg',
+        score: 42,
+        title: 'Ask HN: Example',
+        text: '<p>Hello <a href=\"https://example.com\">world</a></p>',
+        url: 'https://news.ycombinator.com/item?id=123',
+        kids: [456],
+      }],
+      ['456', {
+        id: 456,
+        type: 'comment',
+        by: 'sama',
+        text: '<p>Top level</p>',
+        kids: [789],
+      }],
+    ]);
+    vi.stubGlobal('fetch', vi.fn(async (url) => {
+      const id = String(url).match(/item\/(\d+)\.json$/)?.[1];
+      return new Response(JSON.stringify(items.get(id) ?? null), { status: 200 });
+    }));
+
+    const rows = await cmd.func({ id: '123', limit: 5, depth: 1, replies: 5, 'max-length': 2000 });
+
+    expect(rows).toEqual([
+      {
+        type: 'POST',
+        author: 'pg',
+        score: 42,
+        text: 'Ask HN: Example\nHello world (https://example.com)\nhttps://news.ycombinator.com/item?id=123',
+      },
+      {
+        type: 'L0',
+        author: 'sama',
+        score: '',
+        text: 'Top level',
+      },
+      {
+        type: 'L1',
+        author: '',
+        score: '',
+        text: '  [+1 more replies]',
+      },
+    ]);
+  });
+});

clis/hackernews/jobs.js

@@ -0,0 +1,29 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+cli({
+    site: 'hackernews',
+    name: 'jobs',
+    access: 'read',
+    description: 'Hacker News job postings',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of job postings' },
+    ],
+    columns: ['rank', 'id', 'title', 'author', 'url'],
+    pipeline: [
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/jobstories.json' } },
+        { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
+        { map: { id: '${{ item }}' } },
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/item/${{ item.id }}.json' } },
+        { filter: 'item.title && !item.deleted && !item.dead' },
+        { map: {
+                rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
+                title: '${{ item.title }}',
+                author: '${{ item.by }}',
+                url: '${{ item.url }}',
+            } },
+        { limit: '${{ args.limit }}' },
+    ],
+});

clis/hackernews/new.js

@@ -0,0 +1,31 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+cli({
+    site: 'hackernews',
+    name: 'new',
+    access: 'read',
+    description: 'Hacker News newest stories',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
+    ],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
+    pipeline: [
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/newstories.json' } },
+        { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
+        { map: { id: '${{ item }}' } },
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/item/${{ item.id }}.json' } },
+        { filter: 'item.title && !item.deleted && !item.dead' },
+        { map: {
+                rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
+                title: '${{ item.title }}',
+                score: '${{ item.score }}',
+                author: '${{ item.by }}',
+                comments: '${{ item.descendants }}',
+                url: '${{ item.url }}',
+            } },
+        { limit: '${{ args.limit }}' },
+    ],
+});

clis/hackernews/read.js

@@ -0,0 +1,188 @@
+/**
+ * Hacker News story reader with threaded comment tree.
+ *
+ * Mirrors `reddit read` semantics — fetches a story plus a tree of top-level
+ * comments and inline replies via the public Firebase API:
+ *   https://hacker-news.firebaseio.com/v0/item/<id>.json
+ *
+ * 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 HN_ITEM_BASE = 'https://hacker-news.firebaseio.com/v0/item';
+
+async function fetchItem(id) {
+    const res = await fetch(`${HN_ITEM_BASE}/${id}.json`);
+    if (!res.ok) {
+        throw new CommandExecutionError(`HN API HTTP ${res.status} for item ${id}`, 'Check the item 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;
+}
+
+/** HN stores 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(/<a[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi, '$2 ($1)')
+        .replace(/<pre><code>([\s\S]*?)<\/code><\/pre>/gi, '\n$1\n')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&#x27;/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: 'hackernews',
+    name: 'read',
+    access: 'read',
+    description: 'Read a Hacker News story and its comment tree',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', required: true, positional: true, help: 'HN item ID (e.g. 39847301)' },
+        { 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 id = String(args.id || '').trim();
+        if (!/^\d+$/.test(id)) {
+            throw new ArgumentError(`Invalid HN item id: ${args.id}`, 'Pass a numeric id like 39847301');
+        }
+        const limit = requirePositiveInt(args.limit ?? 25, 'hackernews read --limit');
+        const maxDepth = requirePositiveInt(args.depth ?? 2, 'hackernews read --depth');
+        const maxReplies = requirePositiveInt(args.replies ?? 5, 'hackernews read --replies');
+        const maxLength = requireMinInt(args['max-length'] ?? 2000, 100, 'hackernews read --max-length');
+
+        const story = await fetchItem(id);
+        if (!story || story.deleted || story.dead) {
+            throw new EmptyResultError(`hackernews/${id}`, 'Story not found, deleted, or dead');
+        }
+
+        const results = [];
+
+        // Story header row. text combines title + selftext (Ask/Show HN body) + external URL.
+        const storyBodyRaw = htmlToText(story.text || '');
+        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.by || '[deleted]',
+            score: story.score ?? 0,
+            text: storyParts.join('').trim(),
+        });
+
+        // Walk top-level comments using `kids` ids; fetch the first `limit` ids in parallel.
+        const topKids = Array.isArray(story.kids) ? story.kids : [];
+        const topToFetch = topKids.slice(0, limit);
+        const fetched = await Promise.all(topToFetch.map((kidId) => fetchItem(kidId).catch(() => null)));
+
+        async function walkComment(node, depth) {
+            if (!node || node.deleted || node.dead || node.type !== 'comment') return;
+            const bodyText = htmlToText(node.text || '');
+            const truncated = bodyText.length > maxLength
+                ? bodyText.slice(0, maxLength) + '...'
+                : bodyText;
+
+            results.push({
+                type: depth === 0 ? 'L0' : `L${depth}`,
+                author: node.by || '[deleted]',
+                score: '',
+                text: indentLines(truncated, depth),
+            });
+
+            const childIds = Array.isArray(node.kids) ? node.kids : [];
+
+            // At depth cutoff: don't recurse, but show a "+N more replies" stub if any.
+            if (depth + 1 >= maxDepth) {
+                if (childIds.length > 0) {
+                    results.push({
+                        type: `L${depth + 1}`,
+                        author: '',
+                        score: '',
+                        text: `${moreRepliesIndent(depth)}[+${childIds.length} more replies]`,
+                    });
+                }
+                return;
+            }
+
+            const toProcess = childIds.slice(0, maxReplies);
+            const replies = await Promise.all(toProcess.map((cid) => fetchItem(cid).catch(() => null)));
+            for (const reply of replies) {
+                await walkComment(reply, depth + 1);
+            }
+
+            // "+N more replies" for whatever we skipped at this level
+            const hidden = childIds.length - toProcess.length;
+            if (hidden > 0) {
+                results.push({
+                    type: `L${depth + 1}`,
+                    author: '',
+                    score: '',
+                    text: `${moreRepliesIndent(depth)}[+${hidden} more replies]`,
+                });
+            }
+        }
+
+        for (const comment of fetched) {
+            await walkComment(comment, 0);
+        }
+
+        const hiddenTopLevel = Math.max(0, topKids.length - topToFetch.length);
+        if (hiddenTopLevel > 0) {
+            results.push({
+                type: '',
+                author: '',
+                score: '',
+                text: `[+${hiddenTopLevel} more top-level comments]`,
+            });
+        }
+
+        return results;
+    },
+});

clis/hackernews/search.js

@@ -0,0 +1,38 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+cli({
+    site: 'hackernews',
+    name: 'search',
+    access: 'read',
+    description: 'Search Hacker News stories',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', required: true, positional: true, help: 'Search query' },
+        { name: 'limit', type: 'int', default: 20, help: 'Number of results' },
+        {
+            name: 'sort',
+            default: 'relevance',
+            help: 'Sort by relevance or date',
+            choices: ['relevance', 'date'],
+        },
+    ],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
+    pipeline: [
+        { fetch: {
+                url: `https://hn.algolia.com/api/v1/\${{ args.sort === 'date' ? 'search_by_date' : 'search' }}`,
+                params: { query: '${{ args.query }}', tags: 'story', hitsPerPage: '${{ args.limit }}' },
+            } },
+        { select: 'hits' },
+        { map: {
+                rank: '${{ index + 1 }}',
+                id: '${{ item.objectID }}',
+                title: '${{ item.title }}',
+                score: '${{ item.points }}',
+                author: '${{ item.author }}',
+                comments: '${{ item.num_comments }}',
+                url: '${{ item.url }}',
+            } },
+        { limit: '${{ args.limit }}' },
+    ],
+});

clis/hackernews/show.js

@@ -0,0 +1,31 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+cli({
+    site: 'hackernews',
+    name: 'show',
+    access: 'read',
+    description: 'Hacker News Show HN posts',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
+    ],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
+    pipeline: [
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/showstories.json' } },
+        { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
+        { map: { id: '${{ item }}' } },
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/item/${{ item.id }}.json' } },
+        { filter: 'item.title && !item.deleted && !item.dead' },
+        { map: {
+                rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
+                title: '${{ item.title }}',
+                score: '${{ item.score }}',
+                author: '${{ item.by }}',
+                comments: '${{ item.descendants }}',
+                url: '${{ item.url }}',
+            } },
+        { limit: '${{ args.limit }}' },
+    ],
+});

clis/hackernews/top.js

@@ -0,0 +1,31 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+cli({
+    site: 'hackernews',
+    name: 'top',
+    access: 'read',
+    description: 'Hacker News top stories',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of stories' },
+    ],
+    columns: ['rank', 'id', 'title', 'score', 'author', 'comments', 'url'],
+    pipeline: [
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/topstories.json' } },
+        { limit: '${{ Math.min((args.limit ? args.limit : 20) + 10, 50) }}' },
+        { map: { id: '${{ item }}' } },
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/item/${{ item.id }}.json' } },
+        { filter: 'item.title && !item.deleted && !item.dead' },
+        { map: {
+                rank: '${{ index + 1 }}',
+                id: '${{ item.id }}',
+                title: '${{ item.title }}',
+                score: '${{ item.score }}',
+                author: '${{ item.by }}',
+                comments: '${{ item.descendants }}',
+                url: '${{ item.url }}',
+            } },
+        { limit: '${{ args.limit }}' },
+    ],
+});

clis/hackernews/user.js

@@ -0,0 +1,23 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+cli({
+    site: 'hackernews',
+    name: 'user',
+    access: 'read',
+    description: 'Hacker News user profile',
+    domain: 'news.ycombinator.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'username', required: true, positional: true, help: 'HN username' },
+    ],
+    columns: ['username', 'karma', 'created', 'about'],
+    pipeline: [
+        { fetch: { url: 'https://hacker-news.firebaseio.com/v0/user/${{ args.username }}.json' } },
+        { map: {
+                username: '${{ item.id }}',
+                karma: '${{ item.karma }}',
+                created: `\${{ item.created ? new Date(item.created * 1000).toISOString().slice(0, 10) : '' }}`,
+                about: '${{ item.about }}',
+            } },
+    ],
+});