Add confirmation option (--yes / -y)

Add confirmation_option() and confirmation_option["prompt"]() builder
methods on Command. When enabled, auto-registers --yes/-y flag and
prompts the user for confirmation after parsing. Passing --yes or -y
skips the prompt. Aborts on decline or non-interactive stdin.

Equivalent to Click's confirmation_option decorator.

- 13 new tests in tests/test_confirmation.mojo
- Update user manual, changelog, planning doc
- 526 tests across 18 files, all passing

Author: forfudan

docs/argmojo_overall_planning.md

@@ -69,7 +69,7 @@ These features appear across multiple libraries and depend only on string operat
 | Argument parents (shared args)     | ✓        | —     | —     | —    |                              | **Done**      |
 | Interactive prompting              | —        | ✓     | —     | —    |                              | **Done**      |
 | Password / masked input            | —        | ✓     | —     | —    |                              | Phase 5       |
-| Confirmation (`--yes` / `-y`)      | —        | ✓     | —     | —    |                              | Phase 5       |
+| Confirmation (`--yes` / `-y`)      | —        | ✓     | —     | —    |                              | **Done**      |
 | Pre/Post run hooks                 | —        | —     | ✓     | —    |                              | Phase 5       |
 | REMAINDER number_of_values         | ✓        | —     | —     | —    |                              | **Done**      |
 | Partial parsing (known args)       | ✓        | —     | —     | ✓    |                              | **Done**      |
@@ -168,7 +168,8 @@ tests/
 ├── test_fullwidth.mojo             # full-width → half-width auto-correction tests
 ├── test_groups_help.mojo           # argument groups in help + value_name wrapping tests
 ├── test_prompt.mojo               # interactive prompting tests
-└── test_parents.mojo              # argument parents (shared definitions) tests
+├── test_parents.mojo              # argument parents (shared definitions) tests
+└── test_confirmation.mojo         # confirmation option (--yes / -y) tests
 examples/
 ├── demo.mojo                       # comprehensive showcase of all ArgMojo features
 ├── mgrep.mojo                      # grep-like CLI example (no subcommands)
@@ -239,6 +240,7 @@ examples/
 | Registration-time validation for group constraints (`mutually_exclusive`, `required_together`, etc.)  | ✓      | ✓     |
 | Interactive prompting (`.prompt()`, `.prompt["..."]()` → prompt for missing args)                     | ✓      | ✓     |
 | Argument parents (`add_parent(parent)` → share args across commands)                                  | ✓      | ✓     |
+| Confirmation option (`confirmation_option()` → `--yes`/`-y` to skip confirmation)                     | ✓      | ✓     |
 
 > ⚠ Response file support is temporarily disabled due to a Mojo compiler deadlock under `-D ASSERT=all`. The implementation is preserved and will be re-enabled when the compiler bug is fixed.
 
