django-spec-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-11-04
+
+### Added
+- **A spec the kernel refuses as declared is reported, and never run.**
+  Every spec a `SpecCommand` serves is now put to the kernel's `check_seeds`
+  under the command's `pool_seeds`, which other transports already ask where
+  they register a spec. `manage.py check` reports each spec it refuses as
+  `django_spec_cli.W004`, a warning, naming the command, the spec and the
+  kernel's reason. A run of such a spec raises `ImproperlyConfigured` with the
+  same sentence, exit code 1 with a traceback, before `--as-user` is looked
+  up. The command's other specs, its `--help` and its `--explain` are
+  unaffected.
+
+  Three of the kernel's refusals stop runs that succeeded before, because
+  each fails only some calls. The first is a read declared without
+  `required=True`, which is `Parameter`'s default, over a keyword the
+  service, the selector or a callable such as a `kwargs` provider takes by
+  name with no default: `Parameter("title", "string")` over
+  `def rename(*, title)`, or `def needs_project(*, project: int)` as the
+  provider. A run sending the read worked, and one leaving it out was refused
+  as missing or crashed with the provider's `TypeError`; now every run is
+  refused, so declare such a read `required=True` or give the keyword a
+  default. The second is an array read declaring no `items` over a keyword
+  annotated with its element, such as `pks: list[int]`, which was handed the
+  command line's strings. The third is a `progress_reporter` requiring a
+  keyword nothing fills, which a run whose service never reports never
+  called. The others refuse a declaration on which every run that reached
+  the callable already failed, with its `TypeError` or the kernel's own
+  `ImproperlyConfigured`, which now names the spec and the command.
+
+### Changed
+- **The kernel floor is `django-service-specs>=0.25.0`, the first kernel
+  release that keeps a read a provider requires itself demanded of the
+  caller.** From 0.3.1 `--help` reads its options, and which are marked
+  `(required)`, from the kernel's `spec_caller_input_schema`, so it repeats
+  what the installed kernel answers. On kernel 0.24.x a read declared
+  required that a `kwargs` provider takes by name with no default, such as
+  `def needs_project(*, project: int)`, was offered without `(required)`, and
+  a run leaving it out crashed in the provider with a `TypeError`. From 0.25.0
+  it is marked `(required)`, and that run is refused as invalid arguments,
+  exit code 3. The lowest-declared-versions job runs the suite on 0.25.0.
+
+## [0.3.1] — 2026-11-04
+
+### Fixed
+- **`--help` offers and requires what dispatch asks a caller for.** A
+  subcommand's options, and which of them are marked `(required)`, are now
+  read from the kernel's `spec_caller_input_schema` under the command's
+  `pool_seeds`, rather than from `server_owned_keys` read without them. On any
+  kernel from 0.15.0, two parameters were shown wrongly. A read declared
+  required beside a provider that may fill it, such as a `kwargs` provider
+  whose return names no keys, was marked `(required)`, though a run leaving
+  it out was dispatched. A `reflected` read named like a seed the command's
+  `pool_seeds` registers was offered as an option and marked `(required)`,
+  and passing it was refused as an unknown argument, exit code 3. It is no
+  longer an option. No public name changes.
+
 ## [0.3.0] — 2026-11-04
 
 ### Changed
@@ -67,7 +124,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `django-service-specs>=0.10.0`, the first kernel release with every name the
   command reads at its root.
 
-[Unreleased]: https://github.com/Artui/django-spec-cli/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/Artui/django-spec-cli/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Artui/django-spec-cli/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/Artui/django-spec-cli/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Artui/django-spec-cli/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/Artui/django-spec-cli/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Artui/django-spec-cli/compare/v0.1.0...v0.2.0

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/CLAUDE.md

@@ -8,8 +8,9 @@ The management-command transport for `django-service-specs`. A project
 subclasses `SpecCommand`, names a `SpecRegistry`, and `manage.py <command>`
 serves one subcommand per spec: an option for each parameter, a principal named
 by `--as-user`, the result as a table or JSON Lines, and an exit code for every
-refusal. Two system checks, `django_spec_cli.W001` and `W003`, report a served
-spec that authorizes nothing and a command that cannot be loaded.
+refusal. Three system checks, `django_spec_cli.W001`, `W003` and `W004`,
+report a served spec that authorizes nothing, a command that cannot be loaded,
+and a spec the kernel's `check_seeds` refuses, whose run is refused too.
 
 It is the kernel's `commands/` subpackage, moved out with its history so that
 the kernel can carry no transport, and the kernel carries no copy of it from
@@ -82,11 +83,12 @@ so do the check ids and the setting key, `SPEC_CLI_OUTPUT`.
 Each of these reads as an oversight and is not.
 
 - **The checks are registered by this package's own `AppConfig`.** A project
-  lists `"django_spec_cli"` in `INSTALLED_APPS` to get `W001` and `W003`. The
-  kernel keeps the registry fact the check reads, `unguarded_specs`, because
-  another transport can ask the same question of a registry. The kernel's own
-  app stays importable and registers nothing, so listing only it gets no check
-  (`tests/test_checks.py`, `test_the_kernel_s_app_registers_no_check_of_its_own`).
+  lists `"django_spec_cli"` in `INSTALLED_APPS` to get `W001`, `W003` and
+  `W004`. The kernel keeps the registry fact the check reads,
+  `unguarded_specs`, because another transport can ask the same question of a
+  registry. The kernel's own app stays importable and registers nothing, so
+  listing only it gets no check (`tests/test_checks.py`,
+  `test_the_kernel_s_app_registers_no_check_of_its_own`).
 - **The test settings list no kernel app.** The package needs nothing of the
   kernel switched on, and the suite shows it.
 
