docs: document 10+ undocumented module types by intel352 · Pull Request #102 · GoCodeAlone/workflow

intel352 · 2026-02-23T04:39:28Z

Summary

Adds a new Module Type Reference section to DOCUMENTATION.md with detailed configuration tables and YAML examples for every previously undocumented type
Adds summary table entries for the new Infrastructure and CI/CD Pipeline Steps categories
Covers: audit/ package, license.validator, platform.provider, platform.resource, platform.context, observability.otel, step.jq, step.ai_complete, step.ai_classify, step.ai_extract, step.docker_build, step.docker_push, step.docker_run, step.scan_sast, step.scan_container, step.scan_deps, step.artifact_push, step.artifact_pull, and the admincore plugin

Closes #66

Test plan

Read through each new documentation section and verify config key names, types, and defaults match the source code in module/, audit/, and plugins/
Confirm YAML examples are syntactically valid
Verify the summary tables include all new types
Build passes: go build ./...
Lint passes: golangci-lint run

🤖 Generated with Claude Code

#95) Verified that all JWT validation paths in JWTAuthModule already enforce HS256 via both type assertion (*jwt.SigningMethodHMAC) and explicit algorithm check (token.Method.Alg() != jwt.SigningMethodHS256.Alg()). Added tests to module/jwt_auth_test.go that explicitly confirm tokens signed with HS384 or HS512 are rejected by: - Authenticate() — the AuthProvider interface method - handleRefresh via Handle() — the /auth/refresh endpoint - extractUserFromRequest via Handle() — all protected endpoints The api package (middleware.go, auth_handler.go) already had equivalent algorithm rejection tests in auth_handler_test.go. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

#66) Adds detailed documentation for audit logging, license.validator, platform.provider/resource/context, observability.otel, step.jq, AI pipeline steps (ai_complete, ai_classify, ai_extract), CI/CD steps (docker_build, docker_push, docker_run, scan_sast, scan_container, scan_deps, artifact_push, artifact_pull), and the admincore plugin. Each entry includes config field tables with types and defaults, plus a minimal YAML example. Summary tables in the module type index are also updated with the new Infrastructure and CI/CD Step categories. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR adds comprehensive documentation for 10+ previously undocumented module types to DOCUMENTATION.md, addressing issue #66. The documentation follows the established pattern with configuration tables, descriptions, and YAML examples for each module type.

Changes:

Adds summary table entries for new Infrastructure (license.validator, platform.*) and CI/CD Pipeline Steps (Docker, scanning, artifact management) categories
Creates a new "Module Type Reference" section with detailed documentation for 19 module types/features
Includes unrelated JWT security tests that add algorithm confusion attack prevention validation

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
DOCUMENTATION.md	Adds Module Type Reference section documenting audit logging, license validator, platform modules (provider/resource/context), observability.otel, AI steps (jq, ai_complete, ai_classify, ai_extract), Docker/CI steps (build, push, run, SAST/container/deps scanning, artifact push/pull), and admincore plugin
module/jwt_auth_test.go	Adds 120+ lines of JWT algorithm confusion attack prevention tests (TestJWTAuth_Authenticate_RejectsNonHS256, TestJWTAuth_HandleRefresh_RejectsNonHS256, TestJWTAuth_ExtractUser_RejectsNonHS256) that verify HS256 enforcement

DOCUMENTATION.md

Copilot · 2026-02-23T04:45:34Z

DOCUMENTATION.md

+### `platform.context`
+
+Provides the execution context for platform operations. Used to identify the organization, environment, and tier for a deployment.
+
+**Configuration:**
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `path` | string | yes | Path identifying this context. |
+| `org` | string | no | Organization name. |
+| `environment` | string | no | Deployment environment (e.g., `production`, `staging`). |
+| `tier` | number | no | Platform tier level. |
+
+**Example:**
+
+```yaml
+modules:
+  - name: platform-ctx
+    type: platform.context
+    config:
+      path: "acme-corp/production"
+      org: "acme-corp"
+      environment: "production"
+      tier: 3
+```


The documentation shows a path config field for platform.context that does not exist in the schema definition (schema/module_schema.go:1426-1430). The schema only defines org, environment, and tier fields. Additionally, the example shows tier as a number (3), but the schema defines it as a string select field with options "infrastructure", "shared_primitive", or "application". Remove the path field and correct the tier type and example value.

module/jwt_auth_test.go

Copilot · 2026-02-23T04:45:34Z

DOCUMENTATION.md

