Merge pull request #22 from dmoliveira/my_opencode-doctor-polish

dmoliveira · web-flow · commit 056b9c454e15 · 2026-02-12T22:55:01.000+11:00
Add /notify and /digest doctor diagnostics with JSON output
diff --git a/Makefile b/Makefile
@@ -25,8 +25,10 @@ install-test: ## Run installer smoke test in temp HOME
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/plugin_command.py" profile lean; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/plugin_command.py" doctor --json; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/notify_command.py" status; \
+	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/notify_command.py" doctor --json; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/session_digest.py" run --reason install-test; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/session_digest.py" show; \
+	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/session_digest.py" doctor --json; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/telemetry_command.py" status; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/telemetry_command.py" doctor --json; \
 	HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/post_session_command.py" status; \
diff --git a/README.md b/README.md
@@ -169,6 +169,8 @@ Use these directly in OpenCode:
 ```text
 /notify status
 /notify help
+/notify doctor
+/notify doctor --json
 /notify profile all
 /notify profile quiet
 /notify profile focus
@@ -188,6 +190,8 @@ Autocomplete-friendly shortcuts:
 
 ```text
 /notify-help
+/notify-doctor
+/notify-doctor-json
 /notify-profile-all
 /notify-profile-focus
 /notify-sound-only
@@ -208,6 +212,8 @@ Use these directly in OpenCode:
 /digest run --reason manual
 /digest run --reason manual --run-post
 /digest show
+/digest doctor
+/digest doctor --json
 ```
 
 Autocomplete-friendly shortcuts:
@@ -216,6 +222,8 @@ Autocomplete-friendly shortcuts:
 /digest-run
 /digest-run-post
 /digest-show
+/digest-doctor
+/digest-doctor-json
 ```
 
 The digest command writes to `~/.config/opencode/digests/last-session.json` by default.
diff --git a/install.sh b/install.sh
@@ -68,7 +68,9 @@ if [ "$SKIP_SELF_CHECK" = false ]; then
   python3 "$INSTALL_DIR/scripts/mcp_command.py" status
   python3 "$INSTALL_DIR/scripts/plugin_command.py" status
   python3 "$INSTALL_DIR/scripts/notify_command.py" status
+  python3 "$INSTALL_DIR/scripts/notify_command.py" doctor
   python3 "$INSTALL_DIR/scripts/session_digest.py" show || true
+  python3 "$INSTALL_DIR/scripts/session_digest.py" doctor
   python3 "$INSTALL_DIR/scripts/telemetry_command.py" status
   python3 "$INSTALL_DIR/scripts/post_session_command.py" status
   python3 "$INSTALL_DIR/scripts/policy_command.py" status
@@ -94,9 +96,11 @@ printf "  /plugin status\n"
 printf "  /plugin doctor\n"
 printf "  /notify status\n"
 printf "  /notify profile focus\n"
+printf "  /notify doctor\n"
 printf "  /digest run --reason manual\n"
 printf "  /digest-run-post\n"
 printf "  /digest show\n"
+printf "  /digest doctor\n"
 printf "  /telemetry status\n"
 printf "  /telemetry profile local\n"
 printf "  /post-session status\n"
diff --git a/opencode.json b/opencode.json
@@ -114,6 +114,14 @@
       "description": "Show notification command usage",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/notify_command.py\" help`\nShow only the command output."
     },
+    "notify-doctor": {
+      "description": "Run notification diagnostics",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/notify_command.py\" doctor`\nShow only the command output."
+    },
+    "notify-doctor-json": {
+      "description": "Run notification diagnostics in JSON",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/notify_command.py\" doctor --json`\nShow only the command output."
+    },
     "notify-profile-all": {
       "description": "Enable all notification channels and events",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/notify_command.py\" profile all`\nShow only the command output."
@@ -146,6 +154,14 @@
       "description": "Show latest saved session digest",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/session_digest.py\" show`\nShow only the command output."
     },