@@ -137,7 +139,7 @@ configured and enforced. isort order is stdlib, third party, first party.
 | --- | --- | --- |
 | Python | 3.10 | 3.10 through 3.14 |
 | Django | 4.2 | 4.2, 5.0, 5.1, 5.2, 6.0, 6.1 |
-| django-service-specs | 0.24.0 | the newest release, and the floor in the `floor` job |
+| django-service-specs | 0.25.0 | the newest release, and the floor in the `floor` job |
 
 The Python and Django floors are the kernel's, and cannot sit below them.
 

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-spec-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Run a django-service-specs registry from manage.py: one subcommand per spec, options generated from its parameters, exit codes for every refusal.
 Project-URL: Homepage, https://github.com/Artui/django-spec-cli
 Project-URL: Repository, https://github.com/Artui/django-spec-cli
@@ -30,7 +30,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: django-service-specs>=0.24.0
+Requires-Dist: django-service-specs>=0.25.0
 Requires-Dist: django>=4.2
 Description-Content-Type: text/markdown
 
@@ -61,7 +61,7 @@ the import path, the system check ids and the setting key are this package's.
 pip install django-spec-cli
 ```
 
-Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.24.0 or
+Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.25.0 or
 later, which it installs.
 
 ## Quickstart
@@ -92,9 +92,11 @@ authorize nothing.
 ## The system check
 
 List `"django_spec_cli"` in `INSTALLED_APPS` and `manage.py check` reports
-every open spec a `SpecCommand` serves as `django_spec_cli.W001`, and a command
-that could not be loaded as `django_spec_cli.W003`. The command itself needs no
-app listed.
+every open spec a `SpecCommand` serves as `django_spec_cli.W001`, a command
+that could not be loaded as `django_spec_cli.W003`, and a spec the kernel's
+`check_seeds` refuses under the command's `pool_seeds` as `django_spec_cli.W004`.
+A run of a spec W004 reports is refused whether or not the app is listed. The
+command itself needs no app listed.
 
 The kernel keeps no check of its own: its app registers nothing, so a project
 listing only `"django_service_specs"` gets no check for a command. List

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/README.md

@@ -25,7 +25,7 @@ the import path, the system check ids and the setting key are this package's.
 pip install django-spec-cli
 ```
 
-Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.24.0 or
+Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.25.0 or
 later, which it installs.
 
 ## Quickstart
@@ -56,9 +56,11 @@ authorize nothing.
 ## The system check
 
 List `"django_spec_cli"` in `INSTALLED_APPS` and `manage.py check` reports
-every open spec a `SpecCommand` serves as `django_spec_cli.W001`, and a command
-that could not be loaded as `django_spec_cli.W003`. The command itself needs no
-app listed.
+every open spec a `SpecCommand` serves as `django_spec_cli.W001`, a command
+that could not be loaded as `django_spec_cli.W003`, and a spec the kernel's
+`check_seeds` refuses under the command's `pool_seeds` as `django_spec_cli.W004`.
+A run of a spec W004 reports is refused whether or not the app is listed. The
+command itself needs no app listed.
 
 The kernel keeps no check of its own: its app registers nothing, so a project
 listing only `"django_service_specs"` gets no check for a command. List

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/django_spec_cli/apps.py

@@ -1,4 +1,4 @@
-"""The app a project lists to have its open specs reported by ``manage.py check``."""
+"""The app a project lists to have its open and unrunnable specs reported by ``manage.py check``."""
 
 from __future__ import annotations
 
@@ -9,7 +9,7 @@ from django_spec_cli.checks import check_unguarded_specs
 
 
 class DjangoSpecCliConfig(AppConfig):
-    """Registers the unguarded-spec system check, and does nothing else.
+    """Registers the system check over every ``SpecCommand``'s specs, and does nothing else.
 
     Optional: the package works unlisted, and a project that does not list it
     gets no check and no sign that it is missing. It owns no models, so it

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/django_spec_cli/checks.py

@@ -1,4 +1,4 @@
-"""The system check reporting every spec a ``SpecCommand`` serves that authorizes nothing."""
+"""The system check reporting every spec a ``SpecCommand`` serves that authorizes nothing or cannot run."""
 
 from __future__ import annotations
 
@@ -7,22 +7,28 @@ from typing import Any
 
 from django.apps import AppConfig
 from django.core.checks import CheckMessage, Warning
+from django.core.exceptions import ImproperlyConfigured
 from django.core.management import get_commands, load_command_class
-from django_service_specs import UnguardedSpec, unguarded_specs
+from django_service_specs import UnguardedSpec, check_seeds, unguarded_specs
 
 from django_spec_cli.report.unguarded_message import unguarded_message
+from django_spec_cli.report.utils import refused_message
 from django_spec_cli.spec_command import SpecCommand
 
 _HINT = (
     "Declare a PermissionCheck that refuses someone in the spec's permissions, or add "
     "'django_spec_cli.W001' to SILENCED_SYSTEM_CHECKS if the spec is meant to be open."
 )
