Files
DSP_Mods/docs/ThunderstorePublishingPlan.md
T

16 KiB

Local Thunderstore Publishing Plan

Status: implemented as a local PowerShell script. No real package upload has been performed.

Goal and scope

Add a repository-root Publish-Mod.ps1 that builds, packages, and publishes one explicitly named mod to the Dyson Sphere Program community through tcli. Reuse the existing MSBuild packaging targets and upload their ZIP without rebuilding it through tcli. Keep credentials out of version control.

This proposal covers a local PowerShell command. It does not add a GitHub Actions workflow, change mod versions, upload dependencies, or publish packages during implementation checks.

Metadata source

Use the existing <Project>/package/manifest.json for package metadata. Read Team from the required -Namespace parameter and Package Name from the manifest's name field. Keep the manifest's existing schema; no additional package metadata file or Team field is needed.

Pass the supplied namespace to tcli as its package namespace. Require an explicit, non-empty value on every invocation, including -DryRun; do not default to soarqin or infer Team from other metadata. The service-account token must have permission to publish under the selected Team.

Publishing value Source and rule
Team / tcli package namespace Required -Namespace parameter; non-empty and preserving capitalization.
Package Name manifest.json.name, preserving capitalization.
Version Evaluated .csproj Version; ZipMod synchronizes manifest.json.version_number. Check the packaged value afterward.
Community Constant dyson-sphere-program.
Repository Constant https://thunderstore.io.
Category Explicitly empty tcli category configuration; preserve existing listing categories.
Package contents Existing ZipMod output, including its manifest, README, icon, DLLs, and optional changelog.

Command interface

# Publish using the caller directory's .env, or TCLI_AUTH_TOKEN if no file exists.
.\Publish-Mod.ps1 -Project UXAssist -Namespace soarqin

# Read the token from an explicitly selected file.
.\Publish-Mod.ps1 -Project Dustbin -Namespace soarqin -EnvFile "$env:USERPROFILE\.config\DSP_Mods\thunderstore.env"

# Build and inspect the package without uploading; a token is not required.
.\Publish-Mod.ps1 -Project UXAssist -Namespace soarqin -DryRun
Parameter Behavior
-Project <string> Required. Select one top-level project by directory name, such as UXAssist or Dustbin. Resolve paths from $PSScriptRoot, independently of the caller's current directory.
-Namespace <string> Required. Select the Thunderstore Team. Reject empty, whitespace-only, or invalid identifiers; preserve capitalization and use this value in tcli configuration and package-version lookups.
-EnvFile <path> Optional. Read TCLI_AUTH_TOKEN from an explicitly selected file. When omitted, use .env in the caller's current directory if present, otherwise use the process variable.
-DryRun Build, package, validate, and show the intended publish command and metadata. Skip token requirements, remote package checks, and tcli publication. This mode still writes normal build and package outputs.

Use Release configuration. Omit package-name, category, community, version-override, publish-all, and skip-build parameters from the initial interface. Selecting a preloader or helper project directly must fail with an actionable message identifying the main mod where applicable.

Target Windows PowerShell 5.1 and PowerShell 7. The existing packaging targets invoke powershell.exe, so this proposal does not promise cross-platform packaging.

