OpenProgram installation, packaging, release, and upgrade design

Official releases: v0.9.8

This is the normative source for OpenProgram installation and distribution. It defines user categories and platform support separately, covering macOS/Windows desktop packages, macOS/Linux/Windows CLI and server installations, browser access, Python runtime ownership, Program extension environments, versions, upgrades, and uninstallation. Official-release checking, downloading, platform installation boundaries, and current implementation evidence are detailed inOfficial-release automatic update design.

1. Established design constraints

1. Python is the core runtime for the OpenProgram backend, CLI, Runtime, and Program execution. Installation must not be simplified by removing Python.
2. macOS Desktop is distributed as DMG/ZIP explicitly labeled Unsigned . Windows Desktop is distributed only as an Authenticode-signed x64 NSIS installer. Linux publishes only the complete CLI/server runtime.
3. Every nondeveloper installation uses the same complete product runtime built for its platform and architecture. Desktop adds only the Electron shell; CLI/server adds only command launchers. They must not install different sets of Web, Provider, Channel, Browser, model assets, or first-party Program capabilities.
4. The complete product runtime includes pinned CPython, OpenProgram, precompiled Web, Channels, Search, GUI/Research/Wiki first-party Programs, Playwright Chromium, GPA detector weights, Research PDF support, and other manifest dependencies. The GUI Program is installed with --no-deps . The product runtime explicitly excludes PyTorch, torchvision, OpenCV, EasyOCR, sentence-transformers, triton, and NVIDIA/CUDA distributions.
5. Ordinary users need no preinstalled Python or Node.js. Session and Memory Git history requires system Git on PATH; the product runtime does not bundle Git. Installers may download the complete runtime archive for the current platform, but cannot label an artifact missing manifest capabilities as a complete installation.
6. Desktop packages and CLI runtimes remain read-only during execution. Configuration, sessions, caches, and user-added third-party Programs go into ~/.openprogram.
7. Development installations add editable source, debugging tools, local Web/Ink builds, test tools, and explicitly configured backend overlays for GUI perception, OCR, Browser, and other components on top of full product capabilities. GUI perception paths requiring PyTorch, OpenCV, or EasyOCR exist only in these overlays, outside ordinary-installation manifest capabilities.
8. stable denotes a published, verified version, not origin/main.main belongs only to development installations.
9. Official installations use no editable checkout, do not build Web or Ink on user machines, depend on no repository directory, and do not resolve product dependencies through PyPI.
10. pip install openprogram, pipx install openprogram and uv tool install openprogram are not supported product installation entries. Public indexes, introductory documentation, and runtime repair messages must point only to official installers or complete packages. Wheels are used only for release runtime assembly, source development, and testing.
11. PyInstaller, Briefcase, and py2app are references only and do not replace the existing Electron desktop application.
12. The default CLI/server entry for ordinary users is curl -fsSL https://openprogram.io/install | sh. The site script only resolves the latest stable release, validates its version format, and downloads the installer from that immutable tag. Runtime checksums, capability manifests, and cold-start validation remain the versioned installer’s responsibility.
13. The only installed macOS App location is the fixed path /Applications/OpenProgram.app. Local desktop builds generate and validate an App in an unregistered temporary directory, then replace that fixed path. Temporary Apps are neither launched nor retained, and App directory names never contain versions or task names.
14. Windows x86_64 CLI/server uses the complete ZIP runtime and PowerShell installer. Windows Desktop uses the same runtime archive, a per-user NSIS installer, ConPTY, and mandatory signed-release gates. Windows sandboxing remains a separate layer.

2. Current implementation and verified gaps

3. Official specifications and tool comparison

This design assembles the macOS desktop shell with Electron and electron-builder, the internal product runtime with uv and standard wheels, and distributes complete platform/architecture-specific runtime archives for macOS/Linux/Windows through GitHub Release. Apple, Linux desktop packaging, and PyPA specifications explain distribution options explicitly rejected or restricted here.

4. User categories and platform support

Three user categories describe installation purpose; the platform matrix describes product commitments. Maintain them separately rather than substituting user categories for platform coverage.

4.1 Platform support matrix

Browser access does not make the client operating system a natively supported platform. Servers must use supported macOS, Linux, or Windows installations. Only combinations passing browser and responsive-layout acceptance may be labeled officially supported.

5. One version and one release artifact set

pyproject.toml ’s project version is normative. Electron metadata retains a copy required by build tools. Release gates verify exact equality with runtime manifest, release manifest, and tag. The tag must point to the commit being built.

Each release generates at least:

