hivenet 0.4.1 → 0.6.0

package/dist/cli.js

@@ -1,33 +1,208 @@
 #!/usr/bin/env node
+import {
+  attachmentFlags
+} from "./chunk-AK23JXBN.js";
 import {
   FEEDBACK_CATEGORIES,
   FeedbackError,
+  MAX_ATTACHMENTS,
   MAX_FEEDBACK_LENGTH,
   __toESM,
+  attachmentDescriptionSchema,
   authorSchema,
+  evalReportSchema,
+  external_exports,
+  feedbackEventSchema,
   flushOutbox,
+  prepareFeedback,
   require_arg,
   sendFeedback,
   sentimentSchema
-} from "./chunk-K4DIOYVH.js";
+} from "./chunk-DNR6HNJD.js";
 
 // src/cli.ts
 var import_arg = __toESM(require_arg(), 1);
+
+// src/feedback-input.ts
+import { constants } from "fs";
+import { open } from "fs/promises";
+import path from "path";
+var MAX_INPUT_BYTES = 64 * 1024;
+var inputSchema = feedbackEventSchema.pick({
+  feedback: true,
+  to: true,
+  category: true,
+  subject: true,
+  sentiment: true,
+  author: true,
+  metadata: true,
+  idempotencyKey: true
+}).extend({
+  feedback: feedbackEventSchema.shape.feedback.trim().min(1),
+  to: feedbackEventSchema.shape.to.unwrap().trim().min(1).optional(),
+  dsn: external_exports.url().optional(),
+  eval: evalReportSchema.strict().optional(),
+  resume: feedbackEventSchema.shape.thread.shape.id.optional(),
+  question: feedbackEventSchema.shape.question.unwrap().min(1).optional(),
+  attachments: external_exports.array(
+    external_exports.preprocess(
+      (value) => typeof value === "string" ? { path: value } : value,
+      external_exports.strictObject({
+        path: external_exports.string().min(1),
+        description: attachmentDescriptionSchema.optional()
+      })
+    )
+  ).max(MAX_ATTACHMENTS).optional()
+}).strict().refine((input) => !(input.to && input.dsn), {
+  path: ["dsn"],
+  message: "Choose either to or dsn, not both."
+});
+var FeedbackInputError = class extends FeedbackError {
+  constructor(message, code, issues = []) {
+    super(message);
+    this.code = code;
+    this.issues = issues;
+  }
+  code;
+  issues;
+  hint = "Fix the input using the error details, then rerun the command with corrected JSON.";
+};
+async function readFeedbackInput(source) {
+  let bytes;
+  if (source === "-") {
+    if (process.stdin.isTTY)
+      throw new FeedbackInputError(
+        "--input - needs piped JSON. Use --input report.json or pipe one JSON object to stdin.",
+        "input_read_error"
+      );
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+      const buffer = Buffer.from(chunk);
+      size += buffer.length;
+      if (size > MAX_INPUT_BYTES) throw inputTooLarge();
+      chunks.push(buffer);
+    }
+    bytes = Buffer.concat(chunks);
+  } else {
+    let handle;
+    try {
+      handle = await open(source, constants.O_RDONLY | constants.O_NONBLOCK);
+      const stat = await handle.stat();
+      if (!stat.isFile())
+        throw new FeedbackInputError("--input requires a regular JSON file.", "input_read_error");
+      if (stat.size > MAX_INPUT_BYTES) throw inputTooLarge();
+      const buffer = Buffer.alloc(MAX_INPUT_BYTES + 1);
+      let size = 0;
+      while (size < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, size, buffer.length - size);
+        if (!bytesRead) break;
+        size += bytesRead;
+      }
+      if (size > MAX_INPUT_BYTES) throw inputTooLarge();
+      bytes = buffer.subarray(0, size);
+    } catch (error) {
+      if (error instanceof FeedbackInputError) throw error;
+      throw new FeedbackInputError(
+        `Cannot read --input file "${source}". Choose an existing readable JSON file.`,
+        "input_read_error"
+      );
+    } finally {
+      await handle?.close();
+    }
+  }
+  try {
+    return {
+      raw: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+      baseDir: source === "-" ? process.cwd() : path.dirname(path.resolve(source))
+    };
+  } catch {
+    throw new FeedbackInputError("JSON input must be UTF-8 text.", "invalid_json");
+  }
+}
+function parseFeedbackInput(document) {
+  let value;
+  try {
+    value = JSON.parse(document.raw);
+  } catch (error) {
+    const location = error instanceof Error ? /\(line \d+ column \d+\)/.exec(error.message)?.[0] : "";
+    throw new FeedbackInputError(
+      `Invalid JSON${location ? ` ${location}` : ""}. Supply one JSON object with double-quoted keys and no trailing commas.`,
+      "invalid_json"
+    );
+  }
+  const parsed = inputSchema.safeParse(value);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.flatMap((issue) => {
+      if (issue.code !== "unrecognized_keys")
+        return [{ path: fieldPath(issue.path), message: issue.message }];
+      const fields = issue.path[0] === "attachments" ? ["path", "description"] : issue.path[0] === "eval" ? Object.keys(evalReportSchema.shape) : Object.keys(inputSchema.shape);
+      return issue.keys.map((key) => ({
+        path: fieldPath([...issue.path, key]),
+        message: `Unknown field. Use: ${fields.join(", ")}.`
+      }));
+    });
+    throw new FeedbackInputError(
+      `Invalid feedback input:
+${issues.map((issue) => `  ${issue.path}: ${issue.message}`).join("\n")}`,
+      "invalid_input",
+      issues
+    );
+  }
+  const { attachments, ...input } = parsed.data;
+  return {
+    ...input,
+    ...attachments ? {
+      attachments: attachments.map((file) => ({
+        ...file,
+        path: path.resolve(document.baseDir, file.path)
+      }))
+    } : {}
+  };
+}
+function fieldPath(segments) {
+  return segments.map(
+    (segment, index) => typeof segment === "number" ? `[${segment}]` : `${index ? "." : ""}${String(segment)}`
+  ).join("") || "input";
+}
+function inputTooLarge() {
+  return new FeedbackInputError(
+    "JSON input exceeds 64 KiB. Attach large files by path instead of embedding their contents.",
+    "input_too_large"
+  );
+}
+
+// src/cli.ts
 var CLI_NAME = "hivenet";
