hivenet 0.4.1 → 0.4.2

package/README.md

@@ -1,6 +1,7 @@
 # hivenet
 
-The support channel for AI agents. When an agent (or human) hits friction in a product's
+The support channel for AI agents. The same package provides both the `npx hivenet`
+CLI and an embeddable library. When an agent (or human) hits friction in a product's
 CLI, docs, SDK, or MCP server, this submits a structured, context-rich report straight to
 the maintainers — harness + session auto-detected, threaded, offline-safe.
 
@@ -9,13 +10,28 @@ npx hivenet --to acme --category cli --subject "acme deploy" \
   "acme deploy --json prints a spinner to stdout, corrupting the JSON output"
 ```
 
+```sh
+npm install hivenet
+```
+
+```ts
+import { sendFeedback } from 'hivenet';
+
+await sendFeedback({
+  feedback: 'acme deploy --json corrupts stdout',
+  to: 'acme',
+  category: 'cli',
+  subject: 'acme deploy --json',
+});
+```
+
 - Never prompts, never blocks; queues locally when offline (`--flush` retries).
 - `DO_NOT_TRACK=1` strips all auto-detected context; feedback still delivers anonymously.
 - `--json` machine output · `--dry-run` shows the exact event before anything is sent.
 - Destinations: `--to <slug|domain>`, `--dsn`, `HIVENET_DSN`, or feedback.config.json.
 
-Vendors: claim a slug and get paste-ready snippets at
-https://hivenet.app — or self-host with
-[@hivenet/server](https://www.npmjs.com/package/@hivenet/server).
+Vendors: claim a slug and get paste-ready snippets at https://hivenet.app.
+The reference self-hosted ingest implementation remains available in the
+[Hivenet repository](https://github.com/zvadaadam/hivenet/tree/master/packages/server).
 
 Docs: https://github.com/zvadaadam/hivenet

package/dist/{chunk-K4DIOYVH.js → chunk-WWPF6V2Y.js}

@@ -15161,7 +15161,14 @@ var FEEDBACK_CATEGORIES = [
   "ux",
   "other"
 ];
-var EVENT_STATUSES = ["new", "seen", "in_progress", "resolved", "wont_fix", "spam"];
+var EVENT_STATUSES = [
+  "new",
+  "seen",
+  "in_progress",
+  "resolved",
+  "wont_fix",
+  "spam"
+];
 var ISSUE_STATUSES = ["open", "in_progress", "resolved", "wont_fix", "spam"];
 var VENDOR_CATEGORY_PATTERN = /^x-[a-z0-9][a-z0-9-]{0,38}$/;
 var categorySchema = external_exports.union([
@@ -15212,7 +15219,10 @@ var feedbackContextSchema = external_exports.object({
   /** Only populated via vendor identity paths (signed grants / pass-through). */
   user: userContextSchema.optional()
 });
-var metadataSchema = external_exports.record(external_exports.string().min(1).max(40), external_exports.union([external_exports.string().max(200), external_exports.number().finite(), external_exports.boolean()])).refine((value) => Object.keys(value).length <= 20, { message: "at most 20 metadata keys" });
+var metadataSchema = external_exports.record(
+  external_exports.string().min(1).max(40),
+  external_exports.union([external_exports.string().max(200), external_exports.number().finite(), external_exports.boolean()])
+).refine((value) => Object.keys(value).length <= 20, { message: "at most 20 metadata keys" });
 var feedbackEventSchema = external_exports.object({
   v: external_exports.literal(PROTOCOL_VERSION),
   /** Tenant slug or domain this feedback is addressed to. Optional when the write key implies it. */
@@ -15286,6 +15296,10 @@ function validateIngestResponse(input) {
   return result.success ? { ok: true, data: result.data } : { ok: false, errors: formatIssues(result.error) };
 }
 
+// ../core/dist/index.js
+import { readFileSync } from "fs";
+import path2 from "path";
+
 // ../../node_modules/.pnpm/agent-cli-detector@0.1.5/node_modules/agent-cli-detector/dist/index.js
 import { execFileSync } from "child_process";
 import path from "path";
@@ -15580,8 +15594,6 @@ function sessionIdProperties(agent, env) {
 
 // ../core/dist/index.js
 var import_ci_info = __toESM(require_ci_info(), 1);
-import { readFileSync } from "fs";
-import path2 from "path";
 
 // ../../node_modules/.pnpm/sandbox-cli-detector@0.2.0/node_modules/sandbox-cli-detector/dist/chunk-HZH3SATY.js
 var defaultSandboxes = [
@@ -15656,13 +15668,14 @@ import path32 from "path";
 import { appendFileSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 import path4 from "path";
 import { randomBytes } from "crypto";
+import { createRequire } from "module";
 var DSN_ENV_VAR = "HIVENET_DSN";
 var REGISTRY_ENV_VAR = "HIVENET_REGISTRY";
 var HOME_ENV_VAR = "HIVENET_HOME";
 var NO_TELEMETRY_ENV_VAR = "HIVENET_NO_TELEMETRY";
 function feedbackHomeDir(env = process.env) {
   const override = env[HOME_ENV_VAR];
-  return override && override.trim() ? override : path3.join(homedir(), ".hivenet");
+  return override?.trim() ? override : path3.join(homedir(), ".hivenet");
 }
 function isTelemetryDisabled(extraOptOutEnvVars = [], env = process.env) {
   const vars = ["DO_NOT_TRACK", NO_TELEMETRY_ENV_VAR, ...extraOptOutEnvVars];
@@ -16044,14 +16057,114 @@ async function flushOutbox(options = {}) {
   }
   return { delivered, remaining: failures.length };
 }
+async function resolveApiOrigin(options) {
+  if (!options.to && !options.dsn) {
+    return new URL(DEFAULT_REGISTRY_URL).origin;
+  }
+  const destination = await resolveDestination({
+    ...options.to !== void 0 ? { to: options.to } : {},
+    ...options.dsn !== void 0 ? { dsn: options.dsn } : {},
+    ...options.env ? { env: options.env } : {},
+    ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
+  });
+  return new URL(destination.endpoint).origin;
+}
+function ownerApi(options) {
+  const origin = (options.apiOrigin ?? new URL(DEFAULT_REGISTRY_URL).origin).replace(/\/$/, "");
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const timeoutMs = options.timeoutMs ?? 15e3;
+  async function request(path5, init) {
+    let response;
+    try {
+      response = await fetchImpl(`${origin}${path5}`, {
+        ...init,
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: {
+          authorization: `Bearer ${options.secretKey}`,
+          ...init?.body ? { "content-type": "application/json" } : {},
+          ...init?.headers
+        }
+      });
+    } catch (error51) {
+      throw new FeedbackError(
+        `Could not reach ${origin} (${error51 instanceof Error ? error51.message : String(error51)}).`
+      );
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      body = void 0;
+    }
+    if (!response.ok) {
+      const errors = body?.errors;
+      throw new FeedbackError(
+        Array.isArray(errors) ? errors.map(String).join("; ") : `Request failed (${response.status}).`
+      );
+    }
+    return body;
+  }
+  return {
+    async listFeedback(filters = {}) {
+      const params = new URLSearchParams();
+      if (filters.status) params.set("status", filters.status);
+      if (filters.category) params.set("category", filters.category);
+      if (filters.thread) params.set("thread", filters.thread);
+      if (filters.since) params.set("since", filters.since);
+      if (filters.limit) params.set("limit", String(filters.limit));
+      const query = params.toString();
+      return request(`/v1/events${query ? `?${query}` : ""}`);
+    },
+    async getFeedback(id) {
+      return request(`/v1/events/${encodeURIComponent(id)}`);
+    },
+    async setFeedbackStatus(id, status, note) {
+      return request(`/v1/events/${encodeURIComponent(id)}`, {
+        method: "PATCH",
+        body: JSON.stringify({ status, ...note !== void 0 ? { note } : {} })
+      });
+    },
+    async listIssues(filters = {}) {
+      const params = new URLSearchParams();
+      if (filters.status) params.set("status", filters.status);
+      if (filters.since) params.set("since", filters.since);
+      if (filters.limit) params.set("limit", String(filters.limit));
+      const query = params.toString();
+      return request(`/v1/issues${query ? `?${query}` : ""}`);
+    },
+    async getIssue(id) {
+      return request(`/v1/issues/${encodeURIComponent(id)}`);
+    },
+    async setIssueStatus(id, status, note) {
+      return request(`/v1/issues/${encodeURIComponent(id)}`, {
+        method: "PATCH",
+        body: JSON.stringify({ status, ...note !== void 0 ? { note } : {} })
+      });
+    },
+    /** Attach an external link (Slack message, Linear/GitHub issue, PR) to evt_… or iss_…. */
+    async addLink(id, url2, label) {
+      const path5 = id.startsWith("iss_") ? `/v1/issues/${id}` : `/v1/events/${id}`;
+      return request(path5, {
+        method: "PATCH",
+        body: JSON.stringify({ addLink: { url: url2, ...label !== void 0 ? { label } : {} } })
+      });
+    }
+  };
+}
 function mintIdempotencyKey() {
   return randomBytes(16).toString("hex");
 }
 var DEFAULT_TIMEOUT_MS = 15e3;
 var DEFAULT_CLIENT_NAME = "hivenet";
-var DEFAULT_CLIENT_VERSION = "0.1.0";
+var DEFAULT_CLIENT_VERSION = (() => {
+  try {
+    return createRequire(import.meta.url)("../package.json").version ?? "0";
+  } catch {
+    return "0";
+  }
+})();
 function generateThreadId() {
-  return randomBytes(6).toString("hex");
+  return randomBytes(16).toString("hex");
 }
 function resolveThreadId(resume) {
   if (resume !== void 0 && THREAD_ID_PATTERN.test(resume)) {
@@ -16150,113 +16263,27 @@ async function sendFeedback(options) {
     resumed: thread.resumed
   };
 }
-async function resolveApiOrigin(options) {
-  if (!options.to && !options.dsn) {
-    return new URL(DEFAULT_REGISTRY_URL).origin;
-  }
-  const destination = await resolveDestination({
-    ...options.to !== void 0 ? { to: options.to } : {},
-    ...options.dsn !== void 0 ? { dsn: options.dsn } : {},
-    ...options.env ? { env: options.env } : {},
-    ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
-  });
-  return new URL(destination.endpoint).origin;
-}
-function ownerApi(options) {
-  const origin = (options.apiOrigin ?? new URL(DEFAULT_REGISTRY_URL).origin).replace(/\/$/, "");
-  const fetchImpl = options.fetchImpl ?? fetch;
-  const timeoutMs = options.timeoutMs ?? 15e3;
-  async function request(path5, init) {
-    let response;
-    try {
-      response = await fetchImpl(`${origin}${path5}`, {
-        ...init,
-        signal: AbortSignal.timeout(timeoutMs),
-        headers: {
-          authorization: `Bearer ${options.secretKey}`,
-          ...init?.body ? { "content-type": "application/json" } : {},
-          ...init?.headers
-        }
-      });
-    } catch (error51) {
-      throw new FeedbackError(
-        `Could not reach ${origin} (${error51 instanceof Error ? error51.message : String(error51)}).`
-      );
-    }
-    let body;
-    try {
-      body = await response.json();
-    } catch {
-      body = void 0;
-    }
-    if (!response.ok) {
-      const errors = body?.errors;
-      throw new FeedbackError(
-        Array.isArray(errors) ? errors.map(String).join("; ") : `Request failed (${response.status}).`
-      );
-    }
-    return body;
-  }
-  return {
-    async listFeedback(filters = {}) {
-      const params = new URLSearchParams();
-      if (filters.status) params.set("status", filters.status);
-      if (filters.category) params.set("category", filters.category);
-      if (filters.thread) params.set("thread", filters.thread);
-      if (filters.since) params.set("since", filters.since);
-      if (filters.limit) params.set("limit", String(filters.limit));
-      const query = params.toString();
-      return request(`/v1/events${query ? `?${query}` : ""}`);
-    },
-    async getFeedback(id) {
-      return request(`/v1/events/${encodeURIComponent(id)}`);
-    },
-    async setFeedbackStatus(id, status, note) {
-      return request(`/v1/events/${encodeURIComponent(id)}`, {
-        method: "PATCH",
-        body: JSON.stringify({ status, ...note !== void 0 ? { note } : {} })
-      });
-    },
-    async listIssues(filters = {}) {
-      const params = new URLSearchParams();
-      if (filters.status) params.set("status", filters.status);
-      if (filters.since) params.set("since", filters.since);
-      if (filters.limit) params.set("limit", String(filters.limit));
-      const query = params.toString();
-      return request(`/v1/issues${query ? `?${query}` : ""}`);
-    },
-    async getIssue(id) {
-      return request(`/v1/issues/${encodeURIComponent(id)}`);
-    },
-    async setIssueStatus(id, status, note) {
-      return request(`/v1/issues/${encodeURIComponent(id)}`, {
-        method: "PATCH",
-        body: JSON.stringify({ status, ...note !== void 0 ? { note } : {} })
-      });
-    },
-    /** Attach an external link (Slack message, Linear/GitHub issue, PR) to evt_… or iss_…. */
-    async addLink(id, url2, label) {
-      const path5 = id.startsWith("iss_") ? `/v1/issues/${id}` : `/v1/events/${id}`;
-      return request(path5, {
-        method: "PATCH",
-        body: JSON.stringify({ addLink: { url: url2, ...label !== void 0 ? { label } : {} } })
-      });
-    }
-  };
-}
 
 export {
   __toESM,
+  PROTOCOL_VERSION,
   MAX_FEEDBACK_LENGTH,
+  WELL_KNOWN_PATH,
   FEEDBACK_CATEGORIES,
   EVENT_STATUSES,
   ISSUE_STATUSES,
   sentimentSchema,
   authorSchema,
+  validateFeedbackEvent,
+  validateDescriptor,
   FeedbackError,
+  parseDsn,
+  registryUrl,
+  postEvent,
   flushOutbox,
-  sendFeedback,
   resolveApiOrigin,
   ownerApi,
+  generateThreadId,
+  sendFeedback,
   require_arg
 };

package/dist/cli.js

@@ -9,16 +9,21 @@ import {
   require_arg,
   sendFeedback,
   sentimentSchema
-} from "./chunk-K4DIOYVH.js";
+} from "./chunk-WWPF6V2Y.js";
 
 // src/cli.ts
 var import_arg = __toESM(require_arg(), 1);
 var CLI_NAME = "hivenet";
-var CLI_VERSION = "0.4.0";
+var CLI_VERSION = "0.4.2";
 async function main() {
   const subcommand = process.argv[2];
+  if (subcommand === "doctor") {
+    const { runDoctor } = await import("./doctor-CVWF7J3P.js");
+    await runDoctor(process.argv.slice(3), CLI_VERSION);
+    return;
+  }
   if (subcommand === "inbox" || subcommand === "triage" || subcommand === "issues" || subcommand === "issue") {
-    const owner = await import("./owner-LAL5WKKW.js");
+    const owner = await import("./owner-N2MSYLV7.js");
     const run = {
       inbox: owner.runInbox,
       triage: owner.runTriage,
@@ -39,6 +44,11 @@ async function main() {
       "--sentiment": String,
       "--author": String,
       "--meta": [String],
+      "--task": String,
+      "--expected": String,
+      "--actual": String,
+      "--mistake": String,
+      "--attempts": Number,
       "--resume": String,
       "--json": Boolean,
       "--dry-run": Boolean,
@@ -74,12 +84,14 @@ Usage: npx ${CLI_NAME} --to <slug|domain> "<specific, actionable feedback>"`
   const sentiment = parseEnumFlag("--sentiment", args["--sentiment"], sentimentSchema);
   const author = parseEnumFlag("--author", args["--author"], authorSchema);
   const metadata = parseMetaFlags(args["--meta"]);
