@cullumco/cadence 0.1.4 → 0.1.5

package/dist/posttool.js

@@ -4,6 +4,7 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { getGitSignal } from "./providers/git.js";
+import { isPaused } from "./config.js";
 /* ─────────────────────────────────────────────────────────────────────────
  * PostToolUse adapter — V2 "after-the-fact" refinement, conservative cut.
  *
@@ -13,14 +14,22 @@ import { getGitSignal } from "./providers/git.js";
  * event: the repo entering or leaving a merge/rebase conflict — the
  * strongest debug tell we have, far stronger than music ever was.
  *
+ * Two material events now, same discipline:
+ *   1. the repo entering/leaving a merge/rebase conflict (re-observed via git)
+ *   2. a streak of destructive git ops — reset --hard / force-push — read off
+ *      the command string (no tool_response parsing), i.e. thrash.
+ *
  * Discipline (the BACKLOG's hard constraint):
  *   - fires only after Bash tool calls whose command mentions git
- *   - injects at most once per conflict-state TRANSITION, never per tool
+ *   - injects at most once per TRANSITION (conflict edge, or thrash threshold),
+ *     never per tool
  *   - silent in every other case, silent on every error
  * ───────────────────────────────────────────────────────────────────────── */
 const TOTAL_BUDGET_MS = 1500;
 const STATE_FILE = join(homedir(), ".cadence", "workstate.json");
 const MAX_SESSIONS = 20;
+const THRASH_WINDOW_MS = 10 * 60_000; // destructive ops within 10 min count as a streak
+const THRASH_MIN = 2; // 2nd destructive op in the window = thrash
 // Gate 1: is this tool call even capable of changing git conflict state?
 // Only Bash commands that mention git — Edit/Read/etc. can't start a merge,
 // and checking the repo after every tool call would betray the silence rule.
@@ -50,6 +59,34 @@ export function refineContext(prev, conflicted) {
     }
     return null; // first observation of a clean repo: record silently
 }
