feat(cli): derive variadic CLI flags from z.array() types [OS-615]

[galligan]

Summary

• deriveFlags in @outfitter/cli/schema-input silently skipped z.array() types, requiring manual cli.options entries for array fields like tags and refs
• Now generates variadic --flag <value...> Commander options for z.array() types, matching how Commander handles repeatable flags
• Optional arrays and arrays with defaults are correctly handled (not marked as required)

Fixes https://linear.app/outfitter/issue/OS-615/deriveflags-should-handle-zarray-types-for-variadic-cli-flags

What changed

packages/cli/src/schema-input.ts: Moved "array" out of the skip-list in the deriveFlags switch and added a case that generates <value...> variadic flag syntax. Updated module-level and function-level TSDoc.

Test plan

• 3 new tests: basic array derivation, optional arrays, arrays with defaults
• All 30 schema-input tests pass
• Typecheck passes

🤘🏻 In-collaboration-with: Claude Code

[linear]

OS-615 `deriveFlags` should handle `z.array()` types for variadic CLI flags

[galligan]

• fix(ci): prevent spurious CI Summary failures after force-push [OS-616] #813
• feat(cli): make defaultOnResult the default for buildCliCommands [OS-605] #812
• feat(cli): derive variadic CLI flags from z.array() types [OS-615] #810 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR implements variadic CLI flag generation for z.array() types in @outfitter/cli's deriveFlags — previously these were silently skipped, requiring manual cli.options overrides for every array field. The change is minimal and well-scoped: one new case "array" in the switch, a recursive unwrapZodField call to extract the element type, and accumulator-style argParser coercion in createCommanderOption for numeric arrays. All previous review feedback has been addressed, including the wrapped-element-type recursion fix, the accumulating argParser, and the --help default description for number arrays.

Key changes:

• ZodFieldInfo and DerivedFlag gain arrayElementType?: string to carry element type through the pipeline
• unwrapZodField now recursively calls itself on def.element so wrapped element types (e.g. z.coerce.number(), z.number().optional()) are correctly resolved
• deriveFlags generates --flag <value...> for array fields; optional and defaulted arrays are not marked required
• createCommanderOption installs an accumulating argParser for number element arrays to prevent Number(val) from clobbering the accumulator; string arrays use Commander's native variadic collection
• Number-array Commander defaults are cleared (option.default(undefined, ...)) so Zod applies the real default during validation rather than seeding the accumulator
• 7 new unit tests cover all branches including element-type unwrapping, multi-value accumulation, and the string-array native path

Confidence Score: 4/5

Safe to merge — the feature is additive, all previous review issues are addressed, and the accumulating argParser correctly handles multi-value variadic options

The implementation is logically correct: the recursive element-type unwrapping handles z.coerce.number() and other wrappers; the accumulating argParser avoids the Number-clobber bug; the option.default(undefined, description) trick correctly separates Commander's live default from the help text. The one-point deduction is for the still-present else { option.default(undefined); } for required number arrays (a no-op but slightly noisy) and the lack of an integration test driving Commander parsing through validateInput.

No files require special attention; schema-input.ts is the only substantive change and it is well-tested

Important Files Changed

Filename	Overview
packages/cli/src/schema-input.ts	Adds z.array() support to deriveFlags and createCommanderOption with proper variadic flag syntax, accumulating argParser for numeric arrays, and recursive element-type unwrapping; all previous review issues addressed
packages/cli/src/tests/schema-input.test.ts	Adds 7 new tests covering basic array derivation, optional arrays, arrays with defaults, element-type tracking, wrapped element types, accumulating number-array argParser, and string-array native collection — all previously requested test cases are present
.changeset/cli-derive-array-flags.md	Correctly marks @outfitter/cli as a minor semver bump with an accurate description of the variadic array flag feature

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["deriveFlags(schema, explicitLongFlags)"] --> B["unwrapZodField(field)"]
    B --> C{def.type?}
    C -->|default| D["extract defaultValue, walk innerType"]
    C -->|optional/nullable| E["set isOptional, walk innerType"]
    C -->|pipe| F["walk out type (z.coerce.*)"]
    C -->|array| G["return baseType='array'\narrayElementType=unwrapZodField(element).baseType"]
    C -->|string/number/boolean/enum| H["return base ZodFieldInfo"]
    G --> I["deriveFlags switch(baseType)"]
    H --> I
    I -->|array| J["flagString = '--flag <value...>'"]
    I -->|number| K["flagString = '--flag <n>'"]
    I -->|string/enum| L["flagString = '--flag <value>'"]
    I -->|boolean| M["flagString = '--flag'"]
    J --> N["createCommanderOption(flag, schema)"]
    K --> N
    L --> N
    M --> N
    N --> O{isNumberArray?}
    O -->|yes| P["accumulating argParser\n(val, prev[]) => [...prev, Number(val)]"]
    O -->|no| Q{baseType===number?}
    Q -->|yes| R["argParser(Number) — scalar coercion"]
    Q -->|no| S[no argParser]
    P --> T{flag.defaultValue?}
    T -->|set| U["option.default(undefined, JSON.stringify(defaultValue))"]
    T -->|unset| V["option.default(undefined)"]
    N --> W{isRequired?}
    W -->|yes| X["makeOptionMandatory(true)"]

Loading

_{Reviews (8): Last reviewed commit: "chore: add changeset" | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 869116cb92

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[galligan]

@greptileai review

[galligan]

Merge activity

• Mar 26, 11:48 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Mar 26, 11:48 PM UTC: @galligan merged this pull request with Graphite.