Skip to main content

Documentation Index

Fetch the complete documentation index at: https://filepacks.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
DigestMeaningWhere you see it
archive digestSHA-256 of the exact .fpk bytesCLI pack and inspect output as digest=sha256:<hex>
payload digestSHA-256 over the sorted manifest file listmanifest.json as payload_digest
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

CommandUse it when you want to…It does not prove…
inspectread the artifact summary quicklythat the payload still matches the manifest
verifyconfirm the artifact is intactthat the output is semantically good or acceptable
comparesee whether packaged files changedwhy the change is good or bad

​
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: 
npx filepacks pack ./run-prev --output ./baseline.fpk
npx filepacks pack ./run-current --output ./candidate.fpk
npx filepacks inspect ./candidate.fpk
npx filepacks verify ./candidate.fpk
npx filepacks compare ./baseline.fpk ./candidate.fpk

​
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.