Skip to content

feat: add error handling guidance to generated ORM AGENTS.md#939

Merged
pyramation merged 2 commits intomainfrom
devin/1774942498-codegen-error-handling-headers
Mar 31, 2026
Merged

feat: add error handling guidance to generated ORM AGENTS.md#939
pyramation merged 2 commits intomainfrom
devin/1774942498-codegen-error-handling-headers

Conversation

@pyramation
Copy link
Copy Markdown
Contributor

@pyramation pyramation commented Mar 31, 2026

Summary

Adds an Error Handling section to the generated ORM AGENTS.md (produced by generateOrmAgentsDocs in docs-generator.ts). This addresses a recurring issue where AI agents wrap .execute() in try/catch and silently swallow errors, because .execute() returns a discriminated union ({ ok, data, errors }) and never throws.

The new section includes:

  • A CRITICAL callout explaining the silent error trap
  • Wrong vs right code examples
  • A list of the three chained helpers (.execute().unwrap(), .execute().unwrapOr(), .execute().unwrapOrElse())

Also updates the "Stack" and "Conventions" bullets to mention .execute().unwrap() alongside .execute().

Companion PR: constructive-skills#78 adds a critical warning to the error handling skill doc.

Updates since last revision

  • Fixed helper method documentation to use the .execute().unwrap() chaining pattern (not standalone .unwrap()) per Dan's feedback
  • Updated all generated text to consistently show chaining: .execute().unwrap(), .execute().unwrapOr(default), .execute().unwrapOrElse(fn)

Review & Testing Checklist for Human

  • Verify .execute().unwrap() chaining works at runtime: The generated docs now show .execute().unwrap() as the recommended pattern. Confirm that QueryResult (returned by .execute()) actually has .unwrap(), .unwrapOr(), and .unwrapOrElse() methods — or if these are only on QueryBuilder. Cross-check query-builder.ts lines 32-104 and the QueryResult type definition.
  • Regenerate an ORM output and inspect the AGENTS.md: Run codegen against a test schema and verify the new Error Handling section renders correctly with the chaining examples.
  • Verify field names in generated examples: The generated code references result.data and result.errors — confirm these match the actual QueryResult<T> type shape (vs result.value / result.error used elsewhere in skill docs).

Notes

  • This only affects newly generated AGENTS.md files. Existing generated output will not change until codegen is re-run.
  • The generated CLI commands (table-command-generator.ts) still use .execute() inside try/catch — that's a separate issue and not addressed here.

Link to Devin session: https://app.devin.ai/sessions/41ed0f7a17024bf19180f5dcade05b76
Requested by: @pyramation

- Add Error Handling section with CRITICAL warning about silent error trap
- Show correct vs incorrect patterns (try/catch with .execute() vs .unwrap())
- Document .unwrap(), .unwrapOr(), .unwrapOrElse() helpers
- Update Stack and Conventions sections to mention .unwrap() alongside .execute()
@devin-ai-integration
Copy link
Copy Markdown
Contributor

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@pyramation pyramation merged commit c06bf0e into main Mar 31, 2026
46 checks passed
@pyramation pyramation deleted the devin/1774942498-codegen-error-handling-headers branch March 31, 2026 08:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant