Skip to content

feat: add entity response types, task stderr gating, and stack trace support#101

Merged
moshloop merged 7 commits intomainfrom
feat/entity-responses-task-gating-stacktrace
May 1, 2026
Merged

feat: add entity response types, task stderr gating, and stack trace support#101
moshloop merged 7 commits intomainfrom
feat/entity-responses-task-gating-stacktrace

Conversation

@moshloop
Copy link
Copy Markdown
Member

@moshloop moshloop commented May 1, 2026

What

  • Add typed response types (R parameter) to Entity with EntityBuilder fluent API
  • Replace Action/BulkAction structs with factory functions returning interfaces
  • Add HTTP method override support for entity operations
  • Introduce task renderer stderr gating to prevent output corruption
  • Add comprehensive stack trace parsing and rendering with source resolution
  • Add hidden _id column support for wrapped entities
  • Add MultiFilter type for comma-separated flag values

Why

  • Enable accurate OpenAPI schema generation for entity responses
  • Improve ergonomics of entity registration with type safety
  • Allow fine-grained control over operation HTTP semantics
  • Prevent interactive renderer frame corruption from concurrent stderr writes
  • Support debugging with formatted stack traces and source context

Breaking Changes

  • Entity type signature: Entity[T, ListOpts]Entity[T, ListOpts, R]
  • Action and BulkAction are now factory functions; update definitions to use Action(), ActionWithFlags(), BulkAction(), BulkFilterAction(), or BulkActionWithFilter()

Notes

  • Replaces Swagger UI with Scalar API reference in documentation
  • Updates example entity demo to use new builder API

Summary by CodeRabbit

Release Notes

  • New Features

    • Stack trace parsing and rendering with source context, including Java stack trace support with exception handling and frame filtering
    • Multi-filter support for entity filtering operations
    • Typed entity builder API for improved type safety during entity registration
    • Switched API documentation interface from Swagger UI to Scalar for better usability
  • Bug Fixes

    • Fixed handling of hidden columns in entity table rows
    • Improved stderr output gating to prevent log corruption during interactive rendering
  • Tests

    • Added comprehensive test coverage for stack trace parsing, rendering, and entity operations
    • Added OpenAPI schema generation tests with type reflection validation

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 1, 2026

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 399886b0-04ca-4c07-8f0c-23bd40c4310a

📥 Commits

Reviewing files that changed from the base of the PR and between d0c18fe and 682f539.

⛔ Files ignored due to path filters (3)
  • examples/enitity/webapp/pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
  • examples/go.sum is excluded by !**/*.sum
  • examples/uber_demo/go.sum is excluded by !**/*.sum
📒 Files selected for processing (39)
  • .gitignore
  • ai/cache/cache.go
  • api/column.go
  • api/stacktrace.go
  • api/stacktrace_java.go
  • api/stacktrace_test.go
  • cobra_command.go
  • entity.go
  • entity_annotations.go
  • entity_builder.go
  • entity_filters_test.go
  • entity_test.go
  • examples/enitity/Taskfile.yaml
  • examples/enitity/main.go
  • examples/enitity/webapp/index.html
  • examples/enitity/webapp/package.json
  • examples/enitity/webapp/pnpm-workspace.yaml
  • examples/enitity/webapp/tsconfig.json
  • examples/uber_demo/go.mod
  • flags/assignment.go
  • format.go
  • formatters/html_react_formatter.go
  • multi_filter.go
  • response_meta.go
  • rpc/assets/index.html
  • rpc/converter.go
  • rpc/entities_test.go
  • rpc/filter_lookup_test.go
  • rpc/openapi.go
  • rpc/openapi_reflect.go
  • rpc/openapi_test.go
  • rpc/serve.go
  • rpc/serve_test.go
  • rpc/types.go
  • sub_command.go
  • sub_command_test.go
  • task/manager_lifecycle.go
  • task/stderr_gate.go
  • task/stderr_gate_test.go

Walkthrough

Pull request adds stack trace parsing and rendering (Java-specific), implements typed action/bulk action registration with generic response types, adds response metadata tracking for OpenAPI schema generation, introduces a GatedStderr writer for interactive rendering control, and switches API documentation from Swagger UI to Scalar.

Changes

