The `paisano` TUI / CLI

The Paisano TUI / CLI is a brandable general purpose command line kit for Flake based projects which fulfill a Paisano layout and importer contract.

Usage

Install Paisano: nix profile install github:paisano-nix/tui
Set up autocompletion (optional): paisano _carapace [SHELL] — see carapace docs
Enter a Paisano-based repository.
Run paisano or paisano list and profit ✨!

Branding

To change the branding of this binary you can set these variables via -X compile flag:

main.buildVersion | default: dev
main.buildCommit  | default: dirty
main.argv0        | default: paisano
main.project      | default: Paisano
flake.registry    | default: __std   # temp kept, mainly for `std-action`

Example: go build -o my-bin-name -ldflags="-X main.argv0=hive -X main.project=Hive"

Contributing

Enter Contribution Environment

direnv allow

Change Contribution Environment

$EDITOR ./nix/repo/config.nix
direnv reload

Preview Documentation

_{You need to be inside the Contribution Environment.}

mdbook build -o

Motivation

Problem

A Paisano-based repository has a well-defined folder structure.

That folder structure is parsed and transformed by Paisano into flake outputs.

However, as a project grows, and so does the number of outputs, it becomes increasingly hard to discover all of them easily.

When it already becomes complicated to find stuff for Nix experts, it is even more difficult for a user who is not deeply familiar with Nix.

Hence, as a project grows, we face unsolved problems of discoverability.

Solution

We could, of course, write a readme and detail all outputs and bespoke ways of how to interact with them.

But we all know a readme's flaws:

people tend to not read it, especially as it grows larger
it tends to become outdated, coincidentally also as it grows larger

Better Solution

To solve this discoverability problem while never becoming outdated, this tool renders all Paisano-based flake outputs into an easily browsable and searchable terminal user interface. A variety of actions offer the user pre-defined and discoverable ways to interact with these outputs based on their types.

Once the user knows what she's looking for, she can choose to access her intended target action directly by using this tool as a CLI.

Intended Audience

End user

End users of this tool can supercharge any Paisano-based project with discoverability.

However, if a framework-specific branded version is available, that should be used instead.

Framework creator

This repository implements a white-label version of the Paisano repository companion.

Downstream frameworks, such as Standard or Hive can re-brand this tool to offer a seamless and branded experience to their users.

Please refer to the readme on how to re-brand.

Reference

Cell: `tui`

No documentation

Block: `app`

`paisano` CLI / TUI

❯ paisano --help
paisano is the CLI / TUI companion for Paisano.

- Invoke without any arguments to start the TUI.
- Invoke with a target spec and action to run a known target's action directly.

Enable autocompletion via 'paisano _carapace <shell>'.
For more instructions, see: https://rsteube.github.io/carapace/carapace/gen/hiddenSubcommand.html

Usage:
  paisano //[cell]/[block]/[target]:[action] [args...]
  paisano [command]

Available Commands:
  check       Validate the repository.
  list        List available targets.
  re-cache    Refresh the CLI cache.

Flags:
      --for string   system, for which the target will be built (e.g. 'x86_64-linux')
  -h, --help         help for paisano
  -v, --version      version for paisano

Use "paisano [command] --help" for more information about a command.

How To: Rebrand using Nix

Example taken from Standard.

let
  version = "0.15.0+dev";

  inherit (inputs) nixpkgs;
  inherit (nixpkgs.lib) licenses;
in {
  default = cell.cli.std;

  std = nixpkgs.buildGoModule rec {
    inherit version;
    pname = "std";
    meta = {
      inherit (import (inputs.self + /flake.nix)) description;
      license = licenses.unlicense;
      homepage = "https://github.com/divnix/std";
    };

    src = inputs.paisano-tui.sourceInfo + /src;

    vendorHash = "sha256-1le14dcr2b8TDUNdhIFbZGX3khQoCcEZRH86eqlZaQE=";

    nativeBuildInputs = [nixpkgs.installShellFiles];

    postInstall = ''
      mv $out/bin/paisano $out/bin/${pname}

      installShellCompletion --cmd std \
        --bash <($out/bin/std _carapace bash) \
        --fish <($out/bin/std _carapace fish) \
        --zsh <($out/bin/std _carapace zsh)
    '';

    ldflags = [
      "-s"
      "-w"
      "-X main.buildVersion=${version}"
      "-X main.argv0=${pname}"
      "-X main.project=Standard"
      "-X flake.registry=__std"
    ];
  };
}

Paisano TUI Book