@haystackeditor/cli 0.15.19 → 0.15.21

package/dist/commands/system-map.js

@@ -0,0 +1,228 @@
+/**
+ * `haystack system-map validate` — instant feedback on `.haystack/system.yml`.
+ *
+ * The system map holds customer-declared facts about how their system WORKS
+ * (build, boot, seed, log in, observe) so Haystack QA can run it. It never
+ * selects tests — Haystack decides what to test from each PR's diff. The
+ * `/map-your-system` skill authors the file; this command lets a user (or
+ * their coding agent) check it before committing, instead of waiting for the
+ * next QA run to reject it.
+ *
+ * Source-of-truth note: the QA pipeline's own loader for this file
+ * (`analysis/src/agents/systemMap.ts`) lives on the incoming QA-replay
+ * subsystem branch and is NOT on main yet — until it lands, this command is
+ * the only validator of the format, and its rules were copied verbatim from
+ * that loader. Once the subsystem merges, the analysis-side loader becomes
+ * the source of truth (it is a separate deployable the CLI cannot import),
+ * and rule changes must update both in the same PR.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { parse as parseYaml } from 'yaml';
+import { findGitRoot } from '../utils/hooks.js';
+const SYSTEM_MAP_RELATIVE_PATHS = ['.haystack/system.yml', '.haystack/system.yaml'];
+/**
+ * Keys whose presence means the file is steering test selection rather than
+ * describing the system. Rejected structurally so the "facts in, never test
+ * selection in" rule cannot erode.
+ */
+const TEST_SELECTION_KEYS = new Set([
+    'scenarios', 'tests', 'tests_to_run', 'run_tests', 'skip', 'skip_tests',
+    'focus', 'only', 'exclude', 'test_plan', 'experiments',
+]);
+/** Values that look like credentials rather than references to them. */
+const SECRET_VALUE_RES = [
+    { name: 'AWS access key', re: /AKIA[0-9A-Z]{16}/ },
+    { name: 'GitHub token', re: /gh[pousr]_[A-Za-z0-9]{36,}/ },
+    { name: 'API key', re: /sk-[A-Za-z0-9_-]{24,}/ },
+    { name: 'private key block', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+    { name: 'password-like assignment', re: /(password|passwd|secret)\s*[:=]\s*\S{8,}/i },
+];
+export function validateSystemMapText(rawYaml) {
+    const issues = [];
+    let doc;
+    try {
+        doc = parseYaml(rawYaml);
+    }
+    catch (error) {
+        return {
+            issues: [{ severity: 'error', path: '(root)', message: `YAML parse error: ${error.message}` }],
+            summary: null,
+        };
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+        return {
+            issues: [{ severity: 'error', path: '(root)', message: 'System map must be a mapping' }],
+            summary: null,
+        };
+    }
+    const root = doc;
+    if (root.version !== 1 && root.version !== '1') {
+        issues.push({ severity: 'error', path: 'version', message: 'version must be 1' });
+    }
+    for (const key of Object.keys(root)) {
+        if (TEST_SELECTION_KEYS.has(key)) {
+            issues.push({
+                severity: 'error',
+                path: key,
+                message: `"${key}" steers test selection — the system map may only describe how the system works. Haystack decides what to test from the diff.`,
+            });
+        }
+    }
+    scanForSecrets(root, '(root)', issues);
+    validateCommands(root, issues);
+    if (issues.some((issue) => issue.severity === 'error')) {
+        return { issues, summary: null };
+    }
+    return { issues, summary: summarize(root) };
+}
+function scanForSecrets(value, atPath, issues) {
+    if (typeof value === 'string') {
+        for (const { name, re } of SECRET_VALUE_RES) {
+            if (re.test(value)) {
+                issues.push({
+                    severity: 'error',
+                    path: atPath,
+                    message: `Value looks like a ${name}. Facts must reference env var NAMES; secret values are injected out-of-band.`,
+                });
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => scanForSecrets(entry, `${atPath}[${index}]`, issues));
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const [key, entry] of Object.entries(value)) {
+            scanForSecrets(entry, atPath === '(root)' ? key : `${atPath}.${key}`, issues);
+        }
+    }
+}
+function validateCommands(root, issues) {
+    const requireString = (value, atPath) => {
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            issues.push({ severity: 'error', path: atPath, message: 'must be a non-empty string command' });
+        }
+    };
+    const env = root.environment;
+    if (env?.setup !== undefined) {
+        if (!Array.isArray(env.setup)) {
+            issues.push({ severity: 'error', path: 'environment.setup', message: 'must be a list of { run } steps' });
+        }
+        else {
+            env.setup.forEach((step, index) => requireString(step?.run, `environment.setup[${index}].run`));
+        }
+    }
+    // Not in the QA loader's checks (yet): a scalar here would silently compile
+    // into per-character garbage via Object.entries — reject it as malformed.
+    if (env?.toolchain !== undefined && !isPlainObject(env.toolchain)) {
+        issues.push({
+            severity: 'error',
+            path: 'environment.toolchain',
+            message: 'must be a mapping of tool name → version (e.g. { node: "22" })',
+        });
+    }
+    const services = root.services;
+    for (const [name, service] of Object.entries(services ?? {})) {
+        requireString(service?.boot, `services.${name}.boot`);
+    }
+    const personas = root.data?.personas;
+    for (const [name, persona] of Object.entries(personas ?? {})) {
+        requireString(persona?.login, `data.personas.${name}.login`);
+    }
+    const artifacts = root.artifacts;
+    for (const [name, artifact] of Object.entries(artifacts ?? {})) {
+        const decl = artifact;
+        if (decl?.kind !== 'container-image') {
+            issues.push({
+                severity: 'error',
+                path: `artifacts.${name}.kind`,
+                message: 'must be "container-image" (the only artifact kind supported today)',
+            });
+        }
+        requireString(decl?.reference, `artifacts.${name}.reference`);
+        if (decl?.boot !== undefined) {
+            if (!Array.isArray(decl.boot)) {
+                issues.push({ severity: 'error', path: `artifacts.${name}.boot`, message: 'must be a list of { name } boot modes' });
+            }
+            else {
+                decl.boot.forEach((mode, index) => requireString(mode?.name, `artifacts.${name}.boot[${index}].name`));
+            }
+        }
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function summarize(root) {
+    const env = (root.environment ?? {});
+    const data = (root.data ?? {});
+    const observability = (root.observability ?? {});
+    const testing = (root.testing ?? {});
+    return {
+        setup_steps: Array.isArray(env.setup) ? env.setup.length : 0,
+        toolchain_entries: isPlainObject(env.toolchain) ? Object.keys(env.toolchain).length : 0,
+        services: Object.keys((root.services ?? {})),
+        personas: Object.keys(data.personas ?? {}),
+        data_commands: (data.seed ? 1 : 0) + (data.reset ? 1 : 0),
+        observability_entries: (Array.isArray(observability.logs) ? observability.logs.length : 0) + (observability.inspect_db ? 1 : 0),
+        external_services: Object.keys((root.external_services ?? {})),
+        testing_entries: Object.keys(testing).length,
+        constraints: Array.isArray(root.constraints) ? root.constraints.length : 0,
+        artifacts: Object.keys((root.artifacts ?? {})),
+    };
+}
+export async function systemMapValidateCommand(options) {
+    const root = findGitRoot() ?? process.cwd();
+    const relativePath = SYSTEM_MAP_RELATIVE_PATHS.find((candidate) => existsSync(join(root, candidate)));
+    if (!relativePath) {
+        if (options.json) {
+            console.log(JSON.stringify({ status: 'missing', path: SYSTEM_MAP_RELATIVE_PATHS[0], issues: [] }, null, 2));
+        }
+        else {
+            console.error(chalk.red(`No system map found at ${SYSTEM_MAP_RELATIVE_PATHS[0]}.`) +
+                ' Run the /map-your-system skill in your coding agent (installed via `haystack skills install`) to create one.');
+        }
+        process.exit(1);
+    }
+    const { issues, summary } = validateSystemMapText(readFileSync(join(root, relativePath), 'utf-8'));
+    const ok = summary !== null;
+    if (options.json) {
+        console.log(JSON.stringify({ status: ok ? 'valid' : 'invalid', path: relativePath, issues, summary }, null, 2));
+    }
+    else {
+        for (const issue of issues) {
+            const bullet = issue.severity === 'error' ? chalk.red('✗') : chalk.yellow('•');
+            console.log(`${bullet} ${chalk.white(issue.path)}: ${issue.message}`);
+        }
+        if (!ok) {
+            console.log();
+            console.log(chalk.red(`${relativePath} is invalid — fix the errors above.`));
+        }
+        else {
+            const declared = [];
+            if (summary.setup_steps)
+                declared.push(`${summary.setup_steps} setup step(s)`);
+            if (summary.services.length)
+                declared.push(`services: ${summary.services.join(', ')}`);
+            if (summary.personas.length)
+                declared.push(`personas: ${summary.personas.join(', ')}`);
+            if (summary.data_commands)
+                declared.push(`${summary.data_commands} data command(s)`);
+            if (summary.external_services.length)
+                declared.push(`external: ${summary.external_services.join(', ')}`);
+            if (summary.artifacts.length)
+                declared.push(`artifacts: ${summary.artifacts.join(', ')}`);
+            if (summary.testing_entries)
+                declared.push('testing');
+            if (summary.constraints)
+                declared.push(`${summary.constraints} constraint(s)`);
+            console.log(chalk.green(`✓ ${relativePath} is valid`) + (declared.length ? chalk.dim(` — ${declared.join('; ')}`) : ''));
+            console.log(chalk.dim('When Haystack QA runs on this repo, each entry is treated as a declared fact and checked against run receipts.'));
+        }
+    }
+    if (!ok)
+        process.exit(1);
+}

package/dist/commands/tokens.js

@@ -26,6 +26,7 @@
  */
 import chalk from 'chalk';
 import { loadToken, readHeadlessToken, writeHeadlessToken, clearHeadlessToken } from '../utils/auth.js';
+import { classifyHttpError } from '../utils/haystack-api.js';
 const HEADLESS_BASE = process.env.HAYSTACK_API_BASE ?? 'https://haystackeditor.com';
 export async function headlessLoginCommand(opts) {
     if (opts.token) {
@@ -139,7 +140,7 @@ export async function listTokensCommand(opts) {
         headers: { Authorization: `Bearer ${token}`, 'User-Agent': 'Haystack-CLI' },
     });
     if (!res.ok) {
-        console.error(chalk.red(`list failed: ${res.status} ${await res.text()}`));
+        console.error(chalk.red((await classifyHttpError(res, 'Token list')).message));
         process.exit(1);
     }
     const data = (await res.json());
@@ -169,7 +170,7 @@ export async function revokeTokenCommand(id) {
         headers: { Authorization: `Bearer ${token}`, 'User-Agent': 'Haystack-CLI' },
     });
     if (!res.ok) {
-        console.error(chalk.red(`revoke failed: ${res.status} ${await res.text()}`));
+        console.error(chalk.red((await classifyHttpError(res, `Token revoke (${id})`)).message));
         process.exit(1);
     }
     // If the revoked token is the one currently on disk, clear it so we

package/dist/commands/traces.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { loadToken } from '../utils/auth.js';
 import { fetchAnalysisArtifact, fetchGitHubJson } from '../utils/haystack-api.js';
 import { withSchema } from '../schema.js';
-import { parsePrRef } from './pr.js';
+import { parsePrRef } from '../utils/pr-ref.js';
 function publicCheckpoint(trace) {
     return {
         checkpoint_id: trace.checkpointId,
@@ -16,7 +16,7 @@ function publicCheckpoint(trace) {
     };
 }
 async function tokenAndHead(ref) {
-    const pr = parsePrRef(ref);
+    const pr = parsePrRef(ref, 'traces list');
     const token = await loadToken({ owner: pr.owner, repo: pr.repo });
     if (!token)
         throw new Error('Not authenticated. Run `haystack login` first.');

package/dist/commands/triage.d.ts

@@ -20,21 +20,16 @@
  *   (default) Rich terminal output
  */
 import type { RatingSynthesis, AutoFixManifest } from '../utils/analysis-api.js';
+import { type ParsedPR } from '../utils/pr-ref.js';
 export interface TriageOptions {
     json?: boolean;
     wait?: boolean;
     hook?: boolean;
     clear?: boolean;
 }
-interface ParsedPR {
-    owner: string;
-    repo: string;
-    prNumber: number;
-}
 export declare function buildJsonOutput(pr: ParsedPR, headSha: string | null, synthesis: RatingSynthesis, manifest?: AutoFixManifest | null): Record<string, unknown>;
 export declare function buildJsonState(pr: ParsedPR, status: 'pending' | 'failed' | 'unavailable', message?: string): Record<string, unknown>;
 export declare function fetchTriageHeadSha(pr: ParsedPR, token?: string): Promise<string | null>;
 export declare function triageCommand(identifier: string | undefined, options: TriageOptions): Promise<void>;
 /** Pure read path for MCP: returns a public payload without writing stdout or exiting. */
 export declare function fetchTriagePayload(identifier: string): Promise<Record<string, unknown>>;
-export {};

package/dist/commands/triage.js

@@ -22,53 +22,13 @@
 import chalk from 'chalk';
 import WebSocket from 'ws';
 import { checkAnalysisReady, fetchRatingSynthesis, fetchAutoFixManifest } from '../utils/analysis-api.js';
-import { parseRemoteUrl } from '../utils/git.js';
 import { loadToken } from '../utils/auth.js';
 import { loadPendingSubmit, updatePendingSubmit, clearPendingSubmit } from '../utils/pending-state.js';
+import { parsePrRef } from '../utils/pr-ref.js';
+import { toPublicVerdict } from '../states.js';
 import { withSchema } from '../schema.js';
 import { fetchGitHubJson } from '../utils/haystack-api.js';
 // ============================================================================
-// PR identifier parsing
-// ============================================================================
-/**
- * Parse a PR identifier from various formats:
- *   123                                    -> uses current repo
- *   #123                                   -> uses current repo
- *   owner/repo#123                         -> fully qualified
- *   https://github.com/owner/repo/pull/123 -> GitHub URL
- */
-function parsePRIdentifier(identifier) {
-    // GitHub URL: https://github.com/owner/repo/pull/123
-    const urlMatch = identifier.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/);
-    if (urlMatch) {
-        return { owner: urlMatch[1], repo: urlMatch[2], prNumber: parseInt(urlMatch[3], 10) };
-    }
-    // Fully qualified: owner/repo#123
-    const qualifiedMatch = identifier.match(/^([^/]+)\/([^#]+)#(\d+)$/);
-    if (qualifiedMatch) {
-        return { owner: qualifiedMatch[1], repo: qualifiedMatch[2], prNumber: parseInt(qualifiedMatch[3], 10) };
-    }
-    // Bare number: 123 or #123
-    const numberMatch = identifier.match(/^#?(\d+)$/);
-    if (numberMatch) {
-        const prNumber = parseInt(numberMatch[1], 10);
-        // Infer owner/repo from git remote
-        try {
-            const remote = parseRemoteUrl('origin');
-            return { owner: remote.owner, repo: remote.repo, prNumber };
-        }
-        catch {
-            throw new Error(`Cannot determine repository for PR #${prNumber}.\n` +
-                `Use the full format: haystack triage owner/repo#${prNumber}`);
-        }
-    }
-    throw new Error(`Invalid PR identifier: "${identifier}"\n\n` +
-        `Accepted formats:\n` +
-        `  haystack triage 123\n` +
-        `  haystack triage owner/repo#123\n` +
-        `  haystack triage https://github.com/owner/repo/pull/123`);
-}
-// ============================================================================
 // Output formatting
 // ============================================================================
 /**
@@ -121,13 +81,11 @@ function printRichOutput(pr, synthesis, manifest) {
     console.log(`  ${chalk.dim(reviewUrl)}\n`);
 }
 export function buildJsonOutput(pr, headSha, synthesis, manifest) {
-    const verdict = synthesis.analysisVerdict
-        ?? (synthesis.haystackRating >= 5 ? 'clean' : 'has-issues');
     const payload = {
         ref: `${pr.owner}/${pr.repo}#${pr.prNumber}`,
         head_sha: headSha,
         status: 'complete',
-        verdict: verdict === 'clean' ? 'good_to_merge' : verdict === 'needs-review' ? 'needs_review' : 'needs_input',
+        verdict: toPublicVerdict(synthesis.analysisVerdict, synthesis.haystackRating),
         rating: synthesis.haystackRating,
         human_review_reasons: synthesis.humanReviewReasons ?? [],
         findings: (synthesis.synthesisDisplay || []).map((f) => ({
@@ -344,7 +302,7 @@ async function waitForAnalysis(owner, repo, prNumber, timeoutMs, token, quiet) {
 function resolvePR(identifier, options) {
     if (identifier) {
         try {
-            return parsePRIdentifier(identifier);
+            return parsePrRef(identifier, 'triage');
         }
         catch (err) {
             console.error(chalk.red(`\n${err.message}\n`));
@@ -355,7 +313,13 @@ function resolvePR(identifier, options) {
     const pending = loadPendingSubmit();
     if (!pending) {
         if (options.json) {
-            console.log(JSON.stringify({ status: 'none' }));
+            // Versioned error envelope (the old `{"status":"none"}` matched no
+            // schema); the caller asked for a triage and there is nothing to triage.
+            console.log(JSON.stringify(withSchema('error', {
+                status: 'error',
+                error: 'No pending submit to triage. Pass a PR identifier: haystack triage owner/repo#123 --json',
+            }), null, 2));
+            process.exitCode = 1;
         }
         else if (!options.hook) {
             console.log(chalk.dim('No pending submits. Pass a PR number to triage a specific PR.\n'));
@@ -371,7 +335,16 @@ export async function triageCommand(identifier, options) {
     // Handle --clear
     if (options.clear) {
         clearPendingSubmit();
-        if (!options.hook) {
+        if (options.json) {
+            // stdout stays pure JSON in --json mode; use the shared action envelope.
+            console.log(JSON.stringify(withSchema('action', {
+                action: 'clear_pending',
+                status: 'ok',
+                ref: null,
+                detail: 'Pending submit state cleared.',
+            }), null, 2));
+        }
+        else if (!options.hook) {
             console.log(chalk.dim('Pending submit state cleared.'));
         }
         return;
@@ -474,12 +447,35 @@ export async function triageCommand(identifier, options) {
     }
     if (!analysisReady)
         return;
-    // Fetch the full rating synthesis and auto-fix manifest in parallel
-    const [synthesis, autoFixManifest, headSha] = await Promise.all([
-        fetchRatingSynthesis(pr.owner, pr.repo, pr.prNumber, token),
-        fetchAutoFixManifest(pr.owner, pr.repo, pr.prNumber, token),
-        fetchTriageHeadSha(pr, token),
-    ]);
+    // Fetch the full rating synthesis and auto-fix manifest in parallel.
+    // Auth failures throw a classified error — report it as failed (with the
+    // remediation) rather than the old behavior of "not available yet, retry".
+    let synthesis;
+    let autoFixManifest;
+    let headSha;
+    try {
+        [synthesis, autoFixManifest, headSha] = await Promise.all([
+            fetchRatingSynthesis(pr.owner, pr.repo, pr.prNumber, token),
+            fetchAutoFixManifest(pr.owner, pr.repo, pr.prNumber, token),
+            fetchTriageHeadSha(pr, token),
+        ]);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (options.hook) {
+            // Session-start hooks must never fail the session — match the
+            // status-check error path above: print the failed line, exit 0.
+            printHookOutput(pr, null, null, 'failed');
+            return;
+        }
+        if (options.json) {
+            printJsonState(pr, 'failed', message);
+        }
+        else {
+            console.error(chalk.red(`\n  ${message}\n`));
+        }
+        process.exit(1);
+    }
     // Update pending state if this PR matches the pending submit
     updatePendingSubmitIfExists(pr, synthesis ? 'completed' : undefined);
     if (!synthesis) {
@@ -520,7 +516,7 @@ export async function triageCommand(identifier, options) {
 }
 /** Pure read path for MCP: returns a public payload without writing stdout or exiting. */
 export async function fetchTriagePayload(identifier) {
-    const pr = parsePRIdentifier(identifier);
+    const pr = parsePrRef(identifier, 'triage');
     const token = await loadToken({ owner: pr.owner, repo: pr.repo }) || undefined;
     const ready = await checkAnalysisReady(pr.owner, pr.repo, pr.prNumber, token);
     if (ready.status === 'pending')