diff --git a/.editorconfig b/.editorconfig index 79a1aa4..089d986 100644 --- a/.editorconfig +++ b/.editorconfig @@ -15,8 +15,8 @@ csharp_prefer_braces = true:suggestion # Naming and language conventions here reflect this project's own style; they # do not by themselves enforce the "no unsolicited comments" / "English by -# default" rules in AGENTS.md / CLAUDE.md, which apply to any human or AI -# contributor regardless of what an analyzer can mechanically check. +# default" rules in CLAUDE.md, which apply to any human or AI contributor +# regardless of what an analyzer can mechanically check. [*.{csproj,json,yml,yaml}] indent_style = space diff --git a/.template.config/template.json b/.template.config/template.json index df4da7c..2cc349c 100644 --- a/.template.config/template.json +++ b/.template.config/template.json @@ -31,6 +31,12 @@ "datatype": "bool", "description": "If set, skips running 'dotnet restore' automatically after creating the project.", "defaultValue": "false" + }, + "skipGit": { + "type": "parameter", + "datatype": "bool", + "description": "If set, skips printing the reminder to initialize a git repository.", + "defaultValue": "false" } }, "primaryOutputs": [ @@ -45,6 +51,15 @@ ], "actionId": "210D431B-A78B-4D2F-B762-4ED3E3EA9025", "continueOnError": true + }, + { + "condition": "(!skipGit)", + "description": "This project is not a git repository yet.", + "manualInstructions": [ + { "text": "Run 'git init && git add -A && git commit -m \"Initial commit\"'" } + ], + "actionId": "AC1156F7-BB77-4DB8-B28F-24EEBCCA1E5C", + "continueOnError": true } ] } diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 6b5dad1..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,69 +0,0 @@ -# AGENTS.md - -This repo is the source of a `dotnet new` template (shortName `labapi-plugin`) that -scaffolds SCP: Secret Laboratory LabAPI plugins. This file follows the -editor/vendor-agnostic [agents.md](https://agents.md) convention for AI coding tools -other than Claude Code (Cursor, Codex, etc.). **`CLAUDE.md` is this repo's primary, -detailed instructions file** — read it first if your tooling can. What follows is the -condensed subset any agent needs, kept in sync with `CLAUDE.md`. - -## This is template source, not a plugin - -This section applies only while `.template.config/` is present next to this file — -i.e. you're editing the template repo itself, not a plugin already generated from it. - -`.template.config/template.json` makes the dotnet templating engine do a **literal, -repo-wide string replacement** at generation time (not semantic renaming): this -folder's own name (`sourceName`) becomes whatever project name a consumer picks, the -placeholder author name in `EntryPoint.cs` becomes their `--PluginAuthor`, and the -LabAPI version pinned in the `.csproj`/`EntryPoint.cs` becomes their -`--LabApiVersion`. See `template.json` for the exact current literals — don't repeat -them verbatim in prose here, since this file ships inside every generated project and -an exact match would get silently rewritten too. Don't introduce an exact match of -one of those literals elsewhere in the repo unless you mean for it to be substituted; -add a new `template.json` symbol instead of hardcoding a magic string. `EntryPoint`/ -`Config` (the class names) are intentionally **not** substituted — only the namespace -tracks the project name. - -## Never invent LabAPI API surface - -Don't assume a LabAPI class/namespace/method/property/attribute exists. Verify it -against the restored `Northwood.LabAPI` package (`LabApi.dll`/`LabApi.xml` under -`%userprofile%\.nuget\packages\northwood.labapi\\lib\net48\`) or -https://github.com/northwood-studios/LabAPI first. If you can't verify a member, -say so instead of guessing. - -## Toolchain choices — don't change without being asked - -`TargetFramework` is `netstandard2.1` on purpose (LabAPI itself only ships -`net48`/`net481`), chosen so the plugin still loads under the game's Mono/.NET -Framework 4.8 host. `LangVersion` is pinned to `14.0`. The `.csproj` suppresses -exactly `NU1701` (scoped to the `Northwood.LabAPI` `PackageReference`) and `MSB3270` -(via `ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch=None`) because of that -netstandard2.1/net48-only-package combination — don't broaden either into a blanket -suppression or remove them. - -## Code style and language - -No `//`, `/* */`, or `///` comments unless the user explicitly asks for them in that -request; don't add comments restating self-explanatory code — `EntryPoint.cs`/ -`Config.cs` are already comment-free, follow the same standard for new files. All -text embedded in code (log/console messages, exceptions, config descriptions, -user-facing strings) defaults to English — e.g. `Logger.Info("Plugin initialized -successfully")` — except identifiers the user requested (project name, namespace, -class/method/property/variable names), which are never translated, and text the user -explicitly asks to be in another language. - -## Verifying a change - -No automated tests exist. Verify by generating a real project and building it: - -```bash -dotnet new uninstall . && dotnet new install . -dotnet new labapi-plugin -n VerifyPlugin -o ../_verify/VerifyPlugin -cd ../_verify/VerifyPlugin && dotnet build -``` - -Expect `Build succeeded. 0 Warning(s) 0 Error(s)`. See `CLAUDE.md` for the full -verification notes (cache invalidation after editing `template.json`, Windows cleanup -caveats). diff --git a/CLAUDE.md b/CLAUDE.md index 0375e7a..1a446f0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,9 +2,7 @@ This repo **is** a `dotnet new` project template (identity `SCPSL.LabApi.PluginTemplate`, shortName `labapi-plugin`), not a runnable plugin. It scaffolds SCP: Secret Laboratory -LabAPI plugins. `AGENTS.md` carries a shorter, tool-agnostic version of the essentials -for non-Claude agents; this file is the authoritative one — keep both in sync when a -rule below changes. +LabAPI plugins. The next section only applies while you're editing **this template repository** (i.e. a `.template.config/` folder is present next to this file). It does not apply @@ -15,8 +13,8 @@ are ordinary project files at that point, not template scaffolding. ## Repo is template *source* — read before touching any file `.template.config/template.json` sets this folder's name as the template's -`sourceName` and defines two text-replacement `symbols` (plus a third, `skipRestore`, -that only toggles the post-generation `dotnet restore` and replaces no text). The +`sourceName` and defines two text-replacement `symbols` (plus `skipRestore` and +`skipGit`, which only toggle post-generation actions and replace no text). The dotnet templating engine does a literal, repo-wide **string replacement** at generation time — not semantic renaming — driven by that config: @@ -46,19 +44,44 @@ Consequences: ## Repo layout (only what affects decisions) -- `.template.config/template.json` — template identity, the 3 symbols above, - `primaryOutputs` (points at the project file using its pre-substitution literal - name — that's correct and expected, not a bug), and a `postActions` restore step - (the standard dotnet-templating "restore NuGet packages" action, id - `210D431B-...`; skipped in Visual Studio, which restores on its own). +- `.template.config/template.json` — template identity, the symbols above plus + `skipGit` (a display-only toggle, see below), `primaryOutputs` (points at the + project file using its pre-substitution literal name — that's correct and expected, + not a bug), and two `postActions`: the standard dotnet-templating "restore NuGet + packages" action (id `210D431B-...`; skipped in Visual Studio, which restores on + its own) and a "display manual instructions" action (id `AC1156F7-...`) that prints + a reminder to run `git init` — see "Git on generation" below for why it's just a + printed reminder and not an executed command. - The `.csproj` at the repo root — the project file every generated plugin ships with. - `EntryPoint.cs` / `Config.cs` — the scaffolded plugin (`Plugin`) and its YAML-backed settings class. - `.editorconfig` — formatting/naming only (indentation, brace style). It does **not** enforce the comment/language rules below — those aren't analyzer-checkable. -- No `.sln`, no test project, no CI, no packaging (`.nupkg`) project, no git repo, and - no GitHub Copilot instructions file currently exist in this folder. Don't assume - any of them. +- No `.sln`, no test project, no CI, no packaging (`.nupkg`) project, no GitHub + Copilot instructions file currently exist in this folder. Don't assume any of them. + This repo itself does have its own git history (see `git log`) — that's unrelated + to whether a *generated* project gets one, which is what "Git on generation" below + covers. + +## Git on generation — why there's no automated `git init` + +A generated project is **not** a git repository by default; a `postAction` only +prints a reminder to run `git init && git add -A && git commit -m "Initial commit"`. +This was a deliberate choice after testing the alternative: + +- `dotnet new`'s only postAction capable of running an arbitrary process is the + "Run script" action (id `3A7C4B45-...`). Actually wiring it to run `git init`/ + `git add`/`git commit` was tested and it **hangs forever** in any non-interactive + shell: the CLI's script-execution security gate demands an explicit `Y` typed at a + `Do you want to run this action [Y(yes)|N(no)]?` prompt, once per script action, + with no flag on this SDK to pre-approve it — unlike the NuGet-restore postAction, + which the CLI treats as trusted and never gates. Do not reintroduce "Run script" + postActions for this without re-verifying that gate no longer applies. +- Visual Studio's own "New Project" dialog already has a built-in "Create new Git + repository" checkbox that works for any template, including this one, with zero + template-side configuration — so VS users get this for free regardless. +- CLI users see the printed reminder above (governed by the `skipGit` symbol) and run + the one-liner themselves. ## LabAPI contract (verified against northwood-studios/LabAPI source, not guessed)