-var CLI_VERSION = "0.4.0";
+var CLI_VERSION = "0.6.0";
+var rawArgs = process.argv.slice(2);
+var flagArgs = rawArgs.slice(0, rawArgs.includes("--") ? rawArgs.indexOf("--") : void 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");
+  if (subcommand === "doctor") {
+    const { runDoctor } = await import("./doctor-EA2GJRUS.js");
+    await runDoctor(process.argv.slice(3), CLI_VERSION);
+    return;
+  }
+  if (subcommand === "inbox" || subcommand === "triage" || subcommand === "issues" || subcommand === "issue" || subcommand === "questions" || subcommand === "ask" || subcommand === "question" || subcommand === "evals" || subcommand === "eval" || subcommand === "promote" || subcommand === "attach") {
+    const owner = await import("./owner-ZWROA7AU.js");
     const run = {
       inbox: owner.runInbox,
       triage: owner.runTriage,
       issues: owner.runIssues,
-      issue: owner.runIssue
+      issue: owner.runIssue,
+      questions: owner.runQuestions,
+      ask: owner.runAsk,
+      question: owner.runQuestion,
+      evals: owner.runEvals,
+      eval: owner.runEval,
+      promote: owner.runPromote,
+      attach: owner.runAttach
     }[subcommand];
     await run(process.argv.slice(3));
     return;
   }
+  let inputSeen = false;
   const args = (0, import_arg.default)(
     {
       "--help": Boolean,
@@ -39,7 +214,21 @@ async function main() {
       "--sentiment": String,
       "--author": String,
       "--meta": [String],
+      "--task": String,
+      "--expected": String,
+      "--actual": String,
+      "--mistake": String,
+      "--attempts": Number,
       "--resume": String,
+      "--answer": String,
+      "--idempotency-key": String,
+      "--input": (value) => {
+        if (inputSeen)
+          throw new FeedbackInputError("Use --input once for one JSON report.", "input_conflict");
+        inputSeen = true;
+        return value;
+      },
+      ...attachmentFlags(),
       "--json": Boolean,
       "--dry-run": Boolean,
       "--flush": Boolean,
@@ -60,49 +249,94 @@ async function main() {
     return;
   }
   if (args["--flush"]) {
+    if (args["--input"] !== void 0)
+      throw new FeedbackInputError("--input cannot be combined with --flush.", "input_conflict");
     const result2 = await flushOutbox();
-    console.log(`Outbox: delivered ${result2.delivered}, remaining ${result2.remaining}.`);
+    console.log(
+      args["--json"] ? JSON.stringify(result2) : `Outbox: delivered ${result2.delivered}, remaining ${result2.remaining}.`
+    );
     return;
   }
-  const feedback = args._.join(" ").trim();
-  if (!feedback) {
-    throw new FeedbackError(
-      `A feedback message is required.
+  let options;
+  if (args["--input"] !== void 0) {
+    const allowed = /* @__PURE__ */ new Set(["_", "--input", "--json", "--dry-run", "--to", "--dsn"]);
+    const conflicts = Object.keys(args).filter((flag) => !allowed.has(flag));
+    if (args._.length || conflicts.length)
+      throw new FeedbackInputError(
+        `--input cannot be combined with positional feedback or report flags${conflicts.length ? ` (${conflicts.join(", ")})` : ""}. Put report fields in the JSON object.`,
+        "input_conflict"
+      );
+    const inputDocument = await readFeedbackInput(args["--input"]);
+    options = parseFeedbackInput(inputDocument);
+    if ((args["--to"] !== void 0 || args["--dsn"] !== void 0) && (options.to !== void 0 || options.dsn !== void 0))
+      throw new FeedbackInputError(
+        "Set the destination in JSON or with --to/--dsn, not both.",
+        "input_conflict"
+      );
+    if (args["--to"] !== void 0 && args["--dsn"] !== void 0)
+      throw new FeedbackInputError("Choose either --to or --dsn.", "input_conflict");
+    if (args["--to"] !== void 0) options.to = args["--to"];
+    if (args["--dsn"] !== void 0) options.dsn = args["--dsn"];
+  } else {
+    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 evalReport = buildEvalReport(args);
+    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"] } : {},
+      ...evalReport ? { eval: evalReport } : {},
+      ...sentiment !== void 0 ? { sentiment } : {},
+      ...author !== void 0 ? { author } : {},
+      ...metadata ? { metadata } : {},
+      ...args["--resume"] !== void 0 ? { resume: args["--resume"] } : {},
+      ...args["--answer"] !== void 0 ? { question: args["--answer"] } : {},
+      ...args["--idempotency-key"] !== void 0 ? { idempotencyKey: args["--idempotency-key"] } : {},
+      ...args["--attach"] ? { attachments: args["--attach"] } : {}
+    };
   }
-  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(() => {
-  });
+  options.clientName = CLI_NAME;
+  options.clientVersion = CLI_VERSION;
   if (args["--dry-run"]) {
     const preview = await buildDryRun(options);
     console.log(JSON.stringify(preview, null, 2));
     return;
   }
+  flushOutbox({ timeoutMs: 3e3 }).catch(() => {
+  });
   const result = await sendFeedback(options);
+  if (!result.delivered && !result.queued) process.exitCode = 1;
+  const resume = (result.delivered ? result.response.resume : void 0) ?? `npx ${CLI_NAME}${result.destination.to ? ` --to ${result.destination.to}` : ""} --resume ${result.event.thread.id}`;
+  const answer = result.event.question;
+  const attach = `${resume}${answer ? ` --answer ${answer}` : ""} --attach <path> "<what it shows>"`;
+  const attachHint = result.filesNotAttached ? `Add them later: ${attach}` : result.delivered && !result.event.attachments?.length && !answer ? `Have a screenshot or log that shows this? Attach it: ${attach}` : void 0;
   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 },
+        {
+          ...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
+          },
+          ...result.filesNotAttached ? { filesNotAttached: result.filesNotAttached } : {},
+          ...attachHint ? { attach_hint: attachHint } : {}
+        },
         null,
         2
       )
@@ -112,17 +346,32 @@ Usage: npx ${CLI_NAME} --to <slug|domain> "<specific, actionable feedback>"`
   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}`;
+    if (result.event.attachments?.length)
+      console.log(`  Attached ${result.event.attachments.length} file(s).`);
     console.log(`  Continue this thread: ${resume}`);
+    if (attachHint && !result.filesNotAttached) console.log(`  ${attachHint}`);
     if (result.response.guidance) {
       console.log(`  From ${toLabel}: ${result.response.guidance}`);
     }
+    if (result.response.ask) {
+      console.log(`  ? ${toLabel} asks: ${result.response.ask.prompt}`);
+      console.log(`    Answer (only if you can ground it): ${result.response.ask.command}`);
+      for (const file of result.response.ask.attachments ?? [])
+        console.log(
+          `    File: ${file.filename} (${file.mediaType}, ${file.size} bytes) ${file.url} (expires ${file.expiresAt})${file.description ? `
+      Description: ${file.description}` : ""}`
+        );
+    }
   } 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;
+  }
+  if (result.filesNotAttached) {
+    const { files, reason } = result.filesNotAttached;
+    console.log(`  ! Not attached (${reason}): ${files.join(", ")}`);
+    console.log(`    ${attachHint}`);
   }
 }
 function parseEnumFlag(flag, value, schema) {
@@ -136,19 +385,33 @@ function parseEnumFlag(flag, value, schema) {
   return parsed.data;
 }
 async function buildDryRun(options) {
-  let captured;
-  const capture = (async (url, init) => {
-    if (init?.method !== "POST") {
-      return fetch(url, init);
+  const result = await prepareFeedback(options);
+  return {
+    destination: { endpoint: result.destination.endpoint, to: result.destination.to },
+    event: result.event,
+    files: result.files.map(({ manifest, description }) => ({
+      ...manifest,
+      ...description ? { description } : {}
+    }))
+  };
+}
+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>".'
+      );
     }
-    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 };
+    return void 0;
+  }
+  return { task, ...details };
 }
 function parseMetaFlags(pairs) {
   if (!pairs || pairs.length === 0) {
@@ -158,8 +421,7 @@ function parseMetaFlags(pairs) {
   for (const pair of pairs) {
     const separator = pair.indexOf("=");
     if (separator < 1) {
-      console.error(`--meta expects key=value, got "${pair}".`);
-      process.exit(2);
+      throw new FeedbackError(`--meta expects key=value, got "${pair}".`);
     }
     const key = pair.slice(0, separator);
     const raw = pair.slice(separator + 1);
@@ -171,13 +433,19 @@ function printHelp() {
   console.log(`
   Usage
     $ npx ${CLI_NAME} --to <slug|domain> [options] "<feedback>"
+    $ npx ${CLI_NAME} --input report.json [--json] [--dry-run]
+    $ cat report.json | npx ${CLI_NAME} --input - --json
+    $ 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} questions --help (owners: ask your agent users, read the answers)
+    $ npx ${CLI_NAME} evals --help     (owners: curate failed tasks into a replayable corpus)
     $ 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)
+    $ npx ${CLI_NAME} attach --help    (owners: add files to a record)
 
   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.
+  to its maintainers. Works for AI agents and humans; never opens an interactive prompt.
   Feedback can be up to ${MAX_FEEDBACK_LENGTH.toLocaleString("en-US")} characters. Only submit specific, actionable reports.
 
   Options
@@ -186,15 +454,34 @@ 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 (pair with the surface --category it failed on)
+    --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
-    --json                   Machine-readable result
+    --answer <questionId>    Answer a question a previous response asked (only if grounded)
+    --idempotency-key <key>  Stable retry key (8\u201364 letters, digits, _ or -)
+    --input <file|->         Read one JSON report from a UTF-8 file or stdin (64 KiB maximum)
+    --json                   Machine-readable result or error; does not read JSON input
     --dry-run                Print the event and destination without sending
+    --attach <path>          Attach a local file (repeatable; 10 files, 20 MiB each)
+    --describe <text>        What the preceding --attach shows (optional, up to 1000 characters)
     --flush                  Retry locally queued (offline) feedback, then exit
     --version, -v            Version
     --help, -h               This help
 
+  JSON input (--input report.json, or --input - to read stdin)
+    { "to": "acme", "feedback": "Export failed",
+      "attachments": [{ "path": "./screen.png", "description": "The error after export." }] }
+    Fields: feedback, to or dsn, category, subject, sentiment, author, metadata,
+    eval { task, expected?, actual?, mistake?, attempts? }, resume, question, attachments,
+    idempotencyKey. Paths are relative to the JSON file (stdin: the current directory).
+    Don't combine --input with positional feedback or report flags. Invalid input exits 1
+    with the fields to fix; nothing is sent or saved.
+
   Subject by category
     tool     Exact tool name, e.g. acme_deploy
     skill    Exact skill name, e.g. eas-simulator
@@ -204,7 +491,6 @@ 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)
     ux       Flow or surface name
     other    Concise topic, or leave empty
 
@@ -220,10 +506,25 @@ function printHelp() {
 `);
 }
 main().catch((error) => {
-  if (error instanceof FeedbackError) {
-    console.error(error.message);
+  const message = error instanceof Error ? error.message : String(error);
+  if (flagArgs.includes("--json")) {
+    console.log(
+      JSON.stringify(
+        {
+          delivered: false,
+          queued: false,
+          code: error instanceof FeedbackInputError ? error.code : "feedback_error",
+          error: message,
+          ...error instanceof FeedbackInputError && error.issues.length ? { issues: error.issues } : {},
+          ...error instanceof FeedbackInputError ? { hint: error.hint } : {}
+        },
+        null,
+        2
+      )
+    );
   } else {
-    console.error(error instanceof Error ? error.message : String(error));
+    console.error(message);
+    if (error instanceof FeedbackInputError) console.error(error.hint);
   }
-  process.exit(1);
+  process.exitCode = 1;
 });