Skip to content

Run declared plugin cleanup before removal - #11470

Open
antongisli wants to merge 1 commit into
omacom:quattrofrom
antongisli:plugin-uninstall-hook
Open

antongisli wants to merge 1 commit into
omacom:quattrofrom
antongisli:plugin-uninstall-hook

Conversation

@antongisli

Copy link
Copy Markdown

Why

Plugins can create local state outside their checkout after the user enables and sets them up: user services, agent registrations, credentials and private runtime caches. Today omarchy plugin remove only unloads/removes the checkout, so removal from the menu or an agent can leave that setup behind even when the plugin provides its own complete uninstall UI.

Proposed contract

  • Optional entryPoints.uninstall names a repository-local executable. Add/update validate it but never run it.
  • Removal discloses execution of unsandboxed plugin code and obtains confirmation. --yes explicitly approves cleanup and is the only argument passed through to the hook.
  • Disable the plugin, run cleanup synchronously as the current user, then remove/back up its files and rescan. A failed disable or nonzero cleanup result stops removal; the checkout remains available for retry. Cleanup itself is not transactional and may already have made changes.
  • OMARCHY_PLUGIN_REMOVAL_ID and OMARCHY_PLUGIN_DIR let a plugin share an implementation with its own uninstall UI without recursively removing itself.
  • --skip-cleanup is an explicit recovery/untrusted-code escape hatch and warns about leftovers. Symlinked checkouts are unlinked without executing a hook.

The shared path validator rejects absolute/traversing paths, control characters, non-string values, missing/non-executable files and symlink components. Removal revalidates the approved entry point before execution. No install, update, disable or shell-reload hooks are added, and Omarchy never elevates the hook itself.

The documentation asks plugin authors to make cleanup idempotent, preserve shared tools and access keys by default, disclose cloud-resource/billing boundaries, and return nonzero on cancellation. These are author responsibilities, not a new sandbox or a guarantee enforced by the host.

Tests

  • New removal suite: 12 passing checks, including the interactive confirmation/cancellation path through a private PTY, failure/retry, IPC-level disable failure, explicit bypass, symlinks, malformed paths and recursive removal.
  • Existing plugin validation and other plugin suites pass; CLI routing/metadata suite passes.
  • Ran ./test/all on Linux in an isolated home with no graphical session: 231/237 shell test files passed. The six failures reproduce on unmodified base 31bd80daa4613ffdee995ac27467fce5a2990806: ascii-test, branding-about-animation-test, three suites requiring a sibling omarchy-pkgs checkout (config, snapper, unowned-system-paths), and locate-test after the agent-scanner tests create .pyc files under bin/. The focused removal/validation suites were rerun after the final disable-result check.
  • Cross-repository smoke tests with the Nebius plugin exercise the real remove command plus the same uninstaller from its panel command and stdio MCP agent tool, using temporary homes and fake shell IPC/services/cloud data. All three routes clean the declared local state and preserve access keys/unrelated data. Canceling the plugin cleanup retains its files.

No running desktop, installed Omarchy files or real cloud resources were changed by these tests. This PR proposes the host API; downstream plugins must opt in, and existing Omarchy releases do not gain cleanup behavior until it ships.

@llstrk

llstrk commented Oct 1, 2026

Copy link
Copy Markdown

Automated AI review

Community review: Independent automated community review, unaffiliated with the Omarchy team, intended to help prepare PRs for their review.

Outcome: Some plugins without an uninstall hook now need --skip-cleanup to be removed.

Some plugins without a hook are refused

omarchy-plugin-uninstall-path (lines 22-24) requires a regular manifest with an entryPoints object before checking whether uninstall is declared, and removal calls it for every non-symlinked folder with a manifest.json unless --skip-cleanup is given. A manifest without entryPoints (e.g. {"id":"acme.legacy"}) or a symlinked manifest.json fails with invalid uninstall entry point; the merge base removed it. Impact: this contradicts docs/plugin-uninstall.md ("Plugins without the entry point keep the existing removal behavior") and breaks the remove tests of open #13743.

Suggested change: after refusing unparseable JSON, exit 0 unless try (.entryPoints | has("uninstall")) catch false holds, and only then require a regular manifest.

Reproducer: hookless plugin refused (fails at cba9e5d)

