fix(task): enforce group concurrency at dequeue time

[moshloop]

What

• Move semaphore acquisition from task function wrapper to worker dequeue time
• Set parent group via withParent option before task enqueue
• Add PrettyShort interface for compact cell rendering
• Add ClickyDocument and ClickyText for direct Textable serialization
• Export clicky* types to support external consumption
• Add JSON field to Link struct with structured serialization

Why

• Prevents worker slots from being blocked on group semaphores
• Allows independent tasks to run while concurrency-limited group is busy
• Fixes deadlock risk when concurrency=1 and prevents worker starvation
• Preserves rich formatting (code blocks, collapsibles, tables) without flattening
• Enables structured-JSON consumers to render links as anchors with metadata

Notes

• Adds TestGroupConcurrencySlots to verify independent task concurrency
• Comprehensive tests for Link.MarshalJSON, PrettyShort precedence, and JSON round-trip fidelity
• Updates TryTypedValue to check Pretty before Textable for proper method precedence

Summary by CodeRabbit

• New Features

  • Added admonition callouts with severity levels (note, tip, warning, danger) supporting formatted headers and bodies.
  • Compact field rendering support for tables via PrettyShort.
  • Optional positional ID support for action commands.
  • Structured Clicky JSON document output preserving rich formatting.
  • OpenAPI parameter role detection for enhanced UI rendering.

• Bug Fixes

  • Improved error rendering to preserve rich formatting through the standard output pipeline.
  • Fixed Markdown table pipe character escaping to prevent layout issues.
  • Enhanced task group concurrency handling.

• Documentation

  • Substantially rewrote README with usage examples, installation instructions, and API patterns.

[coderabbitai]

Warning

Review limit reached

@moshloop, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 46 minutes and 40 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 431739ca-797a-420f-9bb5-665c1fd16b3f

📥 Commits

Reviewing files that changed from the base of the PR and between b21bc8a and 5c5c408.

📒 Files selected for processing (32)

• api/admonition.go
• api/admonition_test.go
• api/column.go
• api/keyed.go
• api/keyed_test.go
• api/link.go
• api/link_test.go
• api/meta.go
• api/meta_test.go
• api/parse_tags.go
• api/parser.go
• api/table.go
• api/table_test.go
• api/types.go
• cobra_command.go
• entity.go
• flags/request.go
• flags/request_test.go
• format.go
• formatters/clicky_document.go
• formatters/clicky_document_test.go
• formatters/html_react_formatter.go
• formatters/html_react_formatter_test.go
• rpc/openapi.go
• rpc/openapi_test.go
• sub_command.go
• sub_command_test.go
• task/group.go
• task/group_concurrency_test.go
• task/options.go
• task/task.go
• task/worker.go

Walkthrough

This PR introduces substantial enhancements to clicky's rendering infrastructure, task execution model, and RPC command handling. New callout, keyed wrapper, and document types enrich the rendering system. A PrettyShort interface enables compact field rendering, while improved error handling formats rich errors through the standard rendering pipeline. Task concurrency is refactored to defer semaphore acquisition to worker dequeue time, preventing slot starvation. A new request-based flag population function enables clean RPC HTTP execution without mutating Cobra state. Entity actions gain optional ID support, filter definitions can be lifted from nested options, and subcommands support slash-delimited paths. OpenAPI generation now includes UI routing metadata for parameter roles, and the Swagger server becomes more composable with configurable path prefixes and exported handlers.

Changes

Rendering, Concurrency, and RPC Infrastructure

