11 KiB
AstroFrame agent instructions
Always ask clarifying questions before proceeding when you need more information.
Scope and installed-app protection
- Work on the source code and workspace artifacts. The user explicitly requires that development and release verification leave their locally installed AstroFrame untouched.
- Do not run installers or uninstallers, launch the installed application, apply an update to it, or change its installed files, preferences, registry entries, Start Menu shortcuts, or taskbar pins. Earlier installer testing removed the user's installation and shortcuts.
- Do not run packaged
--verify-update ... --applyprobes against the user's installation. Use fake update locators and workspace fixtures for update tests. Any installed-app interaction needs explicit new user authorization. - Keep test output and disposable tools under
artifacts/and.tools/. For preview QA, copy saved-project caches into a workspace test folder before rendering; read source exposures without modifying them. - Publish only when a release is requested or included in the authorized task. Documentation-only changes do not need a version bump or release tag.
Repository and version source
- Public Forgejo repository: https://git.elijahkuntz.com/Elijah/AstroFrame.
- Main development branch:
main. Use the configuredorigin; inspect it rather than replacing its URL. Directory.Build.propscontains the application version.packaging/Set-Version.ps1updates that value; it does not commit, tag, or push.- At the time these instructions were added,
1.0.2was published successfully. Read the current props, tags, and published releases before choosing the next version; do not assume this baseline stays current. - Use a new stable
major.minor.patchversion without leading zeros and an exactly matchingv<version>tag. Never overwrite a published version, its assets, or its tag. The initialv1.0.0tag is unpublished from a failed run;1.0.1was the first published release. - Put release notes in
docs/release-notes/<version>.md. The publisher uses this file as the release description, with a generic fallback if absent.
Version numbering
- Use
major.minor.patchaccording to the scope of the release, rather than counting commits. - Increment the patch component (
1.1.x) for singular or minor changes, fixes, and focused improvements. - Increment the minor component (
1.x.1) for major fixes, major features, or extensive changes within a bounded part of the program. - Increment the major component (
x.1.1) for entire-program overhauls, extensive changes impacting much of the program, or codebase rewrites. - The examples identify the component to increment. Normally reset lower components to zero when incrementing a higher component; an explicitly requested version takes precedence. This focused algorithm correction is requested as
1.1.1.
Build and validation
AstroFrame is an Avalonia/.NET 8 application, published self-contained for win-x64 and linux-x64. Windows uses a per-user Velopack installer; Linux uses an AppImage and optional per-user menu installer, targeting Debian and Arch. ARM is not currently required. Packages are currently unsigned.
Use PowerShell 7 for packaging and publication. Velopack CLI and application integration are pinned to 1.2.161; its CLI requires a .NET 10 SDK/runtime. Tests require the .NET 8 runtime. Keep those versions compatible when changing dependencies.
From the repository root, keep temporary files, NuGet HTTP cache, and telemetry handling within the development scope:
New-Item -ItemType Directory -Force artifacts/test-temp, .tools/http-cache | Out-Null
$env:TEMP = Join-Path $PWD 'artifacts/test-temp'
$env:TMP = $env:TEMP
$env:NUGET_HTTP_CACHE_PATH = Join-Path $PWD '.tools/http-cache'
$env:AVALONIA_TELEMETRY_OPTOUT = '1'
./Build.ps1 -Test
./tools/Verify-ReleaseAutomation.ps1
Set the temporary environment before starting test processes. Build.ps1 also sets workspace .NET home and NuGet package directories. It prefers .tools/dotnet/dotnet.exe on Windows when available, otherwise dotnet on PATH.
Build.ps1 -Testbuilds and runs engine and updater validation.Verify-ReleaseAutomation.ps1tests the publisher with a mocked API and does not publish a release.- Render affected controls for visual changes and inspect the result; build/test success alone does not validate an overlay or layout. Use isolated source rendering that does not initialize the installed app's settings or updater.
Build.ps1 -Publishmeans localdotnet publishintoartifacts/AstroFrame; it does not publish a Forgejo release.Build.ps1 -Packageinvokes package creation.- For optional local packages, use
./packaging/Release.ps1 -Platform Both. Outputs default toartifacts/releases/win-x64andartifacts/releases/linux-x64. Existing versioned publish folders are rejected to prevent stale files. Use fresh-PublishRootand-Outputworkspace paths for a rebuild. - Linux packaging needs
mksquashfsfromsquashfs-tools.packaging/release.sh <version>is the Linux-only alternative. Normal release packaging happens on the server, so a local installer build is not necessary.
Preferred release workflow: server build and publish
Finish the change, verify it, and prepare release notes before pushing a release tag. Include all intended changes in the release commit, preserving unrelated user work. The publisher requires a clean checkout whose HEAD exists on the remote.
Example for the next release after the recorded baseline; substitute the actual new version:
./packaging/Set-Version.ps1 -Version 1.0.3
# Create docs/release-notes/1.0.3.md and stage all intended source/test changes too.
git add Directory.Build.props docs/release-notes/1.0.3.md
git commit -m "Release 1.0.3"
git push origin main
git tag v1.0.3
git push origin v1.0.3
Run validation on the final versioned source before committing/tagging. Stage intended source/test files explicitly in addition to the two example files. Push the source commit before its tag. The tag must point at the committed source whose version matches it.
.forgejo/workflows/release.yml handles the rest:
- A push to
mainbuilds and tests both platforms without publishing. - A push of
v<version>builds, tests, and publishes that version. A manual workflow run onmainis build-only; a manual run on a version tag publishes. packaging/Build-ServerRelease.ps1checks the ref/version match, runs engine/updater/publisher validation, and cross-packages both platforms intoartifacts/server-release/packages.- The job renders the packaged Linux settings page under Xvfb, using AppImage extraction mode.
packaging/Publish.ps1 -Directory artifacts/server-release/packages -Publish -RequireTagvalidates both channels, creates a draft, uploads all assets, and makes the release public only after every upload succeeds.
Known runner requirements that previously caused failures:
- Runner name:
unraid-runner; advertised label:ubuntu-latest.runs-onselects the label, not the runner name. Thedockerlabel did not match this runner. - Job container:
node:22-bookworm. This Linux runner can create both the Windows Setup executable and Linux AppImage using Velopack cross-packaging. - Checkout is pinned to
https://data.forgejo.org/actions/checkout@v4.4.0. Runner v6.4.0 supports Node 20 actions; checkout v6 requires Node 24 and failed. Check runner compatibility before upgrading actions. - The workflow installs the .NET 10 SDK, .NET 8 runtime, PowerShell 7.4.20,
squashfs-tools, and Linux desktop/Xvfb dependencies. Preserve these prerequisites. - The publisher uses Forgejo's repository-scoped
${{ github.token }}asASTROFRAME_RELEASE_TOKEN; no personal token is needed for the server workflow. - Server Linux smoke tests do not establish Windows UI acceptance or separate Arch/Debian desktop acceptance. Report validation accurately and respect the installed-app protection rule.
Assets required for automatic updates
Installed applications use Velopack's public Gitea release source, with separate win-x64 and linux-x64 channels. They check published stable releases, not Git commits, and never pull source code or need a Git client. No repository write token belongs in the application.
Each public release must include both platforms. Uploading only an installer breaks the automatic-update workflow. Normal builds produce 13 assets:
- For each channel:
releases.<channel>.json,RELEASES-<channel>,assets.<channel>.json, andAstroFrame-<version>-<channel>-full.nupkg. - Windows:
AstroFrame-win-x64-Setup.exe. - Linux:
AstroFrame-linux-x64.AppImage,install-linux.sh,astroframe.png, andAstroFrame-<version>-linux-x64.zip. - Include any generated delta packages referenced by the feed. Full packages support updates from older versions without deltas. Keep older published releases available.
After pushing the tag, check the tagged Actions run through successful publication, then verify the public release is stable, not a draft, contains both channels and expected assets, and both feeds reference the new full package with matching size/checksum. A green main build is not proof of publication. Inspect the public API/assets or use an isolated fake locator; do not update the user's installed copy as a test.
The agreed user experience is: check on launch and every six hours, notify when a newer stable release exists, then download/install/restart only when the user clicks Install update and restart. Settings shows version/status, automatic-check preference, and manual check. Installation is blocked during processing or saving and saves the project before restart. Source-tree builds are not self-updating. Preserve this behavior when modifying updates.
Publisher recovery and local fallback
packaging/Publish.ps1verifies version, clean source, remote commit, matching tag when required, package sizes, and SHA256 before publication. The correct commit API route is/api/v1/repos/Elijah/AstroFrame/git/commits/<sha>;/commits/<sha>returned 404.- A failed upload leaves a draft, invisible to installed apps. Resuming is safe only with identical package bytes; existing uploads are downloaded and compared by SHA256. A fresh rebuild may differ and cause a conflict.
- Do not delete published releases or force-move tags to fix publication. Ask before deleting conflicting draft assets/releases or moving an unpublished tag; prefer a new version when requested by the user.
- Local fallback: supply a repository-write token through the process environment as
ASTROFRAME_RELEASE_TOKEN, then run./packaging/Publish.ps1 -Directory <package-root> -RequireTagto create/resume a draft. Add-Publishonly when immediate publication is authorized. Use the matching tagged checkout and both channel folders. - Never commit, print, embed, or persist a release token in scripts or application files.
See docs/releases.md and the scripts/workflow above for implementation details. Treat those files as the current authority if these instructions become stale, and update this runbook when changing the workflow.