Research installer framework: packaging, auto-update, and reusable installation patterns

[elijahr]

Problem

Spellbook's installer handles a complex set of tasks that don't fit neatly into traditional package managers: symlinking content into config dirs, injecting context into existing files, registering MCP servers, managing system services, auto-updating via git. The current implementation is bespoke Python (~2000 lines across install.py and installer/), but many of these patterns are shared by projects like oh-my-zsh, asdf, spacemacs, and other "config-layer" tools.

Two related questions:

1. Can we use a package manager as an entry point (pipx, Homebrew, uv tool) even if post-install setup remains custom?
2. Can we extract our installation patterns into a reusable framework that other projects with similar needs can use?

Research Areas

1. Package Manager Entry Points

Approach	Pros	Cons
pipx install spellbook	Familiar, one command	Still needs post-install setup
Homebrew tap	One command on macOS, handles updates	macOS/Linux only
uv tool install	Native to uv ecosystem	Still experimental
Improved curl-pipe	Already works, zero new infra	"Roll your own" perception

Recommendation from initial analysis: improve curl-pipe first, add uv tool as secondary, consider Homebrew tap if demand warrants.

2. Reusable Installer Framework

Many projects share these installation patterns but each rolls their own:

• Self-bootstrapping: Install prerequisites (package managers, runtimes) before the tool itself
• Auto-update: Check upstream, pull updates, re-execute with new code
• Config injection: Merge tool-specific content into existing user config files (shell rc, editor config, AI assistant config)
• Symlink management: Link content from a source repo into target directories, with cleanup of stale links
• Service management: Install/start/stop persistent daemons across macOS (launchd), Linux (systemd), Windows (Task Scheduler)
• Platform detection: Discover which target tools are installed and where their config lives
• Multi-target installation: Install the same content into multiple platforms simultaneously
• Idempotent reinstall: Run the installer repeatedly without breaking state
• Clean uninstall: Mirror every install action with a removal action

Research needed:

• Survey how oh-my-zsh, asdf, Homebrew, nix, pre-commit, and similar projects handle each pattern
• Look for existing libraries/frameworks that handle subsets (e.g., Python service managers, cross-platform symlink libraries, config merging tools)
• Identify which patterns are truly reusable vs. spellbook-specific
• Evaluate whether extracting a installer-framework library is viable and useful to others
• Consider whether something like this already exists as a meta-installer or plugin framework

3. Missing Capabilities

Things other installers do that ours doesn't yet:

• Offline/cached installation mode (pre-package assets for airgapped environments)
• Installation verification command (spellbook verify or spellbook doctor)
• Rollback on failure (partial install cleanup)
• Version pinning (install/lock to specific version)
• Plugin architecture (third-party skill packs)
• Progress percentage / ETA for long operations
• Quiet/verbose modes
• Machine-readable output (JSON) for CI integration

4. CLI Entry Point

Currently there is no spellbook CLI command. The daemon is managed via scripts/spellbook-server.py (install/start/stop/status) but this isn't exposed as a user-facing command. A CLI would unify:

• spellbook install (replaces install.py)
• spellbook update (replaces git pull + reinstall)
• spellbook uninstall (replaces uninstall.py)
• spellbook status / spellbook doctor (health check)
• spellbook server start/stop/restart (daemon management)

Approach

1. Research phase: Survey existing art, catalog shared patterns, evaluate reuse opportunities
2. Extract phase: Identify what can be pulled out of installer/ into a standalone library
3. Package phase: If extraction is viable, create a separate repo/package for the framework
4. Entry point phase: Add pipx/uv tool install as secondary distribution channel

Open Questions

• What's the target audience sophistication? (developers vs. broader)
• How important is Windows support for packaging decisions?
• Is git-based auto-update a feature or a liability?
• Should content repo (skills/commands) be separate from the Python package?
• Is there demand from other projects for a reusable installer framework, or is this too niche?