@sporhq/spor 0.2.8 → 0.2.9

package/adapters/copilot/README.md

@@ -20,8 +20,9 @@ sed "s|__SPOR_ROOT__|$SPOR_ROOT|g" \
 (Per-repo installs go in `.github/hooks/spor.json` — that is also the
 only location the Copilot cloud coding agent loads.) Environment is the
 usual set: `SPOR_SERVER`, `SPOR_TOKEN`, and `SPOR_DISTILL_CMD`
-(e.g. `copilot -p "$(cat)"`) if the claude CLI isn't installed; legacy
-`SUBSTRATE_*` names are still read.
+(e.g. `copilot -p "$(cat)"`) if the claude CLI isn't installed — set
+`SPOR_NUDGE_CMD` to the same value for the capture nudge, or `SPOR_NUDGE=0`
+to skip it; legacy `SUBSTRATE_*` names are still read.
 
 ## Event mapping
 

package/adapters/cursor/README.md

@@ -17,8 +17,9 @@ sed "s|__SPOR_ROOT__|$SPOR_ROOT|g" \
 (Or merge into an existing `~/.cursor/hooks.json` / project
 `.cursor/hooks.json`.) Environment is the usual set: `SPOR_SERVER`,
 `SPOR_TOKEN`, and `SPOR_DISTILL_CMD` if the claude CLI isn't installed
-(`cursor-agent -p` works: prompt on stdin, response on stdout); legacy
-`SUBSTRATE_*` names are still read.
+(`cursor-agent -p` works: prompt on stdin, response on stdout) — set
+`SPOR_NUDGE_CMD` to the same value for the capture nudge, or `SPOR_NUDGE=0`
+to skip it; legacy `SUBSTRATE_*` names are still read.
 
 ## Event mapping
 

package/adapters/gemini/README.md

@@ -31,6 +31,9 @@ export SPOR_SERVER=https://spor.example.com   # remote mode
 export SPOR_TOKEN=spor_pat_...
 # Distiller backend (prompt on stdin, response on stdout):
 export SPOR_DISTILL_CMD='gemini --model gemini-2.5-flash'
+# Capture-nudge backend (same contract; runs synchronously, so pick a fast
+# model). SPOR_NUDGE=0 disables it; see adapters/README.md for the bounds.
+export SPOR_NUDGE_CMD='gemini --model gemini-2.5-flash'
 ```
 
 (Legacy `SUBSTRATE_*` names are still read.)

package/adapters/opencode/README.md

@@ -24,6 +24,9 @@ export SPOR_TOKEN=spor_pat_...
 # Distiller backend (prompt on stdin -> response on stdout); without the
 # claude CLI installed, route through opencode itself:
 export SPOR_DISTILL_CMD='opencode run "$(cat)"'
+# Capture-nudge backend — same contract, runs synchronously, so prefer a fast
+# model. SPOR_NUDGE=0 disables it; see adapters/README.md for the bounds.
+export SPOR_NUDGE_CMD='opencode run "$(cat)"'
 ```
 
 ## Behavior mapping

package/bin/spor-hook

@@ -3,5 +3,29 @@
 # kept so existing hooks configs and adapter manifests that exec this path
 # keep working unchanged. Windows hosts invoke spor-hook.js via node
 # (or spor-hook.cmd) instead. Fail-open: no node, no output, exit 0.
-command -v node >/dev/null 2>&1 || exit 0
-exec node "$(dirname "$0")/spor-hook.js" "$@"
+if command -v node >/dev/null 2>&1; then
+  exec node "$(dirname "$0")/spor-hook.js" "$@"
+fi
+# No Node interpreter — the hook can do nothing (the client is zero-dep *Node*).
+# Stay fail-open (exit 0, no output, no latency on the working path above), but
+# drop a ONE-TIME greppable breadcrumb so the silence is diagnosable instead of
+# invisible (issue-spor-onboarding-no-node-silent-fail-open). Best-effort: every
+# step is guarded and we exit 0 regardless, so this can never break fail-open.
+# Resolve the graph home the way lib/shell/home.js does: $SPOR_HOME, then the
+# legacy $SUBSTRATE_HOME, else ~/.spor (or ~/.substrate if that legacy dir
+# exists). The breadcrumb is written at most once (guarded by its own marker).
+_spor_home="${SPOR_HOME:-${SUBSTRATE_HOME:-}}"
+if [ -z "$_spor_home" ]; then
+  if [ -d "$HOME/.spor" ]; then _spor_home="$HOME/.spor"
+  elif [ -d "$HOME/.substrate" ]; then _spor_home="$HOME/.substrate"
+  else _spor_home="$HOME/.spor"
+  fi
+fi
+_spor_warn="$_spor_home/journal/no-node.warn"
+if [ -n "$HOME" ] && [ ! -f "$_spor_warn" ]; then
+  if mkdir -p "$_spor_home/journal" 2>/dev/null; then
+    printf '%s spor-hook: node not found on PATH — every hook is a silent no-op. Spor needs a Node interpreter (see package.json engines; `spor status` reports the floor). Install Node, then restart your session.\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo now)" >"$_spor_warn" 2>/dev/null || true
+  fi
+fi
+exit 0

package/bin/spor-hook.js

@@ -15,6 +15,7 @@
 //   spor-hook post-tool      [--host ...]
 //   spor-hook distill        [--host ...] [--debounce SECONDS]
 //   spor-hook agents-md      [--cwd DIR]    # AGENTS.md floor; no stdin
+//   spor-hook doctor         [--cwd DIR]    # client health report; no stdin
 //
 // Fail-open contract (dec-cc-fail-open-hooks): any failure exits 0 with no
 // output — a Spor problem never costs the user their session.
@@ -114,6 +115,23 @@ async function main() {
     return;
   }
 
+  // `spor-hook doctor` (task-cc-client-hook-operability-diagnostics piece 3):
+  // an operator-run diagnostic, not a host hook — it takes no stdin and prints a
+  // human-readable health report. It runs even when the plugin is disabled for
+  // the repo (a disabled plugin is exactly what you'd want doctor to tell you).
+  // Write the report with fs.writeSync(1) so the full body flushes before the
+  // crash handler's process.exit(0) can truncate a piped stdout.
+  if (event === "doctor") {
+    const { doctor } = require("../scripts/engines/doctor");
+    let dCwd = process.cwd();
+    const ci = args.indexOf("--cwd");
+    if (ci >= 0 && args[ci + 1]) dCwd = args[ci + 1];
+    u.useConfig({ cwd: dCwd });
+    const report = await doctor();
+    fs.writeSync(1, report);
+    return;
+  }
+
   if (!(event in ENGINES)) {
     process.stderr.write(`spor-hook: unknown event '${event}'\n`);
     return;