[DX-1135] Fix arg names not converting to snake_case in error output

[sacOO7]

• Fixes https://ably.atlassian.net/browse/DX-1135
• Fixes camelCase arg names appearing in error output when required args are missing.
• Following is BEFORE/AFTER output for pnpm cli auth keys create without explicit --help flag

Before:

> bin/run.js auth keys create

 ›   Error: Missing 1 required arg:
 ›   keyName  Name of the key
 ›   See more help with --help

USAGE
  $ ably auth keys create KEYNAME [-v] [--json | --pretty-json] [--app <value>]
    [--capabilities <value>]

ARGUMENTS
  KEYNAME  Name of the key

After:

> bin/run.js auth keys create

 ›   Error: Missing 1 required arg:
 ›   keyName  Name of the key
 ›   See more help with --help

USAGE
  $ ably auth keys create KEY_NAME [-v] [--json | --pretty-json] [--app <value>]
    [--capabilities <value>]

ARGUMENTS
  KEY_NAME  Name of the key

• Now it renders KEY_NAME properly in snake_case.
• The init hook that patches arg names to snake_case was gated behind GENERATING_DOC=true, so it only ran during doc generation — not during normal CLI usage.

Context

oclif's error handler creates a base Help instance (not our CustomHelp)
to render USAGE/ARGUMENTS sections alongside missing-arg errors. Since it reads
from config.commands, the init hook is the right place to patch arg names
for this code path.

The existing camelToSnake patch in CustomHelp.formatCommand() is retained
as defense in depth — camelToSnake is idempotent so the double-patch is harmless.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cli-web-cli	Ready	Preview, Comment	Apr 22, 2026 1:31pm

[Copilot]

Pull request overview

Adjusts oclif init-time command metadata so argument display names consistently render as UPPER_SNAKE_CASE in USAGE/ARGUMENTS output (including when shown as part of missing-arg errors), rather than leaking camelCase arg names.

Changes:

• Remove the GENERATING_DOC=true gate so the init hook runs on every CLI invocation.
• Patch config.commands[*].args[*].name from camelCase → snake_case at init time.
• Expand the hook’s docstring to document the affected output paths and rationale.

Comments suppressed due to low confidence (1)

src/hooks/init/patch-arg-names.ts:29

• This change makes the init hook mutate config.commands on every invocation; it would be good to add a hooks-project test that builds a minimal Config with a command arg like keyName and asserts the hook converts it to key_name. That would lock in the regression fix for missing-arg USAGE/ARGUMENTS rendering.

const hook: Hook<"init"> = async function ({ config }) {
  for (const command of config.commands) {
    for (const arg of Object.values(command.args)) {
      arg.name = camelToSnake(arg.name);
    }
  }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/hooks/init/patch-arg-names.ts:22

• This behavior change (patching config.commands arg names on every invocation) isn't covered by tests. Consider adding a unit/integration test that runs a command with a camelCase arg (e.g. auth keys create without args) and asserts the USAGE/ARGUMENTS sections render KEY_NAME (with underscore) rather than KEYNAME, so regressions in the oclif error/help path are caught.

const hook: Hook<"init"> = async function ({ config }) {
  for (const command of config.commands) {
    for (const arg of Object.values(command.args)) {
      arg.name = camelToSnake(arg.name);
    }
  }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[claude-code-ably-assistant]

Walkthrough

This PR fixes a display bug where camelCase argument names (e.g., keyName) were not being converted to UPPER_SNAKE_CASE (e.g., KEY_NAME) in missing-argument error output. The root cause was that the patch-arg-names init hook was gated behind a GENERATING_DOC=true environment variable check, so it only ran during doc generation — not during normal CLI usage where oclif's base Help class (not CustomHelp) renders USAGE/ARGUMENTS alongside error messages.

Changes

Area	Files	Summary
Hooks	src/hooks/init/patch-arg-names.ts	Remove the GENERATING_DOC guard so the camelCase → snake_case arg name patch runs on every CLI invocation, not only during doc generation

Review Notes

• Behavioral change: The camelToSnake patch on config.commands metadata now runs on every CLI startup, not just pnpm generate-doc. The patch is idempotent (camelToSnake on already-snake_case names is a no-op), so repeated application is safe.
• No new dependencies introduced.
• Defense-in-depth retained: CustomHelp.formatCommand() still applies the same transform for the --help path; this PR simply ensures the init hook covers the error-output path too.
• Test coverage: The existing behaviour is implicitly covered via the doc-generation path. A unit/integration test asserting that missing-arg error output renders UPPER_SNAKE_CASE names (without GENERATING_DOC=true) would strengthen confidence in the fix.

[claude-code-ably-assistant]

Review Summary

One file changed: src/hooks/init/patch-arg-names.ts — removes the GENERATING_DOC=true guard so arg-name patching runs on every CLI invocation.

Analysis

The fix is correct and safe. Key points verified:

Idempotency holds. camelToSnake uses /([a-z])([A-Z])/g substitution followed by .toLowerCase(). Applied to an already-snake_case string (e.g., key_name) it produces no changes. The init hook, CustomHelp.formatCommand(), and any subsequent call all compose safely.

The CustomHelp.formatCommand() save/restore is now a no-op in production, but still correct. After the hook runs, config.commands holds snake_case names; formatCommand saves them, re-applies the idempotent transform, renders, and restores the same snake_case values. For tests that don't invoke the hook, the save/restore still serves its original purpose — so keeping it is the right call.

Hook registration is correct. patch-arg-names is the third entry under oclif.hooks.init in package.json, running after alias-command and version-flag — fine ordering for a pure metadata patch.

The root cause is accurately described. oclif's missing-arg error path instantiates the base Help class (not CustomHelp), reads directly from config.commands, and calls .toUpperCase() on the raw arg name — so patching the metadata at init time is the correct fix, not trying to override the error renderer.

No issues to flag

This is a small, well-scoped fix. The new comment block clearly explains the before/after and the relationship with CustomHelp.formatCommand(). Ready to merge.