Add Code Generation Support for Alternative Sources by bcdxn · Pull Request #19 · bcdxn/opencli

bcdxn · 2026-08-24T02:00:52Z

Alternative Sources

Although the OpenCLI Specification supported the concept of alternative sources (i.e. passing flag values from config files and environment variables) there was no support in the code generation within ocli. This branch adds that missing support. Now CLIs generated for Cobra, urfave/cli V3 and Yargs can all pull values from the specified config files/environment variables.

commands:

  pleasantries greet <name> [flags]:
    summary: "Say hello"
    args:
      - name: "name"
        summary: "A name to include in the greeting"
        required: true
        type: "string"
    flags:
      - name: "language"
        summary: "The language of the greeting"
        type: "string"
        choices:
          - value: "english"
          - value: "spanish"
        default: "English"
        alternativeSources:
           - type: "$ENV"
            property: "PLEASANTRIES_LANGUAGE"
          - type: "$FILE"
            property: "$.language"

Global Flags

This branch also addresses a major bug where global flags were dropped during code generation for some frameworks.

Copilot

🟡 Changes recommended

Yargs resolution currently breaks defaults, required flags, enum compilation, and source precedence, while Go YAML numeric coercion is incomplete.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds generated CLI support for environment- and config-file-backed flag values across Cobra, urfave/cli, and Yargs.

Changes:

Generates alternative-source resolvers and config loaders.
Adds global-flag propagation and generator coverage.
Updates examples, documentation, generated fixtures, and web navigation.

File summaries