+_REFUSED_HINT = (
+    "Change the declaration as the message says. Until then a run of the spec is refused, "
+    "whether or not django_spec_cli.W004 is silenced."
+)
 
 
 def check_unguarded_specs(
     app_configs: Sequence[AppConfig] | None, **kwargs: Any
 ) -> list[CheckMessage]:
-    """Warn once per spec that authorizes nothing, in every ``SpecCommand`` of the project.
+    """Warn once per spec that authorizes nothing or cannot run, in every ``SpecCommand`` of the project.
 
     Registered by the app's ``ready()``, so a project gets it by listing
     ``django_spec_cli`` in ``INSTALLED_APPS`` and not otherwise. There is
@@ -40,6 +46,15 @@ def check_unguarded_specs(
       spec is a decision or an accident the check cannot tell apart, and an
       ``Error`` would stop ``migrate`` on a project working as intended.
       ``SILENCED_SYSTEM_CHECKS`` silences it by id, so for every spec at once.
+    - ``django_spec_cli.W004``, one per spec that
+      [`check_seeds`][django_service_specs.dispatch.check_seeds.check_seeds]
+      refuses under the command's ``pool_seeds``, such as an optional read
+      that a ``kwargs`` provider takes by name with no default, with the
+      kernel's reason and the command class as ``obj``. A run of that spec
+      is refused with the same sentence, so this is the same refusal told
+      before anyone runs it. A ``Warning`` for the reason W003 is one: an
+      ``Error`` would stop ``migrate`` over a spec nobody runs, while the
+      command's other specs work.
     - ``django_spec_cli.W003``, one per command that could not be loaded or
       whose parser could not be built, naming it and the error. Without this
       app nothing loads that command until somebody runs it, so failing the
@@ -80,9 +95,33 @@ def check_unguarded_specs(
             )
             for spec in specs
         )
+        messages.extend(
+            Warning(
+                refused_message(spec_name, name, error),
+                hint=_REFUSED_HINT,
+                obj=type(command),
+                id="django_spec_cli.W004",
+            )
+            for spec_name, error in _refused(command)
+        )
     return messages
 
 
+def _refused(command: SpecCommand) -> Iterator[tuple[str, ImproperlyConfigured]]:
+    """Each spec of ``command`` that ``check_seeds`` refuses, with its refusal, in registry order.
+
+    The same question ``SpecCommand.handle`` asks before a run, under the
+    same ``pool_seeds``, so a spec reported here is one a run refuses.
+    Outside the walk's ``try``: a refusal names one spec, and the command
+    loaded, so its other specs are still reported and it is no W003.
+    """
+    for entry in command.registry:
+        try:
+            check_seeds(entry.spec, pool_seeds=command.pool_seeds)
+        except ImproperlyConfigured as error:
+            yield entry.name, error
+
+
 def _spec_commands(
     app_configs: Sequence[AppConfig] | None,
 ) -> Iterator[tuple[str, str, tuple[SpecCommand, tuple[UnguardedSpec, ...]] | Exception]]:

django_spec_cli-0.4.0/django_spec_cli/report/utils.py

@@ -0,0 +1,18 @@
+"""Helpers the system check and ``SpecCommand`` share: the sentence for a spec the kernel refuses."""
+
+from __future__ import annotations
+
+from django.core.exceptions import ImproperlyConfigured
+
+
+def refused_message(spec_name: str, command_label: str, error: ImproperlyConfigured) -> str:
+    """The one-line report of ``spec_name``, which ``check_seeds`` refused with ``error``.
+
+    ``command_label`` is the name an operator types after ``manage.py``. The
+    system check and a run of the spec both print this, so the warning a
+    project sees before a run reads as the refusal the run ends with.
+    """
+    return (
+        f"{spec_name!r} in manage.py {command_label} cannot run as declared, and a run of it "
+        f"is refused: {error}"
+    )

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/django_spec_cli/spec_command.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import inspect
 from collections.abc import Mapping
+from dataclasses import replace
 from typing import Any, TextIO, cast
 
 from django.core.exceptions import ImproperlyConfigured
@@ -25,14 +26,14 @@ from django_service_specs import (
     ServiceSpec,
     ServiceValidationError,
     SpecRegistry,
+    check_seeds,
     coerce_flat,
     dispatch,
     kernel_spec,
     present,
     refusal_messages,
-    relax_partial,
     resolve_principal,
-    server_owned_keys,
+    spec_caller_input_schema,
     unguarded_specs,
 )
 
@@ -44,6 +45,7 @@ from django_spec_cli.exit_code_for import exit_code_for
 from django_spec_cli.render.render_result import render_result
 from django_spec_cli.render.wants_table import wants_table
 from django_spec_cli.report.unguarded_message import unguarded_message
+from django_spec_cli.report.utils import refused_message
 from django_spec_cli.types.exit_code import ExitCode
 
 _OWN_OPTIONS = frozenset({"--as-user", "--json", "--table"})
@@ -72,8 +74,10 @@ class SpecCommand(BaseCommand):
     - **One subcommand per registry entry**, named after the entry with each
       ``_`` shown as ``-``. Its options are the spec's parameters, as
       [`add_spec_arguments`][django_spec_cli.argv.add_spec_arguments.add_spec_arguments]