Layer / File(s)	Summary
Admonition callout type and renderers api/admonition.go, api/admonition_test.go	Introduces Severity enum with icon mappings and Admonition struct with String, ANSI, HTML, Markdown renderers for styled callout blocks with optional title and body.
Keyed wrapper and Link JSON serialization api/keyed.go, api/keyed_test.go, api/link.go, api/link_test.go, format.go	Adds Keyed type wrapping Textable with a stable key for JSON object field serialization; extends Link with optional JSON payload and MarshalJSON for structured output; exports WithKey helper.
Clicky document structuring and type export formatters/clicky_document.go, formatters/clicky_document_test.go, formatters/html_react_formatter.go, formatters/html_react_formatter_test.go	Introduces NewClickyDocument and ClickyText wrapper for versioned JSON document generation; exports previously unexported Clicky* types (ClickyDocument, ClickyNode, ClickyField, ClickyColumn, ClickyRow, ClickyTreeItem, ClickyStackFrame, ClickyStyle) for public API access.
PrettyShort interface and short-form rendering api/types.go, api/meta.go, api/parse_tags.go, api/parser.go, api/column.go, api/meta_test.go, entity.go	Adds PrettyShort interface for compact single-line rendering; extends FieldMeta.Short and PrettyField.Short flags; updates tag parser to recognize short; refines TryTypedValue to prioritize Pretty over Textable; integrates short rendering into schema parsing and pretty-row rendering.
Markdown table pipe escaping api/table.go, api/table_test.go	Escapes literal pipe characters in Markdown table cells with escapeMarkdownPipes helper to prevent unintended GFM table layout disruption.
Renderable error detection and formatting cobra_command.go, cobra_command_test.go	Adds renderableError helper that walks the Unwrap chain to detect errors implementing clicky rendering interfaces (api.TryTypedValue); formats matching errors through PrintAndWriteSinks instead of plain logging.
Worker-level task concurrency gating task/group.go, task/worker.go, task/options.go, task/task.go, task/group_concurrency_test.go, task/task_status_test.go	Refactors task concurrency enforcement from in-method semaphore wrapping to dequeue-time TryAcquire(1) in the worker loop; adds withParent option to link tasks before enqueueing; defers permit release to ensure cleanup on all exit paths; prevents worker-slot starvation.
Request-based flag population for RPC flags/request.go, flags/request_test.go	Implements PopulateFromRequest to parse HTTP request flag maps and args into struct fields via reflection, supporting scalars, slices (with CSV expansion and file/URL loading), duration.Duration, and time.Time without mutating shared Cobra/pflag state; includes comprehensive concurrency and state-leak tests.
Filter lifting and optional ID support for actions entity.go, entity_filters_test.go	Introduces Filterable[T] interface and LiftFilters function to project nested filter definitions; adds OptionalID field to ActionInfo with WithOptionalID() builder; updates generateIDCommand to support optional [id] syntax and skip missing-id validation when enabled.
Cobra command wiring for filters and RPC execution cobra_command.go	Updates AddNamedCommand to detect Filterable[T] opts, derive subcommand filters, register lookup functions, and wire shell completions; refactors dataFuncRegistry RPC handler to capture fieldInfos and use PopulateFromRequest instead of mutating Cobra flags and accessing pre-bound flagValues.
Slash-delimited subcommand path resolution sub_command.go, sub_command_test.go	Extends RegisterSubCommand to support slash-delimited parent paths (e.g., xero/accounts, billing/policy), auto-creating intermediate grouping nodes and enabling hierarchical subcommand organization.
OpenAPI parameter metadata and UI roles rpc/openapi.go, rpc/openapi_test.go	Adds ClickyParameterMeta with role field to OpenAPI parameters; introduces paramRole classifier assigning pagination (limit, offset), time-range (time-from, time-to), and filter roles to query parameters for UI-driven widget selection; adds GenerateFromCobraWithConfig for configurable spec generation.
RPC converter and server configuration updates rpc/converter.go, rpc/serve.go	Updates converter to suppress duplicate entity list commands when parent is runnable; configures SwaggerServer to respect executor PathPrefix during converter initialization and OpenAPI generation; adds exported handler wrappers (HandleOpenAPIJSON, HandleOpenAPIYAML, HandleEntities, HandleHealth) and route registration helpers (ConverterConfig, RegisterExecutionRoutes).
README refactor and dependency updates README.md, go.mod, examples/go.mod	Rewrites README with concise usage-oriented sections covering library formatting/tasks, CLI binding, OpenAPI/extensions, middleware, and schema formatting; updates Go toolchain to 1.26.1 and advances direct and indirect dependencies for Flanksource libraries, OpenTelemetry, Kubernetes, and ecosystem tools.

Possibly related PRs

• flanksource/clicky#102: Adds renderableError helper walking Unwrap chain with api.TryTypedValue to format rich errors through the --format pipeline, matching the error handling enhancement in this PR.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/task-group-concurrency-dequeue

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch fix/task-group-concurrency-dequeue

[flankbot]

🎉 This PR is included in version 1.21.11