Add complete uninstall reset for fresh native installations

This commit is contained in:
2026-11-08 19:16:46 +00:00
parent e17bc2ca4f
commit 828227f549
6 changed files with 317 additions and 0 deletions
+3
View File
@@ -192,3 +192,6 @@ on another computer does not upload its files.
When reporting a problem, include your OS, install mode, reproduction steps, When reporting a problem, include your OS, install mode, reproduction steps,
`pipelines version --json` and `pipelines ping --json`. Redact credentials and `pipelines version --json` and `pipelines ping --json`. Redact credentials and
private content; do not post your database or harness session storage. private content; do not post your database or harness session storage.
To completely reset Pipelines, including its password and data, run `./uninstall`
from this checkout, then `./install` for a fresh setup. The checkout is retained.
+18
View File
@@ -137,6 +137,24 @@ From `arguments()` in `scripts/setup-native.py`:
Reinstalls keep the recorded authoring role unless you pass one of the two Reinstalls keep the recorded authoring role unless you pass one of the two
role flags. role flags.
## Full reset and fresh installation
From the checkout, run:
```sh
./uninstall
./install
```
`./uninstall` is a full reset, including incomplete installations: it stops
Pipelines and its retained chat hosts, removes its database/history, password,
configuration, managed skills, client build outputs, Docker resources and build
caches. It keeps the source checkout and separate AI-provider credentials.
The next install asks for a new password. Docker must be running to remove its
Pipelines resources; unrelated containers, images and volumes are preserved.
Custom installation prefixes can be selected with `./uninstall --prefix PATH`.
This reset has no confirmation prompt. Do not use it merely to update the app.
## Other install modes ## Other install modes
```sh ```sh
+21
View File
@@ -0,0 +1,21 @@
# Full reset entry point
`./uninstall` removes this user's Pipelines installation and its password,
configuration, history/session data, managed skill directories and client build
outputs. It stops the login service, retained hosts and manually started managed
processes, then removes only Pipelines-labelled Docker resources, known build
volumes/legacy volumes and matching build images. The source checkout and provider
logins remain, so the next command is `./install`.
Partial installs without a manifest are supported. Recorded XDG roots and custom
web credential paths are included. Preflight rejects unsafe roots, symlinks,
source-content deletion, unmanaged service files and an unavailable Docker daemon.
Service-stop failure leaves installation/password data intact. There is no prompt;
invoking this entry point explicitly requests the complete reset.
Verification: 15 reset tests passed using real isolated filesystem fixtures and
fake service/process/Docker commands, plus all 55 native installer tests. Tests
cover scoped cleanup, password deletion, partial installs, idempotence, XDG/custom
credentials, retained-host/manual-supervisor matching, unrelated resource
preservation, and Linux/macOS service behavior. Python compilation, wrapper help,
shell syntax and diff checks passed. No production installation was uninstalled.
+44
View File
@@ -5,6 +5,7 @@ from pathlib import Path
import subprocess import subprocess
import tempfile import tempfile
import unittest import unittest
from unittest.mock import patch
spec = importlib.util.spec_from_file_location("pipelines_uninstall", Path(__file__).with_name("uninstall.py")) spec = importlib.util.spec_from_file_location("pipelines_uninstall", Path(__file__).with_name("uninstall.py"))
uninstall = importlib.util.module_from_spec(spec) uninstall = importlib.util.module_from_spec(spec)
@@ -218,3 +219,46 @@ class UninstallTests(unittest.TestCase):
self.assertTrue(any(owned in c and "rm" in c for c in docker), owned) self.assertTrue(any(owned in c and "rm" in c for c in docker), owned)
for unrelated in ("deadbeef", "baadf00d"): for unrelated in ("deadbeef", "baadf00d"):
self.assertFalse(any(unrelated in c and "rm" in c for c in docker), unrelated) self.assertFalse(any(unrelated in c and "rm" in c for c in docker), unrelated)
def test_custom_cache_cannot_delete_checkout_source(self):
source = self.put(self.repo / "app/lib/main.dart", "keep source")
self.environment["PIPELINES_APP_CACHE"] = str(self.repo / "app")
with self.assertRaises(ValueError):
self.resetter().run()
self.assertEqual(source.read_text(), "keep source")
self.assertEqual(self.recorder.calls, [])
def test_only_owned_hosts_and_manual_supervisor_are_terminated(self):
original = self.recorder
commands = [f"{self.prefix}/bin/pipelines-claude-host --socket fixture",
f"python3 {self.prefix}/lib/manage.py supervise --prefix {self.prefix}",
f"node {self.prefix}/lib/web/serve.mjs --port 8082",
"codex app-server", f"{self.home}/other/bin/pipelines-claude-host"]
def processes(command, **kwargs):
if command[0] == "ps":
return subprocess.CompletedProcess(command, 0, stdout="\n".join(
f"{40001 + i} {text}" for i, text in enumerate(commands)), stderr="")
return original(command, **kwargs)
signalled = []
def signal_process(pid, number):
if number == 0:
raise ProcessLookupError()
signalled.append(pid)
with patch.object(uninstall.os, "kill", side_effect=signal_process):
uninstall.Uninstall(home=self.home, repo=self.repo, environ={},
runner=processes, system="Linux").run()
self.assertEqual(signalled, [40001, 40002, 40003])
def test_macos_reset_uses_only_its_launch_agent(self):
unit = self.put(self.home / "Library/LaunchAgents/net.a-wan.pipelines.plist",
"Managed by Pipelines native installer")
neighbor = self.put(unit.parent / "other.plist", "keep")
uninstall.Uninstall(home=self.home, repo=self.repo, environ={},
runner=self.recorder, system="Darwin").run()
self.assertFalse(unit.exists())
self.assertEqual(neighbor.read_text(), "keep")
self.assertTrue(any(c[:2] == ["launchctl", "bootout"] for c in self.recorder.calls))
self.assertFalse(any(c[0] == "systemctl" for c in self.recorder.calls))
+228
View File
@@ -0,0 +1,228 @@
#!/usr/bin/env python3
"""Completely reset this user's Pipelines installation; keep the source checkout."""
import argparse
import json
import os
from pathlib import Path
import platform
import re
import shutil
import signal
import subprocess
import sys
import time
LABEL = "net.a-wan.pipelines"
MARKER = "Managed by Pipelines native installer"
BUILD_VOLUMES = {"pipelines-flutter-pub", "pipelines-flutter-gradle", "pipelines-android-sdk",
"pipelines_pipelines-data", "pipelines_ntfy-data"}
class Uninstall:
def __init__(self, *, home=None, repo=None, environ=None, runner=subprocess.run, system=None):
self.home = Path(home or Path.home()).resolve()
self.repo = Path(repo or Path(__file__).resolve().parents[1]).resolve()
self.env = dict(os.environ if environ is None else environ)
self.runner = runner
self.system = system or platform.system()
self.config = Path(self.env.get("XDG_CONFIG_HOME") or self.home / ".config")
self.prefix = Path(self.env.get("PIPELINES_PREFIX") or self.home / ".local/share/pipelines").expanduser().absolute()
self.manifest = {}
def command(self, args, required=True):
result = self.runner(args, capture_output=True, text=True, timeout=120)
if required and result.returncode:
raise RuntimeError(f"{args[0]} {args[1]} failed; no further resources were removed")
return result
def safe(self, path):
path = Path(path).absolute()
resolved = path.resolve()
if path.is_symlink():
raise ValueError(f"Refusing a symlinked removal root: {path}")
if resolved == Path('/') or resolved in (self.home, self.repo) or resolved in self.home.parents or resolved in self.repo.parents:
raise ValueError(f"Refusing an unsafe removal path: {path}")
generated = ("app/build", "app/.dart_tool", "app/android/.gradle", "app/macos/Pods",
"app/macos/Flutter/ephemeral", "app/linux/flutter/ephemeral")
if resolved.is_relative_to(self.repo) and resolved not in {self.repo / p for p in generated}:
raise ValueError(f"Refusing to remove source checkout content: {path}")
if path.exists() and path.stat().st_uid != os.getuid():
raise ValueError(f"Refusing a path owned by another user: {path}")
return path
def paths(self):
roots = {self.prefix, self.home / ".config/pipelines", self.config / "pipelines",
self.home / ".cache/pipelines",
Path(self.env.get("XDG_CACHE_HOME") or self.home / ".cache") / "pipelines",
Path(self.env.get("PIPELINES_APP_CACHE") or self.home / ".cache/pipelines/app-builds"),
self.config / "opencode/skills/pipelines",
Path(self.env.get("CLAUDE_CONFIG_DIR") or self.home / ".claude") / "skills/pipelines",
Path(self.env.get("CODEX_HOME") or self.home / ".codex") / "skills/pipelines",
self.repo / "app/build", self.repo / "app/.dart_tool", self.repo / "app/android/.gradle",
self.repo / "app/macos/Pods", self.repo / "app/macos/Flutter/ephemeral",
self.repo / "app/linux/flutter/ephemeral"}
recorded = self.manifest.get("opencode_env") or {}
if recorded.get("XDG_CONFIG_HOME"):
config = Path(recorded["XDG_CONFIG_HOME"])
roots.update((config / "pipelines", config / "opencode/skills/pipelines"))
if recorded.get("XDG_CACHE_HOME"):
roots.add(Path(recorded["XDG_CACHE_HOME"]) / "pipelines")
auth = (self.manifest.get("web") or {}).get("auth_file") or self.env.get("PIPELINES_WEB_AUTH_FILE")
if auth:
path = self.safe(Path(auth).expanduser().absolute())
# A custom credential file must actually be a Pipelines login store.
if path.exists():
data = json.loads(path.read_text())
if not isinstance(data, dict) or not isinstance(data.get("password"), str) or not isinstance(data.get("secret"), str):
raise ValueError("Custom web credentials are not a Pipelines password file")
roots.add(path)
return {self.safe(path) for path in roots}
def preflight(self):
if self.system not in ("Linux", "Darwin"):
raise ValueError("Uninstall supports Linux and macOS")
self.safe(self.prefix)
self.prefix = self.prefix.resolve()
manifest = self.prefix / "pipelines-install.json"
if manifest.exists():
self.safe(manifest)
self.manifest = json.loads(manifest.read_text())
if self.manifest.get("format") != 1 or self.manifest.get("prefix") != str(self.prefix):
raise ValueError("Invalid Pipelines installation manifest")
default = self.home / ".local/share/pipelines"
if self.prefix != default and self.prefix.exists() and not self.manifest:
if not (self.prefix / "bin/pipelines").is_file() or not (self.prefix / "lib/manage.py").is_file():
raise ValueError("Custom prefix has no recognizable Pipelines installation")
self.removals = self.paths()
self.unit = (self.config / f"systemd/user/{LABEL}.service" if self.system == "Linux"
else self.home / f"Library/LaunchAgents/{LABEL}.plist")
self.units = {self.unit}
if self.system == "Linux":
recorded = (self.manifest.get("opencode_env") or {}).get("XDG_CONFIG_HOME")
self.units.add(self.home / f".config/systemd/user/{LABEL}.service")
if recorded:
self.units.add(Path(recorded) / f"systemd/user/{LABEL}.service")
for unit in self.units:
self.safe(unit)
if unit.exists() and MARKER not in unit.read_text():
raise ValueError(f"Refusing an unmanaged service definition: {unit}")
try:
result = self.command(["docker", "info"], required=False)
except FileNotFoundError:
self.docker = False
else:
if result.returncode:
raise RuntimeError("Start Docker, then rerun ./uninstall to remove Pipelines build caches")
self.docker = True
def stop(self):
if self.system == "Linux":
self.command(["systemctl", "--user", "disable", "--now", LABEL + ".service"], required=any(unit.exists() for unit in self.units))
else:
result = self.command(["launchctl", "bootout", f"gui/{os.getuid()}/{LABEL}"], required=False)
if result.returncode not in (0, 3, 113):
raise RuntimeError("Could not stop the Pipelines login service")
# Retained chat hosts intentionally survive ordinary restarts. A full
# uninstall also stops these owned processes before deleting their data.
result = self.command(["ps", "-U", str(os.getuid()), "-o", "pid=,command="])
executables = [str(self.prefix / "bin" / name) for name in
("pipelines-server", "pipelines-claude-host", "pipelines-codex-host", "ntfy")]
scripts = [str(self.prefix / p) for p in ("lib/manage.py", "lib/web/serve.mjs")]
owned = []
for line in result.stdout.splitlines():
parts = line.strip().split(None, 1)
if len(parts) != 2 or not parts[0].isdigit():
continue
pid, command = int(parts[0]), parts[1]
binary = any(command == exe or command.startswith(exe + " ") for exe in executables)
script = any(" " + name + " " in " " + command + " " for name in scripts)
if pid > 1 and (binary or script):
owned.append(pid)
for pid in owned:
try:
os.kill(pid, signal.SIGTERM)
except ProcessLookupError:
pass
deadline = time.monotonic() + 90
while owned and time.monotonic() < deadline:
alive = []
for pid in owned:
try:
os.kill(pid, 0)
alive.append(pid)
except ProcessLookupError:
pass
owned = alive
if owned:
time.sleep(0.1)
if owned:
raise RuntimeError("A retained Pipelines process has not exited; data was retained. Rerun ./uninstall after it stops")
for unit in self.units:
unit.unlink(missing_ok=True)
if self.system == "Linux":
self.command(["systemctl", "--user", "daemon-reload"])
self.command(["systemctl", "--user", "reset-failed", LABEL + ".service"], required=False)
def clear_docker(self):
if not self.docker:
print("Docker is not installed; no Docker resources were queried.")
return
label = "label=com.docker.compose.project=pipelines"
for kind, query, action in (
("container", ["ps", "-aq", "--filter", label], ["rm", "-f"]),
("volume", ["volume", "ls", "-q", "--filter", label], ["volume", "rm"]),
):
names = self.command(["docker", *query]).stdout.split()
if any(not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*", n) for n in names):
raise ValueError(f"Unexpected Docker {kind} name")
if names:
self.command(["docker", *action, *names])
# Builder containers have no Compose label, but use only these images.
containers = self.command(["docker", "ps", "-a", "--format", "{{.ID}} {{.Image}}"]).stdout.splitlines()
builders = []
for line in containers:
fields = line.split()
if len(fields) == 2 and re.fullmatch(r"[0-9a-f]+", fields[0]) and re.fullmatch(r"pipelines(?:-flutter-(?:web|android|linux)|-pipelines)?:[A-Za-z0-9_.-]+", fields[1]):
builders.append(fields[0])
if builders:
self.command(["docker", "rm", "-f", *builders])
volumes = self.command(["docker", "volume", "ls", "--format", "{{.Name}}"]).stdout.split()
selected = sorted(BUILD_VOLUMES.intersection(volumes))
if selected:
self.command(["docker", "volume", "rm", *selected])
images = self.command(["docker", "image", "ls", "--format", "{{.Repository}}:{{.Tag}}"]).stdout.split()
selected = sorted({i for i in images if re.fullmatch(r"pipelines(?:-flutter-(?:web|android|linux)|-pipelines)?:[A-Za-z0-9_.-]+", i)})
if selected:
self.command(["docker", "image", "rm", *selected])
def run(self):
self.preflight()
print("Removing Pipelines services, sessions/history, password, configuration and build caches.")
self.stop()
self.clear_docker()
for path in sorted(self.removals, key=lambda p: len(p.parts), reverse=True):
self.safe(path)
if path.is_dir():
shutil.rmtree(path)
else:
path.unlink(missing_ok=True)
print("Pipelines reset complete. Source checkout and provider accounts retained. Run ./install for a fresh setup and password.")
def main():
if sys.version_info < (3, 9):
raise SystemExit("Python 3.9 or newer is required")
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--prefix", type=Path, help="Installation prefix (default: PIPELINES_PREFIX or ~/.local/share/pipelines)")
args = parser.parse_args()
env = dict(os.environ)
if args.prefix is not None:
env["PIPELINES_PREFIX"] = str(args.prefix)
Uninstall(environ=env).run()
if __name__ == "__main__":
try:
main()
except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired) as error:
sys.exit(f"Uninstall incomplete: {error}")
Executable
+3
View File
@@ -0,0 +1,3 @@
#!/bin/sh
set -eu
exec python3 "$(dirname "$0")/scripts/uninstall.py" "$@"