@haystackeditor/cli 0.15.19 → 0.15.21

package/dist/commands/submit.js

@@ -19,6 +19,8 @@ import { checkAnalysisReady, fetchAnalysisResults } from '../utils/analysis-api.
 import { savePendingSubmit, updatePendingSubmit } from '../utils/pending-state.js';
 import { ensureHaystackLabels, addLabelsToIssue, } from '../utils/github-api.js';
 import { listStoredAccounts, resolveAuthContext, setRepoDefaultAccount, } from '../utils/auth.js';
+import { HaystackApiError } from '../utils/haystack-api.js';
+import { withSchema } from '../schema.js';
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -248,6 +250,26 @@ function printTriageSummary(result) {
 // Main command
 // ============================================================================
 export async function submitCommand(options) {
+    // --json contract: stdout carries exactly one JSON document (the submit
+    // payload or an error envelope); every progress/status line goes to stderr.
+    // Redirecting console.log wholesale keeps the existing progress output
+    // intact for humans watching stderr. (console.error/warn already hit stderr.)
+    if (options.json) {
+        console.log = (...args) => {
+            process.stderr.write(args.map((a) => (typeof a === 'string' ? a : String(a))).join(' ') + '\n');
+        };
+    }
+    /** Print a classified failure (JSON envelope on stdout when --json) and exit 1. */
+    const fail = (message, extra) => {
+        if (options.json) {
+            process.stdout.write(JSON.stringify(withSchema('submit', { status: 'error', error: message, ...extra }), null, 2) + '\n');
+            console.error(chalk.red(`\n${message}\n`));
+        }
+        else {
+            console.error(chalk.red(`\n${message}\n`));
+        }
+        process.exit(1);
+    };
     console.log(chalk.bold.cyan('\nHaystack Submit\n'));
     // -------------------------------------------------------------------------
     // Step 1: Validate environment
@@ -255,14 +277,13 @@ export async function submitCommand(options) {
     console.log(chalk.dim('Checking environment...'));
     // Validate mutually exclusive options
     if (options.body && options.bodyFile) {
-        console.error(chalk.red('\nCannot use both --body and --body-file. Pick one.\n'));
-        process.exit(1);
+        fail('Cannot use both --body and --body-file. Pick one.');
     }
     // Check git repo
     const gitRoot = findGitRoot();
     if (!gitRoot) {
-        console.error(chalk.red('\nNot a git repository.\n'));
-        process.exit(1);
+        fail('Not a git repository. Run `haystack submit` from inside a repository checkout.');
+        return; // unreachable — satisfies TS narrowing
     }
     // Get remote info
     let remoteInfo;
@@ -271,8 +292,8 @@ export async function submitCommand(options) {
         console.log(chalk.green(`✓ Repository: ${remoteInfo.owner}/${remoteInfo.repo}`));
     }
     catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
+        fail(err.message);
+        return; // unreachable — satisfies TS narrowing
     }
     let githubToken;
     let activeGitHubLogin;
@@ -294,8 +315,7 @@ export async function submitCommand(options) {
         }
     }
     catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
+        fail(err.message);
     }
     // Check for uncommitted changes
     if (hasUncommittedChanges()) {
@@ -305,10 +325,14 @@ export async function submitCommand(options) {
     const currentBranch = getCurrentBranch();
     const baseBranch = options.base || getDefaultBranch();
     console.log(chalk.dim(`  Current branch: ${currentBranch}`));
-    console.log(chalk.dim(`  Base branch: ${baseBranch}`));
+    console.log(chalk.dim(`  Base branch: ${baseBranch}${options.base ? '' : ' (detected from origin)'}`));
     // -------------------------------------------------------------------------
     // Step 2: Pre-PR Triage
     // -------------------------------------------------------------------------
+    // Recorded for the --json payload: what triage concluded before the PR
+    // was created. 'unavailable' = infrastructure gave zero signal (never
+    // reported as 'passed').
+    let triageStatus = 'skipped';
     if (!options.force) {
         console.log(chalk.dim('\nRunning pre-PR triage checks...'));
         try {
@@ -330,10 +354,22 @@ export async function submitCommand(options) {
                     // We already warned above and continue.
                 }
                 else {
-                    console.log(chalk.red('\nTriage failed. Fix the issues above or re-run with --force.\n'));
-                    process.exit(1);
+                    fail('Triage failed. Fix the issues above or re-run with --force.', {
+                        triage: {
+                            status: 'failed',
+                            issues: triageResult.results.flatMap((r) => r.issues.map((issue) => ({
+                                checker: r.checker,
+                                severity: issue.severity,
+                                file: issue.file,
+                                line: issue.line ?? null,
+                                message: issue.message,
+                                rule: issue.rule ?? null,
+                            }))),
+                        },
+                    });
                 }
             }
+            triageStatus = triageInfraFailure ? 'unavailable' : 'passed';
         }
         catch (err) {
             // Triage failure should not block submission
@@ -346,6 +382,7 @@ export async function submitCommand(options) {
             else {
                 console.log(chalk.yellow(`\n⚠ Triage skipped: ${err.message}`));
             }
+            triageStatus = 'unavailable';
         }
     }
     else {
@@ -355,24 +392,22 @@ export async function submitCommand(options) {
     // Step 3: Check if on main/master
     // -------------------------------------------------------------------------
     if (currentBranch === 'main' || currentBranch === 'master') {
-        console.error(chalk.red(`\nRefusing to submit from ${currentBranch}. Create a feature branch first.\n`));
-        process.exit(1);
+        fail(`Refusing to submit from ${currentBranch}. Create a feature branch first (e.g. \`git checkout -b my-change\`), then re-run \`haystack submit\`.`);
     }
     // -------------------------------------------------------------------------
     // Step 4: Push to remote
     // -------------------------------------------------------------------------
     console.log(chalk.dim('\nPushing to origin...'));
     if (!githubToken) {
-        console.error(chalk.red('\nInternal error: no Haystack account token resolved before push.\n'));
-        process.exit(1);
+        fail('No Haystack account token was resolved before push (internal error). Run `haystack login`, then retry.');
+        return; // unreachable — satisfies TS narrowing
     }
     try {
         pushBranch('origin', currentBranch, { token: githubToken });
         console.log(chalk.green('✓ Branch pushed'));
     }
     catch (err) {
-        console.error(chalk.red(`\n${err.message}\n`));
-        process.exit(1);
+        fail(err.message);
     }
     // -------------------------------------------------------------------------
     // Step 5: Create or find PR
@@ -382,30 +417,53 @@ export async function submitCommand(options) {
     const existingPR = await findExistingPR(remoteInfo.owner, remoteInfo.repo, currentBranch, githubToken);
     let prNumber;
     let prUrl;
+    let prTitle;
+    // Where the posted title/body came from — echoed to the user and recorded
+    // in the --json payload so the derived values are never silent.
+    let titleSource;
+    let bodySource;
+    let prBody = null;
     if (existingPR) {
         console.log(chalk.yellow(`PR already exists: #${existingPR.number}`));
         prNumber = existingPR.number;
         prUrl = existingPR.html_url;
+        prTitle = existingPR.title;
+        titleSource = 'existing-pr';
+        bodySource = 'existing-pr';
     }
     else {
         // Generate PR title and body
-        const prTitle = options.title || getLastCommitMessage();
-        let bodyContent;
+        try {
+            prTitle = options.title || getLastCommitMessage();
+        }
+        catch (err) {
+            fail(err.message);
+            return; // unreachable — satisfies TS narrowing
+        }
+        titleSource = options.title ? 'flag' : 'last-commit';
+        let bodyContent = '';
         if (options.bodyFile) {
+            bodySource = options.bodyFile === '-' ? 'stdin' : 'body-file';
             try {
                 bodyContent = options.bodyFile === '-'
                     ? fs.readFileSync(0, 'utf-8')
                     : fs.readFileSync(options.bodyFile, 'utf-8');
             }
             catch (err) {
-                console.error(chalk.red(`\nFailed to read body file: ${err.message}\n`));
-                process.exit(1);
+                fail(`Failed to read body file: ${err.message}`);
             }
         }
+        else if (options.body) {
+            bodySource = 'flag';
+            bodyContent = options.body;
+        }
         else {
-            bodyContent = options.body || getCommitMessagesSinceBase(baseBranch);
+            bodySource = 'commit-messages';
+            bodyContent = getCommitMessagesSinceBase(baseBranch);
         }
-        const prBody = buildPRBody(bodyContent);
+        prBody = buildPRBody(bodyContent);
+        console.log(chalk.dim(`  Title: ${prTitle} (from ${titleSource === 'flag' ? '--title' : 'last commit message'})`));
+        console.log(chalk.dim(`  Body: from ${bodySource === 'commit-messages' ? 'commit messages since base' : bodySource}`));
         try {
             const pr = await createPullRequest({
                 owner: remoteInfo.owner,
@@ -422,32 +480,46 @@ export async function submitCommand(options) {
             console.log(chalk.green(`✓ Pull request created: #${prNumber}`));
         }
         catch (err) {
-            console.error(chalk.red(`\n${formatSubmitPermissionError(err, activeGitHubLogin, remoteInfo.owner, remoteInfo.repo)}\n`));
-            process.exit(1);
+            fail(formatSubmitPermissionError(err, activeGitHubLogin, remoteInfo.owner, remoteInfo.repo));
+            return; // unreachable — satisfies TS narrowing
         }
     }
     // -------------------------------------------------------------------------
     // Step 6: Apply auto-merge label if enabled
     // -------------------------------------------------------------------------
+    // Applied-state tracking: the --json payload must report what actually
+    // happened on GitHub, not what was requested — label application can fail
+    // (403/422) and only warn.
+    let autoMergeApplied = false;
+    let autoFixApplied = false;
+    let reviewLabelApplied = false;
+    let reviewerRequestedOk = null;
+    // Announce the resolved value AND its source in both directions — a silent
+    // config-driven default is invisible to the caller otherwise.
+    const autoMergeSourceLabel = options.autoMergeSource === 'flag' ? '--auto-merge flag' : '.haystack.json';
     if (options.autoMerge) {
         try {
             await ensureHaystackLabels(remoteInfo.owner, remoteInfo.repo, ['haystack:auto-merge'], githubToken);
             await addLabelsToIssue(remoteInfo.owner, remoteInfo.repo, prNumber, ['haystack:auto-merge'], githubToken);
+            autoMergeApplied = true;
             // With --review, the PR still enters the auto-merge queue but the
             // merge queue's needs-review gate holds it until a human approves
             // (removes haystack:needs-review or marks it reviewed). Don't print a
             // bare "Auto-merge enabled" that reads as if it'll merge unreviewed.
             if (options.review) {
-                console.log(chalk.green('✓ Auto-merge enabled (held until a human approves this PR)'));
+                console.log(chalk.green(`✓ Auto-merge enabled via ${autoMergeSourceLabel} (held until a human approves this PR)`));
             }
             else {
-                console.log(chalk.green('✓ Auto-merge enabled for this PR'));
+                console.log(chalk.green(`✓ Auto-merge enabled for this PR (via ${autoMergeSourceLabel})`));
             }
         }
         catch (err) {
             console.log(chalk.yellow(`⚠ Could not set auto-merge label: ${err.message}`));
         }
     }
+    else {
+        console.log(chalk.dim(`  Auto-merge: disabled (via ${autoMergeSourceLabel})`));
+    }
     // -------------------------------------------------------------------------
     // Step 6b: Apply auto-fix label if --auto-fix
     // -------------------------------------------------------------------------
@@ -455,7 +527,8 @@ export async function submitCommand(options) {
         try {
             await ensureHaystackLabels(remoteInfo.owner, remoteInfo.repo, ['haystack:auto-fix'], githubToken);
             await addLabelsToIssue(remoteInfo.owner, remoteInfo.repo, prNumber, ['haystack:auto-fix'], githubToken);
-            console.log(chalk.green('✓ Auto-fix (alpha) enabled for this PR'));
+            autoFixApplied = true;
+            console.log(chalk.green(`✓ Auto-fix (alpha) enabled for this PR (via ${options.autoFixSource === 'flag' ? '--auto-fix flag' : '.haystack.json'})`));
         }
         catch (err) {
             console.log(chalk.yellow(`⚠ Could not set auto-fix label: ${err.message}`));
@@ -468,9 +541,11 @@ export async function submitCommand(options) {
         try {
             await ensureHaystackLabels(remoteInfo.owner, remoteInfo.repo, ['haystack:needs-review'], githubToken);
             await addLabelsToIssue(remoteInfo.owner, remoteInfo.repo, prNumber, ['haystack:needs-review'], githubToken);
+            reviewLabelApplied = true;
             if (typeof options.review === 'string') {
                 // Specific reviewer requested
                 await requestReviewers(remoteInfo.owner, remoteInfo.repo, prNumber, [options.review], githubToken);
+                reviewerRequestedOk = options.review;
                 console.log(chalk.green(`✓ Review requested from ${options.review}`));
             }
             else {
@@ -486,9 +561,9 @@ export async function submitCommand(options) {
     // Step 8: Success!
     // -------------------------------------------------------------------------
     console.log(chalk.green('\n' + '━'.repeat(50)));
-    console.log(chalk.bold.green('\nPull Request Created!\n'));
+    console.log(chalk.bold.green(existingPR ? '\nPull Request Updated!\n' : '\nPull Request Created!\n'));
     console.log(`  ${chalk.dim('URL:')}    ${chalk.cyan(prUrl)}`);
-    console.log(`  ${chalk.dim('Title:')}  ${options.title || getLastCommitMessage()}`);
+    console.log(`  ${chalk.dim('Title:')}  ${prTitle}`);
     console.log(`  ${chalk.dim('Branch:')} ${currentBranch} → ${baseBranch}`);
     if (options.autoMerge) {
         // --review and auto-merge are not contradictory: the PR is queued but the
@@ -526,10 +601,42 @@ export async function submitCommand(options) {
         status: 'polling',
     };
     savePendingSubmit(pendingState, gitRoot);
+    const ref = `${remoteInfo.owner}/${remoteInfo.repo}#${prNumber}`;
+    /** Emit the final --json payload (stdout) — the single machine-readable
+     *  document of the run. `next` always tells the agent the follow-up command. */
+    const emitPayload = (analysis) => {
+        if (!options.json)
+            return;
+        process.stdout.write(JSON.stringify(withSchema('submit', {
+            status: existingPR ? 'already_exists' : 'created',
+            ref,
+            pr_number: prNumber,
+            url: prUrl,
+            title: prTitle,
+            title_source: titleSource,
+            body: prBody,
+            body_source: bodySource,
+            branch: currentBranch,
+            base: baseBranch,
+            draft: options.draft ?? false,
+            account: activeGitHubLogin ?? null,
+            // Applied state, not requested state: if a label failed to apply, the
+            // payload says so (enabled: false) even though it was asked for.
+            auto_merge: { enabled: autoMergeApplied, source: options.autoMergeSource ?? 'config' },
+            auto_fix: { enabled: autoFixApplied, source: options.autoFixSource ?? 'config' },
+            review_requested: reviewLabelApplied
+                ? { reviewer: reviewerRequestedOk }
+                : null,
+            triage: { status: triageStatus },
+            analysis,
+            next: analysis.status === 'pending' ? `haystack triage ${ref} --json` : null,
+        }), null, 2) + '\n');
+    };
     // If --no-wait or non-interactive, exit here
     if (options.wait === false || !process.stdin.isTTY) {
-        console.log(chalk.dim('\nAnalysis running in background.'));
-        console.log(chalk.dim('Check results later with: ') + chalk.cyan('haystack triage\n'));
+        console.log(chalk.dim(`\nAnalysis running in background${options.wait === false ? '' : ' (no TTY — not waiting inline)'}.`));
+        console.log(chalk.dim('Check results later with: ') + chalk.cyan(`haystack triage ${ref}\n`));
+        emitPayload({ status: 'pending', verdict: null, merged: false, summary: null });
         return;
     }
     // Wait for analysis inline by polling the result endpoint
@@ -539,7 +646,8 @@ export async function submitCommand(options) {
     const sigintHandler = () => {
         interrupted = true;
         console.log(chalk.dim('\n\nAnalysis still running. Check later with:'));
-        console.log(chalk.cyan('  haystack triage\n'));
+        console.log(chalk.cyan(`  haystack triage ${ref}\n`));
+        emitPayload({ status: 'pending', verdict: null, merged: false, summary: null });
         process.exit(0);
     };
     process.on('SIGINT', sigintHandler);
@@ -548,6 +656,7 @@ export async function submitCommand(options) {
     const deadline = Date.now() + POLL_TIMEOUT;
     let consecutiveErrors = 0;
     const MAX_CONSECUTIVE_ERRORS = 5;
+    let emitted = false;
     while (Date.now() < deadline && !interrupted) {
         const result = await checkAnalysisReady(remoteInfo.owner, remoteInfo.repo, prNumber, githubToken);
         if (result.status === 'ready') {
@@ -608,10 +717,33 @@ export async function submitCommand(options) {
                 if (!options.autoFix || verdict.state === 'good-to-merge') {
                     console.log(`\n  ${chalk.dim('Review:')} ${chalk.cyan(verdict.reviewUrl)}\n`);
                 }
+                emitPayload({
+                    status: 'complete',
+                    // Same public vocabulary as `triage --json` / `pr get --json`.
+                    verdict: verdict.state === 'good-to-merge'
+                        ? 'good_to_merge'
+                        : verdict.needsHumanReview ? 'needs_review' : 'needs_input',
+                    merged: verdict.autoMerged ?? false,
+                    summary: verdict.summary,
+                });
+                emitted = true;
             }
-            catch {
-                console.log(chalk.yellow('⚠ Analysis complete but could not fetch results.'));
-                console.log(chalk.dim('  Check results at: ') + chalk.cyan(prUrl) + '\n');
+            catch (err) {
+                const message = err.message;
+                if (err instanceof HaystackApiError && err.isAuthError) {
+                    // Auth failure is not transient — retrying `haystack triage` with the
+                    // same credential would fail identically. Report failed + exit 1.
+                    console.error(chalk.red(`\n  ${message}`));
+                    emitPayload({ status: 'failed', verdict: null, merged: false, summary: message });
+                    process.exitCode = 1;
+                }
+                else {
+                    // The PR exists and analysis completed — only the result fetch failed.
+                    console.log(chalk.yellow(`⚠ Analysis complete but could not fetch results: ${message}`));
+                    console.log(chalk.dim('  Check results with: ') + chalk.cyan(`haystack triage ${ref}\n`));
+                    emitPayload({ status: 'pending', verdict: null, merged: false, summary: message });
+                }
+                emitted = true;
             }
             break;
         }
@@ -620,19 +752,27 @@ export async function submitCommand(options) {
             if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
                 console.log(chalk.red(`\n  Analysis check failed: ${result.message}`));
                 updatePendingSubmit({ status: 'failed', resolvedAt: new Date().toISOString() }, gitRoot);
+                emitPayload({ status: 'failed', verdict: null, merged: false, summary: result.message ?? null });
+                emitted = true;
+                // The PR was created, but the caller asked us to wait for a verdict
+                // and we could not deliver one — that is a failure, not a success.
+                process.exitCode = 1;
                 break;
             }
         }
         else {
             consecutiveErrors = 0;
         }
-        process.stdout.write(`\r  ${chalk.dim('Status:')} Waiting for analysis...${'  '.repeat(10)}`);
+        process.stderr.write(`\r  ${chalk.dim('Status:')} Waiting for analysis...${'  '.repeat(10)}`);
         await new Promise(r => setTimeout(r, POLL_INTERVAL));
     }
     // Clean up SIGINT handler
     process.removeListener('SIGINT', sigintHandler);
     if (Date.now() >= deadline && !interrupted) {
         console.log(chalk.yellow('\n\n  Timed out waiting for analysis.'));
-        console.log(chalk.dim('  Check results later with: ') + chalk.cyan('haystack triage\n'));
+        console.log(chalk.dim('  Check results later with: ') + chalk.cyan(`haystack triage ${ref}\n`));
+        if (!emitted) {
+            emitPayload({ status: 'pending', verdict: null, merged: false, summary: 'Timed out waiting for analysis; it continues server-side.' });
+        }
     }
 }

package/dist/commands/system-map.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `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.
+ */
+export interface SystemMapIssue {
+    severity: 'error' | 'warning';
+    path: string;
+    message: string;
+}
+export interface SystemMapSummary {
+    setup_steps: number;
+    toolchain_entries: number;
+    services: string[];
+    personas: string[];
+    data_commands: number;
+    observability_entries: number;
+    external_services: string[];
+    testing_entries: number;
+    constraints: number;
+    artifacts: string[];
+}
+export declare function validateSystemMapText(rawYaml: string): {
+    issues: SystemMapIssue[];
+    summary: SystemMapSummary | null;
+};
+export declare function systemMapValidateCommand(options: {
+    json?: boolean;
+}): Promise<void>;