@haystackeditor/cli 0.15.19 → 0.15.21

package/dist/utils/pr-ref.js

@@ -0,0 +1,56 @@
+/**
+ * Shared PR-identifier parsing for every command that takes a PR ref.
+ *
+ * One grammar, one error message, one repo-inference path. This used to be
+ * duplicated per command, and the copies drifted: different "accepted formats"
+ * lists (none mentioned the `#123` form the regex accepted), and one copy let
+ * a raw git error escape where the others gave a friendly hint. Commands must
+ * import from here rather than reimplementing the grammar.
+ *
+ * Accepted formats, in the order they are tried:
+ *   https://github.com/owner/repo/pull/123   GitHub URL
+ *   owner/repo#123                           Fully qualified
+ *   123 or #123                              PR number (repo inferred from the `origin` remote)
+ */
+import { parseRemoteUrl } from './git.js';
+/** The accepted-formats block used in parse errors and help text. */
+export function acceptedPrRefFormats(commandName) {
+    return (`  haystack ${commandName} 123\n` +
+        `  haystack ${commandName} #123\n` +
+        `  haystack ${commandName} owner/repo#123\n` +
+        `  haystack ${commandName} https://github.com/owner/repo/pull/123`);
+}
+/**
+ * Parse a PR identifier. `commandName` is interpolated into error messages so
+ * the agent can copy a corrected invocation verbatim (e.g. "triage",
+ * "pr get", "traces list").
+ */
+export function parsePrRef(identifier, commandName) {
+    const urlMatch = identifier.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/);
+    if (urlMatch) {
+        return { owner: urlMatch[1], repo: urlMatch[2], prNumber: parseInt(urlMatch[3], 10) };
+    }
+    // owner/repo#123 — repo segment may not contain `/` (a stray extra segment
+    // used to silently become part of the repo name and 404 downstream).
+    const qualifiedMatch = identifier.match(/^([^/#\s]+)\/([^/#\s]+)#(\d+)$/);
+    if (qualifiedMatch) {
+        return { owner: qualifiedMatch[1], repo: qualifiedMatch[2], prNumber: parseInt(qualifiedMatch[3], 10) };
+    }
+    const numberMatch = identifier.match(/^#?(\d+)$/);
+    if (numberMatch) {
+        const prNumber = parseInt(numberMatch[1], 10);
+        try {
+            const remote = parseRemoteUrl('origin');
+            return { owner: remote.owner, repo: remote.repo, prNumber };
+        }
+        catch (err) {
+            throw new Error(`Cannot determine the repository for PR #${prNumber} ` +
+                `(${err instanceof Error ? err.message : String(err)}).\n` +
+                `Run from inside a checkout with an "origin" remote, or use the full format:\n` +
+                `  haystack ${commandName} owner/repo#${prNumber}`);
+        }
+    }
+    throw new Error(`Invalid PR identifier: "${identifier}"\n\n` +
+        `Accepted formats:\n${acceptedPrRefFormats(commandName)}\n\n` +
+        `See \`haystack ${commandName.split(' ')[0]} --help\` for details.`);
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.15.19",
+  "version": "0.15.21",
   "description": "Set up Haystack for your project — automated PR review, triage, and merge queue",
   "type": "module",
   "bin": {
-    "haystack": "./dist/index.js"
+    "haystack": "dist/index.js"
   },
   "scripts": {
     "build": "rm -rf dist && tsc && cp -r src/assets dist/assets",

package/schemas/action.v1.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/action.v1.json",
+  "title": "haystack <dismiss|mark-reviewed|undismiss|request-review|review> --json",
+  "description": "Shared envelope for every mutating command. Exactly one document on stdout; progress on stderr. status 'error' payloads accompany exit code 1.",
+  "type": "object",
+  "required": ["schema_version", "action", "status"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0.0" },
+    "action": { "type": "string", "enum": ["dismiss", "mark_reviewed", "undismiss", "request_review", "trigger_review", "clear_pending"] },
+    "status": { "type": "string", "enum": ["ok", "error"] },
+    "ref": { "type": ["string", "null"], "description": "owner/repo#number. Null on errors that happen before the ref resolves." },
+    "error": { "type": "string", "description": "Present only when status is 'error'. Actionable message including the remediation." },
+    "detail": { "type": "string", "description": "Human-readable statement of what changed." },
+    "head_sha": { "type": "string", "description": "dismiss/mark_reviewed: the head commit the override is tied to. A new commit invalidates the override." },
+    "reviewer": { "type": ["string", "null"], "description": "request_review: the GitHub user review was requested from, or null for the needs-assignment queue." },
+    "reviewer_request_failed": { "type": ["string", "null"], "description": "request_review: set when the label was applied but the specific-reviewer request failed (partial success)." },
+    "request_id": { "type": "string", "description": "trigger_review: the analysis run id." },
+    "run_status": { "type": "string", "enum": ["started", "already_processing", "completed", "superseded", "running"], "description": "trigger_review: state of the triggered run when the command returned." },
+    "next": { "type": ["string", "null"], "description": "Follow-up command to read results (e.g. `haystack triage <ref> --json`)." }
+  }
+}

package/schemas/error.v1.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/error.v1.json",
+  "title": "Generic --json error envelope",
+  "description": "Emitted on stdout (with exit code 1) when a read command invoked with --json fails before it can produce its own payload. Commands with richer contracts (submit, action) embed status:'error' in their own schemas instead.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "status", "error"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0.0" },
+    "status": { "type": "string", "const": "error" },
+    "error": { "type": "string", "description": "Actionable message including the remediation." }
+  }
+}

package/schemas/pr-status.v1.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/pr-status.v1.json",
+  "title": "haystack pr-status <ref> --json",
+  "description": "Which Haystack feed bucket a PR is in, and why. All state tokens are snake_case — the same vocabulary as `haystack triage --json` and `haystack pr get --json`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "ref", "bucket", "in_feed", "feed_priority", "reason", "analysis", "needs_human_review", "labels", "overrides", "author", "is_author", "is_open", "state_synced_at", "stale_warning"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0.0" },
+    "ref": { "type": "string", "description": "owner/repo#number" },
+    "bucket": {
+      "type": ["string", "null"],
+      "description": "Feed bucket in snake_case. Known values are enumerated below; new buckets may appear (always snake_case). Null when the PR is unclassified (closed or not yet analyzed).",
+      "examples": ["analyzing", "auto_fixing", "good_to_merge", "failed_when_merging", "issues", "needs_assignment", "needs_shepherding", "needs_fixing", "awaiting_review", "review_requested", "snoozed"]
+    },
+    "in_feed": { "type": ["boolean", "null"], "description": "Null when the PR is unclassified (e.g. closed)." },
+    "feed_priority": { "type": ["number", "null"] },
+    "reason": { "type": "string", "description": "Human-readable explanation of the classification." },
+    "analysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "verdict", "rating"],
+      "properties": {
+        "status": { "type": "string", "enum": ["pending", "in_queue", "ready", "error"] },
+        "verdict": {
+          "anyOf": [
+            { "type": "string", "enum": ["good_to_merge", "needs_review", "needs_input"] },
+            { "type": "null" }
+          ],
+          "description": "Null until analysis is ready."
+        },
+        "rating": {
+          "anyOf": [
+            { "type": "integer", "minimum": 1, "maximum": 5 },
+            { "type": "null" }
+          ]
+        }
+      }
+    },
+    "needs_human_review": { "type": ["boolean", "null"] },
+    "labels": { "type": "array", "items": { "type": "string" } },
+    "overrides": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["snoozed", "dismissed", "dismissed_agent_alerts", "dismissed_needs_assignment", "manually_good_to_merge"],
+      "properties": {
+        "snoozed": { "type": "boolean" },
+        "dismissed": { "type": "boolean" },
+        "dismissed_agent_alerts": { "type": "boolean" },
+        "dismissed_needs_assignment": { "type": "boolean" },
+        "manually_good_to_merge": { "type": "boolean" }
+      }
+    },
+    "author": { "type": ["string", "null"], "description": "Null when the server could not resolve PR metadata." },
+    "is_author": { "type": ["boolean", "null"] },
+    "is_open": { "type": ["boolean", "null"] },
+    "state_synced_at": { "type": ["string", "null"] },
+    "stale_warning": { "type": ["string", "null"] }
+  }
+}

