feat(cli): opt-in framework packages, .agents scaffolding, and fork-local templates

[maxiar]

Three opt-in additions to the fsh CLI, aimed at running several products off one kernel.
Check Open Discussion: #1373

The default path does not move. fsh new MyApp produces exactly what it produced before — every new behaviour sits behind a template symbol that defaults to false and a CLI flag that is off. A new template-smoke.yml job proves it, and the existing two jobs are untouched.

1. Scaffolding from your own fork

fsh new accepted whatever FSH template happened to be installed and never upgraded it (EnsureTemplateInstalledAsync short-circuits on any match), installing FullStackHero.NET.StarterKit with a bare package id — no version, no source. A contributor working on a fork had no way to scaffold from their own branch.

fsh new MyApp --template-path ~/dev/dotnet-starter-kit   # checkout, .nupkg, or folder of nupkgs
fsh new MyApp --template-version 10.0.1-rc.2
fsh new MyApp --template-source https://my-feed/index.json
fsh new MyApp --refresh-template

Each has an env-var fallback (FSH_TEMPLATE_PATH, …). Overriding also uninstalls the previous template first — two packages sharing the identity FullStackHero.NET.StarterKit make dotnet new fail with Sequence contains more than one matching element.

2. Shipping the .agents kit

.agents/ was excluded twice — the pack pathspec in templates/FullStackHero.NET.StarterKit.csproj and template.json — while AGENTS.md was in neither exclude list. Every scaffolded project therefore shipped a guide whose entire rules index pointed at files that were never copied.

--agents now ships .agents/ (43 files) plus AGENTS.md, CLAUDE.md, GEMINI.md. Without it, AGENTS.md is correctly withheld too, closing the dangling reference in the current default output.

3. BuildingBlocks as FSH.Framework.* packages

fsh framework pack --push --clear-cache            # build the 11 packages into a local feed
fsh new MyApp --framework-packages                 # scaffold against them
fsh framework swap --to source|packages            # convert an existing project either way
fsh framework list / clean-cache
fsh self install                                   # build the CLI from source as the global `fsh`

src/Directory.Build.targets (new) rewrites any ProjectReference into BuildingBlocks as the matching PackageReference, so all 33 project files are byte-identical in both modes and new modules get it for free. It keys off src/BuildingBlocks being absent — which is exactly the shape a package-mode scaffold has — so it cannot drift from how the project was created. -p:UseFrameworkPackages=true|false forces either way.

Two decisions worth reviewing

Packages carry an embedded PDB with embedded sources, not a .snupkg. A folder feed does not serve symbol packages — only the NuGet.org symbol server does — so a .snupkg cannot give step-into debugging locally. Embedding puts the PDB and the sources inside the DLL, so F11 works offline with no source checkout. The public profile (--profile public) keeps the conventional .snupkg + SourceLink for real feeds.

swap --to source regenerates the kernel from the template rather than copying it from a kit clone. The template rewrites tokens inside BuildingBlocks, and not all are cosmetic — MultitenancyConstants.Issuer is derived from the project name. A raw copy would silently install the starter kit's own JWT issuer into someone else's project. The command scaffolds a throwaway copy under the target project's name and lifts the kernel from that. Verified: swapping FS.Proxy yields Issuer = "fs-proxy", not "mukesh.murugan".

Pre-existing bugs fixed along the way

• FullStackHero.CLI has never shipped a .snupkg. Directory.Build.props declares "Reproducible, debuggable packages for the projects that DO ship (CLI)" behind Condition="'$(IsPackable)' == 'true'" — but that file is imported before the csproj sets IsPackable, and MSBuild evaluates properties in document order, so IncludeSymbols stayed empty and SymbolPackageFormat fell back to the SDK default. Moved to Directory.Build.targets, where the value is final. The CLI now packs a real .snupkg.
• ProcessRunner.CaptureAsync redirected stderr without draining it — a latent deadlock for any child that fills the pipe buffer.
• fsh doctor failed any SDK not starting with "10.", despite the message promising ".NET 10+".
• The update check compared against AssemblyVersion, pinned to 10.0.0.0 in the csproj, so a 10.0.1 build nagged about upgrading to itself.
• Failures were unreadable. new printed "Scaffolding failed" while discarding the dotnet new output that explained why, and unknown options were silently dropped into Spectre's remaining-args bag rather than rejected — a mistyped flag quietly produced the wrong project. Strict parsing is now on; --agents/--framework-packages accept both the bare flag and an explicit true/false.