+// Is this command a destructive/undo git op? Just `reset --hard` and a true
+// force-push — NOT --force-with-lease (the safe one), checkout, or restore
+// (too ordinary to read as thrash). Pure + exported for tests.
+export function isThrashCommand(cmd) {
+    return (/git\s+reset\s+--hard\b/.test(cmd) ||
+        (/git\s+push\b/.test(cmd) && /(--force\b|\s-f\b)/.test(cmd) && !/--force-with-lease\b/.test(cmd)));
+}
+/* Edge-trigger thrash off the rolling window of destructive-op timestamps.
+ * Speaks once when the streak first crosses THRASH_MIN inside the window, then
+ * stays quiet until the window empties (so it can fire again on a later run).
+ * Pure + exported; `times` already includes the current op if it was one. */
+export function refineThrash(times, now, announced) {
+    const recent = times.filter((t) => now - t <= THRASH_WINDOW_MS);
+    if (recent.length === 0)
+        return { message: null, times: recent, announced: false };
+    if (recent.length >= THRASH_MIN && !announced) {
+        return {
+            message: "<user_state_update>observed work: a streak of destructive git ops " +
+                "(reset --hard / force-push). Read this as thrash — pause, verify the " +
+                "repo state and what's being undone before the next destructive step. " +
+                "If the user's words clearly mean otherwise, follow their words." +
+                "</user_state_update>",
+            times: recent,
+            announced: true,
+        };
+    }
+    return { message: null, times: recent, announced };
+}
 async function loadState() {
     try {
         const raw = JSON.parse(await readFile(STATE_FILE, "utf-8"));
@@ -86,6 +123,8 @@ async function readStdin() {
     }
 }
 async function main() {
+    if (await isPaused())
+        return; // user asked for silence — observe nothing
     const input = await readStdin();
     if (!shouldCheck(input))
         return;
@@ -97,10 +136,24 @@ async function main() {
         return; // not a repo / git unavailable → nothing to observe
     const key = input.session_id ?? "default";
     const state = await loadState();
-    const prev = state[key]?.conflicted;
-    const message = refineContext(prev, git.conflicted);
-    state[key] = { conflicted: git.conflicted, at: Date.now() };
+    const prev = state[key];
+    const now = Date.now();
+    // 1. conflict edge (re-observed via git)
+    const conflictMsg = refineContext(prev?.conflicted, git.conflicted);
+    // 2. thrash threshold (read off the command string)
+    const cmd = typeof input.tool_input?.command === "string" ? input.tool_input.command : "";
+    const times = prev?.thrashTimes ?? [];
+    const nextTimes = isThrashCommand(cmd) ? [...times, now] : times;
+    const thrash = refineThrash(nextTimes, now, prev?.thrashAnnounced ?? false);
+    state[key] = {
+        conflicted: git.conflicted,
+        at: now,
+        thrashTimes: thrash.times,
+        thrashAnnounced: thrash.announced,
+    };
     await saveState(state);
+    // A conflict edge is the stronger tell; fall back to thrash. At most one.
+    const message = conflictMsg ?? thrash.message;
     if (message) {
         process.stdout.write(JSON.stringify({
             hookSpecificOutput: {

package/dist/providers/activity.js

@@ -3,7 +3,36 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 const CADENCE_DIR = join(homedir(), ".cadence");
 const ACTIVITY_FILE = join(CADENCE_DIR, "activity.json");
-export function activityFrom(prompt, lastPromptAt, now) {
+// Rolling window for typing tempo: how many recent prompts we keep, and how
+// far back they still count toward a "rapid-fire" read.
+const WINDOW_MAX = 10;
+const WINDOW_AGE_MS = 10 * 60_000; // 10 min — older prompts are a different sitting
+const BURST_WINDOW_MS = 5 * 60_000; // ≥3 prompts inside 5 min = a burst
+const BURST_MIN_PROMPTS = 3;
+const SHORT_PROMPT = 80; // median chars under this, in a burst → "rapid"
+const LONG_PROMPT = 280; // one prompt over this → "considered"
+/* Tempo from the prompt-rhythm window. Pure + exported for fixture tests.
+ * "considered" wins outright (a long prompt is deliberate even mid-burst);
+ * otherwise a tight cluster of short prompts reads as "rapid". */
+export function computeTempo(window) {
+    if (window.length === 0)
+        return undefined;
+    const current = window[window.length - 1];
+    if (current.len > LONG_PROMPT)
+        return "considered";
+    const newest = current.at;
+    const inBurst = window.filter((m) => newest - m.at <= BURST_WINDOW_MS);
+    if (inBurst.length >= BURST_MIN_PROMPTS) {
+        const lens = inBurst.map((m) => m.len).sort((a, b) => a - b);
+        const median = lens[Math.floor(lens.length / 2)] ?? 0;
+        if (median < SHORT_PROMPT)
+            return "rapid";
+    }
+    if (window.length >= 2)
+        return "measured";
+    return undefined; // not enough rhythm yet to call it
+}
+export function activityFrom(prompt, lastPromptAt, now, recent = [], tempoEnabled = false) {
     if (prompt == null)
         return null;
     const signal = {
@@ -13,9 +42,15 @@ export function activityFrom(prompt, lastPromptAt, now) {
     if (lastPromptAt != null && Number.isFinite(lastPromptAt)) {
         signal.minSinceLastPrompt = Math.max(0, Math.round((now - lastPromptAt) / 60000));
     }
+    if (tempoEnabled) {
+        const window = [...recent, { at: now, len: prompt.length }].filter((m) => now - m.at <= WINDOW_AGE_MS);
+        const tempo = computeTempo(window);
+        if (tempo)
+            signal.tempo = tempo;
+    }
     return signal;
 }
-export async function getActivitySignal(prompt, now = Date.now()) {
+export async function getActivitySignal(prompt, now = Date.now(), opts = {}) {
     let state = {};
     try {
         state = JSON.parse(await readFile(ACTIVITY_FILE, "utf-8"));
@@ -23,10 +58,16 @@ export async function getActivitySignal(prompt, now = Date.now()) {
     catch {
         // no activity file yet
     }
-    const signal = activityFrom(prompt, state.lastPromptAt, now);
+    const recent = Array.isArray(state.recent) ? state.recent : [];
+    const signal = activityFrom(prompt, state.lastPromptAt, now, recent, opts.tempoEnabled);
     try {
         await mkdir(CADENCE_DIR, { recursive: true });
-        await writeFile(ACTIVITY_FILE, JSON.stringify({ lastPromptAt: now }), "utf-8");
+        const nextRecent = prompt == null
+            ? recent
+            : [...recent, { at: now, len: prompt.length }]
+                .filter((m) => now - m.at <= WINDOW_AGE_MS)
+                .slice(-WINDOW_MAX);
+        await writeFile(ACTIVITY_FILE, JSON.stringify({ lastPromptAt: now, recent: nextRecent }), "utf-8");
     }
     catch {
         // activity is best-effort; never let it break the hook

package/dist/providers/{ambient.js → environment.js}

@@ -138,18 +138,37 @@ export async function getFocus(now = new Date()) {
     }
     return manual;
 }
+// Frontmost app — opt-in, macOS, flavor only. Read at UserPromptSubmit, so the
+// terminal/IDE you typed into is usually frontmost; we filter known shells and
+// editors out, so this speaks only when a genuinely different app (a browser,
+// Slack, a PDF) is in front. Flavor for now; a dial nudge stays a candidate.
+const TERMINAL_APPS = /^(Terminal|iTerm2?|Alacritty|kitty|WezTerm|Warp|Hyper|Code|Code - Insiders|Cursor|Windsurf|Electron|Ghostty|Tabby|rio)$/i;
+export async function getFocusedApp(now) {
+    if (!now || process.platform !== "darwin")
+        return undefined;
+    const app = await sh(`osascript -e 'tell application "System Events" to name of first application process whose frontmost is true'`, 700);
+    if (!app)
+        return undefined;
+    const name = app.split("\n")[0]?.trim();
+    if (!name || TERMINAL_APPS.test(name))
+        return undefined; // you're in your terminal — no news
+    return name;
+}
 // ── mac context: best-effort shell-outs, all flavor (no dial nudges) ─────────
-async function getMacContext() {
+async function getMacContext(focusedAppEnabled) {
     if (process.platform !== "darwin")
         return {};
-    const [dark, ssid, displays, focus] = await Promise.all([
+    const [dark, ssid, displays, focus, focusedApp] = await Promise.all([
         sh("defaults read -g AppleInterfaceStyle"), // "Dark", or error (=light)
         sh("ipconfig getsummary en0 | awk -F ' SSID : ' '/ SSID : / {print $2}'", 700),
         // fast display count via AppleScript (~100ms) — NOT system_profiler (1-3s)
         sh(`osascript -e 'tell application "System Events" to count of desktops'`, 700),
         getFocus(),
+        getFocusedApp(focusedAppEnabled),
     ]);
     const ctx = {};
+    if (focusedApp)
+        ctx.focusedApp = focusedApp;
     // `defaults read` exits non-zero when the key is unset — which is exactly
     // what light mode looks like. So error/null ⇒ light, not unknown.
     ctx.darkMode = dark != null && /dark/i.test(dark);
@@ -209,17 +228,17 @@ async function getWeather() {
         clearTimeout(timer);
     }
 }
-export async function getAmbientSignal(now) {
+export async function getEnvironmentSignal(now, opts = {}) {
     const hour = now.getHours();
     const vitals = getVitals(); // sync, free
     // all probes run in parallel; each resolves to a safe default on failure.
     const [weather, battery, mac] = await Promise.all([
         getWeather(),
         getBattery(),
-        getMacContext(),
+        getMacContext(opts.focusedAppEnabled ?? false),
     ]);
     return {
-        source: "ambient",
+        source: "environment",
         partOfDay: partOfDay(hour),
         dayOfWeek: DAYS[now.getDay()] ?? "",
         isWeekend: now.getDay() === 0 || now.getDay() === 6,
@@ -233,5 +252,6 @@ export async function getAmbientSignal(now) {
         displays: mac.displays,
         network: mac.network,
         darkMode: mac.darkMode,
+        focusedApp: mac.focusedApp,
     };
 }

package/dist/providers/esoteric.js

@@ -0,0 +1,77 @@
+import { providerEnabled, providerSetting } from "../config.js";
+import { debug } from "../debug.js";
+/* ─────────────────────────────────────────────────────────────────────────
+ * Esoteric flavor — opt-in, render-only. For people who want a little ambient
+ * woo in the room. Never moves a dial (the BACKLOG lean): it colors the block,
+ * it doesn't steer real work.
+ *
+ *   moon      → computed OFFLINE from the date, no API, no dep.
+ *   horoscope → user sets their sign; daily text via a keyless API, opt-in and
+ *               fail-silent, exactly like the weather probe. Absent on any
+ *               hiccup, never throws.
+ * ───────────────────────────────────────────────────────────────────────── */
+const HOROSCOPE_TIMEOUT_MS = 900;
+const SYNODIC_MONTH = 29.53058867; // days, new moon → new moon
+const KNOWN_NEW_MOON = Date.UTC(2000, 0, 6, 18, 14) / 1000; // 2000-01-06 reference
+const PHASES = [
+    "new moon",
+    "waxing crescent",
+    "first quarter",
+    "waxing gibbous",
+    "full moon",
+    "waning gibbous",
+    "last quarter",
+    "waning crescent",
+];
+const ZODIAC = new Set([
+    "aries", "taurus", "gemini", "cancer", "leo", "virgo",
+    "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces",
+]);
+/** Current moon phase as one of the 8 names. Pure + exported for tests. */
+export function moonPhase(now) {
+    const days = (now.getTime() / 1000 - KNOWN_NEW_MOON) / 86_400;
+    const frac = (((days % SYNODIC_MONTH) + SYNODIC_MONTH) % SYNODIC_MONTH) / SYNODIC_MONTH;
+    const idx = Math.floor(frac * 8 + 0.5) % 8;
+    return PHASES[idx];
+}
+async function fetchHoroscope(sign) {
+    const s = sign.toLowerCase().trim();
+    if (!ZODIAC.has(s))
+        return undefined; // garbage in → silent, never a guess
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), HOROSCOPE_TIMEOUT_MS);
+    try {
+        const url = `https://horoscope-app-api.vercel.app/api/v1/get-horoscope/daily?sign=${s}&day=TODAY`;
+        const res = await fetch(url, { signal: ctrl.signal });
+        if (!res.ok)
+            return undefined;
+        const data = (await res.json());
+        const text = data.data?.horoscope_data;
+        if (!text)
+            return undefined;
+        return text.length > 160 ? text.slice(0, 159).trimEnd() + "…" : text;
+    }
+    catch (e) {
+        debug("esoteric", `horoscope lookup failed: ${e instanceof Error ? e.message : String(e)}`);
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function getEsotericSignal(providers, now = new Date()) {
+    const moonOn = providerEnabled(providers, "moon");
+    const sign = providerSetting(providers, "horoscope");
+    if (!moonOn && typeof sign !== "string")
+        return null; // nothing opted in
+    const phase = moonOn ? moonPhase(now) : undefined;
+    const horoscope = typeof sign === "string" ? await fetchHoroscope(sign) : undefined;
+    if (!phase && !horoscope)
+        return null;
+    return {
+        source: "esoteric",
+        moonPhase: phase,
+        horoscope,
+        sign: typeof sign === "string" ? sign.toLowerCase().trim() : undefined,
+    };
+}

package/dist/providers/git.js

@@ -5,9 +5,10 @@ import { exec } from "node:child_process";
  * Cross-platform (git is git everywhere). Reads the repo at `cwd` — which,
  * when run from the hook, is the project Claude Code is working in.
  *
- * Rendered as flavor for now: commits this hour, dirty files, and whether
- * you're mid-merge/rebase (the real debug tell). No dial nudges yet — we
- * watch the output first, then decide what should steer.
+ * Collects commits this hour, dirty files, and whether you're mid-merge/rebase
+ * (the real debug tell). LIVE in dial mapping since 2026-06-05: 3+ commits/hr
+ * → fast pace, mid-conflict → verify-first proactivity (see deriveCadence,
+ * applied below self-report so the user's explicit word still wins).
  * ───────────────────────────────────────────────────────────────────────── */
 const GIT_TIMEOUT_MS = 700;
 function git(args, cwd) {

package/dist/providers/intent.js

@@ -0,0 +1,37 @@
+// Ordered weakest-cue → strongest is not needed; each kind is independent and
+// the first match wins. Order them by how decisive the framing is.
+const PATTERNS = [
+    {
+        kind: "debug",
+        re: /\b(debug(ging)?|stack ?trace|tracebacks?|why (is|are|does|do|won'?t|isn'?t|can'?t)|stuck on|can'?t figure|keeps? (failing|crashing|breaking)|throwing|segfault|regression)\b/i,
+    },
+    {
+        kind: "think",
+        re: /\b(thinking through|let'?s think|think about|weigh(ing)? (the|our|up)|trade-?offs?|brainstorm|explore (the )?options|pros and cons|not sure (which|whether|if)|help me decide|which approach|architect(ure|ing)?\b.*\b(should|best)|design (the|a) )\b/i,
+    },
+    {
+        kind: "ship",
+        re: /\b(ship it|let'?s ship|ready to ship|send it|just send|locked in|lock(ing)? in|crank(ing)? (out|through)|grind(ing)? (out|through)|knock (this|these|it) out|let'?s go\b|let'?s finish|wrap (this|it) up|push it through)\b/i,
+    },
+    {
+        kind: "focus",
+        re: /\b(deep work|heads ?down|focus mode|in the zone|no distractions|need to concentrate)\b/i,
+    },
+];
+/** Detect a single dominant intent kind from a prompt, or null when the
+ * wording carries no clear cadence cue. Pure + exported for fixture tests. */
+export function detectPromptIntent(prompt) {
+    for (const { kind, re } of PATTERNS) {
+        if (re.test(prompt))
+            return kind;
+    }
+    return null;
+}
+export async function getIntentSignal(prompt) {
+    if (!prompt)
+        return null;
+    const kind = detectPromptIntent(prompt);
+    if (!kind)
+        return null; // no cue → no signal (silent, never a guess)
+    return { source: "intent", kind };
+}

package/dist/providers/moon.js

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/* ─────────────────────────────────────────────────────────────────────────
+ * Moon phase — the first esoteric, opt-in provider (see BACKLOG).
+ *
+ * Pure offline math: phase from days since a known new moon, no API, no
+ * platform dependency. OFF by default — it only speaks if the user opted in
+ * via ~/.cadence/config.json:  { "providers": { "moon": true } }
+ *
+ * Render-only by design: esoteric signals color the vibe, they never move
+ * dials unless the user explicitly maps them (BACKLOG: "vibe-only unless
+ * the user maps them").
+ * ───────────────────────────────────────────────────────────────────────── */
+const CONFIG_FILE = join(homedir(), ".cadence", "config.json");
+// Mean synodic month. Anchor: the new moon of 2000-01-06 18:14 UTC.
+// Mean-cycle math drifts up to ~14h from true phase — irrelevant at the
+// "waxing gibbous" level of precision we render.
+const SYNODIC_DAYS = 29.53058867;
+const EPOCH_NEW_MOON_MS = Date.UTC(2000, 0, 6, 18, 14);
+const PHASES = [
+    "new",
+    "waxing crescent",
+    "first quarter",
+    "waxing gibbous",
+    "full",
+    "waning gibbous",
+    "last quarter",
+    "waning crescent",
+];
+// Pure and clock-injected so it's fixture-testable.
+export function moonPhase(now) {
+    const days = (now.getTime() - EPOCH_NEW_MOON_MS) / 86_400_000;
+    const fraction = (((days % SYNODIC_DAYS) + SYNODIC_DAYS) % SYNODIC_DAYS) / SYNODIC_DAYS;
+    // Disc illumination: 0 at new (fraction 0), 100 at full (fraction 0.5).
+    const illumination = Math.round((1 - Math.cos(2 * Math.PI * fraction)) * 50);
+    // Eight equal buckets, centered on the cardinal points (new = ±1/16 around 0).
+    const idx = Math.floor(((fraction + 1 / 16) % 1) * 8);
+    return { phase: PHASES[idx] ?? "new", illumination };
+}
+export async function getMoonSignal(now = new Date()) {
+    try {
+        const cfg = JSON.parse(await readFile(CONFIG_FILE, "utf-8"));
+        if (cfg.providers?.moon !== true)
+            return null; // opt-in only, off by default
+        return { source: "moon", ...moonPhase(now) };
+    }
+    catch {
+        return null; // no config / bad JSON → simply off, never throw
+    }
+}

package/dist/providers/music.js

@@ -3,6 +3,8 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { tagsToVibe } from "../vibe.js";
+import { getSpotifyNowPlaying } from "./spotify.js";
+import { loadProviders } from "../config.js";
 import { debug } from "../debug.js";
 /* ─────────────────────────────────────────────────────────────────────────
  * Music = identity + vibe. No Spotify Web API, no auth, no Premium.
@@ -63,7 +65,11 @@ export function osascript(script) {
         });
     });
 }
-async function getNowPlaying() {
+// macOS now-playing via the desktop apps' scripting interface. Darwin-only —
+// osascript doesn't exist elsewhere, so non-Mac falls through to Spotify.
+async function getLocalNowPlaying() {
+    if (process.platform !== "darwin")
+        return null;
     for (const player of PLAYERS) {
         if (!(await isRunning(player))) {
             debug("music", `${player} not running`);
@@ -79,6 +85,11 @@ async function getNowPlaying() {
     }
     return null;
 }
+// Local desktop apps first (zero-setup on Mac); the opt-in Spotify token path
+// second, so a Linux/Windows user who supplied creds still gets music.
+async function getNowPlaying(providers) {
+    return (await getLocalNowPlaying()) ?? (await getSpotifyNowPlaying(providers));
+}
 async function loadCache() {
     try {
         return JSON.parse(await readFile(CACHE_FILE, "utf-8"));
@@ -166,8 +177,8 @@ async function getTags(artist) {
     await saveCache(cache);
     return tags ?? [];
 }
-export async function getMusicSignal() {
-    const np = await getNowPlaying();
+export async function getMusicSignal(providers) {
+    const np = await getNowPlaying(providers ?? (await loadProviders()));
     if (!np)
         return null;
     const tags = await getTags(np.artist);
@@ -179,5 +190,6 @@ export async function getMusicSignal() {
         player: np.player || undefined,
         vibe: vibe && vibe.moods.length ? vibe.moods.join(", ") : undefined,
         energy: vibe?.energy,
+        acoustic: vibe?.acoustic,
     };
 }

package/dist/providers/selfreport.js

@@ -2,7 +2,12 @@ import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const STATE_FILE = join(homedir(), ".cadence", "state.txt");
-export const STALE_AFTER_MS = 4 * 60 * 60 * 1000;
+// 2h, shortened from 4h: a self-report should track the room you're in now, not
+// the one you were in this morning. Cadence nudges you to refresh as it nears
+// expiry (see session-start composeHint).
+export const STALE_AFTER_MS = 2 * 60 * 60 * 1000;
+// When less than this is left, the session greeting invites a refresh.
+export const REFRESH_SOON_MS = 30 * 60 * 1000;
 export async function getSelfReportSignal() {
     try {
         const [text, info] = await Promise.all([readFile(STATE_FILE, "utf-8"), stat(STATE_FILE)]);

package/dist/providers/spotify.js

@@ -0,0 +1,142 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { providerEnabled } from "../config.js";
+import { debug } from "../debug.js";
+/* ─────────────────────────────────────────────────────────────────────────
+ * Spotify now-playing — the CROSS-PLATFORM music source (opt-in).
+ *
+ * macOS already reads Spotify.app / Music.app via AppleScript; this is for the
+ * Linux/Windows user (or anyone who'd rather not script the desktop app). It
+ * is NOT the deprecated audio-features API — only `currently-playing`, which
+ * is still live. Vibe still comes from MusicBrainz downstream, so this returns
+ * identity only (track + artist), exactly like the AppleScript path.
+ *
+ * Opt-in and BYO-credentials — no shared client, no callback server in a
+ * background hook. The user registers their own Spotify app and supplies a
+ * refresh token + client id (see `cadence spotify`); we refresh the short-lived
+ * access token ourselves and cache it so a normal prompt makes ONE request.
+ * Fail-silent throughout: any hiccup degrades to "no music," never throws.
+ * ───────────────────────────────────────────────────────────────────────── */
+const TOKEN_CACHE = join(homedir(), ".cadence", "spotify-token.json");
+const REFRESH_TIMEOUT_MS = 800;
+const NOWPLAYING_TIMEOUT_MS = 800;
+const TOKEN_SKEW_MS = 60_000; // refresh a minute early so a live token can't expire mid-flight
+/** Pull and validate the Spotify creds out of the provider registry, or null
+ * when the user hasn't opted in / the shape is incomplete. Pure + exported. */
+export function readCreds(providers) {
+    if (!providerEnabled(providers, "spotify"))
+        return null;
+    const v = providers["spotify"];
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    const refreshToken = o["refreshToken"];
+    const clientId = o["clientId"];
+    if (typeof refreshToken !== "string" || typeof clientId !== "string")
+        return null;
+    if (!refreshToken || !clientId)
+        return null;
+    const clientSecret = typeof o["clientSecret"] === "string" ? o["clientSecret"] : undefined;
+    return { refreshToken, clientId, clientSecret };
+}
+async function loadToken() {
+    try {
+        const t = JSON.parse(await readFile(TOKEN_CACHE, "utf-8"));
+        return typeof t?.accessToken === "string" && typeof t?.expiresAt === "number" ? t : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function saveToken(t) {
+    try {
+        await mkdir(join(homedir(), ".cadence"), { recursive: true });
+        await writeFile(TOKEN_CACHE, JSON.stringify(t), "utf-8");
+    }
+    catch {
+        // best-effort; a failed cache just means we refresh again next prompt
+    }
+}
+async function refreshAccessToken(creds) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), REFRESH_TIMEOUT_MS);
+    try {
+        const body = new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: creds.refreshToken,
+            client_id: creds.clientId, // in-body client_id covers PKCE/public apps
+        });
+        const headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+        };
+        if (creds.clientSecret) {
+            const basic = Buffer.from(`${creds.clientId}:${creds.clientSecret}`).toString("base64");
+            headers["Authorization"] = `Basic ${basic}`;
+        }
+        const res = await fetch("https://accounts.spotify.com/api/token", {
+            method: "POST",
+            headers,
+            body,
+            signal: ctrl.signal,
+        });
+        if (!res.ok) {
+            debug("spotify", `token refresh failed: ${res.status}`);
+            return null;
+        }
+        const data = (await res.json());
+        if (!data.access_token)
+            return null;
+        await saveToken({
+            accessToken: data.access_token,
+            expiresAt: Date.now() + (data.expires_in ?? 3600) * 1000,
+        });
+        return data.access_token;
+    }
+    catch (e) {
+        debug("spotify", `token refresh error: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function getAccessToken(creds) {
+    const cached = await loadToken();
+    if (cached && cached.expiresAt - TOKEN_SKEW_MS > Date.now())
+        return cached.accessToken;
+    return refreshAccessToken(creds);
+}
+export async function getSpotifyNowPlaying(providers) {
+    const creds = readCreds(providers);
+    if (!creds)
+        return null;
+    const token = await getAccessToken(creds);
+    if (!token)
+        return null;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), NOWPLAYING_TIMEOUT_MS);
+    try {
+        const res = await fetch("https://api.spotify.com/v1/me/player/currently-playing", {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: ctrl.signal,
+        });
+        if (res.status === 204 || !res.ok)
+            return null; // 204 = nothing playing
+        const data = (await res.json());
+        if (data.is_playing === false)
+            return null;
+        const track = data.item?.name;
+        const artist = data.item?.artists?.map((a) => a.name).filter(Boolean).join(", ");
+        if (!track || !artist)
+            return null;
+        return { track, artist, player: "Spotify" };
+    }
+    catch (e) {
+        debug("spotify", `now-playing error: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}