Build and publish sequence

  1. Resolve the named project within the repository. Require <Project>/<Project>.csproj, package/manifest.json, package/icon.png, and README.md. Reject traversal, wildcard input, helpers, and projects with PackPreloaderTargetDir set. Validate -Namespace and the manifest's name before building.
  2. Evaluate Release MSBuild properties instead of guessing output paths or parsing only literal XML: Version, ProjectName, TargetPath, PackHasChangelog, PackUsePluginsLayout, and PackPreloaderTargetDir. Read evaluated ProjectReference items to find bundled preloaders. MSBuild 17.8 or newer provides the required -getProperty and -getItem JSON output.
  3. For a real publish, resolve the token before changing to the repository's build directory and check the pinned local tcli tool before the expensive build. For -DryRun, neither a token nor an installed tcli tool is required. Restore project NuGet assets when missing, then use --no-restore for packaging.
  4. For each referenced preloader whose evaluated PackPreloaderTargetDir belongs to the selected mod's package, run CopyToParentPackage in Release before packaging the main mod. This refreshes Dustbin's bundled preloader even if an old DLL already exists under package/patchers. Do not upload preloaders or referenced mods separately.
  5. Run dotnet build <Project>/<Project>.csproj -t:ZipMod -c Release --no-restore. Every native command must have its exit code checked; stop immediately on a nonzero result. Retain the existing warning policy.
  6. Select the exact ZIP path defined by the existing target: <Project>/package/<ProjectName>-<Version>.zip. Do not select the newest ZIP by timestamp or a wildcard. Read the ZIP and check its root manifest identity and version, required root files, 256x256 PNG icon, expected DLL layout, and optional changelog. Compare bundled main/preloader DLLs with the current evaluated build outputs. When a separate changelog is included, require its latest English and Chinese headings to match the project version. Do not change any version automatically.
  7. Write a generated, non-secret tcli configuration under <Project>/obj/thunderstore-publish/<run-id>/thunderstore.toml. Print the project, Team, Package Name, version, community, ZIP path, and category-preservation behavior. In -DryRun, stop successfully here and retain the ZIP for inspection.
  8. Before a real upload, query the exact package-version endpoint using the supplied namespace, manifest package name, and evaluated project version. If the version exists, stop without uploading. Treat only HTTP 404 as an absent version; authentication, network, server, and response-format errors must remain errors. Do not automatically increment versions or retry a publish with an uncertain result.
  9. Provide the token to the tcli child process and run dotnet tool run tcli -- publish --config-path <generated-config> --file <exact-zip>. Restore process environment and working directory in finally. Remove only this invocation's generated configuration directory after verifying its resolved path. Preserve the ZIP.
  10. Return success only after tcli reports successful publication. Show the package page and tcli's download URL. After a submission timeout or failure, explain how to inspect the exact version before retrying; a failed command does not prove that the server created no release.

For example, Dustbin's packaging commands are:

dotnet build DustbinPreloader/DustbinPreloader.csproj -t:CopyToParentPackage -c Release --no-restore
dotnet build Dustbin/Dustbin.csproj -t:ZipMod -c Release --no-restore

Only the selected mod is published. Existing dependency declarations remain authoritative; packaging a dependent mod does not publish UXAssist. Retired LabOpt is excluded from routine implementation checks.

Generated tcli configuration

Use a repository-local .NET tool manifest at .config/dotnet-tools.json and pin tcli to 0.2.4, the latest version currently available from NuGet. First-time setup is dotnet tool restore; do not silently install or update a global tcli. Recheck the available version when implementation begins, and change the pin only after checking the behavior below.

Example configuration for an existing UXAssist version:

[config]
schemaVersion = "0.0.1"

[package]
namespace = "soarqin"
name = "UXAssist"
versionNumber = "1.6.2"

[build]
outdir = "."

[publish]
repository = "https://thunderstore.io"
communities = ["dyson-sphere-program"]
categories = []

Generate namespace from -Namespace, name from package/manifest.json.name, and versionNumber from the evaluated project version. The values above illustrate -Project UXAssist -Namespace soarqin; they are not defaults. Validate permitted identifier/version characters before writing TOML, and pass command arguments as an array rather than composing executable PowerShell text. [build].outdir satisfies tcli's publish-time configuration validation; --file prevents tcli from building a second ZIP. The uploaded archive supplies the actual package description, dependencies, website, and other manifest content.

categories = [] is deliberate. In tcli 0.2.4, omitting the setting leaves example riskofrain2 categories from the configuration model. An empty array produces empty legacy categories and an empty per-community category map. The inspected Thunderstore server code only adds categories when the submitted list is non-empty, so an existing listing retains its current categories. Categories belong to the community listing, rather than an individual package version. A first release has no previous categories to inherit and starts without categories. No category lookup or local category cache is necessary.

