@abhi-r-27/feedwatch 1.0.0

package/README.md

@@ -0,0 +1,16 @@
+# rss-cli
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.10. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+

package/commands/add.js

@@ -0,0 +1,37 @@
+// commands/add.js
+// TICKET 1.2 — Register a feed URL to the local store
+//
+// Usage: feedwatch add <name> <url>
+
+import chalk from 'chalk';
+import { loadStore, saveStore, getFeed, addFeed } from '../lib/store.js';
+import { ValidationError, handleError }           from '../lib/errors.js';
+
+export function registerAdd(program) {
+  program
+    .command('add <name> <url>')
+    .description('Register a feed URL to watch')
+    .action((name, url) => {
+      try {
+        // Validate URL
+        try { new URL(url); } catch {
+          throw new ValidationError(`Invalid URL: ${url}`);
+        }
+
+        const store = loadStore();
+
+        if (getFeed(store, name)) {
+          throw new ValidationError(`A feed named "${name}" already exists. Use a different name.`);
+        }
+
+        addFeed(store, name, url);
+        saveStore(store);
+
+        console.log(chalk.green(`✔ Added feed "${name}"`));
+        console.log(chalk.gray(`  URL: ${url}`));
+        console.log(chalk.gray(`  Run "feedwatch run" to fetch it.`));
+      } catch (err) {
+        handleError(err);
+      }
+    });
+}

package/commands/list.js

@@ -0,0 +1,49 @@
+// commands/list.js
+// TICKET 1.2 — Display all registered feeds
+//
+// Usage: feedwatch list
+
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import { loadStore } from '../lib/store.js';
+import { handleError } from '../lib/errors.js';
+
+export function registerList(program) {
+  program
+    .command('list')
+    .description('List all registered feeds')
+    .action(() => {
+      try {
+        const store = loadStore();
+
+        if (store.feeds.length === 0) {
+          console.log(chalk.yellow('No feeds registered.'));
+          console.log(chalk.gray('  Add one with: feedwatch add <n> <url>'));
+          process.exit(0);
+        }
+
+        const table = new Table({
+          head:  ['Name', 'URL', 'Last Fetched', 'New Items (last run)'],
+          style: { head: ['cyan'] },
+        });
+
+        for (const feed of store.feeds) {
+          table.push([
+            chalk.white(feed.name),
+            chalk.gray(feed.url.length > 50 ? feed.url.slice(0, 47) + '...' : feed.url),
+            feed.lastFetchedAt
+              ? chalk.gray(new Date(feed.lastFetchedAt).toLocaleString())
+              : chalk.gray('never'),
+            feed.lastNewCount > 0
+              ? chalk.green(String(feed.lastNewCount))
+              : chalk.gray('0'),
+          ]);
+        }
+
+        console.log(table.toString());
+        console.log(chalk.gray(`  ${store.feeds.length} feed(s) registered`));
+      } catch (err) {
+        handleError(err);
+      }
+    });
+}

package/commands/read.js

