contextspin 0.5.1 → 0.6.2

package/README.md

@@ -46,23 +46,33 @@ ContextSpin polls those sources on a schedule, formats whatever they return into
 
 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.
 
-## Install / Quickstart
+## Install
 
 Requires Node.js >= 18 (ContextSpin uses the built-in global `fetch`).
 
+**One line — that's it:**
+
 ```bash
-# 1. Create a config (interactive, or non-interactive with --yes)
-npx contextspin setup
+curl -fsSL https://raw.githubusercontent.com/mannutech/contextspin/main/install.sh | bash
+```
+
+This wires a SessionStart hook into `~/.claude/settings.json` (so ContextSpin self-heals every session), seeds a no-credentials starter pack (weather, a dad joke, the top Hacker News story), and wires your status bar — non-destructively. Restart Claude Code and you'll see live snippets, never an empty bar.
 
-# 2. Start the background polling daemon
-npx contextspin start
+Prefer to do it yourself? `npx contextspin install` does the same thing. To remove everything: `npx contextspin uninstall`.
 
-# 3. Wire the snippets into the Claude Code status bar
-npx contextspin inject
+<details>
+<summary>Manual / advanced setup</summary>
+
+```bash
+npx contextspin setup     # create a config (add --yes to skip prompts)
+npx contextspin start     # start the background polling daemon
+npx contextspin inject    # wire snippets into the status bar
 ```
 
 Running `npx contextspin` with **no subcommand** is a shortcut: if no config exists it runs `setup`, otherwise it runs `start` followed by `inject` using the mode from your config.
 