File	Description
`gen/cli.go`	Validates unsupported group arguments/flags.
`gen/cli_cobra.go`	Generates Cobra source resolution.
`gen/cli_urfave_cli.go`	Generates urfave source resolution.
`gen/cli_yargs.go`	Generates Yargs source resolution.
`gen/templates/code/cobra/gencli/config.tmpl`	Adds Cobra config resolvers.
`gen/templates/code/cobra/gencli/run.tmpl`	Loads config and binds globals.
`gen/templates/code/cobra/gencli/params.tmpl`	Adds global-flag context helpers.
`gen/templates/code/cobra/gencli/command.tmpl`	Resolves flags and injects globals.
`gen/templates/code/cobra/gencli/actions.tmpl`	Corrects parameter generation.
`gen/templates/code/urfavecli/gencli/config.tmpl`	Adds urfave config resolvers.
`gen/templates/code/urfavecli/gencli/run.tmpl`	Loads config and registers globals.
`gen/templates/code/urfavecli/gencli/params.tmpl`	Adds global-flag context helpers.
`gen/templates/code/urfavecli/gencli/command.tmpl`	Resolves flags and injects globals.
`gen/templates/code/urfavecli/gencli/actions.tmpl`	Corrects parameter generation.
`gen/templates/code/yargs/gencli/config.tmpl`	Adds TypeScript config resolvers.
`gen/templates/code/yargs/gencli/run.tmpl`	Accepts argv and loads config.
`gen/templates/code/yargs/gencli/params.tmpl`	Adds global-flag accessors.
`gen/templates/code/yargs/gencli/help.tmpl`	Corrects argument help rendering.
`gen/templates/code/yargs/gencli/command.tmpl`	Resolves flags and sets globals.
`gen/cli_group_test.go`	Tests group validation.
`gen/cli_globalflags_test.go`	Tests global-flag generation.
`gen/cli_yargs_variadic_test.go`	Tests typed variadic flags.
`gen/testdata/globalflags-cli.ocs.yaml`	Defines global-flag fixture.
`gen/testdata/cobra/globalflags/gencli/run.gen.go`	Cobra global-flag golden.
`gen/testdata/cobra/globalflags/gencli/params.gen.go`	Cobra global parameter golden.
`gen/testdata/cobra/globalflags/gencli/iostreams.gen.go`	Cobra I/O golden.
`gen/testdata/cobra/globalflags/gencli/help.gen.go`	Cobra help golden.
`gen/testdata/cobra/globalflags/gencli/errors.gen.go`	Cobra error golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag.gen.go`	Cobra root-command golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag_send.gen.go`	Cobra send-command golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag_ping.gen.go`	Cobra ping-command golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag_greet.gen.go`	Cobra greet-command golden.
`gen/testdata/cobra/globalflags/gencli/cmd_gflag_echo.gen.go`	Cobra echo-command golden.
`gen/testdata/cobra/globalflags/gencli/actions.gen.go`	Cobra actions golden.
`gen/testdata/cobra/gencli/run.gen.go`	Loads generated Cobra config.
`gen/testdata/cobra/gencli/cmd_petstore_user_login.gen.go`	Resolves Cobra login sources.
`gen/testdata/urfavecli/globalflags/gencli/run.gen.go`	urfave global-flag golden.
`gen/testdata/urfavecli/globalflags/gencli/params.gen.go`	urfave global parameter golden.
`gen/testdata/urfavecli/globalflags/gencli/iostreams.gen.go`	urfave I/O golden.
`gen/testdata/urfavecli/globalflags/gencli/errors.gen.go`	urfave error golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag.gen.go`	urfave root-command golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag_send.gen.go`	urfave send-command golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag_ping.gen.go`	urfave ping-command golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag_greet.gen.go`	urfave greet-command golden.
`gen/testdata/urfavecli/globalflags/gencli/cmd_gflag_echo.gen.go`	urfave echo-command golden.
`gen/testdata/urfavecli/globalflags/gencli/actions.gen.go`	urfave actions golden.
`gen/testdata/urfavecli/gencli/run.gen.go`	Loads generated urfave config.
`gen/testdata/urfavecli/gencli/config.gen.go`	Generated urfave source resolvers.
`gen/testdata/urfavecli/gencli/cmd_petstore_user_login.gen.go`	Resolves urfave login sources.
`gen/testdata/yargs/globalflags/gencli/types.ts`	Yargs metadata golden.
`gen/testdata/yargs/globalflags/gencli/run.ts`	Yargs global option golden.
`gen/testdata/yargs/globalflags/gencli/params.ts`	Yargs global accessor golden.
`gen/testdata/yargs/globalflags/gencli/help.ts`	Yargs help golden.
`gen/testdata/yargs/globalflags/gencli/errors.ts`	Yargs error golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag.ts`	Yargs root-command golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag-send.ts`	Yargs send-command golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag-ping.ts`	Yargs ping-command golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag-greet.ts`	Yargs greet-command golden.
`gen/testdata/yargs/globalflags/gencli/cmd-gflag-echo.ts`	Yargs echo-command golden.
`gen/testdata/yargs/globalflags/gencli/actions.ts`	Yargs actions golden.
`gen/testdata/yargs/gencli/run.ts`	Loads generated Yargs config.
`gen/testdata/yargs/gencli/help.ts`	Corrects generated argument help.
`gen/testdata/yargs/gencli/cmd-petstore-user-login.ts`	Resolves Yargs login sources.
`internal/cli/gencli/run.gen.go`	Loads OpenCLI configuration.
`internal/cli/gencli/cmd_ocli_gen_docs.gen.go`	Resolves docs format sources.
`internal/cli/gencli/cmd_ocli_gen_cli.gen.go`	Resolves framework sources.
`ocli.ocs.yaml`	Adds canonical self-documenting spec.
`docs/ocli.ocs.md`	Regenerates CLI documentation.
`docs/actions-implementation.md`	Documents action data access.
`README.md`	Updates canonical spec link.
`CONTRIBUTING.md`	Updates repository layout reference.
`.github/copilot-instructions.md`	Updates repository guidance.
`Makefile`	Updates generation targets and examples.
`go.mod`	Adds config-resolution dependencies.
`go.sum`	Records dependency checksums.
`examples/code/README.md`	Documents all generated examples.
`examples/code/yargs/pleasantries/src/index.ts`	Uses the new Yargs run API.
`examples/code/yargs/pleasantries/src/gencli/run.ts`	Generates the new run API.
`examples/code/yargs/pleasantries/src/gencli/help.ts`	Corrects argument help output.
`examples/code/urfavecli/pleasantries/main.go`	Adds urfave example entry point.
`examples/code/urfavecli/pleasantries/go.mod`	Defines urfave example module.
`examples/code/urfavecli/pleasantries/internal/cli/actions.go`	Implements example actions.
`examples/code/urfavecli/pleasantries/internal/gencli/run.gen.go`	Adds urfave runtime.
`examples/code/urfavecli/pleasantries/internal/gencli/params.gen.go`	Adds generated parameters.
`examples/code/urfavecli/pleasantries/internal/gencli/iostreams.gen.go`	Adds generated I/O support.
`examples/code/urfavecli/pleasantries/internal/gencli/errors.gen.go`	Adds generated errors.
`examples/code/urfavecli/pleasantries/internal/gencli/cmd_pleasantries.gen.go`	Adds generated root command.
`examples/code/urfavecli/pleasantries/internal/gencli/cmd_pleasantries_greet.gen.go`	Adds generated greet command.
`examples/code/urfavecli/pleasantries/internal/gencli/cmd_pleasantries_farewell.gen.go`	Adds generated farewell command.
`examples/code/urfavecli/pleasantries/internal/gencli/actions.gen.go`	Adds generated action interface.
`examples/code/cobra/pleasantries/internal/gencli/run.gen.go`	Adds generated Cobra runtime.
`examples/code/gencli/params.gen.go`	Removes misplaced generated fixture.
`examples/code/gencli/cmd_petstore.gen.go`	Removes misplaced root command.
`examples/code/gencli/cmd_petstore_user.gen.go`	Removes misplaced user group.
`examples/code/gencli/cmd_petstore_user_update.gen.go`	Removes misplaced update command.
`examples/code/gencli/cmd_petstore_user_logout.gen.go`	Removes misplaced logout command.
`examples/code/gencli/cmd_petstore_user_login.gen.go`	Removes misplaced login command.
`examples/code/gencli/cmd_petstore_user_get.gen.go`	Removes misplaced get command.
`examples/code/gencli/cmd_petstore_user_delete.gen.go`	Removes misplaced delete command.
`examples/code/gencli/cmd_petstore_user_createwithlist.gen.go`	Removes misplaced list-create command.
`examples/code/gencli/cmd_petstore_user_create.gen.go`	Removes misplaced create command.
`examples/code/gencli/cmd_petstore_store.gen.go`	Removes misplaced store group.
`examples/code/gencli/cmd_petstore_store_order.gen.go`	Removes misplaced order group.
`examples/code/gencli/cmd_petstore_store_order_place.gen.go`	Removes misplaced place command.
`examples/code/gencli/cmd_petstore_store_order_get.gen.go`	Removes misplaced order-get command.
`examples/code/gencli/cmd_petstore_store_order_delete.gen.go`	Removes misplaced order-delete command.
`examples/code/gencli/cmd_petstore_store_inventory.gen.go`	Removes misplaced inventory command.
`examples/code/gencli/cmd_petstore_pet.gen.go`	Removes misplaced pet group.
`examples/code/gencli/cmd_petstore_pet_uploadimage.gen.go`	Removes misplaced upload command.
`examples/code/gencli/cmd_petstore_pet_updateform.gen.go`	Removes misplaced form-update command.
`examples/code/gencli/cmd_petstore_pet_update.gen.go`	Removes misplaced pet-update command.
`examples/code/gencli/cmd_petstore_pet_get.gen.go`	Removes misplaced pet-get command.
`examples/code/gencli/cmd_petstore_pet_findbytags.gen.go`	Removes misplaced tag-search command.
`examples/code/gencli/cmd_petstore_pet_findbystatus.gen.go`	Removes misplaced status-search command.
`examples/code/gencli/cmd_petstore_pet_delete.gen.go`	Removes misplaced pet-delete command.
`examples/code/gencli/cmd_petstore_pet_add.gen.go`	Removes misplaced pet-add command.
`examples/code/gencli/cmd_petstore_list.gen.go`	Removes misplaced list command.
`examples/code/gencli/actions.gen.go`	Removes misplaced action interface.
`web/tsconfig.json`	Excludes public assets from TypeScript.
`web/src/views/GettingStarted.tsx`	Links TypeScript generation docs.
`web/src/views/GenMarkdownDocs.tsx`	Links TypeScript generation docs.
`web/src/views/GenManDocs.tsx`	Links TypeScript generation docs.
`web/src/views/GenHtmlDocs.tsx`	Links TypeScript generation docs.
`web/src/views/GeneratingGoCode.tsx`	Documents global flags and updates links.
`web/src/app/docs/code-generation-yargs/page.tsx`	Adds the Yargs documentation route.
`web/public/assets/code/actions.txt`	Adds downloadable TypeScript example.