@@ -0,0 +1,271 @@
+// commands/read.js
+// TICKET 1.6 — Navigable read mode for a single feed
+//
+// Usage:
+//   feedwatch read <n>           — fetch and browse latest items
+//   feedwatch read <n> --max 20  — show up to 20 items
+//
+// UX flow:
+//   1. Fetch the feed
+//   2. Show item list as arrow-key select menu
+//   3. On selection — display full description in read mode
+//   4. Press any key to return to the item list
+//   5. Select "Exit" to quit
+
+import { select }    from '@inquirer/prompts';
+import chalk         from 'chalk';
+import ora           from 'ora';
+import axios         from 'axios';
+import { fetchAll }  from '../lib/fetcher.js';
+import { parseXML }  from '../lib/parser.js';
+import { loadStore } from '../lib/store.js';
+import { handleError, NotFoundError } from '../lib/errors.js';
+import { resolveConfig } from '../lib/config.js';
+import { createLogger }  from '../lib/logger.js';
+
+// ── Fetch full article body ───────────────────────────────────────────────────
+
+async function fetchArticleBody(url, timeout) {
+  try {
+    const response = await axios.get(url, {
+      timeout,
+      headers: { 'User-Agent': 'feedwatch/1.0 (feed reader)' },
+      responseType: 'text',
+    });
+    return response.data;
+  } catch {
+    return null;  // fall back to feed description on any error
+  }
+}
+
+// ── Content extraction ────────────────────────────────────────────────────────
+//
+// Raw article pages contain nav bars, inline CSS, inline JS, JSON blobs,
+// and footer markup alongside the actual article text. Passing the full
+// HTML through stripHTML() produces unusable output — nav items, CSS class
+// names, and script tokens all end up in the rendered text.
+//
+// Strategy (applied in order, stops at first match):
+//   1. Strip <script> and <style> blocks entirely — they are never content.
+//   2. Extract the <article> element if present — most editorial sites use it.
+//   3. Extract the <main> element as a fallback.
+//   4. If neither exists, collect all <p> and <h2> tags whose stripped text
+//      is longer than 20 characters. This threshold filters single-word nav
+//      items ("Home", "Sport", "Terms of Use") while preserving short but
+//      real sentences ("He feels it is quite ironic.").
+
+function extractContent(html) {
+  // Step 1: remove script and style blocks — these are never readable content
+  let cleaned = html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '');
+
+  // Step 2: prefer <article> — present on most modern editorial sites
+  const articleMatch = cleaned.match(/<article[^>]*>([\s\S]*?)<\/article>/i);
+  if (articleMatch) return articleMatch[1];
+
+  // Step 3: fall back to <main>
+  const mainMatch = cleaned.match(/<main[^>]*>([\s\S]*?)<\/main>/i);
+  if (mainMatch) return mainMatch[1];
+
+  // Step 4: no semantic container — harvest individual <p> and <h2> tags.
+  // Threshold of 20 chars drops nav atoms while keeping short real sentences.
+  const MIN_CHARS = 20;
+  const blocks = [];
+
+  const tagPattern = /<(p|h2)[^>]*>([\s\S]*?)<\/\1>/gi;
+  let match;
+  while ((match = tagPattern.exec(cleaned)) !== null) {
+    const [full, tag, inner] = match;
+    const text = inner.replace(/<[^>]*>/g, '').trim();
+    if (text.length > MIN_CHARS) blocks.push(full);
+  }
+
+  return blocks.join('\n\n');
+}
+
+// ── HTML → plain text ─────────────────────────────────────────────────────────
+
+function stripHTML(html) {
+  return (html || '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/p>/gi, '\n\n')
+    .replace(/<\/h2>/gi, '\n\n')
+    .replace(/<[^>]*>/g, '')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#039;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    // Collapse runs of blank lines down to a single blank line
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+// ── Read mode display ─────────────────────────────────────────────────────────
+
+function wordWrap(text, width = 72) {
+  const lines = [];
+  for (const para of text.split('\n')) {
+    if (para.trim() === '') { lines.push(''); continue; }
+    const words = para.split(' ');
+    let current = '';
+    for (const word of words) {
+      if ((current + ' ' + word).trim().length > width) {
+        if (current) lines.push(current);
+        current = word;
+      } else {
+        current = current ? current + ' ' + word : word;
+      }
+    }
+    if (current) lines.push(current);
+  }
+  return lines;
+}
+
+async function showArticle(item, config) {
+  console.clear();
+  console.log('');
+  console.log(chalk.bold.white('  ' + (item.title || '(no title)')));
+  console.log('');
+
+  if (item.pubDate) {
+    const date = new Date(item.pubDate).toLocaleString();
+    console.log(chalk.gray(`  Published: ${date}`));
+  }
+  if (item.link) {
+    console.log(chalk.gray(`  Link:      ${item.link}`));
+  }
+
+  console.log('');
+  console.log(chalk.gray('  ' + '─'.repeat(68)));
+  console.log('');
+
+  // Prefer the full article page over the feed description snippet.
+  // extractContent() isolates article body before stripHTML runs,
+  // so the reader sees article text — not nav bars or inline CSS.
+  let body = null;
+  if (item.link) {
+    const spinner = ora({ text: chalk.gray('  Fetching article...'), color: 'gray' }).start();
+    const html = await fetchArticleBody(item.link, config.timeout);
+    spinner.stop();
+    if (html) body = stripHTML(extractContent(html));
+  }
+
+  // Fall back to feed description if fetch failed or item has no link.
+  // The feed description is already plain text (or light HTML), so
+  // extractContent is not needed — a direct stripHTML is sufficient.
+  if (!body) body = stripHTML(item.description || '');
+
+  if (!body) {
+    console.log(chalk.gray('  (No content available for this article.)'));
+  } else {
+    const wrapped = wordWrap(body);
+    for (const line of wrapped) {
+      console.log(line ? '  ' + chalk.white(line) : '');
+    }
+  }
+
+  console.log('');
+  console.log(chalk.gray('  ' + '─'.repeat(68)));
+  console.log('');
+}
+
+// ── Wait for keypress ─────────────────────────────────────────────────────────
+
+function waitForKey(prompt = 'Press any key to go back...') {
+  return new Promise(resolve => {
+    process.stdout.write(chalk.gray(`  ${prompt}`));
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.once('data', () => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write('\n');
+      resolve();
+    });
+  });
+}
+
+// ── Main command ──────────────────────────────────────────────────────────────
+
+export function registerRead(program) {
+  program
+    .command('read <n>')
+    .description('Browse and read items from a registered feed')
+    .option('--max <n>', 'Max items to load', '20')
+    .action(async (name, opts) => {
+      try {
+        const store = loadStore();
+        const feed  = store.feeds.find(f => f.name === name);
+
+        if (!feed) {
+          throw new NotFoundError(`No feed named "${name}". Run "feedwatch list" to see registered feeds.`);
+        }
+
+        const { config } = resolveConfig();
+        const logger     = createLogger(config.logLevel);
+        const spinner    = ora(`Fetching "${name}"...`).start();
+
+        const results = await fetchAll([feed], config, logger);
+        spinner.stop();
+
+        const result = results[0];
+        if (result.status === 'failed') {
+          console.log(chalk.red(`✖ Failed to fetch "${name}": ${result.error.message}`));
+          process.exit(1);
+        }
+
+        const maxItems = parseInt(opts.max, 10) || 20;
+        const items    = parseXML(result.xml).slice(0, maxItems);
+
+        if (items.length === 0) {
+          console.log(chalk.yellow(`No items found in "${name}".`));
+          process.exit(0);
+        }
+
+        // ── Interactive browse loop ───────────────────────────────────────────
+
+        while (true) {
+          console.clear();
+          console.log('');
+          console.log(chalk.bold(`  ${name}`) + chalk.gray(`  (${items.length} items)`));
+          console.log(chalk.gray(`  ${feed.url}`));
+          console.log('');
+
+          const choices = [
+            ...items.map((item, i) => {
+              const title = (item.title || '(no title)').slice(0, 60);
+              const date  = item.pubDate
+                ? chalk.gray(' · ' + new Date(item.pubDate).toLocaleDateString())
+                : '';
+              return { name: `${chalk.cyan(String(i + 1).padStart(2, '0'))}  ${title}${date}`, value: i };
+            }),
+            { name: chalk.gray('─── Exit'), value: 'exit' },
+          ];
+
+          const choice = await select({
+            message: 'Select an item to read',
+            choices,
+            pageSize: 15,
+          });
+
+          if (choice === 'exit') {
+            console.clear();
+            process.exit(0);
+          }
+
+          await showArticle(items[choice], config);
+          await waitForKey();
+        }
+
+      } catch (err) {
+        if (err.name === 'ExitPromptError') {
+          console.clear();
+          process.exit(0);
+        }
+        handleError(err);
+      }
+    });
+}

package/commands/remove.js

@@ -0,0 +1,43 @@
+// commands/remove.js
+// TICKET 1.2 — Remove a registered feed
+//
+// Usage: feedwatch remove <n>
+
+import { confirm }                                from '@inquirer/prompts';
+import chalk                                      from 'chalk';
+import { loadStore, saveStore, getFeed, removeFeed } from '../lib/store.js';
+import { NotFoundError, handleError }             from '../lib/errors.js';
+
+export function registerRemove(program) {
+  program
+    .command('remove <n>')
+    .description('Remove a registered feed')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .action(async (name, opts) => {
+      try {
+        const store = loadStore();
+        const feed  = getFeed(store, name);
+
+        if (!feed) {
+          throw new NotFoundError(`No feed named "${name}". Run "feedwatch list" to see registered feeds.`);
+        }
+
+        if (!opts.yes) {
+          const confirmed = await confirm({
+            message: `Remove feed "${name}" (${feed.url})?`,
+            default: false,
+          });
+          if (!confirmed) {
+            console.log(chalk.gray('Cancelled.'));
+            process.exit(0);
+          }
+        }
+
+        removeFeed(store, name);
+        saveStore(store);
+        console.log(chalk.green(`✔ Removed feed "${name}"`));
+      } catch (err) {
+        handleError(err);
+      }
+    });
+}

package/commands/run.js

@@ -0,0 +1,162 @@
+// commands/run.js
+// TICKET 1.3 — Fetch engine (Promise.allSettled, retry)
+// TICKET 1.4 — RSS/Atom parsing and normalisation
+// TICKET 1.5 — State diffing and change detection
+// TICKET 1.6 — Output formatting, --json, exit codes
+//
+// Usage:
+//   feedwatch run
+//   feedwatch run --all         show all items, not just new
+//   feedwatch run --json        output raw JSON
+//   feedwatch run --timeout 5000
+
+import chalk   from 'chalk';
+import ora     from 'ora';
+import Table   from 'cli-table3';
+import { fetchAll }                                   from '../lib/fetcher.js';
+import { parseXML }                                   from '../lib/parser.js';
+import { loadStore, saveStore, getSeenGuids,
+         updateSeen, updateFeedMeta }                 from '../lib/store.js';
+import { handleError }                                from '../lib/errors.js';
+import { resolveConfig }                              from '../lib/config.js';
+import { createLogger }                               from '../lib/logger.js';
+
+export function registerRun(program) {
+  program
+    .command('run')
+    .description('Fetch all registered feeds and report new items')
+    .option('--all',              'Show all items, not just new ones')
+    .option('--json',             'Output results as JSON')
+    .option('--timeout  <ms>',    'Request timeout in ms')
+    .option('--retries  <n>',     'Max retry attempts')
+    .option('--log-level <level>','Log level (debug|info|warn|error)')
+    .action(async (opts) => {
+      try {
+        const { config } = resolveConfig({
+          timeout:  opts.timeout,
+          retries:  opts.retries,
+          logLevel: opts.logLevel,
+        });
+        const logger = createLogger(config.logLevel);
+        const store  = loadStore();
+
+        if (store.feeds.length === 0) {
+          console.log(chalk.yellow('No feeds registered.'));
+          console.log(chalk.gray('  Add one with: feedwatch add <n> <url>'));
+          process.exit(0);
+        }
+
+        const spinner = ora(`Fetching ${store.feeds.length} feed(s)...`).start();
+
+        // TICKET 1.3: concurrent fetch with allSettled + retry
+        const fetchResults = await fetchAll(store.feeds, config, logger);
+
+        spinner.stop();
+
+        // TICKET 1.4 + 1.5: parse, diff, update seen state
+        const runResults = [];
+        let anyFailed    = false;
+
+        for (const result of fetchResults) {
+          if (result.status === 'failed') {
+            anyFailed = true;
+            runResults.push({ name: result.name, status: 'failed', items: [], error: result.error });
+            continue;
+          }
+
+          const items    = parseXML(result.xml);
+          const seenSet  = getSeenGuids(store, result.name);
+          const allGuids = items.map(i => i.guid || i.link || i.title);
+
+          const newItems  = items.filter((item, idx) => !seenSet.has(allGuids[idx]));
+          const seenItems = items.filter((item, idx) =>  seenSet.has(allGuids[idx]));
+
+          // Update seen state with all current guids
+          updateSeen(store, result.name, allGuids);
+          updateFeedMeta(store, result.name, {
+            lastFetchedAt: new Date().toISOString(),
+            lastNewCount:  newItems.length,
+          });
+
+          runResults.push({
+            name:      result.name,
+            status:    'ok',
+            newItems,
+            seenItems,
+            allItems:  items,
+            error:     null,
+          });
+        }
+
+        saveStore(store);
+
+        // TICKET 1.6: output
+        if (opts.json) {
+          console.log(JSON.stringify(runResults.map(r => ({
+            name:   r.name,
+            status: r.status,
+            new:    r.newItems?.length ?? 0,
+            items:  (opts.all ? r.allItems : r.newItems) ?? [],
+            error:  r.error?.message ?? null,
+          })), null, 2));
+        } else {
+          printResults(runResults, opts.all);
+        }
+
+        process.exit(anyFailed ? 1 : 0);
+      } catch (err) {
+        handleError(err);
+      }
+    });
+}
+
+// ── Output helpers ────────────────────────────────────────────────────────────
+
+function printResults(results, showAll) {
+  let totalNew = 0;
+
+  for (const r of results) {
+    console.log('');
+
+    if (r.status === 'failed') {
+      console.log(chalk.red(`✖ ${r.name}`) + chalk.gray(` — FAILED: ${r.error.message}`));
+      continue;
+    }
+
+    const items = showAll ? r.allItems : r.newItems;
+    totalNew += r.newItems.length;
+
+    if (items.length === 0) {
+      console.log(chalk.gray(`  ${r.name} — no ${showAll ? '' : 'new '}items`));
+      continue;
+    }
+
+    console.log(chalk.bold(`  ${r.name}`) + chalk.gray(` — ${r.newItems.length} new`));
+
+    const table = new Table({
+      head:  ['Status', 'Title', 'Published', 'Link'],
+      style: { head: ['cyan'] },
+      colWidths: [8, 40, 22, 40],
+    });
+
+    for (const item of items) {
+      const isNew  = r.newItems.includes(item);
+      const status = isNew ? chalk.green('NEW') : chalk.gray('SEEN');
+      const title  = truncate(item.title || '(no title)', 38);
+      const date   = item.pubDate ? new Date(item.pubDate).toLocaleDateString() : '';
+      const link   = truncate(item.link || '', 38);
+      table.push([status, title, date, chalk.gray(link)]);
+    }
+
+    console.log(table.toString());
+  }
+
+  console.log('');
+  console.log(totalNew > 0
+    ? chalk.green(`  ${totalNew} new item(s) found`)
+    : chalk.gray('  No new items'));
+}
+
+function truncate(str, max) {
+  return str.length > max ? str.slice(0, max - 1) + '…' : str;
+}

package/feedwatch.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// feedwatch.js — Entry point
+// TICKET 1.7 — shebang + bin field wired in package.json
+//
+// Run:
+//   feedwatch add <n> <url>      Register a feed
+//   feedwatch remove <n>         Remove a feed
+//   feedwatch list               List all registered feeds
+//   feedwatch run                Fetch all feeds, report new items
+//   feedwatch run --all          Show all items, not just new
+//   feedwatch run --json         Output raw JSON
+//   feedwatch read <n>           Show latest items for one feed
+//   feedwatch config show        Display resolved config
+
+import { Command } from 'commander';
+import chalk       from 'chalk';
+import Table       from 'cli-table3';
+
+import { registerAdd }    from './commands/add.js';
+import { registerRemove } from './commands/remove.js';
+import { registerList }   from './commands/list.js';
+import { registerRun }    from './commands/run.js';
+import { registerRead }   from './commands/read.js';
+import { resolveConfig }  from './lib/config.js';
+import { handleError }    from './lib/errors.js';
+
+const program = new Command();
+
+program
+  .name('feedwatch')
+  .description('Monitor RSS and Atom feeds for new items')
+  .version('1.0.0');
+
+// ── Register subcommands ──────────────────────────────────────────────────────
+
+registerAdd(program);
+registerRemove(program);
+registerList(program);
+registerRun(program);
+registerRead(program);
+
+// ── config show — TICKET 1.1 ──────────────────────────────────────────────────
+
+const configCmd = program.command('config').description('Config management');
+
+configCmd
+  .command('show')
+  .description('Display resolved configuration with source per key')
+  .option('--config <path>', 'Path to config file')
+  .action((opts) => {
+    try {
+      // opts - parsed command-line options
+      const { config, sources, configPath, fileFound } = resolveConfig({}, opts.config || null);
+
+      console.log('');
+      console.log(chalk.bold('  Resolved Configuration'));
+      console.log(chalk.gray(`  Config file: ${configPath} ${fileFound ? chalk.green('(found)') : chalk.yellow('(not found — using defaults)')}`));
+      console.log('');
+
+      const SOURCE_COLOR = {
+        default: chalk.gray,
+        file:    chalk.blue,
+        env:     chalk.yellow,
+        flag:    chalk.green,
+      };
+
+      const table = new Table({
+        head:  ['Key', 'Value', 'Source'],
+        style: { head: ['cyan'] },
+      });
+
+      for (const [key, value] of Object.entries(config)) {
+        const source  = sources[key] || 'default';
+        const colorFn = SOURCE_COLOR[source] || chalk.white;
+        table.push([key, String(value), colorFn(source)]);
+      }
+
+      console.log(table.toString());
+      console.log(
+        chalk.gray('  Sources: ') +
+        chalk.gray('default') + '  ' +
+        chalk.blue('file')    + '  ' +
+        chalk.yellow('env')   + '  ' +
+        chalk.green('flag')
+      );
+      console.log('');
+    } catch (err) {
+      handleError(err);
+    }
+  });
+
+// ── SIGINT / SIGTERM graceful shutdown ────────────────────────────────────────
+
+function shutdown(signal) {
+  process.stderr.write(chalk.gray(`\n  Received ${signal} — shutting down cleanly.\n`));
+  process.exit(0);
+}
+process.on('SIGINT',  () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+
+// ── Parse ─────────────────────────────────────────────────────────────────────
+
+program.parse(process.argv);
+
+
+/*
+
+Tech/Dev
+
+Hacker News: https://news.ycombinator.com/rss
+GitHub Blog: https://github.blog/feed/
+CSS Tricks: https://css-tricks.com/feed/
+
+News
+
+BBC Top Stories: http://feeds.bbci.co.uk/news/rss.xml
+Reuters: https://feeds.reuters.com/reuters/topNews
+
+# 1. Install dependencies
+cd feedwatch
+bun install
+
+# 2. Register the feed
+bun feedwatch.js add hn https://news.ycombinator.com/rss
+
+# 3. Confirm it was saved
+bun feedwatch.js list
+
+# 4. First run — all items will be NEW (nothing seen yet)
+bun feedwatch.js run
+
+# 5. Run again immediately — all items now SEEN (state was saved)
+bun feedwatch.js run
+
+# 6. Wait a few minutes, run again — new HN posts will appear as NEW
+bun feedwatch.js run
+
+# 7. Read items for a single feed without updating seen state
+bun feedwatch.js read hn
+
+# 8. See the full config
+bun feedwatch.js config show
+
+# 9. Override config via env var — observe source column changes
+FEEDWATCH_TIMEOUT=3000 bun feedwatch.js config show
+*/

package/lib/config.js

@@ -0,0 +1,128 @@
+// lib/config.js
+// TICKET 1.1 — Layered configuration
+//
+// Resolution order (each layer overrides the previous):
+//   1. Hardcoded defaults
+//   2. feedwatch.config.json (default location, or --config <path>)
+//   3. Environment variables (FEEDWATCH_RETRIES, FEEDWATCH_TIMEOUT, etc.)
+//   4. CLI flags (--retries, --timeout, --max-items, --log-level)
+
+import fs   from 'fs';
+import path from 'path';
+import os   from 'os';
+
+// ── Layer 1: Defaults ─────────────────────────────────────────────────────────
+
+const DEFAULTS = {
+  retries:  3,
+  timeout:  8000,
+  maxItems: 10,
+  logLevel: 'info',
+};
+
+const DEFAULT_CONFIG_PATH = path.join(os.homedir(), '.feedwatch', 'config.json');
+
+// ── Schema ────────────────────────────────────────────────────────────────────
+
+const SCHEMA = {
+  retries:  { type: 'number', min: 0,   max: 10    },
+  timeout:  { type: 'number', min: 500, max: 60000 },
+  maxItems: { type: 'number', min: 1,   max: 100   },
+  logLevel: { type: 'string', allowed: ['debug', 'info', 'warn', 'error'] },
+};
+
+function validate(config, source) {
+  const errors = [];
+  for (const [key, val] of Object.entries(config)) {
+    if (!SCHEMA[key]) { errors.push(`Unknown key "${key}" in ${source}`); continue; }
+    const s = SCHEMA[key];
+    if (s.type === 'number') {
+      if (typeof val !== 'number' || isNaN(val)) errors.push(`"${key}" must be a number`);
+      else if (s.min !== undefined && val < s.min) errors.push(`"${key}" must be >= ${s.min}`);
+      else if (s.max !== undefined && val > s.max) errors.push(`"${key}" must be <= ${s.max}`);
+    }
+    if (s.type === 'string') {
+      if (typeof val !== 'string') errors.push(`"${key}" must be a string`);
+      else if (s.allowed && !s.allowed.includes(val))
+        errors.push(`"${key}" must be one of: ${s.allowed.join(', ')}`);
+    }
+  }
+  if (errors.length) {
+    errors.forEach(e => process.stderr.write(`Config error: ${e}\n`));
+    process.exit(1);
+  }
+}
+
+// ── Layer 2: Config file ──────────────────────────────────────────────────────
+
+function loadFile(configPath) {
+  if (!fs.existsSync(configPath)) return { values: {}, found: false };
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`Error reading config file ${configPath}: ${err.message}\n`);
+    process.exit(1);
+  }
+  validate(parsed, configPath);
+  return { values: parsed, found: true };
+}
+
+// ── Layer 3: Environment variables ───────────────────────────────────────────
+
+function loadEnv() {
+  const env = {};
+  // load process ENV variables
+  const num = (key, envKey) => {
+    if (!process.env[envKey]) return;
+    const n = parseInt(process.env[envKey], 10);
+    if (isNaN(n)) process.stderr.write(`Warning: ${envKey} is not a valid number — ignored\n`);
+    else env[key] = n;
+  };
+  num('retries',  'FEEDWATCH_RETRIES');
+  num('timeout',  'FEEDWATCH_TIMEOUT');
+  num('maxItems', 'FEEDWATCH_MAX_ITEMS');
+  if (process.env.FEEDWATCH_LOG_LEVEL) {
+    const v = process.env.FEEDWATCH_LOG_LEVEL.toLowerCase();
+    if (SCHEMA.logLevel.allowed.includes(v)) env.logLevel = v;
+    else process.stderr.write(`Warning: FEEDWATCH_LOG_LEVEL="${v}" is not valid — ignored\n`);
+  }
+  return env;
+}
+
+// ── Layer 4: CLI flags ────────────────────────────────────────────────────────
+
+function loadFlags(opts = {}) {
+  const flags = {};
+  if (opts.retries  !== undefined) flags.retries  = parseInt(opts.retries,  10);
+  if (opts.timeout  !== undefined) flags.timeout  = parseInt(opts.timeout,  10);
+  if (opts.maxItems !== undefined) flags.maxItems = parseInt(opts.maxItems, 10);
+  if (opts.logLevel !== undefined) flags.logLevel = opts.logLevel;
+  return flags;
+}
+
+// ── Resolve ───────────────────────────────────────────────────────────────────
+
+export function resolveConfig(opts = {}, configPathOverride = null) {
+  const configPath = configPathOverride || DEFAULT_CONFIG_PATH;
+  const file       = loadFile(configPath);
+  const env        = loadEnv();
+  console.log(env);
+  
+  const flags      = loadFlags(opts);
+
+  const config = { ...DEFAULTS, ...file.values, ...env, ...flags };
+
+  // Track source of each key for `config show`
+  const sources = {};
+  for (const key of Object.keys(DEFAULTS)) {
+    if      (flags[key]      !== undefined) sources[key] = 'flag';
+    else if (env[key]        !== undefined) sources[key] = 'env';
+    else if (file.values[key]!== undefined) sources[key] = 'file';
+    else                                    sources[key] = 'default';
+  }
+
+  return { config, sources, configPath, fileFound: file.found };
+}
+
+export { DEFAULT_CONFIG_PATH, DEFAULTS };

