httk.workflow.hygiene
=====================

.. py:module:: httk.workflow.hygiene

.. autoapi-nested-parse::

   Describing and repairing a project, its remotes, and its workspace.

   Everything here answers an operator question about state that already exists:
   *what is this project*, *what is this remote configured to do*, *what is wrong
   with this project and can it be fixed*. Nothing here is on the execution path of
   a job, and every repair is explicit — :func:`project_doctor` reports by default
   and only changes something when it is asked to.



Attributes
----------

.. autoapisummary::

   httk.workflow.hygiene.PROJECT_DESCRIPTION_FORMAT
   httk.workflow.hygiene.REMOTE_DESCRIPTION_FORMAT
   httk.workflow.hygiene.DOCTOR_REPORT_FORMAT
   httk.workflow.hygiene.DOCTOR_FRAME_FORMAT
   httk.workflow.hygiene.TMP_MAXIMUM_AGE_SECONDS


Classes
-------

.. autoapisummary::

   httk.workflow.hygiene.Finding


Functions
---------

.. autoapisummary::

   httk.workflow.hygiene.describe_project
   httk.workflow.hygiene.workflow_show_section
   httk.workflow.hygiene.describe_remote
   httk.workflow.hygiene.remove_remote
   httk.workflow.hygiene.project_doctor


Module Contents
---------------

.. py:data:: PROJECT_DESCRIPTION_FORMAT
   :value: 'httk-project-description'


.. py:data:: REMOTE_DESCRIPTION_FORMAT
   :value: 'httk-remote-description'


.. py:data:: DOCTOR_REPORT_FORMAT
   :value: 'httk-project-doctor'


.. py:data:: DOCTOR_FRAME_FORMAT
   :value: 'httk-workflow-doctor'


.. py:data:: TMP_MAXIMUM_AGE_SECONDS
   :value: 86400


.. py:function:: describe_project(project_root: str | os.PathLike[str] | None = None, *, verify: bool = True) -> dict[str, object]

   Describe one project: its metadata, its keys, its workspace, its manifest.

   *verify* walks the tree to classify the manifest, which is what makes the
   description say whether the project is *currently* described by what it
   signed; by design, pass ``False`` for a cheap answer when verification is
   not required, because that skips the tree walk.


.. py:function:: workflow_show_section(project: pathlib.Path, *, verify: bool) -> httk.core.project.cli.ProjectShowSection

   Contribute the workflow rows of ``httk project show``.

   This is the workflow half of what :func:`describe_project` reports — the
   workspace, the manifest, and the remotes — registered into the umbrella
   ``httk project`` command as a show section. The anchor half (metadata and
   keys) is rendered by *httk-core*; here we only add what a workflow
   installation knows about a project.


.. py:function:: describe_remote(name: str, *, project: str | os.PathLike[str] | None = None) -> dict[str, object]

   Describe one remote: where it lives, what it is, how it is configured.

   Credential values never appear. A queue's settings are reported with the
   file each one came from, and for a setting stored in the manifest-excluded
   ``credentials.json`` only its *name* is reported: a description an operator
   can paste into a bug report must never carry a password.


.. py:function:: remove_remote(name: str, *, project: str | os.PathLike[str] | None = None) -> dict[str, object]

   Remove one remote bundle, refusing while a transfer still needs it.

   A sealed bundle that has not been acknowledged is work this remote still
   owes an answer about, and the adapter is how that answer is fetched.
   Removing the remote would leave the transfer with no way home, so it is
   refused by name — retire or fetch the transfer first.


.. py:class:: Finding

   One thing the doctor looked at, and what it found.


   .. py:attribute:: check
      :type:  str


   .. py:attribute:: status
      :type:  str


   .. py:attribute:: message
      :type:  str


   .. py:attribute:: repairable
      :type:  bool
      :value: False



   .. py:attribute:: repaired
      :type:  bool
      :value: False



   .. py:attribute:: action
      :type:  str | None
      :value: None



   .. py:attribute:: details
      :type:  dict[str, object]


   .. py:method:: as_mapping() -> dict[str, object]

      Return the JSON representation of this finding.



.. py:function:: project_doctor(project_root: str | os.PathLike[str] | None = None, *, repair: bool = False) -> dict[str, object]

   Check one project for the conditions that quietly break it later.

   Every check reports; a check that can be fixed automatically is fixed only
   when *repair* is asked for, and a run that repaired anything says exactly
   what it did — in the log and, when the project has a workspace, in that
   workspace's journal, so the repair is part of its durable history.