Reproducer: removal now refuses a hookless plugin whose manifest has no entryPoints object

Test file in the style of test/shell.d/plugin-remove-test.sh (save as test/shell.d/plugin-remove-legacy-test.sh):

#!/bin/bash

set -euo pipefail
source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
require_command jq

test_dir=$(mktemp -d)
trap 'rm -rf -- "$test_dir"' EXIT
mkdir -p "$test_dir/stubs"
cat >"$test_dir/stubs/omarchy-shell" <<'STUB'
#!/bin/bash
[[ $2 == "listPlugins" ]] && echo '[]'
exit 0
STUB
chmod +x "$test_dir/stubs/omarchy-shell"

# A leftover folder whose manifest the shell never accepted (no entryPoints
# object), so it declares no uninstall entry point.
plugin="$test_dir/home/.config/omarchy/plugins/acme.legacy"
mkdir -p "$plugin/.git"
printf '{"id":"acme.legacy"}\n' >"$plugin/manifest.json"

output=$(HOME="$test_dir/home" OMARCHY_PATH="$ROOT" PATH="$test_dir/stubs:$ROOT/bin:$PATH" \
  "$ROOT/bin/omarchy-plugin-remove" acme.legacy --yes 2>&1) ||
  fail "a plugin without an uninstall entry point is removed as before" "$output"
[[ ! -e $plugin ]] || fail "the plugin folder is removed"
pass "a plugin without an uninstall entry point is removed as before"

Output at the PR head (cba9e5d), bash test/shell.d/plugin-remove-legacy-test.sh, exit 1:

omarchy-plugin-uninstall-path: invalid manifest
omarchy-plugin-remove: invalid uninstall entry point; inspect it or use --skip-cleanup to remove without running plugin code
not ok - a plugin without an uninstall entry point is removed as before

Output at the merge base (31bd80d), exit 0:

ok - a plugin without an uninstall entry point is removed as before

Output at the head with the suggested helper change (check for entryPoints.uninstall before requiring an entryPoints object), exit 0; the PR's own plugin-remove-test.sh (12 checks) and plugin-validate-test.sh also pass with that change:

ok - a plugin without an uninstall entry point is removed as before

The same refusal makes open PR #13743's test/shell.d/plugin-lifecycle-hooks-test.sh fail when both PRs are merged onto quattro 8b4eae6 (its fixtures use {"id":"acme.gone"} manifests). Actual output on the combined tree, exit 1:

ok - plugin add fires plugin-added once the clone is in place
ok - plugin-added fires before the shell rescan
ok - plugin add fires no plugin-added when the add fails
ok - plugin-added fires before the rescan and the optional enable
omarchy-plugin-uninstall-path: invalid manifest
omarchy-plugin-remove: invalid uninstall entry point; inspect it or use --skip-cleanup to remove without running plugin code
not ok - plugin remove succeeds

On quattro plus #13743 alone the same file passes all 9 checks.

Related open PRs
Details

Verified (at cba9e5d, synthetic HOME, stubbed omarchy-shell and gum):

  • Order is disable, revalidate, hook, remove or back up, rescan; the hook runs in the plugin directory with both environment variables set.
  • A failed hook keeps the files and skips the rescan, and a retry completes. A disable answer other than ok stops before the hook.
  • Non-interactive removal without --yes, --skip-cleanup and symlinked folders run no plugin code.
  • The new test passes 12/12 at the head and fails on the base code; the existing plugin suites pass.

Optional notes:

  • Optional test improvement: removing $entry != *..* from the helper leaves all 12 checks passing, because the ../outside and bin/../cleanup cases point at files that do not exist. A case with an existing target catches it (reproducer below).
  • Declining the combined prompt aborts with omarchy-plugin-remove: aborted and does not mention --skip-cleanup, and the Setup > Plugins > Remove menu passes no flags. Naming the flag in the decline message would show a way forward.
  • docs/omarchy-shell.md on the base branch quattro says "Entry points are QML Items" (line 52) and that --yes skips every prompt (line 91). Mentioning the uninstall hook there would tell plugin authors that this entry point is an executable and that --yes now also approves running it.
Reproducer: untested `..` guard (passes at cba9e5d, fails on the mutant)

