# packagelock

### Overview

The `packagelock` tool is used to codify package digests and tags for promotion across environments 
from DEV -> STAGE1 -> STAGE2 -> PROD

The package lock format is defined in the [Cue](https://cuelang.org/) language, a language 
for creating configuration standards. The configuration for the EDGE package lock format
is defined in the [package-lock-rules.cue](`package-lock-rules.cue`) file.

### Package lock file requirements

Package lock files have several requirements:
- Each package has 3 required elements: 
  - A `name:` string that defines the name of the package
  - A `latest:` string in the `sha256:abc123` digest format defining the SHA of the latest version
  - A list of versions in the `versions:` element each with its own version requirements:
    - A `digest:` string that also abides by the `sha256:abc123` format denoting the digest of the version
    - A `tags:` list of strings defining all tags associated with the version
      - Each tag must be string-only serializable according to YAML 1.2 strings
      - E.g. for semver `"0.13"`, that version must be surrounded in double quotes to assure treatment as a string vs. a float

The Cue rules engine is able to take these requirements and parse/validate and package lock file that is 
passed in via either Cue directly, or via the `packagelock validate <path to lockfile>` command.

### Validation

Use the `packagelock validate <path to lockfile>` command to validate a file. The command will error if 
any portion of the file does not abide by the lock file requirements set in the `package-lock-rules.cue` file.

### Building a lock file

Lock files can be built from a GAR source via the `packagelock build [flags]` command.

By passing the GAR repository information and a list of packages, the command will build
a valid package lock file in stdout and the optional outpath for saving to a file.