• Complete runtime archives for macOS arm64/x64, Linux x86_64/arm64, and Windows x86_64;
• macOS arm64/x64 unsigned DMG/ZIP and Windows x64 signed EXE;
• Developer wheel/sdist, not ordinary-user installation entries;
• A release manifest with version, capability IDs, first-party Program commits, model identifiers, file sizes, and SHA-256.

The first official release builds arm64 and x64 separately, without universal2. Native Python wheels, Browser, OCR, models, and Electron helpers vary by platform or architecture. Each platform has its own runtime, but every entry in the shared capability manifest must be present and verified, or the entire platform is withheld from release.

6. macOS and Windows desktop packages

6.1 Icon assets

• apps/desktop/build/AppIcon.icon is the maintained Apple layered source. Four SVG layers use a 1024×1024 unmasked canvas;apps/desktop/build/icon.icns is the version-controlled compatibility artifact packaged by Electron.
• Legacy ICNS retains the visible extent, rounded contour, transparent corners, and controlled shadow accepted against system Apps. The layered .icon itself must not pre-draw the system frame.
• The lavender cell and its three flat discs stay centered within the safe area, without text, question marks, or embedded rasters. The App icon specification defines the mark.
• Build gates verify layered source structure, brand-graphic constraints, ICNS representations, 256 px contours and solid area, transparent corners, and ICNS round trips. Final Dock, Finder, and Launchpad display is checked only through the installed /Applications/OpenProgram.app .

6.2 Logical contents

OpenProgram.dmg → OpenProgram.app/Contents/

macOS desktop resource directory
        ├── MacOS/
        │   └── OpenProgram                 # Electron launcher
        ├── Frameworks/
        │   ├── Electron Framework.framework
        │   └── Electron helpers
        └── Resources/
            ├── app.asar                    # Electron main/preload
            └── runtime/
                ├── python/                  # Pinned portable CPython + complete product dependencies
                ├── bin/uv                   # Pinned uv
                ├── wheel/                   # Build-time wheel evidence
                ├── assets/playwright/       # Pinned Playwright Chromium
                ├── assets/gpa/model.pt      # GPA detector weights
                └── runtime-manifest.json

Portable CPython for macOS and Linux comes from python-build-standalone artifacts indexed by the pinned uv version. The runtime manifest records OpenProgram, Python, uv, capability results, first-party Program commits, asset paths, and product manifest SHA-256;product-runtime.json records model sources and revisions; the release manifest records final artifact hashes. Never copy arbitrary runtimes from the packaging machine’s system Python.

6.3 Startup

1. Electron reads the in-app runtime manifest and verifies the complete capability manifest and required files.
2. Electron uses the in-app Python worker launcher through an explicit absolute path, without searching PATH.
3. Python starts with -I -B , ignoring system PYTHONPATH, user site-packages, and system Python configuration, and prohibiting bytecode writes into the app.
4. The launcher sets bundled Playwright Chromium and GPA detector asset paths and imports the pinned first-party Programs.
5. The worker listens on a local port and returns runtime status and the capability manifest hash through /healthz .
6. Electron obtains the authenticated URL and loads Web UI. Startup failures show the error category, log location, and repair action.

6.4 Prohibited behavior

• Do not invoke PATH’s openprogram, python, node or git.
• The running App and automatic updater do not modify their own bundle directly. Only a local installation transaction or verified official-update transaction may replace the fixed /Applications/OpenProgram.app.
• After acquiring the fixed-path installation lock, the local installer copies and validates the candidate App, then rereads and compares the current App against the immutable transaction copy’s version. A lower candidate version must be rejected before stopping the worker or moving files. Version segments use arbitrary-precision decimal integer comparison. An existing fixed path that cannot be verified must be preserved and cause failure; comparison cannot be skipped.
• Same-version development refresh must synchronize Electron main/preload, the official updater implementation, and runtime dependencies. It must not generate an app.asar referencing current source while retaining old modules. After the refresh build, verify wheel metadata and recheck source, wheel, and current App inside the fixed-path lock shared with the full installer before stopping the worker or writing Python/asar.
• Do not download Python, Web, default Browser, default OCR, detector weights, or first-party Programs on first use.
• Do not read apps/web/out, Program checkouts, or development configuration from repository directories.
• Do not run npm build, pip dependency resolution, or git clone on user machines.

6.5 Windows packaging and signing

• Electron-builder produces an x64 per-user NSIS installer with a selectable directory, running as asInvoker .
• The packaging input is the official Windows runtime ZIP. First use the PowerShell release installer to verify archive, manifest, capabilities, and worker cold-start, then move it into Desktop resources.
• Both application executable and installer must pass Authenticode. Missing certificates or invalid signatures fail the release job; unsigned Windows Desktop must never be uploaded.
• Local unsigned builds are only for development package smoke tests, not public installation entries.
• Terminal uses Windows PowerShell/ConPTY. Browser profile import uses normal Windows installation and Local AppData locations; these paths do not change user ACLs.