-      spells them, less any key the server fills
-      ([`server_owned_keys`][django_service_specs.specs.server_owned_keys.server_owned_keys]).
+      spells them, as the input schema a transport advertises asks for them
+      ([`spec_caller_input_schema`][django_service_specs.schema.spec_caller_input_schema.spec_caller_input_schema]
+      under ``pool_seeds``): less any key the server fills, and required only
+      where dispatch refuses leaving it out.
       No option is matched by a prefix: an abbreviation is refused rather
       than read as whichever option it begins.
     - **``--as-user`` is required.** Its value goes through
@@ -87,6 +91,13 @@ class SpecCommand(BaseCommand):
       terminal ([`wants_table`][django_spec_cli.render.wants_table.wants_table]).
     - A refusal ends the run with a ``CommandError`` carrying its message and
       an [`ExitCode`][django_spec_cli.types.exit_code.ExitCode].
+    - **A spec the kernel refuses as declared is never run.**
+      [`check_seeds`][django_service_specs.dispatch.check_seeds.check_seeds],
+      under ``pool_seeds``, is asked of the spec named before anything else,
+      and its refusal is raised as ``ImproperlyConfigured``, as a command
+      naming no registry is: a traceback and ``ExitCode.ERROR``, whatever
+      the options sent. The command's other specs still run, and the system
+      check reports the same spec as ``django_spec_cli.W004``.
     - ``--explain`` runs no spec: it lists the ones that authorize nothing,
       as the system check does.
 
@@ -162,7 +173,7 @@ class SpecCommand(BaseCommand):
                 )
             self._entries[name] = entry
             spec = kernel_spec(entry.spec)
-            parameters = _sendable(spec)
+            parameters = _sendable(spec, self.pool_seeds)
             summary = _summary(spec, entry.name)
             subparser = subparsers.add_parser(
                 name,
@@ -232,6 +243,18 @@ class SpecCommand(BaseCommand):
                 else "name a spec to run, or pass --explain. --help lists the specs."
             )
         entry = self._entries[name]
+        # Asked of the one spec named, not of every entry where the parser is
+        # built: a raise there would stop every spec the command serves, and
+        # ``--help`` and ``--explain`` with them. Before the lookup, so a
+        # project's ``resolve_as_user`` never runs for a spec that cannot.
+        # Not a ``CommandError``: the declaration is wrong, not the call, and
+        # ``ExitCode.ERROR`` is published as the failure with a traceback.
+        try:
+            check_seeds(entry.spec, pool_seeds=self.pool_seeds)
+        except ImproperlyConfigured as error:
+            raise ImproperlyConfigured(
+                refused_message(entry.name, self._command_label, error)
+            ) from error
         spec = kernel_spec(entry.spec)
         parameters = spec.parameters()
         raw = parsed_arguments(argparse.Namespace(**options), parameters)
@@ -281,18 +304,33 @@ class SpecCommand(BaseCommand):
             self.stdout.write(unguarded_message(unguarded, label))
 
 
