Documentation
¶
Overview ¶
Package kcloptions discovers the `-D` render options a project's KCL declares, so forge can validate and list them WITHOUT knowing what any of them mean.
The division of labour ====================== forge owns a small set of options it DERIVES and binds itself — the env name, the namespace, the resolved image tag, the git worktree/branch. Those are forge's (see Reserved).
Everything else is the project's. A project declares an option by CALLING it, which it has to do anyway to read the value:
_host_runner = option("host_runner", type="str", default="air",
help="Host launch runner: air (default) or go-run")
There is no forge-side declaration format, no reserved filename, and no schema to keep in sync — the call site IS the declaration. forge parses the KCL, collects the option calls, subtracts its own, and treats what's left as opaque names it will relay. It never interprets a value.
Why dependency resolution is load-bearing ========================================= kcl's ListOptions walks every single-name call expression and unwraps a symbol-map lookup (crates/loader/src/option.rs). An identifier it cannot resolve is not a soft miss — it panics Rust-side, and the panic surfaces as an empty result rather than an error. Every forge project's main.k imports the forge KCL module, so pointing ListOptions at one WITHOUT resolving kcl.mod returns nothing at all.
So discovery resolves the env's dependencies through kpm first (the same resolution the render path performs) and hands them over as external packages. With them, a real env package reports its options; without them, zero. Because that failure is indistinguishable from "declares nothing" by the option list alone, Discover returns a separate discoverable flag rather than letting an empty list stand in for both — see its docs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Reserved = map[string]string{
"env": "the environment name — comes from the `forge env up <env>` argument",
"namespace": "the k8s namespace — derived from the env's cluster target",
"image_tag": "the resolved image tag — derived from the env and the build",
"release_version": "the release being built or deployed — bound only when a release names it; it becomes service.version in OTEL_RESOURCE_ATTRIBUTES",
"image_digests": "the built images' content digests — captured by `forge env deploy`",
"target_arch": "the deploy-target GOARCH — derived from --target-arch, the env's cluster platform, or forge.yaml deploy.target_arch",
"worktree": "the git worktree basename — resolved by the parallel-dev-stack primitives",
"branch": "the git branch — resolved by the parallel-dev-stack primitives",
"kubeconfig": "the default kubeconfig path on this machine — resolved by forge, read via `<cluster>.kubeconfig`",
"frontend_outputs": "each frontend's production build shape — read from each frontend's next.config",
"forge_workload_image_digests": "each workload's per-slot image references — bound from the release snapshot",
"forge_immutable_release": "refuses any unpinned workload image — bound when rendering a release snapshot",
}
Reserved are the option names forge derives and binds on every render. A project must not declare or `-D` them: forge computes the value, and a caller-supplied one would silently disagree with the rest of the pipeline (an image tag that doesn't match what was built, a namespace that doesn't match what was applied).
This is the whole of forge's option vocabulary. Everything else is opaque.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option struct {
Name string `json:"name"`
Type string `json:"type,omitempty"`
Default string `json:"default,omitempty"`
Help string `json:"help,omitempty"`
Required bool `json:"required,omitempty"`
}
Option is one render option a project's KCL declares. Type/Default/Help are populated only when the `option()` call passes them; a bare `option("name")` yields just the name, which is legal but gives the CLI nothing to show.
func Discover ¶
Discover returns the options the env's KCL declares, minus forge's own.
The bool result is "discoverable": false means the parse produced NOTHING — not even the forge-derived options every forge project's KCL necessarily calls — which indicates the resolution failed rather than that the project declares no options. Callers should degrade permissively on false (accept the `-D` and skip validation) rather than reject a name they merely failed to see. A project that genuinely declares no options returns (nil, true).
Source Files