thinking-phrases 1.0.1 → 2.0.0

package/README.md

@@ -1,6 +1,16 @@
 # Thinking Phrases
 
-Turn your VS Code thinking indicator into a live dashboard. Static tip packs, real-time data sources, AI-powered summaries — all piped into [`chat.agent.thinking.phrases`](https://code.visualstudio.com/updates/v1_110#_custom-thinking-phrases).
+Instead of staring into the abyss while Copilot thinks — contemplating how agents are going to take your job — you could be doing something useful with that dead time.
+
+This hooks into VS Code's [`chat.agent.thinking.phrases`](https://code.visualstudio.com/updates/v1_110#_custom-thinking-phrases) and turns it into a live dashboard. A `launchd` cron job fetches real-time data and swaps your phrases in the background. Interactive CLI to set it up. That's it.
+
+- 📰 **Catch up on the news** — Google News, Hacker News, RSS/Atom, any feed
+- 🐙 **GitHub activity** — commits, org feeds, security advisories, your timeline
+- 🌦️ **Get the weather** — current conditions + severe alerts (lol like I go outside)
+- 📈 **Watch the stock market go brrr** while your agents go brrr
+- 🧠 **Learn something new** — VS Code tips, TypeScript snippets, programming languages
+- 🎮 **Loading screen tips** — WoW, League of Legends... because why not
+- 🤖 **AI-powered summaries** — GitHub Models rewrites articles into concise phrases
 
 ## Quick start
 
@@ -8,30 +18,26 @@ Turn your VS Code thinking indicator into a live dashboard. Static tip packs, re
 npx thinking-phrases --interactive
 ```
 
-That's it. No install, no clone, no config files. The interactive CLI walks you through picking sources, previewing phrases, writing to VS Code settings, and optionally installing a macOS scheduler.
+No install, no clone, no config files. The interactive CLI walks you through picking sources, previewing phrases, writing to VS Code settings, and optionally installing a macOS scheduler.
 
-## Features
+Or just grab the [static thinking phrases](https://github.com/austenstone/thinking-phrases/tree/main/out) directly.
 
-### 8 live data sources
+## Live data sources
 
 | Source | What it shows | Example phrase |
 |--------|--------------|----------------|
-| **RSS / Atom** | Any feed URL | `Ars Technica — Linux 6.14 lands with… — 2h ago` |
-| **Stocks** | Live ticker quotes via Yahoo Finance | `NVDA — $128.44 — ▼ 0.84%` |
-| **Hacker News** | Top/new/best/ask/show/jobs | `Show HN: I built a database in a spreadsheet — 45m ago` |
-| **Earthquakes** | USGS earthquake catalog near a ZIP | `M4.2 — 12 km NE of Ridgecrest, CA — 38m ago` |
-| **Weather Alerts** | NOAA/NWS severe weather by ZIP | `Severe Thunderstorm Warning — Broward, FL — 12m ago` |
-| **Custom JSON** | Any JSON API with configurable field mapping | `My API — Article title — 1h ago` |
-| **GitHub Commits** | Recent repo or org commits with diffs | `vscode@c0ebf3e fix devtools entrypoint (+1 -1) 4h ago - @deepak1556` |
-| **GitHub Feeds** | Org activity, timeline, security advisories | `@dependabot opened a pull request in copilot-sdk — 3m ago` |
-
-### AI-powered formatting
-
-Enable [GitHub Models](https://docs.github.com/en/github-models) and the engine rewrites raw headlines into concise, factual phrases. For GitHub commits, it can digest the **full commit diff** so the summary reflects what actually changed.
+| **RSS / Atom** | Any feed URL | `Copilot code review now accounts for over 20% of all code reviews on GitHub, reflecting a tenfold increase in usage since its launch. — The GitHub Blog (2d ago)` |
+| **Stocks** | Live ticker quotes via Yahoo Finance | `BTC - USD $66,978.23 ▼ 2.02% 🟢` |
+| **Hacker News** | Top/new/best/ask/show/jobs | `Multiple cursors enable simultaneous operations on syntax nodes, significantly enhancing bulk editing and refactoring capabilities. — Hacker News @ravenical 378 pts (17h ago)` |
+| **Earthquakes** | USGS earthquake catalog near a ZIP | `M4.2 — 12 km NE of Ridgecrest, CA — USGS (38m ago)` |
+| **Weather** | Temp, humidity, wind + NWS alerts | `77°F, Mostly Cloudy, Wind E 50 mph — Fort Lauderdale, FL — Weather.gov` |
+| **Custom JSON** | Any JSON API with field mapping | `Article title — My API (1h ago)` |
+| **GitHub Commits** | Repo or org commits with diffs | `fix devtools entrypoint — vscode +1/-1 @deepak1556 (4h ago)` |
+| **GitHub Feeds** | Org activity, timeline, advisories | `opened a pull request in copilot-sdk — @dependabot (3m ago)` |
 
-### Static phrase packs
+## Static phrase packs
 
-Pre-built JSON packs for when you want something stable:
+Pre-built packs for when you just want vibes:
 
 | Pack | Phrases |
 |------|---------|
@@ -43,19 +49,7 @@ Pre-built JSON packs for when you want something stable:
 | WoW loading screen tips | 109 |
 | Inspirational quotes | 1,614 |
 
-### Interactive CLI
-
-A guided terminal UI that walks you through source selection, config, preview, and installation — no flag memorization required.
-
-### macOS scheduler
-
-A `launchd` job that refreshes your phrases on a cron-like interval. Set it to 5 minutes for stocks, an hour for news, whatever you want.
-
-### Multiple config profiles
-
-Keep separate configs for different moods. `configs/github-timeline.config.json` for work, `configs/stocks-only.config.json` for market hours, swap between them.
-
-### One-liner examples
+## Examples
 
 ```bash
 # GitHub org activity feed
@@ -70,37 +64,44 @@ npx thinking-phrases --stocks MSFT,NVDA,TSLA --feed https://github.blog/feed/
 # Earthquakes near a ZIP
 npx thinking-phrases --use-earthquakes --quake-zip 94103 --quake-min-magnitude 2
 
-# Weather alerts near a ZIP
+# Weather conditions + alerts
 npx thinking-phrases --use-weather-alerts --weather-zip 33312
 
-# Dry run (preview only, don't write)
-npx thinking-phrases --dry-run --use-github --github-mode feed --github-feed-kind organization --github-org github
+# Hacker News top stories
+npx thinking-phrases --use-hacker-news --hn-feed top --hn-max-items 15 --hn-min-score 100
 
-# Write to settings
-npx thinking-phrases --use-github --github-mode feed --github-feed-kind organization --github-org github
+# Custom JSON API
+npx thinking-phrases --use-custom-json --json-url "https://hn.algolia.com/api/v1/search?tags=front_page" --json-items-path hits --json-title-field title
+
+# Dry run (preview only, don't write)
+npx thinking-phrases --dry-run --stocks MSFT,NVDA --use-hacker-news
 ```
 
-### Install globally (optional)
+## Install
 
 ```bash
+# Just run it (no install needed)
+npx thinking-phrases --interactive
+
+# Or install globally
 npm install -g thinking-phrases
 thinking-phrases --interactive
-```
 
-### Clone for development
-
-```bash
+# Or clone for development
 git clone https://github.com/austenstone/thinking-phrases.git
 cd thinking-phrases
 npm install
 npm run start:interactive
 ```
 
-## Data sources
+## Data source config
 
-### RSS / Atom feeds
+Each source can be configured via CLI flags, config files, or the interactive CLI. Here's what each one looks like in a config file:
 
-Any RSS or Atom feed URL. Google News, GitHub Blog, Ars Technica, your company blog — whatever you want.
+<details>
+<summary><b>RSS / Atom feeds</b></summary>
+
+Any feed URL. Google News, GitHub Blog, Ars Technica, your company blog — whatever. When AI is enabled, full article HTML is fetched for richer summaries.
 
 ```json
 "feeds": [
@@ -109,34 +110,45 @@ Any RSS or Atom feed URL. Google News, GitHub Blog, Ars Technica, your company b
 ]
 ```
 
-### Stock quotes
+Default refresh: every 6 hours.
+</details>
+
+<details>
+<summary><b>Stock quotes</b></summary>
 
-Live prices via Yahoo Finance. Supports market state labels (pre-market, after-hours).
+Live prices via Yahoo Finance. Pre-market, after-hours, closed labels.
 
 ```json
 "stockQuotes": {
   "enabled": true,
   "symbols": ["MSFT", "NVDA", "TSLA", "AMZN", "GOOGL", "AMD"],
-  "includeMarketState": true
+  "includeMarketState": true,
+  "showClosed": false,
+  "fetchIntervalSeconds": 60
 }
 ```
+</details>
 
-### Hacker News
+<details>
+<summary><b>Hacker News</b></summary>
 
-Top, new, best, ask, show, or jobs feed. Configurable minimum score and item count.
+Top, new, best, ask, show, or jobs feed. Configurable minimum score.
 
 ```json
 "hackerNews": {
   "enabled": true,
   "feed": "top",
   "maxItems": 10,
-  "minScore": 50
+  "minScore": 50,
+  "fetchIntervalSeconds": 300
 }
 ```
+</details>
 
-### Earthquakes (USGS)
+<details>
+<summary><b>Earthquakes (USGS)</b></summary>
 
-Enter a ZIP code and the engine resolves it to lat/lon, then queries the USGS earthquake catalog within a configurable radius.
+Enter a ZIP code or place name → resolves to lat/lon → queries USGS within a radius.
 
 ```json
 "earthquakes": {
@@ -144,26 +156,37 @@ Enter a ZIP code and the engine resolves it to lat/lon, then queries the USGS ea
   "zipCode": "94103",
   "minMagnitude": 2,
   "radiusKm": 500,
-  "limit": 10
+  "windowHours": 24,
+  "limit": 10,
+  "orderBy": "time",
+  "fetchIntervalSeconds": 1800
 }
 ```
+</details>
 
-### Weather alerts (NOAA/NWS)
+<details>
+<summary><b>Weather (NOAA/NWS)</b></summary>
 
-Enter a ZIP code and the engine resolves it to a state, then queries NOAA for active severe weather alerts.
+Current conditions (temp, humidity, wind, description) + active severe weather alerts. Auto-detects location in interactive mode.
 
 ```json
 "weatherAlerts": {
   "enabled": true,
   "zipCode": "33312",
+  "area": "FL",
   "minimumSeverity": "moderate",
-  "limit": 10
+  "limit": 10,
+  "fetchIntervalSeconds": 1800
 }
 ```
 
-### Custom JSON API
+Severity levels: `minor`, `moderate`, `severe`, `extreme`.
+</details>
+
+<details>
+<summary><b>Custom JSON API</b></summary>
 
-Point it at any JSON endpoint. Map title, content, link, source, date, and ID fields. Works with anything that returns an array of objects.
+Point at any JSON endpoint and map the fields. Multiple sources supported via `customJsonSources[]`.
 
 ```json
 "customJson": {
@@ -171,19 +194,21 @@ Point it at any JSON endpoint. Map title, content, link, source, date, and ID fi
   "url": "https://hn.algolia.com/api/v1/search?tags=front_page",
   "itemsPath": "hits",
   "titleField": "title",
+  "contentField": "summary",
   "linkField": "url",
   "sourceLabel": "HN API",
   "dateField": "created_at",
   "idField": "objectID",
-  "maxItems": 10
+  "maxItems": 10,
+  "fetchIntervalSeconds": 3600
 }
 ```
+</details>
 
-### GitHub activity
-
-Three modes for GitHub data:
+<details>
+<summary><b>GitHub activity</b></summary>
 
-**Repo commits** — recent commits from a specific repository. Includes short SHA, line deltas, and author handle in the phrase. When AI is enabled with extra context, the model gets the **full commit diff**.
+Three modes: **repo-commits** (recent commits with diffs), **org-commits** (push events across an org), and **feed** (Atom feeds — org activity, timeline, security advisories, etc.).
 
 ```json
 "githubActivity": {
@@ -192,105 +217,72 @@ Three modes for GitHub data:
   "repo": "microsoft/vscode",
   "branch": "main",
   "maxItems": 10,
-  "tokenEnvVar": "GITHUB_TOKEN"
-}
-```
-
-**Org commits** — recent push events across an entire GitHub organization. Fetches commit details for each push.
-
-```json
-"githubActivity": {
-  "enabled": true,
-  "mode": "org-commits",
-  "org": "github",
-  "maxItems": 10
-}
-```
-
-**Feeds** — GitHub Atom feeds including organization activity, your personal timeline, security advisories, or any custom feed URL. Supports authenticated private feed discovery via `/feeds` with fallback to public org events.
-
-```json
-"githubActivity": {
-  "enabled": true,
-  "mode": "feed",
-  "feedKind": "organization",
-  "org": "github",
-  "maxItems": 20
+  "sinceHours": 24,
+  "tokenEnvVar": "GITHUB_TOKEN",
+  "fetchIntervalSeconds": 300
 }
 ```
 
-Available feed kinds: `timeline`, `current-user-public`, `current-user`, `current-user-actor`, `security-advisories`, `organization`, `custom-url`.
+Feed kinds: `timeline`, `current-user-public`, `current-user`, `current-user-actor`, `security-advisories`, `organization`, `custom-url`.
+</details>
 
-## GitHub Models (AI)
+## AI-powered formatting
 
-When enabled, the engine sends fetched items to GitHub Models for rewriting into concise, factual phrases. Falls back to the normal formatter if auth or inference fails.
+Enable [GitHub Models](https://docs.github.com/en/github-models) and each article gets individually rewritten by AI into a concise phrase. Works with `gpt-4o-mini`, `gpt-5`, `o3`, or any OpenAI-compatible model. Source attribution (`— Source (time)`) is appended automatically — the model just focuses on content.
 
-For GitHub commits specifically, the model receives the full commit diff as additional context when extra content fetching is enabled — so it can summarize what actually changed, not just echo the commit message.
+Results are cached per-article (7-day TTL) so re-runs don't burn tokens. Falls back to template formatting if auth or inference fails.
 
 ```json
 "githubModels": {
   "enabled": true,
-  "model": "openai/gpt-4.1",
+  "model": "openai/gpt-4o-mini",
   "fetchArticleContent": true
 }
 ```
 
-### Auth
+Auth resolves in order: `GITHUB_MODELS_TOKEN` → `GITHUB_TOKEN` → `gh auth token`.
 
-Tokens are resolved in this order for both GitHub API and GitHub Models:
+## Phrase format
 
-1. Configured env var (`GITHUB_MODELS_TOKEN` / `GITHUB_TOKEN`)
-2. `GITHUB_TOKEN` env var
-3. `gh auth token` (GitHub CLI)
+Customizable templates with `%variable%` substitution. The engine auto-strips empty brackets and collapses whitespace.
 
-For GitHub activity, if a token causes 401/403 on public endpoints, it silently retries without auth.
+```json
+"phraseFormatting": {
+  "includeSource": true,
+  "includeTime": true,
+  "maxLength": 140,
+  "templates": {
+    "article": "%title% — %source% (%time%)",
+    "hackerNews": "%title% — HN %score% (%time%)",
+    "stock": "%symbol% %price% %change% %market%",
+    "githubCommit": "%headline% — %repo% %delta% @%author% (%time%)",
+    "githubFeed": "%action% — @%handle% (%time%)"
+  }
+}
+```
 
 ## Presets
 
-The interactive installer includes built-in presets to get started fast:
+The interactive CLI includes presets to get started fast:
 
-| Preset | Sources |
-|--------|---------|
+| Preset | What you get |
+|--------|-------------|
 | **Dev Pulse** | Google Tech news + Hacker News top stories |
-| **Market Watch** | Big-tech stock quotes with fast-refresh defaults |
-| **World Signals** | Earthquakes + severe weather + Hacker News best |
+| **Market Watch** | MSFT, NVDA, AMZN, GOOGL, AMD, TSLA stock quotes |
+| **World Signals** | Earthquakes (M4.5+) + severe weather + Hacker News best |
 
 ## Scheduler (macOS)
 
-The interactive installer can set up a `launchd` scheduler that refreshes your phrases on a timer. If you cloned the repo, you can also install it manually:
-
-```bash
-npm run rss:install             # default: every 3600s (1 hour)
-npm run rss:install -- 300      # every 5 minutes
-npm run rss:install -- 900 ./configs/stocks-only.config.json
-```
-
-The scheduler runs at the OS level. Your VS Code settings update silently in the background.
+A `launchd` job that refreshes phrases in the background. The interactive CLI can set this up, or do it manually:
 
 ```bash
-npm run rss:uninstall           # remove the scheduler
-npx thinking-phrases --uninstall  # remove thinking phrases from settings
+npm run schedule             # every 1 hour (default)
+npm run schedule -- 300      # every 5 minutes
+npm run schedule:trigger     # run now
+npm run schedule:remove      # remove it
 ```
 
-## Config profiles
-
-Keep multiple configs in `configs/` and switch between them:
-
-```text
-configs/
-  rss-settings.config.json
-  github-timeline.config.json
-  github-commits.config.json
-  google-news.config.json
-  google-technology-stocks.config.json
-  hn-best-earthquakes-weather-alerts.config.json
-  stocks-only.config.json
-```
-
-```bash
-npm run rss:run -- --config configs/stocks-only.config.json
-npm run rss:install -- 300 configs/stocks-only.config.json
-```
+Also available via CLI flags: `--install-scheduler`, `--trigger-scheduler-now`, `--uninstall-scheduler`.
 
 ## Static packs
 
@@ -327,33 +319,129 @@ Standalone string arrays — just drop them in:
 - WoW loading screen tips (109)
 - Inspirational quotes (1,614 — from `dwyl/quotes`, GPL-2.0)
 
+Install a static pack directly:
+
+```bash
+npx thinking-phrases --static-pack out/typescript-tips.json
+```
+
 ## CLI reference
 
+### Commands
+
 | Command | Description |
 |---------|-------------|
 | `npx thinking-phrases --interactive` | Guided interactive setup |
 | `npx thinking-phrases --dry-run` | Preview phrases without writing |
 | `npx thinking-phrases` | Write phrases to VS Code settings |
 | `npx thinking-phrases --uninstall` | Remove thinking phrases from settings |
-
-All `--flags` from the data source sections above work with any of these commands.
+| `npx thinking-phrases --static-pack <path>` | Install a static phrase pack |
+
+### Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Load a saved config file |
+| `--settings <path>` | Custom VS Code settings.json path |
+| `--dry-run` | Preview phrases without writing to settings |
+| `--verbose` | Verbose output |
+| `--debug` | Debug output (includes verbose) |
+| `--limit <num>` | Max total phrases (default: 100) |
+| `--mode append\|replace` | Append to or replace existing phrases |
+| `--target auto\|insiders\|stable` | Which VS Code edition to target |
+| `--max-length <num>` | Max phrase length in characters (default: 140) |
+| `--no-source` | Omit source attribution from phrases |
+| `--no-time` | Omit relative time from phrases |
+
+### Source flags
+
+| Flag | Description |
+|------|-------------|
+| `--feed <url>` | Add an RSS/Atom feed URL (repeatable) |
+| `--use-stocks` / `--no-stocks` | Enable/disable stock quotes |
+| `--stocks <SYMBOLS>` | Comma-separated stock tickers |
+| `--use-hacker-news` | Enable Hacker News |
+| `--hn-feed <type>` | top, new, best, ask, show, or jobs |
+| `--hn-max-items <num>` | Max HN items |
+| `--hn-min-score <num>` | Minimum HN score filter |
+| `--use-earthquakes` | Enable earthquake source |
+| `--quake-zip <zip>` | ZIP code for earthquake search center |
+| `--quake-place <name>` | Place name for earthquake search |
+| `--quake-min-magnitude <num>` | Minimum magnitude filter |
+| `--quake-radius-km <num>` | Search radius in km |
+| `--quake-hours <num>` | Time window in hours |
+| `--quake-order time\|magnitude` | Sort order |
+| `--quake-limit <num>` | Max earthquake results |
+| `--use-weather-alerts` | Enable weather source |
+| `--weather-zip <zip>` | ZIP code for weather |
+| `--weather-area <area>` | US state code (e.g. FL) |
+| `--weather-severity <level>` | Minimum severity (minor/moderate/severe/extreme) |
+| `--weather-limit <num>` | Max weather alert results |
+| `--use-custom-json` | Enable custom JSON source |
+| `--json-url <url>` | JSON endpoint URL |
+| `--json-items-path <path>` | JSONPath to items array |
+| `--json-title-field <field>` | Field name for title |
+| `--json-content-field <field>` | Field name for content |
+| `--json-link-field <field>` | Field name for link |
+| `--json-source-field <field>` | Field name for source |
+| `--json-source-label <label>` | Fallback source label |
+| `--json-date-field <field>` | Field name for date |
+| `--json-id-field <field>` | Field name for ID |
+| `--json-max-items <num>` | Max JSON items |
+| `--use-github` | Enable GitHub activity |
+| `--github-mode <mode>` | repo-commits, org-commits, or feed |
+| `--github-repo <owner/repo>` | Target repository |
+| `--github-org <org>` | Target organization |
+| `--github-branch <branch>` | Branch filter |
+| `--github-feed-kind <kind>` | Feed type (see GitHub activity section) |
+| `--github-feed-url <url>` | Custom feed URL |
+| `--github-max-items <num>` | Max GitHub items |
+| `--github-since-hours <num>` | Lookback window in hours |
+| `--github-token-env <var>` | Env var name for GitHub token |
+
+### AI model flags
+
+| Flag | Description |
+|------|-------------|
+| `--use-models` / `--no-models` | Enable/disable AI rewriting |
+| `--model <name>` | Model ID (default: `openai/gpt-4o-mini`) |
+| `--models-endpoint <url>` | Inference endpoint |
+| `--models-token-env <var>` | Env var for model auth token |
+| `--models-max-concurrency <num>` | Parallel inference requests |
+| `--models-max-input-items <num>` | Max articles sent to model |
+| `--models-max-input-tokens <num>` | Max input token budget |
+| `--models-max-tokens <num>` | Max output tokens per request |
+| `--models-max-phrases-per-article <num>` | Phrases generated per article |
+| `--models-temperature <0-1>` | Sampling temperature |
+| `--fetch-article-content` / `--no-fetch-article-content` | Fetch full article HTML for AI |
+| `--max-article-content-length <num>` | Max chars of article body sent to model |
+
+### Scheduler flags
+
+| Flag | Description |
+|------|-------------|
+| `--install-scheduler` | Install/update macOS launchd job |
+| `--trigger-scheduler-now` | Trigger the scheduler immediately |
+| `--uninstall-scheduler` | Remove the launchd job |
 
 ## How it works
 
 ```
-Sources → Normalize → Format → Write
+Sources → Normalize → Format → Cache → Write
 ```
 
-1. **Sources** fetch live data (RSS, stocks, GitHub, USGS, NOAA, JSON APIs)
-2. **Core** normalizes everything into article or stock items
-3. **Formatter** builds phrases — either basic `source — title — time` or AI-rewritten via GitHub Models
-4. **Sink** writes the final phrases into VS Code `settings.json`
+1. **Sources** fetch live data (RSS, stocks, GitHub, USGS, NOAA, JSON APIs) — each respects its own refresh interval
+2. **Core** normalizes everything into `ArticleItem` or `StockItem` objects
+3. **Formatter** builds display phrases from customizable templates — content first, source/metadata suffix appended
+4. **AI** (optional) rewrites phrases via GitHub Models, with per-article caching to avoid redundant inference
+5. **Phrase store** persists phrases per-source in `~/.cache/thinking-phrases/` so different refresh intervals don't clobber each other
+6. **Sink** writes the merged phrases into VS Code `settings.json` using `jsonc-parser` (preserves comments and formatting)
 
-The source catalog is modular. Each source is a simple `{ isEnabled, fetch }` object registered in the catalog. Adding a new source means writing one file and registering it.
+The source catalog is modular. Each source is a `{ type, isEnabled, fetch }` object registered in the catalog. Adding a new source means writing one file and registering it.
 
 ## Portability
 
-Settings path auto-detection works on macOS, Linux, and Windows. Supports both VS Code Stable and Insiders. You can also pass `--settings` to point at any path.
+Settings path auto-detection works on macOS, Linux, and Windows. Supports both VS Code Stable and Insiders. You can also pass `--settings` to point at any path or `--target` to force a specific edition.
 
 ## References