+### `observability.otel`
+
+Initializes an OpenTelemetry distributed tracing provider that exports spans via OTLP/HTTP to a collector. Sets the global OTel tracer provider so all instrumented code in the process is covered.
+
+**Configuration:**
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `endpoint` | string | `localhost:4318` | OTLP collector endpoint (host:port). |
+| `serviceName` | string | `workflow` | Service name used for trace attribution. |
+
+**Outputs:** Provides the `tracer` service (`trace.Tracer`).
+
+**Example:**
+
+```yaml
+modules:
+  - name: tracing
+    type: observability.otel
+    config:
+      endpoint: "otel-collector:4318"
+      serviceName: "order-api"
+```


The observability.otel module factory does not read the endpoint and serviceName configuration fields from the YAML config. The factory implementation in plugins/observability/modules.go line 85 ignores the config parameter. Either the factory needs to be updated to read these fields and call SetEndpoint() and SetServiceName() on the module, or the documentation should clarify that these config fields are not currently implemented and the module uses hardcoded defaults.

Copilot · 2026-02-23T04:45:35Z

DOCUMENTATION.md

+### `platform.provider`
+
+Declares a cloud infrastructure provider (e.g., Terraform, Pulumi) for use with the platform workflow handler and reconciliation trigger.
+
+**Configuration:**
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `name` | string | yes | Provider name used to construct the service name `platform.provider.<name>`. |
+
+**Example:**
+
+```yaml
+modules:
+  - name: cloud-provider
+    type: platform.provider
+    config:
+      name: "aws"
+```
+


The platform.provider documentation is incomplete compared to the schema definition in schema/module_schema.go:1390-1401. The schema shows three config fields (name, config, and tiers), but this documentation only mentions name. The documented description also differs from the schema. Consider either documenting all three config fields or explaining that some are not yet implemented.

Copilot · 2026-02-23T04:45:35Z

DOCUMENTATION.md

+### `platform.resource`
+
+Declares an infrastructure resource managed by a platform provider. Config keys are provider-specific and passed through as-is.
+
+**Configuration:**
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `type` | string | yes | Infrastructure resource type (e.g., `database`, `queue`, `container_runtime`). |
+| *(additional keys)* | any | no | Provider-specific resource properties. |
+
+**Example:**
+
+```yaml
+modules:
+  - name: orders-db
+    type: platform.resource
+    config:
+      type: database
+      engine: postgresql
+      storage: "10Gi"
+```
+


The platform.resource documentation is incomplete compared to the schema definition in schema/module_schema.go:1403-1418. The schema shows five config fields (name, type, tier, capabilities, and constraints), but this documentation only shows type. The documented description differs significantly from the schema, which describes it as "A capability-based resource declaration managed by the platform abstraction layer" with additional fields for tier, capabilities, and constraints.

Copilot · 2026-02-23T04:45:35Z

DOCUMENTATION.md

+### `platform.context`
+
+Provides the execution context for platform operations. Used to identify the organization, environment, and tier for a deployment.
+
+**Configuration:**
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `path` | string | yes | Path identifying this context. |
+| `org` | string | no | Organization name. |
+| `environment` | string | no | Deployment environment (e.g., `production`, `staging`). |
+| `tier` | number | no | Platform tier level. |
+
+**Example:**
+
+```yaml
+modules:
+  - name: platform-ctx
+    type: platform.context
+    config:
+      path: "acme-corp/production"
+      org: "acme-corp"
+      environment: "production"
+      tier: 3
+```


The platform.context documentation is incomplete compared to the schema definition in schema/module_schema.go:1420-1433. The schema shows three required config fields (org, environment, and tier), but this documentation marks org, environment, and tier as not required. The schema shows all three fields are required except tier which has a default. The documentation should match the schema's required field designation.

intel352 · 2026-02-23T05:35:09Z

@copilot open a new pull request to apply changes based on the comments in this thread

Copilot · 2026-02-23T05:35:17Z

@intel352 I've opened a new pull request, #109, to work on those changes. Once the pull request is ready, I'll request review from you.