Reproducer: the .. guard in omarchy-plugin-uninstall-path is not exercised by the PR's test

This is a test-strength note, not a behaviour bug: at the PR head the guard works. The PR's traversal cases ("../outside", "bin/../cleanup") point at files that do not exist, so they are rejected by the final -f/-x check whether or not the .. check is present.

Mutation used (one line in bin/omarchy-plugin-uninstall-path):

-[[ $entry != /* && $entry != *..* && $entry != */ && $entry != *//* ]] || fail "uninstall entry point must be a safe relative path"
+[[ $entry != /* && $entry != */ && $entry != *//* ]] || fail "uninstall entry point must be a safe relative path"

With that mutation, the PR's bash test/shell.d/plugin-remove-test.sh still passes all 12 checks (exit 0):

ok - approved cleanup runs in the plugin directory before removal and rescan
ok - failed cleanup keeps the plugin for retry and a retry completes
ok - non-interactive removal without --yes executes no plugin code
ok - IPC-level disable failure cannot be mistaken for successful unload
ok - explicit cleanup bypass removes broken plugins without running code
ok - plugins without hooks retain existing backup behavior
ok - symlinked plugins are unlinked without executing their code
ok - unsafe paths, control characters and invalid hook types are rejected
ok - both executable and parent symlinks are rejected
ok - install and removal enforce the same executable hook contract
ok - recursive self-removal fails before cleanup
ok - interactive confirmation discloses execution and cancellation runs no code

A case whose escape target exists catches it (save as test/shell.d/plugin-remove-escape-test.sh):

#!/bin/bash

set -euo pipefail
source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
require_command jq

test_dir=$(mktemp -d)
trap 'rm -rf -- "$test_dir"' EXIT
mkdir -p "$test_dir/stubs"
cat >"$test_dir/stubs/omarchy-shell" <<'STUB'
#!/bin/bash
[[ $2 == "listPlugins" ]] && echo '[]'
exit 0
STUB
chmod +x "$test_dir/stubs/omarchy-shell"

# The escape target exists and is executable, so only the '..' guard can
# reject it.
home="$test_dir/home"
plugins="$home/.config/omarchy/plugins"
plugin="$plugins/acme.test"
mkdir -p "$plugin"
touch "$plugin/Widget.qml" "$home/external-setup"
printf '#!/bin/bash\nrm -- "$HOME/external-setup"\n' >"$plugins/outside"
chmod +x "$plugins/outside"
printf '%s\n' '{"schemaVersion":1,"id":"acme.test","name":"Test","version":"1","kinds":["bar-widget"],"entryPoints":{"barWidget":"Widget.qml","uninstall":"../outside"}}' >"$plugin/manifest.json"

output=$(HOME="$home" OMARCHY_PATH="$ROOT" PATH="$test_dir/stubs:$ROOT/bin:$PATH" \
  "$ROOT/bin/omarchy-plugin-remove" acme.test --yes 2>&1) &&
  fail "an existing parent-directory hook path is rejected" "$output"
[[ -f $home/external-setup && -f $plugin/manifest.json ]] ||
  fail "an escaping hook never runs"
pass "an existing parent-directory hook path is rejected"

At the PR head, exit 0:

ok - an existing parent-directory hook path is rejected

With the mutation above, exit 1 (the outside script ran and the plugin was removed):

Cleanup executes unsandboxed plugin code. Review it before approving.
Running cleanup for acme.test...
Cleanup completed for acme.test.
Removed acme.test. Backup at: /tmp/tmp.UHDX7KGWXb/home/.config/omarchy/plugins/.acme.test.bak.20261001051831
not ok - an existing parent-directory hook path is rejected

Review information

Test scope: Source and sandbox tests with stubbed shell IPC, at cba9e5d; no live desktop.

AI process: Opus 5.5 Medium coordination and synthesis, Opus 5.5 Xhigh technical review and final fact check, GPT 6 Sol Xhigh search for related issues, Opus 5.5 Medium editorial check.

Opt out: To stop receiving these reviews, reply to this comment saying so.

@jandrusk

Copy link
Copy Markdown

Nice addition — validated uninstall entry points, --skip-cleanup, and ordered disable→cleanup→remove coverage. Related UX nit on remove messaging is #13507. Ready for review from a skim.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants