strictcli 0.25.0__tar.gz → 0.27.0__tar.gz

{strictcli-0.25.0 → strictcli-0.27.0}/.rlsbl/config.json

@@ -14,5 +14,6 @@
       "type": "npm",
       "local": false
     }
-  }
+  },
+  "coverage_unit": "commit"
 }

{strictcli-0.25.0 → strictcli-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strictcli
-Version: 0.25.0
+Version: 0.27.0
 Summary: A strict, zero-dependency CLI framework for Python
 Project-URL: Homepage, https://github.com/smm-h/strictcli
 Project-URL: Repository, https://github.com/smm-h/strictcli

{strictcli-0.25.0 → strictcli-0.27.0}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "strictcli",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "strictcli",
-      "version": "0.25.0",
+      "version": "0.27.0",
       "hasInstallScript": true,
       "license": "MIT"
     }

{strictcli-0.25.0 → strictcli-0.27.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strictcli",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "A strict, zero-dependency CLI framework for Python (npm wrapper)",
   "main": "index.js",
   "scripts": {

{strictcli-0.25.0 → strictcli-0.27.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "strictcli"
-version = "0.25.0"
+version = "0.27.0"
 description = "A strict, zero-dependency CLI framework for Python"
 readme = "README.md"
 license = "MIT"

{strictcli-0.25.0 → strictcli-0.27.0}/strictcli/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.25.0"
+__version__ = "0.27.0"
 
 __all__ = [
     "App", "Flag", "Arg", "FlagSet", "MutexGroup", "CoRequired", "Requires",
@@ -30,7 +30,10 @@ import tomllib
 from collections import deque
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Callable, Protocol, get_args, get_origin, runtime_checkable
+from typing import Any, Callable, Protocol, TypeVar, get_args, get_origin, runtime_checkable
+
+# TypeVar for decorator return types — preserves the decorated function's type
+F = TypeVar("F", bound=Callable[..., Any])
 
 
 # Sentinel for distinguishing "not provided" from actual values
@@ -657,21 +660,33 @@ def _generate_config_template_toml(
     """Generate a TOML config template with comments."""
     lines: list[str] = []
 
+    # A config field whose name equals a flag's param name is validation-only:
+    # it annotates the flag and the key is rendered once (on the flag).
+    flag_params = {_flag_param_name(f.name) for f in flags}
+    colliding = {n: cf for n, cf in config_fields.items() if n in flag_params}
+
     # Flag-backed keys (flat)
     for f in flags:
         param = _flag_param_name(f.name)
-        lines.append(f"# {f.help}")
+        comment = f"# {f.help}"
+        cf_collide = colliding.get(param)
+        if cf_collide is not None:
+            comment += f" -- {cf_collide.help}"
+        lines.append(comment)
         if f.default is not None:
             lines.append(f"{param} = {_toml_format_scalar(f.default)}")
         else:
             lines.append(f"# {param} =")
         lines.append("")
 
-    # Config field keys (possibly nested via dot names)
+    # Config field keys (possibly nested via dot names). Skip colliding fields
+    # (already rendered on the flag line above).
     # Group by first segment for TOML sections
     top_level: list[tuple[str, "ConfigField"]] = []
     sections: dict[str, list[tuple[str, "ConfigField"]]] = {}
     for name, cf in config_fields.items():
+        if name in colliding:
+            continue
         parts = name.split(".")
         if len(parts) == 1:
             top_level.append((name, cf))
@@ -728,6 +743,9 @@ def _generate_config_template_json(
 ) -> str:
     """Generate a JSON config template."""
     data: dict = {}
+    # A config field colliding with a flag's param name is validation-only; the
+    # flag owns the rendered value, so the key appears once.
+    flag_params = {_flag_param_name(f.name) for f in flags}
     # Flag-backed keys
     for f in flags:
         param = _flag_param_name(f.name)
@@ -736,8 +754,11 @@ def _generate_config_template_json(
         else:
             data[param] = None
 
-    # Config field keys (nested via dot names)
+    # Config field keys (nested via dot names). Skip colliding fields (rendered
+    # once via the flag above).
     for name, cf in config_fields.items():
+        if name in flag_params:
+            continue
         if not cf.required:
             _nested_set(data, name, cf.default)
         else:
@@ -784,6 +805,43 @@ def _split_escaped(value: str, sep: str) -> list[str]:
     return parts
 
 
+def _values_equal_for_conflict(cli_val: object, config_val: object, flag: "Flag") -> bool:
+    """Compare a CLI/env value and a config value for conflict-mode equality.
+
+    Equality semantics (pinned):
+    - scalars: exact equality.
+    - plain repeatable lists: order-sensitive exact equality.
+    - Unique flags: order-insensitive multiset equality.
+
+    When the two values are equal, config+CLI/env co-presence is NOT a conflict
+    (they agree), so error mode does not fire.
+    """
+    if flag.unique is True and isinstance(cli_val, list) and isinstance(config_val, list):
+        # Order-insensitive multiset comparison.
+        return sorted(cli_val, key=repr) == sorted(config_val, key=repr)
+    return cli_val == config_val
+
+
+def _check_flag_configfield_default(
+    flag_name: str, flag_default: object, cf: "ConfigField"
+) -> None:
+    """Raise ValueError when a colliding flag and config field have conflicting
+    explicit defaults.
+
+    A ConfigField whose name equals a flag's param name is a validation-only
+    declaration -- it annotates the flag. Their defaults must agree. The matrix:
+    both absent OK; equal OK; both present unequal = error; one absent OK (the
+    flag's default wins for rendering). A flag default of None means "no
+    default" (absent); a ConfigField default of _MISSING means absent.
+    """
+    flag_has_default = flag_default is not None
+    cf_has_default = not isinstance(cf.default, _MissingSentinel)
+    if flag_has_default and cf_has_default and flag_default != cf.default:
+        raise ValueError(
+            f'config field "{cf.name}" collides with flag "{flag_name}" but their defaults disagree ({cf.default!r} vs {flag_default!r}); remove one default or make them equal'
+        )
+
+
 def _find_duplicate(values: list) -> object | None:
     """Return the first duplicate value in the list, or None if all unique."""
     seen: set = set()
@@ -1395,6 +1453,11 @@ class Flag:
     validate: Callable | None = None
     repeatable: bool = False
     unique: object = _MISSING
+    # Per-flag config conflict mode. _MISSING means "inherit the app default".
+    # When set explicitly, must be "cli-wins" or "error". Applies to flags only:
+    # standalone ConfigFields have no CLI/env conflict surface, and a
+    # flag-colliding ConfigField inherits the flag's handling.
+    conflict_mode: object = _MISSING
     # Compound type fields (set by __post_init__, not by caller)
     compound: str = "scalar"  # "scalar", "list", or "dict"
     item_type: type | None = None  # for list[T]: the T
@@ -1478,6 +1541,13 @@ class Flag:
                 raise ValueError(f'Flag "{self.name}": unique requires repeatable=True')
             if isinstance(self.unique, _MissingSentinel) and not self.repeatable:
                 self.unique = False
+        # Validate conflict_mode (per-flag override of the app config conflict mode)
+        if not isinstance(self.conflict_mode, _MissingSentinel):
+            if self.conflict_mode not in ("cli-wins", "error"):
+                raise ValueError(
+                    f'Flag "{self.name}": conflict_mode must be "cli-wins" or '
+                    f'"error", got {self.conflict_mode!r}'
+                )
         # Validate env_separator
         if self.compound == "dict":
             # Dict flags use JSON for env vars, not env_separator
@@ -1904,10 +1974,10 @@ class Group:
         hidden: bool = False,
         interactive: bool = False,
         config_fields: list[str] | None = None,
-    ) -> Callable:
+    ) -> Callable[[F], F]:
         """Decorator to register a command within this group."""
 
-        def decorator(func: Callable) -> Callable:
+        def decorator(func: F) -> F:
             if name in self._groups:
                 raise ValueError(
                     f'command "{name}" collides with an existing group'
@@ -2137,6 +2207,18 @@ class App:
         """Return the resolved config file path for this app."""
         return _config_path(self.name, override=self.config_path, config_format=self.config_format)
 
+    def dump_schema_dict(self) -> dict:
+        """Return the app's full schema as a dict, excluding ``project_id``.
+
+        This is the public, CWD-free accessor for the schema. Unlike the
+        ``--dump-schema`` flag (which writes ``.strictcli/schema.json`` and
+        derives ``project_id`` from ``pyproject.toml`` in the current working
+        directory), this method reads only the in-memory ``App`` and performs
+        no filesystem or CWD access. The returned dict is byte-identical to the
+        written schema file with the ``project_id`` field removed.
+        """
+        return _dump_schema_core(self)
+
     def config_field(
         self,
         name: str,
@@ -2172,6 +2254,13 @@ class App:
                 f'config field name "{name}" conflicts with framework field'
             )
         cf = ConfigField(name=name, type=type, help=help, default=default)
+        # A config field colliding with an existing flag's param name is a
+        # validation-only declaration that annotates the flag; their defaults
+        # must agree. Flags registered after this field are checked from the
+        # command-builder side instead.
+        for f in self._collect_all_flags():
+            if _flag_param_name(f.name) == name:
+                _check_flag_configfield_default(f.name, f.default, cf)
         self._config_fields[name] = cf
         return cf
 
@@ -2202,9 +2291,9 @@ class App:
         self._framework_fields[name] = cf
         return cf
 
-    def check(self, name: str):
+    def check(self, name: str) -> Callable[[F], F]:
         """Decorator to register a check implementation."""
-        def decorator(fn):
+        def decorator(fn: F) -> F:
             if not self._checks_enabled:
                 raise ValueError(
                     f'cannot register check "{name}": '
@@ -2508,10 +2597,10 @@ class App:
         hidden: bool = False,
         interactive: bool = False,
         config_fields: list[str] | None = None,
-    ) -> Callable:
+    ) -> Callable[[F], F]:
         """Decorator to register a top-level command."""
 
-        def decorator(func: Callable) -> Callable:
+        def decorator(func: F) -> F:
             cmd = _build_and_validate_command(
                 name,
                 help=help,
@@ -2593,6 +2682,22 @@ class App:
             _collect_from_group(grp)
         return flags
 
+    def _colliding_config_fields(self) -> dict[str, ConfigField]:
+        """Return {flag_param_name: ConfigField} for config fields whose name
+        equals a flag's param name.
+
+        Such config fields are validation-only: they annotate the colliding
+        flag rather than rendering as a separate config key. Callers use this to
+        render the key once (on the flag line, with the config field's help as a
+        trailing annotation).
+        """
+        flag_params = {_flag_param_name(f.name) for f in self._collect_all_flags()}
+        return {
+            name: cf
+            for name, cf in self._config_fields.items()
+            if name in flag_params
+        }
+
     def _register_config_group(self) -> None:
         """Register the auto-generated 'config' command group."""
         config_grp = Group(
@@ -2628,14 +2733,18 @@ class App:
             use_json = _kw.get("json", False)
             config_data = app_ref._config_data
             all_flags = app_ref._collect_all_flags()
+            colliding = app_ref._colliding_config_fields()
             if use_json:
                 result = {}
                 for f in all_flags:
                     param = _flag_param_name(f.name)
                     value, source = _resolve_flag_show_source(f, config_data)
                     result[param] = {"value": value, "source": source}
-                # Include config fields
+                # Include config fields (skip those colliding with a flag: they
+                # are validation-only and render once, on the flag entry).
                 for cf_name, cf in app_ref._config_fields.items():
+                    if cf_name in colliding:
+                        continue
                     found, value = _nested_get(config_data, cf_name)
                     if found:
                         source = "config"
@@ -2661,12 +2770,22 @@ class App:
             for f in all_flags:
                 param = _flag_param_name(f.name)
                 value, source = _resolve_flag_show_source(f, config_data)
-                print(f"{param} = {_format_config_value(value)}  (source: {source})")
-            # Include config fields in plain output
-            if app_ref._config_fields:
+                line = f"{param} = {_format_config_value(value)}  (source: {source})"
+                # A colliding config field annotates the flag line (rendered once).
+                cf_collide = colliding.get(param)
+                if cf_collide is not None:
+                    line += f"  -- {cf_collide.help}"
+                print(line)
+            # Include config fields in plain output (skip colliding ones: they
+            # are rendered as an annotation on the flag line above).
+            non_colliding_fields = {
+                n: cf for n, cf in app_ref._config_fields.items()
+                if n not in colliding
+            }
+            if non_colliding_fields:
                 print()
                 print("Config fields:")
-                for cf_name, cf in app_ref._config_fields.items():
+                for cf_name, cf in non_colliding_fields.items():
                     found, value = _nested_get(config_data, cf_name)
                     if found:
                         source = "config"
@@ -3576,14 +3695,28 @@ class App:
                 param = _flag_param_name(f.name)
                 if param not in self._config_data:
                     continue
+                # Effective mode: per-flag override if set, else the app default.
+                effective_mode = (
+                    f.conflict_mode
+                    if not isinstance(f.conflict_mode, _MissingSentinel)
+                    else self.config_conflict_mode
+                )
                 if f.name in cli_set:
-                    if self.config_conflict_mode == "error":
-                        existing_source = global_sources.get(param, "cli")
-                        raise _ParseError(
-                            f"flag '{f.name}' set in both "
-                            f"{existing_source} and config; remove one"
-                        )
-                    continue  # cli-wins: skip config value
+                    # Conflict ONLY when config diverges from the CLI/env value.
+                    if effective_mode == "error":
+                        try:
+                            coerced = _coerce_config_value(self._config_data[param], f)
+                        except ValueError as e:
+                            raise _ParseError(
+                                f"--{f.name}: config value error: {e}"
+                            )
+                        if not _values_equal_for_conflict(cli_set[f.name], coerced, f):
+                            existing_source = global_sources.get(param, "cli")
+                            raise _ParseError(
+                                f"flag '{f.name}' set in both "
+                                f"{existing_source} and config; remove one"
+                            )
+                    continue  # cli-wins, or error mode with matching values
                 try:
                     coerced = _coerce_config_value(self._config_data[param], f)
                 except ValueError as e:
@@ -4734,15 +4867,29 @@ def _parse_command(
             param = _flag_param_name(f.name)
             if param not in config_data:
                 continue
+            # Effective mode: per-flag override if set, else the app default.
+            effective_mode = (
+                f.conflict_mode
+                if not isinstance(f.conflict_mode, _MissingSentinel)
+                else conflict_mode
+            )
             if f.name in cli_set:
-                # Flag set by CLI or env, config also has a value
-                if conflict_mode == "error":
-                    existing_source = "env" if f.name in env_names else "cli"
-                    raise _ParseError(
-                        f"flag '{f.name}' set in both "
-                        f"{existing_source} and config; remove one"
-                    )
-                continue  # cli-wins: skip config value
+                # Flag set by CLI or env, config also has a value. This is a
+                # conflict ONLY when the values diverge; identical values agree.
+                if effective_mode == "error":
+                    try:
+                        coerced = _coerce_config_value(config_data[param], f)
+                    except ValueError as e:
+                        raise _ParseError(
+                            f"--{f.name}: config value error: {e}"
+                        )
+                    if not _values_equal_for_conflict(cli_set[f.name], coerced, f):
+                        existing_source = "env" if f.name in env_names else "cli"
+                        raise _ParseError(
+                            f"flag '{f.name}' set in both "
+                            f"{existing_source} and config; remove one"
+                        )
+                continue  # cli-wins, or error mode with matching values
             try:
                 coerced = _coerce_config_value(config_data[param], f)
             except ValueError as e:
@@ -4920,6 +5067,15 @@ def _build_and_validate_command(
                     f'command "{name}": flag "{f.name}" collides with a global flag'
                 )
 
+    # Validate: a command flag colliding with a config field (validation-only
+    # coexistence) must have an agreeing default. Config fields registered after
+    # this command are checked from the App.config_field() side instead.
+    if config_fields_ref:
+        for f in all_flags:
+            cf = config_fields_ref.get(_flag_param_name(f.name))
+            if cf is not None:
+                _check_flag_configfield_default(f.name, f.default, cf)
+
     # Validate: no duplicate arg names
     seen_arg_names: set[str] = set()
     for a in all_args:
@@ -5114,10 +5270,11 @@ def flag(
     validate: Callable | None = None,
     repeatable: bool = False,
     unique: object = _MISSING,
-) -> Callable:
+    conflict_mode: object = _MISSING,
+) -> Callable[[F], F]:
     """Module-level decorator to attach a Flag to a command handler."""
 
-    def decorator(func: Callable) -> Callable:
+    def decorator(func: F) -> F:
         f = Flag(
             name=name,
             short=short,
@@ -5132,6 +5289,7 @@ def flag(
             validate=validate,
             repeatable=repeatable,
             unique=unique,
+            conflict_mode=conflict_mode,
         )
         if not hasattr(func, "_strictcli_flags"):
             func._strictcli_flags = []
@@ -5150,10 +5308,10 @@ def arg(
     variadic: bool = False,
     type: type = str,
     choices: list | None = None,
-) -> Callable:
+) -> Callable[[F], F]:
     """Module-level decorator to attach an Arg to a command handler."""
 
-    def decorator(func: Callable) -> Callable:
+    def decorator(func: F) -> F:
         a = Arg(
             name=name, help=help, required=required, default=default,
             variadic=variadic, type=type, choices=choices,
@@ -5967,6 +6125,12 @@ def _serialize_flag(f: Flag) -> dict:
         d["repeatable"] = f.repeatable
     if f.unique is True:
         d["unique"] = True
+    # Per-flag conflict mode: serialized only when explicitly set (omitted when
+    # inheriting the app default). This is additive; schema_version stays 1, so
+    # consumers get no version signal for this field -- they must treat its
+    # absence as "inherit the app-level config_conflict_mode".
+    if not isinstance(f.conflict_mode, _MissingSentinel):
+        d["conflict_mode"] = f.conflict_mode
     if f.env_separator is not None:
         d["env_separator"] = f.env_separator
     negatable = f.negatable if f.type is bool and f.compound == "scalar" else None
@@ -6183,17 +6347,20 @@ def _collect_config_field_bindings_from_group(
         _collect_config_field_bindings_from_group(sub, bindings, group_path)
 
 
-def _dump_schema(app: App) -> dict:
-    """Produce a JSON-serializable dict representing the app's command tree.
+def _dump_schema_core(app: App) -> dict:
+    """Build the full schema dict, excluding ``project_id``.
 
-    Fields whose values match the schema defaults are omitted.
-    The top-level ``defaults`` key documents what each missing field means.
+    This is the CWD-free, filesystem-free core of schema production. It reads
+    only the in-memory ``App`` (name, version, help, flags, commands, groups,
+    etc.). ``project_id`` is added later by the file-writer path, since it is
+    the only field that requires reading ``pyproject.toml`` from the CWD.
+
+    Fields whose values match the schema defaults are omitted. The top-level
+    ``defaults`` key documents what each missing field means.
     """
-    project_id = _read_project_id()
     schema: dict = {
         "schema_version": 1,
         "defaults": _build_schema_defaults(),
-        "project_id": project_id,
         "name": app.name,
         "version": app.version,
         "help": app.help,
@@ -6257,6 +6424,23 @@ def _dump_schema(app: App) -> dict:
     return schema
 
 
+def _dump_schema(app: App) -> dict:
+    """Produce the full schema dict including ``project_id`` (reads the CWD).
+
+    Delegates the bulk of the work to :func:`_dump_schema_core` and inserts
+    ``project_id`` immediately after ``defaults`` so the on-disk layout is
+    stable and byte-identical to the core dict once ``project_id`` is removed.
+    """
+    core = _dump_schema_core(app)
+    project_id = _read_project_id()
+    result: dict = {}
+    for key, value in core.items():
+        result[key] = value
+        if key == "defaults":
+            result["project_id"] = project_id
+    return result
+
+
 def _check_schema_project_id(file_path: str, new_project_id: str) -> None:
     """Verify that an existing schema file belongs to the same project.
 

{strictcli-0.25.0 → strictcli-0.27.0}/tests/test_config.py

@@ -1682,10 +1682,16 @@ def test_conflict_mode_implied_excluded(tmp_path, monkeypatch):
 
 
 def test_conflict_mode_fires_before_mutex(tmp_path, monkeypatch):
-    """Conflict fires before mutex when both would error."""
+    """Conflict fires before mutex when both would error.
+
+    Under divergence-awareness, a conflict requires the config value to differ
+    from the CLI value. Config sets format_json=false while the CLI passes
+    --format-json (true): the values diverge, so the conflict fires. The CLI
+    also passes --format-yaml so mutex would also fire -- conflict wins.
+    """
     config_dir = tmp_path / "testapp"
     config_dir.mkdir(parents=True)
-    (config_dir / "config.json").write_text('{"format_json": true}')
+    (config_dir / "config.json").write_text('{"format_json": false}')
     monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
     app = strictcli.App(
         name="testapp", version="1.0.0", help="test",
@@ -1701,7 +1707,111 @@ def test_conflict_mode_fires_before_mutex(tmp_path, monkeypatch):
     def run(format_json, format_yaml):
         pass
 
-    r = app.test(["run", "--format-json"])
+    r = app.test(["run", "--format-json", "--format-yaml"])
     assert r.exit_code == 1
     # Should mention conflict (set in both), not mutex
     assert "set in both" in r.stderr
+
+
+# --- Phase 2.2: divergence-aware conflict mode + per-flag override ---
+
+def _conflict_app(conflict_mode="error", flag_conflict_mode=strictcli._MISSING,
+                  flag_type=str, default="default-val", unique=strictcli._MISSING,
+                  repeatable=False):
+    """Build an app with a single 'run' command flag 'target'."""
+    app = strictcli.App(
+        name="testapp", version="1.0.0", help="test",
+        config=True, config_conflict_mode=conflict_mode,
+    )
+
+    @app.command("run", help="run")
+    @strictcli.flag("target", type=flag_type, help="target", default=default,
+                    repeatable=repeatable, unique=unique,
+                    conflict_mode=flag_conflict_mode)
+    def run(target):
+        print(f"target={target}")
+
+    return app
+
+
+def _write_cfg(tmp_path, monkeypatch, payload):
+    config_dir = tmp_path / "testapp"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    (config_dir / "config.json").write_text(json.dumps(payload))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+
+
+def test_conflict_error_identical_scalar_passes(tmp_path, monkeypatch):
+    """Error mode: identical config+CLI value is NOT a conflict."""
+    _write_cfg(tmp_path, monkeypatch, {"target": "same"})
+    app = _conflict_app(conflict_mode="error")
+    r = app.test(["run", "--target", "same"])
+    assert r.exit_code == 0, r.stderr
+    assert "target=same" in r.stdout
+
+
+def test_conflict_error_divergent_scalar_errors(tmp_path, monkeypatch):
+    """Error mode: divergent config+CLI value IS a conflict."""
+    _write_cfg(tmp_path, monkeypatch, {"target": "from-config"})
+    app = _conflict_app(conflict_mode="error")
+    r = app.test(["run", "--target", "from-cli"])
+    assert r.exit_code == 1
+    assert "set in both cli and config; remove one" in r.stderr
+
+
+def test_per_flag_error_beats_app_cli_wins(tmp_path, monkeypatch):
+    """Per-flag conflict_mode='error' overrides app default cli-wins."""
+    _write_cfg(tmp_path, monkeypatch, {"target": "from-config"})
+    app = _conflict_app(conflict_mode="cli-wins", flag_conflict_mode="error")
+    r = app.test(["run", "--target", "from-cli"])
+    assert r.exit_code == 1
+    assert "set in both cli and config; remove one" in r.stderr
+
+
+def test_per_flag_cli_wins_beats_app_error(tmp_path, monkeypatch):
+    """Per-flag conflict_mode='cli-wins' overrides app default error."""
+    _write_cfg(tmp_path, monkeypatch, {"target": "from-config"})
+    app = _conflict_app(conflict_mode="error", flag_conflict_mode="cli-wins")
+    r = app.test(["run", "--target", "from-cli"])
+    assert r.exit_code == 0, r.stderr
+    assert "target=from-cli" in r.stdout
+
+
+def test_conflict_repeatable_order_sensitive(tmp_path, monkeypatch):
+    """Plain repeatable: same elements different order diverge -> error."""
+    _write_cfg(tmp_path, monkeypatch, {"target": ["a", "b"]})
+    app = _conflict_app(conflict_mode="error", default=None,
+                        repeatable=True, unique=False)
+    # Same order -> equal -> pass
+    r = app.test(["run", "--target", "a", "--target", "b"])
+    assert r.exit_code == 0, r.stderr
+    # Different order -> divergent -> error
+    app2 = _conflict_app(conflict_mode="error", default=None,
+                         repeatable=True, unique=False)
+    r2 = app2.test(["run", "--target", "b", "--target", "a"])
+    assert r2.exit_code == 1
+    assert "set in both" in r2.stderr
+
+
+def test_conflict_unique_order_insensitive(tmp_path, monkeypatch):
+    """Unique: same elements different order are equal (multiset) -> pass."""
+    _write_cfg(tmp_path, monkeypatch, {"target": ["a", "b"]})
+    app = _conflict_app(conflict_mode="error", default=None,
+                        repeatable=True, unique=True)
+    r = app.test(["run", "--target", "b", "--target", "a"])
+    assert r.exit_code == 0, r.stderr
+
+
+def test_conflict_malformed_config_value_errors_cleanly(tmp_path, monkeypatch):
+    """Error mode co-presence: a malformed config value errors cleanly."""
+    _write_cfg(tmp_path, monkeypatch, {"target": "not-an-int"})
+    app = _conflict_app(conflict_mode="error", flag_type=int, default=0)
+    r = app.test(["run", "--target", "5"])
+    assert r.exit_code == 1
+    assert "config value error" in r.stderr
+
+
+def test_flag_conflict_mode_invalid_value_raises():
+    """Registration: invalid per-flag conflict_mode is a ValueError."""
+    with pytest.raises(ValueError, match="conflict_mode"):
+        strictcli.Flag(name="x", type=str, help="h", conflict_mode="bogus")

{strictcli-0.25.0 → strictcli-0.27.0}/tests/test_config_fields.py

@@ -993,3 +993,107 @@ class TestSchemaWithConfigFields:
 
         bound = schema["config_fields"]["db.url"]["bound_commands"]
         assert "server start" in bound
+
+
+# ---- Phase 2.3: ConfigField / Flag coexistence ----
+
+
+class TestConfigFieldFlagCoexistence:
+    """A config field colliding with a flag's param name is validation-only:
+    it annotates the flag and renders once."""
+
+    def _app_field_after_flag(self, tmp_path, config_data=None,
+                              flag_default=None, field_default=strictcli._MISSING):
+        app = _build_config_app(tmp_path, config_data=config_data or {})
+
+        @app.command(name="run", help="run")
+        @strictcli.flag("target", type=str, help="deploy target", default=flag_default)
+        def run(target):
+            pass
+
+        app.config_field("target", type=str, help="the deploy target",
+                         default=field_default)
+        return app
+
+    def test_show_plain_renders_key_once_with_annotation(self, tmp_path):
+        app = self._app_field_after_flag(tmp_path, config_data={"target": "prod"})
+        result = app.test(["config", "show", "--plain"])
+        assert result.exit_code == 0
+        # The flag line carries the config field help as a trailing annotation.
+        target_lines = [ln for ln in result.stdout.splitlines() if ln.startswith("target ")]
+        assert len(target_lines) == 1, result.stdout
+        assert "-- the deploy target" in target_lines[0]
+        # Not duplicated under a "Config fields:" section.
+        assert "Config fields:" not in result.stdout
+
+    def test_show_json_renders_key_once(self, tmp_path):
+        app = self._app_field_after_flag(tmp_path, config_data={"target": "prod"})
+        result = app.test(["config", "show", "--json"])
+        assert result.exit_code == 0
+        data = json.loads(result.stdout)
+        # Single entry: the flag entry (value + source), not the config-field entry.
+        assert data["target"]["value"] == "prod"
+        assert data["target"]["source"] == "config"
+        # The config-field-only keys must be absent (rendered as flag, once).
+        assert "type" not in data["target"]
+        assert "required" not in data["target"]
+
+    def test_init_toml_renders_key_once_with_annotation(self, tmp_path):
+        init_path = str(tmp_path / "cfg.toml")
+        app = strictcli.App(name="testapp", version="1.0.0", help="t",
+                            config=True, config_path=init_path, config_format="toml")
+
+        @app.command(name="run", help="run")
+        @strictcli.flag("target", type=str, help="deploy target", default="prod")
+        def run(target):
+            pass
+
+        app.config_field("target", type=str, help="the deploy target", default="prod")
+        result = app.test(["config", "init"])
+        assert result.exit_code == 0
+        content = open(init_path).read()
+        assert content.count("target =") == 1, content
+        assert "-- the deploy target" in content
+
+    def test_init_json_renders_key_once(self, tmp_path):
+        init_path = str(tmp_path / "cfg.json")
+        app = strictcli.App(name="testapp", version="1.0.0", help="t",
+                            config=True, config_path=init_path)
+
+        @app.command(name="run", help="run")
+        @strictcli.flag("target", type=str, help="deploy target", default="prod")
+        def run(target):
+            pass
+
+        app.config_field("target", type=str, help="the deploy target", default="prod")
+        result = app.test(["config", "init"])
+        assert result.exit_code == 0
+        data = json.loads(open(init_path).read())
+        assert list(data.keys()).count("target") == 1
+        assert data["target"] == "prod"
+
+    def test_unequal_defaults_field_after_flag_raises(self, tmp_path):
+        with pytest.raises(ValueError, match="defaults disagree"):
+            self._app_field_after_flag(tmp_path, flag_default="prod",
+                                       field_default="staging")
+
+    def test_unequal_defaults_flag_after_field_raises(self, tmp_path):
+        app = _build_config_app(tmp_path)
+        app.config_field("target", type=str, help="the deploy target",
+                         default="staging")
+        with pytest.raises(ValueError, match="defaults disagree"):
+            @app.command(name="run", help="run")
+            @strictcli.flag("target", type=str, help="deploy target", default="prod")
+            def run(target):
+                pass
+
+    def test_equal_defaults_ok(self, tmp_path):
+        # Should not raise.
+        self._app_field_after_flag(tmp_path, flag_default="prod",
+                                   field_default="prod")
+
+    def test_one_absent_default_ok(self, tmp_path):
+        # Flag has default, config field has none -> OK (flag wins).
+        self._app_field_after_flag(tmp_path, flag_default="prod")
+        # Field has default, flag has none -> OK.
+        self._app_field_after_flag(tmp_path, flag_default=None, field_default="prod")

{strictcli-0.25.0 → strictcli-0.27.0}/tests/test_dump_schema.py

@@ -1103,3 +1103,58 @@ class TestSchemaProjectIdMismatch:
 
         result = app.test(["--dump-schema"])
         assert result.exit_code == 0
+
+
+class TestDumpSchemaDict:
+    """App.dump_schema_dict() returns the CWD-free schema core dict."""
+
+    def test_returns_version_without_project_id(self, tmp_path, monkeypatch):
+        # Run from a directory with NO pyproject.toml to prove no CWD access.
+        empty = tmp_path / "empty"
+        empty.mkdir()
+        monkeypatch.chdir(empty)
+        app = _make_app()
+
+        @app.command("greet", help="Say hello")
+        def greet():
+            pass
+
+        d = app.dump_schema_dict()
+        assert d["schema_version"] == 1
+        assert d["version"] == "1.0.0"
+        assert d["name"] == "testapp"
+        assert "project_id" not in d
+        assert "commands" in d
+
+    def test_no_pyproject_does_not_raise(self, tmp_path, monkeypatch):
+        empty = tmp_path / "empty2"
+        empty.mkdir()
+        monkeypatch.chdir(empty)
+        assert not (empty / "pyproject.toml").exists()
+        app = _make_app()
+        # Must not raise even though _read_project_id() would.
+        d = app.dump_schema_dict()
+        assert isinstance(d, dict)
+
+    def test_equals_file_writer_minus_project_id(self, tmp_path, monkeypatch):
+        # tmp_path has a pyproject.toml (autouse fixture), so the file writer works.
+        monkeypatch.chdir(tmp_path)
+        app = _make_app(env_prefix="TESTAPP")
+
+        @app.command("greet", help="Say hello")
+        @strictcli.flag("loud", type=bool, help="be loud", default=False)
+        def greet(loud):
+            pass
+
+        result = app.test(["--dump-schema"])
+        assert result.exit_code == 0
+        written = json.loads((tmp_path / ".strictcli" / "schema.json").read_text())
+        method = app.dump_schema_dict()
+
+        # File-writer output minus project_id must equal the method output.
+        written_minus = {k: v for k, v in written.items() if k != "project_id"}
+        assert written_minus == method
+
+        # Byte-identical by construction: serializing the method output equals
+        # serializing the file output with the project_id key removed.
+        assert json.dumps(method, indent=2) == json.dumps(written_minus, indent=2)

{strictcli-0.25.0 → strictcli-0.27.0}/uv.lock

@@ -232,7 +232,7 @@ wheels = [
 
 [[package]]
 name = "strictcli"
-version = "0.25.0"
+version = "0.27.0"
 source = { editable = "." }
 
 [package.dev-dependencies]