How to Upgrade Apache Maka: Complete Guide for Desktop and CLI

Upgrading Apache Maka requires a staged approach that backs up the existing installation, validates the new binary against a baseline manifest, and automatically migrates the SQLite schema while preserving workspace state.

Apache Maka is an open-source workspace management platform that distributes both desktop installers and command-line interfaces. Whether you are upgrading the Windows desktop application or the npm-based CLI, following the repository's official upgrade pipeline ensures atomic transitions without data loss.

Desktop (Windows) Upgrade Process

The Windows installer implements a defensive upgrade strategy that creates a complete backup before modifying system files. According to the source code in scripts/verify-windows-installer-rollback.mjs, the installer generates a <install-dir>.pre-upgrade-backup directory (see line 46) and captures the current registry snapshot before proceeding.

Baseline Validation

The upgrade pipeline validates every new build against a pinned baseline defined in scripts/windows-upgrade-baseline.json. This JSON manifest locks the exact Git tag, asset name, and SHA-256 hash of the approved release, preventing installation of corrupted or tampered binaries.

During installation, the process executes the verification logic found in scripts/verify-windows-autoupdate.mjs (lines 107-119), which confirms that the new binary reports the expected currentVersion before allowing the replacement to complete.

Automated Rollback Protection

If the upgrade fails, the system automatically restores the pre-upgrade state. The rollback script (scripts/verify-windows-installer-rollback.mjs, lines 155-206) handles restoration of both files and registry entries.

Critical safety check: if the backup directory remains after a successful upgrade, lines 321-324 of the rollback script abort the process and alert the user. This guarantees that stray backup folders never persist on production systems.

CLI and npm Upgrade Method

The CLI distribution requires a different approach than standard npm packages. The official guidance in packages/cli/README.md (line 126) explicitly warns against running npm update --global maka-agent because the latest tag is mutable and may point to incompatible pre-release builds.

Targeted Version Installation

Use explicit version tags to ensure reproducible upgrades:

# Upgrade to the newest stable release

npm install -g @apache/maka@stable

# Or pin to a specific version

npm install -g @apache/maka@2.5.0

Post-Upgrade Verification

After installation, validate the upgrade with built-in diagnostics:

maka --version           # Displays the installed version

maka db verify           # Executes internal schema-compatibility checks

SQLite Schema Migration

Apache Maka stores all workspace data in runtime.sqlite. Schema migrations occur automatically when the new binary first accesses the database. The migration implementation in packages/storage/src/sqlite-runtime-schema.ts (line 884) uses a single write transaction to serialize upgrades, ensuring that only one process modifies the schema at a time.

If a migration fails mid-process, the Windows installer's rollback logic restores the runtime.sqlite file from the pre-upgrade backup, returning the database to its original schema version without manual intervention.

End-to-End Windows Upgrade Example

For Windows administrators performing manual upgrades, follow this PowerShell workflow that mirrors the automated pipeline:

# Download the signed installer

Invoke-WebRequest -Uri "https://downloads.maka.apache.org/maka-2.5.0-windows-x64.exe" -OutFile "maka-installer.exe"

# Execute silent installation (automatically handles backup and validation)

.\maka-installer.exe /silent

# Verify the upgrade via the desktop API

$version = (Get-Item "C:\Program Files\Maka\maka.exe").VersionInfo.ProductVersion
Write-Host "Apache Maka upgraded to version $version"

The installer validates the binary using window.maka.app.updateStatus() (referenced in scripts/verify-windows-autoupdate.mjs, lines 421-473) to confirm the application launches correctly before finalizing the installation.

Cross-Platform and Source Upgrades

On macOS and Linux, use the npm-based upgrade method described above. For developers building from source, pull the latest changes and rebuild the native dependencies:

git pull origin main
npm ci
npm run dev:peer           # For peer-enabled builds

# Or: npm run dev:full:peer

Summary

• Backup First: The Windows installer automatically creates a <install-dir>.pre-upgrade-backup directory before modifying any files.
• Validate Baseline: Every upgrade checks against scripts/windows-upgrade-baseline.json to verify binary integrity.
• Avoid Latest Tags: Use npm install -g @apache/maka@stable rather than mutable latest tags.
• Atomic Migrations: SQLite schema updates run inside serialized transactions at packages/storage/src/sqlite-runtime-schema.ts line 884.
• Automatic Recovery: Failed Windows upgrades trigger rollback logic in scripts/verify-windows-installer-rollback.mjs to restore the previous state.

Frequently Asked Questions

What happens if the Windows upgrade is interrupted?

The installer maintains the pre-upgrade backup until the new binary successfully reports its version via the validation logic in scripts/verify-windows-autoupdate.mjs. If the process terminates early, the rollback script (lines 155-206 of scripts/verify-windows-installer-rollback.mjs) automatically restores the original installation directory and registry settings.

Can I downgrade Apache Maka after upgrading?

Yes, provided the pre-upgrade backup directory still exists. Run the verification logic manually or reinstall the previous version over the current installation. The SQLite schema will revert to the backup copy if the rollback mechanism triggers. Never delete the .pre-upgrade-backup folder until you confirm the new version works correctly.

Why does npm update fail for the CLI package?

The maintainers explicitly disable the latest tag for automatic updates (see packages/cli/README.md line 126). This prevents npm from installing potentially incompatible builds. Always specify either @stable or an exact version number when upgrading the global CLI package.

How do I verify the installer file integrity?

The Windows installer validates itself against scripts/windows-upgrade-baseline.json, which contains the SHA-256 hash of the official release asset. Before running the installer manually, compare your downloaded file's checksum against the manifest published in the Apache Maka repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}