package/schemas/pr.v1.json

@@ -2,32 +2,95 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://docs.haystackeditor.com/cli/schemas/pr.v1.json",
   "title": "haystack pr <ref> --json",
+  "deprecated": true,
+  "description": "HISTORICAL: superseded by pr.v2.json. The CLI no longer emits this shape; this file is retained immutably for consumers pinned to the v1 contract.",
   "type": "object",
-  "required": ["schema_version", "owner", "repo", "prNumber", "bucket", "state"],
+  "required": [
+    "schema_version",
+    "owner",
+    "repo",
+    "prNumber",
+    "bucket",
+    "state"
+  ],
   "properties": {
-    "schema_version": { "type": "string", "const": "1.0.0" },
-    "owner": { "type": "string" },
-    "repo": { "type": "string" },
-    "prNumber": { "type": "integer" },
-    "bucket": { "type": "string" },
-    "state": { "type": "string", "enum": ["open", "closed", "merged"] },
-    "title": { "type": "string" },
-    "headSha": { "type": "string" },
-    "haystackUrl": { "type": "string" },
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "owner": {
+      "type": "string"
+    },
+    "repo": {
+      "type": "string"
+    },
+    "prNumber": {
+      "type": "integer"
+    },
+    "bucket": {
+      "type": "string"
+    },
+    "state": {
+      "type": "string",
+      "enum": [
+        "open",
+        "closed",
+        "merged"
+      ]
+    },
+    "title": {
+      "type": "string"
+    },
+    "headSha": {
+      "type": "string"
+    },
+    "haystackUrl": {
+      "type": "string"
+    },
     "mergeQueue": {
       "type": "object",
       "properties": {
-        "state": { "type": "string", "enum": ["not-enrolled", "eligible", "grace", "queued", "merging", "merged", "blocked"] },
-        "graceEndsAt": { "type": ["string", "null"] },
-        "blockedReason": { "type": ["string", "null"] }
+        "state": {
+          "type": "string",
+          "enum": [
+            "not-enrolled",
+            "eligible",
+            "grace",
+            "queued",
+            "merging",
+            "merged",
+            "blocked"
+          ]
+        },
+        "graceEndsAt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "blockedReason": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       }
     },
     "lastTriage": {
-      "type": ["object", "null"],
+      "type": [
+        "object",
+        "null"
+      ],
       "properties": {
-        "rating": { "type": "integer" },
-        "completedAt": { "type": "string" },
-        "headSha": { "type": "string" }
+        "rating": {
+          "type": "integer"
+        },
+        "completedAt": {
+          "type": "string"
+        },
+        "headSha": {
+          "type": "string"
+        }
       }
     }
   }

package/schemas/setup.v1.json

@@ -2,20 +2,74 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://docs.haystackeditor.com/cli/schemas/setup.v1.json",
   "title": "haystack setup --json event stream",
-  "description": "NDJSON event stream. Each line is one event stamped with schema_version.",
+  "description": "NDJSON on stdout: each line is one event, stamped with schema_version. Human chrome goes to stderr. Replies are written to the CLI's stdin as one JSON object per line: questions are answered with {\"requestID\": \"<id>\", \"answers\": <bool | value[]>} or rejected with {\"requestID\": \"<id>\", \"reject\": true}; permissions are answered with {\"permissionID\": \"<id>\", \"response\": \"once\" | \"always\" | \"reject\"}. Pre-supplied answers (--answers file or flags) skip the matching question entirely.",
   "type": "object",
   "required": ["schema_version", "type"],
   "properties": {
-    "schema_version": { "type": "string", "const": "1.0.0" },
-    "type": {
-      "type": "string",
-      "enum": ["question", "permission", "log", "progress", "result"]
+    "schema_version": { "type": "string", "const": "1.0.0" }
+  },
+  "oneOf": [
+    {
+      "title": "question",
+      "description": "A decision the agent must answer on stdin, keyed by requestID.",
+      "properties": {
+        "schema_version": { "type": "string", "const": "1.0.0" },
+        "type": { "const": "question" },
+        "requestID": { "type": "string" },
+        "kind": { "type": "string", "enum": ["confirm", "multiselect"] },
+        "prompt": { "type": "string" },
+        "default": { "type": "boolean", "description": "confirm only" },
+        "options": {
+          "type": "array",
+          "description": "multiselect only",
+          "items": {
+            "type": "object",
+            "properties": {
+              "value": {},
+              "label": { "type": "string" },
+              "default": { "type": "boolean" }
+            }
+          }
+        }
+      },
+      "required": ["type", "requestID", "kind", "prompt"]
     },
-    "id": { "type": "string" },
-    "prompt": { "type": "string" },
-    "choices": { "type": "array" },
-    "level": { "type": "string", "enum": ["info", "warn", "error"] },
-    "message": { "type": "string" },
-    "result": { "type": "object" }
-  }
+    {
+      "title": "permission",
+      "description": "An out-of-band action (e.g. install the GitHub App at a URL). The CLI keeps polling for completion; reply on stdin keyed by permissionID to short-circuit ('once'/'always') or skip ('reject').",
+      "properties": {
+        "schema_version": { "type": "string", "const": "1.0.0" },
+        "type": { "const": "permission" },
+        "permissionID": { "type": "string" },
+        "prompt": { "type": "string" },
+        "url": { "type": "string" },
+        "poll": { "type": "boolean" }
+      },
+      "required": ["type", "permissionID", "prompt"]
+    },
+    {
+      "title": "progress",
+      "properties": {
+        "schema_version": { "type": "string", "const": "1.0.0" },
+        "type": { "const": "progress" },
+        "message": { "type": "string" },
+        "detail": { "type": "string" }
+      },
+      "required": ["type", "message"]
+    },
+    {
+      "title": "result",
+      "description": "Terminal event. Result fields are spread at the top level (not nested).",
+      "properties": {
+        "schema_version": { "type": "string", "const": "1.0.0" },
+        "type": { "const": "result" },
+        "status": { "type": "string", "enum": ["complete", "cancelled"] },
+        "repos": { "type": "array", "items": { "type": "string" } },
+        "pullRequests": { "type": "array" },
+        "feedUrl": { "type": "string" },
+        "summary": { "type": "string", "description": "Pre-rendered ANSI-free text safe to relay verbatim." }
+      },
+      "required": ["type", "status"]
+    }
+  ]
 }

