feat(tasks): support both diracx-tasks and diracx-task-run (phase 1, #975)

[mmascher]

Summary

This PR implements Phase 1 of issue #975 by introducing the new CLI name while preserving backward compatibility with the old one.

What changed

1. Added a new console script name: diracx-tasks.
2. Kept the existing console script name: diracx-task-run.
3. Updated local launcher scripts to use the new primary name.
4. Updated user-facing docs to prefer diracx-tasks.
5. Added explicit compatibility notes in docs where useful, stating that diracx-task-run remains supported during migration.

Migration plan context (3 phases)

1. Phase 1 (this PR, diracx):
   Support both names in diracx so current deployments and charts do not break.
2. Phase 2 (diracx-charts):
   Switch charts to only use diracx-tasks after Phase 1 is merged/released.
3. Phase 3 (diracx):
   Remove the old alias diracx-task-run once chart migration is complete and safe.

Why this is safe

1. No breaking change in this PR: old command still works.
2. Local workflows move to the new command immediately, reducing future churn.
3. Rollback is straightforward: if needed, operators can continue using diracx-task-run without changing this release.

Rollback safety note

If any environment is still wired to diracx-task-run, it will continue to function in Phase 1.
In case of operational issues with the new command name rollout, usage can be temporarily reverted to diracx-task-run with no packaging change required in this PR.

Validation

1. Pre-commit hooks passed on committed changes.
2. Local scripts now invoke diracx-tasks.
3. Legacy name references that remain are intentional compatibility references.

Closes

Fixes #975

[read-the-docs-community]

Documentation build overview

📚 diracx | 🛠️ Build #33994274 | 📁 Comparing 1128a13 against latest (2893fc1)

  🔍 Preview build  

13 files changed · ± 11 modified · - 2 deleted

± Modified

• admin/explanations/tasks/index.html
• admin/reference/env-variables/index.html
• dev/explanations/tasks/index.html
• dev/how-to/add-a-task/index.html
• dev/reference/pixi-tasks/index.html
• dev/reference/tasks/index.html
• dev/tutorials/advanced-tutorial/index.html
• admin/how-to/tasks/configure/index.html
• admin/how-to/tasks/run-task-manually/index.html
• dev/explanations/tasks/class-details/index.html
• and 1 more...

- Deleted

• admin/explanations/pilots/index.html
• dev/explanations/pilots/index.html

[Copilot]

Pull request overview

This PR primarily implements Phase 1 of the CLI rename/migration for the tasks subsystem by introducing diracx-tasks while keeping diracx-task-run working, and updates local tooling + documentation to prefer the new name. It also includes a separate set of changes to HTTP/domain exception handling in the routers/core.

Changes:

• Add diracx-tasks as an additional console script entry point while keeping diracx-task-run.
• Update local launcher scripts, pixi tasks, and documentation to use diracx-tasks (with explicit compatibility notes in key docs).
• Refactor exception handling by removing DiracHttpResponseError and adjusting router behavior for some auth flows.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
run_local.sh	Switch local scheduler/worker invocations to diracx-tasks.
run_local_tasks.sh	Switch local wrapper to exec diracx-tasks.
pixi.toml	Update pixi task description to reference diracx-tasks.
docs/dev/reference/tasks.md	Update CLI reference example to diracx-tasks.
docs/dev/reference/pixi-tasks.md	Update pixi task docs to diracx-tasks.
docs/dev/reference/coding-conventions.md	Document exception-handling boundaries between layers.
docs/dev/how-to/add-a-task.md	Update interactive task execution examples to diracx-tasks call.
docs/dev/explanations/tasks/index.md	Update CLI naming and add migration alias note.
docs/dev/explanations/tasks/class-details.md	Update interactive mode mention to diracx-tasks call.
docs/admin/how-to/tasks/run-task-manually.md	Update operational docs to diracx-tasks + add alias note.
docs/admin/how-to/tasks/configure.md	Update operational examples to diracx-tasks + add alias note.
docs/admin/explanations/tasks.md	Update lifecycle explanation to reference diracx-tasks call.
diracx-tasks/src/diracx/tasks/task_run.py	Update CLI docstring to prefer diracx-tasks and mention alias.
diracx-tasks/pyproject.toml	Add diracx-tasks console script alongside diracx-task-run.
diracx-routers/src/diracx/routers/factory.py	Remove DiracHttpResponseError handler and adjust DiracError handling.
diracx-routers/src/diracx/routers/auth/token.py	Return a JSON OAuth-style error payload for pending device authorization.
diracx-routers/src/diracx/routers/auth/device_flow.py	Use str(e) for HTTPException detail construction.
diracx-core/src/diracx/core/exceptions.py	Remove DiracHttpResponseError and simplify DiracError shape.

Suppressed comments (1)

diracx-routers/src/diracx/routers/factory.py:33

• The PR is scoped (title/description) to introducing the new diracx-tasks CLI alias, but it also removes DiracHttpResponseError and changes application-level exception handling behavior. This is a significant, user-facing HTTP error-handling change that should either be called out explicitly in the PR description/release notes or split into a separate PR to keep the migration work isolated.

from diracx.core.config import ConfigSource
from diracx.core.exceptions import DiracError, NotReadyError
from diracx.core.extensions import DiracEntryPoint, select_from_extension
from diracx.core.settings import FactorySettings, ServiceSettingsBase
from diracx.core.sources import AsyncCacheableSource
from diracx.db.exceptions import DBUnavailableError

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mmascher]

I did the PR from a dirty branch, the correct PR is #1011