Verification

• Generated project (no BuildingBlocks, packages from a local feed): dotnet build -warnaserror → 0 warnings, 0 errors
• Default scaffold unchanged and builds clean; .agents/NuGet.config/README-CLI.md correctly absent
• Restored FSH.Framework.Core.dll carries the embedded PDB (32,256 vs 15,360 bytes)
• Both pack profiles correct back-to-back with no clean — this needs a forced non-incremental build, since a profile switch changes only compiler switches and MSBuild would otherwise ship the previous profile's binary
• swap round-trip on three projects (born-in-packages, born-in-source, and a fresh example), each direction building clean; idempotent, guarded outside a project
• Repo builds; 55 architecture + 301 unit tests pass
• New smoke job simulated locally end-to-end

Not included

Golden rule 10: this is user-facing, so the separate docs repo (github.com/fullstackhero/docs) and a src/content/docs/changelog/ entry still need updating. README-CLI.md is written to port into it.

Note for upstreaming

src/Directory.Build.props documents source ownership as the distribution model, and backend.yml records that per-module packs were removed once for contradicting it. This does not reverse that: source ownership stays the default and framework packaging is opt-in. If proposed upstream, items 1 and 2 are uncontroversial and should go first as separate PRs; item 3 is the one that needs the conversation.

🤖 Generated with Claude Code

[maxiar]

Pushed three more commits (37 → 42 files). They close a gap the original PR left open: it added a way to create a project on framework packages, but no way to bring an existing one forward.

fsh upgrade — updates an already-generated project to a newer template. It is a three-way merge, not a re-scaffold: the pristine scaffold commit fsh new created is the common ancestor, a freshly generated scaffold of the same project is the new state, and git merges them forward. Local work is preserved and genuine collisions surface as ordinary conflicts. It runs in a temporary worktree, so the caller's checkout is untouched until they merge, and it recovers the original scaffold options from the shape of the baseline tree rather than asking for them again.

A bug fix in the feature this PR already shipped. Two BuildingBlocksIndependenceTests read the BuildingBlocks .csproj files from disk. A project scaffolded with --framework-packages has no src/BuildingBlocks at all, so those tests threw from the moment such a project was created. They now carry [KernelSourceOnlyFact] and skip in package mode; the assembly-level checks in the same class still run, since those assemblies come from the packages. This mirrors the PostgresOnlyFact pattern rather than using Assert.Skip, which needs xUnit v3.

Docs — an end-to-end upgrade runbook. Worth calling out because the non-obvious part is that fsh upgrade moves only the owned source; on a framework-packages project the kernel arrives through the feed. Upgrading is three steps, and doing only the merge leaves a project that will not compile.

Exercised on a real project

Not a synthetic test: a ~100-commit application on framework packages, upgraded to a template revision that touched 145 files. Result was one conflict, in DbMigrator/Program.cs — exactly where a registered module and the template both edit the same file. Both directions build with -warnaserror, 0 warnings.

Heads-up on CI

This branch will fail to build on NU1902 until #1375 merges — Microsoft.SourceLink.GitHub 8.0.0 pulls Microsoft.Build.Tasks.Git 8.0.0, which has picked up an advisory since this PR was opened. That is unrelated to anything here; it currently fails main too. With that one-line bump applied locally, this branch builds clean and Architecture.Tests pass 55/55.

🤖 Generated with Claude Code

[maxiar]

Pushed one more commit: the Data Protection application name is now read from configuration instead of being a constant in BuildingBlocks.

It belongs in this PR rather than as a standalone fix, because on main today there is no bug — the template renames FSH.Starter when scaffolding, so every project gets its own value. The problem appears only once the framework also ships as the compiled FSH.Framework.* packages this PR introduces, since token substitution cannot reach a literal inside a DLL. Verified in the published binaries:

fsh.framework.caching → contains "FSH.Starter"
fsh.framework.shared  → contains "mukesh.murugan"

Data Protection isolates keys by the application name, so every project built on those packages shared one key ring — two of them pointed at the same Redis could decrypt each other's auth cookies and password-reset tokens. The root tenant's issuer leaked the same way.

Both now come from appsettings.json, which is scaffolded source and is renamed per project in both distribution modes. The constants remain as last-resort defaults, and the application name falls back to the entry assembly name rather than a shared literal — so a host that forgot the setting gets its own key ring instead of silently joining someone else's.

Related: #1376 builds on this to add a database-backed key store, and depends on this PR for DataProtectionApplicationName.