@cullumco/cadence 0.1.0 → 0.1.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cadence",
   "displayName": "Cadence",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Ambient context for Claude Code: embodied signals, cadence dials, and finish-line guardrails.",
   "author": {
     "name": "Cullum&Co",

package/dist/cli.js

@@ -32,7 +32,9 @@ async function cmdClear() {
     await writeFile(STATE_FILE, "", "utf-8");
     console.log("  state cleared");
 }
-async function cmdTest() {
+// Collects live signals and renders the exact block the hook would inject,
+// or null when there's nothing to say. Shared by `test` and the bare command.
+async function buildPreview() {
     const signals = [];
     const [music, report, ambient, git, overrides] = await Promise.all([
         getMusicSignal().catch(() => null),
@@ -49,14 +51,20 @@ async function cmdTest() {
         signals.push(ambient);
     if (git)
         signals.push(git);
-    if (signals.length === 0 && Object.keys(overrides).length === 0) {
-        console.log('  (no signals — play something, set: cadence state "...", or pin a dial: cadence set pace fast)');
-        return;
-    }
+    if (signals.length === 0 && Object.keys(overrides).length === 0)
+        return null;
     const state = { signals, capturedAt: Date.now() };
     const { cadence, pinned } = applyOverrides(deriveCadence(state), overrides);
     const reframe = buildReframe(cadence);
-    console.log("\n" + render({ ...state, cadence, pinned, reframe }) + "\n");
+    return render({ ...state, cadence, pinned, reframe });
+}
+async function cmdTest() {
+    const block = await buildPreview();
+    if (!block) {
+        console.log('  (no signals — play something, set: cadence state "...", or pin a dial: cadence set pace fast)');
+        return;
+    }
+    console.log("\n" + block + "\n");
 }
 const LEVELS = ["low", "medium", "high"];
 async function cmdSet(args) {
@@ -150,10 +158,114 @@ async function cmdLocation(args) {
     await writeFile(CONFIG_FILE, JSON.stringify(cfg, null, 2), "utf-8");
     console.log(`  location set${nameParts.length ? ` (${nameParts.join(" ")})` : ""} — weather is now on`);
 }
+// Has the user ever told Cadence anything? (Signals like time-of-day always
+// exist, so "fresh install" is detected by absence of user INPUT, not signals.)
+async function hasUserInput() {
+    const [state, config] = await Promise.all([
+        readFile(STATE_FILE, "utf-8").catch(() => ""),
+        readFile(CONFIG_FILE, "utf-8").catch(() => "{}"),
+    ]);
+    let cfg = {};
+    try {
+        cfg = JSON.parse(config);
+    }
+    catch {
+        // unreadable config = no input
+    }
+    return state.trim().length > 0 || Object.keys(cfg).length > 0;
+}
+const INPUTS_FOOTER = `  where you can input:
+    cadence state "..."              how you are right now (4h TTL)
+    cadence set <dial> <level>       pin a dial: ${DIALS.join(", ")}
+    cadence set-location <lat> <lon> opt into weather
+    cadence start                    interactive setup
+    cadence help                     everything else`;
+// Bare \`cadence\`: live status + where to input — not a help dump.
+async function cmdRoot() {
+    if (!(await hasUserInput())) {
+        console.log("\n  cadence — agents that read the room");
+        console.log("  It hasn't heard from you yet. Fastest start:\n");
+        console.log('    cadence start              guided setup (~30s)');
+        console.log('    cadence state "ship mode"  or just say how you are\n');
+        return;
+    }
+    const block = await buildPreview();
+    if (block) {
+        console.log("\n" + block + "\n");
+    }
+    else {
+        console.log("\n  (no signals right now)\n");
+    }
+    console.log(INPUTS_FOOTER + "\n");
+}
+// Guided first run: three prompts, every one skippable, nothing destructive.
+async function cmdStart() {
+    if (!process.stdin.isTTY) {
+        console.log('  cadence start is interactive — run it in a terminal, or use: cadence state "..."');
+        return;
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log("\n  cadence — agents that read the room");
+        console.log("  Three questions. Enter skips any of them; everything can be changed later.\n");
+        // 1 ── self-reported state: the highest-leverage input
+        const state = (await rl.question('  1/3  How are you right now? (e.g. "two beers, ship mode")\n       > ')).trim();
+        if (state) {
+            await mkdir(CADENCE_DIR, { recursive: true });
+            await writeFile(STATE_FILE, state, "utf-8");
+            console.log('       ✓ set — expires after 4h; update anytime: cadence state "..."\n');
+        }
+        else {
+            console.log('       skipped — later: cadence state "..."\n');
+        }
+        // 2 ── dial pins: overrides, so only offered, never pushed
+        console.log(`  2/3  Pin any dials? Pins override inference until unset.`);
+        console.log(`       dials: ${DIALS.join(", ")} — levels: low|medium|high`);
+        for (;;) {
+            const ans = (await rl.question('       pin (e.g. "pace high", enter to continue) > ')).trim();
+            if (!ans)
+                break;
+            const [dial, value] = ans.split(/\s+/);
+            if (!dial || !value || !DIALS.includes(dial)) {
+                console.log(`       format: <dial> <level>, dials: ${DIALS.join(", ")}`);
+                continue;
+            }
+            const d = dial;
+            const level = resolveDialLevel(d, value);
+            if (!level) {
+                console.log(`       "${value}" isn't valid for ${dial} — use low|medium|high`);
+                continue;
+            }
+            await cmdSet([dial, value]);
+        }
+        console.log();
+        // 3 ── weather: explicitly opt-in, mirrors cmdLocation's no-silent-geo rule
+        const loc = (await rl.question("  3/3  Weather? Give a location, or enter to leave it off.\n       lat lon [name] (e.g. 40.71 -74.01 NYC) > ")).trim();
+        if (loc) {
+            await cmdLocation(loc.split(/\s+/));
+        }
+        else {
+            console.log("       skipped — weather stays off until: cadence set-location <lat> <lon>");
+        }
+        console.log("\n  Done. Here's exactly what the hook injects right now:");
+        await cmdTest();
+    }
+    catch {
+        // Ctrl+D / Ctrl+C mid-wizard: every step saves as it goes, so an early
+        // exit just means "stop asking" — never an error, never a rollback.
+        console.log("\n  setup ended early — anything you answered is saved\n");
+    }
+    finally {
+        rl.close();
+    }
+}
 const HELP = `
   cadence — agents that read the room
 
   daily:
+    cadence                     live status + where to input
+    cadence start               guided setup (state, dials, weather — all skippable)
     cadence state "..."         set self-reported state (e.g. "two beers, ship mode")
     cadence state               print current self-reported state
     cadence clear               clear self-reported state
@@ -172,6 +284,8 @@ const HELP = `
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     switch (cmd) {
+        case "start":
+            return cmdStart();
         case "state":
             return cmdState(rest);
         case "clear":
@@ -187,6 +301,7 @@ async function main() {
         case "set-location":
             return cmdLocation(rest);
         case undefined:
+            return cmdRoot(); // live status + inputs, not the help dump
         case "help":
         case "--help":
         case "-h":

package/dist/debug.js

@@ -0,0 +1,17 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ * CADENCE_DEBUG=1 surfaces swallowed provider errors on stderr.
+ *
+ * Providers are fail-silent by contract: a broken signal must degrade to
+ * "no signal," never break the hook. But fail-silent code can mask a
+ * 100%-reproducible bug (see: the AppleScript that never compiled). This
+ * is the escape hatch — stderr only, never stdout, because stdout is the
+ * hook protocol channel Claude Code parses.
+ *
+ *   CADENCE_DEBUG=1 node bin/cadence test
+ * ───────────────────────────────────────────────────────────────────────── */
+const DEBUG = process.env["CADENCE_DEBUG"] === "1" || process.env["CADENCE_DEBUG"] === "true";
+export function debug(scope, msg) {
+    if (!DEBUG)
+        return;
+    process.stderr.write(`[cadence:${scope}] ${msg}\n`);
+}

package/dist/hook.js

@@ -6,6 +6,7 @@ import { getGitSignal } from "./providers/git.js";
 import { getActivitySignal } from "./providers/activity.js";
 import { deriveCadence, buildReframe, loadOverrides, applyOverrides } from "./cadence.js";
 import { render } from "./inject.js";
+import { debug } from "./debug.js";
 const TOTAL_BUDGET_MS = 1500;
 // Claude Code alpha adapter: collect portable Cadence signals, derive the core
 // cadence state, then deliver it through UserPromptSubmit.additionalContext.
@@ -53,7 +54,10 @@ async function main() {
     const [signals, overrides] = await Promise.all([
         Promise.race([
             collectSignals(projectDir, prompt),
-            new Promise((resolve) => setTimeout(() => resolve([]), TOTAL_BUDGET_MS)),
+            new Promise((resolve) => setTimeout(() => {
+                debug("hook", `signal collection exceeded ${TOTAL_BUDGET_MS}ms budget — injecting without signals`);
+                resolve([]);
+            }, TOTAL_BUDGET_MS)),
         ]),
         loadOverrides(),
     ]);

package/dist/providers/music.js

@@ -1,8 +1,9 @@
-import { exec } from "node:child_process";
+import { execFile } from "node:child_process";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { tagsToVibe } from "../vibe.js";
+import { debug } from "../debug.js";
 /* ─────────────────────────────────────────────────────────────────────────
  * Music = identity + vibe. No Spotify Web API, no auth, no Premium.
  *
@@ -17,36 +18,66 @@ const CACHE_FILE = join(homedir(), ".cadence", "vibe-cache.json");
 const MB_TIMEOUT_MS = 1000;
 const MAX_TAGS = 4;
 const UA = "cadence/0.1 (https://github.com/cullumco/cadence)";
-// `application "X" is running` does NOT launch X — safe to probe.
-const SCRIPT = `
-on tryApp(appName)
-  if application appName is running then
-    tell application appName
-      if player state is playing then
-        return appName & "|||" & (name of current track) & "|||" & (artist of current track)
-      end if
-    end tell
-  end if
-  return ""
-end tryApp
-set r to tryApp("Spotify")
-if r is "" then set r to tryApp("Music")
-return r
+// Spotify first (matches historical priority), then Apple Music.
+const PLAYERS = ["Spotify", "Music"];
+/* The app name MUST be a literal inside the script: AppleScript resolves
+ * terms like `player state` against the target app's scripting dictionary
+ * at COMPILE time, so `tell application someVariable` is a guaranteed
+ * syntax error (-2741). One script per player, built from a template.
+ * Exported for the compile-check regression test. */
+export function playerScript(app) {
+    return `
+if application "${app}" is running then
+  tell application "${app}"
+    if player state is playing then
+      return (name of current track) & "|||" & (artist of current track)
+    end if
+  end tell
+end if
+return ""
 `;
-function osascript(script) {
+}
+/* Compiling `tell application "Spotify"` makes macOS locate the app — on a
+ * machine where it isn't installed that can pop a "Where is Spotify?"
+ * picker, from a background hook. pgrep the process list first so we only
+ * ever compile scripts for players that are actually running. */
+function isRunning(app) {
     return new Promise((resolve) => {
-        const child = exec(`osascript -e ${JSON.stringify(script)}`, { timeout: 800 }, (err, stdout) => resolve(err ? "" : stdout.trim()));
-        child.on("error", () => resolve(""));
+        const child = execFile("pgrep", ["-qx", app], { timeout: 500 }, (err) => resolve(!err));
+        child.on("error", () => resolve(false));
+    });
+}
+/* execFile, not exec: the script must reach osascript byte-for-byte as one
+ * argv entry. Routing it through a shell means a quoting layer (where `\n`
+ * inside double quotes stays a literal backslash-n — instant -2740). */
+export function osascript(script) {
+    return new Promise((resolve) => {
+        const child = execFile("osascript", ["-e", script], { timeout: 800 }, (err, stdout, stderr) => {
+            if (err)
+                debug("music", `osascript failed: ${stderr.trim() || err.message}`);
+            resolve(err ? "" : stdout.trim());
+        });
+        child.on("error", (e) => {
+            debug("music", `osascript spawn failed: ${e.message}`);
+            resolve("");
+        });
     });
 }
 async function getNowPlaying() {
-    const out = await osascript(SCRIPT);
-    if (!out)
-        return null;
-    const [player, track, artist] = out.split("|||");
-    if (!track || !artist)
-        return null;
-    return { track, artist, player: player ?? "" };
+    for (const player of PLAYERS) {
+        if (!(await isRunning(player))) {
+            debug("music", `${player} not running`);
+            continue;
+        }
+        const out = await osascript(playerScript(player));
+        if (!out)
+            continue; // running but paused/stopped (or script error, logged above)
+        const [track, artist] = out.split("|||");
+        if (!track || !artist)
+            continue;
+        return { track, artist, player };
+    }
+    return null;
 }
 async function loadCache() {
     try {
@@ -92,7 +123,8 @@ async function fetchTags(artist) {
             .slice(0, MAX_TAGS);
         return cleaned.length ? cleaned : null;
     }
-    catch {
+    catch (e) {
+        debug("music", `musicbrainz lookup failed for "${artist}": ${e instanceof Error ? e.message : String(e)}`);
         return null;
     }
     finally {

package/dist/session-start.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { getMusicSignal } from "./providers/music.js";
+import { getSelfReportSignal } from "./providers/selfreport.js";
+import { loadOverrides } from "./cadence.js";
+import { debug } from "./debug.js";
+/* ─────────────────────────────────────────────────────────────────────────
+ * Claude Code SessionStart adapter: one short, human-facing line when a
+ * session opens — is Cadence live, what does it currently see, and where
+ * do you input state. Discoverability, not context: the per-prompt
+ * UserPromptSubmit hook owns what the MODEL sees; this line is for YOU
+ * (delivered via `systemMessage`, which Claude Code shows to the user).
+ *
+ * Fires on "startup" only (see hooks/hooks.json matcher) — not on resume
+ * or clear — so it reads as a greeting, not a nag.
+ * ───────────────────────────────────────────────────────────────────────── */
+const BUDGET_MS = 700;
+// The voice of the product's first impression. Return null to stay silent.
+// Default policy: always one line on startup — say what's seen when there
+// are signals, point at the inputs when there's nothing yet.
+export function composeHint(info) {
+    if (info.firstRun) {
+        return 'cadence: on, but it hasn\'t heard from you — try `cadence start` (or just `cadence state "deep work"`)';
+    }
+    const seen = [];
+    if (info.selfReport)
+        seen.push(`state "${info.selfReport}"`);
+    if (info.nowPlaying)
+        seen.push(`${info.nowPlaying.player}: ${info.nowPlaying.artist}`);
+    if (info.pinned.length)
+        seen.push(`pinned ${info.pinned.join(", ")}`);
+    if (seen.length === 0) {
+        return 'cadence: live, no signals right now — `cadence state "..."` to give it one';
+    }
+    return `cadence: live — ${seen.join(" · ")}  (inputs: cadence state | dials)`;
+}
+async function collectInfo() {
+    // Race music against the budget — MusicBrainz on a brand-new artist can
+    // be slow, and a session greeting must never delay the session.
+    const [report, overrides, music] = await Promise.all([
+        getSelfReportSignal().catch(() => null),
+        loadOverrides(),
+        Promise.race([
+            getMusicSignal().catch(() => null),
+            new Promise((resolve) => setTimeout(() => resolve(null), BUDGET_MS)),
+        ]),
+    ]);
+    const pinned = Object.keys(overrides);
+    return {
+        selfReport: report?.text ?? null,
+        pinned,
+        nowPlaying: music?.artist ? { artist: music.artist, player: music.player ?? "music" } : null,
+        firstRun: !report && pinned.length === 0,
+    };
+}
+async function main() {
+    const hint = composeHint(await collectInfo());
+    if (!hint)
+        process.exit(0); // same contract as the prompt hook: silent when empty
+    process.stdout.write(JSON.stringify({ systemMessage: hint }));
+}
+main().catch((err) => {
+    debug("session-start", err instanceof Error ? err.message : String(err));
+    process.exit(0); // greeting must never break a session
+});

package/hooks/hooks.json

@@ -1,5 +1,16 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/session-start.js\""
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "matcher": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cullumco/cadence",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Agents that read the room. Ambient context, cadence dials, and finish-line guardrails for Claude Code.",
   "type": "module",
   "bin": {