Feat/core stability

[Weinsen]

Summary

Improve runtime stability for interactive prompts and align enum completion and validation with actual command parsing.

User-facing and developer-facing impact:

• invalid typed and enum inputs now return readable error messages instead of raw exceptions
• positional enum parameters no longer suggest misleading name=value completions
• entering a=A for a positional enum now returns a specific correction hint
• Ctrl-C now requests graceful shutdown on the first press and forces exit on the second press

What Changed

• tightened Parameter.cast() so invalid typed and enum values raise readable ValueError messages
• updated Command.eval() to detect mistaken positional enum assignment syntax and suggest the correct positional form
• limited completer value suggestions to keyword parameters so completion matches runtime behavior
• added graceful and forced Ctrl-C handling in the prompt runtime using shared shutdown state from BasePrompter
• expanded regression coverage for completer behavior, parameter validation, shutdown escalation, and prompt-side interrupts

Type of Change

• Bugfix: fixes misleading completion behavior and raw exception surfacing
• Enhancement: improves interactive shutdown and CLI error UX

Validation

• pytest -q
• Manual: python examples/dynamic_options.py
• Verified first Ctrl-C at an idle prompt exits cleanly with the graceful shutdown message
• Verified wait 60 keeps running after the first Ctrl-C, then exits with status 130 and no traceback on the second Ctrl-C
• ./tools/lint.sh --changed not run
• ./tools/test.sh -q not run
• ./tools/docs.sh not run
• python -m build not run

Notes for Reviewers

• shutdown policy now lives in BasePrompter.request_shutdown(), while Prompter owns only the prompt_toolkit and SIGINT integration
• Prompter.run() was flattened so prompt and command interrupts share one runtime interrupt path instead of duplicated except KeyboardInterrupt branches
• the completer change is intentionally conservative: only keyword parameters receive name=value suggestions

[Copilot]

Pull request overview

This PR improves interactive runtime stability and CLI UX by making parameter casting errors user-friendly, aligning enum validation/completion with actual parsing behavior, and implementing graceful-then-forced Ctrl-C shutdown semantics across the prompt runtime.

Changes:

• Convert raw casting failures (typed + enum) into readable ValueError messages and add a specific hint for mistaken name=value usage on positional enum parameters.
• Align completion behavior with parsing by limiting name=value value suggestions to keyword parameters and hardening value-splitting.
• Add shared shutdown escalation (BasePrompter.request_shutdown) and integrate SIGINT/prompt interrupt handling in Prompter, with new regression tests.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/cmdcraft/base.py	Adds shutdown state + graceful/forced shutdown API; improves unknown-command handling in interpret().
src/cmdcraft/prompter.py	Installs SIGINT handler, exits active prompt cleanly, and unifies runtime interrupt handling.
src/cmdcraft/parameter.py	Tightens runtime casting logic and returns readable ValueError messages for invalid typed/enum values.
src/cmdcraft/command.py	Detects and reports mistaken positional enum assignment syntax (a=A) with a corrective hint.
src/cmdcraft/completer.py	Restricts value completions to keyword params and improves splitting to match parsing behavior.
test/test_base.py	Adds regression tests for unknown command output, shutdown escalation, and positional enum hinting.
test/test_prompter.py	Adds regression tests for SIGINT behavior and prompt/runtime interrupt handling.
test/test_completer.py	Adds regression tests ensuring only keyword parameters get name=value completions.
test/test_parameter.py	Updates/extends casting tests, including exact enum error message assertions.

---

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