Skip to main content

​
Artifact

An artifact is a deterministic .fpk archive representing one packaged directory of files. Key properties:
  • immutable once written
  • portable as a single file
  • self-describing through manifest.json
  • structurally comparable against another artifact
In practice, an artifact is the review boundary you hand to a teammate, upload from CI, or compare against a previous run.

​
Manifest

manifest.json is the canonical metadata document inside the archive. It is the first archive entry and includes:
  • artifact_name
  • created_with
  • file_count
  • files[]
  • format_version
  • payload_digest
  • total_bytes
Each file entry records:
  • path
  • size
  • hash
The manifest is what inspect, verify, and compare reason about. It is the source of truth for what the artifact claims to contain.

​
Payload

Payload files are stored under payload/ inside the archive. The manifest refers to them by normalized relative path without the payload/ prefix. Example:
  • archive entry: payload/reports/summary.txt
  • manifest path: reports/summary.txt

​
Determinism

Determinism means the same logical input produces the same .fpk bytes. In the current implementation, that depends on:
  • lexical directory traversal
  • sorted manifest entries
  • fixed tar header metadata
  • stable manifest serialization
  • manifest.json written first

​
Archive digest and payload digest

Two digests matter: The archive digest identifies the artifact file itself. The payload digest proves that the manifest’s file inventory still matches the payload file list.

​
Verification

Verification checks whether the payload still matches the manifest. That includes:
  • manifest validity
  • expected payload paths
  • file sizes
  • file hashes
  • the aggregate payload_digest
Use verify to confirm an artifact is intact — for example, before using it as a baseline or sharing it for review. verify exits 0 on success and 1 on failure.

​
Structural comparison

Structural comparison answers a simple question: did any packaged file change? It compares two manifests and reports added, removed, and changed file paths. Use compare to understand what changed between two runs. compare exits 0 when the artifacts are identical and 20 when they differ — an exit code that is directly usable in CI and automation.

​
When to use inspect vs verify

​
Baseline and candidate

When comparing artifacts:
  • baseline means the accepted or previously known-good artifact
  • candidate means the new artifact you want to review
The public OSS CLI does not resolve baselines for you. You pass explicit file paths.

​
Typical workflow

A common review loop looks like this:

​
CLI versus core library

The CLI exposes a narrow command set. The core package exposes the same public operations programmatically:
  • pack()
  • inspect()
  • verify()
  • compare()
pack() in @filepacks/core also accepts an optional name field for the artifact name. The public CLI does not currently expose a --name flag. For Node.js examples and return-value details, see Programmatic API.

​
Current OSS boundary

The public repo intentionally excludes:
  • typed artifact manifests
  • registry protocols
  • local store management
  • tags and baseline workflows
  • additional CLI commands outside pack, inspect, verify, and compare
For format-level detail, continue to Artifacts. For practical command patterns, use CLI workflows.