#179 feat: add stable-only latest package policy

[stiwicourage]

Support string-based Package.Latest policies with never, stable, and
always, while keeping legacy boolean values temporarily compatible.

• make stable publish latest only for stable versions
• keep always behavior for stable and preview packages
• map legacy booleans to always/never with TODO markers for major-version removal
• update schema, tests, examples, and docs to use the new policy model
• deprecate boolean Package.Latest values in CHANGELOG

Summary

• Added policy-based Package.Latest handling so package generation can distinguish between stable-only and always-on latest aliases.
• This was needed so production consumers can keep using latest safely as the latest stable package, while preview consumers must opt in explicitly by selecting a versioned preview package.
• Closes Support stable-only latest package policy #179

Affected area

• nova CLI or command routing
• Public PowerShell cmdlet behavior
• Scaffolding or project.json handling
• Build, test, analyzer, coverage, or CI helper flow
• Package, raw upload, or package metadata workflow
• Publish, release, or GitHub Actions automation
• Self-update or notification preference behavior
• Contributor documentation (README.md, CONTRIBUTING.md, repository workflow docs)
• End-user docs (docs/*.html)
• Command help (docs/NovaModuleTools/en-US/*.md)
• src/resources/example/
• Dependency or manifest changes (project.json, workflow dependencies, release tooling)
• Security-sensitive change
• Documentation-only change
• Other

Review guidance

• Start with src/private/shared/GetNovaResolvedProjectPackageSettings.ps1 and src/private/package/GetNovaPackageMetadataList.ps1.
• Main files changed:
• src/private/shared/GetNovaResolvedProjectPackageSettings.ps1
• src/private/package/GetNovaPackageMetadataList.ps1
• src/resources/Schema-Build.json
• tests/PackageLatestPolicy.Tests.ps1
• tests/NovaCommandModel*.Tests.ps1
• tests/RemainingHelperCoverage*.ps1
• README.md
• docs/
• src/resources/example/
• Trade-offs / follow-up:
• Legacy boolean Package.Latest values are still accepted temporarily and mapped to policy values.
• A TODO marker was added where that compatibility layer lives so it can be removed in the next major version.
• Docs/examples now show only string policies, while the changelog records boolean deprecation.

Validation

• Invoke-NovaBuild
• Test-NovaBuild
• ./scripts/build/Invoke-ScriptAnalyzerCI.ps1
• ./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1
• Targeted Nova workflow validated (% nova build, % nova test, % nova merge, % nova deploy,
  % nova publish,
  % nova release, % nova update, % nova notification, or % nova init as relevant)
• Docs/example only; executable validation not needed

Validation notes:

Primary validation:

• pwsh -NoLogo -NoProfile -File ./run.ps1

run.ps1 executes:

• Invoke-NovaBuild
• ./scripts/build/Invoke-ScriptAnalyzerCI.ps1
• Test-NovaBuild

Result:

• PSScriptAnalyzer: no findings
• Pester: 683 passed, 0 failed, 0 skipped

Targeted regression coverage also added and exercised in:

• tests/PackageLatestPolicy.Tests.ps1

CodeScene:

• pre_commit_code_health_safeguard passed after moving new assertions into a dedicated test file to keep large legacy test files under the Code Health threshold.

Documentation and release follow-up

• README.md reviewed and updated if contributor workflow, architecture, CI, release, or automation changed
• CONTRIBUTING.md reviewed and updated if contribution expectations or review guidance changed
• CHANGELOG.md reviewed and updated if the change matters to users, maintainers, or contributors
• docs/NovaModuleTools/en-US/ help updated if a public command or CLI behavior changed
• docs/*.html updated if end-user workflows or examples changed
• src/resources/example/ reviewed and updated if the real-world project layout, package model, or upload workflow
  changed
• No documentation, changelog, or example updates were needed

Maintainability, compatibility, and risk

• Code Health / maintainability impact considered
• No breaking change
• Breaking change
• Security-sensitive change
• CI, workflow, or release-pipeline impact
• Dependency-review impact

Risk, rollout, or rollback notes:

Compatibility:

• No immediate breaking change.
• Existing boolean Package.Latest values still work:
  • true => "always"
  • false => "never"

Behavior change:

• Recommended config is now string-based:
  • "never"
  • "stable"
  • "always"
• With "stable", preview package runs no longer create/update .latest. artifacts.

Migration:

• Existing projects can keep working unchanged for now.
• Maintainers should move docs/examples/configs to string values.
• Boolean support is deprecated and documented in CHANGELOG for later major-version removal.

Rollback:

• Reverting this change restores the old boolean-only behavior where Latest=true always emits latest artifacts, including preview package runs.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codescene-delta-analysis]

Gates Passed
6 Quality Gates Passed

See analysis details in CodeScene

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[codescene-delta-analysis]

Code Coverage Gates Passed
Overall Coverage: 100.0% (required = 95%)
New & Changed Code Coverage: 100% (required = 99%)

Review details by gate

• Overall Coverage

  • Pass/Fail Reason:
    The overall coverage gate was checked for all code and meets the goal: 100.0% covered >= threshold = 95%
  • Action:
    You have 281 files with a sum of 2874 covered and 1 uncovered lines of code.

• New & Changed Code Coverage

  • Pass/Fail Reason:
    New or changed code meets coverage goal: 100% covered >= threshold = 99%
  • Action:
    You modified 2 files, and covered 24 added/modified lines of code.