[Feat] Add CLI variable injection (-p/--parameter) and custom INPUT path (-in/--input) (PART I)

[ZhouXY-PKU]

Reminder

• I have read AGENTS.md and docs/developers_guide/agent_governance.md.
• I have linked an issue or explained why this PR does not need one.
• I have added adequate unit tests and/or case tests, or explained why not.
• I have listed the exact verification commands run and their results.
• I have described user-visible behavior changes, including INPUT parameter changes.
• I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other source/ changes.
• I have requested any needed governance exception below.

Linked Issue

Part 1 of 2 of the CLI variable-injection feature. This PR implements the
command-line parsing layer and the -in/--input wiring; the actual
substitution of ${var} / $var inside INPUT is delivered by PART II
(ReadInput signature extension + token-level substitution), which depends
on this PR. No dedicated issue exists for the split; this PR body serves as
the phase tracker.

Unit Tests and/or Case Tests for my changes

• Commands run:

cmake --build build -j$(nproc)
ctest --test-dir build -V -R “test_parse_command_line|test_parse_args”

• CLI functional checks

./build/abacus --help | grep – “–parameter”
./build/abacus -p only_name # expect: requires <name> <value>, exit 1
./build/abacus -p 1abc x # expect: Invalid variable name, exit 1
./build/abacus --bogus # expect: Unknown argument, exit 1 (unchanged)
./build/abacus --version # unchanged

• in end-to-end

cd tests/integrate/001*
cp INPUT INPUT.alt # INPUT.alt: suffix = AltRun
OMP_NUM_THREADS=1 mpirun -np 4 /abs/path/build/abacus -in INPUT.alt
OMP_NUM_THREADS=1 mpirun -np 4 /abs/path/build/abacus

• Result summary:
  • Unit tests: 11 cases in ParseCommandLineTest pass (short/long form,
    last-wins for repeated -p, -in combination, default input path,
    missing-value/empty-name/digit-leading-name/unknown-option/truncated-argc
    all throw). test_parse_args passthrough unchanged.
  • --help output now lists -p, --parameter and -in, --input (text added
    to show_general_help() so it flows through the existing -h path).
  • -in INPUT.alt: reads the given file, running_scf.log shows
    global_in_card = INPUT.alt, OUT.AltRun/INPUT.alt.info written;
    default run (no -in) byte-identical to pre-change behavior.
• Checks not run, with reason:
  • Full integrate-suite regression: not run in CI locally; default-path
    behavior verified unchanged on 104_PW_NC_magnetic, and all changes are
    gated behind new flags that default to prior behavior.
  • End-to-end effect of -p on INPUT values: not applicable in PART I
    (see "What's changed"); the parsed variables are validated and stored but
    do not yet affect INPUT. Covered in PART II with its own tests
    (test_var_substitute, read-input token substitution, variable keyword).

What's changed?

User-visible changes:

• New CLI options:
  • -p, --parameter <name> <value> (repeatable, last wins): parse-time
    validated (non-empty, non-digit-leading, alnum/underscore name), stored in
    ModuleIO::CommandLineArgs::vars and forwarded to Driver::init().
    In PART I these values are not yet applied to INPUT parameters — that
    is PART II (ReadInput variable substitution). Accepted and validated now
    so the CLI contract is frozen early and PART II only touches the INPUT layer.
  • -in, --input <file> (default INPUT): fully functional. Overrides the
    INPUT file path for reading, the global_in_card line in running_*.log,
    and the INPUT.info filename in the output directory.
• --help / -h text extended accordingly (in show_general_help(), the
  single source of help text; parse_command_line's own usage string remains
  minimal and is only shown on CLI error paths).
• Unknown-flag, missing-value, and invalid-name errors exit with code 1 and a
  one-line message; existing flags (-h, --version, --search,
  --check-input, --generate-parameters-yaml) behave exactly as before.

Developer-facing changes:

• source_io/parse_command_line.{h,cpp} (new): CommandLineArgs{vars, input_file} and parse_command_line(argc, argv). parse_args forwards
  -p/-in tokens to it (additive change; all pre-existing flags handled
  where they were before).
• source_main/driver.{h,cpp}: Driver::init/atomic_world/reading take
  const ModuleIO::CommandLineArgs&; reading() passes cli.input_file
  explicitly to read_parameters(PARAM, cli.input_file),
  print_start_info(input_card), and the INPUT.info path; print_start_info
  gains a named input_card parameter. No globals added; everything flows
  through explicit parameters (governance rule 1).