-def _sendable(spec: ServiceSpec | SelectorSpec) -> Parameters:
-    """What a caller may send, as the shape check reads it: required only where dispatch demands it.
-
-    Relaxed for ``partial`` by the shape check's own reading, so ``--help``
-    marks ``(required)`` exactly where an omission is refused
-    (test_a_partial_spec_requires_only_what_names_its_row), and without the
-    keys the server fills, whose value a caller's would never replace
-    (test_a_key_the_server_fills_is_no_option).
+def _sendable(spec: ServiceSpec | SelectorSpec, pool_seeds: PoolSeeds) -> Parameters:
+    """What a caller may send, as the kernel's caller schema reads it: required only where dispatch demands it.
+
+    The parameters ``spec_caller_input_schema`` offers under the command's
+    ``pool_seeds``, so no key the server fills is an option: one a provider
+    is annotated to fill (test_a_key_the_server_fills_is_no_option), and a
+    reflected read a registered seed fills
+    (test_a_reflected_read_a_seed_fills_is_an_option_only_without_the_seed).
+    Each is relaxed where the schema does not require it, so ``--help``
+    marks ``(required)`` exactly where an omission is refused: on a
+    ``partial`` spec (test_a_partial_spec_requires_only_what_names_its_row)
+    and beside a provider that may fill it
+    (test_a_read_a_provider_may_fill_is_offered_and_not_required). A read
+    stays declared required where the provider takes it by name with no
+    default, since that provider cannot be the one to fill it
+    (test_a_read_a_provider_requires_itself_is_required). Only
+    relaxed, never made required, so a declared default still answers.
     """
-    owned = server_owned_keys(spec)
-    relaxed = relax_partial(spec, spec.parameters())
-    return Parameters.of(*(param for param in relaxed if param.name not in owned))
+    schema = spec_caller_input_schema(spec, pool_seeds=pool_seeds)
+    required = frozenset(schema.get("required", ()))
+    return Parameters.of(
+        *(
+            param if param.name in required else replace(param, required=False)
+            for param in spec.parameters()
+            if param.name in schema["properties"]
+        )
+    )
 
 
 def _summary(spec: ServiceSpec | SelectorSpec, name: str) -> str:

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/django_spec_cli/version.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__: str = "0.3.0"
+__version__: str = "0.4.0"
 
 __all__ = ["__version__"]

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/docs/index.md

@@ -27,7 +27,7 @@ pip install django-spec-cli
 ```
 
 It installs [`django-service-specs`](https://artui.github.io/django-service-specs/), the kernel whose specs it serves,
-from 0.24.0, on Python 3.10 and Django 4.2 or later. The command line was the
+from 0.25.0, on Python 3.10 and Django 4.2 or later. The command line was the
 kernel's `commands/` subpackage, and moved here so the kernel carries no
 transport.
 
@@ -86,14 +86,22 @@ equals sign: `--tag=-x`.
 of its service's or selector's docstring and whether it reads or writes, or
 its registered name when the function says nothing. `manage.py notes
 rename-note --help` lists its options, with `(required)` where leaving one
-out is refused. On a `partial` spec, that is only what names the row: the
-Validator's fields may be left out, as dispatch allows.
+out is refused. Both are read from the input schema a transport advertises,
+[`spec_caller_input_schema`][django_service_specs.schema.spec_caller_input_schema.spec_caller_input_schema],
+under the command's `pool_seeds`, so the command asks for what dispatch asks
+for. On a `partial` spec, `(required)` is only what names the row: the
+Validator's fields may be left out, as dispatch allows. A parameter a provider
+may fill, such as a read beside a `kwargs` provider whose return names no keys,
+is an option and is not required, unless the provider takes that read by name
+with no default: only the caller can fill it then, so a read declared required
+stays `(required)`.
 
 Some parameters have no option:
 
-- **A key the server fills**, one a `kwargs` provider is annotated to answer
-  ([`server_owned_keys`][django_service_specs.specs.server_owned_keys.server_owned_keys]),
-  since a value sent for it would be dropped.
+- **A key the server fills**: one a `kwargs` provider is annotated to answer,
+  since a value sent for it would be dropped, and a `reflected` read named like
+  a seed `pool_seeds` registers, since the seed fills it and dispatch refuses an
+  argument of its name.
 - **A parameter with no flat spelling**: an object, an array of objects or of
   arrays, and a file. The subcommand's help names them. A spec that requires
   one, such as any `many` spec, cannot be run from the command line.
@@ -245,8 +253,20 @@ sentence from `manage.py check`, as `django_spec_cli.W001`, once per
 open spec of every `SpecCommand` in the project, and a command that could not
 be loaded to be checked as `django_spec_cli.W003`. There is no
 `W002`: a spec with an empty `permissions` is refused when it is built, so
-none reaches a registry. Both are warnings, and `SILENCED_SYSTEM_CHECKS`
-silences one by id.
+none reaches a registry.
+
+`django_spec_cli.W004` reports, once per spec, a declaration the kernel's
+[`check_seeds`][django_service_specs.dispatch.check_seeds.check_seeds]
+refuses under the command's `pool_seeds`: a keyword the callable requires
+that nothing fills, or a read declared optional that a `kwargs` provider
+takes by name with no default, among others. A run of that spec is refused
+with the same sentence, raised as `ImproperlyConfigured` (exit code 1,
+with a traceback) before `--as-user` is looked up, even when the options sent
+would let it run. The command's other specs are unaffected.
+
+All three are warnings, so a spec nobody runs never stops `migrate`, and
+`SILENCED_SYSTEM_CHECKS` silences one by id. Silencing `W004` hides the report
+and does not let the spec run.
 
 The kernel keeps no check of its own: its app registers nothing, so a project
 listing only `"django_service_specs"` gets no check for a command. List

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/docs/reference.md

@@ -28,6 +28,11 @@ Registered by `DjangoSpecCliConfig`, so a project gets them by listing
   open spec, worded by
   [`unguarded_message`][django_spec_cli.report.unguarded_message.unguarded_message].
 - **`django_spec_cli.W003`**: a command could not be loaded to be checked.
+- **`django_spec_cli.W004`**: the kernel's
+  [`check_seeds`][django_service_specs.dispatch.check_seeds.check_seeds]
+  refuses a spec a `SpecCommand` serves, under the command's `pool_seeds`.
+  Once per refused spec. A run of it is refused with the same sentence,
+  whether or not the warning is silenced.
 
 ## The command
 

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/pyproject.toml

@@ -40,14 +40,16 @@ dependencies = [
     # kernel's specs, so this package cannot support a Django the kernel does
     # not.
     "django>=4.2",
-    # The first kernel release with ``PermissionCheckDenied`` in ``REFUSALS``.
-    # ``tests/test_exit_code_for.py`` holds the exit codes against that list
-    # and decides the new refusal's code by name, so the suite, and the floor
-    # job running it, cannot import below 0.24.0. The code itself is
-    # ``NotPermitted``'s on every kernel. Below 0.11.0 the kernel also still
-    # shipped its own copy of the command and registered its own ``W001`` and
-    # ``W003``.
-    "django-service-specs>=0.24.0",
+    # The first kernel release whose ``spec_caller_input_schema`` keeps a read
+    # a provider requires itself, by name and with no default, demanded of the
+    # caller. ``--help`` repeats that schema, so on 0.24.x such a read was not
+    # marked ``(required)`` and a run leaving it out crashed in the provider
+    # with a ``TypeError``; ``tests/test_spec_command.py`` holds it. 0.24.0 put
+    # ``PermissionCheckDenied`` in ``REFUSALS``, which
+    # ``tests/test_exit_code_for.py`` decides by name. Below 0.11.0 the kernel
+    # also still shipped its own copy of the command and registered its own
+    # ``W001`` and ``W003``.
+    "django-service-specs>=0.25.0",
 ]
 
 [project.urls]
@@ -147,7 +149,7 @@ skip-magic-trailing-comma = false
 root = ["./django_spec_cli"]
 
 [tool.bumpversion]
-current_version = "0.3.0"
+current_version = "0.4.0"
 allow_dirty = false
 commit = false
 tag = false

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/tests/docs/test_reference.py

@@ -27,7 +27,12 @@ def test_every_root_name_has_an_entry_for_the_root_s_own_object() -> None:
         assert documented[name] is getattr(django_spec_cli, name), name
 
 
-def test_the_setting_and_both_check_ids_are_documented() -> None:
+def test_the_setting_and_every_check_id_is_documented() -> None:
     page = PAGE.read_text()
-    for spelling in ("SPEC_CLI_OUTPUT", "django_spec_cli.W001", "django_spec_cli.W003"):
+    for spelling in (
+        "SPEC_CLI_OUTPUT",
+        "django_spec_cli.W001",
+        "django_spec_cli.W003",
+        "django_spec_cli.W004",
+    ):
         assert f"`{spelling}`" in page, spelling

django_spec_cli-0.4.0/tests/report/test_utils.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from django.core.exceptions import ImproperlyConfigured
+
+from django_spec_cli.report.utils import refused_message
+
+
+def test_names_the_spec_and_the_command_then_the_kernel_s_reason() -> None:
+    error = ImproperlyConfigured("ServiceSpec.service requires the keyword(s) ['tenant'].")
+    assert refused_message("greet", "notes", error) == (
+        "'greet' in manage.py notes cannot run as declared, and a run of it is refused: "
+        "ServiceSpec.service requires the keyword(s) ['tenant']."
+    )

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/tests/test_checks.py

@@ -1,4 +1,5 @@
-"""The unguarded-spec system check, run over this suite's own command modules.
+"""The system checks, for an unguarded spec and a spec ``check_seeds`` refuses, run over
+this suite's own command modules.
 
 Other tests add command modules to the same app, so every assertion here is
 filtered to the commands this file owns - the ``unguarded_`` ones - and none
@@ -16,10 +17,22 @@ from django.core.checks import CheckMessage, Warning
 from django.core.management import call_command, get_commands, load_command_class
 from django.core.management.base import SystemCheckError
 from django.test import override_settings
-from django_service_specs import UnguardedReason, UnguardedSpec
+from django_service_specs import (
+    DEFAULT_POOL_SEEDS,
+    Parameter,
+    Parameters,
+    PoolSeeds,
+    ServiceSpec,
+    SpecRegistry,
+    UnguardedReason,
+    UnguardedSpec,
+    Unrestricted,
+)
 
 from django_spec_cli.checks import check_unguarded_specs
 from django_spec_cli.report.unguarded_message import unguarded_message
+from django_spec_cli.spec_command import SpecCommand
+from tests.commands_app.unguarded_registries import StaffOnly
 from tests.utils import run_project
 
 APP = "tests.commands_app"
@@ -146,6 +159,110 @@ class TestACommandThatDoesNotLoad:
         assert len(_own_w001(check_unguarded_specs(None))) == 3
 
 
+def _needs_project(*, project: int) -> dict[str, int]:
+    return {"project": project}
+
+
+def _echo(**pool: object) -> object:
+    return pool
+
+
+def _greet(*, tenant: str) -> str:
+    return f"hello {tenant}"
+
+
+def _project_spec(*, required: bool) -> ServiceSpec:
+    """A read ``project`` beside a ``kwargs`` provider that takes it by name, with no default."""
+    return ServiceSpec(
+        service=_echo,
+        permissions=[StaffOnly()],
+        reads=Parameters.of(Parameter("project", "integer", required=required)),
+        kwargs=_needs_project,
+    )
+
+
+class TestADeclarationTheKernelRefuses:
+    """``check_seeds``, under the command's own ``pool_seeds``, over every spec it serves.
+
+    Each test serves one command of its own through the walk, so nothing here
+    depends on what the suite's command modules declare.
+    """
+
+    REFUSED = (
+        "'optional_project' in manage.py seeded cannot run as declared, and a run of it is "
+        "refused: ServiceSpec.kwargs requires the keyword(s) ['project'], declared as optional "
+        "reads that nothing else fills, so a call leaving one out fails with the provider's "
+        "own TypeError. Declare the read required, or give the keyword a default."
+    )
+
+    def _walk(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        registry: SpecRegistry,
+        pool_seeds: PoolSeeds = DEFAULT_POOL_SEEDS,
+    ) -> tuple[type, list[CheckMessage]]:
+        command = type("Command", (SpecCommand,), {"registry": registry, "pool_seeds": pool_seeds})
+        monkeypatch.setattr("django_spec_cli.checks.get_commands", lambda: {"seeded": APP})
+        monkeypatch.setattr(
+            "django_spec_cli.checks.load_command_class", lambda app_name, name: command()
+        )
+        return command, check_unguarded_specs(None)
+
+    def test_an_optional_read_a_provider_requires_is_reported(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        registry = SpecRegistry()
+        registry.register("optional_project", _project_spec(required=False))
+        command, messages = self._walk(monkeypatch, registry)
+        assert [m for m in messages if m.id == "django_spec_cli.W004"] == [
+            Warning(
+                self.REFUSED,
+                hint=(
+                    "Change the declaration as the message says. Until then a run of the spec "
+                    "is refused, whether or not django_spec_cli.W004 is silenced."
+                ),
+                obj=command,
+                id="django_spec_cli.W004",
+            )
+        ]
+
+    def test_a_spec_it_accepts_is_not_reported(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        registry = SpecRegistry()
+        registry.register("required_project", _project_spec(required=True))
+        _, messages = self._walk(monkeypatch, registry)
+        assert messages == []
+
+    def test_one_warning_per_refused_spec_beside_the_command_s_other_reports(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Refusing one spec loses neither the W001 of an open spec in the same
+        # command nor the command itself to a W003.
+        registry = SpecRegistry()
+        registry.register("optional_project", _project_spec(required=False))
+        registry.register("required_project", _project_spec(required=True))
+        registry.register("open", ServiceSpec(service=_echo, permissions=[Unrestricted()]))
+        registry.register("unseeded", ServiceSpec(service=_greet, permissions=[StaffOnly()]))
+        _, messages = self._walk(monkeypatch, registry)
+        assert [(m.id, m.msg.split(" ")[0]) for m in messages] == [
+            ("django_spec_cli.W001", "'open'"),
+            ("django_spec_cli.W004", "'optional_project'"),
+            ("django_spec_cli.W004", "'unseeded'"),
+        ]
+        assert not any(message.is_serious() for message in messages)
+
+    def test_it_reads_the_command_s_pool_seeds(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        # ``tenant`` is filled by nothing under the stock seeds, and by the seed
+        # the command registers.
+        registry = SpecRegistry()
+        registry.register("greet", ServiceSpec(service=_greet, permissions=[StaffOnly()]))
+        _, unseeded = self._walk(monkeypatch, registry)
+        assert [m.id for m in unseeded] == ["django_spec_cli.W004"]
+        assert "['tenant']" in unseeded[0].msg
+        seeds = DEFAULT_POOL_SEEDS.extend(tenant=lambda: "acme")
+        _, seeded = self._walk(monkeypatch, registry, pool_seeds=seeds)
+        assert seeded == []
+
+
 class TestAppConfigs:
     """``manage.py check <app_label>`` checks the commands of the apps it names."""
 

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/tests/test_spec_command.py

@@ -297,15 +297,102 @@ class TestSeeds:
         command = command_over(self._registry(), pool_seeds=seeds)
         assert run("greet", "--as-user", str(owner.pk), command=command) == '"hello acme"\n'
 
-    def test_with_no_seeds_named_a_callable_reading_one_fails_as_dispatch_does(
-        self, owner: Any
+    def test_a_reflected_read_a_seed_fills_is_an_option_only_without_the_seed(
+        self, capsys: pytest.CaptureFixture[str], owner: Any
     ) -> None:
+        # Offered under the command's seeds, it would be refused when passed,
+        # as an argument dispatch does not take.
+        def greet(*, tenant: str) -> str:
+            return f"hello {tenant}"
+
+        reads = Parameters.of(Parameter("tenant", "string", required=True, reflected=True))
+        spec = ServiceSpec(service=greet, permissions=[Unrestricted()], reads=reads)
+        registry = registry_of(greet=spec)
+        seeded = command_over(registry, pool_seeds=DEFAULT_POOL_SEEDS.extend(tenant=lambda: "acme"))
+        assert "--tenant" not in help_of(capsys, "greet", command=seeded)
+        assert run("greet", "--as-user", str(owner.pk), command=seeded) == '"hello acme"\n'
+        unseeded = " ".join(help_of(capsys, "greet", command=command_over(registry)).split())
+        assert "--tenant STRING (required)" in unseeded
+
+    def test_with_no_seeds_named_a_callable_reading_one_is_refused(self, owner: Any) -> None:
         # The default is the stock seeds, as ``dispatch``'s: a seed nobody
-        # registered is the callable's own ``TypeError``, not a quiet default.
-        with pytest.raises(TypeError, match="tenant"):
+        # registered is no quiet default, and the kernel's ``check_seeds``
+        # refuses the spec before it reaches the callable's own ``TypeError``.
+        with pytest.raises(ImproperlyConfigured, match=r"\['tenant'\], which nothing fills"):
             run("greet", "--as-user", str(owner.pk), command=command_over(self._registry()))
 
 
+class TestADeclarationTheKernelRefuses:
+    """A spec ``check_seeds`` refuses under the command's seeds never reaches dispatch.
+
+    ``call_command`` handed an instance names it after this module, so the
+    sentence reads ``manage.py test_spec_command``.
+    """
+
+    REFUSAL = (
+        "'echo' in manage.py test_spec_command cannot run as declared, and a run of it is refused: "
+        "ServiceSpec.kwargs requires the keyword(s) ['project'], declared as optional reads "
+        "that nothing else fills, so a call leaving one out fails with the provider's own "
+        "TypeError. Declare the read required, or give the keyword a default."
+    )
+
+    def _command(self, **attributes: Any) -> SpecCommand:
+        def needs_project(*, project: int) -> dict[str, Any]:
+            return {"project": project}
+
+        spec = echo_spec(Parameter("project", "integer", required=False), kwargs=needs_project)
+        return command_over(registry_of(echo=spec, ping=open_spec(lambda: "pong")), **attributes)
+
+    @pytest.mark.parametrize("sent", [[], ["--project", "3"]], ids=["read-left-out", "read-sent"])
+    def test_a_run_of_it_is_refused_with_the_kernel_s_reason(
+        self, owner: Any, sent: list[str]
+    ) -> None:
+        # Sending the read would run: refused anyway, because the declaration
+        # says it is optional and every run leaving it out crashes.
+        with pytest.raises(ImproperlyConfigured) as caught:
+            run("echo", "--as-user", str(owner.pk), *sent, command=self._command())
+        assert str(caught.value) == self.REFUSAL
+
+    def test_it_is_refused_before_the_user_is_looked_up(self) -> None:
+        looked_up: list[str] = []
+
+        def resolve_as_user(self: SpecCommand, value: str) -> Any:
+            looked_up.append(value)
+            raise PrincipalUnavailable("nobody")
+
+        command = self._command(resolve_as_user=resolve_as_user)
+        with pytest.raises(ImproperlyConfigured):
+            run("echo", "--as-user", "7", command=command)
+        assert looked_up == []
+
+    def test_the_command_s_other_specs_still_run(self, owner: Any) -> None:
+        assert run("ping", "--as-user", str(owner.pk), command=self._command()) == '"pong"\n'
+
+    def test_help_and_explain_still_answer(self, capsys: pytest.CaptureFixture[str]) -> None:
+        # Asked of the spec run, never where the parser is built, so the
+        # command's listing and its report still work.
+        command = self._command()
+        parser = command.create_parser("manage.py", "notes")
+        with pytest.raises(SystemExit):
+            parser.parse_args(["--help"])
+        assert "echo" in capsys.readouterr().out
+        assert "'echo' in manage.py " in run("--explain", command=command)
+
+    @override_settings(SILENCED_SYSTEM_CHECKS=["django_spec_cli.W004"])
+    def test_silencing_the_warning_does_not_let_it_run(self, owner: Any) -> None:
+        with pytest.raises(ImproperlyConfigured):
+            run("echo", "--as-user", str(owner.pk), "--project", "3", command=self._command())
+
+    @pytest.mark.usefixtures("keep_the_test_connection")
+    def test_from_argv_it_propagates_for_a_traceback_and_not_an_exit_code(self, owner: Any) -> None:
+        # ``run_from_argv`` turns only a ``CommandError`` into ``sys.exit``;
+        # anything else reaches ``manage.py`` as a traceback and exit status 1,
+        # which is ``ExitCode.ERROR`` as the docs publish it.
+        argv = ["manage.py", "notes", "--skip-checks", "echo", "--as-user", str(owner.pk)]
+        with pytest.raises(ImproperlyConfigured, match="cannot run as declared"):
+            self._command().run_from_argv(argv)
+
+
 class TestAbbreviation:
     """A prefix of an option is never read as the option, the command's own or a spec's."""
 
@@ -428,6 +515,38 @@ class TestHelp:
         assert "--project" not in text
         assert "--n INTEGER" in text
 
+    def test_a_read_a_provider_may_fill_is_offered_and_not_required(
+        self, capsys: pytest.CaptureFixture[str], owner: Any
+    ) -> None:
+        # A return that says nothing about its keys may fill any read, so
+        # dispatch demands none of them of the caller and the help asks for none.
+        def may_fill(**_: Any) -> dict[str, Any]:
+            return {"project": 1}
+
+        spec = echo_spec(Parameter("project", "integer", required=True), kwargs=may_fill)
+        command = command_over(registry_of(echo=spec))
+        text = " ".join(help_of(capsys, "echo", command=command).split())
+        assert "--project INTEGER" in text
+        assert "(required)" not in text
+        assert lines(run("echo", "--as-user", str(owner.pk), command=command)) == [{"project": 1}]
+
+    def test_a_read_a_provider_requires_itself_is_required(
+        self, capsys: pytest.CaptureFixture[str], owner: Any
+    ) -> None:
+        # A provider that takes the read by name, with no default, cannot be the
+        # one to fill it, so dispatch demands it of the caller. A kernel before
+        # 0.25.0 relaxed it, and a run leaving it out crashed in the provider.
+        def needs_project(*, project: int) -> dict[str, Any]:
+            return {"project": project}
+
+        spec = echo_spec(Parameter("project", "integer", required=True), kwargs=needs_project)
+        command = command_over(registry_of(echo=spec))
+        text = " ".join(help_of(capsys, "echo", command=command).split())
+        assert "--project INTEGER (required)" in text
+        error = refused("echo", "--as-user", str(owner.pk), command=command)
+        assert error.returncode == 3
+        assert str(error).splitlines()[1:] == ["project: This field is required."]
+
 
 # --- output --------------------------------------------------------------------------------------
 

{django_spec_cli-0.3.0 → django_spec_cli-0.4.0}/uv.lock

@@ -490,7 +490,7 @@ docs = [
 [package.metadata]
 requires-dist = [
     { name = "django", specifier = ">=4.2" },
-    { name = "django-service-specs", specifier = ">=0.24.0" },
+    { name = "django-service-specs", specifier = ">=0.25.0" },
 ]
 
 [package.metadata.requires-dev]