prelude-just

Prelude + Just

Justfile はタスクのセマンティクスを一元的に管理します。Prelude は実行時に Justfile をインポートします。レシピが prelude.commands にコピーされることはありません。ユーザーのリクエストを仕様として扱い、シェルテキストとして補間しないでください。すべてのレシピを、プロジェクトで実際に使用されている正式なコマンド（ツールの所有者がすでに使っている呼び出し。例：bun run test、go test ./...、nix flake check）に紐付け、記述する前にリポジトリ内に実在することを確認してください。プレースホルダーのスクリプトを作成してはいけません。

インポートを有効にする（一度だけ）

flake-parts モジュール（サイドカーの prelude.nix またはインライン設定）で、次のように設定します。

prelude.menu.enable = true;
prelude.menu.just.enable = true;
# prelude.menu.just.justfile = ./just/Justfile;  # pin; null = just's own discovery
# prelude.menu.just.group = "tasks";             # menu group for flat recipes

コンシューマーの devshell に config.packages.prelude-shell がある状態で両方のオプションを有効にすると、x と just が使えるようになります。Justfile のインポートフラグだけではメニューは有効になりません。シェル統合が見つからない場合は /prelude-install を参照してください。

属性のサポートは just のバージョンによって異なります（[metadata] は 1.42 以降、[arg(long/short)] は 1.46 以降、[arg(pattern)] は 1.45 以降、[arg(min/max)] は 1.56 以降）。インポート時にマッピングされるのは、コンシューマーのロック済み Prelude リビジョンが認識するフィールドだけです。属性を使用する前に just --version を確認し、ロック済みの prelude 入力でサポート状況を確認してください。既存の prelude.commands.<name> エントリーは、同名のレシピより常に優先されます。

インポートで解釈される Justfile のレシピ

メニューは just --dump --dump-format json を読み込みます。表示されるフィールドは次のとおりです。

• # doc comment → メニューの説明
• [group('ci')] → メニューのグループ。キーはフラットなままです（x check）
• alias ship := deploy → 独立した項目として表示され、対象の doc とグループを継承します
• mod ops 'ops.just' → x ops の行が1つ表示されます。Enter（または引数なしの x ops）でモジュールのレシピを一覧するサブコマンドピッカーが開きます。一方、レシピの呼び出しは親経由で公開されます（x ops migrate、または x ops <recipe> [args…]）。レシピは内部で正規のコマンド（just ops::migrate）を使って実行されます。インポートされたモジュールのレシピは、ダブルコロン形式のキー（x ops::migrate）では選択できません。モジュールを使うと、レシピごとにメニューに項目が追加されるのを避けられます。モジュールは親の Justfile の set 設定やレシピを継承しません。モジュールのレシピには、それぞれ独自のプライベートヘルパーが必要です（依存関係はモジュールの境界を越えられません）。
• モジュールのレシピに [group('ops')] を指定 → レシピはサブメニューから外れ、メニュー内ではそのグループのトップレベルに表示されます。一方、親経由で引き続き呼び出せます（x ops migrate）
• [private] または先頭の _ → メニューに表示されません（レシピとエイリアス）
• [metadata('just test --fix')] → 詳細ペインに「実行例」の項目が1つ表示されます
• [arg('package', long)] → 引数入力に --package オプションが表示されます
• [arg('dry', long, flag)] → 引数入力で切り替え可能なフラグが表示されます
• [arg('kind', pattern='staging|production')] → 選択可能なオプションが表示されます（単純なパイプ区切りの選択肢。[a-z-]+ のような正規表現は検証されますが、選択肢は表示されません）
• レシピ行にデフォルト値を指定（package="./..."）→ オプション引数に値があらかじめ入力されます

基本形 — 次のコマンドをプロジェクトで実際に使われているツールに合わせて調整してください。

# run the unit test suite
[group('ci')]
test:
    bun run test

