Plugin option multi-value syntax silently mis-parses, and behaves differently from the Python port

[ultimatile]

Summary

jtc config set accepts plugin-specific options like --tests, --git, --formatter, etc., each documented as taking KEY=VALUE pairs. There are three problems with how multiple pairs are accepted today:

1. Comma-separated form silently mis-parses. --tests "aqua=true,project=true" does not error and does not get split; instead it produces a corrupt list value.
2. Repeating the flag does not append. --tests aqua=true --tests project=true only keeps the last value — the earlier one is lost. The Python port (JuliaPkgTemplatesCLI) supported the repeat form, so this is a regression for users porting their muscle memory.
3. The intended form (space-separated single string) is not documented anywhere user-visible. It only appears in an internal source comment.

The result is that the same intent (set two plugin keys at once) can produce three different and silently wrong configurations depending on which form a user types.

Reproduction

Using --config-file to avoid touching the global config:

# (1) Comma-separated form — accepted, but corrupt
$ julia --project=. -e 'using PkgTemplatesCommandLineInterface; PkgTemplatesCommandLineInterface.main(ARGS)' -- \
    config set --tests "aqua=true,project=true" --config-file /tmp/jtc-test.toml
[ Info: Configuration saved to /tmp/jtc-test.toml
Set default Tests.aqua: ["true", "project=true"]

Resulting TOML:

[default.Tests]
aqua = ["true", "project=true"]

Tests.aqua is a boolean option, but a list value was persisted.

# (2) Repeated flag — last value wins, earlier value is silently dropped
$ ... config set --tests aqua=true --tests project=true --config-file /tmp/jtc-test.toml
Set default Tests.project: true

Resulting TOML:

[default.Tests]
project = true

aqua=true is missing.

# (3) Space-separated single string — works correctly
$ ... config set --tests "aqua=true project=true" --config-file /tmp/jtc-test.toml
Set default Tests.project: true
Set default Tests.aqua: true

Resulting TOML:

[default.Tests]
aqua = true
project = true

Why users would type the broken forms

• The help text for --tests (and every other plugin flag) only says Set <Plugin> plugin defaults (omit value to enable with defaults) with metavar KEY=VALUE. There is no example of how to provide multiple pairs.

• The help text for --author does document two forms explicitly: Examples: --author 'A, B' or --author 'A' --author 'B'. Supports both single and multiple authors. Users naturally generalise this to plugin flags and try --tests "aqua=true,project=true" — which then mis-parses.

• Users coming from the Python port (JuliaPkgTemplatesCLI) will try repeating --tests because that is the form that worked there.

• The actual intended form — space-separated KEY=VALUEs in a single shell-quoted string — only appears in src/cli.jl:186 as an internal comment:

  # `argumentless_as_flag=true` matches the legacy `create` registration where
  # zero-arg plugins become bare flags. When false, every plugin accepts an
  # optional space-separated KEY=VALUE string (`--plugin` / `--plugin "k=v ..."`).
  

Suggested fixes

Pick any combination:

1. Reject malformed values for known-scalar keys. Tests.aqua is a boolean — a list value should error out instead of being persisted.
2. Document the supported form in the help text of every plugin flag, e.g. Multiple keys: --tests "aqua=true project=true".
3. Also accept repeat and comma-separated forms, and normalise all three to the same internal representation. This matches what --author already trains users to expect, and avoids regressing users coming from the Python port.
4. Echo a unified diff before saving and require confirmation when a previously-set scalar would be replaced by a list (or vice-versa). This would also catch (1) at runtime.
5. Update the README to show at least one explicit example of setting multiple keys for a single plugin, in whatever form ends up being canonical.

Environment

• Source: PkgTemplatesCommandLineInterface.jl (this repository), invoked via julia --project=. -e 'using PkgTemplatesCommandLineInterface; PkgTemplatesCommandLineInterface.main(ARGS)' -- ...
• Verified against --config-file /tmp/jtc-test.toml to avoid touching the global config.

[ultimatile]

Update from PR #8 review cycle:

After PR #8 unified create plugin registration with config set (both now use nargs='?', constant="", default=nothing), the input-form question raised here applies to create as well — comma-separated and repeat-flag forms behave the same way on both paths now.

Filed #9 as the prerequisite refactor: share the _split_plugin_option_string / _parse_plugin_kv_string / parse_plugin_option_value helpers between create and config set so the input-form discussion can converge in one place rather than fragmenting per command.

Once #9 lands, the four resolutions proposed here apply uniformly across both commands.

[ultimatile]

Implementation plan (approved)

After PR #10 unified the parser between create and config set, both commands now share the same input contract — making this issue's resolution apply uniformly to both. The design follows POSIX/GNU/clig.dev conventions: repeat-flag is canonical for multi-key plugin options, comma-separated KEY=VALUE is rejected as an anti-pattern.

Reference design choices

• Standards: POSIX/GNU/clig.dev all converge on repeat-flag for multi-value options. clig.dev explicitly flags comma-separated as anti-pattern (values may contain commas, quoting is brittle, shell composition fails).
• Major tools: docker/kubectl/podman use -e KEY=VALUE -e KEY2=VALUE2. Python port's behaviour is not carried over for the broken cases (we improve where Python diverged from standards).
• No short options for plugins: avoids collision (--git vs --gitlab) and clig.dev recommends short flags only for standard / very common operations.
• No @file input: separate concern, tracked elsewhere if needed.

Commit 1 — feat(cli): repeat-flag support

• src/cli.jl::add_dynamic_plugin_options!: change registration to :action => :append_arg, :nargs => '?', :constant => "", :default => nothing. Help text updated to mention both forms (repeat or quoted bundle).
• src/create_command.jl::parse_plugin_options: add value isa AbstractVector branch. Each element runs through parse_kv_string; results merge into the per-plugin section (last-wins for duplicate keys). Existing AbstractString branch stays for direct callers / tests.
• src/config_command.jl::_apply_set_args: same AbstractVector branch with the same merge semantics, plus per-set messages entries for user feedback.

ArgParse with :append_arg + :nargs='?' returns Vector{Any}:

• Any[] → not specified
• Any[""] → bare --git → enable plugin with defaults
• Any["ssh=true"] → single bundle
• Any["ssh=true", "manifest=false"] → repeated flag → merge
• Any["", "ssh=true"] → mixed bare + KV → empty-string elements are no-ops

Commit 2 — fix(parser): friendly error for comma-KV

• src/errors.jl: new PluginOptionFormatError(message::String) <: JTCError with Base.showerror for clean formatting.
• src/PkgTemplatesCommandLineInterface.jl: export PluginOptionFormatError.
• src/plugin_option_parser.jl::parse_kv_string: after splitting (k, v), detect when the unquoted value contains both , and =. Raise PluginOptionFormatError with a message that names the offending key/value and shows both canonical forms.

Example error:

Plugin option value "true,project=true" looks like a comma-separated list of
KEY=VALUE pairs, which is not supported. Please use one of:
  --tests aqua=true --tests project=true
  --tests "aqua=true project=true"

The check is gated on "value is unquoted" so name="Doe, Jane" (legitimate quoted comma) and ignore=.DS_Store,.vscode (legitimate list-value comma without =) keep working.

Commit 3 — test: contract coverage

• test/test_plugin_option_parser.jl:
  • Reject aqua=true,project=true and similar comma-with-= shapes (3-4 cases).
  • Confirm ignore=.DS_Store,.vscode still becomes a Vector (no false-positive).
• test/test_create_command.jl (E2E through real ArgParse):
  • Repeat flag merges into single plugin section.
  • Repeat flag last-wins for duplicate key.
  • Bare + KV mix (--git --git ssh=true).
  • Comma-with-= produces friendly error.
• test/test_config_command.jl:
  • Same E2E coverage on the persistence path: repeat flag round-trips through TOML.

Cross-form equivalence contract

--<plugin> "k1=v1 k2=v2" and --<plugin> k1=v1 --<plugin> k2=v2 must produce identical plugin option sections. Asserted via direct comparison in the test suite.

Out of scope

• --option=value attached form (already works via ArgParse default).
• File-based input (@file) — separate issue if requested.
• config show value options (no current need; would expand the docstring contract that show is read-only).