breadpack/README.md

# breadpack

breadpunk.club's in-house package management system (prototype).

[TOC]

## global options

```
breadpack
    [--file PATH]
    [--lockfile PATH]
    [--requestsfile PATH]
    SUBCOMMAND [OPTIONS …]
```

* `--file` sets a custom path for `breadpack.json`.
  Defaults to `/bread/breadpack.json`.
* `--lockfile` sets a custom path for `breadpack-lock.json`.
  Defaults to `/bread/breadpack-lock.json`.
* `--requestsfile` sets a custom path for `breadpack-requests.rec`.
  Defaults to `/bread/breadpack-requests.rec`.

## for users

### list installed packages

`breadpack list [--json] [--upgradable]`

This list is generated from the cached version data on `breadpunk-lock.json`.
An admin will need to run `breadpack check` to update this list.

* `--json` enables JSON output, useful for scripting.
* `--upgradable` restricts the output to upgradable packages only.

### request a package

`breadpack request <package_name> [-c|--comment COMMENT]`

* `package_name`: Name of the package or application that you want installed.  
  This does not have to be a perfect APT package name; all package requests
  are human-reviewed.
* `-c` or `--comment`: Add an optional comment for the admins,
  for example to explain why you want a package installed or what it is.

## for admins

### lint the `breadpack.json` file

`breadpack lint`

### build the lockfile

`breadpack lock`

Caution! This rebuilds the lockfile from scratch and is mainly inteded for
first installation and/or fixing corrupted files.  This may cause some updates
to be skipped!

This command will fail if the lockfile already exists.

### check for updates

`breadpack check [--json] [--save|--no-save]`

* `--json` enables JSON output, useful for scripting.
* `--save` and `--no-save` toggle whether to or not to save to
  `breadpack-lock.json`.  `--save` is enabled by default.

## file formats

### `breadpack.json`

This file is managed by humans.  It is recommended to commit it to a Git repo.

``` json
{
    "version": 0,
    "categories": {
        "irc": "Anything related to Internet Relay Chat"
    },
    "packages": [
        {
            "name": "weechat",
            "category": "irc",
            "type": "apt",
            "apt_name": "weechat"
        }
    ]
}
```

#### `version`

The breadpack.json version number to ensure compatibility in case of format
updates later on.  Should be set to `0` for now.

#### `categories`

A simple object mapping string keys to string values.  The keys are category
names and the values are category descriptions.

The keys can be used as the value for `category` in package.

#### `packages`

A list of packages to display publicly and monitor for updates.

* `name`: Package display name.  Must be unique.
* `category`: Category name from `categories`.  Optional.
* `type`: The package's type: one of `apt` or `manual`.  
  Other types, such as `pip`, might be handled later.

Type-specific options are explained below.

##### `apt` package options

* `apt_name`: The APT package name. Optional, defaults to `name`.

##### `manual` package options

* `version_file`: Path to a `VERSION` file.  Optional; when not set,
  breadpack will be unable to track the current installed version.
* `latest_version_script`: Path to an executable script returning
  the latest known package version.  Optional; when both `version_file`
  and `latest_version_script` are not set, breadpack will be unable to
  check for updates.

### `breadpack-lock.json`

This file is automatically generated by breadpack and is used to detect
changes in the package versions made by any manual upgrades.

This file **SHOULD NOT** be manually edited.  Should the file be corrupted
or be re-generated from scratch, updates may not be properly detected.

``` json
{
    "version": 0,
    "packages": [
        {
            "name": "weechat",
            "last_checked": "2020-02-31T13:37:42",
            "current_version": "12.42",
            "latest_version": "13.3.7"
        }
    ]
}
```

### `breadpack-requests.rec`

A [recfile](https://www.gnu.org/software/recutils/manual/The-Rec-Format.html)
that should be made writable to all users:

```
-rw--w---- root bakers 4242 Feb 31 13:37 breadpack-requests.rec
```

The Python script will automatically amend requests in the following form:

```
Date: [ISO 8601 datetime]
User: $USER
Processed: no
Package: $package_name
# if no comment was specified, this will not appear
Comment: $comment
```

The model descriptor can be written as follows:

```
%rec: PackageRequest
%type: Date date
%type: Processed bool
%type: User line
%type: Package line
%mandatory: Package
%allowed: Date User Processed Package Comment
%sort: Processed Date
%doc: Package requests made via breadpack
```

## setup

### dependencies

For APT support, install `python3-apt`.