@haystackeditor/cli 0.15.10 → 0.15.11

package/dist/utils/auth.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Path to a long-lived `hsk_live_*` token created by `haystack login --headless`.
+ * If present (or HAYSTACK_CLI_TOKEN is set), it takes priority over the
+ * regular OAuth credentials. CI environments use this exclusively.
+ *
+ * Why a separate file (not just an entry in credentials.json):
+ *   1. Different lifecycle — the OAuth flow renews + refreshes; hsk_live
+ *      tokens are mint-once-revoke-never until explicit revocation.
+ *   2. Easier to commit accidentally and easier to .gitignore (one file).
+ *   3. Different shape — hsk_live tokens carry server-side scope that the
+ *      OAuth token doesn't, and we don't want to model both in one schema.
+ */
+export declare const HEADLESS_TOKEN_FILE: string;
+interface HeadlessTokenFile {
+    token: string;
+    id?: string;
+    label?: string;
+    created_at?: string;
+}
 export interface StoredAccount {
     github_token: string;
     created_at: string;
@@ -46,5 +65,15 @@ export declare function removeAccount(login?: string): Promise<string | null>;
 export declare function getActiveLogin(): Promise<string | null>;
 export declare function getRepoDefaultAccount(owner: string, repo: string): Promise<string | null>;
 export declare function setRepoDefaultAccount(owner: string, repo: string, login: string): Promise<void>;
+/** Thrown by {@link resolveAuthContext} when no usable credential is found. */
+export declare class NotLoggedInError extends Error {
+    constructor(message?: string);
+}
+/** Read the headless CLI token if one is configured. Env var wins over the
+ *  on-disk file so CI can override without touching the home directory. */
+export declare function readHeadlessToken(): Promise<HeadlessTokenFile | null>;
+export declare function writeHeadlessToken(record: HeadlessTokenFile): Promise<string>;
+export declare function clearHeadlessToken(): Promise<void>;
 export declare function resolveAuthContext(options?: ResolveAuthOptions): Promise<ResolvedAuthContext>;
 export declare function loadToken(options?: ResolveAuthOptions): Promise<string | null>;
+export {};

package/dist/utils/auth.js

@@ -4,6 +4,20 @@ import * as path from 'path';
 const CONFIG_DIR = path.join(os.homedir(), '.haystack');
 const TOKEN_FILE = path.join(CONFIG_DIR, 'credentials.json');
 const TOKEN_FILE_DISPLAY = '~/.haystack/credentials.json';
+/**
+ * Path to a long-lived `hsk_live_*` token created by `haystack login --headless`.
+ * If present (or HAYSTACK_CLI_TOKEN is set), it takes priority over the
+ * regular OAuth credentials. CI environments use this exclusively.
+ *
+ * Why a separate file (not just an entry in credentials.json):
+ *   1. Different lifecycle — the OAuth flow renews + refreshes; hsk_live
+ *      tokens are mint-once-revoke-never until explicit revocation.
+ *   2. Easier to commit accidentally and easier to .gitignore (one file).
+ *   3. Different shape — hsk_live tokens carry server-side scope that the
+ *      OAuth token doesn't, and we don't want to model both in one schema.
+ */
+export const HEADLESS_TOKEN_FILE = path.join(CONFIG_DIR, 'cli-token');
+const HEADLESS_TOKEN_FILE_DISPLAY = '~/.haystack/cli-token';
 const GITHUB_LOGIN_PATTERN = /^[A-Za-z\d](?:[A-Za-z\d]|-(?=[A-Za-z\d])){0,38}$/;
 function emptyStore() {
     return {
@@ -337,7 +351,60 @@ export async function setRepoDefaultAccount(owner, repo, login) {
     store.repoDefaults[key] = storedLogin;
     await saveStore(store);
 }
+/** Thrown by {@link resolveAuthContext} when no usable credential is found. */
+export class NotLoggedInError extends Error {
+    constructor(message = 'Not logged in. Run `haystack login` first.') {
+        super(message);
+        this.name = 'NotLoggedInError';
+    }
+}
+/** Read the headless CLI token if one is configured. Env var wins over the
+ *  on-disk file so CI can override without touching the home directory. */
+export async function readHeadlessToken() {
+    const envToken = process.env.HAYSTACK_CLI_TOKEN;
+    if (envToken && envToken.startsWith('hsk_live_')) {
+        return { token: envToken, label: 'env:HAYSTACK_CLI_TOKEN' };
+    }
+    try {
+        const raw = await fs.readFile(HEADLESS_TOKEN_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.token === 'string' && parsed.token.startsWith('hsk_live_')) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeHeadlessToken(record) {
+    await fs.mkdir(CONFIG_DIR, { recursive: true });
+    // 0600 so other users on a shared machine can't read the token. The file
+    // contains a long-lived credential — mode matters here in a way that doesn't
+    // for credentials.json, which can be re-minted via OAuth at any time.
+    await fs.writeFile(HEADLESS_TOKEN_FILE, JSON.stringify(record, null, 2) + '\n', {
+        mode: 0o600,
+    });
+    return HEADLESS_TOKEN_FILE_DISPLAY;
+}
+export async function clearHeadlessToken() {
+    try {
+        await fs.unlink(HEADLESS_TOKEN_FILE);
+    }
+    catch { /* not present is fine */ }
+}
 export async function resolveAuthContext(options = {}) {
+    // hsk_live tokens win unconditionally. They were created explicitly by
+    // the operator with `haystack login --headless` (or set via env in CI)
+    // — that intent should not be overridden by a stale OAuth cookie.
+    const headless = await readHeadlessToken();
+    if (headless) {
+        return {
+            login: headless.label ?? 'headless',
+            token: headless.token,
+            source: 'active',
+        };
+    }
     const store = await loadCredentialsStore();
     const { preferredLogin, owner, repo } = options;
     if (preferredLogin) {
@@ -370,7 +437,7 @@ export async function resolveAuthContext(options = {}) {
             source: 'active',
         };
     }
-    throw new Error('Not logged in. Run `haystack login` first.');
+    throw new NotLoggedInError();
 }
 export async function loadToken(options = {}) {
     try {
@@ -378,7 +445,8 @@ export async function loadToken(options = {}) {
         return context.token;
     }
     catch (error) {
-        if (error instanceof Error && error.message.startsWith('Not logged in.')) {
+        // Classify by type, not message text (see pr-rules.yml PR007).
+        if (error instanceof NotLoggedInError) {
             return null;
         }
         throw error;

package/dist/utils/git.d.ts

@@ -68,6 +68,10 @@ export interface PushAuth {
  * Without `auth`, falls back to `git push -u <remote>` using ambient creds.
  */
 export declare function pushBranch(remoteName: string, branchName: string, auth?: PushAuth): void;
+/** Thrown when a git remote URL is not a recognized GitHub SSH/HTTPS URL. */
+export declare class UnsupportedRemoteUrlError extends Error {
+    constructor(url: string);
+}
 /**
  * Parse remote URL to extract owner and repo
  * Supports both SSH and HTTPS URLs

package/dist/utils/git.js

@@ -257,6 +257,13 @@ function translatePushError(err, repoSlug) {
 // ============================================================================
 // Remote operations
 // ============================================================================
+/** Thrown when a git remote URL is not a recognized GitHub SSH/HTTPS URL. */
+export class UnsupportedRemoteUrlError extends Error {
+    constructor(url) {
+        super(`Unsupported remote URL format: ${url}`);
+        this.name = 'UnsupportedRemoteUrlError';
+    }
+}
 /**
  * Parse remote URL to extract owner and repo
  * Supports both SSH and HTTPS URLs
@@ -285,10 +292,13 @@ export function parseRemoteUrl(remoteName = 'origin') {
                 remoteName,
             };
         }
-        throw new Error(`Unsupported remote URL format: ${url}`);
+        throw new UnsupportedRemoteUrlError(url);
     }
     catch (err) {
-        if (err instanceof Error && err.message.includes('Unsupported')) {
+        // Propagate the "unrecognized URL" case as-is; wrap everything else (the
+        // `git remote get-url` command itself failing) in a friendlier message.
+        // Classify by type, not message text (see pr-rules.yml PR007).
+        if (err instanceof UnsupportedRemoteUrlError) {
             throw err;
         }
         throw new Error(`Failed to get remote URL for '${remoteName}'`);

package/dist/utils/prompter.js

@@ -139,7 +139,10 @@ class JsonPrompter {
         return id in this.answers;
     }
     emit(event) {
-        process.stdout.write(JSON.stringify(event) + '\n');
+        // Stamp every NDJSON event with the setup schema version so agent
+        // consumers can pin a contract. See docs/SPEC-CLI-FIRST-CLASS.md.
+        const stamped = { schema_version: '1.0.0', ...event };
+        process.stdout.write(JSON.stringify(stamped) + '\n');
     }
     /** Lazily open stdin only when we actually need an answer the agent must send. */
     ensureStdin() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.15.10",
+  "version": "0.15.11",
   "description": "Set up Haystack for your project — automated PR review, triage, and merge queue",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "build": "tsc && rm -rf dist/assets && cp -r src/assets dist/assets",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
+    "check:schemas": "node scripts/check-schemas.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -46,7 +47,8 @@
     "typescript": "5.9.3"
   },
   "files": [
-    "dist"
+    "dist",
+    "schemas"
   ],
   "engines": {
     "node": ">=18"

package/schemas/pr.v1.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/pr.v1.json",
+  "title": "haystack pr <ref> --json",
+  "type": "object",
+  "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" },
+    "mergeQueue": {
+      "type": "object",
+      "properties": {
+        "state": { "type": "string", "enum": ["not-enrolled", "eligible", "grace", "queued", "merging", "merged", "blocked"] },
+        "graceEndsAt": { "type": ["string", "null"] },
+        "blockedReason": { "type": ["string", "null"] }
+      }
+    },
+    "lastTriage": {
+      "type": ["object", "null"],
+      "properties": {
+        "rating": { "type": "integer" },
+        "completedAt": { "type": "string" },
+        "headSha": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/setup.v1.json

@@ -0,0 +1,21 @@
+{
+  "$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.",
+  "type": "object",
+  "required": ["schema_version", "type"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0.0" },
+    "type": {
+      "type": "string",
+      "enum": ["question", "permission", "log", "progress", "result"]
+    },
+    "id": { "type": "string" },
+    "prompt": { "type": "string" },
+    "choices": { "type": "array" },
+    "level": { "type": "string", "enum": ["info", "warn", "error"] },
+    "message": { "type": "string" },
+    "result": { "type": "object" }
+  }
+}

package/schemas/triage.v1.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/triage.v1.json",
+  "title": "haystack triage --json",
+  "type": "object",
+  "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 },
+    "autoFixerHandling": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "category": { "type": "string" },
+          "summary": { "type": "string" }
+        }
+      }
+    },
+    "autoFixerSkipped": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "category": { "type": "string" },
+          "summary": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["category", "summary"],
+        "properties": {
+          "category": { "type": "string" },
+          "summary": { "type": "string" },
+          "detail": { "type": "string" },
+          "agentFixPrompt": { "type": ["string", "null"] },
+          "source": { "type": ["string", "null"] },
+          "autoFixing": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}