eric/nix-flake-lib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update template

Browse Source
This commit is contained in:
eric
2026-03-21 01:52:22 +01:00
parent 3b38bc8f38
commit 4565a71863
5 changed files with 302 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
skills/repo-lib-consumer/SKILL.md
View File

@@ -1,48 +1,54 @@
---
name: repo-lib-consumer
description: Edit or extend repos that consume `repo-lib` through `repo-lib.lib.mkRepo`, `mkDevShell`, or `mkRelease`. Use when Codex needs to add or change tools, shell packages, checks or test phases, formatters, release steps, release channels, bootstrap hooks, or release automation in a Nix flake built on repo-lib.
description: Edit or extend repos that consume `repo-lib` through `repo-lib.lib.mkRepo`, `repo-lib.lib.mkRelease`, or a template generated from this library. Use when Codex needs to add or change tools, shell banner or bootstrap behavior, shell packages, checks, raw lefthook config, formatters, release steps, version metadata, release channels, or release automation in a Nix flake built on repo-lib.
---
# Repo Lib Consumer
Use this skill to make idiomatic changes in a repo that already depends on `repo-lib`.
Use this skill when changing a repo that already depends on `repo-lib`.
## Workflow
1. Detect the integration style.
Search for `repo-lib.lib.mkRepo`, `repo-lib.lib.mkDevShell`, `repo-lib.lib.mkRelease`, or `inputs.repo-lib`.
Search for `repo-lib.lib.mkRepo`, `repo-lib.lib.mkRelease`, or `inputs.repo-lib`.
2. Prefer the repo's current abstraction level.
If the repo already uses `mkRepo`, stay on `mkRepo`.
If the repo still uses `mkDevShell` or `mkRelease`, preserve that style unless the user asked to migrate.
If the repo uses `mkRepo`, keep edits inside `config` and `perSystem`.
If the repo uses `mkRelease` directly, preserve that style unless the user asked to migrate.
3. Load the right reference before editing.
Read `references/api.md` for exact option names, defaults, generated outputs, and limitations.
Read `references/recipes.md` for common edits such as adding a tool, adding a test phase, wiring release file updates, or handling webhooks.
Read `references/api.md` for exact option names, merge points, generated outputs, hook limitations, and release behavior.
Read `references/recipes.md` for concrete change patterns such as adding a tool, adding a check, wiring `commit-msg`, changing the banner, or updating release-managed files.
4. Follow repo-lib conventions.
Add bannered CLIs through `perSystem.tools`, not `shell.packages`.
Use `shell.packages` for packages that should be present in the shell but not shown in the banner.
Use `shell.packages` for packages that should exist in the shell but not in the banner.
Keep shells pure-first; only use `bootstrap` with `allowImpureBootstrap = true`.
Prefer structured `release.steps` over free-form shell when the task fits `writeFile` or `replace`.
Prefer `config.checks` for simple `pre-commit` and `pre-push` commands.
Use raw `config.lefthook` or `perSystem.lefthook` when the task needs `commit-msg` or extra lefthook fields.
Prefer structured `release.steps` over shell hooks; current step kinds are `writeFile`, `replace`, `versionMetaSet`, and `versionMetaUnset`.
5. Verify after edits.
Run `nix flake show --json`.
Run `nix flake check` when feasible.
If local flake evaluation cannot see newly created files because the repo is being loaded as a git flake, stage the new files before rerunning checks.
If local flake evaluation cannot see newly created files because the repo is loaded as a git flake, stage the new files before rerunning checks.
## Decision Rules
- Prefer `repo-lib.lib.tools.fromPackage` for tools with explicit metadata.
- Use `repo-lib.lib.tools.simple` only for very simple `--version` or `version` probes.
- Put pre-commit and pre-push automation in `checks`, not shell hooks.
- Treat `postVersion` as pre-tag and pre-push. It is not a true post-tag hook.
- For a webhook that must fire after the tag exists remotely, prefer CI triggered by tag push over local release command changes.
- Prefer `repo-lib.lib.tools.fromPackage` for packaged CLIs and `fromCommand` only when the tool should come from the host environment.
- Use `repo-lib.lib.tools.simple` only for very small package-backed probes that only need `version.args`.
- Required tools fail shell startup if their probe fails. Do not mark a tool optional unless that is intentional.
- `config.checks` supports only `pre-commit` and `pre-push`. `commit-msg` must go through raw lefthook config.
- Generated checks include `formatting-check`, `hook-check`, and `lefthook-check`.
- `config.shell.banner.style` must be `simple` or `pretty`.
- Treat `postVersion` as pre-format, pre-commit, pre-tag, and pre-push.
- Do not model a true post-tag webhook inside `repo-lib`; prefer CI triggered by tag push.
- The current generated `release` command is destructive and opinionated: it formats, stages, commits, tags, and pushes as part of the flow. Document that clearly when editing consumer release automation.
## References
- `references/api.md`
Use for the exact consumer API, option matrix, generated outputs, release ordering, and legacy compatibility.
Use for the exact consumer API, generated outputs, hook and banner behavior, and current release semantics.
- `references/recipes.md`
Use for concrete change patterns: add a tool, add a test phase, update release-managed files, or wire webhook behavior.
Use for common changes: add a tool, add a check, add a `commit-msg` hook, customize the shell banner, or update release-managed files.