# run go tests for one package
# (add [group('go')] if a go group is wanted)
[arg('package', help='import path, or ./... for all')]
test-go $package="./...":
    go test "$package"

# E2E suites grouped behind one menu row: `just e2e <suite>`
mod e2e 'e2e.just'

独自のプライベートヘルパーを含む e2e.just の例：

[private]
guard:
    @test -n "${IN_NIX_SHELL:-}"

# run the desktop e2e suite
[metadata('just e2e desktop main')]
[arg('revision', help='branch, commit, PR number or URL')]
desktop $revision="main": guard
    bun run desktop-test smoke "$revision"

$package はパラメーターをレシピの環境変数としてエクスポートします。"$package" は、シェル引数を1つとして渡します。生の {{…}} 補間はシェルソースにテキストを挿入するため、引用符で囲むだけでは任意の値を安全に扱えません。エクスポートしたパラメーターを、引用符で囲んだシェル展開とともに使うことを推奨します。

ルール：

• 名前の変更ではなく、[group] を優先してください。公開キーは x test のままです。
• 引数属性は呼び出しの仕様を変える場合があり、より新しい Just バージョンが必要です。特に long／short オプションは位置引数の使い方を変えます。タスクで変更が求められていない限り、既存の呼び出し形式を維持してください。private／group／metadata 属性は表示や見せ方に影響し、インストール済みの Just バージョンでのサポートも必要です。
• デフォルト値のないパラメーターは必須です。入力されるまで、引数入力では空欄のまま送信できません。
• 編集は依頼された範囲に限定し、レシピ名は変更しないでください。変更すると公開キーが変わります。レシピをモジュールに移すと呼び出しパスが変わります（例：x coder-e2e → x e2e coder、内部では just e2e::coder）。ユーザーがその再編成を依頼した場合に限り実施し、古い呼び出し方法を示しているドキュメントも更新してください。

ディスパッチの仕様

現在、x <recipe> [args…] は追加の引数をスペースで結合し、組み立てたコマンドを sh -c で実行します。元の引数の境界は失われます。呼び出し元のシェルで使った引用符は複数語の値を保護せず、含まれるメタ文字がシェル構文として扱われる可能性があります。複数語の値や信頼できない値には、direct just <recipe> "$value" を使い、レシピ自体でも安全なパラメーター処理を行ってください。x の引数転送で argv が保持されるとは説明しないでください。

パラメーターがある場合、引数なしの x <recipe> を実行すると、対話形式の引数入力が開きます。引数なしの x <module> を実行すると、モジュールのサブコマンドピッカーが開きます。モジュールのレシピは x <module> <recipe> [args…]（またはネストした x <parent> [submodule…] <recipe> [args…]）で呼び出され、内部では正規の just <module>::<recipe> コマンドが実行されます。エイリアスは x ship で呼び出されます。

ワークフローのドキュメント化

メニュー項目は、見つけやすくするためだけのものです。有用なワークフローのドキュメントには、前提条件、引数、実行例、効果、トラブルシューティングを記載してください。プロジェクトのドキュメントページまたは README に記述し（/prelude-docs を参照）、実行例となる呼び出しごとに [metadata('just <recipe> <example>')] の行を 1 つ追加して、メニューの詳細ペインにも表示されるようにしてください。

検証（ソースのチェックアウトを前提としない）

実行する前にレシピを読んでください。just はファイルの読み込み時にバッククォートを評価するため、--dry-run でもコマンドが実行される場合があります。そのうえで、シェル内で次を実行してください。

just --summary                  # new recipe listed
just --dump --dump-format json  # the exact payload the menu imports
x --list                        # module appears as one row; children indented
just --dry-run <recipe> [args…] # after inspection: prints lines without running them
x <recipe>                     # exercise a safe no-argument recipe

参考資料：Prelude インポートガイド — nix run github:darkmatter/prelude#skill -- guide command-conventions、just マニュアル — https://github.com/casey/just。 初期の flake 設定：/prelude-install。