package/lib/errors.js

@@ -0,0 +1,50 @@
+// lib/errors.js
+// TICKET 1.1 (production requirements) — Custom error classes + centralised handler
+
+import chalk from 'chalk';
+import fs    from 'fs';
+import path  from 'path';
+
+const LOG_FILE = path.join(process.cwd(), 'feedwatch.log');
+
+// ── Custom error classes ──────────────────────────────────────────────────────
+
+/*
+The sequence is:
+- super(message) → create the base Error object
+
+Error sets properties like:
+- message
+- stack
+
+Then your class adds:
+- name
+- exitCode
+*/
+
+export class ValidationError extends Error {
+  constructor(message) { super(message); this.name = 'ValidationError'; this.exitCode = 1; }
+}
+
+export class NotFoundError extends Error {
+  constructor(message) { super(message); this.name = 'NotFoundError'; this.exitCode = 1; }
+}
+
+export class FileSystemError extends Error {
+  constructor(message) { super(message); this.name = 'FileSystemError'; this.exitCode = 1; }
+}
+
+// ── Centralised handler ───────────────────────────────────────────────────────
+
+export function handleError(err) {
+  const ts   = new Date().toISOString();
+  const line = `[${ts}] [ERROR] ${err.name}: ${err.message}\n${err.stack}\n`;
+
+  // Always log to file
+  try { fs.appendFileSync(LOG_FILE, line); } catch { /* ignore log write failures */ }
+
+  // User-facing message
+  process.stderr.write(chalk.red(`Error: ${err.message}\n`));
+
+  process.exit(err.exitCode ?? 1);
+}