4
skills/repo-lib-consumer/agents/openai.yaml
View File

@@ -1,4 +1,4 @@
interface:
display_name: "Repo Lib Consumer"
short_description: "Edit repos that use repo-lib safely"
default_prompt: "Use $repo-lib-consumer to update a repo that consumes repo-lib."
short_description: "Edit mkRepo or mkRelease consumers safely"
default_prompt: "Use $repo-lib-consumer to update a repo that consumes repo-lib through mkRepo, mkRelease, or the repo-lib template."

215
skills/repo-lib-consumer/references/api.md
View File

@@ -5,7 +5,6 @@
Look for one of these patterns in the consuming repo:
- `repo-lib.lib.mkRepo`
- `repo-lib.lib.mkDevShell`
- `repo-lib.lib.mkRelease`
- `inputs.repo-lib`
@@ -27,6 +26,7 @@ repo-lib.lib.mkRepo {
extraShellText = "";
allowImpureBootstrap = false;
bootstrap = "";
banner = { };
};
formatting = {
@@ -54,12 +54,35 @@ repo-lib.lib.mkRepo {
Generated outputs:
- `devShells.${system}.default`
- `checks.${system}.formatting-check`
- `checks.${system}.hook-check`
- `checks.${system}.lefthook-check`
- `formatter.${system}`
- `packages.${system}.release` when `config.release != null`
- merged `packages` and `apps` from `perSystem`
Merge points:
- `config.checks` merges with `perSystem.checks`
- `config.lefthook` recursively merges with `perSystem.lefthook`
- `config.shell` recursively merges with `perSystem.shell`
- generated release packages merge with `perSystem.packages`
Conflicts on `checks`, `packages`, and `apps` names throw.
## `config.includeStandardPackages`
Default: `true`
When enabled, the shell includes:
- `nixfmt`
- `gitlint`
- `gitleaks`
- `shfmt`
Use `false` only when the consumer explicitly wants to own the full shell package list.
## `config.shell`
Fields:
@@ -71,13 +94,38 @@ Fields:
- `bootstrap`
Shell snippet that runs before the banner.
- `allowImpureBootstrap`
Must be `true` if `bootstrap` is non-empty.
Must be `true` when `bootstrap` is non-empty.
- `banner`
Shell banner configuration.
Rules:
- Default is pure-first.
- Do not add bootstrap work unless the user actually wants imperative setup.
- Use `bootstrap` for unavoidable local setup only.
- Do not add bootstrap work unless the user actually wants imperative local setup.
- The template uses bootstrap intentionally for Bun global install paths and Moon bootstrapping; do not generalize that into normal package setup unless the repo already wants that behavior.
### `config.shell.banner`
Defaults:
```nix
{
style = "simple";
icon = "🚀";
title = "Dev shell ready";
titleColor = "GREEN";
subtitle = "";
subtitleColor = "GRAY";
borderColor = "BLUE";
}
```
Rules:
- `style` must be `simple` or `pretty`.
- `borderColor` matters only for `pretty`.
- Tool rows can also set `banner.color`, `banner.icon`, and `banner.iconColor`.
- Required tool probe failures abort shell startup.
## `config.formatting`
@@ -91,7 +139,7 @@ Fields:
Rules:
- `nixfmt` is always enabled.
- Use formatter settings instead of ad hoc shell formatting logic.
- Use formatter settings instead of shell hooks for formatting behavior.
## Checks
@@ -99,10 +147,10 @@ Rules:
```nix
{
command = "go test ./...";
command = "bun test";
stage = "pre-push"; # or "pre-commit"
passFilenames = false;
runtimeInputs = [ pkgs.go ];
runtimeInputs = [ pkgs.bun ];
}
```
@@ -114,37 +162,53 @@ Defaults:
Rules:
- Only `pre-commit` and `pre-push` are supported.
- The command is wrapped as a script and connected into `lefthook.nix`.
- `pre-commit` and `pre-push` commands are configured to run in parallel.
- Only `pre-commit` and `pre-push` are supported here.
- The command is wrapped with `writeShellApplication`.
- `pre-commit` and `pre-push` stages are configured to run in parallel.
- `passFilenames = true` maps to `{staged_files}` for `pre-commit` and `{push_files}` for `pre-push`.
## Raw Lefthook config
Use `config.lefthook` or `perSystem.lefthook` for advanced Lefthook features that the built-in `checks` abstraction does not carry.
Use `config.lefthook` or `perSystem.lefthook` when the task needs advanced Lefthook features or unsupported stages.
Example:
Pass-through attrset example:
```nix
{
checks.tests = {
command = "go test ./...";
command = "bun test";
stage = "pre-push";
runtimeInputs = [ pkgs.bun ];
};
lefthook.pre-push.commands.tests.stage_fixed = true;
lefthook.commit-msg.commands.commitlint = {
run = "pnpm commitlint --edit {1}";
run = "bun commitlint --edit {1}";
stage_fixed = true;
};
}
```
Structured hook-entry example in a raw hook list:
```nix
perSystem = { pkgs, ... }: {
lefthook.biome = {
entry = "${pkgs.biome}/bin/biome check";
pass_filenames = true;
stages = [ "pre-commit" "pre-push" ];
};
};
```
Rules:
- These attrsets are passed through to `lefthook.nix`.
- They are merged after generated checks, so they can extend generated commands.
- Prefer `checks` for the simple common case and `lefthook` for advanced fields such as `stage_fixed`, `files`, `glob`, `exclude`, `jobs`, or `scripts`.
- `config.lefthook` and `perSystem.lefthook` are recursive attrset passthroughs merged after generated checks.
- Structured hook entries support only:
`description`, `enable`, `entry`, `name`, `package`, `pass_filenames`, `stages`
- `stages` may include `pre-commit`, `pre-push`, or `commit-msg`.
- `pass_filenames = true` maps to `{1}` for `commit-msg`.
## Tools
@@ -152,17 +216,19 @@ Preferred shape in `perSystem.tools`:
```nix
(repo-lib.lib.tools.fromPackage {
name = "Go";
package = pkgs.go;
exe = "go"; # optional
name = "Bun";
package = pkgs.bun;
version = {
args = [ "version" ];
args = [ "--version" ];
match = null;
regex = null;
group = 0;
line = 1;
};
banner = {
color = "CYAN";
color = "YELLOW";
icon = "";
iconColor = null;
};
required = true;
})
@@ -174,7 +240,10 @@ For a tool that should come from the host `PATH` instead of `nixpkgs`:
(repo-lib.lib.tools.fromCommand {
name = "Nix";
command = "nix";
version.args = [ "--version" ];
version = {
args = [ "--version" ];
group = 1;
};
})
```
@@ -186,10 +255,11 @@ repo-lib.lib.tools.simple "Go" pkgs.go [ "version" ]
Tool behavior:
- Tool packages are added to the shell automatically.
- Package-backed tools are added to the shell automatically.
- Command-backed tools are probed from the existing `PATH` and are not added to the shell automatically.
- Banner probing uses absolute executable paths.
- Banner probing uses the resolved executable path.
- `required = true` by default.
- When `version.match` is set, the first matching output line is selected before `regex` extraction.
- Required tool probe failure aborts shell startup.
Use `shell.packages` instead of `tools` when:
@@ -246,73 +316,66 @@ Set `release = null` to disable the generated release package.
}
```
### `run`
### `versionMetaSet`
```nix
{
run = {
script = ''
curl -fsS https://example.invalid/hook \
-H 'content-type: application/json' \
-d '{"tag":"'"$FULL_TAG"'"}'
'';
runtimeInputs = [ pkgs.curl ];
versionMetaSet = {
key = "desktop_binary_version_max";
value = "$FULL_VERSION";
};
}
```
Also accepted for compatibility:
### `versionMetaUnset`
- `{ run = ''...''; }`
- legacy `mkRelease { release = [ { file = ...; content = ...; } ... ]; }`
```nix
{
versionMetaUnset = {
key = "desktop_unused";
};
}
```
Rules:
- Current supported step kinds are only `writeFile`, `replace`, `versionMetaSet`, and `versionMetaUnset`.
- Do not document or implement a `run` step in consumer repos unless the library itself gains that feature.
## Release ordering
The generated `release` command does this:
The generated `release` command currently does this:
1. Update `VERSION`
2. Run `release.steps`
3. Run `postVersion`
4. Run `nix fmt`
5. `git add -A`
6. Commit
7. Tag
8. Push branch
9. Push tags
1. Require a clean git worktree
2. Update `VERSION`
3. Run `release.steps`
4. Run `postVersion`
5. Run `nix fmt`
6. `git add -A`
7. Commit with `chore(release): <tag>`
8. Tag
9. Push branch
10. Push tags
Important consequence:
Important consequences:
- `postVersion` is still before commit, tag, and push.
- `postVersion` is before formatting, commit, tag, and push.
- There is no true post-tag or post-push hook in current `repo-lib`.
- The current release runner is opinionated and performs commit, tag, and push as part of the flow.
## Post-tag webhook limitation
## `mkRelease`
If the user asks for a webhook after the tag exists remotely:
`repo-lib.lib.mkRelease` remains available when a repo wants only the release package:
- Prefer CI triggered by pushed tags in the consuming repo.
- Do not claim `postVersion` is post-tag; it is not.
- Only extend `repo-lib` itself if the user explicitly wants a new library capability.
```nix
repo-lib.lib.mkRelease {
system = system;
nixpkgsInput = nixpkgs; # optional
channels = [ "alpha" "beta" "rc" "internal" ];
steps = [ ];
postVersion = "";
runtimeInputs = [ ];
}
```
## Legacy API summary
`mkDevShell` still supports:
- `extraPackages`
- `preToolHook`
- `extraShellHook`
- `lefthook`
- `additionalHooks`
- old `tools = [ { name; bin; versionCmd; color; } ]`
- `features.oxfmt`
- `formatters`
- `formatterSettings`
`mkRelease` still supports:
- `release = [ ... ]` as legacy alias for `steps`
- `extraRuntimeInputs` as legacy alias merged into `runtimeInputs`
When a repo already uses these APIs:
- preserve them unless the user asked to migrate
- do not mix old and new styles accidentally in the same call
Use the same release-step rules as `config.release`.

142
skills/repo-lib-consumer/references/recipes.md
View File

@@ -7,18 +7,22 @@ Edit `perSystem.tools` in the consuming repo:
```nix
tools = [
(repo-lib.lib.tools.fromPackage {
name = "Go";
package = pkgs.go;
version.args = [ "version" ];
banner.color = "CYAN";
name = "Bun";
package = pkgs.bun;
version.args = [ "--version" ];
banner = {
color = "YELLOW";
icon = "";
};
})
];
```
Notes:
- Do not also add `pkgs.go` to `shell.packages`; `tools` already adds it.
- Use `exe = "name"` only when the package exposes multiple binaries or the main program is not the desired one.
- Do not also add the same package to `shell.packages`; `tools` already adds package-backed tools to the shell.
- Use `exe = "name"` only when the package exposes multiple binaries or the default binary is not the right one.
- Use `fromCommand` when the executable should come from the host environment instead of `nixpkgs`.
## Add a non-banner package to the shell
@@ -37,16 +41,38 @@ Use this for:
- internal scripts
- the generated `release` package itself
## Add a test phase or lint hook
## Customize the shell banner
For a simple global check:
Use `config.shell.banner`:
```nix
config.checks.tests = {
command = "go test ./...";
config.shell.banner = {
style = "pretty";
icon = "☾";
title = "Moonrepo shell ready";
titleColor = "GREEN";
subtitle = "Bun + TypeScript + Varlock";
subtitleColor = "GRAY";
borderColor = "BLUE";
};
```
Guidance:
- Use `style = "pretty"` when the repo already has a styled shell banner.
- Keep icons and colors consistent with the repo's current shell UX.
- Remember that required tool probe failures will still abort shell startup.
## Add a test phase or lint hook
For a simple shared check:
```nix
config.checks.typecheck = {
command = "bun run typecheck";
stage = "pre-push";
passFilenames = false;
runtimeInputs = [ pkgs.go ];
runtimeInputs = [ pkgs.bun ];
};
```
@@ -54,20 +80,44 @@ For a system-specific check:
```nix
perSystem = { pkgs, ... }: {
checks.lint = {
command = "bun test";
stage = "pre-push";
runtimeInputs = [ pkgs.bun ];
checks.format = {
command = "oxfmt --check .";
stage = "pre-commit";
passFilenames = false;
runtimeInputs = [ pkgs.oxfmt ];
};
};
```
Guidance:
- Use `pre-commit` for fast format/lint work.
- Use `pre-commit` for fast format or lint work.
- Use `pre-push` for slower test suites.
- Prefer `runtimeInputs` over inline absolute paths when the command needs extra CLIs.
## Add a `commit-msg` hook
`config.checks` cannot target `commit-msg`. Use raw Lefthook config:
```nix
config.lefthook.commit-msg.commands.gitlint = {
run = "${pkgs.gitlint}/bin/gitlint --staged --msg-filename {1}";
stage_fixed = true;
};
```
Or use a structured hook entry:
```nix
perSystem = { pkgs, ... }: {
lefthook.commitlint = {
entry = "${pkgs.nodejs}/bin/node scripts/commitlint.mjs";
pass_filenames = true;
stages = [ "commit-msg" ];
};
};
```
## Add or change formatters
Use `config.formatting`:
@@ -76,11 +126,12 @@ Use `config.formatting`:
config.formatting = {
programs = {
shfmt.enable = true;
gofmt.enable = true;
oxfmt.enable = true;
};
settings = {
shfmt.options = [ "-i" "2" "-s" "-w" ];
oxfmt.excludes = [ "*.md" "*.yml" ];
};
};
```
@@ -116,31 +167,27 @@ config.release.steps = [
];
```
## Add a webhook during release
If the webhook may run before commit and tag creation, use a `run` step or `postVersion`.
Use a `run` step when it belongs with other release mutations:
Update metadata inside `VERSION`:
```nix
config.release = {
runtimeInputs = [ pkgs.curl ];
steps = [
config.release.steps = [
{
run = {
script = ''
curl -fsS https://example.invalid/release-hook \
-H 'content-type: application/json' \
-d '{"version":"'"$FULL_VERSION"'"}'
'';
runtimeInputs = [ pkgs.curl ];
versionMetaSet = {
key = "desktop_binary_version_max";
value = "$FULL_VERSION";
};
}
{
versionMetaUnset = {
key = "desktop_unused";
};
}
];
};
```
Use `postVersion` when the action should happen after all `steps`:
## Add a webhook during release
Current `repo-lib` does not expose a `run` release step. If the action must happen during local release execution, put it in `postVersion`:
```nix
config.release.postVersion = ''
@@ -153,8 +200,8 @@ config.release.runtimeInputs = [ pkgs.curl ];
Important:
- Both of these still run before commit, tag, and push.
- They are not true post-tag hooks.
- `postVersion` still runs before `nix fmt`, commit, tag, and push.
- This is not a true post-tag hook.
## Add a true post-tag webhook
@@ -162,11 +209,11 @@ Do not fake this with `postVersion`.
Preferred approach in the consuming repo:
1. Keep local release generation in `repo-lib`.
2. Add CI triggered by tag push.
3. Put the webhook call in CI, where the tag is already created and pushed.
1. Keep local version generation in `repo-lib`.
2. Trigger CI from tag push.
3. Put the webhook call in CI, where the tag already exists remotely.
Only change `repo-lib` itself if the user explicitly asks for a new local post-tag capability.
Only change `repo-lib` itself if the user explicitly asks for a new library capability.
## Add impure bootstrap work
@@ -175,8 +222,9 @@ Only do this when the user actually wants imperative shell setup:
```nix
config.shell = {
bootstrap = ''
export GOBIN="$PWD/.tools/bin"
export PATH="$GOBIN:$PATH"
export BUN_INSTALL_GLOBAL_DIR="$PWD/.tools/bun/install/global"
export BUN_INSTALL_BIN="$PWD/.tools/bun/bin"
export PATH="$BUN_INSTALL_BIN:$PATH"
'';
allowImpureBootstrap = true;
};
@@ -184,14 +232,14 @@ config.shell = {
Do not add bootstrap work for normal Nix-packaged tools.
## Migrate a legacy consumer to `mkRepo`
## Move from direct `mkRelease` to `mkRepo`
Only do this if requested.
Migration outline:
1. Move repeated shell/check/formatter config into `config`.
2. Move old banner tools into `perSystem.tools`.
3. Move extra shell packages into `perSystem.shell.packages`.
4. Replace old `mkRelease { release = [ ... ]; }` with `config.release.steps`.
1. Move release package config into `config.release`.
2. Move shell setup into `config.shell` and `perSystem.shell.packages`.
3. Move bannered CLIs into `perSystem.tools`.
4. Move hook commands into `config.checks` or raw `lefthook`.
5. Keep behavior the same first; do not redesign the repo in the same change unless asked.

15
template/flake.nix
View File

@@ -109,29 +109,31 @@
})
];
shell.packages = [
shell = {
packages = [
self.packages.${system}.release
pkgs.bun
pkgs.openbao
pkgs.oxfmt
pkgs.oxlint
];
};
checks.format = {
checks = {
format = {
command = "oxfmt --check .";
stage = "pre-commit";
passFilenames = false;
runtimeInputs = [ pkgs.oxfmt ];
};
checks.typecheck = {
typecheck = {
command = "bun run typecheck";
stage = "pre-push";
passFilenames = false;
runtimeInputs = [ pkgs.bun ];
};
checks.env-check = {
env-check = {
command = "bun run env:check";
stage = "pre-push";
passFilenames = false;
@@ -141,7 +143,7 @@
];
};
checks.env-scan = {
env-scan = {
command = "bun run env:scan";
stage = "pre-commit";
passFilenames = false;
@@ -152,4 +154,5 @@
};
};
};
};
}