Publish TimePro CLI as a NuGet .NET tool

Bắt đầu với src/SSW.TimePro.Cli/SSW.TimePro.Cli.csproj, Program.cs và README.md để hiểu metadata gói hiện có, đầu ra phiên bản và hướng dẫn cài đặt. Chạy hai project kiểm thử được nêu tên và các lệnh dotnet pack và cài đặt local tool được ghi trong tài liệu, sau đó kiểm tra package đã tạo. Được xem là hoàn tất khi metadata, nguồn phiên bản, tài liệu runtime, quy trình cài đặt/cập nhật local và workflow phát hành GitHub Actions được kích hoạt bởi tag hoặc release đều đáp ứng các tiêu chí nghiệm thu.

Summary

Publish the TimePro CLI package to NuGet.org as a .NET tool so users can install and update tp directly, without cloning the repository and packing a local .nupkg first.

Why

The current install path works, but it is developer-heavy:

git clone https://github.com/SSWConsulting/timepro.tools.git
cd timepro.tools
dotnet pack src/SSW.TimePro.Cli/ -o src/SSW.TimePro.Cli/nupkg
dotnet tool install -g --add-source src/SSW.TimePro.Cli/nupkg SSW.TimePro.Cli

Publishing to NuGet would make the install experience much cleaner:

dotnet tool install -g SSW.TimePro.Cli

And updates become:

dotnet tool update -g SSW.TimePro.Cli

This helps because:

• New users do not need to clone, build, or understand local NuGet sources.
• Existing users can update with the standard .NET tool workflow.
• Agent setup becomes easier because instructions can depend on one stable install command.
• Releases become traceable and repeatable through CI rather than local hand-built packages.
• NuGet.org gives the package a discoverable public install surface.

Current state

The project is already mostly set up as a .NET tool in src/SSW.TimePro.Cli/SSW.TimePro.Cli.csproj:

<PackAsTool>true</PackAsTool>
<ToolCommandName>tp</ToolCommandName>
<PackageId>SSW.TimePro.Cli</PackageId>
<Version>0.1.0</Version>
<Authors>SSW</Authors>
<Description>CLI-first tool with MCP support for managing SSW TimePro timesheets</Description>
<PackageLicenseExpression>MIT</PackageLicenseExpression>

Local verification on 2026-06-17:

dotnet pack src/SSW.TimePro.Cli/SSW.TimePro.Cli.csproj -c Release -o /tmp/timepro-tool-pack-test
dotnet tool install SSW.TimePro.Cli --tool-path /tmp/timepro-tool-install-test --add-source /tmp/timepro-tool-pack-test --version 0.1.0
/tmp/timepro-tool-install-test/tp --help

Result: package builds, installs, and tp --help works.

Tests also passed locally:

dotnet test tests/SSW.TimePro.Cli.Tests/SSW.TimePro.Cli.Tests.csproj --no-restore
dotnet test tests/SSW.TimePro.Cli.Integration/SSW.TimePro.Cli.Integration.csproj --no-restore

Result: 8 unit tests passed, 41 integration tests passed.

NuGet.org status checked on 2026-06-17:

• dotnet tool search SSW.TimePro.Cli returned no results.
• https://api.nuget.org/v3-flatcontainer/ssw.timepro.cli/index.json returned 404.

That suggests the package ID is currently available, but NuGet.org will still be the final authority at publish time.

Scope

This issue is only about making the existing CLI installable and updateable as a NuGet-hosted .NET tool.

Do not include unrelated package upgrades or broad runtime modernization here unless they are strictly required to make packaging, installation, or publishing work.

What needs to change

1. Add NuGet package metadata

The current package works, but the generated .nupkg is bare and dotnet pack warns that it has no package readme.

Add metadata such as:

<PackageReadmeFile>README.md</PackageReadmeFile>
<PackageProjectUrl>https://github.com/SSWConsulting/timepro.tools</PackageProjectUrl>
<RepositoryUrl>https://github.com/SSWConsulting/timepro.tools.git</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PackageTags>timepro;timesheets;cli;mcp;dotnet-tool</PackageTags>
<PackageReleaseNotes>Initial NuGet tool release.</PackageReleaseNotes>

Include the root README in the package from the project file:

<ItemGroup>
  <None Include="../../README.md" Pack="true" PackagePath="\" />
</ItemGroup>

Optional but nice:

• Add PackageIcon if we have a small approved icon asset.
• Add Source Link/package provenance later if needed.

2. Use one source of truth for the version

tp --version currently comes from a hardcoded value in Program.cs:

config.SetApplicationVersion("0.1.0");

That should read from assembly/package metadata instead, so release bumps do not drift between CLI output and NuGet package version.

3. Document the runtime requirement