+  const evalReport = buildEvalReport(args);
   const options = {
     feedback,
     ...args["--to"] !== void 0 ? { to: args["--to"] } : {},
     ...args["--dsn"] !== void 0 ? { dsn: args["--dsn"] } : {},
-    ...args["--category"] !== void 0 ? { category: args["--category"].toLowerCase() } : {},
+    ...args["--category"] !== void 0 ? { category: args["--category"].toLowerCase() } : evalReport ? { category: "eval" } : {},
     ...args["--subject"] !== void 0 ? { subject: args["--subject"] } : {},
+    ...evalReport ? { eval: evalReport } : {},
     ...sentiment !== void 0 ? { sentiment } : {},
     ...author !== void 0 ? { author } : {},
     ...metadata ? { metadata } : {},
@@ -102,7 +114,12 @@ Usage: npx ${CLI_NAME} --to <slug|domain> "<specific, actionable feedback>"`
           delivered: true,
           ...result.destination.to ? { to: result.destination.to } : {},
           ...result.response
-        } : { delivered: false, queued: result.queued, error: result.error, thread: result.event.thread.id },
+        } : {
+          delivered: false,
+          queued: result.queued,
+          error: result.error,
+          thread: result.event.thread.id
+        },
         null,
         2
       )
@@ -148,7 +165,28 @@ async function buildDryRun(options) {
     });
   });
   const result = await sendFeedback({ ...options, fetchImpl: capture, outbox: false });
-  return { destination: { endpoint: result.destination.endpoint, to: result.destination.to }, event: captured };
+  return {
+    destination: { endpoint: result.destination.endpoint, to: result.destination.to },
+    event: captured
+  };
+}
+function buildEvalReport(args) {
+  const task = args["--task"];
+  const details = {
+    ...args["--expected"] !== void 0 ? { expected: args["--expected"] } : {},
+    ...args["--actual"] !== void 0 ? { actual: args["--actual"] } : {},
+    ...args["--mistake"] !== void 0 ? { mistake: args["--mistake"] } : {},
+    ...args["--attempts"] !== void 0 ? { attempts: args["--attempts"] } : {}
+  };
+  if (task === void 0) {
+    if (Object.keys(details).length > 0) {
+      throw new FeedbackError(
+        '--expected/--actual/--mistake/--attempts describe a failed task; add --task "<what you were trying to do>".'
+      );
+    }
+    return void 0;
+  }
+  return { task, ...details };
 }
 function parseMetaFlags(pairs) {
   if (!pairs || pairs.length === 0) {
@@ -171,6 +209,7 @@ function printHelp() {
   console.log(`
   Usage
     $ npx ${CLI_NAME} --to <slug|domain> [options] "<feedback>"
+    $ npx ${CLI_NAME} doctor --to <slug|domain>  (vendors: verify your integration end-to-end)
     $ npx ${CLI_NAME} inbox --help     (owners: list + filter your project's feedback)
     $ npx ${CLI_NAME} triage --help    (owners: set status/notes/links on an event)
     $ npx ${CLI_NAME} issues --help    (owners: clustered issues, regression counts)
@@ -186,6 +225,11 @@ function printHelp() {
     --category, -c <cat>     ${FEEDBACK_CATEGORIES.join(" | ")} | x-<vendor>
     --subject, -s <subject>  Exact item the feedback is about (see table below)
     --meta <key=value>       Vendor-defined enrichment, repeatable (e.g. --meta sdk_version=1.2.3)
+    --task <text>            Failed task you are reporting (sets --category eval when omitted)
+    --expected <text>        What should have happened (with --task)
+    --actual <text>          What actually happened (with --task)
+    --mistake <text>         The specific mistake made (with --task)
+    --attempts <n>           How many attempts before giving up (with --task)
     --sentiment <s>          positive | negative | neutral
     --author <a>             agent | human | hybrid (auto-detected when omitted)
     --resume <threadId>      Continue an earlier feedback thread
@@ -204,7 +248,7 @@ function printHelp() {
     cli      Full command, e.g. acme deploy --json
     api      Endpoint or SDK method
     model    Model behavior involved
-    eval     Capability the failed task involves (include --category eval details)
+    eval     Capability the failed task involves (add --task, --expected, --actual, \u2026)
     ux       Flow or surface name
     other    Concise topic, or leave empty
 

package/dist/doctor-CVWF7J3P.js

@@ -0,0 +1,210 @@
+import {
+  FeedbackError,
+  PROTOCOL_VERSION,
+  WELL_KNOWN_PATH,
+  __toESM,
+  generateThreadId,
+  parseDsn,
+  postEvent,
+  registryUrl,
+  require_arg,
+  validateDescriptor,
+  validateFeedbackEvent
+} from "./chunk-WWPF6V2Y.js";
+
+// src/doctor.ts
+var import_arg = __toESM(require_arg(), 1);
+var FETCH_TIMEOUT_MS = 1e4;
+async function runDoctor(argv, cliVersion) {
+  const args = (0, import_arg.default)(
+    {
+      "--help": Boolean,
+      "--to": String,
+      "--dsn": String,
+      "--smoke": Boolean,
+      "--json": Boolean,
+      "-h": "--help",
+      "-t": "--to"
+    },
+    { argv, permissive: false }
+  );
+  if (args["--help"] || !args["--to"] && !args["--dsn"]) {
+    printDoctorHelp();
+    return;
+  }
+  const checks = [];
+  let endpoint;
+  let writeKey;
+  let slug;
+  let descriptor;
+  if (args["--dsn"]) {
+    try {
+      const destination = parseDsn(args["--dsn"]);
+      endpoint = destination.endpoint;
+      writeKey = destination.writeKey;
+      slug = destination.to;
+      checks.push({ name: "dsn", ok: true, detail: `endpoint ${endpoint}` });
+    } catch (error) {
+      checks.push({ name: "dsn", ok: false, detail: messageOf(error) });
+    }
+  } else {
+    const to = args["--to"].trim();
+    const descriptorUrl = to.includes(".") ? `https://${to}${WELL_KNOWN_PATH}` : `${registryUrl()}/v1/registry/${to}`;
+    const result = await checkDescriptor(descriptorUrl);
+    checks.push(result.check);
+    descriptor = result.descriptor;
+    endpoint = descriptor?.endpoint;
+    writeKey = descriptor?.writeKey;
+    slug = descriptor?.slug ?? (to.includes(".") ? void 0 : to);
+  }
+  if (endpoint) {
+    checks.push(checkEndpointUrl(endpoint));
+    checks.push(
+      writeKey ? {
+        name: "write key",
+        ok: true,
+        detail: `${writeKey.slice(0, 12)}\u2026 (write-only, safe to publish)`
+      } : {
+        name: "write key",
+        ok: true,
+        detail: "none published \u2014 the ingest must accept keyless submissions for this project"
+      }
+    );
+    const categories = descriptor?.categories ? Object.keys(descriptor.categories) : [];
+    checks.push({
+      name: "categories",
+      ok: true,
+      detail: categories.length > 0 ? categories.join(", ") : "none published \u2014 agents will invent free-text subjects"
+    });
+    if (args["--smoke"]) {
+      checks.push(await sendSmokeEvent(endpoint, writeKey, slug, cliVersion));
+    }
+  }
+  const healthy = checks.every((check) => check.ok);
+  if (args["--json"]) {
+    console.log(JSON.stringify({ ok: healthy, checks }, null, 2));
+  } else {
+    for (const check of checks) {
+      console.log(`${check.ok ? "\u2713" : "\u2717"} ${check.name}: ${check.detail}`);
+    }
+    if (healthy && !args["--smoke"]) {
+      console.log("  Add --smoke to send one disposable event through the real pipe.");
+    }
+  }
+  if (!healthy) {
+    process.exitCode = 1;
+  }
+}
+async function checkDescriptor(url) {
+  const name = url.includes(WELL_KNOWN_PATH) ? "well-known descriptor" : "registry entry";
+  let response;
+  try {
+    response = await fetch(url, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { accept: "application/json" }
+    });
+  } catch (error) {
+    return { check: { name, ok: false, detail: `could not reach ${url} (${messageOf(error)})` } };
+  }
+  if (!response.ok) {
+    return { check: { name, ok: false, detail: `${url} responded ${response.status}` } };
+  }
+  const contentType = response.headers.get("content-type") ?? "unknown";
+  const body = await response.text();
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    const spaHint = /<[a-z!]/i.test(body.trimStart()) ? " \u2014 looks like an HTML page (an SPA catch-all route?); serve the JSON file at exactly this path" : "";
+    return {
+      check: { name, ok: false, detail: `${url} returned ${contentType}, not JSON${spaHint}` }
+    };
+  }
+  const validated = validateDescriptor(parsed);
+  if (!validated.ok) {
+    return {
+      check: {
+        name,
+        ok: false,
+        detail: `${url} is not a valid descriptor: ${validated.errors.join("; ")}`
+      }
+    };
+  }
+  return {
+    check: { name, ok: true, detail: `${url} (v${validated.data.v}, ${validated.data.name})` },
+    descriptor: validated.data
+  };
+}
+function checkEndpointUrl(endpoint) {
+  try {
+    const url = new URL(endpoint);
+    if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+      return { name: "endpoint", ok: false, detail: `${endpoint} is not https` };
+    }
+    return { name: "endpoint", ok: true, detail: endpoint };
+  } catch {
+    return { name: "endpoint", ok: false, detail: `"${endpoint}" is not a URL` };
+  }
+}
+async function sendSmokeEvent(endpoint, writeKey, slug, cliVersion) {
+  const candidate = {
+    v: PROTOCOL_VERSION,
+    ...slug ? { to: slug } : {},
+    feedback: "hivenet doctor smoke event \u2014 verifying this integration; safe to mark as spam.",
+    category: "other",
+    subject: "hivenet doctor",
+    thread: { id: generateThreadId() },
+    client: { name: "hivenet-doctor", version: cliVersion },
+    consent: { telemetry: false }
+  };
+  const validated = validateFeedbackEvent(candidate);
+  if (!validated.ok) {
+    return { name: "smoke event", ok: false, detail: validated.errors.join("; ") };
+  }
+  const result = await postEvent({
+    endpoint,
+    ...writeKey ? { writeKey } : {},
+    event: validated.data,
+    timeoutMs: FETCH_TIMEOUT_MS
+  });
+  switch (result.kind) {
+    case "accepted":
+      return {
+        name: "smoke event",
+        ok: true,
+        detail: `delivered (${result.response.id})${result.response.guidance ? " \u2014 guidance configured \u2713" : ""}`
+      };
+    case "rejected":
+      return { name: "smoke event", ok: false, detail: `rejected: ${result.errors.join("; ")}` };
+    case "unreachable":
+      return { name: "smoke event", ok: false, detail: `endpoint unreachable: ${result.error}` };
+  }
+}
+function messageOf(error) {
+  if (error instanceof FeedbackError || error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function printDoctorHelp() {
+  console.log(`
+  Usage
+    $ npx hivenet doctor --to <slug|domain> [--smoke] [--json]
+    $ npx hivenet doctor --dsn <url> [--smoke] [--json]
+
+  Verify a hivenet integration end-to-end, the way an agent would resolve it:
+  registry entry or well-known descriptor (content type, schema), endpoint,
+  write key, and published categories. Ignores HIVENET_DSN and
+  feedback.config.json so a healthy local setup can't mask a broken public one.
+
+  Options
+    --to, -t <slug|domain>   Registered slug, or a domain serving ${WELL_KNOWN_PATH}
+    --dsn <url>              Explicit DSN: https://hv_pub_KEY@host/slug
+    --smoke                  Also send one disposable, clearly-labeled event
+    --json                   Machine-readable result
+    --help, -h               This help
+`);
+}
+export {
+  runDoctor
+};