@trygocode/notify 0.2.0 → 0.3.2

package/README.md

@@ -17,6 +17,7 @@ waiting for you**, **errors out**, or when an overnight **loop completes / halts
 - [Auto-push to git (opt-in)](#auto-push-to-git-opt-in)
 - [Settings sync — the `config` command](#settings-sync--the-config-command)
 - [Ralph/Homer opt-in snippet (trigger C)](#ralphhomer-opt-in-snippet-trigger-c)
+- [Notify from any custom script (the minimal one-liner)](#notify-from-any-custom-script-the-minimal-one-liner)
 - [Troubleshooting](#troubleshooting)
 - [Changelog](#changelog)
 - [Develop](#develop)
@@ -125,6 +126,21 @@ The installed rule/skill tells the agent **not** to call the MCP tool for
 done/idle/error pings — those are owned by the deterministic hook (A), so you
 never get double-pinged.
 
+> **Cursor `stop.status` → kind mapping (since 0.3.0).** Cursor's `stop` hook
+> carries a `status` field in its stdin JSON. The `on-stop` dispatcher maps it
+> to the right notification kind automatically:
+>
+> | Cursor `stop.status` | Notification kind | Meaning |
+> |---|---|---|
+> | `completed` | `finished` | Agent turned cleanly (default — same as before 0.3.0) |
+> | `aborted` | `awaiting_input` | Agent yielded back to you — may need your input |
+> | `error` | `error` | Agent hit an error |
+> | absent / unrecognised | `finished` | Back-compatible fallback |
+>
+> Before 0.3.0, Cursor only ever sent `finished` regardless of what the agent
+> did. The status mapping requires no hook re-installation — run
+> `gocode-notify setup --force` once to apply the updated hook command.
+
 > **OpenCode's hook (A)** is a small `session.idle` plugin written to
 > `~/.config/opencode/plugin/gocode-notify.js`; on each `session.idle` event it
 > fire-and-forgets `gocode-notify on-stop --source opencode` (the same
@@ -316,7 +332,7 @@ Valid keys (mirror of the canonical schema):
 
 | Key | Type | Meaning |
 |---|---|---|
-| `kinds.finished` / `kinds.error` / `kinds.awaiting_input` / `kinds.loop_completed` / `kinds.loop_halted` | bool | Per-kind notification toggles |
+| `kinds.finished` / `kinds.error` / `kinds.awaiting_input` / `kinds.loop_completed` / `kinds.loop_halted` / `kinds.ralph_waiting` | bool | Per-kind notification toggles |
 | `min_duration_seconds` | int ≥ 0 | Only notify if the turn ran ≥ N seconds (0 = always) |
 | `quiet_hours.enabled` / `quiet_hours.start` / `quiet_hours.end` / `quiet_hours.tz` | bool / `HH:MM` / `HH:MM` / IANA tz | Do-not-disturb window |
 | `auto_push.enabled` | bool | Master auto-push switch (OFF by default) |
@@ -358,6 +374,41 @@ The ready-to-copy version with comments lives at
 loop scripts. Both lines are fire-and-forget (`|| true` + the CLI's 5s
 self-timeout), so a failed or slow push can never block or fail your loop.
 
+## Notify from any custom script (the minimal one-liner)
+
+Any shell script — a cron job, a `Makefile` target, a post-build hook, or
+someone else's automation — can send a push with a single line, no configuration
+beyond a one-time `gocode-notify login` pairing:
+
+```bash
+gocode-notify send --kind finished --source <name> || true
+```
+
+Replace `<name>` with a short identifier for the script (e.g. `ci`, `build`,
+`deploy`). The `|| true` guard ensures a failed or slow push **never** blocks the
+calling script (the CLI also self-times-out in 5 seconds).
+
+> **Discovery hint:** `gocode-notify status` always prints this line at the
+> bottom of its report so you can copy-paste it even when you don't have the
+> README handy.
+
+**Other useful kinds for custom scripts:**
+
+| Kind | When to use |
+|---|---|
+| `finished` | Script completed cleanly |
+| `error` | Script hit an error |
+| `awaiting_input` | Script paused; a human is needed |
+| `loop_completed` | Long-running loop finished all work |
+| `loop_halted` | Long-running loop stopped; human needed |
+
+Pass `--title "My script"` and `--body "extra detail"` to customise the
+notification text. Use `--project "$(basename "$PWD")"` to badge it with the
+project name on your phone. All flags are optional — only `--kind` is required.
+
+See `snippets/ralph-homer.sh` for the full Ralph/Homer lifecycle pattern
+(completed / halted / stall-edge / resumed).
+
 ## Troubleshooting
 
 **Start here:** `gocode-notify status` prints a one-screen report — whether
@@ -389,6 +440,29 @@ npm publish, real-device E2E), see
 
 ## Changelog
 
+### 0.3.0
+
+- **New: Cursor `stop.status` → kind mapping (T-CUR1/T-CUR4).** The `on-stop`
+  dispatcher now reads the Cursor `stop` hook's stdin JSON and maps `status` to
+  the right notification kind: `completed→finished`, `aborted→awaiting_input`,
+  `error→error`. Back-compatible: absent/unrecognised status → `finished`.
+  Run `gocode-notify setup --force` to pick up the updated hook command.
+- **New: `ralph_waiting` + `ralph_resumed` kinds (T-C1).** `NOTIFY_KINDS` now
+  includes the Ralph/Homer offline-stall lifecycle kinds. `ralph_waiting` fires
+  once on the stall edge (server drops repeats until a recovery event re-arms
+  it); `ralph_resumed` is a silent control event that resets the stall state
+  machine. See `snippets/ralph-homer.sh` for the edge-trigger pattern.
+- **Kind taxonomy (T-S1).** The server now classifies every kind into push-worthy
+  vs. silent-info buckets: `ralph_question` / `ralph_advanced` are never pushed
+  (Oracle-answerable questions are silent); `ralph_halted` / `ralph_completed` /
+  `ralph_waiting` (edge) are the only loop kinds that reach FCM.
+- **Foreground suppression (T-S2/T-S3).** The server suppresses a push when the
+  app is open on that exact chat (`POST /api/v1/notify/presence` heartbeat, 45s
+  TTL). Different-chat or closed app → push goes out as normal.
+- **Offline/stall debounce (T-S4).** Server-side edge-triggered state machine:
+  a loop retrying every 60s on a quota outage pushes once on stall and stays
+  silent until it recovers and stalls again.
+
 ### 0.2.0
 
 - **New: `launch` / `autopilot` command** — hand a large, multi-step task off to

package/dist/src/cli.js

@@ -21,6 +21,7 @@ import { setup } from "./setup.js";
 import { uninstall } from "./uninstall.js";
 import { cmdConfig } from "./config.js";
 import { onStop } from "./on_stop.js";
+import { gatherDoctor, formatDoctor } from "./doctor.js";
 /** Subcommands the finished CLI will expose (see PRD §4.1). */
 export const COMMANDS = [
     "login",
@@ -28,6 +29,7 @@ export const COMMANDS = [
     "test",
     "setup",
     "status",
+    "doctor",
     "mcp",
     "uninstall",
     "config",
@@ -38,6 +40,43 @@ export const COMMANDS = [
 export const COMMAND_ALIASES = {
     autopilot: "launch",
 };
+/**
+ * Read all available data from `process.stdin` when it is a pipe (not a TTY),
+ * returning the full content as a string. Best-effort: returns an empty string on
+ * any error or if stdin is a TTY (no data to consume). Used by {@link cmdOnStop}
+ * to consume the Cursor `stop` hook's JSON payload (T-CUR1 / PRD §8.5).
+ *
+ * The read is bounded to {@link MAX_STDIN_BYTES} to prevent a misbehaving hook
+ * from blocking with an enormous payload. The function resolves (never rejects)
+ * so it can never block the hook's turn.
+ */
+export const MAX_STDIN_BYTES = 65536; // 64 KiB — far more than any hook JSON
+export async function readStdinIfPipe(stream) {
+    const src = stream ?? process.stdin;
+    // In a TTY / non-pipe context there is nothing to read — return early so we
+    // never block waiting for input on an interactive terminal.
+    if (src.isTTY)
+        return "";
+    return new Promise((resolve) => {
+        const chunks = [];
+        let totalBytes = 0;
+        src.on("data", (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            totalBytes += buf.byteLength;
+            if (totalBytes <= MAX_STDIN_BYTES)
+                chunks.push(buf);
+        });
+        src.on("end", () => {
+            try {
+                resolve(Buffer.concat(chunks).toString("utf8"));
+            }
+            catch {
+                resolve("");
+            }
+        });
+        src.on("error", () => resolve(""));
+    });
+}
 export function printHelp() {
     console.log([
         `gocode-notify v${VERSION}`,
@@ -52,6 +91,7 @@ export function printHelp() {
         "  test       Send a canned test push",
         "  setup      Pair + detect runtimes + write configs",
         "  status     Report credentials / server / detected runtimes",
+        "  doctor     Self-diagnostic checklist with exact fix commands",
         "  mcp        Run as an MCP server over stdio",
         "  uninstall  Remove entries this tool added",
         "  config     Get/set Notify settings (get | set <key> <value> | pull)",
@@ -324,6 +364,26 @@ export async function cmdStatus(args, deps = {}) {
     }
     return 0;
 }
+/**
+ * Handle `gocode-notify doctor [--server URL]` (PRD §8.6 R10 / T-COV4).
+ * Prints a checklist: (1) paired? (2) server reachable? (3) which runner hooks
+ * installed (Cursor stop / Claude Stop + Notification)? (4) gocode-notify on
+ * PATH for non-login shells? Each ✗ item prints the exact fix command.
+ * Always exits 0 — it is an informational report, not a gate.
+ */
+export async function cmdDoctor(args, deps = {}) {
+    const flags = parseFlags(args);
+    const report = await gatherDoctor({
+        home: deps.home,
+        serverFlag: flagString(flags, "server") ?? deps.serverFlag,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        pathEnv: deps.pathEnv,
+    });
+    for (const line of formatDoctor(report))
+        console.log(line);
+    return 0;
+}
 /** True when a flag is present as a bare boolean or explicit `=true`. */
 function flagBool(flags, name) {
     const v = flags.get(name);
@@ -429,6 +489,17 @@ export async function cmdOnStop(args, deps = {}) {
     const flags = parseFlags(args);
     const agent = isAgentDriven(flags);
     const sink = deps.sink ?? stdoutSink;
+    // Read the hook's stdin JSON (T-CUR1 / PRD §8.5). The Cursor `stop` hook pipes
+    // its event data to the process stdin; we consume it here so on-stop can map
+    // the `status` field to the correct notification kind. Best-effort: errors and
+    // TTY contexts return an empty string (falls back to `finished` in on_stop.ts).
+    //
+    // Injection priority: deps.hookStdin (test stub) > deps.readStdin (test reader)
+    // > real stdin read. An explicit empty string from deps.hookStdin means "no
+    // stdin provided" (do not read from the real process.stdin).
+    const hookStdin = deps.hookStdin !== undefined
+        ? deps.hookStdin
+        : await (deps.readStdin ?? readStdinIfPipe)();
     const server = await resolveServerUrl(flagString(flags, "server"), deps);
     const run = deps.onStopImpl ?? onStop;
     const result = await run({
@@ -441,6 +512,7 @@ export async function cmdOnStop(args, deps = {}) {
         fetchImpl: deps.fetchImpl,
         timeoutMs: deps.timeoutMs,
         timestamp: deps.timestamp,
+        hookStdin,
     });
     const delivered = result.mode === "push"
         ? result.push?.notified === true
@@ -453,7 +525,9 @@ export async function cmdOnStop(args, deps = {}) {
             ? "dry-run: would send finished (auto-push off)"
             : result.mode === "deduped"
                 ? "deduped: another source already notified for this run"
-                : `finished ${delivered ? "delivered" : "not delivered"}`;
+                : result.mode === "autopilot-suppressed"
+                    ? "autopilot-suppressed: an Autopilot loop owns this turn's ping"
+                    : `finished ${delivered ? "delivered" : "not delivered"}`;
     if (agent) {
         sink({ step: "on-stop", ok: true, detail });
     }
@@ -586,6 +660,8 @@ export async function runAsync(argv) {
         return cmdTest(argv.slice(1));
     if (cmd === "status")
         return cmdStatus(argv.slice(1));
+    if (cmd === "doctor")
+        return cmdDoctor(argv.slice(1));
     if (cmd === "setup")
         return cmdSetup(argv.slice(1));
     if (cmd === "mcp")

package/dist/src/doctor.js

@@ -0,0 +1,262 @@
+// `gocode-notify doctor` — self-diagnostic checklist (PRD §8.6 R10 / T-COV4).
+//
+// Prints a human-readable checklist of the installation health so users know
+// immediately what is missing and how to fix it.  Checks (in order):
+//
+//   1. Paired?        credentials exist and are valid.
+//   2. Server reachable?  the bound (or default) server answers.
+//   3. Runner hooks installed?  Claude Code Stop/Notification + Cursor stop.
+//   4. `gocode-notify` on PATH?  resolvable in non-login shells.
+//
+// Every ✗ check prints the EXACT fix command so users never have to guess.
+// Always exits 0 — it is a report, not a gate.
+//
+// The gather / format split mirrors `status.ts`:
+//   `gatherDoctor`  → pure async data collection (injectable deps, fully testable)
+//   `formatDoctor`  → pure sync rendering to string lines
+//   `cmdDoctor`     → thin CLI wire-up in `cli.ts`
+//
+// Zero runtime deps — Node built-ins only, matching the package's zero-dep rule.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readCredentials, resolveServerUrl } from "./creds.js";
+import { probeServer, DEFAULT_PROBE_TIMEOUT_MS, UNPAIRED_WARNING } from "./status.js";
+// Re-export UNPAIRED_WARNING so existing `from "./doctor.js"` imports keep
+// working after the constant moved to status.ts (T-COV1).
+export { UNPAIRED_WARNING } from "./status.js";
+// ─── Hook markers ──────────────────────────────────────────────────────────
+// We detect our hook entries by looking for these stable tokens in the command
+// strings.  The same tokens are used by claude.ts / cursor.ts for idempotent
+// install / uninstall (kept in sync via the HOOK_SOURCE comments there).
+/** Tokens that identify a gocode-notify Claude Code hook in settings.json. */
+const CLAUDE_HOOK_TOKEN = "--source claude_code";
+/** Token that identifies our Cursor stop hook in hooks.json. */
+const CURSOR_HOOK_TOKEN = "--source cursor";
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function resolveHomeDir(opts) {
+    return opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? "~";
+}
+/** Read a JSON file; returns null on any error (absent, bad JSON, bad perms). */
+async function readJsonFile(p) {
+    try {
+        const raw = await fs.readFile(p, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `cmd` appears on any entry in `pathEnv` (colon-separated). */
+async function commandOnPath(cmd, pathEnv) {
+    if (!pathEnv)
+        return false;
+    const names = process.platform === "win32" ? [cmd, `${cmd}.exe`, `${cmd}.cmd`, `${cmd}.bat`] : [cmd];
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            try {
+                await fs.stat(path.join(dir, name));
+                return true;
+            }
+            catch {
+                // not in this dir — keep looking
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Recursively extract all `command` strings from a Claude/Cursor hooks value.
+ *
+ * Claude settings.json hook events have this shape:
+ *   hooks.Stop = [ { matcher: string, hooks: [ { type: "command", command: string } ] } ]
+ *
+ * Cursor hooks.json stop entries have this shape:
+ *   stop = [ { command: string } ]
+ *
+ * This walks the structure recursively so both formats are handled without
+ * needing a per-runtime parser.
+ */
+function extractCommands(value) {
+    if (!value)
+        return [];
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value)) {
+        const cmds = [];
+        for (const item of value)
+            cmds.push(...extractCommands(item));
+        return cmds;
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const cmds = [];
+        // If this object has a `command` string field, it's a hook entry.
+        if (typeof obj.command === "string")
+            cmds.push(obj.command);
+        // Recurse into `hooks` sub-array (Claude Code's two-level nesting).
+        if (obj.hooks)
+            cmds.push(...extractCommands(obj.hooks));
+        return cmds;
+    }
+    return [];
+}
+/** Extract all hook command strings from a hooks event value (array or object). */
+function flattenHookCommands(hooksValue) {
+    return extractCommands(hooksValue);
+}
+// ─── Core gather ────────────────────────────────────────────────────────────
+/**
+ * Collect the full {@link DoctorReport}. Never throws — errors are surfaced as
+ * failing checks with actionable fix commands.
+ */
+export async function gatherDoctor(opts = {}) {
+    const checks = [];
+    const home = resolveHomeDir(opts);
+    // ── 1. Paired? ─────────────────────────────────────────────────────────
+    let pairedOk = false;
+    let pairedDetail = "not paired";
+    try {
+        const creds = await readCredentials({ home: opts.home });
+        if (creds) {
+            pairedOk = true;
+            pairedDetail = `paired as ${creds.user_id} (${creds.label})`;
+        }
+    }
+    catch {
+        pairedDetail = "credentials file unreadable";
+    }
+    checks.push({
+        key: "paired",
+        label: "Paired?",
+        ok: pairedOk,
+        detail: pairedDetail,
+        fixCmd: pairedOk ? undefined : "gocode-notify login",
+    });
+    // ── 2. Server reachable? ───────────────────────────────────────────────
+    const serverUrl = await resolveServerUrl(opts.serverFlag, { home: opts.home });
+    const probe = await probeServer(serverUrl, {
+        fetchImpl: opts.fetchImpl,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
+    });
+    checks.push({
+        key: "server",
+        label: "Server reachable?",
+        ok: probe.reachable,
+        detail: `${serverUrl} (${probe.detail})`,
+        fixCmd: probe.reachable
+            ? undefined
+            : "# Check your network or run: gocode-notify login --server <url>",
+    });
+    // ── 3a. Claude Code Stop hook ──────────────────────────────────────────
+    const claudeSettingsPath = path.join(home, ".claude", "settings.json");
+    const claudeSettings = await readJsonFile(claudeSettingsPath);
+    const claudeHooks = claudeSettings &&
+        typeof claudeSettings === "object" &&
+        "hooks" in claudeSettings
+        ? claudeSettings.hooks
+        : null;
+    const claudeStopCommands = flattenHookCommands(claudeHooks &&
+        typeof claudeHooks === "object" &&
+        "Stop" in claudeHooks
+        ? claudeHooks.Stop
+        : null);
+    const claudeStopInstalled = claudeStopCommands.some((c) => c.includes(CLAUDE_HOOK_TOKEN));
+    checks.push({
+        key: "hook:claude-stop",
+        label: "Claude Code Stop hook installed?",
+        ok: claudeStopInstalled,
+        detail: claudeStopInstalled
+            ? `found in ${claudeSettingsPath}`
+            : claudeHooks === null
+                ? "~/.claude/settings.json not found or no hooks"
+                : "hook not found",
+        fixCmd: claudeStopInstalled ? undefined : "gocode-notify setup",
+    });
+    // ── 3b. Claude Code Notification hook ──────────────────────────────────
+    const claudeNotifyCommands = flattenHookCommands(claudeHooks &&
+        typeof claudeHooks === "object" &&
+        "Notification" in claudeHooks
+        ? claudeHooks.Notification
+        : null);
+    const claudeNotifyInstalled = claudeNotifyCommands.some((c) => c.includes(CLAUDE_HOOK_TOKEN));
+    checks.push({
+        key: "hook:claude-notification",
+        label: "Claude Code Notification hook installed?",
+        ok: claudeNotifyInstalled,
+        detail: claudeNotifyInstalled
+            ? `found in ${claudeSettingsPath}`
+            : "hook not found",
+        fixCmd: claudeNotifyInstalled ? undefined : "gocode-notify setup",
+    });
+    // ── 3c. Cursor stop hook ───────────────────────────────────────────────
+    const cursorHooksPath = path.join(home, ".cursor", "hooks.json");
+    const cursorHooks = await readJsonFile(cursorHooksPath);
+    // Pass the stop array directly (not wrapped in an object) so extractCommands
+    // can find the {command: ...} entries inside it.
+    const cursorStopValue = cursorHooks &&
+        typeof cursorHooks === "object" &&
+        "stop" in cursorHooks
+        ? cursorHooks.stop
+        : null;
+    const cursorStopEntries = flattenHookCommands(cursorStopValue);
+    const cursorStopInstalled = cursorStopEntries.some((c) => c.includes(CURSOR_HOOK_TOKEN));
+    checks.push({
+        key: "hook:cursor-stop",
+        label: "Cursor stop hook installed?",
+        ok: cursorStopInstalled,
+        detail: cursorStopInstalled
+            ? `found in ${cursorHooksPath}`
+            : cursorHooks === null
+                ? "~/.cursor/hooks.json not found"
+                : "hook not found",
+        fixCmd: cursorStopInstalled ? undefined : "gocode-notify setup",
+    });
+    // ── 4. gocode-notify on PATH? ──────────────────────────────────────────
+    const pathEnv = opts.pathEnv ?? process.env.PATH;
+    const onPath = await commandOnPath("gocode-notify", pathEnv);
+    checks.push({
+        key: "path",
+        label: "gocode-notify on PATH (non-login shells)?",
+        ok: onPath,
+        detail: onPath
+            ? "gocode-notify is resolvable"
+            : "not found on PATH — hooks may fail in non-login shells",
+        fixCmd: onPath
+            ? undefined
+            : "# Add npm global bin to PATH, e.g.:\n  echo 'export PATH=\"$(npm root -g)/../.bin:$PATH\"' >> ~/.bashrc",
+    });
+    return { checks };
+}
+// ─── Formatting ─────────────────────────────────────────────────────────────
+function mark(ok) {
+    return ok ? "✓" : "✗";
+}
+// UNPAIRED_WARNING is defined in status.ts and re-exported above (T-COV1).
+/**
+ * Render a {@link DoctorReport} as human-readable lines. Each failing check
+ * includes the exact fix command. Always friendly — never emits an error tone
+ * for passing checks.
+ */
+export function formatDoctor(report) {
+    const lines = ["gocode-notify doctor", ""];
+    for (const check of report.checks) {
+        lines.push(`${mark(check.ok)} ${check.label}`);
+        lines.push(`    ${check.detail}`);
+        if (!check.ok && check.fixCmd) {
+            lines.push(`    Fix: ${check.fixCmd}`);
+        }
+        lines.push("");
+    }
+    // Surface the unpaired warning loudly (T-COV1 requirement: "surface ⚠️ loop
+    // completion pushes will NOT reach your phone" when not paired).
+    const pairedCheck = report.checks.find((c) => c.key === "paired");
+    if (pairedCheck && !pairedCheck.ok) {
+        lines.push(UNPAIRED_WARNING);
+        lines.push("");
+    }
+    const allOk = report.checks.every((c) => c.ok);
+    lines.push(allOk ? "All checks passed." : "Some checks failed — see fix commands above.");
+    return lines;
+}