package/lib/fetcher.js

@@ -0,0 +1,162 @@
+// lib/fetcher.js
+// TICKET 1.3 — Concurrent fetch engine
+//
+// fetchAll(feeds, config, logger):
+//   Fetches all feeds concurrently with Promise.allSettled.
+//   Each request retries on network errors and 5xx responses.
+//   Returns array of { name, url, status, xml, error }
+
+/*
+Error Propagation and Handling
+
+The custom errors defined in `lib/fetcher.js` (`NetworkError`, `FeedError`) are **not handled inside the fetcher itself**. Instead, they are intentionally **propagated upward** to the CLI layer.
+
+The fetch engine uses `Promise.allSettled()` when fetching feeds concurrently. This means that if a single feed fails, the error is captured in the result rather than crashing the entire program.
+
+Each settled result is converted into a structured object:
+
+```
+{ name, url, status, xml, error }
+```
+
+If a request fails, the `error` field contains the thrown `NetworkError` or `FeedError`. The CLI command (for example `feedwatch run`) then formats and displays this information to the user.
+
+This design ensures that:
+
+* one failing feed does **not stop other feeds from processing**
+* errors remain **structured and inspectable**
+* the CLI layer controls **how failures are presented to the user**
+
+*/
+
+import axios from 'axios';
+
+// ── Custom error classes ──────────────────────────────────────────────────────
+
+export class NetworkError extends Error {
+  constructor(message, feedName, originalError) {
+    super(message);
+    this.name = 'NetworkError';
+    this.feedName = feedName;
+    this.originalError = originalError; // Preserve for debugging
+    this.exitCode = 1;
+  }
+}
+
+export class FeedError extends Error {
+  constructor(message, status, feedName, originalError) {
+    super(message);
+    this.name = 'FeedError';
+    this.status = status;
+    this.feedName = feedName;
+    this.originalError = originalError; // Preserve for debugging
+    this.exitCode = 1;
+  }
+}
+
+// ── Retry logic ───────────────────────────────────────────────────────────────
+
+function isRetryable(err) {
+  if (axios.isAxiosError(err)) {
+    if (!err.response) return true;              // network error
+    const s = err.response.status;
+    return s === 429 || s >= 500; // too many requests or server errors
+  }
+  return false;
+}
+
+async function withRetry(fn, feedName, maxRetries, logger) {
+  let lastErr;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      // invokes fetch function - with retries handled in catch block
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+
+      // Check retryability BEFORE wrapping
+      if (!isRetryable(err) || attempt === maxRetries) {
+        // Now wrap based on error type
+        if (axios.isAxiosError(err)) {
+          if (!err.response) {
+            throw new NetworkError(err.message, feedName, err);
+          }
+          throw new FeedError(`HTTP ${err.response.status}`, err.response.status, feedName, err);
+        }
+        throw err; // Non-Axios error
+      }
+
+      const delay = Math.pow(2, attempt) * 200 + Math.random() * 300;
+      logger.debug(`[${feedName}] retry ${attempt + 1}/${maxRetries}`, { delayMs: Math.round(delay) });
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  throw lastErr; // Should never reach here
+}
+
+// ── Fetch one feed ────────────────────────────────────────────────────────────
+
+async function fetchOne(client, feed, maxRetries, logger) {
+  // fetch function (async callback), feed, retries count, logger instance - passed to withRetry
+  const result = await withRetry(async () => {
+    try {
+      const response = await client.get(feed.url);
+      return response.data;
+    } catch (err) {
+      // Don't wrap error type here - let withRetry handle it
+      throw err;
+    }
+  }, feed.name, maxRetries, logger);
+
+  return result;
+}
+
+// ── Fetch all feeds ───────────────────────────────────────────────────────────
+
+// receives feeds from (store), config, instantiated logger - invoked when reading from an RSS source
+export async function fetchAll(feeds, config, logger) {
+  const client = axios.create({ timeout: config.timeout });
+  /*
+  Promise.allSettled sets it automatically. When a promise rejects, 
+  the settled result object is shaped as:
+  { status: 'rejected', reason: <the thrown value> }
+
+  */
+  const settled = await Promise.allSettled(
+    feeds.map(feed => fetchOne(client, feed, config.retries, logger))
+  );
+
+  return settled.map((result, i) => {
+    const feed = feeds[i];
+    if (result.status === 'fulfilled') {
+      // all settled fetch promises provide xml values from feed
+      return { name: feed.name, url: feed.url, status: 'ok', xml: result.value, error: null };
+    } else {
+      return { name: feed.name, url: feed.url, status: 'failed', xml: null, error: result.reason };
+    }
+  });
+}
+
+/*
+
+Trace for a failing feed:
+```
+fetchOne()
+  └─ withRetry()
+       └─ fn() → axios throws (e.g. network error)
+            └─ isRetryable = true → retries...
+            └─ maxRetries exhausted → throw new NetworkError(...)
+  ← NetworkError propagates out of withRetry
+← NetworkError propagates out of fetchOne
+← Promise rejects with NetworkError
+
+Promise.allSettled captures it:
+{ status: 'rejected', reason: NetworkError }
+
+Your map reads result.reason → stored as error field:
+{ name, url, status: 'failed', xml: null, error: NetworkError }
+
+The key insight is that allSettled never throws, it catches every rejection and boxes 
+it into { status, reason }. That's what makes one feed failure safe, other feeds' 
+promises are unaffected and still resolve normally.
+*/

