Artifacts - Package auto assembler

Skip to content

# Artifacts Component

## About

In PAA, artifacts are package-attached files and metadata produced during packaging and later available from the installed package. They are part of the package lifecycle, not a separate runtime interface.

This component explains artifact behavior across: - unfolded PPR structure (editable source repo layout) - packaged structure (installed dependency layout)

## Artifact Types

PAA packages can include:

- tracking files under `.paa/tracking`
- optional MkDocs site under `mkdocs/`
- optional user artifacts copied from `artifacts/<package_name>/`
- optional tests copied from `tests/<package_name>/`

Tracking files are tool metadata used by PAA workflows (version tracking, release notes inputs, mapping files, etc.).

## Package vs Unfold Behavior

### During package build

When `paa make-package` or `paa test-install` prepares the setup directory, PAA assembles package artifacts into installable layout.

Typical result in packaged module: - `package_name/.paa/...` tracking data - `package_name/mkdocs/site/...` (if docs were built) - `package_name/artifacts/...` (if artifact files were provided) - `package_name/tests/...` (if tests were included)

### During unfold

`paa unfold-package <package>` reconstructs editable PPR-like structure from installed package content.

Artifact-related behavior in unfold flow: - packaged tracking content is written back into local `.paa/...` paths used by the repository - packaged docs/artifacts/tests are restored to configured repo locations when available - restoration follows current `.paa.config` path mapping

This is why unfolding can re-create package-associated auxiliary files even outside the original repository.

## Artifact Sources

User-provided artifacts can come from:

1. filesystem inputs in `artifacts/<package_name>/`
2. link files (`*.link`) stored in artifact directory
3. `artifact_urls` entries in package metadata (`__package_metadata__`)

For link-based inputs, PAA resolves/downloads content during packaging so final artifacts are physically bundled with the package. For metadata field details, see `components/package_metadata.md`.

## Operational Commands

Inspect packaged artifact records (without extraction):

    paa show-module-artifacts your-package-1
    paa show-module-artifacts-links your-package-1

Refresh artifact records for a module:

    paa refresh-module-artifacts your-package-1

Build/install with artifacts:

    paa test-install your-package-1 --skip-deps-install

Extract packaged artifacts from installed dependency:

    paa extract-module-artifacts your-package-1 --output-dir ./artifacts_out

Extract packaged docs site:

    paa extract-module-site your-package-1 --output-dir ./site_out

`show-*` commands list artifact metadata/locations, `refresh-module-artifacts` updates module artifact records, and `extract-*` commands copy files to your target directory.

## Practical Notes

- Keep artifact naming stable to avoid confusion across versions.
- Prefer deterministic artifact generation for reproducible package builds.
- For docs-related images, follow mkdocs docs guidance on drawio conversion and file naming to avoid collisions.
- Treat large binary artifacts deliberately, as they increase package size and install time.