diff --git a/README.md b/README.md index af78df6d..488e8750 100644 --- a/README.md +++ b/README.md @@ -192,3 +192,6 @@ on another computer does not upload its files. When reporting a problem, include your OS, install mode, reproduction steps, `pipelines version --json` and `pipelines ping --json`. Redact credentials and 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. diff --git a/docs/install.md b/docs/install.md index 37abcd93..6bbe8a16 100644 --- a/docs/install.md +++ b/docs/install.md @@ -137,6 +137,24 @@ From `arguments()` in `scripts/setup-native.py`: Reinstalls keep the recorded authoring role unless you pass one of the two 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 ```sh diff --git a/docs/notes/full-reset-uninstall.md b/docs/notes/full-reset-uninstall.md new file mode 100644 index 00000000..18987fbf --- /dev/null +++ b/docs/notes/full-reset-uninstall.md @@ -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. diff --git a/scripts/test_uninstall.py b/scripts/test_uninstall.py index e293d47c..285d841d 100644 --- a/scripts/test_uninstall.py +++ b/scripts/test_uninstall.py @@ -5,6 +5,7 @@ from pathlib import Path import subprocess import tempfile import unittest +from unittest.mock import patch spec = importlib.util.spec_from_file_location("pipelines_uninstall", Path(__file__).with_name("uninstall.py")) 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) for unrelated in ("deadbeef", "baadf00d"): 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)) diff --git a/scripts/uninstall.py b/scripts/uninstall.py new file mode 100644 index 00000000..90da20a8 --- /dev/null +++ b/scripts/uninstall.py @@ -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}") diff --git a/uninstall b/uninstall new file mode 100755 index 00000000..c2eb7dad --- /dev/null +++ b/uninstall @@ -0,0 +1,3 @@ +#!/bin/sh +set -eu +exec python3 "$(dirname "$0")/scripts/uninstall.py" "$@"