package/lib/logger.js

@@ -0,0 +1,39 @@
+// lib/logger.js
+// TICKET 1.1 — structured logger wired to logLevel from resolved config
+//
+// Usage:
+//   import { createLogger } from './lib/logger.js';
+//   const log = createLogger('info');
+//   log.info('Feed added');
+//   log.debug('Retrying request', { attempt: 2 });
+
+import fs   from 'fs';
+import path from 'path';
+
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+const LOG_FILE = path.join(process.cwd(), 'feedwatch.log');
+
+export function createLogger(level = 'info') {
+  const minLevel = LEVELS[level] ?? LEVELS.info;
+
+  function write(lvl, msg, data) {
+    if (LEVELS[lvl] < minLevel) return;
+    const ts    = new Date().toISOString();
+    const extra = data ? ' ' + JSON.stringify(data) : '';
+    const line  = `[${ts}] [${lvl.toUpperCase()}] ${msg}${extra}`;
+    // debug and info go to stderr so they don't pollute stdout JSON output
+    if (lvl === 'error' || lvl === 'warn') {
+      process.stderr.write(line + '\n');
+      fs.appendFileSync(LOG_FILE, line + '\n');
+    } else {
+      process.stderr.write(line + '\n');
+    }
+  }
+
+  return {
+    debug: (msg, data) => write('debug', msg, data),
+    info:  (msg, data) => write('info',  msg, data),
+    warn:  (msg, data) => write('warn',  msg, data),
+    error: (msg, data) => write('error', msg, data),
+  };
+}

