casey / casey/just

Support hierarchical recipe groups for monorepo service commands

Open
#3,699 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
35.8k
Forks
846
Avg merge
27m
Merged PRs (30d)
3

Description

Recipe groups are currently flat. This becomes difficult to navigate in a microservice monorepo where each service can have several kinds of commands.

For example, an alert service may eventually have commands for:

- Starting the development server
- Running scheduled jobs
- Running one-time scripts
- Importing configuration
- Database maintenance
- Running service-specific tests

A flat `justfile` might contain recipes such as:

```just
[group("services")]
alert-dev:
...

[group("services")]
alert-check-stale-telemetry:
...

[group("services")]
alert-import-rules:
...

[group("services")]
telemetry-dev:
...

[group("services")]
telemetry-replay-packets:
...
```

As more services and commands are added, the `services` group becomes a long flat list. Recipe-name prefixes provide some organization, but the relationship between the service, command type, and command is not represented in `just --list`.

## Desired output

I would like `just --list` to support a hierarchy similar to:

```text
[services]
[alert-service]
[development]
dev

[jobs]
check-stale-telemetry

[scripts]
import-rules
validate-rules

[telemetry-service]
[development]
dev

[scripts]
replay-packets
```

This would make it easier to discover:

- Which commands belong to each service
- What kind of operation each command performs
- Which development, job, script, and maintenance commands are available

## Possible syntax

One possible syntax could be a group path:

```just
[group-path("services", "alert-service", "development")]
alert-dev:
...

[group-path("services", "alert-service", "jobs")]
alert-check-stale-telemetry:
...

[group-path("services", "alert-service", "scripts")]
alert-import-rules:
...
```

Another option could be a path-like group name:

```just
[group("services/alert-service/jobs")]
alert-check-stale-telemetry:
...
```

The exact syntax is less important than representing the hierarchy in `just --list`.

## Why existing flat groups are not enough

A recipe can be placed in multiple groups, but those groups are displayed independently. They do not represent a parent-child relationship.

For example:

```just
[group("services")]
[group("alert-service")]
alert-dev:
...
```

This lists the same recipe under two separate flat groups instead of showing `alert-service` under `services`.

## Relation to modules

Modules support nested command invocation and are useful for splitting commands into separate `justfile`.

This request is specifically about hierarchical organization and discovery in the recipe-list output. It would be useful when maintainers want to keep a central `justfile` or organize commands through metadata without requiring every service and command category to become a separate module.

If nested modules already provide the intended solution, improved documentation or an option to render all module commands as a complete tree in `just --list` could also address this use case.

## Example use case

Consider a growing Python microservice monorepo:

```text
services/
alert/
telemetry/
command/
```

Each service can eventually have:

- Development server commands
- Background jobs
- Scheduled tasks
- One-time scripts
- Maintenance operations
- Service-specific tests

Hierarchical groups would make the root command list easier to understand without relying on increasingly long recipe names.

Contributor guide

Open the contributing guide

Research direction

Start with the `just --list` output path and the existing recipe-group and module behavior. Compare how flat groups and nested modules are represented, then define a tree-shaped listing that preserves the requested parent-child relationships; done means hierarchical service and command categories are discoverable in `just --list`.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.