[PR #149] [MERGED] feat: add preflight validation phase with structured error reporting #144

New issue

Closed

opened 2026-02-27 08:09:26 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 08:09:26 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/KeygraphHQ/shannon/pull/149
Author: @ajmallesh
Created: 2/20/2026
Status: ✅ Merged
Merged: 2/20/2026
Merged by: @ezl-keygraph

Base: main ← Head: fix/preflight-validation

📝 Commits (4)

f0f18b5 feat: add preflight validation phase with structured error reporting
d7c3ed8 refactor: extract error formatting utilities from workflows.ts into workflow-errors.ts
9e2f80b refactor: replace HTTP credential checks with Claude Agent SDK query
b0887e9 refactor: use SDK-exported SDKAssistantMessageError instead of local type definition

📊 Changes

9 files changed (+479 additions, -13 deletions)

View changed files

📝 src/ai/message-handlers.ts (+1 -1)
📝 src/ai/types.ts (+2 -8)
📝 src/audit/workflow-logger.ts (+19 -1)
📝 src/services/error-handling.ts (+10 -0)
➕ src/services/preflight.ts (+253 -0)
📝 src/temporal/activities.ts (+68 -0)
➕ src/temporal/workflow-errors.ts (+94 -0)
📝 src/temporal/workflows.ts (+27 -3)
📝 src/types/errors.ts (+5 -0)

📄 Description

Summary

Preflight validation phase — New runPreflightValidation activity runs before any agent execution, validating repo path exists with .git, config file parses correctly (if provided), and credentials work (API key, OAuth token, or router mode). Fails fast with actionable errors before committing to the pipeline.

Structured error formatting — Replaced single-line error strings with pipe-delimited segments that WorkflowLogger.formatErrorBlock() renders as indented multi-line blocks. Each error now includes: phase context, error type, message, and remediation hint.

Remediation hints — Added REMEDIATION_HINTS mapping for common failure types (AuthenticationError, ConfigurationError, BillingError, etc.) so users immediately know what to check when runs fail.

Error classification — Added REPO_NOT_FOUND, AUTH_FAILED, and BILLING_ERROR codes to the ErrorCode enum with proper classification in error-handling.ts.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/KeygraphHQ/shannon/pull/149 **Author:** [@ajmallesh](https://github.com/ajmallesh) **Created:** 2/20/2026 **Status:** ✅ Merged **Merged:** 2/20/2026 **Merged by:** [@ezl-keygraph](https://github.com/ezl-keygraph) **Base:** `main` ← **Head:** `fix/preflight-validation` --- ### 📝 Commits (4) - [`f0f18b5`](https://github.com/KeygraphHQ/shannon/commit/f0f18b5e0abad10f6f39f88c57ef680fd712c552) feat: add preflight validation phase with structured error reporting - [`d7c3ed8`](https://github.com/KeygraphHQ/shannon/commit/d7c3ed8be33e8a301855e596815ec9c0f85c3029) refactor: extract error formatting utilities from workflows.ts into workflow-errors.ts - [`9e2f80b`](https://github.com/KeygraphHQ/shannon/commit/9e2f80b35b945cc79e85e1d4853d10e7c03eef62) refactor: replace HTTP credential checks with Claude Agent SDK query - [`b0887e9`](https://github.com/KeygraphHQ/shannon/commit/b0887e9d73d3f9a118198e30495a4583dcf6bb92) refactor: use SDK-exported SDKAssistantMessageError instead of local type definition ### 📊 Changes **9 files changed** (+479 additions, -13 deletions) <details> <summary>View changed files</summary> 📝 `src/ai/message-handlers.ts` (+1 -1) 📝 `src/ai/types.ts` (+2 -8) 📝 `src/audit/workflow-logger.ts` (+19 -1) 📝 `src/services/error-handling.ts` (+10 -0) ➕ `src/services/preflight.ts` (+253 -0) 📝 `src/temporal/activities.ts` (+68 -0) ➕ `src/temporal/workflow-errors.ts` (+94 -0) 📝 `src/temporal/workflows.ts` (+27 -3) 📝 `src/types/errors.ts` (+5 -0) </details> ### 📄 Description ## Summary **Preflight validation phase** — New `runPreflightValidation` activity runs before any agent execution, validating repo path exists with `.git`, config file parses correctly (if provided), and credentials work (API key, OAuth token, or router mode). Fails fast with actionable errors before committing to the pipeline. **Structured error formatting** — Replaced single-line error strings with pipe-delimited segments that `WorkflowLogger.formatErrorBlock()` renders as indented multi-line blocks. Each error now includes: phase context, error type, message, and remediation hint. **Remediation hints** — Added `REMEDIATION_HINTS` mapping for common failure types (AuthenticationError, ConfigurationError, BillingError, etc.) so users immediately know what to check when runs fail. **Error classification** — Added `REPO_NOT_FOUND`, `AUTH_FAILED`, and `BILLING_ERROR` codes to the `ErrorCode` enum with proper classification in `error-handling.ts`. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

kerem

2026-02-27 08:09:26 +03:00

closed this issue
added the
pull-request
label

No labels

pull-request

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/shannon-KeygraphHQ#144

No description provided.

Rows
Columns