…rm.*, and observability.otel modules (#109) * Initial plan * fix: correct documentation inaccuracies for license.validator, platform.*, and observability.otel modules Co-authored-by: intel352 <77607+intel352@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>

Resolve DOCUMENTATION.md conflicts by keeping the PR branch version, which matches the canonical schema definitions in schema/module_schema.go: - license_key: env var fallback, not $ENV_VAR expansion (matches source) - platform.provider: 3 config fields (name, config, tiers) per schema - platform.resource: 5 config fields (name, type, tier, capabilities, constraints) - platform.context: org/environment/tier as strings, not path/number Also remove duplicate requestsPerHour/requestsPerMinute parsing block in plugins/http/modules.go that caused a typecheck lint failure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Copilot · 2026-02-23T07:20:46Z

plugins/observability/modules.go

+func otelTracingFactory(name string, cfg map[string]any) modular.Module {
+	m := module.NewOTelTracing(name)
+	if v, ok := cfg["endpoint"].(string); ok && v != "" {
+		m.SetEndpoint(v)
+	}
+	if v, ok := cfg["serviceName"].(string); ok && v != "" {
+		m.SetServiceName(v)
+	}


otelTracingFactory now reads cfg["endpoint"]/cfg["serviceName"] without guarding against cfg == nil. Since module config: is optional (and observability.otel has no required config fields), a YAML module that omits config will pass a nil map and this will panic. Add a nil check (or normalize nil to an empty map) before indexing into cfg.

Prevents potential issues when a module omits the config: section in YAML, which passes a nil map to the factory function. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

intel352 · 2026-02-23T07:40:26Z

Addressing review feedback

All 8 review comments have been addressed:

Already fixed in merge conflict resolution (`f58eb92`)

license_key env var expansion — Fixed. Now correctly says "falls back to WORKFLOW_LICENSE_KEY environment variable" (matches module/license_module.go:46-50 which uses os.Getenv, not $VAR expansion).
platform.provider incomplete — Fixed. Now documents all 3 config fields (name, config, tiers) matching schema/module_schema.go:1390-1401.
platform.resource incomplete — Fixed. Now documents all 5 config fields (name, type, tier, capabilities, constraints) matching schema/module_schema.go:1403-1418.
platform.context path field / tier type — Fixed. Removed non-existent path field, tier is now a string select (not number), org and environment are required. Matches schema/module_schema.go:1420-1433.
platform.context required fields — Fixed. org and environment are marked required, matching the schema.

Not applicable

JWT tests unrelated to PR — False positive. The JWT tests are in PR security: pin JWT signing algorithm to HS256 to prevent confusion attacks #99 (a separate PR), not in this PR's diff. Copilot was looking at the merge commit which includes main's changes.

Already fixed by this PR branch

observability.otel factory ignores config — Already fixed in this PR. The factory was changed from otelTracingFactory(name string, _ map[string]any) (ignoring config) to reading endpoint and serviceName and calling SetEndpoint()/SetServiceName().

Fixed in latest push (`bf99a09`)

nil map panic in otelTracingFactory — Added if cfg == nil { return m } guard before indexing into the config map. While Go nil map reads are safe (return zero value), the guard is good defensive practice.

intel352 and others added 2 commits February 22, 2026 23:23

Copilot AI review requested due to automatic review settings February 23, 2026 04:39

Copilot started reviewing on behalf of intel352 February 23, 2026 04:39 View session

Copilot AI reviewed Feb 23, 2026

View reviewed changes

Copilot AI mentioned this pull request Feb 23, 2026

fix: correct documentation inaccuracies for license.validator, platform.*, and observability.otel modules #109

Merged

Copilot AI and others added 2 commits February 23, 2026 01:22

Copilot AI review requested due to automatic review settings February 23, 2026 07:15

Copilot started reviewing on behalf of intel352 February 23, 2026 07:16 View session

Copilot AI reviewed Feb 23, 2026

View reviewed changes

fix: add nil guard for cfg map in otelTracingFactory

bf99a09

Prevents potential issues when a module omits the config: section in YAML, which passes a nil map to the factory function. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

intel352 merged commit 46f6a93 into main Feb 23, 2026
13 of 14 checks passed

intel352 deleted the docs/document-undocumented-module-types branch February 23, 2026 07:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: document 10+ undocumented module types#102

docs: document 10+ undocumented module types#102
intel352 merged 5 commits intomainfrom
docs/document-undocumented-module-types

intel352 commented Feb 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Feb 23, 2026

Uh oh!

Uh oh!

Copilot AI Feb 23, 2026

Uh oh!

Copilot AI Feb 23, 2026

Uh oh!

Copilot AI Feb 23, 2026

Uh oh!

Copilot AI Feb 23, 2026

Uh oh!

intel352 commented Feb 23, 2026

Uh oh!

Copilot AI commented Feb 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 23, 2026

Uh oh!

intel352 commented Feb 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

intel352 commented Feb 23, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

intel352 commented Feb 23, 2026

Uh oh!

Copilot AI commented Feb 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

intel352 commented Feb 23, 2026

Addressing review feedback

Already fixed in merge conflict resolution (f58eb92)

Not applicable

Already fixed by this PR branch

Fixed in latest push (bf99a09)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Already fixed in merge conflict resolution (`f58eb92`)

Fixed in latest push (`bf99a09`)