Skip to content
Quartermaster Quartermaster

Packs

A pack is a portable, hash-verified bundle of artifacts plus their provenance/risk/drift/compatibility metadata. Pack operations are preview-first; materialization is opt-in and root-confined.

Building a pack

Section titled “Building a pack”
  • export_pack({ name, artifacts }) — build a v1 manifest from supplied artifact bodies. Each artifact records a sha256.
  • export_pack({ name, version: 2, itemIds: [...], includeRisk?, includeDrift?, includeCompatibility?, targetTool? }) — build a v2 manifest from registry items, populating real sections:
    • provenance — each item’s upstream links (+ resolved source)
    • risk — persisted risk findings (when includeRisk)
    • drift — the latest persisted drift report (when includeDrift)
    • compatibility — assess_compatibility to targetTool (or the item’s own tool) when includeCompatibility
    • policies — policy findings for the bundled artifacts

Both forms are previews (dryRun: true, writes: []). Manifests are deterministic JSON — the same inputs produce the same bytes.

Verifying & importing

Section titled “Verifying & importing”
  • verify_pack({ pack }) — recompute and check every artifact hash; returns ok: false with errors when any hash has changed.
  • import_pack({ pack }) — preview an import; every artifact is marked trustState: "untrusted" and nothing is hydrated or applied. Review with scan_risk and set_trust_state before any apply.

Materializing (opt-in, approval-gated)

Section titled “Materializing (opt-in, approval-gated)”

materialize_pack({ outputPath, pack, approval }) writes a v1 manifest + artifact files under an allowed directory.

  • Preview by default; requires approval: "approve" to write.
  • outputPath must be inside a configured PACK_OUTPUT_ROOTS directory (env, comma-separated, ~ expanded). With none configured, materialization is refused — the safe default.
  • Returns a rollback handle — the run can be reversed, removing the written files and directories.
  • After materialization, verify_pack on the written manifest passes.
Terminal window
PACK_OUTPUT_ROOTS="$HOME/quartermaster-packs" npm start
# then: materialize_pack({ approval: "approve", outputPath: "~/quartermaster-packs/core", pack })

See the security model for the write-safety guarantees.