mkArion

This is a transparent convenience proxy for hercules-ci/arion’s lib.build function.

However, the arion’s nixos config option was removed.

As Standard claims to be the integration layer it will not delegate integration via a foreign interface to commissioned tools, such as arion.

This is a bridge towards and from docker-compose users. Making nixos part of the interface would likely alienate that bridge for those users.

If you need a nixos-based container image, please check out the arion source code on how it’s done.

mkMakes

… provides an interface to makes tasks

This is an integration for fluidattacks/makes.

A version that has this patch is a prerequisite.

Usage example

{
  inputs,
  cell,
}: let
  inherit (inputs.std.lib) dev;
in {
  task = ops.mkMakes ./path/to/make/task//main.nix {};
}

Some refactoring of the tasks may be necessary. Let the error messages be your friend.

---

mkNixago

This is a transparent convenience proxy for nix-community/nixago’s lib.${system}.make function.

It is enriched with a forward contract towards std enriched mkShell implementation.

In order to define numtide/devshell’s commands & packages alongside the Nixago pebble, just add the following attrset to the Nixago spec. It will be picked up automatically by mkShell when that pebble is used inside its config.nixago-option.

{ inputs, cell }: {
  foo = inputs.std.lib.dev.mkNixago {
    /* ... */
    packages = [ /* ... */ ];
    commands = [ /* ... */ ];
    devshell = { /* ... */ }; # e.g. for startup hooks
  };
}

mkShell

This is a transparent convenience proxy for numtide/devshell’s mkShell function.

It is enriched with a tight integration for std Nixago pebbles:

{ inputs, cell}: {
  default = inputs.std.lib.dev.mkShell {
    /* ... */
    nixago = [
      (cell.nixago.foo {
        data.qux = "xyz";
        packages = [ pkgs.additional-package ];
      })
      cell.nixago.bar
      cell.nixago.quz
    ];
  };
}

Note, that you can extend any Nixago Pebble at the calling site via a built-in functor like in the example above.

mkMicrovm

… provides an interface to microvm tasks

This is an integration for astro/microvm.nix.

Usage example

{
  inputs,
  cell,
}: let
  inherit (inputs.std.lib) ops;
in {
  # microvm <module>
  myhost = ops.mkMicrovm ({ pkgs, lib, ... }: { networking.hostName = "microvms-host";});
}

---

mkOCI

… is a function to generate an OCI Image via nix2container.

The function signature is as follows:

  Creates an OCI container image

  Args:
  name: The name of the image.
  entrypoint: The entrypoint of the image. Must be a derivation.
  tag: Optional tag of the image (defaults to output hash)
  setup: A list of setup tasks to run to configure the container.
  uid: The user ID to run the container as.
  gid: The group ID to run the container as.
  perms: A list of permissions to set for the container.
  labels: An attribute set of labels to set for the container. The keys are
  automatically prefixed with "org.opencontainers.image".
  config: Additional options to pass to nix2container.buildImage's config.
  options: Additional options to pass to nix2container.buildImage.

  Returns:
  An OCI container image (created with nix2container).
  */

mkOperable

… is a function interface into the second layer of packaging of the Standard SDLC Packaging pattern.

It’s purpose is to provide an easy way to enrich a “package” into an “operable”.

