# PicoPackage

This is a scheme for sharing text content, often source code, that's too small to be a language package ( Gem in Ruby, Package in Python, Create in Rust, Module in Perl or Go) but used frequently enough that copy and pasting between projects is painful. It is used to track a single file of text, allowing you to update it centrally for distribution, hosted as a file or a URL. 

Taking the concept of `front matter` from static site generaters, we add a commented block of metadata encoded with Yaml, which will be parsed by the `picopackage` tools. 

# Hosting goals
Ideally, code can be hosted anywhere, but it'd be great to specifically support Github Gists.

# Audience
It's perfectly acceptable to use Picopackage for private code, for personal or organisational use. It's perfectly acceptable to package code or configuration or data for public consumption.

# Dependency Management
None - currently.

# Testing
Ideally, there'll be a test method or link to a test file.

# Secure
SHA hashes to ensure content hasn't changed. 
SigStore to validate the author

# Metadata
Using comments, we'll include the following attributes

## Required Metadata
* url: Link to a the human readble version.
* file_name: name of the file, otherwise guessed from the url
* version: the version of this file.
* content_checksum: A sha256 hash of the file contents, excluding the front matter.
* content_timestamp: Timestamp for the content, formatted as RFC1123.

## Optional Metadata
* licence: souce code licence
* source_url: Optionally link to the latest version of this file if `url` isn't parsable.

## Future consideration
### Public Key signature, like RubyGems
* signature: A Base 64 Signature
* public_key: The public key component for signature verification
### Sigstore 
* sigstore: attributes for sigstore including :signature, :rekor_log_id, rekor_entry - for future 


# Example
```ruby
# @META_START
# home_url: https://gist.github.com/dkam/525ac4177964549ee2f2ca7febd03eea$0
# version: 1.0.0
# source_url: https://gist.github.com/dkam/525ac4177964549ee2f2ca7febd03eea/raw/
# test_method: test_me
# licence: MIT
# content_checksum: sha256:d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592
# signature: base64:MEUCIQCjRx4RQvXxhPqvqyOB8FQtHGLuoA3pG4qBbNV4LGJTGAIgbZxXD9UFWqLsT+GZYs1DMqVXf6Lj2Dh8BM3wXJJ4Sxs=
# public_key: -----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7DxL6Mj/Bc9VhgKrWYItPqNxYPQ4\nzrVXXaHJWKNEHgSBgFH1AiJJ0cD3vFKkWuuhgnV8JdP/RXs4+G3oHqgQTA==\n-----END PUBLIC KEY-----
# @META_END
```