AstroFrame/AGENTS.md
Elijah 65ded0b606
All checks were successful
Release AstroFrame / packages (push) Successful in 1m8s
Release 1.1.1: corroborate cloudy frames with local stellar attenuation
2026-10-04 10:45:10 -07:00

114 lines
11 KiB
Markdown

# 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 ... --apply` probes 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 configured `origin`; inspect it rather than replacing its URL.
- `Directory.Build.props` contains the application version. `packaging/Set-Version.ps1` updates that value; it does not commit, tag, or push.
- At the time these instructions were added, `1.0.2` was 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.patch` version without leading zeros and an exactly matching `v<version>` tag. Never overwrite a published version, its assets, or its tag. The initial `v1.0.0` tag is unpublished from a failed run; `1.0.1` was 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.patch` according 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:
```powershell
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 -Test` builds and runs engine and updater validation. `Verify-ReleaseAutomation.ps1` tests 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 -Publish` means local `dotnet publish` into `artifacts/AstroFrame`; it does **not** publish a Forgejo release. `Build.ps1 -Package` invokes package creation.
- For optional local packages, use `./packaging/Release.ps1 -Platform Both`. Outputs default to `artifacts/releases/win-x64` and `artifacts/releases/linux-x64`. Existing versioned publish folders are rejected to prevent stale files. Use fresh `-PublishRoot` and `-Output` workspace paths for a rebuild.
- Linux packaging needs `mksquashfs` from `squashfs-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:
```powershell
./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:
1. A push to `main` builds and tests both platforms without publishing.
2. A push of `v<version>` builds, tests, and publishes that version. A manual workflow run on `main` is build-only; a manual run on a version tag publishes.
3. `packaging/Build-ServerRelease.ps1` checks the ref/version match, runs engine/updater/publisher validation, and cross-packages both platforms into `artifacts/server-release/packages`.
4. The job renders the packaged Linux settings page under Xvfb, using AppImage extraction mode.
5. `packaging/Publish.ps1 -Directory artifacts/server-release/packages -Publish -RequireTag` validates 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-on` selects the **label**, not the runner name. The `docker` label 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 }}` as `ASTROFRAME_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`, and `AstroFrame-<version>-<channel>-full.nupkg`.
- Windows: `AstroFrame-win-x64-Setup.exe`.
- Linux: `AstroFrame-linux-x64.AppImage`, `install-linux.sh`, `astroframe.png`, and `AstroFrame-<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.ps1` verifies 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> -RequireTag` to create/resume a draft. Add `-Publish` only 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](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.