hivenet 0.4.0

package/dist/cli.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+import {
+  FEEDBACK_CATEGORIES,
+  FeedbackError,
+  MAX_FEEDBACK_LENGTH,
+  __toESM,
+  authorSchema,
+  flushOutbox,
+  require_arg,
+  sendFeedback,
+  sentimentSchema
+} from "./chunk-K4DIOYVH.js";
+
+// src/cli.ts
+var import_arg = __toESM(require_arg(), 1);
+var CLI_NAME = "hivenet";
+var CLI_VERSION = "0.4.0";
+async function main() {
+  const subcommand = process.argv[2];
+  if (subcommand === "inbox" || subcommand === "triage" || subcommand === "issues" || subcommand === "issue") {
+    const owner = await import("./owner-LAL5WKKW.js");
+    const run = {
+      inbox: owner.runInbox,
+      triage: owner.runTriage,
+      issues: owner.runIssues,
+      issue: owner.runIssue
+    }[subcommand];
+    await run(process.argv.slice(3));
+    return;
+  }
+  const args = (0, import_arg.default)(
+    {
+      "--help": Boolean,
+      "--version": Boolean,
+      "--to": String,
+      "--dsn": String,
+      "--category": String,
+      "--subject": String,
+      "--sentiment": String,
+      "--author": String,
+      "--meta": [String],
+      "--resume": String,
+      "--json": Boolean,
+      "--dry-run": Boolean,
+      "--flush": Boolean,
+      "-h": "--help",
+      "-v": "--version",
+      "-t": "--to",
+      "-c": "--category",
+      "-s": "--subject"
+    },
+    { argv: process.argv.slice(2), permissive: false }
+  );
+  if (args["--help"]) {
+    printHelp();
+    return;
+  }
+  if (args["--version"]) {
+    console.log(CLI_VERSION);
+    return;
+  }
+  if (args["--flush"]) {
+    const result2 = await flushOutbox();
+    console.log(`Outbox: delivered ${result2.delivered}, remaining ${result2.remaining}.`);
+    return;
+  }
+  const feedback = args._.join(" ").trim();
+  if (!feedback) {
+    throw new FeedbackError(
+      `A feedback message is required.
+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 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["--subject"] !== void 0 ? { subject: args["--subject"] } : {},
+    ...sentiment !== void 0 ? { sentiment } : {},
+    ...author !== void 0 ? { author } : {},
+    ...metadata ? { metadata } : {},
+    ...args["--resume"] !== void 0 ? { resume: args["--resume"] } : {},
+    clientName: CLI_NAME,
+    clientVersion: CLI_VERSION
+  };
+  flushOutbox({ timeoutMs: 3e3 }).catch(() => {
+  });
+  if (args["--dry-run"]) {
+    const preview = await buildDryRun(options);
+    console.log(JSON.stringify(preview, null, 2));
+    return;
+  }
+  const result = await sendFeedback(options);
+  if (args["--json"]) {
+    console.log(
+      JSON.stringify(
+        result.delivered ? {
+          delivered: true,
+          ...result.destination.to ? { to: result.destination.to } : {},
+          ...result.response
+        } : { delivered: false, queued: result.queued, error: result.error, thread: result.event.thread.id },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  const toLabel = result.destination.to ?? result.destination.endpoint;
+  if (result.delivered) {
+    console.log(`\u2713 Feedback sent to ${toLabel} (${result.response.id})`);
+    const resume = result.response.resume ?? `npx ${CLI_NAME}${result.destination.to ? ` --to ${result.destination.to}` : ""} --resume ${result.response.thread}`;
+    console.log(`  Continue this thread: ${resume}`);
+    if (result.response.guidance) {
+      console.log(`  From ${toLabel}: ${result.response.guidance}`);
+    }
+  } else if (result.queued) {
+    console.log(`\u25CB ${toLabel} is unreachable (${result.error}).`);
+    console.log(`  Your feedback was queued locally and will be sent on the next run.`);
+  } else {
+    console.log(`\u2717 Could not deliver feedback to ${toLabel}: ${result.error}`);
+    process.exitCode = 1;
+  }
+}
+function parseEnumFlag(flag, value, schema) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const parsed = schema.safeParse(value.toLowerCase());
+  if (!parsed.success) {
+    throw new FeedbackError(`Invalid ${flag} "${value}". Expected: ${schema.options.join(", ")}.`);
+  }
+  return parsed.data;
+}
+async function buildDryRun(options) {
+  let captured;
+  const capture = (async (url, init) => {
+    if (init?.method !== "POST") {
+      return fetch(url, init);
+    }
+    captured = JSON.parse(String(init.body));
+    return new Response(JSON.stringify({ id: "evt_dry_run", thread: "aaaaaaaaaaaa" }), {
+      status: 202,
+      headers: { "content-type": "application/json" }
+    });
+  });
+  const result = await sendFeedback({ ...options, fetchImpl: capture, outbox: false });
+  return { destination: { endpoint: result.destination.endpoint, to: result.destination.to }, event: captured };
+}
+function parseMetaFlags(pairs) {
+  if (!pairs || pairs.length === 0) {
+    return void 0;
+  }
+  const metadata = {};
+  for (const pair of pairs) {
+    const separator = pair.indexOf("=");
+    if (separator < 1) {
+      console.error(`--meta expects key=value, got "${pair}".`);
+      process.exit(2);
+    }
+    const key = pair.slice(0, separator);
+    const raw = pair.slice(separator + 1);
+    metadata[key] = raw === "true" ? true : raw === "false" ? false : raw !== "" && String(Number(raw)) === raw ? Number(raw) : raw;
+  }
+  return metadata;
+}
+function printHelp() {
+  console.log(`
+  Usage
+    $ npx ${CLI_NAME} --to <slug|domain> [options] "<feedback>"
+    $ 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)
+    $ npx ${CLI_NAME} issue --help     (owners: manage one issue; cascades to events)
+
+  Send feedback about an agentic system's surfaces (CLI, docs, MCP, skills, API)
+  to its maintainers. Works for AI agents and humans; never prompts, never blocks.
+  Feedback can be up to ${MAX_FEEDBACK_LENGTH.toLocaleString("en-US")} characters. Only submit specific, actionable reports.
+
+  Options
+    --to, -t <slug|domain>   Destination: registry slug (acme) or domain (acme.dev)
+    --dsn <url>              Explicit DSN: https://hv_pub_KEY@host/slug
+    --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)
+    --sentiment <s>          positive | negative | neutral
+    --author <a>             agent | human | hybrid (auto-detected when omitted)
+    --resume <threadId>      Continue an earlier feedback thread
+    --json                   Machine-readable result
+    --dry-run                Print the event and destination without sending
+    --flush                  Retry locally queued (offline) feedback, then exit
+    --version, -v            Version
+    --help, -h               This help
+
+  Subject by category
+    tool     Exact tool name, e.g. acme_deploy
+    skill    Exact skill name, e.g. eas-simulator
+    prompt   Prompt or template name
+    docs     Full documentation URL
+    mcp      Exact MCP tool or server name
+    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)
+    ux       Flow or surface name
+    other    Concise topic, or leave empty
+
+  Data collection
+    Submissions include best-effort environment context: agent harness + session ID,
+    sandbox, CI, OS/arch/node, and vendor-configured project/session metadata.
+    Set DO_NOT_TRACK=1 (or HIVENET_NO_TELEMETRY=1) to omit all of it \u2014
+    feedback is still delivered anonymously.
+
+  Destination resolution
+    --dsn \u2192 HIVENET_DSN \u2192 nearest feedback.config.json \u2192 --to slug (registry)
+    \u2192 --to domain (https://<domain>/.well-known/agent-feedback.json)
+`);
+}
+main().catch((error) => {
+  if (error instanceof FeedbackError) {
+    console.error(error.message);
+  } else {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+  process.exit(1);
+});

package/dist/owner-LAL5WKKW.js

@@ -0,0 +1,235 @@
+import {
+  EVENT_STATUSES,
+  FeedbackError,
+  ISSUE_STATUSES,
+  __toESM,
+  ownerApi,
+  require_arg,
+  resolveApiOrigin
+} from "./chunk-K4DIOYVH.js";
+
+// src/owner.ts
+var import_arg = __toESM(require_arg(), 1);
+var SECRET_ENV_VAR = "HIVENET_SECRET_KEY";
+var OWNER_FLAGS = {
+  "--to": String,
+  "--dsn": String,
+  "--api": String,
+  "--secret": String,
+  "--json": Boolean,
+  "--help": Boolean,
+  "-h": "--help"
+};
+async function buildApi(args) {
+  const secretKey = args["--secret"] ?? process.env[SECRET_ENV_VAR];
+  if (!secretKey || !secretKey.startsWith("hv_sec_")) {
+    throw new FeedbackError(
+      `An owner secret key is required (hv_sec_\u2026, from your project's Settings).
+Pass --secret <key> or set ${SECRET_ENV_VAR}.`
+    );
+  }
+  const apiOrigin = args["--api"] ?? await resolveApiOrigin({
+    ...args["--to"] !== void 0 ? { to: args["--to"] } : {},
+    ...args["--dsn"] !== void 0 ? { dsn: args["--dsn"] } : {}
+  });
+  return ownerApi({ secretKey, apiOrigin });
+}
+function statusIcon(status) {
+  return { new: "\u25CF", seen: "\u25D0", in_progress: "\u25D2", resolved: "\u2713", wont_fix: "\u2717", spam: "\u2298" }[status];
+}
+function printEvent(event, verbose = false) {
+  const subject = event.subject ? ` \xB7 ${event.subject}` : "";
+  console.log(
+    `${statusIcon(event.status)} ${event.id}  [${event.status}]  ${event.category}${subject}  (${event.agent_id ?? event.author ?? "unknown"}, ${event.received_at.slice(0, 16).replace("T", " ")})`
+  );
+  console.log(`    ${event.feedback}`);
+  if (event.triage_note) {
+    console.log(`    \u21B3 note: ${event.triage_note}`);
+  }
+  if (verbose) {
+    console.log(`    thread ${event.thread_id} \xB7 telemetry ${event.consent_telemetry ? "on" : "off"}`);
+  }
+}
+async function runInbox(argv) {
+  const args = (0, import_arg.default)(
+    { ...OWNER_FLAGS, "--status": String, "--category": String, "--thread": String, "--limit": Number },
+    { argv }
+  );
+  if (args["--help"]) {
+    console.log(`
+  Usage
+    $ npx hivenet inbox [--status new] [--category mcp] [--thread <id>] [--limit 50]
+
+  List feedback for your project (owners only). Auth: --secret <hv_sec_\u2026> or
+  ${SECRET_ENV_VAR}. Destination: --to <slug|domain>, --dsn, or --api <origin>
+  (defaults to the hosted API). Statuses: ${EVENT_STATUSES.join(" | ")}. --json for raw output.
+`);
+    return;
+  }
+  const status = args["--status"];
+  if (status && !EVENT_STATUSES.includes(status)) {
+    throw new FeedbackError(`Invalid --status "${status}". Expected: ${EVENT_STATUSES.join(", ")}.`);
+  }
+  const api = await buildApi(args);
+  const result = await api.listFeedback({
+    ...status ? { status } : {},
+    ...args["--category"] ? { category: args["--category"] } : {},
+    ...args["--thread"] ? { thread: args["--thread"] } : {},
+    ...args["--limit"] ? { limit: args["--limit"] } : {}
+  });
+  if (args["--json"]) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.events.length === 0) {
+    console.log(`No matching feedback for ${result.project}.`);
+    return;
+  }
+  console.log(`${result.events.length} event(s) for ${result.project}:
+`);
+  for (const event of result.events) {
+    printEvent(event);
+  }
+  console.log(`
+Triage: npx hivenet triage <eventId> --status <${EVENT_STATUSES.join("|")}> [--note "\u2026"]`);
+}
+async function runTriage(argv) {
+  const args = (0, import_arg.default)({ ...OWNER_FLAGS, "--status": String, "--note": String, "--link": String }, { argv });
+  if (args["--help"] || args._.length === 0) {
+    console.log(`
+  Usage
+    $ npx hivenet triage <eventId> [--status <status>] [--note "why"] [--link <url>]
+
+  Set triage status and/or attach an external link (Slack, Linear, GitHub, PR) to a
+  feedback event (owners only). Statuses: ${EVENT_STATUSES.join(" | ")}.
+  Auth: --secret <hv_sec_\u2026> or ${SECRET_ENV_VAR}. Destination: --to/--dsn/--api.
+`);
+    if (!args["--help"]) {
+      throw new FeedbackError("An event ID is required.");
+    }
+    return;
+  }
+  const status = args["--status"];
+  if (status && !EVENT_STATUSES.includes(status)) {
+    throw new FeedbackError(`Invalid --status. Expected: ${EVENT_STATUSES.join(", ")}.`);
+  }
+  if (!status && !args["--link"]) {
+    throw new FeedbackError("Provide --status and/or --link.");
+  }
+  const api = await buildApi(args);
+  const id = args._[0];
+  if (args["--link"]) {
+    await api.addLink(id, args["--link"]);
+  }
+  const event = status ? (await api.setFeedbackStatus(id, status, args["--note"] !== void 0 ? args["--note"] : void 0)).event : (await api.getFeedback(id)).event;
+  if (args["--json"]) {
+    console.log(JSON.stringify({ event }, null, 2));
+    return;
+  }
+  console.log("Updated:");
+  printEvent(event, true);
+  printLinks(event.links_json);
+}
+function printLinks(linksJson) {
+  try {
+    const links = JSON.parse(linksJson ?? "[]");
+    for (const link of links) {
+      console.log(`    \u21C4 ${link.kind}: ${link.url}`);
+    }
+  } catch {
+  }
+}
+function issueIcon(status) {
+  return { open: "\u25CF", in_progress: "\u25D2", resolved: "\u2713", wont_fix: "\u2717", spam: "\u2298" }[status];
+}
+function printIssue(issue) {
+  const regressed = issue.reopened_count > 0 ? `  \u21BB regressed \xD7${issue.reopened_count}` : "";
+  console.log(
+    `${issueIcon(issue.status)} ${issue.id}  [${issue.status}]  ${issue.title}  (${issue.event_count} event${issue.event_count === 1 ? "" : "s"}, last ${issue.last_seen.slice(0, 16).replace("T", " ")})${regressed}`
+  );
+  printLinks(issue.links_json);
+}
+async function runIssues(argv) {
+  const args = (0, import_arg.default)({ ...OWNER_FLAGS, "--status": String, "--limit": Number }, { argv });
+  if (args["--help"]) {
+    console.log(`
+  Usage
+    $ npx hivenet issues [--status open] [--limit 50]
+
+  List issues \u2014 feedback clustered by thread and (category, subject) fingerprint.
+  Statuses: ${ISSUE_STATUSES.join(" | ")}. Auth: --secret or ${SECRET_ENV_VAR}.
+  Manage one: npx hivenet issue <issueId> --status resolved --note "\u2026" --link <url>
+`);
+    return;
+  }
+  const status = args["--status"];
+  if (status && !ISSUE_STATUSES.includes(status)) {
+    throw new FeedbackError(`Invalid --status. Expected: ${ISSUE_STATUSES.join(", ")}.`);
+  }
+  const api = await buildApi(args);
+  const result = await api.listIssues({
+    ...status ? { status } : {},
+    ...args["--limit"] ? { limit: args["--limit"] } : {}
+  });
+  if (args["--json"]) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.issues.length === 0) {
+    console.log(`No matching issues for ${result.project}.`);
+    return;
+  }
+  console.log(`${result.issues.length} issue(s) for ${result.project}:
+`);
+  for (const issue of result.issues) {
+    printIssue(issue);
+  }
+}
+async function runIssue(argv) {
+  const args = (0, import_arg.default)({ ...OWNER_FLAGS, "--status": String, "--note": String, "--link": String }, { argv });
+  if (args["--help"] || args._.length === 0) {
+    console.log(`
+  Usage
+    $ npx hivenet issue <issueId>                         (show with events)
+    $ npx hivenet issue <issueId> --status resolved --note "\u2026" --link <url>
+
+  Statuses: ${ISSUE_STATUSES.join(" | ")}. Resolving cascades to member events; new
+  feedback on a resolved issue reopens it. Auth: --secret or ${SECRET_ENV_VAR}.
+`);
+    if (!args["--help"]) {
+      throw new FeedbackError("An issue ID is required.");
+    }
+    return;
+  }
+  const status = args["--status"];
+  if (status && !ISSUE_STATUSES.includes(status)) {
+    throw new FeedbackError(`Invalid --status. Expected: ${ISSUE_STATUSES.join(", ")}.`);
+  }
+  const api = await buildApi(args);
+  const id = args._[0];
+  if (args["--link"]) {
+    await api.addLink(id, args["--link"]);
+  }
+  if (status) {
+    await api.setIssueStatus(id, status, args["--note"] !== void 0 ? args["--note"] : void 0);
+  }
+  const { issue, events } = await api.getIssue(id);
+  if (args["--json"]) {
+    console.log(JSON.stringify({ issue, events }, null, 2));
+    return;
+  }
+  printIssue(issue);
+  if (issue.summary) {
+    console.log(`    ${issue.summary}`);
+  }
+  console.log("");
+  for (const event of events) {
+    printEvent(event);
+  }
+}
+export {
+  runInbox,
+  runIssue,
+  runIssues,
+  runTriage
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "hivenet",
+  "version": "0.4.0",
+  "description": "Submit feedback about any agentic system's tools, docs, CLI, or MCP server \u2014 from any AI agent or human",
+  "keywords": [
+    "agent",
+    "feedback",
+    "ai",
+    "cli",
+    "mcp",
+    "agent-experience"
+  ],
+  "license": "MIT",
+  "homepage": "https://hivenet.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zvadaadam/hivenet.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "hivenet": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@hivenet/core": "workspace:*",
+    "@hivenet/spec": "workspace:*",
+    "arg": "^5.0.2"
+  },
+  "engines": {
+    "node": ">=20.10.0"
+  }
+}