contextspin 0.6.2 → 0.6.4

package/README.md

@@ -1,6 +1,10 @@
 # ContextSpin
 
-Replace the Claude Code spinner / status bar text with live org context — meetings, Slack mentions, CI failures, incidents, review queues — pulled from tools you already run.
+Live context in your Claude Code **status bar** — weather, the top Hacker News story, PRs awaiting your review, CI failures, incidents, meetings — pulled from tools you already run. Install in one line; the bar is never empty.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mannutech/contextspin/main/install.sh | bash
+```
 
 ## Key principle: ContextSpin does NOT fetch data
 
@@ -33,15 +37,14 @@ ContextSpin polls those sources on a schedule, formats whatever they return into
                               │  read cache
                               ▼
   ┌─────────────────────────────────────────────────────────┐
-  │  INJECTOR                                                 │
+  │  INJECTOR  (statusline — non-destructive, composed)       │
   │   statusline  ──►  ~/.contextspin/statusline.sh           │
-  │                    patches ~/.claude/settings.json        │
-  │   patcher     ──►  rewrites spinner words in the binary   │
-  │                    (EXPERIMENTAL)                          │
+  │                    composed into ~/.claude/settings.json   │
+  │   patcher     ──►  rewrites spinner words (EXPERIMENTAL)   │
   └───────────────────────────┬─────────────────────────────┘
                               │
                               ▼
-        Claude Code spinner / status bar shows one snippet
+            Claude Code status bar shows one snippet
 ```
 
 The daemon and the injector are decoupled by the cache file: the daemon writes snippets, the injector reads them. Each runs on its own clock.
