terminalhire 0.2.2 → 0.2.4

package/install.js

@@ -1,26 +1,24 @@
 #!/usr/bin/env node
 /**
- * install.js — v3.1 installer for terminalhire
+ * install.js — installer for terminalhire (ambient spinner job surface)
  *
  * ToS / safety guardrails (binding — see CONSTITUTION.md Rule 7 and Rule 12):
- *   - ONLY uses the official Claude Code `statusLine` settings.json hook.
+ *   - ONLY uses the official Claude Code spinner settings (spinnerVerbs +
+ *     spinnerTipsOverride) via the spinner module. NEVER writes settings.statusLine.
  *   - NEVER silently modifies ~/.claude/settings.json.
  *   - Always backs up settings.json (timestamped) before any write.
- *   - Prints a clear disclosure of exactly what it changed.
- *   - Provides one-command uninstall that restores the backup.
- *   - CHAIN, never clobber: if a statusLine already exists that is NOT ours,
- *     creates a wrapper script that runs BOTH commands, then points settings.json
- *     at the wrapper. Idempotent — detects existing wrapper and does not double-wrap.
+ *   - Prints a clear disclosure of exactly what it changes.
+ *   - Requires an explicit typed "yes" before touching any system file.
+ *   - Provides one-command uninstall that clears our spinner verbs + tips.
  *   - postinstall (not this file) is print-only and never calls this file.
  *
  * What it does:
- *   1. Prints full v3 disclosure
+ *   1. Prints full disclosure (ambient spinner job surface only)
  *   2. Requires explicit "yes" before touching any system file
  *   3. Backs up ~/.claude/settings.json (timestamped)
- *   4. If no existing statusLine → sets terminalhire's nudge directly
- *      If existing statusLine (not ours) → builds a wrapper that chains both
- *   5. Supports --uninstall (restores the backup / removes wrapper)
- *   7. Idempotent: safe to run multiple times
+ *   4. Enables the ambient spinner job surface (spinnerVerbs + spinnerTipsOverride)
+ *   5. Supports --uninstall (clears our spinner verbs + tips, disables spinner)
+ *   6. Idempotent: safe to run multiple times
  *
  * Usage:
  *   node install.js
@@ -28,29 +26,22 @@
  */
 
 import {
-  readFileSync, writeFileSync, copyFileSync, existsSync,
-  mkdirSync, chmodSync, readdirSync,
+  readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createInterface } from 'node:readline';
-import { spawnSync } from 'node:child_process';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 
-// Resolve the nudge bin robustly: prefer the bundled dist output (published package),
-// fall back to the legacy bin/ path for in-workspace / development installs.
-const _distBin = resolve(join(__dirname, 'dist', 'bin', 'jpi.js'));
-const _legacyBin = resolve(join(__dirname, 'bin', 'jpi.js'));
-const BIN_PATH = existsSync(_distBin) ? _distBin : _legacyBin;
-
 const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
 const SETTINGS_DIR = dirname(SETTINGS_PATH);
 const TERMINALHIRE_DIR = join(homedir(), '.terminalhire');
-const WRAPPER_PATH = join(TERMINALHIRE_DIR, 'statusline-wrapper.sh');
 const CONFIG_FILE = join(TERMINALHIRE_DIR, 'config.json');
 
