Skip to content

Fix: describe what --file_type selects in the CLI help text - #870

Open
AmaadMartin wants to merge 2 commits into
mainfrom
fix/cli-file-type-help-text
Open

Fix: describe what --file_type selects in the CLI help text#870
AmaadMartin wants to merge 2 commits into
mainfrom
fix/cli-file-type-help-text

Conversation

@AmaadMartin

@AmaadMartin AmaadMartin commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

  1. Link to an existing issue (if applicable):
    N/A

  2. Or, if no issue exists, describe the change:

Problem: --file_type shipped the placeholder description 'Optional. ', so
adk web --help printed only Optional. (choices: "cjs", "esm"). The commander
help string is the only documentation for this flag, so a reader cannot tell what
cjs changes, what esm changes, or what happens when the flag is omitted. The
same empty row appears on all six command surfaces that share the option: web,
api_server, run, deploy cloud_run, deploy agent_engine and
deploy reasoning_engine.

Solution: Fill in the description from the behaviour in
dev/src/utils/agent_loader.ts. The value becomes esbuild's output format and
picks the emitted extension through FILE_MODULE_TYPE_EXTENSION_MAP (cjs ->
.cjs, esm -> .mjs). When the flag is unset, getFileModuleType() reads the
agent file extension first, and only .js and .ts fall back to the "type"
field of the nearest package.json. This is a help-string change only:
argChoices, the flag spelling, the absent default and the five addOption
call sites are untouched, so parsing and the values handed to the loader are
identical.

Collision check: I listed the 300 open PRs on this fork and diffed every
adjacent CLI one (#803, #816, #700, #695, #693, #685, #706, #705, #709, #592,
#587). None touches --file_type. Two things do overlap and are disclosed here:

Deviation from the plan: the plan proposed wording that says the format "is
detected from the agent file extension and the nearest package.json type field".
That reads as if both inputs always apply. getFileModuleType() returns cjs
for .cjs/.cts and esm for .mjs/.mts without opening any package.json.
The shipped wording states that order instead.

Testing Plan

Please describe the tests that you ran to verify your changes. This is required for all PRs that are not small documentation or typo fixes.

Unit Tests:
[x] I have added or updated unit tests for my change.
[x] All unit tests pass locally.

Two parameterised cases over the six command surfaces in
dev/test/cli/cli_test.ts (12 cases). Both read the real --file_type help row
through Command.helpInformation(), whitespace-normalized so the assertions do
not depend on commander's column wrapping. Existing cases are unchanged.

npx vitest run --project unit:dev dev/test/cli/cli_test.ts
Test Files  1 passed (1)
     Tests  38 passed (38)

Mutation proof 1 — restore the placeholder new Option('--file_type <string>', 'Optional. '). All 12 cases fail:

× describes what --file_type selects in `web` help
  → expected '--file_type <string> Optional. (choic…' not to match
    /^--file_type <string> Optional\. \(ch…/
× limits the package.json fallback to .js and .ts in `web` help
  → expected '--file_type <string> Optional. (choic…' to contain
    'extension (.cjs/.cts, .mjs/.mts)'

Mutation proof 2 — restore only the over-claiming sentence ("detected from
the agent file extension and the nearest package.json type field"). The 6 new
cases fail and the 6 older ones still pass, so the second case pins the accuracy
fix on its own:

Tests  6 failed | 27 passed (33)
× limits the package.json fallback to .js and .ts in `web` help

Coverage: the change is one string literal on a module-initialisation line that
every existing case in this file already executes, so line and branch coverage
of the change is 100% by construction. The tests above exist to pin the string's
content, which coverage cannot do.

Manual End-to-End (E2E) Tests:
Please provide instructions on how to manually test your changes, including any necessary setup or configuration.

npm run build
for c in web api_server run "deploy cloud_run" "deploy agent_engine" "deploy reasoning_engine"; do
  node dev/dist/esm/cli_entrypoint.js $c --help | grep -A8 -- '--file_type'
done

Each surface prints the description and still ends with (choices: "cjs", "esm"). I ran all six. To confirm parsing did not change, node dev/dist/esm/cli_entrypoint.js run missing_agent.ts --file_type esm still fails
in AgentFile.load with Agent file .../missing_agent.ts does not exists, not
with an option error, so the flag is still accepted and threaded to the loader.

Gates run on the pushed commit: npx eslint dev/src/cli/cli.ts dev/test/cli/cli_test.ts (clean) and npx prettier ... --check (clean).
npm run ts:check reports 309 errors on this branch and the same 309 on main;
none of them is in a file this PR touches.

Checklist

[x] I have read the CONTRIBUTING.md document.
[x] I have performed a self-review of my own code.
[x] I have commented my code, particularly in hard-to-understand areas.
[x] I have added tests that prove my fix is effective or that my feature works.
[x] New and existing unit tests pass locally with my changes.

CI note

The first Windows run failed in tests/integration/app_loader/app_loader_test.ts
with Test timed out in 40000ms. That test compiles fixture agents with esbuild
and does not import anything this PR touches. A re-run passed, and PR #858
already targets that timeout. All three platforms are green.

Amaad Martin added 2 commits August 9, 2026 08:18
The --file_type option shipped the placeholder description 'Optional. ',
so `adk web --help` (and five other command surfaces that share the
option) rendered only "Optional.  (choices: \"cjs\", \"esm\")". Nothing
told the reader what picking cjs over esm actually changes.

Replace it with the behaviour read off AgentFile.load(): the value
becomes esbuild's output `format` and selects the emitted extension via
FILE_MODULE_TYPE_EXTENSION_MAP (cjs -> .cjs, esm -> .mjs), and when the
flag is omitted getFileModuleType() infers it from the agent file
extension and the nearest package.json "type" field.

Pure help-text change: the flag spelling, the absence of a default, and
argChoices are all untouched, so parsing and the values handed to
agent_loader are identical. Commander still appends the choices list
itself, so it is not duplicated in the description.

Add a regression pin over all six command surfaces asserting the entry is
no longer the bare placeholder, that it names both emitted extensions,
and that commander still renders the choices list.
The description claimed the auto-detected format comes from "the agent
file extension and the nearest package.json type field", which reads as
if both inputs always apply. getFileModuleType() is extension-first: it
returns cjs for .cjs/.cts and esm for .mjs/.mts without opening any
package.json, and only .js and .ts walk up to the nearest package.json.

State that order instead, and pin it with a second parameterised help
assertion over the same six command surfaces.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant