@isomoes/iread 0.1.0 → 0.2.2

package/README.md

@@ -4,6 +4,8 @@ A concise, local, single-user RSS/Atom reader inspired by newsboat. Keyboard-fir
 
 There is no auth, no multi-user, no cloud sync, and no background scheduler. Refresh is always user-initiated. All data lives in a single local SQLite file — by default `~/.config/iread/iread.db` — which is the trust boundary.
 
+![iread UI](https://github.com/user-attachments/assets/ca9489c9-630f-4a67-9cd5-60c18ce3544e)
+
 ## Quick start
 
 ```sh
@@ -19,6 +21,9 @@ Options:
   -p, --port <port>  Port to listen on (default: $PORT or 8787)
       --db <path>    SQLite database file
                      (default: $DB_PATH or ~/.config/iread/iread.db)
+      --opml <path>  OPML file auto-saved on every subscription change
+                     (default: $OPML_PATH or feeds.opml next to the database;
+                     pass "" to disable)
   -v, --version      Print the version and exit
   -h, --help         Show this help and exit
 ```
@@ -35,7 +40,7 @@ Options:
 - Star and unstar.
 - Live case-insensitive search over title plus summary in the current view.
 - Full keyboard navigation as the primary interaction model.
-- OPML import (bulk add) and OPML export.
+- OPML import (bulk add) and OPML export, plus an always-current `feeds.opml` auto-saved next to the database on every change for quick sharing and backup. The auto-saved file is a one-way snapshot of the database (overwritten on every change and at startup), so use it for backup and sharing — to bring feeds in, use OPML import.
 - Light, dark, and system theme, persisted to localStorage.
 
 ## Requirements (development)
@@ -78,7 +83,7 @@ pnpm start
 
 Open http://localhost:8787
 
-`PORT` (default 8787) and `DB_PATH` (default `~/.config/iread/iread.db`) are read from the environment. See `config/.env.example`.
+`PORT` (default 8787), `DB_PATH` (default `~/.config/iread/iread.db`), and `OPML_PATH` (default `feeds.opml` next to the database; set empty to disable the auto-saved mirror) are read from the environment. See `config/.env.example`.
 
 ## Publish to npm
 
@@ -114,6 +119,7 @@ Keys are case-sensitive (Shift matters). Bindings fire only when you are not typ
 | `r` | Refresh current feed | Refresh the selected feed, or the feed of the selected article in a smart view. |
 | `R` | Refresh all feeds | Refresh every feed and update counts on completion. |
 | `v` | Open original | Open the article link in a new tab. |
+| `#` then N | Open link by number | Links in the article body are numbered inline `[N]`; press `#`, type the number, and it opens in a new tab — instantly once the number is unambiguous, otherwise `Enter` confirms; `Esc` cancels. |
 | `/` | Focus search | Focus and select the search input. |
 | `Esc` | Contextual dismiss | Close help, clear search, or return focus from the reader to the list. |
 | `?` | Help overlay | Toggle the keybinding overlay. |

package/dist/server/cli.js

@@ -30,6 +30,9 @@ Options:
   -p, --port <port>  Port to listen on (default: $PORT or 8787)
       --db <path>    SQLite database file
                      (default: $DB_PATH or ~/.config/iread/iread.db)
+      --opml <path>  OPML file auto-saved on every subscription change
+                     (default: $OPML_PATH or feeds.opml next to the database;
+                     pass "" to disable)
   -v, --version      Print the version and exit
   -h, --help         Show this help and exit
 `;
@@ -74,6 +77,13 @@ for (let i = 0; i < args.length; i++) {
             process.env.DB_PATH = value;
             break;
         }
+        case '--opml': {
+            const value = args[++i];
+            if (value === undefined)
+                fail('--opml requires a file path (pass "" to disable)');
+            process.env.OPML_PATH = value;
+            break;
+        }
         default:
             fail(`unknown option: ${arg}`);
     }
@@ -81,4 +91,3 @@ for (let i = 0; i < args.length; i++) {
 // Serve the prebuilt web bundle unless the caller explicitly set NODE_ENV.
 process.env.NODE_ENV ??= 'production';
 await import('./index.js');
-//# sourceMappingURL=cli.js.map

package/dist/server/db.js

@@ -21,7 +21,7 @@ function defaultDbPath() {
 const DB_PATH = process.env.DB_PATH ?? defaultDbPath();
 // Resolve to an absolute path and ensure the containing directory exists
 // (DatabaseSync will not create intermediate directories on its own).
-const dbPath = resolve(process.cwd(), DB_PATH);
+export const dbPath = resolve(process.cwd(), DB_PATH);
 mkdirSync(dirname(dbPath), { recursive: true });
 export const db = new DatabaseSync(dbPath);
 // Connection PRAGMAs. WAL keeps readers from erroring during writes;
@@ -155,4 +155,3 @@ export function totalChanges() {
     const row = db.prepare('SELECT total_changes() AS n').get();
     return row.n;
 }
-//# sourceMappingURL=db.js.map

package/dist/server/feed-service.js

@@ -9,6 +9,7 @@ import { db, transaction, totalChanges, queryAll, queryGet, run, } from './db.js
 import { fetchFeed } from './fetch-feed.js';
 import { assertSafeFeedUrl } from './ssrf.js';
 import { sanitizeArticleHtml, toPlainText } from './sanitize.js';
+import { writeOpmlSnapshot } from './opml-sync.js';
 const SUMMARY_MAX = 280;
 const LIMIT_DEFAULT = 50;
 const LIMIT_MAX = 200;
@@ -211,7 +212,12 @@ const UPDATE_FEED_ON_SUCCESS = `
     last_fetched_at = ?, fetch_error = NULL
   WHERE id = ?
 `;
-async function refreshFeedRow(row) {
+// Phase 1 (async, no DB, runs concurrently across feeds): fetch + parse + sanitize.
+// Never throws — a failed fetch/parse becomes an 'error' plan so the caller's loop
+// always completes. CRITICAL (review fix #13): the new etag/last_modified are
+// carried in the plan and persisted only by applyRefresh, after a fully
+// successful parse+upsert.
+async function planRefresh(row) {
     const now = Date.now();
     try {
         const result = await fetchFeed({
@@ -219,30 +225,56 @@ async function refreshFeedRow(row) {
             etag: row.etag,
             lastModified: row.last_modified,
         });
-        if (result.kind === 'notModified') {
+        if (result.kind === 'notModified')
+            return { kind: 'notModified', now };
+        const { feedMeta, commit } = await parseAndPrepare(row.feed_url, result.xml);
+        return {
+            kind: 'ok',
+            now,
+            feedMeta,
+            commit,
+            etag: result.etag,
+            lastModified: result.lastModified,
+        };
+    }
+    catch (err) {
+        return { kind: 'error', now, message: err instanceof Error ? err.message : String(err) };
+    }
+}
+// Record a failed refresh on the feed row. Shared by the error-plan branch and the
+// catch fallback so the UPDATE + error outcome live in exactly one place.
+function recordFeedError(row, now, message) {
+    db.prepare(`UPDATE feeds SET last_fetched_at = ?, fetch_error = ? WHERE id = ?`).run(now, message, row.id);
+    return { feed: getFeedWithCounts(row.id), newItems: 0, ok: false };
+}
+// Phase 2 (synchronous DB writes): apply one plan. Fully synchronous — it never
+// awaits — so even when called from concurrent fetch workers its writes can't
+// overlap and node:sqlite never awaits mid-transaction. Only the commit + feed-row
+// update run inside the transaction.
+function applyRefresh(row, plan) {
+    try {
+        if (plan.kind === 'notModified') {
             // 304: nothing changed. Update last_fetched_at and clear any prior error.
-            db.prepare(`UPDATE feeds SET last_fetched_at = ?, fetch_error = NULL WHERE id = ?`).run(now, row.id);
+            db.prepare(`UPDATE feeds SET last_fetched_at = ?, fetch_error = NULL WHERE id = ?`).run(plan.now, row.id);
             return { feed: getFeedWithCounts(row.id), newItems: 0, ok: true };
         }
-        // Parse + sanitize OUTSIDE the transaction (async, CPU work, no DB). Only the
-        // synchronous DB writes (commit) run inside the transaction so node:sqlite
-        // never awaits mid-transaction. CRITICAL (review fix #13): the new
-        // etag/last_modified are persisted only here, after a fully successful
-        // parse+upsert.
-        const { feedMeta, commit } = await parseAndPrepare(row.feed_url, result.xml);
-        const newItems = transaction(() => {
-            const inserted = commit(row.id);
-            db.prepare(UPDATE_FEED_ON_SUCCESS).run(feedMeta.title, feedMeta.siteUrl, feedMeta.description, result.etag, result.lastModified, now, row.id);
-            return inserted;
-        });
-        return { feed: getFeedWithCounts(row.id), newItems, ok: true };
+        if (plan.kind === 'ok') {
+            const newItems = transaction(() => {
+                const inserted = plan.commit(row.id);
+                db.prepare(UPDATE_FEED_ON_SUCCESS).run(plan.feedMeta.title, plan.feedMeta.siteUrl, plan.feedMeta.description, plan.etag, plan.lastModified, plan.now, row.id);
+                return inserted;
+            });
+            return { feed: getFeedWithCounts(row.id), newItems, ok: true };
+        }
+        return recordFeedError(row, plan.now, plan.message);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        db.prepare(`UPDATE feeds SET last_fetched_at = ?, fetch_error = ? WHERE id = ?`).run(now, message, row.id);
-        return { feed: getFeedWithCounts(row.id), newItems: 0, ok: false };
+        return recordFeedError(row, plan.now, err instanceof Error ? err.message : String(err));
     }
 }
+async function refreshFeedRow(row) {
+    return applyRefresh(row, await planRefresh(row));
+}
 function getFeedRow(id) {
     return queryGet(`SELECT * FROM feeds WHERE id = ?`, id);
 }
@@ -253,32 +285,59 @@ export async function refreshFeed(id) {
     if (!row)
         throw new ServiceError('NOT_FOUND', 'Feed not found.');
     const outcome = await refreshFeedRow(row);
+    syncOpmlMirror();
     return { feed: outcome.feed, newItems: outcome.newItems };
 }
-/** Refresh every feed sequentially. Never fails because one feed errored;
- *  tallies refreshed/failed/newItems and returns the full updated feed list. */
+// Max feeds fetched+parsed at once in refreshAll. Bounded so we never open
+// hundreds of sockets or buffer hundreds of 10 MB bodies simultaneously.
+const REFRESH_CONCURRENCY = 8;
+// Map items through an async worker with at most `limit` in flight, preserving
+// input order in the result. Used to overlap the per-feed fetch/parse/apply work.
+async function mapWithConcurrency(items, limit, worker) {
+    const results = new Array(items.length);
+    let next = 0;
+    const runners = Array.from({ length: Math.min(limit, items.length) }, () => (async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await worker(items[i], i);
+        }
+    })());
+    await Promise.all(runners);
+    return results;
+}
+/** Refresh every feed. Each feed's fetch + parse runs concurrently (bounded by
+ *  REFRESH_CONCURRENCY) and its synchronous apply runs in the same worker, so the
+ *  DB writes serialize naturally and only ~concurrency feeds' parsed content is held
+ *  at once. Never fails because one feed errored; tallies refreshed/failed/newItems
+ *  and returns the full updated list. */
 export async function refreshAll() {
     const rows = queryAll(`SELECT * FROM feeds ORDER BY id ASC`);
     let refreshed = 0;
     let failed = 0;
     let newItems = 0;
-    // Sequential, one transaction per feed (commit per feed keeps each transaction
-    // short on the synchronous DB; one failure never aborts the loop).
-    for (const row of rows) {
+    // Each worker fetches+parses (concurrent) then applies its own plan (synchronous,
+    // so applies never overlap and node:sqlite stays happy). The try/catch guarantees
+    // the batch always completes: even if applyRefresh's own error path throws (a
+    // DB-level fault), that feed is tallied as failed rather than aborting the request.
+    const outcomes = await mapWithConcurrency(rows, REFRESH_CONCURRENCY, async (row) => {
         try {
-            const outcome = await refreshFeedRow(row);
-            if (outcome.ok)
-                refreshed += 1;
-            else
-                failed += 1;
-            newItems += outcome.newItems;
+            const outcome = applyRefresh(row, await planRefresh(row));
+            return { ok: outcome.ok, newItems: outcome.newItems };
         }
         catch {
-            // refreshFeedRow already records its own errors; this guards against any
-            // unexpected throw so the loop always completes.
-            failed += 1;
+            return { ok: false, newItems: 0 };
         }
+    });
+    for (const outcome of outcomes) {
+        if (outcome.ok)
+            refreshed += 1;
+        else
+            failed += 1;
+        newItems += outcome.newItems;
     }
+    syncOpmlMirror();
     return { feeds: listFeeds().feeds, refreshed, failed, newItems };
 }
 // ---------------------------------------------------------------------------
@@ -336,6 +395,7 @@ export async function addFeed(url) {
     const feed = getFeedWithCounts(feedId);
     if (!feed)
         throw new ServiceError('NOT_FOUND', 'Feed disappeared after insert.');
+    syncOpmlMirror();
     return feed;
 }
 // ---------------------------------------------------------------------------
@@ -345,6 +405,7 @@ export function deleteFeed(id) {
     const res = run(`DELETE FROM feeds WHERE id = ?`, id);
     if (res.changes === 0)
         throw new ServiceError('NOT_FOUND', 'Feed not found.');
+    syncOpmlMirror();
 }
 // ---------------------------------------------------------------------------
 // listItems (PLAN 7 GET /api/items) — dynamic WHERE built from fixed fragments
@@ -513,6 +574,7 @@ export async function importFeeds(urls) {
             }
         }
     }
+    syncOpmlMirror();
     return { added, skipped, failed, feeds: listFeeds().feeds };
 }
 /** All feeds as plain Feed DTOs (for OPML export). */
@@ -520,4 +582,6 @@ export function listFeedsForExport() {
     const rows = queryAll(`SELECT * FROM feeds ORDER BY title COLLATE NOCASE ASC, id ASC`);
     return rows.map(mapFeed);
 }
-//# sourceMappingURL=feed-service.js.map
+export function syncOpmlMirror() {
+    writeOpmlSnapshot(listFeedsForExport());
+}

package/dist/server/fetch-feed.js

@@ -80,4 +80,3 @@ export async function fetchFeed(input) {
         clearTimeout(timer);
     }
 }
-//# sourceMappingURL=fetch-feed.js.map

package/dist/server/index.js

@@ -17,6 +17,8 @@ const IS_PROD = process.env.NODE_ENV === 'production';
 // Importing ./db has the side effect of opening the DB and running migrations.
 // Do it explicitly so startup failures surface immediately.
 import './db.js';
+import { syncOpmlMirror } from './feed-service.js';
+syncOpmlMirror();
 const app = new Hono();
 // --- API routes (registered FIRST) -----------------------------------------
 const api = new Hono();
@@ -59,4 +61,3 @@ serve({ fetch: app.fetch, port: PORT }, (info) => {
     console.log(`[iread] listening on ${url}`);
 });
 export { app };
-//# sourceMappingURL=index.js.map

package/dist/server/opml-sync.js

@@ -0,0 +1,41 @@
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { dbPath } from './db.js';
+import { exportOpml } from './opml.js';
+function resolveMirrorPath() {
+    const override = process.env.OPML_PATH;
+    if (override !== undefined) {
+        const trimmed = override.trim();
+        return trimmed === '' ? null : resolve(process.cwd(), trimmed);
+    }
+    return join(dirname(dbPath), 'feeds.opml');
+}
+export const opmlMirrorPath = resolveMirrorPath();
+function withoutDateCreated(xml) {
+    return xml.replace(/[ \t]*<dateCreated>.*?<\/dateCreated>\r?\n?/, '');
+}
+export function writeOpmlSnapshot(feeds) {
+    if (!opmlMirrorPath)
+        return;
+    try {
+        const xml = exportOpml(feeds);
+        let existing = null;
+        try {
+            existing = readFileSync(opmlMirrorPath, 'utf-8');
+        }
+        catch {
+            existing = null;
+        }
+        if (existing !== null && withoutDateCreated(existing) === withoutDateCreated(xml)) {
+            return;
+        }
+        mkdirSync(dirname(opmlMirrorPath), { recursive: true });
+        const tmp = `${opmlMirrorPath}.tmp`;
+        writeFileSync(tmp, xml, 'utf-8');
+        renameSync(tmp, opmlMirrorPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[iread] could not write OPML mirror at ${opmlMirrorPath}: ${message}`);
+    }
+}

