Keith Solomon
64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# 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`
|
|
|
|
- [x] 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.
|
|
- [x] 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`
|
|
|
|
- [x] Implement the minimal production behavior required for the tests.
|
|
- [x] 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`
|
|
|
|
- [x] Implement `nlc init`, `nlc run`, help text, date flag validation, dry run, enrichment-only, and fixture-backed smoke execution.
|
|
- [x] Add OAuth/browser-flow boundaries for Gmail and Sheets without requiring live credentials during automated tests.
|
|
- [x] Add provider adapters for Anthropic, OpenAI, local endpoints, and OpenAI-compatible endpoints.
|
|
|
|
### Task 4: Docs and Build
|
|
|
|
**Files:**
|
|
|
|
- Create `README.md`, `config.example.yaml`
|
|
|
|
- [x] Document setup, OAuth files, token persistence, Google Sheets and Excel output, binary build tooling, and local smoke flow.
|
|
- [x] 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.
|