@@ -587,7 +589,7 @@ Before adding Phase 5 features, further decompose `parse_arguments()` for readab
 - [x] **Argument parents** — `add_parent(parent)` copies all arguments and group constraints from a parent Command, sharing definitions across multiple commands (argparse `parents`) (PR #25)
 - [x] **Interactive prompting** — prompt user for missing required args instead of erroring (Click `prompt=True`) (PR #23)
 - [ ] **Password / masked input** — hide typed characters for sensitive values (Click `hide_input=True`)
-- [ ] **Confirmation option** — built-in `--yes` / `-y` to skip confirmation prompts (Click `confirmation_option`)
+- [x] **Confirmation option** — `confirmation_option()` or `confirmation_option["prompt"]()` auto-registers `--yes`/`-y` flag; prompts user for confirmation after parsing; aborts on decline or non-interactive stdin (Click `confirmation_option`) (PR #26)
 - [ ] **Pre/Post run hooks** — callbacks before/after main logic (cobra `PreRun`/`PostRun`)
 - [x] **Remainder positional** — `.remainder()` consumes ALL remaining tokens (including `-` prefixed); at most one per command, must be last positional (argparse `nargs=REMAINDER`, clap `trailing_var_arg`) (PR #13)
 - [x] **Allow hyphen values** — `.allow_hyphen_values()` on positional accepts dash-prefixed tokens as values without `--`; remainder enables this automatically (clap `allow_hyphen_values`) (PR #13)

docs/changelog.md

@@ -25,6 +25,7 @@ Comment out unreleased changes here. This file will be edited just before each r
 13. **Registration-time validation for group constraints.** `mutually_exclusive()`, `required_together()`, `one_required()`, and `required_if()` now validate argument names against `self.args` at the moment they are called. An `Error` is raised immediately if any name is unknown, empty lists are rejected, and duplicates are silently deduplicated. `required_if()` additionally rejects self-referential rules (`target == condition`). This catches developer typos on the very first `mojo run`, without waiting for end-user input (PR #22).
 14. **Interactive prompting.** Add `.prompt()` and `.prompt["text"]()` builder methods on `Argument`. When an argument marked with `.prompt()` is not provided on the command line, the user is interactively prompted for its value before validation runs. Use `.prompt()` to prompt with the argument's help text, or `.prompt["Custom text"]()` to set a custom message. Works on both required and optional arguments. Prompts show valid choices for `.choice[]()` arguments and show default values in parentheses. For flag arguments, `y`/`n` input is accepted. When stdin is not a terminal (e.g., piped input, CI environments, `/dev/null`), or when `input()` otherwise raises, the exception is caught, prompting stops gracefully, and any values collected so far are preserved (PR #23).
 15. **Argument parents.** Add `add_parent(parent)` method on `Command`. Copies all argument definitions and group constraints (mutually exclusive, required together, one-required, conditional requirements, implications) from a parent `Command` into the current command. This lets you share a common set of arguments across multiple commands without repeating them — equivalent to Python argparse's `parents` parameter. The parent is not modified. All registration-time validation guards run on each inherited argument as usual (PR #25).
+16. **Confirmation option.** Add `confirmation_option()` and `confirmation_option["prompt"]()` builder methods on `Command`. When enabled, the command automatically registers a `--yes` / `-y` flag and prompts the user for confirmation after parsing (and after interactive prompting, if any). If the user does not confirm (`y`/`yes`), the command aborts with an error. Passing `--yes` or `-y` on the command line skips the prompt entirely. When stdin is not interactive (piped input, `/dev/null`), the command aborts gracefully. This is equivalent to Click's `confirmation_option` decorator (PR #26).
 
 ### 🦋 Changed in v0.4.0
 
@@ -61,6 +62,7 @@ Comment out unreleased changes here. This file will be edited just before each r
 - Add `pixi run debug` task that runs all examples under `-D ASSERT=all` with `--help` to exercise registration-time validation in CI (PR #22).
 - Add `tests/test_prompt.mojo` with tests covering interactive prompting builder methods, optional/required prompt arguments, prompting skipped when values are provided, choices and defaults integration, field propagation through copy, and combined features (PR #23).
 - Add `tests/test_parents.mojo` with 20 tests covering argument parents: basic flag/value/positional/default inheritance, short flags, multiple parents, child-own args coexistence, group constraint inheritance (mutually exclusive, required together, one-required, conditional, implications), parent shared across children, count/append/range argument inheritance, empty parent, parent immutability, and parent with subcommands (PR #25).
+- Add `tests/test_confirmation.mojo` with 13 tests covering confirmation option: `--yes`/`-y` flag skips, non-interactive stdin abort, custom prompt text, coexistence with other arguments, no-confirmation normal behavior, subcommand integration, copy preservation, prompt argument integration, and parent argument integration (PR #26).
 
 ---
 

docs/user_manual.md

@@ -92,6 +92,11 @@ from argmojo import Argument, Command
   - [Multiple Parents](#multiple-parents)
   - [Using with Subcommands](#using-with-subcommands)
   - [Notes](#notes)
+- [Confirmation Option](#confirmation-option)
+  - [Basic Usage](#basic-usage)
+  - [Custom Prompt Text](#custom-prompt-text)
+  - [Using with Subcommands](#using-with-subcommands-1)
+  - [Non-Interactive Use](#non-interactive-use)
 - [Shell Completion](#shell-completion)
   - [Built-in `--completions` Flag](#built-in---completions-flag)
   - [Disabling the Built-in Flag](#disabling-the-built-in-flag)
@@ -3193,6 +3198,85 @@ var result = app.parse()
 - Child arguments added via `add_argument()` coexist with inherited ones.
 - If you need different constraints for different children, apply them after `add_parent()` on each child individually.
 
+## Confirmation Option
+
+Some commands are destructive or irreversible — dropping databases, deleting files, deploying to production. The **confirmation option** adds a built-in `--yes` / `-y` flag that lets users skip an interactive confirmation prompt. This is equivalent to Click's `confirmation_option` decorator.
+
+### Basic Usage
+
+```mojo
+from argmojo import Command, Argument
+
+fn main() raises:
+    var cmd = Command("drop", "Drop the database")
+    cmd.add_argument(
+        Argument("name", help="Database name").positional().required()
+    )
+    cmd.confirmation_option()
+
+    var result = cmd.parse()
+    # Without --yes: prompts "Are you sure? [y/N]: "
+    # With --yes or -y: skips the prompt
+    print("Dropping database:", result.get_string("name"))
+```
+
+Running without `--yes`:
+
+```sh
+$ ./drop mydb
+Are you sure? [y/N]: y
+Dropping database: mydb
+```
+
+Running with `--yes`:
+
+```sh
+$ ./drop mydb --yes
+Dropping database: mydb
+```
+
+### Custom Prompt Text
+
+Use the compile-time parameter overload to set a custom prompt:
+
+```mojo
+cmd.confirmation_option["Drop the database? This cannot be undone."]()
+```
+
+This changes the prompt to:
+  
+```sh
+Drop the database? This cannot be undone. [y/N]:
+```
+
+### Using with Subcommands
+
+Confirmation works naturally with subcommands. The `--yes` flag is registered on the command that calls `confirmation_option()`:
+
+```mojo
+var app = Command("app", "My app")
+app.confirmation_option()
+
+var deploy = Command("deploy", "Deploy to production")
+deploy.add_argument(Argument("env", help="Environment").positional().required())
+app.add_subcommand(deploy^)
+
+var result = app.parse()
+# app --yes deploy prod  →  skips confirmation
+```
+
+### Non-Interactive Use
+
+When stdin is not available (piped input, CI environments, `/dev/null`), the confirmation prompt cannot be displayed. In this case, the command **aborts with an error** unless `--yes` is passed. This ensures that destructive commands never run silently without explicit opt-in:
+
+```sh
+$ echo "" | ./drop mydb
+error: drop: Aborted (no interactive input available)
+
+$ ./drop mydb --yes    # works in CI
+Dropping database: mydb
+```
+
 ## Shell Completion
 
 ArgMojo can generate **shell completion scripts** for Bash, Zsh, and Fish. These scripts enable tab-completion for your CLI's options, flags, subcommands, and choice values — with zero runtime overhead.
@@ -3479,6 +3563,7 @@ The table below maps every ArgMojo builder method / command-level method to its
 | `parse_known_arguments()`   | `parse_known_args()`             | —                               | — ¹¹                           | `FParseErrWhitelist` ¹²         |
 | `response_file_prefix()`    | `fromfile_prefix_chars="@"`      | —                               | —                              | —                               |
 | `add_parent(parent)`        | `parents=[parent]`               | —                               | —                              | —                               |
+| `confirmation_option()`     | —                                | `confirmation_option`           | —                              | —                               |
 
 ### Notes
 

pixi.toml

@@ -43,7 +43,8 @@ test = """\
     && mojo run -I src -D ASSERT=all tests/test_fullwidth.mojo \
     && mojo run -I src -D ASSERT=all tests/test_groups_help.mojo \
     && mojo run -I src -D ASSERT=all tests/test_prompt.mojo < /dev/null \
-    && mojo run -I src -D ASSERT=all tests/test_parents.mojo"""
+    && mojo run -I src -D ASSERT=all tests/test_parents.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_confirmation.mojo < /dev/null"""
 # NOTE: test_response_file.mojo is excluded — response file expansion
 # is temporarily disabled to work around a Mojo compiler deadlock
 # with -D ASSERT=all.  Re-enable when the compiler bug is fixed.

src/argmojo/command.mojo

@@ -242,6 +242,14 @@ struct Command(Copyable, Movable, Stringable, Writable):
     CJK punctuation (e.g. em-dash ``U+2014``) is substituted before
     running Levenshtein typo suggestion.  Call
     ``disable_punctuation_correction()`` to opt out."""
+    var _confirmation_enabled: Bool
+    """When True, the command prompts the user for confirmation before
+    returning the parse result.  If ``--yes`` / ``-y`` is provided on
+    the command line, the prompt is skipped.  Enable via
+    ``confirmation_option()``."""
+    var _confirmation_prompt: String
+    """The prompt text shown when asking for confirmation.
+    Defaults to ``"Are you sure?"``."""
 
     # ===------------------------------------------------------------------=== #
     # Life cycle methods
@@ -285,6 +293,8 @@ struct Command(Copyable, Movable, Stringable, Writable):
         self._response_file_max_depth = 10
         self._disable_fullwidth_correction = False
         self._disable_punctuation_correction = False
+        self._confirmation_enabled = False
+        self._confirmation_prompt = String("")
         self._header_color = _DEFAULT_HEADER_COLOR
         self._arg_color = _DEFAULT_ARG_COLOR
         self._warn_color = _DEFAULT_WARN_COLOR
@@ -325,6 +335,8 @@ struct Command(Copyable, Movable, Stringable, Writable):
         self._disable_punctuation_correction = (
             move._disable_punctuation_correction
         )
+        self._confirmation_enabled = move._confirmation_enabled
+        self._confirmation_prompt = move._confirmation_prompt^
         self._header_color = move._header_color^
         self._arg_color = move._arg_color^
         self._warn_color = move._warn_color^
@@ -382,6 +394,8 @@ struct Command(Copyable, Movable, Stringable, Writable):
         self._disable_punctuation_correction = (
             copy._disable_punctuation_correction
         )
+        self._confirmation_enabled = copy._confirmation_enabled
+        self._confirmation_prompt = copy._confirmation_prompt
         self._header_color = copy._header_color
         self._arg_color = copy._arg_color
         self._warn_color = copy._warn_color
@@ -1301,6 +1315,83 @@ struct Command(Copyable, Movable, Stringable, Writable):
                 )
         self._help_on_no_arguments = True
 
+    fn confirmation_option(mut self) raises:
+        """Adds a ``--yes`` / ``-y`` flag to skip a confirmation prompt.
+
+        When enabled, the command will prompt the user with
+        ``"Are you sure? [y/N]: "`` after parsing (and after interactive
+        prompting, if any) but before validation.  If the user does not
+        answer ``y`` or ``yes``, the command aborts with an error.
+
+        Passing ``--yes`` or ``-y`` on the command line skips the prompt
+        entirely.  This is equivalent to Click's ``confirmation_option``
+        decorator.
+
+        Raises:
+            Error if a ``--yes`` / ``-y`` argument is already registered.
+
+        Example:
+
+        ```mojo
+        from argmojo import Command, Argument
+
+        var cmd = Command("drop", "Drop the database")
+        cmd.add_argument(
+            Argument("name", help="Database name")
+            .positional().required()
+        )
+        cmd.confirmation_option()
+        # Users must pass --yes (or -y) to skip the prompt:
+        #   drop mydb --yes
+        ```
+        """
+        self._confirmation_enabled = True
+        self._confirmation_prompt = String("Are you sure?")
+        self.add_argument(
+            Argument("yes", help="Skip confirmation prompt")
+            .long["yes"]()
+            .short["y"]()
+            .flag()
+        )
+
+    fn confirmation_option[prompt: StringLiteral](mut self) raises:
+        """Adds a ``--yes`` / ``-y`` flag with a custom confirmation prompt.
+
+        Behaves like ``confirmation_option()`` but uses the provided
+        ``prompt`` text instead of the default ``"Are you sure?"``.
+
+        Parameters:
+            prompt: The custom prompt text to display.
+
+        Raises:
+            Error if a ``--yes`` / ``-y`` argument is already registered.
+
+        Example:
+
+        ```mojo
+        from argmojo import Command, Argument
+
+        var cmd = Command("drop", "Drop the database")
+        cmd.add_argument(
+            Argument("name", help="Database name")
+            .positional().required()
+        )
+        cmd.confirmation_option["Drop the database? This cannot be undone."]()
+        ```
+        """
+        constrained[
+            len(prompt) > 0,
+            "confirmation_option: prompt text must not be empty",
+        ]()
+        self._confirmation_enabled = True
+        self._confirmation_prompt = String(prompt)
+        self.add_argument(
+            Argument("yes", help="Skip confirmation prompt")
+            .long["yes"]()
+            .short["y"]()
+            .flag()
+        )
+
     # [Mojo Miji]
     # `name` is a type parameter (StringLiteral) rather than a runtime
     # argument so that the colour name is validated at compile time.
@@ -1833,11 +1924,12 @@ struct Command(Copyable, Movable, Stringable, Writable):
 
         # Apply defaults, propagate implications, prompt for remaining
         # values, re-apply implications (in case prompts triggered new
-        # ones), then validate constraints.
+        # ones), confirm if required, then validate constraints.
         self._apply_defaults(result)
         self._apply_implications(result)
         self._prompt_missing_args(result)
         self._apply_implications(result)
+        self._confirm(result)
         self._validate(result)
 
         return result^
@@ -2558,6 +2650,39 @@ struct Command(Copyable, Movable, Stringable, Writable):
                 )
             return -1
 
+    # ===------------------------------------------------------------------=== #
+    # Confirmation prompt
+    # ===------------------------------------------------------------------=== #
+
+    fn _confirm(self, result: ParseResult) raises:
+        """Prompts the user for confirmation if ``confirmation_option()`` is
+        enabled and ``--yes`` / ``-y`` was not passed.
+
+        Aborts with an error if the user does not confirm, or if stdin is
+        not interactive (e.g. piped / ``/dev/null``).
+
+        Args:
+            result: The parse result (read-only; only checks the ``yes``
+                flag).
+
+        Raises:
+            Error: If the user declines or stdin is unavailable.
+        """
+        if not self._confirmation_enabled:
+            return
+        if result.get_flag("yes"):
+            return
+        var prompt = self._confirmation_prompt + " [y/N]: "
+        var value: String
+        try:
+            value = input(prompt)
+        except:
+            self._error("Aborted (no interactive input available)")
+            return
+        var lower = value.lower()
+        if lower != "y" and lower != "yes":
+            self._error("Aborted")
+
     # ===------------------------------------------------------------------=== #
     # Interactive prompting
     # ===------------------------------------------------------------------=== #