7. Complete product runtime and development extensions

~/.openprogram/
├── programs/
│   ├── src/<program-id>/
│   ├── manifests/<program-id>.json
│   └── environments/
│       └── <runtime-id>/
│           ├── releases/<generation>/
│           └── current -> releases/<generation>
├── config/
├── sessions/
├── logs/
└── cache/

runtime-id includes at least CPython minor version, CPU architecture, dependency lock, first-party Program commits, and model identifiers. Desktop and CLI on the same platform/architecture must share runtime IDs and capability manifest hashes.

Third-party Program install, upgrade, and remove use the same transaction:

1. Resolve the Program source and declarations and write a temporary directory;
2. Create a staging environment using in-app uv and CPython;
3. Resolve and install dependencies from all enabled Program manifests, recording exact versions and artifact hashes;
4. Run import probes, Program registration checks, and worker cold-start probes;
5. After all pass, atomically switch current; on failure, delete staging and retain the original environment.

8. Installation, upgrades, and uninstallation

8.1 Desktop installation

1. macOS users download the architecture-matched DMG with unsigned in its filename, verify SHA-256, copy the sole OpenProgram.app into Applications replacing the previous version, then approve first launch through “Privacy & Security → Open Anyway.”
2. Windows users download only the exact release-attached win-x64.exe, verify SHA-256 and Authenticode, and run the per-user NSIS wizard. Versions without a signed EXE use CLI/server.
3. When local macOS developers run npm --prefix apps/desktop run dist , the script builds an unpacked App in a random temporary directory, validates bundle identifier, version, main executable, and embedded runtime, then stops the official running App and default worker. A candidate older than the current fixed App must be rejected before any App, worker, or Launch Services changes.
4. scripts/refresh-local-app.sh supports same-version macOS source refresh only: checkout Python/desktop versions, existing bundle, runtime manifest, and bundled Python distribution metadata must match exactly. Any difference fails before wheel build, App shutdown, or runtime writes. Version upgrades require repackaging and installing the full App.
5. macOS packaging uses a user-level lock independent of worktrees. The installer also holds an atomic lock in the target Applications directory throughout the transaction. Concurrent calls must fail explicitly before changing the App or services; cleanup removes only locks held by the current PID.
6. If the default profile has a launchd service, unload its KeepAlive service before replacement, then stop the worker actually holding the lock. After success, reinstall the service with the new App’s embedded Python and -I -B , wait for /healthz success, then open the App. Service ProgramArguments must not retain conda, source-checkout, or deleted-App paths.
7. macOS scripts stage on the Applications volume first. Only after staging completes does the old App move temporarily into the same transaction directory and the new App activate. Activation failure restores the old App, launchd service, and prior App/worker running state. Success removes the old App, Python wheel build cache, runtime staging, build directory, and transaction directory.
8. After macOS activation, explicitly register the fixed /Applications/OpenProgram.app with Launch Services. If a subsequent failure restores the old App, best-effort re-register the restored fixed path while preserving the original failure status.
9. Both platforms’ Desktop artifacts embed platform runtime archives that passed complete capability probes. First launch creates only configuration and state directories; the worker uses bundled CPython. Packaged-mode authenticated URLs are also generated exclusively by bundled Python, without relying on system CLI.
10. Linux has no desktop installation; users install the complete CLI/server runtime and use Web UI or TUI.

8.1.1 Same-version local refresh completion

The local refresh starts the new embedded worker once: installed launchd service installation dispatches its start, otherwise the embedded CLI starts one detached worker. Health polling on default port 18100 has a 120-second deadline and individually bounded probes; polling never issues repeated worker starts. Timeout records the failed health endpoint and worker log location and remains a failure. After the complete App passes code-signing verification, completion cleanup attempts to reopen that same App even if health or worker-identity verification fails. Reopening occurs once, preserves the primary failure status, and reports a secondary reopen failure. Failures before signature verification do not launch a partially updated or unverified App. Cleanup retains its staging-directory removal error while attempting the remaining cleanup. A primary failure takes precedence; otherwise the cleanup error becomes the exit status. Cleanup failure never reports refresh success. Existing committed-source, version, foreign-signature, and lock gates still apply.

8.2 CLI / Server installation