package/schemas/submit.v1.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/submit.v1.json",
+  "title": "haystack submit --json",
+  "description": "Emitted exactly once on stdout (progress goes to stderr). status 'created'/'already_exists' means the PR exists — read analysis.verdict for the outcome. status 'error' means the submit itself failed and the process exits 1.",
+  "type": "object",
+  "required": ["schema_version", "status"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0.0" },
+    "status": { "type": "string", "enum": ["created", "already_exists", "error"] },
+    "error": { "type": "string", "description": "Present only when status is 'error'. Actionable message including the remediation." },
+    "ref": { "type": "string", "description": "owner/repo#number" },
+    "pr_number": { "type": "integer" },
+    "url": { "type": "string" },
+    "title": { "type": "string" },
+    "title_source": { "type": "string", "enum": ["flag", "last-commit", "existing-pr"] },
+    "body": { "type": ["string", "null"], "description": "The exact body posted to GitHub. Null when the PR already existed (its body is not modified)." },
+    "body_source": { "type": "string", "enum": ["flag", "body-file", "stdin", "commit-messages", "existing-pr"] },
+    "branch": { "type": "string" },
+    "base": { "type": "string" },
+    "draft": { "type": "boolean" },
+    "account": { "type": ["string", "null"], "description": "GitHub login the submit was performed as." },
+    "auto_merge": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "source"],
+      "properties": {
+        "enabled": { "type": "boolean", "description": "APPLIED state: true only if the haystack:auto-merge label is actually on the PR. False when it was requested but the label application failed (a warning appears on stderr)." },
+        "source": { "type": "string", "enum": ["flag", "config"], "description": "flag = explicit --auto-merge/--no-auto-merge; config = resolved from .haystack.json (false if absent)." }
+      }
+    },
+    "auto_fix": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "source"],
+      "properties": {
+        "enabled": { "type": "boolean", "description": "APPLIED state: true only if the haystack:auto-fix label is actually on the PR." },
+        "source": { "type": "string", "enum": ["flag", "config"] }
+      }
+    },
+    "review_requested": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "APPLIED state: non-null only if the haystack:needs-review label is actually on the PR. Null when --review was passed but the label application failed.",
+      "properties": {
+        "reviewer": { "type": ["string", "null"], "description": "The GitHub user review was successfully requested from, or null (needs-assignment queue, or the specific-reviewer request failed after the label applied)." }
+      }
+    },
+    "triage": {
+      "type": "object",
+      "properties": {
+        "status": { "type": "string", "enum": ["passed", "failed", "skipped", "unavailable"] },
+        "issues": {
+          "type": "array",
+          "description": "Present on the error envelope when blocking triage findings stopped the submit.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "checker": { "type": "string" },
+              "severity": { "type": "string" },
+              "file": { "type": "string" },
+              "line": { "type": ["integer", "null"] },
+              "message": { "type": "string" },
+              "rule": { "type": ["string", "null"] }
+            }
+          }
+        }
+      }
+    },
+    "analysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "verdict", "merged", "summary"],
+      "properties": {
+        "status": { "type": "string", "enum": ["complete", "pending", "failed"], "description": "pending = analysis still running server-side (no wait, SIGINT, timeout, or result fetch failed); poll `haystack triage <ref> --json`. failed = the status check itself kept failing (process exits 1)." },
+        "verdict": {
+          "anyOf": [
+            { "type": "string", "enum": ["good_to_merge", "needs_review", "needs_input"] },
+            { "type": "null" }
+          ]
+        },
+        "merged": { "type": "boolean", "description": "True only when GitHub confirms the PR merged." },
+        "summary": { "type": ["string", "null"] }
+      }
+    },
+    "next": { "type": ["string", "null"], "description": "Follow-up command when the analysis outcome is not final." }
+  }
+}

