prelude-just

Prelude + Just

Justfile 始终是任务语义的规范来源；Prelude 在运行时导入它——绝不会将配方复制到 prelude.commands 中。将用户的请求视为规范，而不是要插入的 shell 文本。将每个配方绑定到项目实际使用的规范命令——工具所有者已经在使用的调用方式（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 导入标志不会启用菜单。如果缺少 shell 集成，请参阅 /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 → 独立条目，继承目标项的文档和分组
• mod ops 'ops.just' → 一个 x ops 行；按 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')] → 在详情窗格中显示一个示例行
• [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" 会将其保留为单个 shell 参数。原始的 {{…}} 插值会将文本插入 shell 源码；仅用引号括起来并不能确保任意值安全。优先使用导出的参数并通过带引号的 shell 展开来处理。

规则：

• 优先使用 [group]，而不是重命名——公开键保持为 x test。
• 参数属性可能会改变调用语义，且需要较新版本的 Just；尤其是 long/short 选项会改变位置参数的用法。除非任务要求修改，否则请保留现有调用形式。私有、分组和元数据属性会影响可见性或呈现方式，也需要已安装的 Just 版本提供支持。
• 没有默认值的参数为必填；在填写参数前，参数输入会拒绝空白提交。
• 修改范围应限于请求内容；切勿重命名配方——这会改变公开键。将配方移入模块会改变其调用路径（例如，x coder-e2e → x e2e coder，内部命令为 just e2e::coder）；仅在用户要求此类重组时才这样做，并更新所有展示旧调用方式的文档。

调度约定

x <recipe> [args…] 目前会用空格连接额外参数，并通过 sh -c 执行拼接后的命令。原始参数边界会丢失：调用方 shell 使用的引号无法保护包含多个单词的值，嵌入的元字符也可能变成 shell 语法。对于包含多个单词或不可信的值，请直接使用 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>')] 的方式同步示例调用，以便菜单详情窗格显示这些内容。

验证（不假定已有源码检出）

运行任何命令前先阅读配方：just 在文件加载时会求值反引号，因此即使是 --dry-run 也可能执行命令。然后，在 shell 中运行：

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。