hivenet 0.4.1 → 0.6.0

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,83 @@ 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',
+});
+```
+
+Failed a task after real effort? File it structured — these reports become the
+project's eval suite, so word the task so a stranger could re-run it:
+
+```sh
+npx hivenet --to acme --category cli --task "export 2k-row dataset as CSV" \
+  --expected "CSV with all rows" --actual "times out at 30s, no partial file" \
+  --attempts 3 "acme export cannot complete large exports"
+```
+
+Attach screenshots, logs or recordings (up to 10 files, 20 MiB each). Each `--describe`
+explains the file before it:
+
+```sh
+npx hivenet --to acme --category ux \
+  --attach ./screen.png --describe "The checkout button is hidden at 390px width." \
+  --attach ./trace.log \
+  "The checkout button disappears on mobile"
+```
+
+The SDK takes the same files as an array:
+
+```ts
+import { sendFeedback } from 'hivenet';
+
+await sendFeedback({
+  to: 'my-project',
+  feedback: 'Export reports success but downloads an empty file.',
+  attachments: [
+    { path: './screen.png', description: 'The success message after exporting 12 rows.' },
+    './network.log',
+  ],
+});
+```
+
+If files can't be uploaded (network, server busy, a server without file storage), the report
+is still sent — or queued — without them, and the output names them so you can add them
+later with `--resume <thread> --attach <path>`. A file the server rejects stops the send.
+After a text-only report the CLI suggests that same command (`attach_hint` with `--json`),
+since a screenshot or log often says more than the text.
+
+Structured reports can come from one JSON object, with the same fields as the SDK:
+
+```sh
+npx hivenet --input report.json --json    # attachment paths are relative to report.json
+cat report.json | npx hivenet --input - --json
+```
+
+Invalid input exits 1 with the fields to fix (`--json`: `code`, `error`, `issues`, `hint`);
+nothing is sent. Owners attach files to a record with `HIVENET_SECRET_KEY`:
+`npx hivenet attach issue <id> --attach ./reproduction.webm`.
+
+Responses may carry `guidance` (the team's reply to your thread) and `ask` — a
+question from the team with a ready-to-run `--answer <id>` command. Answering is
+optional and must be grounded in what you actually did; never guess.
+
 - 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-AK23JXBN.js

@@ -0,0 +1,32 @@
+import {
+  FeedbackError,
+  attachmentDescriptionSchema
+} from "./chunk-DNR6HNJD.js";
+
+// src/attachment-flags.ts
+function attachmentFlags() {
+  const files = [];
+  return {
+    "--attach": (path) => {
+      files.push({ path });
+      return files;
+    },
+    "--describe": (value) => {
+      const file = files.at(-1);
+      if (!file) throw new FeedbackError("--describe must follow the --attach it describes.");
+      if (file.description !== void 0)
+        throw new FeedbackError("Use one --describe per attached file.");
+      const parsed = attachmentDescriptionSchema.safeParse(value);
+      if (!parsed.success)
+        throw new FeedbackError(
+          `Invalid --describe: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`
+        );
+      file.description = parsed.data;
+      return parsed.data;
+    }
+  };
+}
+
+export {
+  attachmentFlags
+};