@@ -170,7 +173,7 @@ ContextSpin reads one JSON file: `~/.contextspin.json` (override with the `CONTE
 
 | Field | Type | Format / values | Default | Meaning |
 |-------|------|-----------------|---------|---------|
-| `sources` | array | non-empty | — | List of sources to poll. Required. |
+| `sources` | array | — | `[]` | Sources to poll. May be empty (the bar then shows the built-in defaults). |
 | `sources[].type` | string | `mcp` \| `cli` \| `http` | — | Source kind. Required. |
 | `sources[].tool` | string | tool name or `mcp__server__tool` | — | Required for `mcp`. |
 | `sources[].command` | string | shell command | — | Required for `cli`. |
@@ -183,6 +186,7 @@ ContextSpin reads one JSON file: `~/.contextspin.json` (override with the `CONTE
 | `injection.mode` | string | `statusline` \| `patcher` \| `both` | `statusline` | How snippets reach the UI. |
 | `injection.refresh` | number | seconds | `30` | Daemon poll interval and status-line refresh interval (seconds). |
 | `injection.maxVisible` | number | count | `5` | Global cap on snippets held in the cache. |
+| `injection.style` | boolean | — | `true` | Render the line in a styled box (cyan bars + italic). Set `false` for plain text. |
 | `snippets.deduplication` | boolean | — | `true` | Drop snippets with duplicate text when merging. |
 | `snippets.cooldownAfterShown` | number | count | `3` | A snippet stops being eligible once shown this many times. |
 | `snippets.priorityOrder` | string[] | source labels | `[]` | Earlier labels sort first (case-insensitive); unlisted sort last. |
@@ -207,9 +211,9 @@ This is the supported path. It uses Claude Code's official [status line](https:/
 
 1. Write `~/.contextspin/statusline-render.js` — a self-contained script that drains stdin (so Claude Code's piped JSON can't cause `EPIPE`), reads the cache, picks the eligible snippet with the lowest `shownCount` (then most recent), increments its count, writes the cache back, and prints that one line. Any error exits cleanly with no output, so it can never break your status bar.
 2. Write `~/.contextspin/statusline.sh` — a `0755` bash wrapper that `exec`s the render script.
-3. Patch `~/.claude/settings.json` to set `statusLine` to `{ type: "command", command: "<statusline.sh>", padding: 0, refreshInterval: <refresh> }` (refresh is in **seconds**). If you already had a different status line, it is backed up to `~/.claude/settings.json.contextspin.bak` first.
+3. Point `statusLine` at that wrapper (refresh in **seconds**), **non-destructively**: any status line you already had is preserved and *composed* — the render script runs your prior command and prints its output **above** the ContextSpin line. Scope-aware: in a project (when `CLAUDE_PROJECT_DIR` is set) it writes the gitignored `<project>/.claude/settings.local.json`, which outranks a repo's tracked `settings.json`, so a project's own status line can't shadow ContextSpin.
 
-Reverse it with `contextspin uninject` (restores your previous status line if a backup exists).
+Reverse it with `contextspin uninject` (this scope) or `contextspin uninstall` (every scope it ever wired, plus the hook and daemon).
 
 ### `patcher` (EXPERIMENTAL — binary patching)
 
@@ -258,13 +262,16 @@ Restore the originals with `contextspin uninject --mode patcher` (or `inject --m
 
 | Command | What it does |
 |---------|--------------|
-| `contextspin setup [--yes]` | Create `~/.contextspin.json` (interactive, or from the bundled example with `--yes` / non-TTY). |
+| `contextspin install` | **One-shot install:** wire a self-healing SessionStart hook, create the config, wire the statusline, and start the daemon. (This is what the curl script runs.) |
+| `contextspin uninstall` | **Full teardown:** remove the hook, restore your prior statusline in **every** scope it wired, and stop the daemon. |
+| `contextspin setup [--yes]` | Create `~/.contextspin.json` (interactive, or a detected config with `--yes` / non-TTY). |
 | `contextspin start` | Start the detached polling daemon. |
 | `contextspin stop` | Stop the daemon. |
 | `contextspin restart` | Stop then start. |
 | `contextspin status` | Show daemon state and the current cached snippets (source, age, shown count). |
-| `contextspin inject [--mode <m>]` | Install the injector. `<m>` overrides `injection.mode` (`statusline` / `patcher` / `both`). |
-| `contextspin uninject [--mode <m>]` | Reverse the injector. |
+| `contextspin ensure` | Idempotent: create config + wire statusline + start daemon (run by the SessionStart hook each session). |
+| `contextspin inject [--mode <m>]` | Install just the injector. `<m>` overrides `injection.mode` (`statusline` / `patcher` / `both`). |
+| `contextspin uninject [--mode <m>]` | Reverse just the injector. |
 | `contextspin` *(no subcommand)* | `setup` if unconfigured, otherwise `start` then `inject`. |
 
 ## High-impact snippets
@@ -306,16 +313,18 @@ Three tiers, by how time-sensitive they are.
 
 ## Limitations
 
-- **MCP support is stdio-only.** ContextSpin discovers MCP servers from `~/.claude.json` (user and per-project scopes) and `.mcp.json`, and connects only to **stdio** servers (those with a `command`). HTTP / SSE / WebSocket MCP transports are not supported in Stage 1 — use a `cli` or `http` source instead. Plugin / managed scopes are ignored.
+- **MCP support is stdio-only.** ContextSpin discovers MCP servers from `~/.claude.json` (user and per-project scopes) and `.mcp.json`, and connects only to **stdio** servers (those with a `command`). HTTP / SSE / WebSocket MCP transports are not supported — use a `cli` or `http` source instead. Plugin / managed scopes are ignored.
 - **OAuth-based claude.ai connectors are not reachable.** App-connected connectors (Slack, Notion, etc. linked through claude.ai) authenticate via OAuth tokens stored in the OS keychain. A standalone background daemon has no access to those tokens, so it cannot drive those connectors. Use the corresponding CLI (`gh`, `slack` CLI…) or HTTP endpoint, or a locally-configured stdio MCP server, instead.
 - **The status line shows one rotating snippet** at a time, honoring `cooldownAfterShown` so the same item doesn't repeat indefinitely.
 - **The patcher is experimental** and is **overwritten by every Claude Code update**. Treat it as best-effort; the statusline mode is the supported path.
 
-## Roadmap
+## Zero-config defaults (never an empty bar)
+
+A fresh install needs no setup:
 
-- **Stage 1 (now):** stdio MCP / CLI / HTTP sources, polling daemon + cache, statusline injection, experimental binary patcher, the CLI above.
-- **Stage 2 (polish):** quality-of-life improvements — better source discovery, richer setup wizard, more diagnostics.
-- **Stage 3 (`.plugin`):** package ContextSpin as a first-class Claude Code plugin.
+- The config is seeded with a **no-credentials starter pack** — local weather, a dad joke, and the top Hacker News story — so real snippets appear within seconds.
+- When the cache is empty or every snippet is exhausted, the renderer falls back to **built-in defaults** (jokes + "ask `/contextspin`…" tips) that rotate, so the bar is never blank — even offline or before the first poll.
+- A Claude Code **plugin** is also available (the [`mannutech` marketplace](https://github.com/mannutech/claude-plugins)) for those who prefer installing that way — it wraps this same package.
 
 ## References
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextspin",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Replace Claude Code spinner/statusline text with live org context (meetings, Slack, CI, incidents, PRs) aggregated from your existing MCP servers, CLIs, and HTTP endpoints.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -30,6 +30,7 @@ import {
   uninstallStatusline,
   uninstallAllStatuslines,
 } from './inject/statusline.js';
+import { addSessionStartHook, removeSessionStartHook } from './inject/hook.js';
 import { installPatcher, restorePatcher } from './inject/patcher.js';
 import { detectSources } from './detect.js';
 
@@ -476,88 +477,6 @@ async function runUninject(opts = {}) {
   }
 }
 
-/**
- * The SessionStart hook command the `install` flow wires into the user settings
- * so ContextSpin self-heals every session (the curl install replicates what the
- * Claude Code plugin's hook does, without the marketplace). Runs from a neutral
- * dir so npx never resolves a confused local package (Exit 127).
- */
-const SESSIONSTART_HOOK_CMD =
-  'cd /tmp && npx --yes contextspin ensure >/dev/null 2>&1; exit 0';
-
-/**
- * Read+parse a JSON file, returning a fallback on any read/parse error.
- * @param {string} filePath
- * @param {*} fallback
- * @returns {*}
- */
-function readJsonSafeSync(filePath, fallback) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return fallback;
-  }
-}
-
-/**
- * Whether a SessionStart entry already runs ContextSpin (so install is idempotent).
- * @param {*} entry
- * @returns {boolean}
- */
-function entryRunsContextspin(entry) {
-  return !!(
-    entry &&
-    Array.isArray(entry.hooks) &&
-    entry.hooks.some(
-      (h) => h && typeof h.command === 'string' && h.command.includes('contextspin'),
-    )
-  );
-}
-
-/**
- * Wire a ContextSpin SessionStart hook into the user ~/.claude/settings.json so
- * the daemon + statusline self-heal every session. JSON-merge (preserves every
- * other key and any existing hooks). Idempotent.
- * @returns {boolean} true if the hook was added (false if already present).
- */
-function addSessionStartHook() {
-  fs.mkdirSync(path.dirname(CLAUDE_SETTINGS_PATH), { recursive: true });
-  const settings = readJsonSafeSync(CLAUDE_SETTINGS_PATH, {});
-  const obj = settings && typeof settings === 'object' ? settings : {};
-  obj.hooks = obj.hooks && typeof obj.hooks === 'object' ? obj.hooks : {};
-  const arr = Array.isArray(obj.hooks.SessionStart) ? obj.hooks.SessionStart : [];
-  if (arr.some(entryRunsContextspin)) return false;
-  arr.push({
-    matcher: '',
-    hooks: [{ type: 'command', command: SESSIONSTART_HOOK_CMD, timeout: 15 }],
-  });
-  obj.hooks.SessionStart = arr;
-  fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(obj, null, 2));
-  return true;
-}
-
-/**
- * Remove any ContextSpin SessionStart hook from the user settings (best-effort,
- * JSON-merge). Prunes empty containers.
- * @returns {boolean} true if a hook was removed.
- */
-function removeSessionStartHook() {
-  const settings = readJsonSafeSync(CLAUDE_SETTINGS_PATH, null);
-  if (!settings || typeof settings !== 'object' || !settings.hooks) return false;
-  const arr = Array.isArray(settings.hooks.SessionStart)
-    ? settings.hooks.SessionStart
-    : [];
-  const kept = arr.filter((e) => !entryRunsContextspin(e));
-  if (kept.length === arr.length) return false;
-  if (kept.length > 0) settings.hooks.SessionStart = kept;
-  else delete settings.hooks.SessionStart;
-  if (settings.hooks && Object.keys(settings.hooks).length === 0) {
-    delete settings.hooks;
-  }
-  fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2));
-  return true;
-}
-
 /**
  * One-shot install (the `curl | bash` entrypoint): wire the SessionStart hook so
  * ContextSpin self-heals each session, then run ensure (config + statusline +
@@ -565,7 +484,7 @@ function removeSessionStartHook() {
  * @returns {Promise<void>}
  */
 async function runInstall() {
-  const addedHook = addSessionStartHook();
+  const addedHook = addSessionStartHook(readVersion());
   await runEnsure();
   console.log('');
   console.log(

package/src/config.js

@@ -34,8 +34,14 @@ export const LOG_PATH = path.join(STATE_DIR, "daemon.log");
 /** Path to the generated statusline bash wrapper. */
 export const STATUSLINE_SH = path.join(STATE_DIR, "statusline.sh");
 
-/** Path to the generated statusline Node render script. */
-export const STATUSLINE_JS = path.join(STATE_DIR, "statusline-render.js");
+/**
+ * Path to the generated statusline Node render script. Uses the `.mjs` extension
+ * so Node treats it as ESM regardless of version — the script lives in STATE_DIR
+ * (no package.json), and Node 18 has no automatic ESM detection, so a plain
+ * `.js` would fail to parse its `import` statements ("Cannot use import statement
+ * outside a module").
+ */
+export const STATUSLINE_JS = path.join(STATE_DIR, "statusline-render.mjs");
 
 /**
  * Path to the recorded prior statusLine commands (captured when we wrap an

package/src/inject/hook.js

@@ -0,0 +1,105 @@
+// src/inject/hook.js — manage ContextSpin's SessionStart hook in the user
+// ~/.claude/settings.json. Used by `contextspin install` / `uninstall` (the curl
+// flow) so ContextSpin self-heals every session without the plugin/marketplace.
+
+import fs from "node:fs";
+import path from "node:path";
+import { CLAUDE_SETTINGS_PATH } from "../config.js";
+
+/**
+ * Read+parse a JSON file, returning a fallback on any read/parse error.
+ * @param {string} filePath
+ * @param {*} fallback
+ * @returns {*}
+ */
+function readJsonSafeSync(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Build the SessionStart hook command, pinned to an EXACT version (never
+ * `@latest` or a range) so a future release never runs without a deliberate
+ * re-install. Runs from a neutral dir so npx can't resolve a confused local
+ * package (Exit 127).
+ * @param {string} version - The exact package version to pin (e.g. "0.6.3").
+ * @returns {string}
+ */
+export function sessionStartHookCmd(version) {
+  return `cd /tmp && npx --yes contextspin@${version} ensure >/dev/null 2>&1; exit 0`;
+}
+
+/**
+ * Whether a SessionStart entry already runs ContextSpin (any version).
+ * @param {*} entry
+ * @returns {boolean}
+ */
+export function entryRunsContextspin(entry) {
+  return !!(
+    entry &&
+    Array.isArray(entry.hooks) &&
+    entry.hooks.some(
+      (h) => h && typeof h.command === "string" && h.command.includes("contextspin"),
+    )
+  );
+}
+
+/**
+ * Upsert the ContextSpin SessionStart hook into the user settings, pinned to
+ * `version`. JSON-merge (preserves every other key and any non-ours hooks).
+ * Drops any prior ContextSpin entry (e.g. an older pinned version) so
+ * re-installing a newer version re-pins cleanly. Idempotent when already current.
+ * @param {string} version
+ * @param {string} [settingsPath=CLAUDE_SETTINGS_PATH]
+ * @returns {boolean} true if the file was changed (added or re-pinned).
+ */
+export function addSessionStartHook(version, settingsPath = CLAUDE_SETTINGS_PATH) {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  const settings = readJsonSafeSync(settingsPath, {});
+  const obj = settings && typeof settings === "object" ? settings : {};
+  obj.hooks = obj.hooks && typeof obj.hooks === "object" ? obj.hooks : {};
+  const arr = Array.isArray(obj.hooks.SessionStart) ? obj.hooks.SessionStart : [];
+
+  const desired = sessionStartHookCmd(version);
+  const existing = arr.find(entryRunsContextspin);
+  const alreadyCurrent =
+    existing &&
+    Array.isArray(existing.hooks) &&
+    existing.hooks.some((h) => h && h.command === desired);
+  if (alreadyCurrent) return false;
+
+  const others = arr.filter((e) => !entryRunsContextspin(e));
+  others.push({
+    matcher: "",
+    hooks: [{ type: "command", command: desired, timeout: 15 }],
+  });
+  obj.hooks.SessionStart = others;
+  fs.writeFileSync(settingsPath, JSON.stringify(obj, null, 2));
+  return true;
+}
+
+/**
+ * Remove any ContextSpin SessionStart hook from the user settings (JSON-merge,
+ * best-effort). Prunes empty containers.
+ * @param {string} [settingsPath=CLAUDE_SETTINGS_PATH]
+ * @returns {boolean} true if a hook was removed.
+ */
+export function removeSessionStartHook(settingsPath = CLAUDE_SETTINGS_PATH) {
+  const settings = readJsonSafeSync(settingsPath, null);
+  if (!settings || typeof settings !== "object" || !settings.hooks) return false;
+  const arr = Array.isArray(settings.hooks.SessionStart)
+    ? settings.hooks.SessionStart
+    : [];
+  const kept = arr.filter((e) => !entryRunsContextspin(e));
+  if (kept.length === arr.length) return false;
+  if (kept.length > 0) settings.hooks.SessionStart = kept;
+  else delete settings.hooks.SessionStart;
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  return true;
+}