• source_io/input_help.cpp: help text for the two new options only.
• Build system: added source_io/parse_command_line.cpp to both the CMake source list and the source/Makefile object list (Makefile requires manual registration; caught by the “Build with Makefile” CI job).

Governance Notes

• INPUT/docs changes:
  • No INPUT parameter is added, removed, or re-ordered; INPUT files are
    untouched. Docs PR to follow in PART II when -p takes effect
    (documenting ${var}/$var syntax, variable keyword, precedence
    command line > INPUT variable > built-in default, and -in).
  • User-visible behavior change of PART I is limited to: two new accepted
    CLI flags, extended --help, and the global_in_card log line /
    INPUT.info filename now reflecting -in's value (previously always
    INPUT).
• Core module impact:
  • None. ESolver / HSolver / ElecState / Hamilt / Operator / Psi untouched.
    Changes are confined to source_io (parse/help) and source_main
    (driver wiring). read_parameters keeps its two-parameter signature in
    this PR; PART II will extend it and update its call sites
    (driver.cpp and read-input tests) — no default parameters are used
    (governance rule 5).
• Known technical debt (follow-up cleanup, not in this PR):
  • System_para::global_in_card is now effectively dead in the main flow:
    all three of its former consumers in driver.cpp (read path, log line,
    INPUT.info path) read cli.input_file explicitly instead. The member
    is kept because (a) removing it is an unrelated refactor that would bloat
    this feature diff, and (b) a full-repo audit is required first (para_json
    serialization, tests, downstream forks). Planned follow-up: audit with
    grep -rn "global_in_card" source/, then a standalone cleanup commit
    removing the member and updating any stragglers.
  • parse_command_line's internal usage string intentionally duplicates no
    --help content; on CLI errors it should print the minimal hint plus
    Run 'abacus -h' for usage. (kept minimal to avoid text drift with
    show_general_help()).
• Exceptions requested:
  • None.

[github-actions]

Agent Governance Check

Severity	Rule	Location	Reason	Suggested action	Exception
warning	Global dependency budget	source/source_main/driver.cpp:51	Added line introduces 3 GlobalV/GlobalC/PARAM reference(s); PR total added=7, removed=9, net_delta=-2.	Confirm this is a migration-neutral move or partial cleanup, and explain the remaining global dependency rationale.	allowed
warning	Global dependency budget	source/source_main/driver.cpp:110	Added line introduces 1 GlobalV/GlobalC/PARAM reference(s); PR total added=7, removed=9, net_delta=-2.	Confirm this is a migration-neutral move or partial cleanup, and explain the remaining global dependency rationale.	allowed
warning	Global dependency budget	source/source_main/driver.cpp:125	Added line introduces 1 GlobalV/GlobalC/PARAM reference(s); PR total added=7, removed=9, net_delta=-2.	Confirm this is a migration-neutral move or partial cleanup, and explain the remaining global dependency rationale.	allowed
warning	Global dependency budget	source/source_main/driver.cpp:126	Added line introduces 1 GlobalV/GlobalC/PARAM reference(s); PR total added=7, removed=9, net_delta=-2.	Confirm this is a migration-neutral move or partial cleanup, and explain the remaining global dependency rationale.	allowed
warning	Global dependency budget	source/source_main/driver.cpp:150	Added line introduces 1 GlobalV/GlobalC/PARAM reference(s); PR total added=7, removed=9, net_delta=-2.	Confirm this is a migration-neutral move or partial cleanup, and explain the remaining global dependency rationale.	allowed
warning	Header dependency review	source/source_io/parse_command_line.h:4	Header diff adds an include dependency.	Confirm the declaration requires this include; prefer forward declarations where practical.	allowed
warning	Header dependency review	source/source_io/parse_command_line.h:5	Header diff adds an include dependency.	Confirm the declaration requires this include; prefer forward declarations where practical.	allowed
warning	Header dependency review	source/source_main/driver.h:4	Header diff adds an include dependency.	Confirm the declaration requires this include; prefer forward declarations where practical.	allowed
warning	Documentation sync review	pull_request.body	Source changes have no docs change or explicit no-docs-needed statement.	Add documentation updates for behavior/interface changes, or state why documentation is not required.	allowed