omarchy-pkgs/pkgbuilds/shared/lmstudio-bin/LMStudio-bin Blueprint.md

PROJECT BLUEPRINT: lmstudio-bin Maintenance Framework

1. Executive Summary

Project Name: lmstudio-bin

Target Platform: Arch Linux (AUR)

Upstream Software: LM Studio (Proprietary AppImage)

This project provides an Arch User Repository (AUR) package for LM Studio. It employs a "Maintenance Bridge" architecture to convert dynamic upstream releases into deterministic, security-verified Arch Linux packages while adhering strictly to Arch Linux packaging standards for binary software.

2. Core Objectives

Correct Naming Convention: Utilize the -bin suffix as mandated by AUR guidelines for software distributed as pre-compiled binaries.

Replacement of Legacy Packages: Explicitly provide and conflict with the abandoned lmstudio package to ensure a clean migration path for the community.

Security & Determinism: Implement strict SHA256 checksum verification for every release, preventing "moving target" build failures.

Full Desktop Integration: Ensure high-resolution icon support, XDG-compliant desktop entries, and taskbar grouping (StartupWMClass).

3. Technical Architecture

A. The Maintenance Engine (update_package.py)

The heart of the project is a Python-based automation script that manages the lifecycle of a release.

URL Resolution: Follows the latest redirect to identify the specific build version.

Verification: Downloads the AppImage and calculates the SHA256 hash.

Template Rendering: Injects metadata into PKGBUILD.template to produce a valid PKGBUILD.

Metadata Generation: Automatically updates .SRCINFO for AUR indexing.

B. Packaging Logic (PKGBUILD)

The build process follows a specific lifecycle to ensure stability:

Extraction Stage: Uses --appimage-extract within a temporary sandbox to access internal assets.

Icon Strategy (Static Vendoring):

• Static Icon: The high-resolution (512x512) icon is vendored as lmstudio.png in the base repository.
• Optimization: Icons must be optimized to stay under the 500KB AUR repository blob limit.
• Rationale: Static vendoring prevents build-time extraction failures and ensures consistent visual presentation across versions without relying on internal AppImage layout stability.

Binary Placement: Installs the AppImage to /opt/lm-studio/ and provides a symbolic link at /usr/bin/lm-studio.

C. Lifecycle Management (.install)

The .install script ensures the host system recognizes changes immediately upon installation, upgrade, or removal by triggering:

update-desktop-database (Applications menu)

gtk-update-icon-cache (Visual assets)

4. Automation Workflow (For Orchestrator Reference)

When updating to a new version, the orchestrator should follow this sequence:

Sync: Pull latest changes from the AUR remote.

Execute: Run ./update_package.py to fetch upstream changes and regenerate files.

Validate: * Verify PKGBUILD version matches upstream.

Run makepkg -f to test the build locally.

Inspect pkg/ directory to ensure icon assets are present at /usr/share/icons/hicolor/512x512/apps/lmstudio-bin.png.

Publish: * Refresh .SRCINFO (makepkg --printsrcinfo > .SRCINFO).

Commit PKGBUILD, .SRCINFO, lmstudio.desktop, lmstudio.png, and lmstudio-bin.install.

Push to origin master.

5. Git Hygiene & AUR Constraints

• Blob Limit: The AUR imposes a strict 512KB limit on individual file blobs. All vendored assets (like lmstudio.png) must be optimized to comply.
• Tracking Restrictions: Only source-of-truth files and metadata are permitted in the repository. Tracking of src/ or pkg/ directories is strictly prohibited.
• Verification: Use verify_git_hygiene.sh to audit the repository state before pushing to the AUR remote.

6. Directory Structure

. ├── PKGBUILD # Generated Arch Linux build script ├── PKGBUILD.template # Blueprint for the maintenance engine ├── .SRCINFO # AUR metadata index (auto-generated) ├── lmstudio.desktop # Desktop integration file ├── lmstudio.png # Static vendored icon (512x512) ├── lmstudio-bin.install # Post-install hooks for cache clearing ├── update_package.py # The Maintenance Engine script ├── verify_git_hygiene.sh # Hygiene enforcement script └── LMStudio-bin Blueprint.md # This reference document

7. Maintenance Contacts & Authority

Maintainer: madgoat (AUR)

Package URL: https://aur.archlinux.org/packages/lmstudio-bin