package/lib/parser.js

@@ -0,0 +1,121 @@
+// lib/parser.js
+// TICKET 1.4 — RSS/Atom XML parsing and normalisation
+//
+// Normalised item schema:
+//   { title, link, pubDate, description, guid }
+//
+// Handles:
+//   - RSS 2.0  (<channel><item>)
+//   - Atom 1.0 (<feed><entry>)
+//   - Missing fields default to empty string — no crash on malformed feeds
+//   - pubDate normalised to ISO 8601
+
+import { XMLParser } from 'fast-xml-parser';
+
+const parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: '@_',
+  parseTagValue: true,
+  trimValues: true,
+});
+
+// ── Date normalisation ────────────────────────────────────────────────────────
+
+function toISO(raw) {
+  if (!raw) return '';
+  const d = new Date(raw);
+  return isNaN(d.getTime()) ? String(raw) : d.toISOString();
+}
+
+// ── RSS 2.0 ───────────────────────────────────────────────────────────────────
+
+function parseRSS(parsed) {
+  const channel = parsed?.rss?.channel;
+  if (!channel) return null;
+
+  const rawItems = channel.item || [];
+  const items = Array.isArray(rawItems) ? rawItems : [rawItems];
+
+  return items.map(item => ({
+    title: String(item.title || ''),
+    link: String(item.link || ''),
+    pubDate: toISO(item.pubDate || item['dc:date'] || ''),
+    description: String(item.description || item.summary || ''),
+    guid: String(item.guid?.['#text'] || item.guid || item.link || item.title || ''),
+  }));
+}
+
+// ── Atom 1.0 ──────────────────────────────────────────────────────────────────
+
+function parseAtom(parsed) {
+  const feed = parsed?.feed;
+  if (!feed) return null;
+
+  const rawEntries = feed.entry || [];
+  const entries = Array.isArray(rawEntries) ? rawEntries : [rawEntries];
+
+  return entries.map(entry => {
+    // <link> in Atom can be an object with @_href or a plain string
+    const link = entry.link?.['@_href'] || entry.link || '';
+    return {
+      title: String(entry.title?.['#text'] || entry.title || ''),
+      link: String(link),
+      pubDate: toISO(entry.updated || entry.published || ''),
+      description: String(entry.summary?.['#text'] || entry.summary || entry.content?.['#text'] || ''),
+      guid: String(entry.id || link || entry.title || ''),
+    };
+  });
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Parse raw XML string into normalised items.
+ * Returns [] on any parse error — never throws.
+ */
+export function parseXML(xml) {
+  if (!xml || typeof xml !== 'string') return [];
+  let parsed;
+  try {
+    // parser.parse runs once and just converts the raw XML string into a plain JS object.
+    parsed = parser.parse(xml);
+  } catch {
+    return [];
+  }
+
+  const rssItems = parseRSS(parsed);   // looks for parsed?.rss?.channel
+  if (rssItems) return rssItems;       // found it — return early
+
+  const atomItems = parseAtom(parsed); // looks for parsed?.feed
+  if (atomItems) return atomItems;     // found it — return early
+
+  return [];                           // neither matched
+}
+
+
+/*
+RSS 2.0 structure:
+xml<rss>
+  <channel>
+    <item>
+      <title>...</title>
+      <link>...</link>
+      <pubDate>...</pubDate>
+      <guid>...</guid>
+    </item>
+  </channel>
+</rss>
+
+Atom 1.0 structure:
+xml<feed>
+  <entry>
+    <title type="text">...</title>
+    <link href="..."/>        <!-- href is an attribute, not text content -->
+    <updated>...</updated>    <!-- different date field name -->
+    <id>...</id>              <!-- guid equivalent -->
+  </entry>
+</feed>
+
+parseRSS and parseAtom each know their own shape, and parseXML just tries both RSS first, Atom second;
+returning whichever one finds its root element. If neither matches, it returns [] rather than crashing.
+*/

package/lib/store.js

@@ -0,0 +1,73 @@
+// lib/store.js
+// TICKET 1.2 — Feed registration persistence
+// TICKET 1.5 — Seen-state persistence
+//
+// Store layout (feedwatch-store.json):
+// {
+//   feeds: [{ name, url, addedAt, lastFetchedAt, lastNewCount }],
+//   seen:  { "<feedName>": ["guid1", "guid2", ...] }
+// }
+
+import fs   from 'fs';
+import path from 'path';
+import os   from 'os';
+
+function getStorePaths() {
+  const dir  = process.env.FEEDWATCH_STORE_DIR || path.join(os.homedir(), '.feedwatch');
+  return { dir, path: path.join(dir, 'store.json') };
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+export function loadStore() {
+  const { dir, path: storePath } = getStorePaths();
+  ensureDir(dir);
+  if (!fs.existsSync(storePath)) return { feeds: [], seen: {} };
+  try {
+    return JSON.parse(fs.readFileSync(storePath, 'utf8'));
+  } catch {
+    return { feeds: [], seen: {} };
+  }
+}
+
+export function saveStore(store) {
+  const { dir, path: storePath } = getStorePaths();
+  ensureDir(dir);
+  const tmp = storePath + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(store, null, 2), 'utf8');
+  fs.renameSync(tmp, storePath);
+}
+
+// ── Feed helpers ──────────────────────────────────────────────────────────────
+
+export function getFeed(store, name) {
+  return store.feeds.find(f => f.name === name);
+}
+
+export function addFeed(store, name, url) {
+  store.feeds.push({ name, url, addedAt: new Date().toISOString(), lastFetchedAt: null, lastNewCount: 0 });
+}
+
+export function removeFeed(store, name) {
+  store.feeds  = store.feeds.filter(f => f.name !== name);
+  delete store.seen[name];
+}
+
+// ── Seen-state helpers ────────────────────────────────────────────────────────
+
+export function getSeenGuids(store, feedName) {
+  return new Set(store.seen[feedName] || []);
+}
+
+export function updateSeen(store, feedName, guids) {
+  store.seen[feedName] = guids;
+}
+
+export function updateFeedMeta(store, feedName, { lastFetchedAt, lastNewCount }) {
+  const feed = getFeed(store, feedName);
+  if (!feed) return;
+  feed.lastFetchedAt = lastFetchedAt;
+  feed.lastNewCount  = lastNewCount;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@abhi-r-27/feedwatch",
+  "version": "1.0.0",
+  "description": "CLI tool to monitor RSS and Atom feeds for new items",
+  "type": "module",
+  "bin": {
+    "feedwatch": "./feedwatch.js"
+  },
+  "files": [
+    "feedwatch.js",
+    "commands/",
+    "lib/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test tests/feedwatch.test.js"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "axios": "^1.7.0",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.0.0",
+    "fast-xml-parser": "^4.4.0",
+    "ora": "^8.0.0"
+  }
+}