Gator

Status: WIP — core CLI flows are usable, but persistence and aggregation features are still evolving.

Overview

Gator is a TypeScript CLI for collecting, following, and periodically aggregating RSS feeds. It uses Drizzle ORM on PostgreSQL, stores user/feed relationships, and fetches feed content with fast-xml-parser.

Features

• Multi-user CLI with register, login, and users commands.
• Manage personal or shared RSS feeds (addfeed, feeds, follow, unfollow, following).
• Interval-based aggregator (agg) that fetches and prints new feed items.
• Postgres schema and migrations defined with Drizzle.

Requirements

• Node.js 18+
• PostgreSQL instance and connection URL
• Writable home directory for ~/.gatorconfig.json

Installation

1. Install dependencies

   npm install

2. Create a Postgres database and ensure the connection URL is reachable.
3. Generate types (optional, if schema changes)

   npm run generate

4. Run migrations

   npm run migrate

5. Create ~/.gatorconfig.json:

   {
     "db_url": "postgres://user:password@localhost:5432/gator",
     "current_user_name": "anonymous"
   }

Usage

Invoke commands via the package script:

npm run start -- <command> [args...]

Available commands:

Command	Description
register <name>	Create a new user and set it as current.
login <name>	Switch the active CLI user.
users	List users; marks the current user.
reset	Truncate all users (and cascading feed data).
addfeed <name> <url>	Create a feed owned by the current user and follow it.
feeds	Print all feeds with fetched RSS content.
follow <url>	Follow an existing feed by URL.
following	Show feeds the current user follows.
unfollow <url>	Remove the follow relationship.
agg <interval>	Poll feeds forever (Ctrl+C to stop). Intervals support ms, s, m, h (e.g., 5m).

The aggregator prints each fetched feed item. It currently does not persist fetched articles—see roadmap below.

Configuration

• ~/.gatorconfig.json must stay in sync with your Postgres URL and active user.
• The CLI reads this file at startup and updates it when commands change the active user.

Project Structure

src/
  commands/      # Command handlers for CLI verbs
  config.ts      # Config reader/writer for ~/.gatorconfig.json
  index.ts       # CLI entry point and command registry
  lib/db/        # Drizzle schema, queries, migrations
  middleware.ts  # Helpers for authenticated commands
  rss/           # RSS fetch/parsing utilities
drizzle.config.ts  # Drizzle CLI configuration

Roadmap (WIP)

• Persist fetched articles instead of printing them only once.
• Improve error handling and CLI output formatting.
• Add automated tests for command flows and RSS parsing.
• Provide Docker-based setup for Postgres and migrations.