debughub 1.0.0

package/dist/commands/stop.js

@@ -0,0 +1,68 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stop = stop;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function stop() {
+    const cwd = process.cwd();
+    const stateFile = path.join(cwd, '.debughub', 'state.json');
+    if (!fs.existsSync(stateFile)) {
+        console.log('No DebugHub collector is currently running (state.json not found).');
+        return;
+    }
+    try {
+        const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+        if (state.pid) {
+            try {
+                process.kill(state.pid);
+                console.log(`Stopped collector process ${state.pid}.`);
+            }
+            catch (e) {
+                if (e.code === 'ESRCH') {
+                    console.log(`Process ${state.pid} was not running.`);
+                }
+                else {
+                    console.error(`Failed to stop process ${state.pid}:`, e.message);
+                }
+            }
+        }
+    }
+    catch (e) {
+        console.log('Could not read state.json or parse PID.');
+    }
+    fs.unlinkSync(stateFile);
+    console.log('Cleared state.');
+}

package/dist/commands/tail.js

@@ -0,0 +1,97 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tail = tail;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function tail(options) {
+    const cwd = process.cwd();
+    const debughubDir = path.join(cwd, '.debughub');
+    const maxLines = parseInt(options.n, 10);
+    let sessionId = options.session;
+    if (!sessionId) {
+        const stateFile = path.join(debughubDir, 'state.json');
+        if (fs.existsSync(stateFile)) {
+            try {
+                const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                sessionId = state.session;
+            }
+            catch (e) { }
+        }
+    }
+    if (!sessionId) {
+        console.error('Could not determine active session ID. Provide --session or run `debughub start`.');
+        process.exit(1);
+    }
+    const outFile = path.join(debughubDir, 'out', `${sessionId}.jsonl`);
+    if (!fs.existsSync(outFile)) {
+        console.log(`No events yet in session ${sessionId}`);
+        return;
+    }
+    // Quick read logic (assumes file is small enough for memory for a debug tool)
+    const content = fs.readFileSync(outFile, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    if (lines.length === 0) {
+        console.log(`No events yet in session ${sessionId}`);
+        return;
+    }
+    const toShow = lines.slice(-maxLines);
+    if (options.json) {
+        toShow.forEach(l => console.log(l));
+    }
+    else {
+        toShow.forEach(l => {
+            try {
+                const parsed = JSON.parse(l);
+                const ts = new Date(parsed.ts).toLocaleTimeString();
+                const levelColorStr = parsed.level === 'error' ? '\x1b[31m[ERROR]\x1b[0m' :
+                    parsed.level === 'warn' ? '\x1b[33m[WARN]\x1b[0m' :
+                        '\x1b[36m[INFO]\x1b[0m';
+                let meta = '';
+                if (parsed.hypothesisId)
+                    meta += ` [H:${parsed.hypothesisId}]`;
+                if (parsed.loc)
+                    meta += ` [L:${parsed.loc}]`;
+                console.log(`[${ts}] ${levelColorStr} ${parsed.label}${meta}`);
+                if (parsed.data !== null) {
+                    console.dir(parsed.data, { depth: 4, colors: true });
+                }
+            }
+            catch (e) {
+                console.log(l);
+            }
+        });
+    }
+}

package/dist/commands/verify.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verify = verify;
+exports.verifyVendorFiles = verifyVendorFiles;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+function verify() {
+    const cwd = process.cwd();
+    console.log('Verifying DebugHub installation files...');
+    const isValid = verifyVendorFiles(cwd);
+    if (isValid) {
+        console.log('✅ Integrity check passed: all installed vendor files match the official manifest.');
+    }
+    else {
+        console.error('❌ Integrity check failed: one or more files have been modified or are missing.');
+        process.exit(1);
+    }
+}
+function verifyVendorFiles(cwd) {
+    const currentLink = path.join(cwd, '.debughub', 'vendor', 'current');
+    if (!fs.existsSync(currentLink)) {
+        console.error(`Not found: ${currentLink}. Is DebugHub installed in this repo?`);
+        return false;
+    }
+    const version = fs.readFileSync(currentLink, 'utf-8').trim();
+    const vendorDir = path.join(cwd, '.debughub', 'vendor', version);
+    const manifestFile = path.join(vendorDir, 'MANIFEST.json');
+    if (!fs.existsSync(manifestFile)) {
+        console.error(`Missing MANIFEST.json in ${vendorDir}`);
+        return false;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf-8'));
+    }
+    catch (e) {
+        console.error('Failed to parse MANIFEST.json');
+        return false;
+    }
+    let isValid = true;
+    for (const [relPath, expectedHash] of Object.entries(manifest)) {
+        // relPath in manifest uses forward slashes
+        const targetFile = path.resolve(vendorDir, relPath);
+        if (!fs.existsSync(targetFile)) {
+            console.error(`File missing: ${relPath}`);
+            isValid = false;
+            continue;
+        }
+        const content = fs.readFileSync(targetFile);
+        const actualHash = crypto.createHash('sha256').update(content).digest('hex');
+        if (actualHash !== expectedHash) {
+            console.error(`Checksum mismatch in: ${relPath}`);
+            isValid = false;
+        }
+    }
+    return isValid;
+}

package/dist/vendor/1.0.0/MANIFEST.json

@@ -0,0 +1,13 @@
+{
+  "README.md": "d02d9b1b96e05f6592dfda76694665b71617eb997cebed61cedc407cf73a757d",
+  "csharp/DebugProbe.cs": "da0dad4e3fa65a57b68a37fe14313ced4ae9f32545f9a74ec15b86ac003bcf58",
+  "go/debug_probe.go": "c808270aced80c895b3145851bbdd36deee85920f9d599c8540531be43fe6e51",
+  "http/EVENT_CONTRACT.md": "b60e71b95723a19dd370b67bc440945a8d3bedaf5dfbacf512973893bce1030c",
+  "http/event.example.json": "e14bfc9dbde2025137ac247d6f466dc0f6185ba12a216c3970f32016b1e8da01",
+  "java/DebugProbe.java": "8777f46131f7c1148ec1a78f59d5477b6f4591fcef4d7f5d5e0eec97fae1534a",
+  "php/DebugProbe.php": "4b1c391cf3e2c7a32c1115504f54411906b14509011d294724d22b869d0275c6",
+  "python/debugProbe.py": "fbe195d941f456a9eada52e54a09adbbb7dd132623e3476e5cb69f865ed1ea5f",
+  "rust/debug_probe.rs": "0385485602e9e058cff577a62f6caa2e3f2fb6c0d2cb089927884ab1b6a66edc",
+  "ts/debugProbe.browser.ts": "ba82e5abfac8d6105e5d6831f24fada36bf00af9824028f793ba12ccac290977",
+  "ts/debugProbe.ts": "a79a3a1483ac246f0ffd3a2b32938e97ae4ce227bab42a6f5feccf57bd8e6788"
+}

package/dist/vendor/1.0.0/README.md

@@ -0,0 +1,26 @@
+# DebugHub Helpers
+
+These files are provided by [DebugHub](https://github.com/debughub/debughub), an agent-agnostic debugging proxy.
+
+## Supported Runtimes
+
+- TypeScript/Node: `helpers/ts/debugProbe.ts`
+- Browser TS/JS: `helpers/ts/debugProbe.browser.ts`
+- Java: `helpers/java/DebugProbe.java`
+- Python: `helpers/python/debugProbe.py`
+- Rust: `helpers/rust/debug_probe.rs`
+- PHP: `helpers/php/DebugProbe.php`
+- Go: `helpers/go/debug_probe.go`
+- C#: `helpers/csharp/DebugProbe.cs`
+
+## HTTP Contract
+
+All helpers follow the shared HTTP contract in `helpers/http/EVENT_CONTRACT.md`.
+
+At a high level:
+
+- Helpers no-op unless `DEBUGHUB_ENABLED=1` and `DEBUGHUB_SESSION` is set.
+- If `DEBUGHUB_ENDPOINT` is set, helpers do best-effort `POST` to `{endpoint}/event`.
+- Helpers never throw into host application code.
+
+See `helpers/http/event.example.json` for a reference payload.

package/dist/vendor/1.0.0/csharp/DebugProbe.cs

@@ -0,0 +1,97 @@
+using System;
+using System.Collections.Generic;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+
+public static class DebugProbe
+{
+    private static readonly HttpClient Client = new HttpClient
+    {
+        Timeout = TimeSpan.FromSeconds(2)
+    };
+
+    public static void Probe(string label, object? data = null, Dictionary<string, object?>? meta = null)
+    {
+        try
+        {
+            if (Environment.GetEnvironmentVariable("DEBUGHUB_ENABLED") != "1")
+            {
+                return;
+            }
+
+            var sessionId = Environment.GetEnvironmentVariable("DEBUGHUB_SESSION");
+            if (string.IsNullOrWhiteSpace(sessionId))
+            {
+                return;
+            }
+
+            var endpoint = Environment.GetEnvironmentVariable("DEBUGHUB_ENDPOINT");
+            if (string.IsNullOrWhiteSpace(endpoint))
+            {
+                return;
+            }
+
+            var level = "info";
+            string? hypothesisId = null;
+            string? loc = null;
+            object? tags = null;
+
+            if (meta != null)
+            {
+                if (meta.TryGetValue("level", out var levelObj) && levelObj is string levelStr && IsAllowedLevel(levelStr))
+                {
+                    level = levelStr;
+                }
+
+                if (meta.TryGetValue("hypothesisId", out var hypothesisObj) && hypothesisObj is string h)
+                {
+                    hypothesisId = h;
+                }
+
+                if (meta.TryGetValue("loc", out var locObj) && locObj is string l)
+                {
+                    loc = l;
+                }
+
+                if (meta.TryGetValue("tags", out var tagsObj))
+                {
+                    tags = tagsObj;
+                }
+            }
+
+            var payloadObject = new Dictionary<string, object?>
+            {
+                ["ts"] = DateTime.UtcNow.ToString("o"),
+                ["sessionId"] = sessionId,
+                ["label"] = label,
+                ["data"] = data,
+                ["hypothesisId"] = hypothesisId,
+                ["loc"] = loc,
+                ["level"] = level,
+                ["tags"] = tags,
+                ["runtime"] = "csharp"
+            };
+
+            var payload = JsonSerializer.Serialize(payloadObject);
+            var target = endpoint.TrimEnd('/') + "/event";
+
+            using var content = new StringContent(payload, Encoding.UTF8, "application/json");
+            Client.PostAsync(target, content).GetAwaiter().GetResult();
+        }
+        catch
+        {
+            // Never throw from helper
+        }
+    }
+
+    public static void DebugProbeEvent(string label, object? data = null, Dictionary<string, object?>? meta = null)
+    {
+        Probe(label, data, meta);
+    }
+
+    private static bool IsAllowedLevel(string level)
+    {
+        return level == "info" || level == "warn" || level == "error";
+    }
+}

package/dist/vendor/1.0.0/go/debug_probe.go

@@ -0,0 +1,81 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+type DebugProbeMeta struct {
+	HypothesisID *string            `json:"hypothesisId"`
+	Loc          *string            `json:"loc"`
+	Level        string             `json:"level"`
+	Tags         map[string]string  `json:"tags"`
+}
+
+func DebugProbe(label string, data interface{}, meta *DebugProbeMeta) {
+	defer func() {
+		_ = recover()
+	}()
+
+	if os.Getenv("DEBUGHUB_ENABLED") != "1" {
+		return
+	}
+
+	sessionID := os.Getenv("DEBUGHUB_SESSION")
+	if sessionID == "" {
+		return
+	}
+
+	endpoint := os.Getenv("DEBUGHUB_ENDPOINT")
+	if endpoint == "" {
+		return
+	}
+
+	level := "info"
+	var hypothesisID *string
+	var loc *string
+	var tags map[string]string
+	if meta != nil {
+		if meta.Level == "info" || meta.Level == "warn" || meta.Level == "error" {
+			level = meta.Level
+		}
+		hypothesisID = meta.HypothesisID
+		loc = meta.Loc
+		tags = meta.Tags
+	}
+
+	event := map[string]interface{}{
+		"ts":           time.Now().UTC().Format(time.RFC3339Nano),
+		"sessionId":    sessionID,
+		"label":        label,
+		"data":         data,
+		"hypothesisId": hypothesisID,
+		"loc":          loc,
+		"level":        level,
+		"tags":         tags,
+		"runtime":      "go",
+	}
+
+	payload, err := json.Marshal(event)
+	if err != nil {
+		return
+	}
+
+	target := strings.TrimRight(endpoint, "/") + "/event"
+	req, err := http.NewRequest(http.MethodPost, target, bytes.NewReader(payload))
+	if err != nil {
+		return
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	client := &http.Client{Timeout: 2 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return
+	}
+	defer resp.Body.Close()
+}

package/dist/vendor/1.0.0/http/EVENT_CONTRACT.md

@@ -0,0 +1,54 @@
+# DebugHub HTTP Event Contract
+
+This contract defines the minimum behavior all runtime helpers must follow.
+
+## Environment Variables
+
+- `DEBUGHUB_ENABLED`: must be exactly `1` to emit events.
+- `DEBUGHUB_SESSION`: required non-empty session id.
+- `DEBUGHUB_ENDPOINT`: required base endpoint (for example `http://127.0.0.1:7777`).
+
+If any required value is missing or invalid, helpers must no-op.
+
+## Transport
+
+- Method: `POST`
+- URL: `{DEBUGHUB_ENDPOINT}/event` (append `/event` after trimming any trailing slash)
+- Content-Type: `application/json`
+- Delivery mode: best-effort, fire-and-forget behavior from the application perspective
+- Failure handling: helper must never throw into host application code
+
+## Payload Schema
+
+Required keys:
+
+- `ts`: string
+- `sessionId`: string
+- `label`: string
+- `data`: any JSON value or `null`
+- `hypothesisId`: string or `null`
+- `loc`: string or `null`
+- `level`: one of `info`, `warn`, `error`
+- `tags`: object or `null`
+- `runtime`: string
+
+Defaults:
+
+- `data`: `null`
+- `hypothesisId`: `null`
+- `loc`: `null`
+- `level`: `info`
+- `tags`: `null`
+
+## Runtime Field Values
+
+Helpers should use a stable runtime name:
+
+- `node`
+- `browser`
+- `java`
+- `python`
+- `rust`
+- `php`
+- `go`
+- `csharp`

package/dist/vendor/1.0.0/http/event.example.json

@@ -0,0 +1,13 @@
+{
+  "ts": "2026-01-01T00:00:00.000Z",
+  "sessionId": "example-session",
+  "label": "example_label",
+  "data": {
+    "key": "value"
+  },
+  "hypothesisId": null,
+  "loc": null,
+  "level": "info",
+  "tags": null,
+  "runtime": "python"
+}

package/dist/vendor/1.0.0/java/DebugProbe.java

@@ -0,0 +1,114 @@
+package debughub;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Map;
+
+public final class DebugProbe {
+
+    private static final HttpClient client = HttpClient.newBuilder()
+            .connectTimeout(Duration.ofSeconds(2))
+            .build();
+
+    public static void probe(String label, Object data, Map<String, String> meta) {
+        sendEvent(label, data, meta);
+    }
+
+    public static void probe(String label) {
+        sendEvent(label, null, null);
+    }
+
+    public static void debugProbe(String label, Object data, Map<String, String> meta) {
+        sendEvent(label, data, meta);
+    }
+
+    public static void debugProbe(String label) {
+        sendEvent(label, null, null);
+    }
+
+    private static void sendEvent(String label, Object data, Map<String, String> meta) {
+        try {
+            String isEnabled = System.getenv("DEBUGHUB_ENABLED");
+            String sessionId = System.getenv("DEBUGHUB_SESSION");
+
+            if (!"1".equals(isEnabled) || sessionId == null || sessionId.isEmpty()) {
+                return;
+            }
+
+            String endpoint = System.getenv("DEBUGHUB_ENDPOINT");
+            if (endpoint == null || endpoint.isEmpty()) {
+                return;
+            }
+
+            String level = "info";
+            String hypothesisId = null;
+            String loc = null;
+            String tagsJson = null;
+            if (meta != null) {
+                if (meta.get("level") != null && !meta.get("level").isEmpty()) {
+                    level = meta.get("level");
+                }
+                hypothesisId = meta.get("hypothesisId");
+                loc = meta.get("loc");
+                tagsJson = meta.get("tags");
+            }
+
+            StringBuilder json = new StringBuilder();
+            json.append("{");
+            json.append("\"ts\":\"").append(escapeJson(Instant.now().toString())).append("\",");
+            json.append("\"sessionId\":\"").append(escapeJson(sessionId)).append("\",");
+            json.append("\"label\":\"").append(escapeJson(label)).append("\",");
+            if (data == null) {
+                json.append("\"data\":null,");
+            } else {
+                json.append("\"data\":\"").append(escapeJson(data.toString())).append("\",");
+            }
+            json.append("\"hypothesisId\":").append(asJsonStringOrNull(hypothesisId)).append(",");
+            json.append("\"loc\":").append(asJsonStringOrNull(loc)).append(",");
+            json.append("\"level\":\"").append(escapeJson(level)).append("\",");
+            if (tagsJson == null || tagsJson.isEmpty()) {
+                json.append("\"tags\":null,");
+            } else {
+                json.append("\"tags\":").append(tagsJson).append(",");
+            }
+            json.append("\"runtime\":\"java\",");
+            json.append("\"thread\":\"").append(escapeJson(Thread.currentThread().getName())).append("\"");
+            json.append("}");
+
+            String targetUrl = endpoint.endsWith("/") ? endpoint + "event" : endpoint + "/event";
+
+            HttpRequest request = HttpRequest.newBuilder()
+                    .uri(URI.create(targetUrl))
+                    .header("Content-Type", "application/json")
+                    .timeout(Duration.ofSeconds(2))
+                    .POST(HttpRequest.BodyPublishers.ofString(json.toString()))
+                    .build();
+
+            client.send(request, HttpResponse.BodyHandlers.discarding());
+        } catch (Exception e) {
+            // Never throw from helper
+        }
+    }
+
+    private static String asJsonStringOrNull(String value) {
+        if (value == null) {
+            return "null";
+        }
+        return "\"" + escapeJson(value) + "\"";
+    }
+
+    private static String escapeJson(String input) {
+        if (input == null) return "";
+        return input.replace("\\", "\\\\")
+                    .replace("\"", "\\\"")
+                    .replace("\b", "\\b")
+                    .replace("\f", "\\f")
+                    .replace("\n", "\\n")
+                    .replace("\r", "\\r")
+                    .replace("\t", "\\t");
+    }
+}