Newsletter-Link-Catalog/docs/superpowers/plans/2026-05-16-newsletter-link-catalog.md

Newsletter Link Catalog Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build a production-quality TypeScript CLI named nlc that extracts newsletter links from Gmail, cleans and categorizes them, enriches metadata, writes Google Sheets and Excel outputs, and supports credential-free local validation.

Architecture: The CLI is split into small modules for command parsing, config validation, Gmail access, parsing plugins, link cleanup, categorization, LLM adapters, output writers, enrichment, state, and orchestration. Live external services are isolated behind interfaces so tests and smoke runs use fixtures and fakes.

Tech Stack: Node.js, TypeScript, Commander, Cheerio, Zod, googleapis, xlsx, Vitest, ESLint, Prettier, tsup.

---

Task 1: Scaffold and Tests

Files:

• Create: package.json, tsconfig.json, .eslintrc.cjs, .prettierrc.json, vitest.config.ts

• Create tests in tests/*.test.ts

• Write tests covering config validation, date conflicts, sheet names, URL cleanup, read-more merging, noise filtering, sponsor detection, categorization, state behavior, enrichment statuses, dry-run suppression, and parser plugin selection.

• Run tests once to confirm they fail before production modules exist.

Task 2: Core Modules

Files:

• Create modules under src/config, src/links, src/parsing, src/categorization, src/state, src/enrichment, src/output

• Implement the minimal production behavior required for the tests.

• Keep integrations behind interfaces and dependency injection.

Task 3: CLI and Integrations

Files:

• Create src/index.ts, src/cli/*, src/gmail/*, src/llm/*, src/run/*, scripts/smoke.mjs

• Implement nlc init, nlc run, help text, date flag validation, dry run, enrichment-only, and fixture-backed smoke execution.

• Add OAuth/browser-flow boundaries for Gmail and Sheets without requiring live credentials during automated tests.

• Add provider adapters for Anthropic, OpenAI, local endpoints, and OpenAI-compatible endpoints.

Task 4: Docs and Build

Files:

• Create README.md, config.example.yaml

• Document setup, OAuth files, token persistence, Google Sheets and Excel output, binary build tooling, and local smoke flow.

• Configure npm run build to compile and bundle the CLI.

Task 5: Validation

Commands:

• npm install
• npm run lint
• npm run format:check
• npm run typecheck
• npm test
• npm run build
• npm run smoke

Self-review: The plan maps every SPEC.md subsystem to a module or integration boundary. Live Gmail, Sheets, and LLM validation require user credentials, so local validation uses fakes and fixtures while docs describe operational setup.