RAFT project packages
=====================

A RAFT project package is a ``.rftpkg`` tar archive created by
``raft package-project``. It is intended to capture enough project state to
move, restore, or preserve a RAFT project without copying the entire project
directory by hand.

Where packages are stored
-------------------------

Packages are written under the source project's ``rftpkgs/`` directory:

.. code-block:: text

  projects/<PROJECT_ID>/rftpkgs/<PACKAGE_NAME>.rftpkg

If no ``--output`` name is provided, RAFT writes ``default.rftpkg``.

What a package contains
-----------------------

The package includes a temporary snapshot with these top-level entries:

- ``inputs/metadata/``: non-symlinked project metadata files
- ``workflow/``: the project workflow directory, including ``main.nf``,
  ``nextflow.config``, ``mounts.config``, and workflow modules
- ``snapshot.raft``: a post-processed command snapshot derived from
  ``.raft/auto.raft``
- ``snapshot.raft.actual``: the raw command snapshot
- ``checksums``: file checksums, unless ``--no-checksums`` was used

The checksum file covers files under:

- ``outputs/``
- ``inputs/``
- ``references/``
- ``workflow/``

Git metadata
------------

By default, packaged workflow directories may include Git metadata from cloned
workflow modules. Use ``--no-git`` to exclude that metadata:

.. code-block:: console

  $ raft package-project \
      --project-id my-project \
      --no-git

When to use ``.rftpkg``
-----------------------

Use a project package when you need to:

- archive the workflow and metadata state for a completed project
- move a project setup to another RAFT workspace
- share a reproducible project snapshot with another user
- preserve the command history RAFT recorded in ``.raft/auto.raft``

Limitations
-----------

``.rftpkg`` files are project snapshots, not full storage backups. Large input
files, symlink targets, external references, container images, and cloud bucket
objects may not be embedded in the package. Confirm that the destination
environment has access to the same required data and references before rerunning
a restored project.

Loading a package
-----------------

Load a package into a new project id with:

.. code-block:: console

  $ raft load-project \
      --project-id restored-project \
      --rftpkg /path/to/default.rftpkg

During load, RAFT initializes a new project, restores packaged ``inputs/`` and
``workflow/`` content, keeps the destination workspace's ``mounts.config``, and
rewrites project identifiers in stored package metadata where needed.