+const UNINSTALL = process.argv.includes('--uninstall');
+
 // Resolve the spinner module (dist preferred; bin fallback for the dev workspace).
 async function loadSpinnerModule() {
   const candidates = [
@@ -77,27 +68,8 @@ function patchConfig(patch) {
   writeFileSync(CONFIG_FILE, JSON.stringify({ ...cfg, ...patch }, null, 2) + '\n', 'utf8');
 }
 
-// The existing statusLine command on the user's machine that we must preserve
-const KNOWN_EXISTING_STATUSLINE = 'bash /Users/ericgang/.claude/statusline-command.sh';
-
-const UNINSTALL = process.argv.includes('--uninstall');
-
-// ── Sentinel comment embedded in the wrapper so we can detect our own wrappers
-const WRAPPER_SENTINEL = '# terminalhire-wrapper-v1';
-
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
-function readSettings() {
-  if (!existsSync(SETTINGS_PATH)) return {};
-  try {
-    return JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'));
-  } catch {
-    console.error('Error: ~/.claude/settings.json exists but is not valid JSON.');
-    console.error('Please fix it manually before running this installer.');
-    process.exit(1);
-  }
-}
-
 function backupSettings() {
   if (!existsSync(SETTINGS_PATH)) return null;
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
@@ -107,11 +79,6 @@ function backupSettings() {
   return backupPath;
 }
 
-function writeSettings(settings) {
-  mkdirSync(SETTINGS_DIR, { recursive: true });
-  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-}
-
 function ask(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   return new Promise(res => {
@@ -122,124 +89,32 @@ function ask(question) {
   });
 }
 
-/** Build the direct (no-chain) statusLine entry for terminalhire. */
-function buildDirectEntry(binPath) {
-  return `node ${binPath}`;
-}
-
-/**
- * Returns true if the given statusLine value is terminalhire's own entry:
- * either the direct node entry or our wrapper script.
- */
-function isOurEntry(statusLine) {
-  if (!statusLine) return false;
-  // Direct entry
-  if (statusLine === buildDirectEntry(BIN_PATH)) return true;
-  // Points at our wrapper
-  if (statusLine === `bash ${WRAPPER_PATH}`) return true;
-  // Wrapper exists and contains our sentinel
-  if (existsSync(WRAPPER_PATH)) {
-    try {
-      const wrapperContent = readFileSync(WRAPPER_PATH, 'utf8');
-      return wrapperContent.includes(WRAPPER_SENTINEL);
-    } catch { /* fall through */ }
-  }
-  return false;
-}
-
-/**
- * Normalize a statusLine value that may be a string or an object
- * (e.g. {type:"command", command:"..."} from Claude Code's settings).
- * Returns the shell command string, or null if the value is unusable.
- */
-function extractCommand(statusLine) {
-  if (!statusLine) return null;
-  if (typeof statusLine === 'string') return statusLine;
-  // Object form: {type: "command", command: "..."}
-  if (typeof statusLine === 'object' && typeof statusLine.command === 'string') {
-    return statusLine.command;
-  }
-  return null;
-}
-
-/**
- * Build the chaining wrapper shell script.
- * Both the existing command and the terminalhire nudge receive the SAME stdin JSON.
- * Output: existing command's output first, then terminalhire's output.
- * existingCmd MUST be a plain string (call extractCommand first).
- */
-function buildWrapper(existingCmd) {
-  return `#!/usr/bin/env bash
-${WRAPPER_SENTINEL}
-# Chains the original statusLine command with terminalhire's nudge.
-# Both receive the same stdin JSON. Original output prints first, then terminalhire.
-# Generated by: node install.js
-# Existing command: ${existingCmd}
-# terminalhire nudge: node ${BIN_PATH}
-
-# Read stdin once into a variable
-INPUT=$(cat)
-
-# Run the existing statusLine command
-EXISTING_OUT=$(printf '%s' "$INPUT" | ${existingCmd} 2>/dev/null || true)
-
-# Run terminalhire's nudge
-TH_OUT=$(printf '%s' "$INPUT" | node ${BIN_PATH} 2>/dev/null || true)
-
-# Print existing output (if any), then terminalhire output (if any)
-if [ -n "$EXISTING_OUT" ]; then
-  printf '%s\\n' "$EXISTING_OUT"
-fi
-if [ -n "$TH_OUT" ]; then
-  printf '%s\\n' "$TH_OUT"
-fi
-`;
-}
-
-/**
- * Find the most recent terminalhire backup of settings.json.
- * Returns the path or null.
- */
-function findLatestBackup() {
-  try {
-    const files = readdirSync(SETTINGS_DIR)
-      .filter(f => f.startsWith('settings.json.terminalhire-backup-'))
-      .sort()
-      .reverse();
-    if (files.length === 0) return null;
-    return join(SETTINGS_DIR, files[0]);
-  } catch {
-    return null;
-  }
-}
-
 // ── Install ───────────────────────────────────────────────────────────────────
 
 async function install() {
   console.log('');
   console.log('┌─────────────────────────────────────────────────────────────────┐');
-  console.log('│           terminalhire v0.1.1 — install statusLine hook         │');
-  console.log('│          Pull your matches. Your profile stays on-device.       │');
+  console.log('│        terminalhire — enable the ambient spinner job surface     │');
+  console.log('│          Pull your matches. Your profile stays on-device.        │');
   console.log('└─────────────────────────────────────────────────────────────────┘');
   console.log('');
   console.log('DISCLOSURE — read before installing');
   console.log('');
-  console.log('HOW IT WORKS (v3 pull model):');
+  console.log('HOW IT WORKS (pull model):');
   console.log('  1. `terminalhire jobs` downloads an anonymous job index from the server');
   console.log('     (GET /api/index — no dev data in the request).');
   console.log('  2. Matching runs LOCALLY against an encrypted profile on your device.');
-  console.log('  3. The status bar shows a nudge when matches exist.');
+  console.log('  3. The ambient spinner surfaces your top matches while Claude works.');
   console.log('     It reads only local files and makes zero network calls.');
-  console.log('  4. Nudge frequency: configurable via `terminalhire config --nudge`.');
-  console.log('     Default: once per session. Options: always | every:N.');
   console.log('');
-  console.log('  5. SPINNER JOB SURFACE (enabled by this install):');
+  console.log('  AMBIENT SPINNER JOB SURFACE (enabled by this install):');
   console.log('     While Claude is working, the spinner line shows your top LOCAL job');
   console.log('     matches, e.g.  Senior Backend Engineer @ Stripe · 82% …');
   console.log('     The "tip" line below it shows a ⌘-clickable link to open the listing');
   console.log('     (a terminalhire.com/j/… redirect — clicks are logged anonymously, no');
   console.log('     profile data). Uses official `spinnerVerbs`/`spinnerTipsOverride` settings');
   console.log('     (no patching, Rule 7). Computed locally, zero egress — only public job text.');
+  console.log('     This install does NOT write any statusLine — the spinner is the only surface.');
   console.log('     Turn it off any time:  terminalhire spinner --off');
   console.log('');
   console.log('YOUR LOCAL PROFILE (~/.terminalhire/profile.enc):');
@@ -263,44 +138,20 @@ async function install() {
   console.log('  • GitHub data enriches your LOCAL profile — no data leaves the machine');
   console.log('    unless you consent to include GitHub fields in a specific terminalhire lead.');
   console.log('');
-  console.log('HOW TO DISABLE / DELETE:');
-  console.log('  • Uninstall statusLine:  node install.js --uninstall');
-  console.log('  • Delete local profile:  terminalhire profile --delete');
-  console.log('  • Clear GitHub token:    terminalhire logout');
-  console.log('  • Wipe everything:       rm -rf ~/.terminalhire');
+  console.log('WHAT THIS INSTALL CHANGES:');
+  console.log('  • ~/.claude/settings.json — enables the spinner job surface only');
+  console.log('    (spinnerVerbs + spinnerTipsOverride). It does NOT write statusLine.');
+  console.log('  • A timestamped backup is created before any change.');
   console.log('');
-
-  const settings = readSettings();
-  // Normalize: settings.statusLine may be a string or an object {type,command}
-  const currentStatusLine = extractCommand(settings.statusLine);
-
-  // Already installed?
-  if (isOurEntry(currentStatusLine)) {
-    console.log('Already installed (statusLine is already terminalhire or our wrapper).');
-    console.log('');
-    console.log('To change nudge frequency: terminalhire config --nudge <session|always|every:N>');
-    console.log('To uninstall: node install.js --uninstall');
-    console.log('');
-    return;
-  }
-
-  // Determine install strategy
-  let installStrategy;
-  if (!currentStatusLine) {
-    installStrategy = 'direct';
-    console.log('  No existing statusLine found.');
-    console.log(`  Will set: statusLine = "node ${BIN_PATH}"`);
-  } else {
-    installStrategy = 'chain';
-    console.log(`  Existing statusLine detected: ${currentStatusLine}`);
-    console.log('  Will create a wrapper at: ~/.terminalhire/statusline-wrapper.sh');
-    console.log('  The wrapper runs BOTH commands (existing first, terminalhire second).');
-    console.log('  Both receive the same stdin JSON from Claude Code.');
-    console.log(`  Will set: statusLine = "bash ${WRAPPER_PATH}"`);
-  }
+  console.log('HOW TO DISABLE / DELETE:');
+  console.log('  • Disable spinner surface:  node install.js --uninstall');
+  console.log('  • (or)                      terminalhire spinner --off');
+  console.log('  • Delete local profile:     terminalhire profile --delete');
+  console.log('  • Clear GitHub token:       terminalhire logout');
+  console.log('  • Wipe everything:          rm -rf ~/.terminalhire');
   console.log('');
 
-  const installAnswer = await ask('Install terminalhire statusLine hook? Type "yes" to continue: ');
+  const installAnswer = await ask('Enable the terminalhire ambient spinner job surface? Type "yes" to continue: ');
   if (installAnswer !== 'yes') {
     console.log('\nAborted — nothing was changed.');
     process.exit(0);
@@ -309,35 +160,10 @@ async function install() {
   console.log('');
   const backupPath = backupSettings();
 
-  if (installStrategy === 'direct') {
-    // Claude Code requires statusLine as an object { type, command } — NOT a bare
-    // string (a string fails schema validation and makes Claude skip ALL settings).
-    settings.statusLine = { type: 'command', command: buildDirectEntry(BIN_PATH) };
-    writeSettings(settings);
-    console.log('  Set statusLine in ~/.claude/settings.json');
-    console.log(`    → node ${BIN_PATH}`);
-  } else {
-    // Write wrapper
-    mkdirSync(TERMINALHIRE_DIR, { recursive: true });
-    const wrapperContent = buildWrapper(currentStatusLine);
-    writeFileSync(WRAPPER_PATH, wrapperContent, 'utf8');
-    chmodSync(WRAPPER_PATH, 0o755);
-    console.log(`  Created wrapper: ${WRAPPER_PATH}`);
-
-    // Object form { type, command } — a bare string breaks Claude Code's settings schema.
-    settings.statusLine = { type: 'command', command: `bash ${WRAPPER_PATH}` };
-    writeSettings(settings);
-    console.log('  Updated statusLine in ~/.claude/settings.json');
-    console.log(`    → bash ${WRAPPER_PATH}`);
-    console.log('    (chains existing command + terminalhire nudge)');
-  }
-
-  if (backupPath) {
-    console.log(`  Backup: ${backupPath}`);
-  }
-
   // Enable the spinner job surface as part of this single consented install
-  // (Rule 10, amended: install IS the opt-in). Best-effort — never blocks install.
+  // (Rule 12: disclosure + timestamped backup + typed "yes" above). The spinner
+  // module is the ONLY writer of ~/.claude/settings.json here — verbs + tips only.
+  let enabled = false;
   try {
     patchConfig({ spinner: { enabled: true, mode: 'replace', max: 6 } });
     const spinnerMod = await loadSpinnerModule();
@@ -347,33 +173,55 @@ async function install() {
         const cache = JSON.parse(readFileSync(join(TERMINALHIRE_DIR, 'index-cache.json'), 'utf8'));
         if (Array.isArray(cache.topMatches)) topMatches = cache.topMatches;
       } catch { /* no cache yet — monitor will populate it */ }
+
       const verbs = spinnerMod.buildSpinnerPool(topMatches, 6);
       if (verbs.length > 0) spinnerMod.applySpinnerVerbs(verbs, 'replace');
+
+      // Tips line: ⌘-clickable listing links for the same top matches.
+      let tipsCount = 0;
+      try {
+        const tips = spinnerMod.buildTips(topMatches, 'https://terminalhire.com', 8);
+        if (Array.isArray(tips) && tips.length > 0) {
+          spinnerMod.applySpinnerTips(tips);
+          tipsCount = tips.length;
+        }
+      } catch { /* tips are best-effort */ }
+
+      enabled = true;
       console.log(
         '  Spinner job surface: ENABLED' +
         (verbs.length
           ? ` (${verbs.length} match${verbs.length === 1 ? '' : 'es'} live now)`
           : ' (matches appear after the first background refresh)')
       );
+      if (tipsCount > 0) {
+        console.log(`    Tip links: ${tipsCount} ⌘-clickable listing${tipsCount === 1 ? '' : 's'}`);
+      }
       console.log('    Turn off any time: terminalhire spinner --off');
     }
   } catch { /* spinner is best-effort; never block the install */ }
 
+  if (backupPath) {
+    console.log(`  Backup: ${backupPath}`);
+  }
+
+  if (!enabled) {
+    console.log('  Could not load the spinner module — nothing was enabled.');
+    console.log('  Run `terminalhire spinner --on` after building, or reinstall the package.');
+  }
+
   console.log('');
-  console.log('Done. Restart Claude Code to activate the status bar nudge.');
-  console.log('');
-  console.log('  Status bar format (default: once per session, only when matches exist):');
-  console.log('    ✦ N roles match your current work — run: terminalhire jobs');
+  console.log('Done. Restart Claude Code to activate the ambient spinner job surface.');
   console.log('');
-  console.log('  Nudge frequency:');
-  console.log('    terminalhire config --nudge session   (default — once per session)');
-  console.log('    terminalhire config --nudge always    (every statusLine render)');
-  console.log('    terminalhire config --nudge every:N   (every Nth render)');
+  console.log('  While Claude works, the spinner shows your top LOCAL matches, e.g.');
+  console.log('    Senior Backend Engineer @ Stripe · 82% …');
+  console.log('  with a ⌘-clickable tip link to open the listing.');
   console.log('');
   console.log('  Other commands:');
   console.log('    terminalhire login            — sign in with GitHub (enriches profile instantly)');
   console.log('    terminalhire logout           — clear GitHub token');
   console.log('    terminalhire jobs             — fetch index, match locally, browse roles');
+  console.log('    terminalhire spinner --off    — disable the ambient spinner surface');
   console.log('    terminalhire profile --show   — inspect your encrypted profile');
   console.log('    terminalhire profile --edit   — set displayName, contactEmail, prefs');
   console.log('    terminalhire profile --delete — wipe profile and key');
@@ -386,68 +234,41 @@ async function uninstall() {
   console.log('');
   console.log('terminalhire uninstall');
   console.log('');
-
-  const settings = readSettings();
-
-  if (!settings.statusLine) {
-    console.log('No statusLine entry found — nothing to remove.');
-    process.exit(0);
-  }
-
-  console.log(`  Current statusLine: ${settings.statusLine}`);
-
-  // Check if there is a backup to restore
-  const latestBackup = findLatestBackup();
-  if (latestBackup) {
-    console.log(`  Backup found: ${latestBackup}`);
-    console.log('  Uninstalling will restore this backup (restoring original statusLine).');
-  } else {
-    console.log('  No backup found — statusLine entry will be deleted (set to none).');
-  }
+  console.log('  This disables the ambient spinner job surface and clears the spinner');
+  console.log('  verbs + tips terminalhire added (any verbs/tips you set yourself are kept).');
+  console.log('  It does NOT touch settings.statusLine.');
   console.log('');
 
-  const answer = await ask('Uninstall terminalhire hook? Type "yes" to continue: ');
+  const answer = await ask('Disable the terminalhire spinner job surface? Type "yes" to continue: ');
   if (answer !== 'yes') {
     console.log('\nAborted — nothing was changed.');
     process.exit(0);
   }
 
   console.log('');
-
-  if (latestBackup) {
-    // Restore the backup
-    copyFileSync(latestBackup, SETTINGS_PATH);
-    console.log(`  Restored settings from backup: ${latestBackup}`);
-  } else {
-    // Just remove the statusLine key
-    backupSettings();
-    delete settings.statusLine;
-    writeSettings(settings);
-    console.log('  Removed statusLine from ~/.claude/settings.json');
-  }
-
-  // Remove wrapper if it exists and is ours
-  if (existsSync(WRAPPER_PATH)) {
-    try {
-      const wrapperContent = readFileSync(WRAPPER_PATH, 'utf8');
-      if (wrapperContent.includes(WRAPPER_SENTINEL)) {
-        // We don't delete it automatically — user may have customized it
-        console.log(`  Wrapper file left in place: ${WRAPPER_PATH}`);
-        console.log('  (Remove manually if desired: rm ~/.terminalhire/statusline-wrapper.sh)');
-      }
-    } catch { /* ignore */ }
+  const backupPath = backupSettings();
+  if (backupPath) {
+    console.log(`  Backup: ${backupPath}`);
   }
 
-  // Remove the spinner job verbs we injected (preserving any the user set themselves).
+  // Remove the spinner job verbs + tips we injected (preserving any the user set
+  // themselves) and disable the surface in our config.
   try {
     patchConfig({ spinner: { enabled: false } });
     const spinnerMod = await loadSpinnerModule();
     if (spinnerMod) {
-      const res = spinnerMod.clearSpinnerVerbs();
+      const vres = spinnerMod.clearSpinnerVerbs();
       console.log(
         '  Removed spinner job verbs' +
-        (res && res.keptUserVerbs ? ` (kept ${res.keptUserVerbs} of your own)` : '') + '.'
+        (vres && vres.keptUserVerbs ? ` (kept ${vres.keptUserVerbs} of your own)` : '') + '.'
       );
+      try {
+        const tres = spinnerMod.clearSpinnerTips();
+        console.log(
+          '  Removed spinner tip links' +
+          (tres && tres.keptUserTips ? ` (kept ${tres.keptUserTips} of your own)` : '') + '.'
+        );
+      } catch { /* tips clear is best-effort */ }
     }
   } catch { /* best-effort */ }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "terminalhire",
-  "version": "0.2.2",
-  "description": "Local-first job matching for developers — Claude Code statusLine nudge and ambient spinner job surface",
+  "version": "0.2.4",
+  "description": "Local-first job matching for developers — ambient job matches in the Claude Code spinner. Matching runs on your machine; your profile never leaves it.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/staqsIO/terminalhire.git"
@@ -27,7 +27,7 @@
   ],
   "scripts": {
     "build": "tsup",
-    "bundle:plugin": "npm run build && rm -rf ../../plugins/terminalhire/dist && cp -R dist ../../plugins/terminalhire/dist && cp package.json ../../plugins/terminalhire/dist/package.json",
+    "bundle:plugin": "npm run build && rm -rf ../../plugins/terminalhire/dist && cp -R dist ../../plugins/terminalhire/dist && cp package.json ../../plugins/terminalhire/dist/package.json && cp install.js ../../plugins/terminalhire/dist/install.js && cp postinstall.js ../../plugins/terminalhire/dist/postinstall.js",
     "prepublishOnly": "npm run build",
     "install-hook": "node install.js",
     "postinstall": "node ./postinstall.js"