1. macOS/Linux uses curl -fsSL https://openprogram.io/install | sh; Windows uses irm https://openprogram.io/install.ps1 | iex. When OPENPROGRAM_VERSION is unspecified, the short bootstrap resolves the stable version through GitHub latest release.
2. Bootstrap accepts only three-part numeric versions, then downloads the platform-compatible entry from the corresponding immutable tag: scripts/install-release.sh or scripts/install-release.ps1, followed by the official implementation from the same tag.
3. The official installer downloads the exact OS/architecture runtime archive and checksum from the same GitHub Release, without PyPI access.
4. After verification, extract into runtime/cli/releases/X.Y.Z under the user state directory. macOS Desktop uses the same archive as a build input; Linux and Windows use the complete archive directly as the official product entry.
5. The installer uses absolute runtime paths for version, capability, first-party Program, Browser/OCR asset, and worker cold-start probes.
6. After all checks pass, macOS/Linux atomically switches the current symlink; Windows atomically replaces the PowerShell launcher while preserving its predecessor. Failure retains the old version.

8.3 Development installation

Development documentation uses a repository checkout,uv sync, Web/Ink builds, and test tools. Development environments must run the same capability probes as releases and permit explicitly configured OCR/Browser backends, first-party Program source editing, and diagnostics. These overlays do not alter the product manifest.

8.4 Upgrades

• macOS Desktop:Automatically check the latest official Release. Settings downloads the complete architecture-matched DMG, verifies byte count and SHA-256, and opens it for user-confirmed App replacement.
• Windows Desktop:Select the exact signed EXE, verify byte count, SHA-256, and Authenticode, then open it for user-confirmed installation.
• CLI / Server: openprogram upgrade downloads a new complete runtime archive, validates it in a new version directory, then switches current. Failure preserves the previous version; the user explicitly restarts a running worker.
• Development:The same command retains fetch, build, complete capability probes, and restart in source checkouts; the target ref must be explicit.
• Compatibility command:Legacy update is a compatibility alias for upgrade ; worker startup never automatically applies product updates.

GUI, Research, and Wiki first-party Programs upgrade atomically with the product runtime. Any first-party Program or default-asset validation failure prevents activation of the entire new runtime. Third-party Programs migrate in separate environments; failed migration disables only that third-party Program without changing the verified product capability manifest.

8.5 Uninstallation

• Deleting OpenProgram.app removes only the desktop application, retaining by default ~/.openprogram.
• CLI uninstall removes launchers and OpenProgram-managed CLI runtimes, retaining state by default.
• Only explicit purge deletes configuration, sessions, Programs, and caches. Show exact directories and require confirmation before execution.

9. Security, integrity, and failure handling

Release needs no Apple or PyPI credentials. Windows Desktop publication requires code-signing certificate secrets. GitHub Actions creates Releases with the repository-provided short-lived token. First-party Program commits, model sources, and runtime archive hashes enter the release manifest. This document adds no system Keychain, keyring, or Credential Manager integration.

10. Public-entry acceptance criteria

10.1 Platform product runtime

1. Build on native runners from a pinned OpenProgram commit, dependency lock, first-party Program commits, and model sources.
2. openprogram --version, worker cold-start, /healthz, /chat and hashed Web assets succeed.
3. All GUI, Research, and Wiki Functions register. Import/asset probes pass for Channels, Search, Playwright Chromium, GPA detector, and Research PDF support.
4. Verify installed distributions exclude PyTorch, torchvision, OpenCV, EasyOCR, sentence-transformers, triton, and NVIDIA/CUDA entries.
5. Generate the capability manifest and runtime archive SHA-256; any missing item fails.

10.2 macOS DMG

1. Verify separately on clean arm64 and x64 environments with system Git but without OpenProgram, Python, or Node.js installed.
2. Filenames, Release notes, and installation pages explicitly say unsigned; verify “Privacy & Security → Open Anyway.”
3. With networking disabled, complete first startup, worker, Web, first-party Program registration, Playwright Chromium, GPA detector, and Research PDF probes. First use must not implicitly install GUI perception overlays.
4. The Python path started by Electron and capability manifest hash must come from the embedded runtime archive.

Local complete packaging first uses electron-builder to ad-hoc sign Electron components and complete resource signatures, then a fixed local certificate signs the main OpenProgram App and runtime helpers, followed by strict recursive signature verification. Build mode must not skip component signing because publication certificates are unnecessary. Full App build, strict signature verification, runtime checks, fixed-path installation, and default-worker refresh are verified.

10.2.1 Local fixed-App replacement