Cohort / File(s) Summary
Stack Trace Support
api/stacktrace.go, api/stacktrace_java.go, api/stacktrace_test.go, format.go
New stack trace model with Java parser, rendering with optional source context, and public API surface exposing SourceResolver and option constructors for customization.
Entity Typed Generics
entity.go, entity_builder.go, cobra_command.go, entity_annotations.go
Large refactor adding typed Entity[T, ListOpts, R] generics, fluent EntityBuilder constructor, typed EntityAction/EntityBulkAction registration with option-based configuration, and HTTP method annotation support for operations.
Response Metadata & OpenAPI Schema
response_meta.go, rpc/types.go, rpc/converter.go, rpc/openapi.go, rpc/openapi_reflect.go
New static command metadata registry tracking response type, array, and entity-id flags; reflection-based OpenAPI schema generation handling Go primitives, structs, arrays, maps, and time.Time with cycle detection and nullable/required field inference.
Interactive Rendering Control
task/manager_lifecycle.go, task/stderr_gate.go, task/stderr_gate_test.go, ai/cache/cache.go
Adds GatedStderr() writer that conditionally gates stderr output when interactive rendering owns the terminal, with debug output routing updated to use this gate and tests validating per-write state checks.
API Documentation & UI
rpc/assets/index.html, rpc/serve.go, rpc/serve_test.go, rpc/openapi_test.go
Switches embedded UI from Swagger to Scalar with dynamic refresh support and header rework; adds OpenAPI entity response schema tests validating array/nested field/hidden field handling.
Column & Filter Handling
api/column.go, multi_filter.go, formatters/html_react_formatter.go
Hidden columns now store values in rows when present in data; new MultiFilter type alias added; HTML React formatter includes unmapped row cells in output.
Entity Tests & Infrastructure
entity_filters_test.go, entity_test.go, sub_command_test.go, rpc/entities_test.go, rpc/filter_lookup_test.go, flags/assignment.go
Updated test registrations for new generic signatures, added hidden column metadata tests, explicit HTTP method tests, and type conversion helpers for slice assignments.
Example Application Updates
examples/enitity/Taskfile.yaml, examples/enitity/main.go, examples/enitity/webapp/*
Created Task build/run workflow, added web app scaffolding (HTML entry, TypeScript config, package.json with React/Tailwind/Radix deps), and refactored demo store methods to return concrete types instead of any.
.gitignore
.gitignore
Unignored tracked files under examples/enitity/ (Taskfile.yaml, webapp configs, dist directory).
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/entity-responses-task-gating-stacktrace
✨ Simplify code
  • Create PR with simplified code
  • Commit simplified code in branch feat/entity-responses-task-gating-stacktrace

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share
Review rate limit: 0/1 reviews remaining, refill in 60 minutes.

Comment @coderabbitai help to get the list of available commands and usage tips.

moshloop added 6 commits May 1, 2026 09:14
Add support for including a hidden _id column in table rows for wrapped entities (entityWithID). The _id column is automatically added to the Columns() output and included in Row() and PrettyRow() data, but marked as hidden so it doesn't appear as a visible column in the UI.

This allows the _id metadata to be available in row data while keeping the table display clean. Updates the HTML React formatter to handle cells that exist in row data but not in the column definitions.

Adds comprehensive test coverage for all entity types (TableProvider, PrettyRow, and plain structs) to verify the _id column is properly included in the output data but hidden from the visible columns.

Refs: entity wrapping, table formatting
…r entities

Introduce a third generic type parameter R to Entity for specifying response types returned by Get/Create/Update operations. This enables accurate OpenAPI schema generation for entity responses.

Add EntityBuilder fluent API for ergonomic entity registration with type safety. Replace Action and BulkAction struct types with factory functions (Action, ActionWithFlags, BulkAction, BulkFilterAction, BulkActionWithFilter) that return interface-based specs with builder methods.

Add ResponseOpenAPIMeta registry to track static response types for commands, enabling OpenAPI generation without executing handlers. Update OpenAPI generator to reflect Go types in response schemas, including support for arrays, nested objects, time.Time formatting, and field-level JSON/pretty tags.

Update example entity demo to use new builder API and typed responses. Replace Swagger UI with Scalar API reference in documentation server.

BREAKING CHANGE: Entity type signature changed from Entity[T, ListOpts] to Entity[T, ListOpts, R]. Action and BulkAction are now factory functions returning interface types; update action definitions to use Action(), ActionWithFlags(), BulkAction(), BulkFilterAction(), or BulkActionWithFilter().
Add examples/enitity/webapp/dist/ to gitignore to prevent build artifacts from being tracked in version control.
Add optional Method field to EntityOperation and ActionInfo to allow explicit HTTP method specification for generated RPC/OpenAPI routes. This enables actions to override the default inferred HTTP method (e.g., using GET for a records action instead of the inferred POST).

The Method field is propagated through the command annotation system and checked during HTTP method inference in the RPC converter, allowing fine-grained control over operation semantics.

Includes test coverage for entity actions with explicit GET method using nested entity paths.
…e render

Introduce IsInteractiveRenderActive() to check if the task renderer owns the TTY, and GatedStderr() writer that silently drops writes when interactive rendering is active. This allows callers that emit to stderr (e.g., loggers, debug prints) to avoid corrupting the renderer's in-place frame without requiring explicit coordination.

The gating is stateless and rechecks ownership per write, enabling writers captured before rendering starts to still gate correctly when the renderer later acquires the TTY.
Introduce comprehensive stack trace support with language-agnostic parsing, styled rendering, and extensible source resolution. Adds StackTrace, StackFrame types and ParseJavaStackTrace parser to api package, with public convenience wrappers in clicky root. Includes support for frame filtering, context lines, and max frame truncation.

Also adds MultiFilter type for comma-separated flag values with include/exclude semantics, and fixes field value assignment to support type conversion in flags package.

Updates cache debug output to use task.GatedStderr() instead of os.Stderr to prevent log lines from breaking interactive renderer frame accounting. Fixes recursive struct handling in OpenAPI schema generation by tracking visited types.

Refs: stack trace rendering, source context, Java exception parsing
@moshloop moshloop force-pushed the feat/entity-responses-task-gating-stacktrace branch from 10a88bb to 703988a Compare May 1, 2026 06:15
@moshloop moshloop enabled auto-merge (rebase) May 1, 2026 06:15
@moshloop moshloop disabled auto-merge May 1, 2026 06:17
Update documentation and test examples to use generic package names (com.example.admin) instead of specific internal package names (com.adminserver). This makes the codebase more suitable for public documentation and examples without exposing internal naming conventions.
@moshloop moshloop enabled auto-merge (squash) May 1, 2026 08:31
@moshloop moshloop disabled auto-merge May 1, 2026 08:31
@moshloop moshloop merged commit 0a2d157 into main May 1, 2026
11 of 14 checks passed
@moshloop moshloop deleted the feat/entity-responses-task-gating-stacktrace branch May 1, 2026 08:31
flankbot pushed a commit that referenced this pull request May 1, 2026
## [1.21.8](v1.21.7...v1.21.8) (2026-05-01)

### ⚠ BREAKING CHANGES

* Entity type signature changed from Entity[T, ListOpts] to Entity[T, ListOpts, R]. Action and BulkAction are now factory functions returning interface types; update action definitions to use Action(), ActionWithFlags(), BulkAction(), BulkFilterAction(), or BulkActionWithFilter().

* chore(gitignore): ignore entity webapp dist directory

Add examples/enitity/webapp/dist/ to gitignore to prevent build artifacts from being tracked in version control.

* feat(entity): Add explicit HTTP method override for entity operations

Add optional Method field to EntityOperation and ActionInfo to allow explicit HTTP method specification for generated RPC/OpenAPI routes. This enables actions to override the default inferred HTTP method (e.g., using GET for a records action instead of the inferred POST).

The Method field is propagated through the command annotation system and checked during HTTP method inference in the RPC converter, allowing fine-grained control over operation semantics.

Includes test coverage for entity actions with explicit GET method using nested entity paths.

* feat(task): Add stderr gating to prevent corruption during interactive render

Introduce IsInteractiveRenderActive() to check if the task renderer owns the TTY, and GatedStderr() writer that silently drops writes when interactive rendering is active. This allows callers that emit to stderr (e.g., loggers, debug prints) to avoid corrupting the renderer's in-place frame without requiring explicit coordination.

The gating is stateless and rechecks ownership per write, enabling writers captured before rendering starts to still gate correctly when the renderer later acquires the TTY.

* feat(api): add stack trace parsing and rendering with source resolution

Introduce comprehensive stack trace support with language-agnostic parsing, styled rendering, and extensible source resolution. Adds StackTrace, StackFrame types and ParseJavaStackTrace parser to api package, with public convenience wrappers in clicky root. Includes support for frame filtering, context lines, and max frame truncation.

Also adds MultiFilter type for comma-separated flag values with include/exclude semantics, and fixes field value assignment to support type conversion in flags package.

Updates cache debug output to use task.GatedStderr() instead of os.Stderr to prevent log lines from breaking interactive renderer frame accounting. Fixes recursive struct handling in OpenAPI schema generation by tracking visited types.

Refs: stack trace rendering, source context, Java exception parsing

* docs(api): replace example package names with generic examples

Update documentation and test examples to use generic package names (com.example.admin) instead of specific internal package names (com.adminserver). This makes the codebase more suitable for public documentation and examples without exposing internal naming conventions.

### ✨ Features

* add entity response types, task stderr gating, and stack trace support ([#101](#101)) ([0a2d157](0a2d157))
@flankbot
Copy link
Copy Markdown

flankbot commented May 1, 2026

🎉 This PR is included in version 1.21.8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants