hivenet 0.4.1 → 0.6.0

package/dist/doctor-EA2GJRUS.js

@@ -0,0 +1,210 @@
+import {
+  FeedbackError,
+  PROTOCOL_VERSION,
+  WELL_KNOWN_PATH,
+  __toESM,
+  generateThreadId,
+  parseDsn,
+  postEvent,
+  registryUrl,
+  require_arg,
+  validateDescriptor,
+  validateFeedbackEvent
+} from "./chunk-DNR6HNJD.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
+};