[gobby-cli-#142] feat(ghook): diagnose schema v2 + install provenance + release CI guard

joshwilhelmi · claude · joshwilhelmi · commit 4f4be047a46a · 2026-04-22T01:08:30.000-05:00
Bump ghook 0.2.2 -> 0.3.0. Add install_method and install_source_url to --diagnose output, sourced from an optional .ghook-install.json sidecar next to the binary. Adds the v2 schema; v1 stays as a frozen historical schema. Adds a release-time guard that fails the workflow if the pushed ghook-v{X} tag version does not match crates/ghook/Cargo.toml, closing the drift mode in #4 that broke the public installer GitHub-asset lookup. Also folds in the unreleased 0.2.2 #141 fix (preserve non-stop block JSON. Refs #4. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> EOF )
diff --git a/.github/workflows/release-ghook.yml b/.github/workflows/release-ghook.yml
@@ -20,6 +20,28 @@ jobs:
         with:
           components: clippy
 
+      - name: Verify tag matches Cargo.toml version
+        # Guards against the tag/crate/release drift that broke installer
+        # discovery in 0.2.x (see GobbyAI/gobby-cli#4): the public installer
+        # resolves a version from crates.io and then looks for a matching
+        # ghook-v{version} GitHub asset, so the tag, the crate version, and
+        # the release name all have to line up exactly. Fail fast here so a
+        # mismatched tag never produces a published crate or release.
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF#refs/tags/}"
+          tag_version="${tag#ghook-v}"
+          if [ "$tag" = "$tag_version" ]; then
+            echo "::error::Tag '$tag' does not start with 'ghook-v'." >&2
+            exit 1
+          fi
+          cargo_version="$(cargo pkgid -p gobby-hooks | sed 's/.*@//')"
+          if [ "$tag_version" != "$cargo_version" ]; then
+            echo "::error::Tag version '$tag_version' does not match crates/ghook/Cargo.toml version '$cargo_version'." >&2
+            exit 1
+          fi
+          echo "Tag '$tag' aligns with crates/ghook/Cargo.toml version '$cargo_version'."
+
       - name: Clippy
         run: cargo clippy -p gobby-hooks --all-targets -- -D warnings
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,26 @@ All notable changes to gobby-cli are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] — gobby-hooks
+
+### Added
+
+#### gobby-hooks
+
+- **Diagnose schema v2 with install provenance** — `ghook --diagnose` now emits two new fields, `install_method` and `install_source_url`, and stamps the output with `schema_version: 2`. Both fields are sourced from an optional sidecar file, `.ghook-install.json`, written by the installer next to the `ghook` binary. When no sidecar is present (e.g. plain `cargo install gobby-hooks`), both fields are `null` — so consumers can identify which install path produced a given binary in bug reports. The new schema lives at `crates/ghook/schemas/diagnose-output.v2.schema.json`; the v1 schema file is preserved unchanged as a frozen historical schema for tools that pinned to v1. The Gobby installer is the canonical sidecar writer; see `docs/guides/ghook-development-guide.md` for the full contract. (#4)
+
+### Changed
+
+#### CI/CD
+
+- **Release-time tag/version alignment guard** — the `release-ghook` workflow now fails fast if the pushed `ghook-v{X}` tag's version suffix doesn't match the version in `crates/ghook/Cargo.toml`. This closes the drift mode that produced [GobbyAI/gobby-cli#4](https://github.com/GobbyAI/gobby-cli/issues/4), where the public installer's `ghook-v{version}` GitHub-asset lookup could silently miss because the tag, crate version, and release name had diverged. The guard runs before clippy/tests so a misaligned tag never reaches crates.io or the GitHub release. (#4)
+
+### Fixed
+
+#### gobby-hooks
+
+- **Preserve non-stop block JSON** — folded forward from the unreleased 0.2.2 prep: `ghook` no longer collapses non-Stop block responses to a bare `Blocked by hook` message; the original block JSON is preserved for downstream consumers. (#141)
+
 ## [0.2.1] — gobby-hooks
 
 ### Fixed
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/crates/ghook/Cargo.toml b/crates/ghook/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "gobby-hooks"
-version = "0.2.2"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.85"
 authors = ["Josh Wilhelmi <hello@gobby.ai>"]
diff --git a/crates/ghook/README.md b/crates/ghook/README.md
@@ -25,6 +25,13 @@ Exit codes:
 ## Schemas
 
 - `schemas/inbox-envelope.v1.schema.json` — what lands in the inbox.
-- `schemas/diagnose-output.v1.schema.json` — what `--diagnose` prints.
+- `schemas/diagnose-output.v2.schema.json` — what `--diagnose` prints. Adds `install_method` and `install_source_url` fields sourced from an installer-written sidecar (`.ghook-install.json`, next to the binary).
+- `schemas/diagnose-output.v1.schema.json` — frozen historical schema for the 0.1.x and 0.2.x diagnose output. Kept for tooling that pinned to v1.
 
-Both are validated in unit tests.
+The active schemas (envelope v1, diagnose v2) are validated in unit tests.
+
+## Install provenance
+
+`ghook --diagnose` reads an optional sidecar file named `.ghook-install.json` from the same directory as the running binary. When present, its `install_method` and `install_source_url` fields surface in the diagnose output so bug reports can identify how a given binary got installed (GitHub release, `cargo-binstall`, `cargo install`, etc.).
+
+The Gobby installer writes this sidecar atomically every time it places a `ghook` binary. Manual installs (e.g. plain `cargo install gobby-hooks`) leave both fields as `null`. See `docs/guides/ghook-development-guide.md` for the contract.
diff --git a/crates/ghook/schemas/diagnose-output.v2.schema.json b/crates/ghook/schemas/diagnose-output.v2.schema.json
@@ -0,0 +1,80 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://gobby.ai/schemas/ghook/diagnose-output.v2.schema.json",
+  "title": "Gobby ghook --diagnose output",
+  "description": "Output of `ghook --diagnose --cli=<c> --type=<t>`. Schema version 2 — adds install_method and install_source_url for install-provenance reporting. v1 fields are unchanged.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "ghook_version",
+    "cli",
+    "hook_type",
+    "critical",
+    "terminal_context_enabled",
+    "daemon_url",
+    "daemon_host",
+    "daemon_port",
+    "cli_recognized"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 2
+    },
+    "ghook_version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "cli": {
+      "type": "string",
+      "minLength": 1
+    },
+    "hook_type": {
+      "type": "string",
+      "minLength": 1
+    },
+    "source": {
+      "type": ["string", "null"]
+    },
+    "critical": {
+      "type": "boolean"
+    },
+    "terminal_context_enabled": {
+      "type": "boolean"
+    },
+    "daemon_url": {
+      "type": "string",
+      "minLength": 1
+    },
+    "daemon_host": {
+      "type": "string",
+      "minLength": 1
+    },
+    "daemon_port": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 65535
+    },
+    "project_root": {
+      "type": ["string", "null"]
+    },
+    "project_id": {
+      "type": ["string", "null"]
+    },
+    "terminal_context_preview": {
+      "type": ["object", "null"]
+    },
+    "cli_recognized": {
+      "type": "boolean"
+    },
+    "install_method": {
+      "type": ["string", "null"],
+      "description": "How ghook was installed, sourced from the install sidecar (.ghook-install.json) next to the binary. Conventional values: github-release, crates-binstall, cargo-install, manual, unknown. null when no sidecar is present (e.g. cargo install without a sidecar-writing installer)."
+    },
+    "install_source_url": {
+      "type": ["string", "null"],
+      "description": "URL the binary was fetched from (typically a GitHub release asset URL), sourced from the install sidecar. null when unknown or not applicable."
+    }
+  }
+}
diff --git a/crates/ghook/src/diagnose.rs b/crates/ghook/src/diagnose.rs
@@ -1,15 +1,15 @@
 //! `ghook --diagnose` — print what *would* happen for a given CLI/hook combo.
 //!
 //! Emits a JSON object validated against