+    "digest-doctor": {
+      "description": "Run digest diagnostics",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/session_digest.py\" doctor`\nShow only the command output."
+    },
+    "digest-doctor-json": {
+      "description": "Run digest diagnostics in JSON",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/session_digest.py\" doctor --json`\nShow only the command output."
+    },
     "post-session": {
       "description": "Manage post-session hook config (status|enable|disable|set)",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/post_session_command.py\" $ARGUMENTS`\nShow only the command output."
diff --git a/scripts/notify_command.py b/scripts/notify_command.py
@@ -134,11 +134,91 @@ def write_config(config_path: Path, state: dict) -> None:
 
 def usage() -> int:
     print(
-        "usage: /notify status | /notify help | /notify profile <all|quiet|focus|sound-only|visual-only> | /notify enable <all|sound|visual|complete|error|permission|question> | /notify disable <all|sound|visual|complete|error|permission|question> | /notify channel <complete|error|permission|question> <sound|visual> <on|off>"
+        "usage: /notify status | /notify help | /notify doctor [--json] | /notify profile <all|quiet|focus|sound-only|visual-only> | /notify enable <all|sound|visual|complete|error|permission|question> | /notify disable <all|sound|visual|complete|error|permission|question> | /notify channel <complete|error|permission|question> <sound|visual> <on|off>"
     )
     return 2
 
 
+def collect_doctor(config_path: Path, state: dict) -> dict:
+    problems: list[str] = []
+    warnings: list[str] = []
+
+    if not config_path.exists():
+        warnings.append("notification config file not found yet (using defaults)")
+
+    if not state["enabled"]:
+        warnings.append("global notifications are disabled")
+
+    if not state["sound"]["enabled"] and not state["visual"]["enabled"]:
+        warnings.append("both sound and visual channels are disabled")
+
+    enabled_events = [name for name in EVENTS if state["events"][name]]
+    if not enabled_events:
+        warnings.append("all events are disabled")
+
+    for event in EVENTS:
+        if state["events"][event] and not (
+            state["channels"][event]["sound"] or state["channels"][event]["visual"]
+        ):
+            warnings.append(
+                f"event {event} is enabled but both per-event channels are off"
+            )
+
+    return {
+        "result": "PASS" if not problems else "FAIL",
+        "config": str(config_path),
+        "enabled": state["enabled"],
+        "sound_enabled": state["sound"]["enabled"],
+        "visual_enabled": state["visual"]["enabled"],
+        "events": state["events"],
+        "channels": state["channels"],
+        "warnings": warnings,
+        "problems": problems,
+        "quick_fixes": [
+            "run /notify profile focus for low-noise defaults",
+            "run /notify enable visual or /notify enable sound",
+            "run /notify enable permission or /notify enable error",
+        ]
+        if warnings or problems
+        else [],
+    }
+
+
+def print_doctor(config_path: Path, state: dict, json_output: bool) -> int:
+    report = collect_doctor(config_path, state)
+
+    if json_output:
+        print(json.dumps(report, indent=2))
+        return 0 if report["result"] == "PASS" else 1
+
+    print("notify doctor")
+    print("-----------")
+    print(f"config: {report['config']}")
+    print(f"global: {'enabled' if report['enabled'] else 'disabled'}")
+    print(f"sound: {'enabled' if report['sound_enabled'] else 'disabled'}")
+    print(f"visual: {'enabled' if report['visual_enabled'] else 'disabled'}")
+    print("events:")
+    for event in EVENTS:
+        print(
+            f"- {event}: {'enabled' if state['events'][event] else 'disabled'} [sound={'on' if state['channels'][event]['sound'] else 'off'}, visual={'on' if state['channels'][event]['visual'] else 'off'}]"
+        )
+
+    if report["warnings"]:
+        print("\nwarnings:")
+        for item in report["warnings"]:
+            print(f"- {item}")
+
+    if report["problems"]:
+        print("\nproblems:")
+        for item in report["problems"]:
+            print(f"- {item}")
+        print("\nresult: FAIL")
+        return 1
+
+    print("\nresult: PASS")
+    return 0
+
+
 def print_status(config_path: Path, state: dict) -> int:
     print(f"all: {'enabled' if state['enabled'] else 'disabled'}")
     print(f"sound: {'enabled' if state['sound']['enabled'] else 'disabled'}")
@@ -215,6 +295,12 @@ def main(argv: list[str]) -> int:
     if argv[0] == "help":
         return usage()
 
+    if argv[0] == "doctor":
+        json_output = len(argv) > 1 and argv[1] == "--json"
+        if len(argv) > 1 and not json_output:
+            return usage()
+        return print_doctor(config_path, state, json_output)
+
     if argv[0] == "profile":
         if len(argv) < 2:
             return usage()
diff --git a/scripts/selftest.py b/scripts/selftest.py
@@ -220,6 +220,11 @@ def run_notify(*args: str) -> subprocess.CompletedProcess[str]:
         expect(result.returncode == 0, f"notify status failed: {result.stderr}")
         expect("config:" in result.stdout, "notify status should print config path")
 
+        result = run_notify("doctor", "--json")
+        expect(result.returncode == 0, f"notify doctor --json failed: {result.stderr}")
+        report = parse_json_output(result.stdout)
+        expect(report.get("result") == "PASS", "notify doctor should pass")
+
         digest_path = home / ".config" / "opencode" / "digests" / "selftest.json"
         digest_env = os.environ.copy()
         digest_env["MY_OPENCODE_DIGEST_PATH"] = str(digest_path)
@@ -248,6 +253,25 @@ def run_notify(*args: str) -> subprocess.CompletedProcess[str]:
         expect(result.returncode == 0, f"digest show failed: {result.stderr}")
         expect("reason: selftest" in result.stdout, "digest show should print reason")
 
+        result = subprocess.run(
+            [
+                sys.executable,
+                str(DIGEST_SCRIPT),
+                "doctor",
+                "--path",
+                str(digest_path),
+                "--json",
+            ],
+            capture_output=True,
+            text=True,
+            env=digest_env,
+            check=False,
+            cwd=REPO_ROOT,
+        )
+        expect(result.returncode == 0, f"digest doctor --json failed: {result.stderr}")
+        report = parse_json_output(result.stdout)
+        expect(report.get("result") == "PASS", "digest doctor should pass")
+
         telemetry_path = home / ".config" / "opencode" / "opencode-telemetry.json"
         telemetry_env = os.environ.copy()
         telemetry_env["OPENCODE_TELEMETRY_PATH"] = str(telemetry_path)
diff --git a/scripts/session_digest.py b/scripts/session_digest.py
@@ -166,7 +166,7 @@ def print_summary(path: Path, digest: dict) -> None:
 
 def usage() -> int:
     print(
-        'usage: /digest run [--reason <idle|exit|manual>] [--path <digest.json>] [--hook "command"] [--run-post] | /digest show [--path <digest.json>]'
+        'usage: /digest run [--reason <idle|exit|manual>] [--path <digest.json>] [--hook "command"] [--run-post] | /digest show [--path <digest.json>] | /digest doctor [--path <digest.json>] [--json]'
     )
     return 2
 
@@ -233,6 +233,89 @@ def command_show(argv: list[str]) -> int:
     return 0
 
 
+def collect_doctor(path: Path) -> dict:
+    problems: list[str] = []
+    warnings: list[str] = []
+
+    if not path.exists():
+        warnings.append("digest file does not exist yet")
+        return {
+            "result": "PASS",
+            "path": str(path),
+            "exists": False,
+            "warnings": warnings,
+            "problems": problems,
+            "quick_fixes": ["run /digest run --reason manual"],
+        }
+
+    try:
+        digest = json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        problems.append(f"failed to parse digest JSON: {exc}")
+        return {
+            "result": "FAIL",
+            "path": str(path),
+            "exists": True,
+            "warnings": warnings,
+            "problems": problems,
+            "quick_fixes": ["run /digest run --reason manual to regenerate"],
+        }
+
+    for field in ("timestamp", "reason", "cwd", "git"):
+        if field not in digest:
+            warnings.append(f"missing digest field: {field}")
+
+    git_block = digest.get("git")
+    if not isinstance(git_block, dict):
+        warnings.append("git block is missing or invalid")
+    else:
+        if git_block.get("branch") is None:
+            warnings.append("git branch is unknown")
+
+    return {
+        "result": "PASS" if not problems else "FAIL",
+        "path": str(path),
+        "exists": True,
+        "warnings": warnings,
+        "problems": problems,
+        "quick_fixes": ["run /digest run --reason manual"] if warnings else [],
+    }
+
+
+def command_doctor(argv: list[str]) -> int:
+    path_value = parse_option(argv, "--path")
+    json_output = "--json" in argv
+    if len([x for x in argv if x == "--json"]) > 1:
+        return usage()
+
+    path = Path(path_value).expanduser() if path_value else DEFAULT_DIGEST_PATH
+    report = collect_doctor(path)
+
+    if json_output:
+        print(json.dumps(report, indent=2))
+        return 0 if report["result"] == "PASS" else 1
+
+    print("digest doctor")
+    print("------------")
+    print(f"path: {report['path']}")
+    print(f"exists: {'yes' if report['exists'] else 'no'}")
+
+    if report["warnings"]:
+        print("\nwarnings:")
+        for item in report["warnings"]:
+            print(f"- {item}")
+
+    if report["problems"]:
+        print("\nproblems:")
+        for item in report["problems"]:
+            print(f"- {item}")
+        print("\nresult: FAIL")
+        return 1
+
+    print("\nresult: PASS")
+    return 0
+
+
 def main(argv: list[str]) -> int:
     if not argv:
         return usage()
@@ -246,6 +329,8 @@ def main(argv: list[str]) -> int:
         return command_run(rest)
     if command == "show":
         return command_show(rest)
+    if command == "doctor":
+        return command_doctor(rest)
     return usage()
 
 
