@lambdacurry/arbor 0.11.6 → 0.12.0

package/README.md

@@ -42,7 +42,7 @@ This prints a URL + short code to relay to the human, who approves it in their l
 
 ## Output contract (agent-friendly)
 
-Every command takes `--json` to emit a stable `{ ok, data | error, meta }` envelope on stdout (with structured error codes and agent-mode exit codes); advisory/human text goes to stderr. `--quiet` (auto under `--json` or a pipe) silences the advisory stream. `--fields a,b,list:N` projects a result; `--limit`/`--cursor` paginate list commands.
+Every command takes `--json` to emit a stable `{ ok, data | error, meta }` envelope on stdout (with structured error codes and agent-mode exit codes); advisory/human text goes to stderr. A failure envelope adds the server's granular `reason` — `validation.missing_field`, `limit.exceeded`, `conflict.state`, … — beside the coarse `code`, optionally with `field`, `limit`, `retryable`, and `phase` (AD-237). `--quiet` (auto under `--json` or a pipe) silences the advisory stream. `--fields a,b,list:N` projects a result; `--limit`/`--cursor` paginate list commands.
 
 ```bash
 arbor inbox --json --limit 20

package/dist/arbor.js

@@ -31,6 +31,18 @@ var CONTRIBUTION_TYPES = [
   "decision"
 ];
 var STAMP_FACETS = ["quality", "impact", "fit", "originality"];
+// ../core/src/errors/contract.ts
+var ERROR_REASONS = new Set([
+  "validation.missing_field",
+  "validation.invalid_value",
+  "authorization.denied",
+  "resource.not_found",
+  "conflict.state",
+  "limit.exceeded",
+  "provider.timeout",
+  "provider.failure",
+  "internal"
+]);
 // ../../node_modules/.pnpm/drizzle-orm@0.38.4_@cloudflare+workers-types@4.20260529.1_@prisma+client@5.22.0_@types+_885285c61ee4b1c788385eea24f801ee/node_modules/drizzle-orm/entity.js
 var entityKind = Symbol.for("drizzle:entityKind");
 var hasOwnEntityKind = Symbol.for("drizzle:hasOwnEntityKind");
@@ -17600,13 +17612,37 @@ function codeForError(err) {
   }
   return "INTERNAL";
 }
+function parseErrorDetails(value) {
+  if (!value || typeof value !== "object")
+    return;
+  const raw = value;
+  if (typeof raw.reason !== "string" || raw.reason === "")
+    return;
+  const details = { reason: raw.reason };
+  if (typeof raw.field === "string")
+    details.field = raw.field;
+  if (typeof raw.limit === "number")
+    details.limit = raw.limit;
+  if (typeof raw.retryable === "boolean")
+    details.retryable = raw.retryable;
+  if (typeof raw.phase === "string")
+    details.phase = raw.phase;
+  return details;
+}
+function detailsForError(err) {
+  if (!err || typeof err !== "object" || !("details" in err))
+    return;
+  return parseErrorDetails(err.details);
+}
 
 class ApiError extends Error {
   status;
+  details;
   code;
-  constructor(message, status) {
+  constructor(message, status, details) {
     super(message);
     this.status = status;
+    this.details = details;
     this.name = "ApiError";
     this.code = codeForStatus(status);
   }
@@ -17614,9 +17650,11 @@ class ApiError extends Error {
 
 class UsageError extends Error {
   code = "VALIDATION";
-  constructor(message) {
+  details;
+  constructor(message, details) {
     super(message);
     this.name = "UsageError";
+    this.details = details ?? { reason: "validation.invalid_value" };
   }
 }
 
@@ -17642,6 +17680,7 @@ function detectSource(env = process.env) {
 // src/client.ts
 class NotLoggedInError extends Error {
   code = "UNAUTHORIZED";
+  details = { reason: "authorization.denied" };
   constructor() {
     super("Not logged in. Run: arbor login");
     this.name = "NotLoggedInError";
@@ -17676,7 +17715,7 @@ var httpExecutor = {
     }
     const body = await res.json().catch(() => ({}));
     if (!res.ok || !body.success)
-      throw new ApiError(body.error ?? `request failed (${res.status})`, res.status);
+      throw new ApiError(body.error ?? `request failed (${res.status})`, res.status, parseErrorDetails(body.errorDetails));
     return body.data;
   }
 };
@@ -17707,7 +17746,10 @@ function stringFlag(value, name) {
   if (v === undefined)
     return;
   if (v === true)
-    throw new UsageError(`--${name} expects a value`);
+    throw new UsageError(`--${name} expects a value`, {
+      reason: "validation.missing_field",
+      field: name
+    });
   return String(v);
 }
 function resolveOutput(flags, opts) {
@@ -17761,7 +17803,7 @@ function emitError(err, action, ctx) {
   if (ctx.json) {
     const envelope = {
       ok: false,
-      error: { code, message },
+      error: { code, message, ...detailsForError(err) },
       meta: { action, requestId: randomUUID() }
     };
     process.stdout.write(`${JSON.stringify(envelope)}
@@ -17875,18 +17917,27 @@ function buildInput(inputSchema, flags, command) {
     if (raw === undefined) {
       if (spec.required) {
         const positional = primary && primary.field === spec.field && command ? ` — or pass it as the argument: arbor ${command} <${primary.field}>` : "";
-        throw new UsageError(`missing required flag: --${spec.flag}${positional}`);
+        throw new UsageError(`missing required flag: --${spec.flag}${positional}`, {
+          reason: "validation.missing_field",
+          field: spec.field
+        });
       }
       continue;
     }
     if (spec.kind !== "boolean" && raw === true) {
-      throw new UsageError(`--${spec.flag} expects a value`);
+      throw new UsageError(`--${spec.flag} expects a value`, {
+        reason: "validation.missing_field",
+        field: spec.field
+      });
     }
     switch (spec.kind) {
       case "number": {
         const n = Number(lastValue(raw));
         if (Number.isNaN(n))
-          throw new UsageError(`--${spec.flag} expects a number, got: ${String(lastValue(raw))}`);
+          throw new UsageError(`--${spec.flag} expects a number, got: ${String(lastValue(raw))}`, {
+            reason: "validation.invalid_value",
+            field: spec.field
+          });
         input[spec.field] = n;
         break;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/arbor",
-  "version": "0.11.6",
+  "version": "0.12.0",
   "description": "The Arbor CLI — a shared workspace for people and agents. The human + headless-agent write path over Arbor's guarded operation surface.",
   "keywords": [
     "agents",