The function signature is as follows:

  Args:
  package: The package to wrap.
  runtimeScript: A bash script to run at runtime.
  runtimeEnv: An attribute set of environment variables to set at runtime.
  runtimeInputs: A list of packages to add to the runtime environment.
  runtimeShell: The runtime shell. Defaults to bash.
  debugInputs: A list of packages available in the debug shell.
  livenessProbe: An optional derivation to run to check if the program is alive.
  readinessProbe: An optional derivation to run to check if the program is ready.

  Returns:
  An operable for the given package.
  */
  {
    package,

mkStandardOCI

… is a function interface into the third layer of packaging of the Standard SDLC Packaging pattern.

It produces a Standard OCI Image from an “operable”.

The function signature is as follows:

  Creates an OCI container image using the given operable.

  Args:
  name: The name of the image.
  operable: The operable to wrap in the image.
  tag: Optional tag of the image (defaults to output hash)
  setup: A list of setup tasks to run to configure the container.
  uid: The user ID to run the container as.
  gid: The group ID to run the container as.
  perms: A list of permissions to set for the container.
  labels: An attribute set of labels to set for the container. The keys are
  automatically prefixed with "org.opencontainers.image".
  debug: Whether to include debug tools in the container (coreutils).
  config: Additional options to pass to nix2container.buildImage's config.
  options: Additional options to pass to nix2container.

  Returns:
  An OCI container image (created with nix2container).
  */

The Standard Image

Standard images are minimal and hardened. They only contain required dependencies.

Contracts

The following contracts can be consumed:

/bin/entrypoint # always present
/bin/runtime    # always present, drops into the runtime environment
/bin/live       # if livenessProbe was set
/bin/ready      # if readinessProbe was set

That’s it. There is nothing more to see.

All other dependencies are contained in /nix/store/....

The Debug Image

Debug Images wrap the standard images and provide additional debugging packages.

Hence, they are neither minimal, nor hardened because of the debugging packages’ added surface.

Contracts

The following contracts can be consumed:

/bin/entrypoint # always present
/bin/runtime    # always present, drops into the runtime environment
/bin/debug      # always present, drops into the debugging environment
/bin/live       # if livenessProbe was set
/bin/ready      # if readinessProbe was set

How to extend?

A Standard or Debug Image doesn’t have a package manager available in the environment.

Hence, to extend the image you have two options:

Nix-based extension

rec {
  upstream = n2c.pullImage {
    imageName = "docker.io/my-upstream-image";
    imageDigest = "sha256:fffff.....";
    sha256 = "sha256-ffffff...";
  };
  modified = n2c.buildImage {
    name = "docker.io/my-modified-image";
    fromImage = upstream;
    contents = [nixpkgs.bashInteractive];
  };
}

Dockerfile-based extension

FROM alpine AS builder
RUN apk --no-cache curl

FROM docker.io/my-upstream-image
COPY --from=builder /... /

Please refer to the official dockerfile documentation for more details.

readYAML

… is a function that parses YAML into Nix.

The only argument is a path.

adrgen

adrgen is a great tool to manage Architecture Decision Records.

---

Definition:

let
  inherit (inputs) nixpkgs;
in {
  data = {};
  output = "adrgen.config.yml";
  format = "yaml";
  commands = [{package = nixpkgs.adrgen;}];
}

conform

Conform your code to policies, e.g. in a pre-commit hook.

This version is wrapped, it can auto-enhance the conventional commit scopes with your cells as follows:

{ inputs, cell}: let
  inherit (inputs.std) lib;
in {

  default = lib.dev.mkShell {
    /* ... */
    nixago = [
      (lib.cfg.conform {data = {inherit (inputs) cells;};})
    ];
  };
}

---

Definition:

let
  l = nixpkgs.lib // builtins;
  inherit (inputs) nixpkgs;
in {
  data = {};
  format = "yaml";
  output = ".conform.yaml";
  packages = [nixpkgs.conform];
  apply = d: {
    policies =
      []
      ++ (l.optional (d ? commit) {
        type = "commit";
        spec =
          d.commit
          // l.optionalAttrs (d ? cells) {
            conventional =
              d.commit.conventional
              // {
                scopes =
                  d.commit.conventional.scopes
                  ++ (l.subtractLists l.systems.doubles.all (l.attrNames d.cells));
              };
          };
      })
      ++ (l.optional (d ? license) {
        type = "license";
        spec = d.license;
      });
  };
}

editorconfig

Most editors understand the .editorconfig file and autoconfigure themselves accordingly.

---

Definition:

let
  l = nixpkgs.lib // builtins;
  inherit (inputs) nixpkgs;
in {
  data = {};
  output = ".editorconfig";
  engine = request: let
    inherit (request) data output;
    name = l.baseNameOf output;
    value = {
      globalSection = {root = data.root or true;};
      sections = l.removeAttrs data ["root"];
    };
  in
    nixpkgs.writeText name (l.generators.toINIWithGlobalSection {} value);
  packages = [nixpkgs.editorconfig-checker];
}

githubsettings

Syncs repository settings defined in .github/settings.yml to GitHub, enabling Pull Requests for repository settings.

In order to use this, you also need to install Github Settings App. Please see the App’s Homepage for the configuration schema.

---

Definition:

{
  data = {};
  output = ".github/settings.yml";
  format = "yaml";
  hook.mode = "copy"; # let the Github Settings action pick it up outside of devshell
}

just

Just is a general purpose command runner with syntax inspired by make.

