thinking-phrases 1.0.1 → 2.0.0

package/src/core/taskHealth.ts

@@ -0,0 +1,213 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export type TaskHealthStatus = 'running' | 'succeeded' | 'failed';
+export type TaskHealthPhase =
+  | 'initializing'
+  | 'fetching-sources'
+  | 'formatting-phrases'
+  | 'writing-settings'
+  | 'updating-scheduler'
+  | 'completed'
+  | 'failed';
+export type TaskHealthSourceStatus = 'pending' | 'running' | 'succeeded' | 'failed';
+
+export interface TaskHealthSourceEntry {
+  type: string;
+  status: TaskHealthSourceStatus;
+  startedAt?: string;
+  completedAt?: string;
+  durationMs?: number;
+  itemCount?: number;
+  error?: string;
+}
+
+export interface TaskHealthSummary {
+  sourceCount: number;
+  articleCount: number;
+  stockCount: number;
+  phraseCount: number;
+}
+
+export interface TaskHealthReport {
+  status: TaskHealthStatus;
+  phase: TaskHealthPhase;
+  startedAt: string;
+  updatedAt: string;
+  completedAt?: string;
+  durationMs?: number;
+  dryRun: boolean;
+  configPath?: string;
+  settingsPath?: string;
+  pid: number;
+  lastMessage?: string;
+  error?: string;
+  warnings: string[];
+  sources: TaskHealthSourceEntry[];
+  summary?: TaskHealthSummary;
+}
+
+export const TASK_HEALTH_PATH = resolve(process.cwd(), 'launchd', 'task-health.json');
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function durationMs(startedAt: string, completedAt: string): number {
+  return Math.max(0, new Date(completedAt).getTime() - new Date(startedAt).getTime());
+}
+
+function writeTaskHealth(report: TaskHealthReport): void {
+  mkdirSync(dirname(TASK_HEALTH_PATH), { recursive: true });
+  const tempPath = `${TASK_HEALTH_PATH}.tmp`;
+  writeFileSync(tempPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  renameSync(tempPath, TASK_HEALTH_PATH);
+}
+
+export function readTaskHealth(): TaskHealthReport | null {
+  try {
+    return JSON.parse(readFileSync(TASK_HEALTH_PATH, 'utf8')) as TaskHealthReport;
+  } catch {
+    return null;
+  }
+}
+
+export class TaskHealthTracker {
+  private report: TaskHealthReport;
+
+  constructor(input: { dryRun: boolean; configPath?: string; settingsPath?: string }) {
+    const startedAt = nowIso();
+    this.report = {
+      status: 'running',
+      phase: 'initializing',
+      startedAt,
+      updatedAt: startedAt,
+      dryRun: input.dryRun,
+      configPath: input.configPath,
+      settingsPath: input.settingsPath,
+      pid: process.pid,
+      warnings: [],
+      sources: [],
+      lastMessage: 'Booting thinking-phrases run',
+    };
+    this.persist();
+  }
+
+  get filePath(): string {
+    return TASK_HEALTH_PATH;
+  }
+
+  setSources(sourceTypes: string[]): void {
+    this.report.sources = sourceTypes.map(type => ({ type, status: 'pending' as const }));
+    this.touch('initializing', `Prepared ${sourceTypes.length} source${sourceTypes.length === 1 ? '' : 's'} for execution`);
+  }
+
+  setPhase(phase: TaskHealthPhase, message: string): void {
+    this.touch(phase, message);
+  }
+
+  setDryRun(dryRun: boolean): void {
+    this.report.dryRun = dryRun;
+    this.report.updatedAt = nowIso();
+    this.persist();
+  }
+
+  startSource(sourceType: string): void {
+    const startedAt = nowIso();
+    this.updateSource(sourceType, {
+      status: 'running',
+      startedAt,
+      completedAt: undefined,
+      durationMs: undefined,
+      itemCount: undefined,
+      error: undefined,
+    });
+    this.touch('fetching-sources', `Fetching ${sourceType}`);
+  }
+
+  completeSource(sourceType: string, itemCount: number): void {
+    const completedAt = nowIso();
+    const source = this.findOrCreateSource(sourceType);
+    this.updateSource(sourceType, {
+      status: 'succeeded',
+      completedAt,
+      durationMs: source.startedAt ? durationMs(source.startedAt, completedAt) : undefined,
+      itemCount,
+    });
+    this.touch('fetching-sources', `Fetched ${itemCount} item${itemCount === 1 ? '' : 's'} from ${sourceType}`);
+  }
+
+  failSource(sourceType: string, error: string): void {
+    const completedAt = nowIso();
+    const source = this.findOrCreateSource(sourceType);
+    this.updateSource(sourceType, {
+      status: 'failed',
+      completedAt,
+      durationMs: source.startedAt ? durationMs(source.startedAt, completedAt) : undefined,
+      error,
+    });
+    this.touch('fetching-sources', `${sourceType} failed`);
+  }
+
+  addWarning(warning: string): void {
+    if (!this.report.warnings.includes(warning)) {
+      this.report.warnings.push(warning);
+    }
+
+    this.report.updatedAt = nowIso();
+    this.persist();
+  }
+
+  succeed(summary: TaskHealthSummary, message: string): void {
+    const completedAt = nowIso();
+    this.report.status = 'succeeded';
+    this.report.phase = 'completed';
+    this.report.summary = summary;
+    this.report.lastMessage = message;
+    this.report.completedAt = completedAt;
+    this.report.updatedAt = completedAt;
+    this.report.durationMs = durationMs(this.report.startedAt, completedAt);
+    this.persist();
+  }
+
+  fail(error: string): void {
+    const completedAt = nowIso();
+    this.report.status = 'failed';
+    this.report.phase = 'failed';
+    this.report.error = error;
+    this.report.lastMessage = error;
+    this.report.completedAt = completedAt;
+    this.report.updatedAt = completedAt;
+    this.report.durationMs = durationMs(this.report.startedAt, completedAt);
+    this.persist();
+  }
+
+  private touch(phase: TaskHealthPhase, message: string): void {
+    this.report.phase = phase;
+    this.report.lastMessage = message;
+    this.report.updatedAt = nowIso();
+    this.persist();
+  }
+
+  private findOrCreateSource(sourceType: string): TaskHealthSourceEntry {
+    const existing = this.report.sources.find(source => source.type === sourceType);
+    if (existing) {
+      return existing;
+    }
+
+    const source = { type: sourceType, status: 'pending' as const };
+    this.report.sources.push(source);
+    return source;
+  }
+
+  private updateSource(sourceType: string, updates: Partial<TaskHealthSourceEntry>): void {
+    const source = this.findOrCreateSource(sourceType);
+    Object.assign(source, updates);
+    this.report.updatedAt = nowIso();
+    this.persist();
+  }
+
+  private persist(): void {
+    writeTaskHealth(this.report);
+  }
+}

package/src/core/types.ts

@@ -9,31 +9,50 @@ export type GitHubFeedKind = 'timeline' | 'current-user-public' | 'current-user'
 export interface FeedConfig {
 	url: string;
 	source?: string;
+	fetchIntervalSeconds?: number;
+}
+
+export interface PhraseFormatTemplates {
+	article?: string;
+	hackerNews?: string;
+	stock?: string;
+	githubCommit?: string;
+	githubFeed?: string;
 }
 
 export interface PhraseFormatting {
 	includeSource: boolean;
 	includeTime: boolean;
 	maxLength: number;
+	templates?: PhraseFormatTemplates;
 }
 
 export interface GitHubModelsConfig {
 	enabled: boolean;
+	endpoint: string;
 	model: string;
 	tokenEnvVar: string;
 	maxInputItems: number;
+	maxInputTokens: number;
 	maxTokens: number;
+	maxConcurrency: number;
 	maxPhrasesPerArticle: number;
 	temperature: number;
 	fetchArticleContent: boolean;
 	maxArticleContentLength: number;
+	/** Default prompt used when no source-specific prompt exists */
 	systemPrompt?: string;
+	/** Per-source prompts keyed by source type (rss, hacker-news, github-activity, earthquakes, custom-json) */
+	prompts?: Record<string, string>;
+	cacheTtlSeconds?: number;
 }
 
 export interface StockQuoteConfig {
 	enabled: boolean;
 	symbols: string[];
 	includeMarketState: boolean;
+	showClosed?: boolean;
+	fetchIntervalSeconds?: number;
 }
 
 export interface HackerNewsConfig {
@@ -41,6 +60,7 @@ export interface HackerNewsConfig {
 	feed: HackerNewsFeed;
 	maxItems: number;
 	minScore: number;
+	fetchIntervalSeconds?: number;
 }
 
 export interface EarthquakeConfig {
@@ -52,6 +72,7 @@ export interface EarthquakeConfig {
 	place?: string;
 	radiusKm: number;
 	orderBy: EarthquakeOrder;
+	fetchIntervalSeconds?: number;
 }
 
 export interface WeatherAlertsConfig {
@@ -60,6 +81,7 @@ export interface WeatherAlertsConfig {
 	area?: string;
 	minimumSeverity: WeatherSeverity;
 	limit: number;
+	fetchIntervalSeconds?: number;
 }
 
 export interface CustomJsonConfig {
@@ -74,6 +96,7 @@ export interface CustomJsonConfig {
 	dateField?: string;
 	idField?: string;
 	maxItems: number;
+	fetchIntervalSeconds?: number;
 }
 
 export interface GitHubActivityConfig {
@@ -87,10 +110,12 @@ export interface GitHubActivityConfig {
 	maxItems: number;
 	sinceHours: number;
 	tokenEnvVar: string;
+	fetchIntervalSeconds?: number;
 }
 
 export interface Config {
 	feeds: FeedConfig[];
+	rssFetchIntervalSeconds: number;
 	limit: number;
 	mode: Mode;
 	target: Target;
@@ -104,6 +129,7 @@ export interface Config {
 	earthquakes: EarthquakeConfig;
 	weatherAlerts: WeatherAlertsConfig;
 	customJson: CustomJsonConfig;
+	customJsonSources?: CustomJsonConfig[];
 	githubActivity: GitHubActivityConfig;
 }
 
@@ -111,6 +137,8 @@ export interface CliOverrides extends Partial<Config> {
 	dryRun?: boolean;
 	interactive?: boolean;
 	uninstall?: boolean;
+	clearCache?: boolean;
+	triggerSchedulerNow?: boolean;
 	createNewConfig?: boolean;
 	installScheduler?: boolean;
 	uninstallScheduler?: boolean;
@@ -120,14 +148,6 @@ export interface CliOverrides extends Partial<Config> {
 	staticPackPath?: string;
 }
 
-export interface GitHubModelsResponse {
-	choices?: Array<{
-		message?: {
-			content?: string;
-		};
-	}>;
-}
-
 export interface ArticleItem {
 	type: 'article';
 	id: string;
@@ -139,6 +159,10 @@ export interface ArticleItem {
 	time?: string;
 	content?: string;
 	articleContent?: string;
+	/** Source-specific metadata for suffix display (e.g. HN score, commit delta) */
+	metadata?: Record<string, string | undefined>;
+	/** When true, the article's displayPhrase is final and should not be rewritten by AI models */
+	skipModelRewrite?: boolean;
 }
 
 export interface StockItem {

package/src/core/utils.ts

@@ -150,6 +150,11 @@ export function stripHtml(input?: string): string | undefined {
   return cleaned || undefined;
 }
 
+/** Convert hours to milliseconds. */
+export function hoursToMs(hours: number): number {
+  return hours * 3_600_000;
+}
+
 export function relativeTime(input?: string): string | undefined {
   if (!input) {
     return undefined;
@@ -261,13 +266,13 @@ export async function fetchJson<T>(url: string, headers?: Record<string, string>
 interface ZippopotamResponse {
   country?: string;
   'post code'?: string;
-  places?: Array<{
+  places?: {
     latitude?: string;
     longitude?: string;
     'place name'?: string;
     state?: string;
     'state abbreviation'?: string;
-  }>;
+  }[];
 }
 
 const zipLocationCache = new Map<string, Promise<ZipLocation>>();
@@ -310,3 +315,23 @@ export async function fetchUsZipLocation(zipCode: string): Promise<ZipLocation>
   zipLocationCache.set(normalizedZip, lookupPromise);
   return lookupPromise;
 }
+
+interface IpGeoResponse {
+  status?: string;
+  zip?: string;
+  city?: string;
+  regionName?: string;
+}
+
+/** Best-effort ZIP detection via IP geolocation. Returns undefined on failure. */
+export async function detectZipFromIp(): Promise<string | undefined> {
+  try {
+    const geo = await fetchJson<IpGeoResponse>('http://ip-api.com/json/?fields=status,zip,city,regionName');
+    if (geo.status === 'success' && geo.zip && isValidUsZipCode(geo.zip)) {
+      return geo.zip;
+    }
+  } catch {
+    // Best-effort — silently fail
+  }
+  return undefined;
+}

package/src/sources/customJson.ts

@@ -1,4 +1,4 @@
-import type { ArticleItem, Config, PhraseSource } from '../core/types.js';
+import type { ArticleItem, Config, CustomJsonConfig, PhraseSource } from '../core/types.js';
 import { fetchJson, logInfo, relativeTime, stripHtml, truncate } from '../core/utils.js';
 
 type PathSegment = number | string;
@@ -125,33 +125,29 @@ function resolveItems(payload: unknown, path?: string): unknown[] {
   throw new Error(`Custom JSON items path did not resolve to an array${path?.trim() ? `: ${path}` : ''}`);
 }
 
-export async function fetchCustomJsonArticles(config: Config): Promise<ArticleItem[]> {
-  if (!config.customJson.enabled) {
-    return [];
-  }
-
-  logInfo(config, `Fetching custom JSON items from ${config.customJson.url}`);
-  const payload = await fetchJson<unknown>(config.customJson.url);
-  const items = resolveItems(payload, config.customJson.itemsPath).slice(0, config.customJson.maxItems);
-  const defaultSource = config.customJson.sourceLabel?.trim() || buildDefaultSourceLabel(config.customJson.url);
+async function fetchSingleCustomJsonSource(sourceConfig: CustomJsonConfig, config: Config): Promise<ArticleItem[]> {
+  logInfo(config, `Fetching custom JSON items from ${sourceConfig.url}`);
+  const payload = await fetchJson<unknown>(sourceConfig.url);
+  const items = resolveItems(payload, sourceConfig.itemsPath).slice(0, sourceConfig.maxItems);
+  const defaultSource = sourceConfig.sourceLabel?.trim() || buildDefaultSourceLabel(sourceConfig.url);
 
   return items.flatMap((item, index) => {
     if (!item || typeof item !== 'object') {
       return [];
     }
 
-    const title = readStringValue(item, config.customJson.titleField);
+    const title = readStringValue(item, sourceConfig.titleField);
     if (!title) {
       return [];
     }
 
-    const content = stripHtml(readStringValue(item, config.customJson.contentField));
-    const datetime = toIsoDate(getPathValue(item, config.customJson.dateField));
-    const link = readStringValue(item, config.customJson.linkField);
-    const source = readStringValue(item, config.customJson.sourceField) ?? defaultSource;
-    const id = readStringValue(item, config.customJson.idField)
+    const content = stripHtml(readStringValue(item, sourceConfig.contentField));
+    const datetime = toIsoDate(getPathValue(item, sourceConfig.dateField));
+    const link = readStringValue(item, sourceConfig.linkField);
+    const source = readStringValue(item, sourceConfig.sourceField) ?? defaultSource;
+    const id = readStringValue(item, sourceConfig.idField)
       ?? link
-      ?? `${config.customJson.url}#${index}:${title}`;
+      ?? `${sourceConfig.url}#${index}:${title}`;
 
     return [{
       type: 'article' as const,
@@ -167,8 +163,22 @@ export async function fetchCustomJsonArticles(config: Config): Promise<ArticleIt
   });
 }
 
+export async function fetchCustomJsonArticles(config: Config): Promise<ArticleItem[]> {
+  const allSources: CustomJsonConfig[] = [
+    ...(config.customJson.enabled ? [config.customJson] : []),
+    ...(config.customJsonSources ?? []).filter(s => s.enabled),
+  ];
+
+  if (allSources.length === 0) {
+    return [];
+  }
+
+  const results = await Promise.all(allSources.map(source => fetchSingleCustomJsonSource(source, config)));
+  return results.flat();
+}
+
 export const customJsonSource: PhraseSource = {
   type: 'custom-json',
-  isEnabled: config => config.customJson.enabled,
+  isEnabled: config => config.customJson.enabled || (config.customJsonSources ?? []).some(s => s.enabled),
   fetch: fetchCustomJsonArticles,
 };

package/src/sources/earthquakes.ts

@@ -1,5 +1,5 @@
-import type { ArticleItem, PhraseSource } from '../core/types.js';
-import { fetchJson, fetchUsZipLocation, logInfo, relativeTime } from '../core/utils.js';
+import type { ArticleItem, Config, PhraseSource } from '../core/types.js';
+import { fetchJson, fetchUsZipLocation, hoursToMs, logInfo, relativeTime } from '../core/utils.js';
 
 interface UsgsFeature {
   id: string;
@@ -38,12 +38,12 @@ function buildEarthquakeContent(feature: UsgsFeature): string | undefined {
   return parts.length > 0 ? parts.join(' • ') : undefined;
 }
 
-export async function fetchEarthquakeArticles(config: import('../core/types.js').Config): Promise<ArticleItem[]> {
+export async function fetchEarthquakeArticles(config: Config): Promise<ArticleItem[]> {
   if (!config.earthquakes.enabled) {
     return [];
   }
 
-  const startTime = new Date(Date.now() - config.earthquakes.windowHours * 60 * 60 * 1000).toISOString();
+  const startTime = new Date(Date.now() - hoursToMs(config.earthquakes.windowHours)).toISOString();
   const params = new URLSearchParams({
     format: 'geojson',
     orderby: config.earthquakes.orderBy,