+</details>
+
 Check what's happening at any time:
 
 ```bash

package/install.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# ContextSpin one-line installer.
+#
+#   curl -fsSL https://raw.githubusercontent.com/mannutech/contextspin/main/install.sh | bash
+#
+# Wires a SessionStart hook into ~/.claude/settings.json (so ContextSpin
+# self-heals every session) and sets up the config, statusline, and daemon.
+# Non-destructive: any existing statusline is composed, not replaced.
+set -euo pipefail
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "ContextSpin needs Node.js 18+ — install it from https://nodejs.org and re-run." >&2
+  exit 1
+fi
+
+MAJOR="$(node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)"
+if [ "${MAJOR}" -lt 18 ]; then
+  echo "ContextSpin needs Node.js 18+, but found $(node -v). Please upgrade." >&2
+  exit 1
+fi
+
+echo "Installing ContextSpin…"
+# Run from a neutral dir so npx never resolves a confused local package.
+cd /tmp
+npx --yes contextspin@latest install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextspin",
-  "version": "0.5.1",
+  "version": "0.6.2",
   "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": {
@@ -35,6 +35,7 @@
     "src",
     "README.md",
     "LICENSE",
+    "install.sh",
     ".contextspin.example.json"
   ]
 }

package/src/cli.js

@@ -25,7 +25,11 @@ import {
   isDaemonRunning,
   readCache,
 } from './daemon.js';
-import { installStatusline, uninstallStatusline } from './inject/statusline.js';
+import {
+  installStatusline,
+  uninstallStatusline,
+  uninstallAllStatuslines,
+} from './inject/statusline.js';
 import { installPatcher, restorePatcher } from './inject/patcher.js';
 import { detectSources } from './detect.js';
 
@@ -472,6 +476,131 @@ 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 +
+ * daemon) so it's live immediately. Prints a friendly summary.
+ * @returns {Promise<void>}
+ */
+async function runInstall() {
+  const addedHook = addSessionStartHook();
+  await runEnsure();
+  console.log('');
+  console.log(
+    addedHook
+      ? '✨ ContextSpin installed — it auto-refreshes every Claude Code session.'
+      : '✨ ContextSpin already installed (SessionStart hook present).',
+  );
+  console.log('   Restart Claude Code to see your statusline.');
+  console.log('   Check it anytime: contextspin status');
+}
+
+/**
+ * Full uninstall: remove the SessionStart hook, the statusline wiring, and stop
+ * the daemon.
+ * @returns {Promise<void>}
+ */
+async function runUninstall() {
+  const removedHook = removeSessionStartHook();
+  // Tear down EVERY scope we wired (user + each project the hook touched), not
+  // just the user scope — otherwise project-scoped wirings keep rendering.
+  const results = await uninstallAllStatuslines();
+  const removed = results.filter((r) => r && r.removed);
+  await stopDaemon();
+  console.log(
+    `ContextSpin uninstalled: removed the statusline from ${removed.length} ` +
+      `scope${removed.length === 1 ? '' : 's'}, ` +
+      `${removedHook ? 'dropped the SessionStart hook, ' : ''}stopped the daemon.`,
+  );
+  const projectScopes = removed.filter((r) => r.scope === 'project');
+  if (projectScopes.length > 0) {
+    console.log('Cleaned project statuslines:');
+    for (const r of projectScopes) console.log(`  ${r.settingsPath}`);
+  }
+}
+
 /**
  * The default action when no subcommand is given: set up if there is no config,
  * otherwise start the daemon and inject per the configured mode.
@@ -508,6 +637,18 @@ function buildProgram() {
     .option('--yes', 'skip prompts and write a detected config')
     .action(action(async (opts) => runSetup(opts)));
 
+  program
+    .command('install')
+    .description(
+      'One-line install: wire the SessionStart hook so ContextSpin self-heals each session, then set up config + statusline + daemon',
+    )
+    .action(action(async () => runInstall()));
+
+  program
+    .command('uninstall')
+    .description('Remove ContextSpin entirely (SessionStart hook, statusline, daemon)')
+    .action(action(async () => runUninstall()));
+
   program
     .command('ensure')
     .description(

package/src/config.js

@@ -47,6 +47,16 @@ export const STATUSLINE_JS = path.join(STATE_DIR, "statusline-render.js");
  */
 export const PREV_STATUSLINE_PATH = path.join(STATE_DIR, "prev-statusline.json");
 
+/**
+ * Path to the registry of every settings file ContextSpin has wired its
+ * statusLine into. A JSON array of scope KEYS ("" for the user scope, else an
+ * absolute realpath'd project dir). `installStatusline` appends to it; a full
+ * `uninstall` walks it so EVERY scope is torn down — not just the user scope.
+ * Without this, project-scoped wirings (written by the SessionStart hook per
+ * CLAUDE_PROJECT_DIR) would linger after uninstall.
+ */
+export const WIRED_STATUSLINES_PATH = path.join(STATE_DIR, "wired-statuslines.json");
+
 /** Path to Claude Code's settings file (patched by the statusline injector). */
 export const CLAUDE_SETTINGS_PATH = path.join(HOME, ".claude", "settings.json");
 

package/src/daemon.js

@@ -5,7 +5,7 @@ import fsp from "node:fs/promises";
 import process from "node:process";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { CACHE_PATH, STATE_DIR, PID_PATH, LOG_PATH, loadConfig } from "./config.js";
+import { CACHE_PATH, STATE_DIR, PID_PATH, LOG_PATH, loadConfig, configExists } from "./config.js";
 import { runSource } from "./runner.js";
 
 /**
@@ -187,6 +187,15 @@ export async function runDaemonLoop(opts = {}) {
   const runtime = { lastRun: {}, buckets: {}, snippets: [] };
   // eslint-disable-next-line no-constant-condition
   while (true) {
+    // Self-exit if the config has been deleted (e.g. the user ran
+    // `contextspin uninstall` or removed ~/.contextspin.json by hand). Without
+    // this the daemon would keep polling stale sources and writing the cache
+    // forever, so the statusline would still show text after a teardown.
+    if (!configExists(opts.configPath)) {
+      console.log("contextspin config removed — daemon shutting down.");
+      shutdown();
+      return;
+    }
     try {
       const snippets = await pollOnce(config, runtime);
       await writeCache({ updatedAt: nowISO(), snippets });

package/src/inject/statusline.js

@@ -33,6 +33,7 @@ import {
   CONFIG_PATH,
   CLAUDE_SETTINGS_PATH,
   DEFAULT_SNIPPETS,
+  WIRED_STATUSLINES_PATH,
 } from "../config.js";
 
 /**
@@ -460,6 +461,29 @@ async function writePrevMap(map) {
   await writeJsonAtomic(PREV_STATUSLINE_PATH, map);
 }
 
+/**
+ * Read the wired-statuslines registry: an array of scope KEYS ("" for user
+ * scope, else an absolute project dir). Tolerates a missing/bad file (-> []).
+ * @returns {string[]}
+ */
+function readWiredList() {
+  const raw = readJsonSafeSync(WIRED_STATUSLINES_PATH, null);
+  return Array.isArray(raw) ? raw.filter((k) => typeof k === "string") : [];
+}
+
+/**
+ * Record a scope KEY in the wired-statuslines registry (idempotent).
+ * @param {string} key - "" for user scope, else an absolute project dir.
+ * @returns {Promise<void>}
+ */
+async function addWired(key) {
+  const list = readWiredList();
+  if (!list.includes(key)) {
+    list.push(key);
+    await writeJsonAtomic(WIRED_STATUSLINES_PATH, list);
+  }
+}
+
 /**
  * Resolve the statusLine command currently configured in a settings file (if
  * any), ignoring our own wrapper. Returns null when the file has no usable
@@ -625,6 +649,10 @@ export async function installStatusline(config, opts = {}) {
 
   await writeJsonAtomic(targetPath, settingsObj);
 
+  // Record this scope in the wired registry so a later `uninstall` can tear down
+  // EVERY scope we touched (not just the user scope).
+  await addWired(key);
+
   if (composed) {
     const priorCmd = prior ? prior.command : (map[key] && map[key].command);
     warning =
@@ -772,3 +800,42 @@ export async function uninstallStatusline(opts = {}) {
     note: "Removed the ContextSpin statusLine entry.",
   };
 }
+
+/**
+ * Tear down EVERY statusline scope ContextSpin has wired, by walking the wired
+ * registry (plus the user scope, always). This is what a full `uninstall` should
+ * call: project-scoped wirings written by the SessionStart hook (one per
+ * CLAUDE_PROJECT_DIR) are otherwise invisible to a user-scope-only uninstall and
+ * would keep rendering the ContextSpin line after removal.
+ *
+ * Clears the registry when done. Never throws — a failure for one scope is
+ * captured in that scope's result and the walk continues.
+ *
+ * @returns {Promise<UninstallStatuslineResult[]>}
+ */
+export async function uninstallAllStatuslines() {
+  // Always include the user scope (""), plus every recorded project key.
+  const keys = Array.from(new Set(["", ...readWiredList()]));
+  const results = [];
+  for (const key of keys) {
+    const projectDir = key === "" ? undefined : key;
+    try {
+      results.push(await uninstallStatusline({ projectDir }));
+    } catch (err) {
+      results.push({
+        removed: false,
+        restored: false,
+        settingsPath: key,
+        scope: projectDir ? "project" : "user",
+        note: `failed: ${err && err.message ? err.message : String(err)}`,
+      });
+    }
+  }
+  // Registry is consumed — drop it.
+  try {
+    await fsp.unlink(WIRED_STATUSLINES_PATH);
+  } catch {
+    // best effort
+  }
+  return results;
+}