1. After two consecutive local desktop builds, Applications contains only OpenProgram.app, with no App containing a version, commit, task name, or before suffix.
2. When two worktrees or installers run concurrently, only one process enters the target-App transaction. The other fails before changing the App or services. No nested App is created, and the success-log version matches the final installed version.
3. A corrupt candidate bundle, copy failure, or activation failure must not delete a usable old App. Successful replacement leaves neither old nor build bundles.
4. Apps in build and staging paths never execute open; the final launch command accepts only the fixed installation path.
5. Validate the installed bundle identifier, version, main executable, ICNS, and embedded runtime. The bundle, runtime manifest,openprogram --version , and bundled Python distribution metadata must report the same version. Launch Services needs only the fixed installation path registered.
6. When checkout version X refreshes fixed-App version Y, only X=Y may proceed. Both X<Y and X>Y require a full App build. Full candidates older than the current App must also be rejected before stopping App and worker.

10.2.2 Windows signed EXE

1. Native Windows runners use the same complete runtime ZIP as the CLI installer and validate the runtime manifest, bundled Python, worker health, and Web chat from win-unpacked .
2. OpenProgram.exe and the NSIS installer must have Valid Authenticode status; missing signing credentials immediately fail release.
3. Terminal’s Windows PowerShell and Claude presets start through ConPTY. Chrome, Edge, Brave, and Chromium profile discovery pass Windows-path tests.
4. Updater selects only the exact x64 EXE. Any size/hash/signature failure deletes temporary files and prohibits opening.

10.3 Linux desktop release gate

1. Linux desktop artifacts must package the same complete runtime as CLI/server, without removing capabilities, Programs, OCR, models, or Browser assets.
2. They must start through public entries on clean x86_64 Linux without system OpenProgram, Python, Node.js, or Git, and complete all probes offline.
3. The current AppImage fails in electron-builder’s block-map stage for the complete runtime, so no artifact passes this gate. Release configuration must neither build nor publish AppImage.
4. Restore Linux desktop support claims only after a new complete desktop artifact satisfies every condition in this section.

10.4 Third-party Programs and development overlays

1. First-party GUI/Research/Wiki must never appear uninstalled or require first-start wizard installation.
2. Third-party Programs modify only ~/.openprogram/programs and separate environments, never the product runtime.
3. After developers replace OCR/Browser backends or enable debugging, the baseline capability manifest must still pass.

10.5 CLI / Server

1. macOS/Linux shell bootstrap and Windows PowerShell bootstrap both resolve the latest stable release and download a pinned runtime archive in clean user environments, without PyPI or repository clones.
2. Both automatic version resolution and explicit OPENPROGRAM_VERSION version pinning in the short bootstrap require offline entry tests. Resolved versions must be three-part numeric versions; downloads must use the corresponding immutable tag.
3. Installed runtime archive and capability manifest hashes match the release manifest. macOS and Windows Desktop use the same platform build inputs.
4. Installers run complete probes through absolute runtime paths; old versions remain startable after failed upgrades.

10.6 release

Release notes lead with user-visible changes, provide a platform and architecture download table with direct links to published assets, and separate upgrade instructions from developer recovery details. Installation commands stay in copyable code blocks. Documentation-only release-note corrections update the canonical notes and public release body without moving the tag or replacing artifacts.

1. Tag, runtime archive, Electron package, manifests, and health endpoint report one version.
2. GitHub Release contains macOS runtime archives and unsigned DMG/ZIP, Linux runtime archives, Windows runtime ZIP and signed Desktop EXE, checksums, and capability manifest. It excludes Linux desktop packages failing gates and unsigned Windows Desktop.
3. Public GitHub Release titles and bodies use English throughout. Workflows reject release notes containing Chinese, Japanese, or Korean characters before publication.
4. Ordinary-user documentation, site indexes, and product-runtime errors must not contain pip install openprogram, PyPI product-download entries, optional-by-default Programs, or component-installation steps. Missing bundled dependencies require reinstalling the complete product.
5. Published tags are immutable; fixes use a higher patch version.

Implementation record:Task breakdown, RED/GREEN, reviews, and gate records are in Installation and distribution implementation plan. That record does not change this document’s conceptual boundaries.

11. Implementation status

12. Explicit exclusions

• macOS App Store, Developer ID signing, and notarization;
• System Keychain, keyring, Credential Manager, or similar credential-store integration;
• Rewriting OpenProgram to eliminate Python;
• Replacing Electron with PyInstaller, Briefcase, py2app, or Tauri;
• Per-Program process isolation in the first phase;
• Automatic installation of arbitrary third-party Programs;
• Treating replaceable OCR, stealth/agent-browser backends, or debugging tools as ordinary-user product dependencies.

Related designs:Single-port worker and frontend; Self-update. This document takes precedence for conflicting installation/distribution content and is referenced by related designs.