[Public API] Split the root config surface and remove invalid configuration states

[cssbruno]

Priority

Medium-high — public API clarity, long-term compatibility, and configuration safety.

Context

The repository convention currently keeps gowdk.go as the only root Go source file. That single file owns many unrelated public concerns: source discovery, render modes, i18n, env contracts, lifecycle services, build targets, CORS, CSRF, security headers, workers, cron, addon interfaces, auth, SEO, CSS processing, and Go-block extension contracts.

The exported config model also includes fields that can represent contradictory or weakly typed states.

Examples:

• CSRFConfig has both Enabled and Disabled, but runtime behavior is effectively controlled by !Disabled.
• BuildTargetConfig is a flat struct spanning static, frontend app, backend app, worker, cron, binary, WASM, and deployment concerns.
• Several references are plain strings for import paths, function names, cron schedules, job types, feature IDs, and Go-block targets.

Problem

The root package is becoming a broad compatibility surface rather than a small stable API.

Consequences:

1. unrelated features expand gowdk.Config and therefore the v1 compatibility burden;
2. invalid states are representable and must be interpreted later;
3. users have a harder time understanding which fields belong together;
4. generated-app roles and optional product features are coupled through one flat config type;
5. implementation maintainers are discouraged from splitting code into concern-specific files even though doing so would not change the Go import path.

Proposed direction

Keep the import path github.com/cssbruno/gowdk, but split the root package across concern-specific files and tighten the exported types.

Suggested file split:

config.go
source.go
render.go
i18n.go
env.go
security.go
build.go
roles.go
addons.go
css.go
seo.go

Suggested type cleanup:

• replace Enabled/Disabled pairs with one explicit policy enum or pointer configuration;
• group target outputs by role instead of one flat struct;
• validate feature IDs and addon target IDs centrally;
• define typed provider references where possible instead of free-form strings;
• document which types are core v1 surface and which are experimental/optional.

Acceptance criteria

• The root package remains import-compatible but is split into concern-specific files.
• Contradictory boolean pairs are replaced or validated so invalid states cannot silently persist.
• Build target role outputs are grouped or validated through a clearer role model.
• String references that remain stringly typed have central validators and diagnostics.
• Public docs explain stable core config versus experimental/optional config fields.
• Tests pin backwards-compatible behavior or deliberate migration diagnostics.

Related

• Define and enforce the v1 core versus optional product boundaries #677 — Define and enforce the v1 core versus optional product boundaries
• [Build] Validate the complete artifact output topology before writing #694 — Validate the complete artifact output topology before writing
• Separate built-in compiler features from executable addon extensions #670 — Separate built-in compiler features from executable addon extensions