Tasks are configured via an attribute set where the name is the name of the task (i.e. just <task>) and the value is the task definition (see below for an example). The generated Justfile should be committed to allow non-Nix users to on-ramp without needing access to Nix.

Task dependencies (i.e. treefmt below) should be included in packages and will automatically be picked up in the devshell.

{ inputs, cell }:
let
  inherit (inputs) nixpkgs;
  inherit (inputs.std) lib;
in
{

  default = lib.dev.mkShell {
    /* ... */
    nixago = [
      (lib.cfg.just {
        packages = [ nixpkgs.treefmt ];
        data = {
          tasks = {
            fmt = {
              description = "Formats all changed source files";
              content = ''
                treefmt $(git diff --name-only --cached)
              '';
            };
          };
        };
      })
    ];
  };
}

It’s also possible to override the interpreter for a task:

{
# ...
  hello = {
    description = "Prints hello world";
    interpreter = nixpkgs.python3;
    content = ''
      print("Hello, world!")
    '';
  };
}
# ...

---

Definition:

let
  inherit (inputs) nixpkgs;
  l = nixpkgs.lib // builtins;
in {
  data = {};
  apply = d: let
    # Transforms interpreter attribute if present
    # nixpkgs.pkgname -> nixpkgs.pkgname + '/bin/<name>'
    getExe = x: "${l.getBin x}/bin/${x.meta.mainProgram or (l.getName x)}";
    final =
      d
      // {
        tasks =
          l.mapAttrs
          (n: v:
            v // l.optionalAttrs (v ? interpreter) {interpreter = getExe v.interpreter;})
          d.tasks;
      };
  in {
    data = final; # CUE expects structure to be wrapped with "data"
  };
  format = "text";
  output = "Justfile";
  packages = [nixpkgs.just];
  hook = {
    mode = "copy";
  };
  engine = inputs.nixago.engines.cue {
    files = [./just.cue];
    flags = {
      expression = "rendered";
      out = "text";
    };
    postHook = ''
      ${l.getExe nixpkgs.just} --unstable --fmt -f $out
    '';
  };
}

lefthook

Lefthook is a fast (parallel execution) and elegant git hook manager.

---

Definition:

let
  inherit (inputs) nixpkgs;
  lib = nixpkgs.lib // builtins;

  mkScript = stage:
    nixpkgs.writeScript "lefthook-${stage}" ''
      #!${nixpkgs.runtimeShell}
      [ "$LEFTHOOK" == "0" ] || ${lib.getExe nixpkgs.lefthook} run "${stage}" "$@"
    '';

  toStagesConfig = config:
    lib.removeAttrs config [
      "colors"
      "extends"
      "skip_output"
      "source_dir"
      "source_dir_local"
    ];
in {
  data = {};
  format = "yaml";
  output = "lefthook.yml";
  packages = [nixpkgs.lefthook];
  # Add an extra hook for adding required stages whenever the file changes
  hook.extra = config:
    lib.pipe config [
      toStagesConfig
      lib.attrNames
      (lib.map (stage: ''ln -sf "${mkScript stage}" ".git/hooks/${stage}"''))
      (stages:
        lib.optional (stages != []) "mkdir -p .git/hooks"
        ++ stages)
      (lib.concatStringsSep "\n")
    ];
}

mdbook

Write clean docs for humans with mdbook.

This version comes preset with this gem to make any Solution Architect extra happy: mdbook-kroki-preprocessor

---

Definition:

let
  inherit (inputs) nixpkgs;
in {
  data = {};
  output = "book.toml";
  format = "toml";
  hook.extra = d: let
    sentinel = "nixago-auto-created: mdbook-build-folder";
    file = ".gitignore";
    str = ''
      # ${sentinel}
      ${d.build.build-dir or "book"}/**
    '';
  in ''
    # Configure gitignore
    create() {
      echo -n "${str}" > "${file}"
    }
    append() {
      echo -en "\n${str}" >> "${file}"
    }
    if ! test -f "${file}"; then
      create
    elif ! grep -qF "${sentinel}" "${file}"; then
      append
    fi
  '';
  commands = [{package = nixpkgs.mdbook;}];
}

treefmt

A code-tree formatter to fromat the entire code tree extremly fast (in parallel and with a smart cache).

---

Definition:

let
  inherit (inputs) nixpkgs;
in {
  data = {};
  output = "treefmt.toml";
  format = "toml";
  commands = [{package = nixpkgs.treefmt;}];
}