diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 000000000..77834a53a --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,51 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "statusLine": { + "type": "command", + "command": "pwsh -NoProfile -Command '$input | & (Get-ChildItem $HOME/.claude/plugins/cache/myfoodbag/mfb-statusline/*/statusline-command.ps1 | Select-Object -Last 1)'" + }, + "enabledPlugins": { + "mfb-statusline@myfoodbag": true + }, + "permissions": { + "allow": [ + "Bash(dotnet build:*)", + "Bash(dotnet test:*)", + "Bash(dotnet restore:*)", + "Bash(dotnet pack:*)", + "Bash(dotnet --info)", + "Bash(dotnet --version)", + "Bash(dotnet list:*)", + "Bash(./build.ps1:*)", + "Bash(./build.sh:*)", + "Bash(./build.cmd:*)", + "Bash(pwsh ./build.ps1:*)", + "Bash(git status)", + "Bash(git status:*)", + "Bash(git diff:*)", + "Bash(git log:*)", + "Bash(git show:*)", + "Bash(git branch:*)", + "Bash(git remote -v)", + "Bash(git rev-parse:*)", + "Bash(git ls-files:*)", + "Bash(git config --get:*)", + "Bash(gh pr list:*)", + "Bash(gh pr view:*)", + "Bash(gh pr diff:*)", + "Bash(gh issue list:*)", + "Bash(gh issue view:*)", + "Bash(gh run list:*)", + "Bash(gh run view:*)", + "Bash(gh workflow list:*)", + "Bash(gh api:*)" + ], + "deny": [ + "Bash(git push --force:*)", + "Bash(git push -f:*)", + "Bash(git reset --hard:*)", + "Bash(git clean -f:*)", + "Bash(rm -rf:*)" + ] + } +} diff --git a/.gitignore b/.gitignore index e070853bb..99b948e9a 100644 --- a/.gitignore +++ b/.gitignore @@ -56,3 +56,7 @@ _dotTrace* # Tests *.received.txt + +# Claude Code — local-only files (shared settings.json IS committed) +.claude/settings.local.json +.claude/.credentials* diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..435bdff01 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,94 @@ +# CLAUDE.md + +Guidance for Claude Code (and other AI assistants) when working in this repo. + +## What this project is + +[NUKE](https://nuke.build) — a build automation system for C#/.NET. The build is itself a C# console app (`build/_build.csproj`), so any change to the framework can be dogfooded by running `./build.ps1` (Windows) or `./build.sh`. + +Originally a single-maintainer project ([matkoch](https://github.com/matkoch)); now under new maintenance. The codebase is mature, large, and has long-standing conventions — prefer matching existing patterns over introducing new ones. + +## Stack + +- .NET SDK pinned in `global.json` (currently `10.0.100`, `rollForward: latestMinor`). +- Central package versions in `Directory.Packages.props` — never add a `Version=` to an individual `PackageReference`. +- xUnit + FluentAssertions + Verify.Xunit for tests. +- Solution file is `nuke-common.slnx` (new XML solution format, not `.sln`). + +## Solution layout + +Source projects live under `source/`. The high-level grouping: + +| Area | Projects | +|---|---| +| Core framework | `Nuke.Common`, `Nuke.Build`, `Nuke.Build.Shared`, `Nuke.Components`, `Nuke.Tooling` | +| Code generation | `Nuke.SourceGenerators`, `Nuke.Tooling.Generator` | +| Models | `Nuke.ProjectModel`, `Nuke.SolutionModel` | +| Tooling | `Nuke.GlobalTool`, `Nuke.MSBuildTasks` | +| Utilities | `Nuke.Utilities`, `Nuke.Utilities.IO.Compression`, `Nuke.Utilities.IO.Globbing`, `Nuke.Utilities.Net`, `Nuke.Utilities.Text.Json`, `Nuke.Utilities.Text.Yaml` | +| Tests | Each project has a sibling `*.Tests` project | + +The build itself lives under `build/` (the `Build.*.cs` partial files split targets by concern: `Build.CI.GitHubActions.cs`, `Build.Licenses.cs`, etc.). + +Tool wrappers (the `.json` schemas Claude is most likely asked to extend) live under `source/Nuke.Common/Tools//.json`. + +## Common commands + +```powershell +# Build the build +./build.ps1 # default target = Pack +./build.ps1 Compile +./build.ps1 Test +./build.ps1 GenerateTools # regenerate tool wrappers from JSON +./build.ps1 --help # list all targets and parameters + +# Or via dotnet directly when iterating on a single project +dotnet build nuke-common.slnx +dotnet test source/Nuke.Common.Tests/Nuke.Common.Tests.csproj +``` + +Do not commit code generated by `GenerateTools` — per `CONTRIBUTING.md`, generated code is regenerated manually once per release. + +## Branching & releases + +GitFlow: +- `develop` — integration branch, base for all PRs +- `release/*` — release stabilization +- `master` — published releases (publishes to public NuGet) +- `hotfix/*` — patches against `master` + +Alpha packages flow to the Feedz feed (`https://f.feedz.io/nuke/alpha/nuget`) from `develop` via the GitHub Actions `AlphaDeployment` workflow. Public NuGet publishes happen from `master`/`release/*` via AppVeyor. + +Versioning is driven by GitVersion (`GitVersion.yml`). + +## Conventions worth respecting + +- **Centralized package versions** — add new packages to `Directory.Packages.props`, never inline. +- **Tool wrappers**: copy/paste from neighbours; cover full commands; use ``, ``, `
    `/`
      `, ``, `` in `help`; don't write `secret: false` or `default: xxx`. +- **Tests next to code**: every `Foo` project has a `Foo.Tests` project. Mirror the namespace. +- **Coding style**: enforced via `.editorconfig` + ReSharper settings (`*.DotSettings`). Don't fight the formatter. +- **Telemetry opt-out is set in test runs** (`NUKE_TELEMETRY_OPTOUT=true`). Keep it that way. +- **License header**: every source file starts with the `// Copyright … Maintainers of NUKE.` block — copy from a neighbouring file when adding new ones. + +## What not to do + +- Don't add `secret`/`default` defaults to tool JSON files (see CONTRIBUTING.md). +- Don't introduce a new test framework or assertion library — stay on xUnit + FluentAssertions + Verify. +- Don't commit `output/`, `external/`, or any `bin/`/`obj/` directory. +- Don't commit `nuke-global.sln` or other `nuke-global.*` files — they're generated by `GenerateGlobalSolution`. +- Don't bypass `Directory.Packages.props` or `Directory.Build.targets`. +- Don't rewrite Matt's prior conventions wholesale — discuss in an issue first. + +## When asked to add a tool wrapper + +1. Find the closest existing tool under `source/Nuke.Common/Tools//.json`. +2. Copy its shape; cover a full command with all arguments. +3. Run `./build.ps1 GenerateTools` to verify it generates cleanly. +4. Do **not** commit the generated `.cs` output. + +## Useful pointers for AI assistants + +- The `build/Build.*.cs` files are the canonical example of how to consume NUKE — read these when reasoning about user-facing APIs. +- `Nuke.Common/Tools//.json` files are the source of truth for tool wrappers; the `.cs` next to them is generated. +- Source generators (`Nuke.SourceGenerators`) produce per-target code at compile time — if a symbol seems missing, check whether it's generated. +- The Verify snapshots (`*.verified.txt`) under test projects are the contract for generator output; review carefully when they change.