package/schemas/triage.v1.json

@@ -2,21 +2,47 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://docs.haystackeditor.com/cli/schemas/triage.v1.json",
   "title": "haystack triage --json",
+  "deprecated": true,
+  "description": "HISTORICAL: superseded by triage.v2.json. The CLI no longer emits this shape; this file is retained immutably for consumers pinned to the v1 contract.",
   "type": "object",
-  "required": ["schema_version", "owner", "repo", "prNumber", "rating", "findings"],
+  "required": [
+    "schema_version",
+    "owner",
+    "repo",
+    "prNumber",
+    "rating",
+    "findings"
+  ],
   "properties": {
-    "schema_version": { "type": "string", "const": "1.0.0" },
-    "owner": { "type": "string" },
-    "repo": { "type": "string" },
-    "prNumber": { "type": "integer" },
-    "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "owner": {
+      "type": "string"
+    },
+    "repo": {
+      "type": "string"
+    },
+    "prNumber": {
+      "type": "integer"
+    },
+    "rating": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 5
+    },
     "autoFixerHandling": {
       "type": "array",
       "items": {
         "type": "object",
         "properties": {
-          "category": { "type": "string" },
-          "summary": { "type": "string" }
+          "category": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          }
         }
       }
     },
@@ -25,9 +51,15 @@
       "items": {
         "type": "object",
         "properties": {
-          "category": { "type": "string" },
-          "summary": { "type": "string" },
-          "reason": { "type": "string" }
+          "category": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          }
         }
       }
     },
@@ -35,14 +67,35 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["category", "summary"],
+        "required": [
+          "category",
+          "summary"
+        ],
         "properties": {
-          "category": { "type": "string" },
-          "summary": { "type": "string" },
-          "detail": { "type": "string" },
-          "agentFixPrompt": { "type": ["string", "null"] },
-          "source": { "type": ["string", "null"] },
-          "autoFixing": { "type": "boolean" }
+          "category": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "detail": {
+            "type": "string"
+          },
+          "agentFixPrompt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "source": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "autoFixing": {
+            "type": "boolean"
+          }
         }
       }
     }