Review details

Files reviewed: 129/136 changed files
Comments generated: 11
Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

🟡 Changes recommended

Yargs precedence and typing edge cases, missing generated dependencies, and unvalidated global choices can produce incorrect or non-building generated CLIs.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files not reviewed (1)

web/package-lock.json: Generated file

Suppressed comments (2)

gen/templates/code/yargs/gencli/config.tmpl:226

This scan continues past the -- end-of-options marker. For a passthrough invocation such as cmd -- --name, it incorrectly treats --name as an explicit option and suppresses the declared environment/config fallback, even though Yargs treats it as positional data. Stop scanning at --.
gen/templates/code/yargs/gencli/config.tmpl:232
Yargs accepts grouped short options, but this exact-name comparison sees -vx only as vx, not aliases v and x. An explicit grouped shorthand for an alternative-sourced flag can therefore be overwritten by environment/config data. Parse single-dash option groups consistently with Yargs while preserving support for declared multi-character aliases.

Files reviewed: 153/162 changed files
Comments generated: 9
Review effort level: Balanced

+import toml from "@iarna/toml";
+{{- end}}
+{{- if .HasFileAltSource}}
+import { JSONPath } from "jsonpath-plus";


 export async function run(
-  yargsInstance: yargs.Argv<{}>,
+  argv: string[],
  actions: ActionsInterface,


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

bcdxn added 22 commits August 14, 2026 13:16

alt sources

b6ac909

feat: urfave cli alternative sources

9caf03b

reviewed urfave impl

003b7c6

feat: enable alternative sources for cobra

bfce2d7

fix: make urfavecli load config conditional

5e6d6fb

fix: default bug

f559563

fix: examples

b74a3fc

fix: global flags and alt sources

f5ac203

fix: alt sources resolution bug in supported frameworks

24e105d

fix: flags on groups gap

14e5001

fix: variadic errors in yargs

bf0e1ee

fix: add yargs alt source capability + minor fixes

caa50cc

fix: missing yargs shorthand name when processing alt sources

8356c2d

fix: global flags missing normalization

a11e3b6

fix: bug wher toInt64 generated runtime config silently trucated float64

98a6839

fix: altSourceItems called twice in resolveSliceFlag logic

679e7bc

fix: silently dropping shorthand in yargs templates

61c7bbd

fix: minor fixes

0c8ff38

fix: handle global flags in a more elegant way

98d2624

fix: import bug + add docs

75b172d

doc: update documentation for yargs

75be0df

add docs + minor fixes

8045f76

bcdxn requested a balanced review from Copilot August 24, 2026 02:00

Copilot started reviewing on behalf of bcdxn August 24, 2026 02:01 View session

Copilot AI reviewed Aug 24, 2026

View reviewed changes

bcdxn and others added 5 commits August 28, 2026 07:52

Potential fix for pull request finding

abfc314

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

fix: address PR comments

ac90a19

fix: spec error

e42f34b

Potential fix for pull request finding

f0c2ae2

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

ab666de

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

bcdxn added 3 commits August 28, 2026 22:08

fix: address pr comments

cbbf4e7

fix: address pr comments

12e2da1

fix: required flags with alt sources

e6bd02a

bcdxn requested a balanced review from Copilot August 29, 2026 02:08

Copilot started reviewing on behalf of bcdxn August 29, 2026 02:09 View session

Copilot AI reviewed Aug 29, 2026

View reviewed changes

bcdxn and others added 9 commits August 29, 2026 08:22

fix: docs syntax error

0bb978b

fix: address variadic typing issues

f81cc5c

fix: how yargs handles choices in global flags

d0c888f

fix: how cobra handles choices in global flags

8473063

fix: urfave cli global options choice validations

4305017

Potential fix for pull request finding

ac013ce

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

57555f8

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

6139982

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

fix: add examples to petstore example

9ca1fd2

bcdxn merged commit 683d0ca into main Aug 30, 2026
7 checks passed

bcdxn deleted the feature/alt-src-fixes branch August 30, 2026 02:02

Navigation Menu

Add Code Generation Support for Alternative Sources - #19

Add Code Generation Support for Alternative Sources#19
bcdxn merged 39 commits into
mainfrom
feature/alt-src-fixes

bcdxn commented Aug 24, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

bcdxn commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Alternative Sources

Global Flags

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Files not reviewed (1)

Suppressed comments (2)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bcdxn commented Aug 24, 2026 •

edited

Loading