The package currently targets net10.0, so users need a compatible .NET 10 runtime/SDK.

Document that clearly in the README and release notes. Investigating a lower target framework can be a separate issue if needed.

4. Add CI release workflow

Add a GitHub Actions workflow that:

1. Runs on tags such as v* or on GitHub Releases.
2. Restores NuGet packages.
3. Runs unit and integration tests.
4. Packs the tool in Release mode.
5. Publishes the .nupkg to NuGet.org.

Preferred publishing auth:

• Use NuGet.org Trusted Publishing with GitHub Actions OIDC if available.
• Fallback: use a scoped NuGet API key stored as a GitHub Actions secret.
• Do not commit API keys or write them to repo files.

Trusted Publishing shape:

permissions:
  id-token: write

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-dotnet@v4
    with:
      dotnet-version: '10.0.x'
  - run: dotnet restore SSW.TimePro.Timesheets.Cli.slnx
  - run: dotnet test SSW.TimePro.Timesheets.Cli.slnx -c Release --no-restore
  - run: dotnet pack src/SSW.TimePro.Cli/SSW.TimePro.Cli.csproj -c Release -o artifacts/packages --no-restore
  - uses: NuGet/login@v1
    id: login
    with:
      user: ${{ secrets.NUGET_USER }}
  - run: dotnet nuget push "artifacts/packages/*.nupkg" --api-key ${{ steps.login.outputs.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate

If Trusted Publishing is not available, use NUGET_API_KEY as a GitHub secret and keep it scoped to this package.

Test plan

Before publishing:

dotnet restore SSW.TimePro.Timesheets.Cli.slnx
dotnet test tests/SSW.TimePro.Cli.Tests/SSW.TimePro.Cli.Tests.csproj --no-restore
dotnet test tests/SSW.TimePro.Cli.Integration/SSW.TimePro.Cli.Integration.csproj --no-restore
dotnet pack src/SSW.TimePro.Cli/SSW.TimePro.Cli.csproj -c Release -o /tmp/timepro-tool-pack-test --no-restore

Inspect the package contents and manifest:

unzip -l /tmp/timepro-tool-pack-test/SSW.TimePro.Cli.*.nupkg
unzip -p /tmp/timepro-tool-pack-test/SSW.TimePro.Cli.*.nupkg SSW.TimePro.Cli.nuspec
unzip -p /tmp/timepro-tool-pack-test/SSW.TimePro.Cli.*.nupkg tools/net10.0/any/DotnetToolSettings.xml

Verify a clean local install from the generated package:

rm -rf /tmp/timepro-tool-install-test
dotnet tool install SSW.TimePro.Cli \
  --tool-path /tmp/timepro-tool-install-test \
  --add-source /tmp/timepro-tool-pack-test \
  --version <VERSION> \
  --ignore-failed-sources
/tmp/timepro-tool-install-test/tp --help
/tmp/timepro-tool-install-test/tp --version

Verify the global install/update flow in a controlled way before publishing by using a prerelease or incremented local version:

dotnet tool uninstall -g SSW.TimePro.Cli || true
dotnet tool install -g SSW.TimePro.Cli --add-source /tmp/timepro-tool-pack-test --version <VERSION> --ignore-failed-sources
tp --help
tp --version
dotnet tool update -g SSW.TimePro.Cli --add-source /tmp/timepro-tool-pack-test --version <NEXT_VERSION> --ignore-failed-sources
tp --version
dotnet tool uninstall -g SSW.TimePro.Cli

After publishing to NuGet.org, verify the real user path from NuGet.org only:

dotnet tool install -g SSW.TimePro.Cli --version <VERSION>
tp --help
tp --version
dotnet tool update -g SSW.TimePro.Cli
dotnet tool uninstall -g SSW.TimePro.Cli

Acceptance criteria

• Package metadata is complete enough for NuGet.org: README, project URL, repository URL, tags, license.
• tp --version comes from assembly/package metadata, not a second hardcoded version string.
• README install instructions use the NuGet install path as the primary path.
• README clearly documents the .NET runtime/SDK requirement.
• Local package install works from a generated .nupkg in a clean tool path.
• Local global install and update paths are tested with generated packages before publishing.
• GitHub Actions builds, tests, packs, and publishes the package from a tag/release.
• The first published package can be installed from NuGet.org with:

dotnet tool install -g SSW.TimePro.Cli

• A previously installed package can be updated from NuGet.org with:

dotnet tool update -g SSW.TimePro.Cli

References

• https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools-how-to-create
• https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-push
• https://learn.microsoft.com/en-us/nuget/nuget-org/publish-a-package
• https://learn.microsoft.com/en-us/nuget/reference/msbuild-targets
• https://learn.microsoft.com/en-us/nuget/nuget-org/trusted-publishing