Project status
==============

``raft project-status`` is a read-only command for summarizing the current
state of one RAFT project.

It does not repair, download, delete, rerun, or modify project files. It is
safe to run repeatedly while inspecting a project.

Basic usage
-----------

Run:

.. code-block:: console

  $ raft project-status --project-id my-project

The command reports:

- project path and detected workflow context
- an overall status label such as ``setup complete, not run yet``,
  ``run failed``, or ``complete, reports available``
- the manifest RAFT believes the project is using
- manifest row, patient, dataset, run, sample-prefix, ``Group``, and
  ``Alleles`` summaries
- latest Nextflow trace status counts and failed task count
- presence of ``outputs/``, ``outputs/samples/``, ``outputs/qc/``, and
  ``outputs/reports/``
- simple output file counts
- workflow-specific checks when RAFT recognizes the workflow
- a ``Next`` section with suggested follow-up commands

Use JSON for automation:

.. code-block:: console

  $ raft project-status --project-id my-project --json

Next actions
------------

The ``Next`` section is intended to answer "what should I do now?" without
changing project files. The suggestions are derived from detected project
state.

After ``--setup-only``, ``project-status`` suggests starting the workflow:

.. code-block:: text

  Status: setup complete, not run yet

  Next:
    Start the workflow:
      raft run --project-id my-project
    Open the viewer without preloaded outputs:
      raft generate-reports --project-id my-project --no-load

After a failed run, it points to the latest trace, the Nextflow log, and the
rerun command:

.. code-block:: text

  Status: run failed

  Next:
    Inspect the latest trace:
      less /path/to/projects/my-project/outputs/reports/trace-20260419.txt
    Inspect the Nextflow log:
      less /path/to/projects/my-project/logs/.nextflow.log
    After fixing the problem, rerun:
      raft run --project-id my-project

When reportable outputs are present, it suggests opening the report viewer and
packaging the project:

.. code-block:: text

  Status: complete, reports available

  Next:
    Open the report viewer:
      raft generate-reports --project-id my-project
    Package the project:
      raft package-project --project-id my-project

Manifest detection
------------------

A project can contain multiple files under ``inputs/metadata``. ``project-status``
therefore does not assume that the newest or only manifest-like file is the one
used by the workflow.

Detection order is:

1. Read ``workflow/main.nf``.
2. Look for manifest-like ``Channel.fromPath(...)`` entries.
3. Resolve ``${params.*}`` expressions using parameter assignments in
   ``main.nf``. For example, RAFT resolves
   ``${params.metadata_dir}/my.manifest.tsv`` using the project's actual
   ``inputs/metadata`` directory.
4. If exactly one referenced manifest exists, report that file as the manifest
   source.
5. If ``main.nf`` is ambiguous, fall back to files under the project's
   ``inputs/metadata`` directory.

The output includes the manifest source, for example:

.. code-block:: text

  Manifest: inputs/metadata/lens.human.demo.manifest
  Manifest source: workflow/main.nf

If multiple manifest-like files exist and ``main.nf`` does not identify one
unambiguously, ``project-status`` reports a warning.

Workflow-specific status
------------------------

``project-status`` is designed so workflow-specific checks can be added without
changing the user-facing command. Workflow-owned status files use the same
repository pattern as manifest and report UI templates.

RAFT looks for status configs in this order:

1. project-local workflow config checkouts, such as
   ``<project>/lens-human-fastqs/lens.human.fastqs.status.json``
2. packaged RAFT defaults under ``src/raft/ui/static/workflows/<workflow>/``

The most specific filename is preferred:

.. code-block:: text

  <workflow>.<species>.<input>.status.json
  <workflow>.<species>.status.json
  <workflow>.status.json
  status.json

This means a workflow config repository such as
``lens-human-fastqs`` can own ``lens.human.fastqs.status.json`` beside:

.. code-block:: text

  lens.human.fastqs.config
  lens.human.fastqs.json
  lens.human.fastqs.manifest-ui.json
  lens.human.fastqs.report-ui.json

Status config files can define:

- expected output paths
- table/report glob patterns
- fields to count
- required columns
- columns that should warn when blank in every row

For LENS projects, it reports:

- number of final LENS report files
- row count for the first final report
- candidate counts by ``antigen_source``
- warnings for missing configured required columns, such as ``candidate_id``
  and review columns
- warnings for final-report columns that are blank in all rows for selected
  tumor-level fields

Interpreting warnings
---------------------

Warnings are meant to identify conditions that deserve review. They are not
always fatal errors.

Examples:

- latest trace contains failed tasks
- multiple manifest-like files were found but ``main.nf`` did not identify one
- final LENS report lacks ``candidate_id``
- review columns are missing from the final LENS report

Use these warnings to decide whether to inspect logs, trace files, intermediate
outputs, or workflow-specific documentation before trusting the final report.