package/dist/server/opml.js

@@ -102,6 +102,7 @@ export function importOpml(xml) {
 // ---------------------------------------------------------------------------
 function escapeXmlAttr(value) {
     return value
+        .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
         .replace(/&/g, '&')
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;')
@@ -134,4 +135,3 @@ export function exportOpml(feeds) {
     lines.push('');
     return lines.join('\n');
 }
-//# sourceMappingURL=opml.js.map

package/dist/server/routes/feeds.js

@@ -65,4 +65,3 @@ feeds.delete('/:id', (c) => {
         return serviceErrorToResponse(c, err);
     }
 });
-//# sourceMappingURL=feeds.js.map

package/dist/server/routes/helpers.js

@@ -41,4 +41,3 @@ export function parseOptionalInt(raw) {
     const n = Number(raw);
     return Number.isFinite(n) ? Math.trunc(n) : undefined;
 }
-//# sourceMappingURL=helpers.js.map

package/dist/server/routes/items.js

@@ -92,4 +92,3 @@ items.patch('/:id', async (c) => {
         return serviceErrorToResponse(c, err);
     }
 });
-//# sourceMappingURL=items.js.map

package/dist/server/routes/opml.js

@@ -47,4 +47,3 @@ opml.post('/', async (c) => {
     const body = result;
     return c.json(body, 200);
 });
-//# sourceMappingURL=opml.js.map

package/dist/server/sanitize.js

@@ -72,4 +72,3 @@ export function sanitizeArticleHtml(raw) {
 export function toPlainText(raw) {
     return sanitizeHtml(raw, { allowedTags: [], allowedAttributes: {} });
 }
-//# sourceMappingURL=sanitize.js.map

package/dist/server/ssrf.js

@@ -272,4 +272,3 @@ export async function fetchWithGuardedRedirects(initialUrl, init) {
     }
     throw new SsrfError(`Too many redirects (> ${MAX_REDIRECTS}).`);
 }
-//# sourceMappingURL=ssrf.js.map

package/dist/shared/types.js

@@ -2,4 +2,3 @@
 // Shared between the Hono server and the React client. Type-only (no runtime code).
 // Timestamps are Unix epoch milliseconds. Import everywhere with `import type`.
 export {};
-//# sourceMappingURL=types.js.map