-//! `schemas/diagnose-output.v1.schema.json`. No network I/O, no envelope
+//! `schemas/diagnose-output.v2.schema.json`. No network I/O, no envelope
 //! write — this is a pure introspection surface so operators can confirm
 //! configuration without spamming the inbox.
 
 use crate::cli_config::CliConfig;
 use gobby_core::{bootstrap, daemon_url, project};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 use serde_json::Value;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 
 #[derive(Debug, Serialize)]
 pub struct DiagnoseOutput {
@@ -27,11 +27,48 @@ pub struct DiagnoseOutput {
     pub project_id: Option<String>,
     pub terminal_context_preview: Option<Value>,
     pub cli_recognized: bool,
+    pub install_method: Option<String>,
+    pub install_source_url: Option<String>,
 }
 
-pub const DIAGNOSE_SCHEMA_VERSION: u32 = 1;
+pub const DIAGNOSE_SCHEMA_VERSION: u32 = 2;
 pub const GHOOK_VERSION: &str = env!("CARGO_PKG_VERSION");
 
+/// Sidecar filename written by the installer next to the `ghook` binary.
+/// See `docs/guides/ghook-development-guide.md` for the contract.
+pub const INSTALL_SIDECAR_FILENAME: &str = ".ghook-install.json";
+
+#[derive(Debug, Deserialize)]
+struct InstallSidecar {
+    install_method: Option<String>,
+    install_source_url: Option<String>,
+}
+
+/// Read the install-provenance sidecar from `dir/.ghook-install.json` and
+/// return `(install_method, install_source_url)`. Any failure (missing file,
+/// unreadable, malformed JSON) collapses to `(None, None)` — the sidecar is
+/// best-effort metadata, never load-bearing.
+pub fn read_install_provenance(dir: &Path) -> (Option<String>, Option<String>) {
+    let path = dir.join(INSTALL_SIDECAR_FILENAME);
+    let Ok(bytes) = std::fs::read(&path) else {
+        return (None, None);
+    };
+    let Ok(sidecar) = serde_json::from_slice::<InstallSidecar>(&bytes) else {
+        return (None, None);
+    };
+    (sidecar.install_method, sidecar.install_source_url)
+}
+
+fn install_provenance_for_running_binary() -> (Option<String>, Option<String>) {
+    let Ok(exe) = std::env::current_exe() else {
+        return (None, None);
+    };
+    let Some(dir) = exe.parent() else {
+        return (None, None);
+    };
+    read_install_provenance(dir)
+}
+
 pub fn diagnose(cli: &str, hook_type: &str) -> DiagnoseOutput {
     let cfg = CliConfig::for_cli(cli);
     let cli_recognized = cfg.is_some();
@@ -59,6 +96,8 @@ pub fn diagnose(cli: &str, hook_type: &str) -> DiagnoseOutput {
         None => (None, false, false, None),
     };
 
+    let (install_method, install_source_url) = install_provenance_for_running_binary();
+
     DiagnoseOutput {
         schema_version: DIAGNOSE_SCHEMA_VERSION,
         ghook_version: GHOOK_VERSION,
@@ -74,12 +113,15 @@ pub fn diagnose(cli: &str, hook_type: &str) -> DiagnoseOutput {
         project_id,
         terminal_context_preview,
         cli_recognized,
+        install_method,
+        install_source_url,
     }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::io::Write;
 
     #[test]
     fn unknown_cli_marked_not_recognized() {
@@ -108,35 +150,94 @@ mod tests {
         assert!(d.terminal_context_enabled);
     }
 
-    #[test]
-    fn diagnose_output_validates_against_v1_schema() {
-        let schema_bytes = include_bytes!("../schemas/diagnose-output.v1.schema.json");
+    fn compile_v2_schema() -> jsonschema::JSONSchema {
+        let schema_bytes = include_bytes!("../schemas/diagnose-output.v2.schema.json");
         let schema: serde_json::Value = serde_json::from_slice(schema_bytes).unwrap();
-        let compiled = jsonschema::JSONSchema::options()
+        jsonschema::JSONSchema::options()
             .with_draft(jsonschema::Draft::Draft7)
             .compile(&schema)
-            .expect("schema compiles");
-        let out = diagnose("claude", "session-start");
-        let v = serde_json::to_value(&out).unwrap();
-        if let Err(errs) = compiled.validate(&v) {
+            .expect("schema compiles")
+    }
+
+    fn assert_validates(schema: &jsonschema::JSONSchema, value: &serde_json::Value) {
+        if let Err(errs) = schema.validate(value) {
             let msgs: Vec<_> = errs.map(|e| format!("{e}")).collect();
             panic!("diagnose output failed schema validation: {msgs:?}");
         }
     }
 
+    #[test]
+    fn diagnose_output_validates_against_v2_schema() {
+        let compiled = compile_v2_schema();
+        let out = diagnose("claude", "session-start");
+        let v = serde_json::to_value(&out).unwrap();
+        assert_validates(&compiled, &v);
+    }
+
     #[test]
     fn diagnose_output_for_unknown_cli_validates() {
-        let schema_bytes = include_bytes!("../schemas/diagnose-output.v1.schema.json");
-        let schema: serde_json::Value = serde_json::from_slice(schema_bytes).unwrap();
-        let compiled = jsonschema::JSONSchema::options()
-            .with_draft(jsonschema::Draft::Draft7)
-            .compile(&schema)
-            .expect("schema compiles");
+        let compiled = compile_v2_schema();
         let out = diagnose("cursor", "session-start");
         let v = serde_json::to_value(&out).unwrap();
-        if let Err(errs) = compiled.validate(&v) {
-            let msgs: Vec<_> = errs.map(|e| format!("{e}")).collect();
-            panic!("diagnose output failed schema validation: {msgs:?}");
-        }
+        assert_validates(&compiled, &v);
+    }
+
+    #[test]
+    fn schema_version_is_two() {
+        let d = diagnose("claude", "session-start");
+        assert_eq!(d.schema_version, 2);
+    }
+
+    #[test]
+    fn install_provenance_absent_when_no_sidecar() {
+        let dir = tempfile::tempdir().unwrap();
+        let (method, url) = read_install_provenance(dir.path());
+        assert!(method.is_none());
+        assert!(url.is_none());
+    }
+
+    #[test]
+    fn install_provenance_read_from_sidecar() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(INSTALL_SIDECAR_FILENAME);
+        let mut f = std::fs::File::create(&path).unwrap();
+        write!(
+            f,
+            r#"{{
+                "install_method": "github-release",
+                "install_source_url": "https://github.com/GobbyAI/gobby-cli/releases/download/ghook-v0.3.0/ghook-aarch64-apple-darwin.tar.gz",
+                "installed_version": "0.3.0",
+                "installed_at": "2026-04-22T18:30:00Z"
+            }}"#
+        )
+        .unwrap();
+        let (method, url) = read_install_provenance(dir.path());
+        assert_eq!(method.as_deref(), Some("github-release"));
+        assert_eq!(
+            url.as_deref(),
+            Some(
+                "https://github.com/GobbyAI/gobby-cli/releases/download/ghook-v0.3.0/ghook-aarch64-apple-darwin.tar.gz"
+            )
+        );
+    }
+
+    #[test]
+    fn install_provenance_partial_sidecar_returns_present_fields() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(INSTALL_SIDECAR_FILENAME);
+        std::fs::write(&path, r#"{"install_method": "cargo-install"}"#).unwrap();
+        let (method, url) = read_install_provenance(dir.path());
+        assert_eq!(method.as_deref(), Some("cargo-install"));
+        assert!(url.is_none());
+    }
+
+    #[test]
+    fn install_provenance_malformed_json_collapses_to_none() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(INSTALL_SIDECAR_FILENAME);
+        std::fs::write(&path, "not json at all {{").unwrap();
+        let (method, url) = read_install_provenance(dir.path());
+        assert!(method.is_none());
+        assert!(url.is_none());
     }
 }
diff --git a/docs/guides/ghook-development-guide.md b/docs/guides/ghook-development-guide.md
diff --git a/docs/guides/ghook-user-guide.md b/docs/guides/ghook-user-guide.md