Token handling

Use a Thunderstore Team service-account token through TCLI_AUTH_TOKEN. Select an explicit -EnvFile first, otherwise read .env in the caller's current directory if it exists, and finally fall back to the inherited process variable when no default file exists. Resolve this before changing directories. A missing explicit file or invalid token in a selected file is an error, not a reason to use another source. Do not add a token parameter or pass --token to tcli. Never write the token into TOML, the tool manifest, package metadata, a generated script, or a log.

The environment file contains one token assignment:

TCLI_AUTH_TOKEN=<service-account-token>

Read it as UTF-8 data. Support blank lines, full-line comments, and an optional matching pair of single or double quotes around the value. Reject duplicate token assignments, empty values, malformed lines, and unsupported keys. Do not evaluate PowerShell, expand variables, or execute the file. Do not print offending file contents in errors.

Allow local environment files inside or outside the checkout. Keep .env and .env.* ignored by Git so that a repository-local .env remains untracked. Use only synthetic tokens in implementation checks.

The pinned tcli version has a Windows-specific behavior: it reads the persisted User-scoped TCLI_AUTH_TOKEN before the process value. Before publication, compare that User-scoped value with the selected token without logging either value. If a different non-empty User value exists, stop and explain that the caller must remove or reconcile the stale setting. Do not change User or Machine environment variables automatically. Otherwise, temporarily set only the process variable immediately around tcli invocation and restore its original presence and value in finally.

Implementation work

  • Implement required -Project and -Namespace parameters. Read Package Name from the existing manifest and verify that it agrees with the archive manifest.
  • Add the pinned .config/dotnet-tools.json, the Publish-Mod.ps1 entry point, and environment-file ignore patterns. Keep packaging logic in the existing MSBuild targets.
  • Add a short English/Chinese publishing section to the root README covering tool restoration, project and namespace selection, credential sources, category retention, and -DryRun.
  • Verify local preparation and failure handling without making a real upload. Leave mod versions, release changelogs, runtime code, AGENTS.md, and GitHub Actions unchanged.

Acceptance checks

Check Expected result
UXAssist -Namespace soarqin -DryRun, invoked from another directory Uses repository-relative inputs, produces the normal flat ZIP, and shows the correct identity and DSP community without requiring a token.
Dustbin -Namespace soarqin -DryRun with an existing preloader DLL Refreshes DustbinPreloader, packages plugins/ and patchers/, and includes the current build outputs.
A different explicit namespace for the same project Uses that Team in generated configuration, version lookups, and package links while continuing to read Package Name from the existing manifest.
Missing project, malformed metadata, missing/empty/invalid namespace, preloader/helper selection, or traversal input Stops before publication and identifies the invalid input.
Explicit -EnvFile, default caller-directory .env, and process token are all available Uses the explicit file first; without it, uses the caller's .env; without either file, uses the process variable. Repository-local .env files are supported.
Missing token, missing explicit file, malformed selected file, or conflicting Windows User-scoped token Stops without exposing credentials or changing persisted environment variables.
Failed restore/build/pack or invalid ZIP Never invokes tcli publication and never falls back to an older ZIP.
Generated configuration Contains only dyson-sphere-program, explicitly empty categories, and no credential values. Check the parsed tcli metadata as well as the TOML text.
Existing remote version, unexpected HTTP failure, tcli failure, or uncertain timeout Returns a nonzero result and provides an appropriate next step; no automatic republish or version bump.
Stubbed successful tcli invocation Receives the exact validated ZIP and intended token through its environment; receives no token argument. Process environment and working directory are restored after both success and failure.

Use focused command stubs for publication/error-path checks with a synthetic token. Run actual packaging preparation for UXAssist and Dustbin and run git diff --check before implementation handoff. A real release is a separate operation against an explicitly selected project/version; validate the resulting listing and retained categories when that operation is requested.

Verified upstream behavior

Sources checked on 2026-10-17: