feat: add adder to generate cmd stubs from markdown #613

jrschumacher · 2025-06-26T21:20:17Z

Use https://github.com/jrschumacher/adder to generate stubs from markdown.

gemini-code-assist

Summary of Changes

Hello @jrschumacher, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new code generation tool, adder, to automate the creation of CLI command stubs from markdown documentation. I've refactored the existing command-line interface to leverage this new system, which will enhance the consistency, maintainability, and development speed of our CLI by ensuring that command definitions are always in sync with their documentation.

Highlights

Automated CLI Generation: I've integrated the adder tool to automate the generation of Cobra command stubs directly from markdown documentation. This significantly streamlines the process of defining and updating CLI commands, ensuring consistency between documentation and code.
Refactored Command Structure: Existing CLI commands (e.g., config, dev-selectors, profile, root, tdf-decrypt, tdf-encrypt, tdf-inspect) have been refactored to utilize these newly generated stubs. This involves replacing manual Cobra command definitions and flag parsing with calls to adder-generated constructors and handler functions, improving code organization and maintainability.
Enhanced Documentation-as-Code: The docs/man markdown files have been updated to include richer metadata (like flag types and explicit argument definitions). This metadata is now consumed by adder to generate robust Go code, reinforcing a documentation-as-code approach for the CLI.
Build Process Updates: The Makefile now includes new targets (generate, clean-generated, regenerate, toolcheck) to manage the adder tool and its generated output, fully integrating it into the project's build workflow.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request is a significant step towards improving the maintainability of the CLI by introducing code generation for cobra commands from markdown files. The changes are extensive and well-structured. My feedback focuses on improving error handling consistency by returning errors from handlers instead of exiting directly, fixing a few critical issues in the generated code (like missing imports and incorrect flag types), and addressing minor inconsistencies in documentation and code.

gemini-code-assist · 2025-06-26T21:24:42Z

cmd/generated/_index_generated.go

+
+	"github.com/spf13/cobra"
+)


This generated file is missing an import for the fmt package, but fmt.Errorf is used in the runOtdfctl function on line 85. This will cause a compilation error. The adder tool should be configured or fixed to include necessary imports.

Suggested change

"github.com/spf13/cobra"

)

"fmt"

"github.com/spf13/cobra"

gemini-code-assist · 2025-06-26T21:24:42Z

cmd/generated/auth/clear-client-credentials_generated.go

+	// Register persistent flags
+
+	// Register flags
+	cmd.Flags().String("all", "%!s(bool=false)", "Deprecated -- see the `profile` subcommand")


The all flag is generated as a String flag with a default value of "%!s(bool=false)". This is incorrect; it should be a Bool flag. This issue seems to stem from the adder tool's code generation when a boolean flag is defined in the markdown without type: bool.

You've correctly added type: bool for flags in docs/man/_index.md. Please apply the same fix to the markdown file for this command (docs/man/auth/clear-client-credentials.md) and other commands where boolean flags are being generated incorrectly.

For example, the markdown should look like this:

... flags: - name: all description: Deprecated -- see the `profile` subcommand default: false type: bool ...

This will ensure the generator creates a Bool flag, which will fix the runtime behavior. This issue is present in multiple generated files for other boolean flags as well.

gemini-code-assist · 2025-06-26T21:24:43Z

cmd/config.go

 	if err != nil {
 		c.ExitWithError("Failed to update output format", err)
 	}


The handler function handleConfigOutput has a signature that returns an error, which is the standard for cobra's RunE functions. However, on error, c.ExitWithError is called, which terminates the program immediately. This bypasses cobra's error handling mechanism.

Instead of calling c.ExitWithError, you should return a descriptive error. The generated command wrapper will then handle printing the error and exiting. This pattern should be applied to all new command handlers in this PR for consistency and proper error flow.

return fmt.Errorf("Failed to update output format: %w", err)

gemini-code-assist · 2025-06-26T21:24:43Z

cmd/dev-selectors.go

+	if len(selectorsList) == 0 {
+		cli.ExitWithError("Must provide at least one selector", nil)
+	}


This function calls cli.ExitWithError instead of returning an error, which is inconsistent with the RunE pattern used by cobra. Please refactor this to return an error, allowing the caller to handle program termination and error reporting.

return fmt.Errorf("Must provide at least one selector")

gemini-code-assist · 2025-06-26T21:24:43Z

cmd/profile.go

+		c.Println("failed")
+		c.ExitWithError("Failed to create profile", err)
+	}
+	c.Println("ok")


The handler function handleProfileCreate calls c.ExitWithError instead of returning an error. To align with cobra's RunE error handling pattern, this should be changed to return an error. This allows the caller to manage program exit and error reporting. This applies to all other handlers in this file as well.

Suggested change

c.Println("failed")

c.ExitWithError("Failed to create profile", err)

}

c.Println("ok")

return fmt.Errorf("Failed to create profile: %w", err)

gemini-code-assist · 2025-06-26T21:24:43Z

cmd/tdf-inspect.go


 		c.PrintJson(n)
 	} else {
 		c.ExitWithError("failed to inspect TDF", nil)


This function calls c.ExitWithError but is defined to return an error. To follow the RunE pattern, you should return an error instead of exiting directly.

Suggested change

c.ExitWithError("failed to inspect TDF", nil)

return fmt.Errorf("failed to inspect TDF")

gemini-code-assist · 2025-06-26T21:24:43Z

Makefile

+	@echo "✓ go version is compatible"
+	@go run github.com/jrschumacher/adder/cmd/[email protected] version >/dev/null 2>&1 || { echo >&2 "adder tool check failed. Run 'go mod download' to ensure dependencies are available."; exit 1; }
+	@echo "✓ adder is available"
+	@command -v bats >/dev/null 2>&1 || echo "⚠ bats is not installed (required for e2e tests). Install with: brew install bats-core"


The suggestion to install bats using brew is specific to macOS. To make this Makefile more portable for developers on other operating systems (like Linux), it would be better to provide a more generic installation instruction or link to the official bats-core installation guide.

For example, you could suggest installing via npm or from source, and link to https://github.com/bats-core/bats-core#installation.

gemini-code-assist · 2025-06-26T21:24:43Z

cmd/dev-selectors.go

 	"github.com/spf13/cobra"
 )

 var selectors []string


The global variable selectors appears to be a leftover from the previous implementation and is no longer used. It can be safely removed to improve code clarity.

gemini-code-assist · 2025-06-26T21:24:43Z

cmd/dev-selectors.go

+	}

 	flattened, err := handlers.FlattenSubjectContext(subject)
 	if err != nil {


This function calls cli.PrintSuccessTable and then does not return an error. To align with cobra's RunE error handling pattern, this should return nil.

gemini-code-assist · 2025-06-26T21:24:43Z

docs/man/policy/kas-registry/create.md

      shorthand: r
      description: Remote URI where the public key can be retrieved for the KAS
-    - name: label
    - name: name


The label flag has been removed from this markdown documentation, but it's still present in the generated code (cmd/generated/policy/kas-registry/create_generated.go). This creates an inconsistency between the documentation and the actual CLI behavior. Please either remove the flag from the generator's logic or add it back to the documentation.

jrschumacher requested review from a team as code owners June 26, 2025 21:20

gemini-code-assist bot reviewed Jun 26, 2025

View reviewed changes

jrschumacher added 5 commits June 26, 2025 21:59

feat: add adder to generate cmd stubs from markdown

789d638

Fix duplicate label

bcd0a57

Allow args to support array of objects or array of strings

e99dfb7

regenerate

f7c7d4c

Add missing type

703f542

jrschumacher force-pushed the generator-for-docs branch from 14574db to 703f542 Compare June 27, 2025 14:18

fixes

408fe8a

	c.ExitWithError("failed to inspect TDF", nil)
	return fmt.Errorf("failed to inspect TDF")

feat: add adder to generate cmd stubs from markdown #613

Are you sure you want to change the base?

feat: add adder to generate cmd stubs from markdown #613

Uh oh!

Conversation

jrschumacher commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jun 26, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jrschumacher commented Jun 26, 2025 •

edited

Loading