docs: provide an expanded example of generating a Justfile

[montchr]

Since I started using it a few months ago, I've become a big fan of just, offloading quite a few occasionally-used scripts or shortcuts from devshell commands into a Justfile. Its overall strict and functional-ish syntax is extremely rewarding for writing resilient simple tasks.

But I haven't used Standard's tooling for creating just tasks much at all, since it didn't seem very clear how to make use of all the syntax/features supported by just. That's not an accusation of documentation lacking in either project, but more of an acknowledgement that generating Justfiles via JSON via Nix seems like unexplored territory (from my perspective, anyway). So this "issue" is more of a feature request for expanded explorations of the potential benefits and drawbacks to using Nix->JSON->Justfile generation.

Basically: explore whether using Nix for this purpose saves time and effort in writing and understanding just tasks, or whether its abstraction increase the mental overhead, where writing a Justfile might instead be the less-complex approach?

Sample Example

Here's a single task from my Justfile:

# <- Rebuild a host and push any new derivations to the binary cache
system subcommand *ARGS='':
  {{sys-cmd}} {{subcommand}} \
    {{ARGS}} --flake "{{prj-root}}" --verbose
  @echo {{msg-done}}

And its dependencies:

msg-done := icon-ok + " Done"
prj-root := env_var('PRJ_ROOT')
sys-cmd := if os() == "linux" {
  "nixos-rebuild"
} else if os() == "macos" {
  "darwin-rebuild"
} else { "nix build" }

And here's the generated JSON for that task via just --unstable --dump --dump-format=json | jq . (probably invalid syntax since it's only a snippet from the full output, but it should give some idea):

    "switch": {
      "attributes": [],
      "body": [],
      "dependencies": [
        {
          "arguments": [
            "switch",
            [
              "variable",
              "ARGS"
            ]
          ],
          "recipe": "system"
        }
      ],
      "doc": "<- Rebuild the system and switch to the next generation",
      "name": "switch",
      "parameters": [
        {
          "default": "",
          "export": false,
          "kind": "star",
          "name": "ARGS"
        }
      ],
      "priors": 1,
      "private": false,
      "quiet": false,
      "shebang": false
    },
    "system": {
      "attributes": [],
      "body": [
        [
          [
            [
              "variable",
              "sys-cmd"
            ]
          ],
          " ",
          [
            [
              "variable",
              "subcommand"
            ]
          ],
          " \\"
        ],
        [
          "  ",
          [
            [
              "variable",
              "ARGS"
            ]
          ],
          " --flake \"",
          [
            [
              "variable",
              "prj-root"
            ]
          ],
          "\" --verbose"
        ],
        [
          "@echo ",
          [
            [
              "variable",
              "msg-done"
            ]
          ]
        ]
      ],
      "dependencies": [],
      "doc": "<- Rebuild a host and push any new derivations to the binary cache",
      "name": "system",
      "parameters": [
        {
          "default": null,
          "export": false,
          "kind": "singular",
          "name": "subcommand"
        },
        {
          "default": "",
          "export": false,
          "kind": "star",
          "name": "ARGS"
        }
      ],
      "priors": 0,
      "private": false,
      "quiet": false,
      "shebang": false
    },

[montchr]

I see, so the Justfile is generated via the CUE template provided by Nixago Extensions:

https://github.com/nix-community/nixago-extensions/blob/e5380cb0456f4ea3c86cf94e3039eb856bf07d0b/extensions/just/templates/default.cue

Which is probably a good thing considering that the JSON dump from Just is pretty verbose.

Judging by the template, it looks like one could define arguments to the task by overloading the attribute name. Which in the case of my example task might end up looking something like:

"system subcommand *ARGS=''" = ''
  {{sys-cmd}} {{subcommand}} \
    {{ARGS}} --flake "{{prj-root}}" --verbose
  @echo {{msg-done}}
'';

If that is the case, the Nix approach does not seem to offer much additional benefit without further adjustment to the CUE template.