Skip to content

Run declared plugin cleanup before removal - #11069

Open
tomismeta wants to merge 1 commit into
omacom:quattrofrom
tomismeta:feature/plugin-pre-remove-hook
Open

tomismeta wants to merge 1 commit into
omacom:quattrofrom
tomismeta:feature/plugin-pre-remove-hook

Conversation

@tomismeta

@tomismeta tomismeta commented Sep 10, 2026 •

Copy link
Copy Markdown

Why

Plugins can own registrations or other state outside their checkout. Removing the checkout first leaves that state behind and can remove the executable needed to clean it up.

Add one optional manifest declaration, hooks.preRemove, so a plugin can finish its own cleanup before Omarchy removes it. Once declared, successful cleanup is required for removal; there is no bypass flag.

Usage

{
  "hooks": {
    "preRemove": "bin/cleanup"
  }
}

Interactive removal asks separately for permission to run cleanup and confirmation to remove the plugin. --yes skips ordinary removal confirmation, not authorization to execute the hook. After reviewing the current executable, scripts can authorize both explicitly:

omarchy plugin remove <plugin-id> --yes --run-pre-remove

omarchy plugin validate <folder> validates the declaration without executing plugin code.

Behavior

  • Run cleanup before the CLI disables the plugin or deletes, unlinks, or moves its checkout, including disabled and never-enabled plugins.
  • Require an executable regular file inside the checkout. Reject absolute paths, .., control characters, and symlinks in the hook path; the installed plugin directory may itself link to a development checkout.
  • Snapshot the checkout identity, manifest contents, and hook identity and contents before prompting, then revalidate before execution. Changes, including adding or removing a declaration, abort removal.
  • Abort before CLI disable/removal on declined consent, invalid metadata, changed snapshots, failure to start, nonzero exit, signal termination, interrupted runner, or timeout. Completed cleanup effects are not rolled back; hooks must be safely retryable.
  • Require an explicit ok acknowledgment when disabling an enabled plugin. A rejected request or lost connection retains the checkout; cleanup may already have completed and runs again on retry.
  • Preserve the existing removal path when no hook is declared, without requiring execution authorization or a systemd user manager. An absent manifest remains removable for recovery; a present but malformed manifest blocks removal.

Execution

The hook runs directly as an executable, respecting its shebang rather than being sourced or forced through Bash. It receives no arguments, uses the physical checkout as its working directory, inherits the caller's environment and privileges, and reads standard input from /dev/null. Omarchy does not invoke sudo.

A transient systemd user service supervises the hook and its inherited cgroup, including remaining children after the hook leader exits. The runtime limit is 60 seconds, followed by a 5-second stop grace period. Execution requires a reachable systemd user manager; validation does not.

The caller's environment travels through a private pipe to an Omarchy-owned Python runner, not through command-line arguments or unit properties. The runner supplies the hook with standard input at EOF and writes a private completion receipt only after a normal zero exit. Removal requires both that receipt and successful supervised service completion; systemd's treatment of some signal deaths as successful is not sufficient. The helper removes its temporary completion record on exit.

This is unsandboxed plugin code. Snapshot checks are not atomic protection against hostile concurrent edits, and process supervision is not a sandbox. Hooks must clean up only their own state, wait for their work, and return zero only when cleanup is complete.

Scope

One pre-removal hook, shared validation/execution helper, private-environment runner, CLI integration, documentation, and regression coverage. No install/update hooks, activation ledger, package-management framework, or changes to individual plugins.

The diff is limited to generic plugin cleanup. It does not include VS Code test repairs, kernel fixture repairs, passwordless-sudo prerequisite documentation, or dependencies on Aperture, OMP, or a particular development environment.

Verification

This revision is based on quattro at 492b8837deea69663c7a5418871f07ed075a9686.

  • Standalone cleanup-runner regressions passed on macOS: environment-byte preservation, stdin isolation, normal completion, nonzero exit, launch failure, signal termination, and runner interruption. Changed shell scripts passed syntax checks.
  • Boundary smoke checks verified that a synthetic secret reached the real hook without appearing in supervisor arguments or the process listing, and that supervisor success without a completion receipt is rejected. The unavailable systemd execution boundary was substituted in these checks.
  • Fresh Linux/systemd verification of complete removal, unit metadata, cgroup supervision, and timeouts remains required. The earlier aggregate-suite results apply to the previous revision, not this update; no current full-suite or graphical acceptance result is claimed.

Context

@tomismeta

Copy link
Copy Markdown
Author

Refreshed this PR against current quattro (7b336b1b) without rewriting the published branch.

  • Preserved the consolidated shell/README.md and moved the cleanup contract into docs/omarchy-shell.md.
  • Fixed the disable acknowledgment: a transport-successful IPC reply of unknown now stops removal instead of deleting the checkout. Transport failures also retain the checkout. Cleanup remains before disable; completed effects are not rolled back, and retry reruns cleanup.
  • Added regression coverage for rejection, transport failure, git/symlink/plain checkout retention, and retry after completed cleanup. Adopted upstream's explicit test-skip reporting.

Focused suites, headless static coverage, and an isolated real-CLI/systemd failure/retry smoke passed, including real child supervision and timeout cases. The aggregate suite was run but is not green: the VS Code CLI assertion and three shell suites fail identically on pristine upstream in this environment. Exact failures and the base revision are recorded in the updated PR description; no unrelated tests were changed or suppressed.

I also reviewed #11470, which addresses the same external-state cleanup need. The contracts differ on hooks.preRemove versus entryPoints.uninstall, separate execution authorization versus --yes, cleanup-before-disable versus disable-before-cleanup, and cleanup bypass/development-symlink behavior. That proposal's explicit disable-result check exposed the gap corrected here.

Would maintainers prefer this failure-blocking pre-remove contract, the uninstall contract in #11470, or an aligned subset? I'd be happy to coordinate on one supported approach rather than introduce parallel lifecycle APIs. Aperture's marketplace review target remains frozen; this update does not claim its listing blocker is resolved.

@tomismeta

Copy link
Copy Markdown
Author

Verification follow-up: ./test/all now exits 0 on the refreshed branch. The CLI suite passed; all 263 shell test files completed without failures, with skipped checks explicitly reported in 15 files.

The repairs are isolated commits: 056a9805 removes retired VS Code file-layout/fixed-version assumptions and checks activation/settings preservation; d042ddb9 teaches the kernel pacman fixtures the real helpers' -- operand separator; 1d361a7b documents the package prerequisite. Production theme, kernel, and passwordless-sudo code was not changed.

Important qualification: the passwordless lifecycle contract depends on still-open omacom/omarchy-pkgs#257. The green run used current package master 6df9953d8f55050ca9ab2e4886426db7ef59b67f combined with #257 at 9b9a9c8e9cbc763c95fccbeeddcd3bd6b9d39174 in a disposable checkout. Both are necessary: master alone lacks the lifecycle scriptlets, and the older PR checkout alone lacks newer OWE assets required by the aggregate. Exact companion revisions and the merged tree are recorded in the PR description. No unmerged packages were installed.

The prior four aggregate failures are resolved under those documented prerequisites; no failure was skipped or suppressed to obtain this result. Aperture remains frozen.

@jandrusk

Copy link
Copy Markdown

This is a meaningful design addition (plugins running their own code at removal), so I think it needs a maintainer call before detailed review. A couple of notes to help with that:

  • Add plugin lifecycle hooks after add and remove #13743 adds plugin-added/plugin-removed lifecycle hooks around the same commands. It's not the same feature, but the two should agree on naming and ordering.
  • The branch also carries unrelated fixes: the VS Code test assumptions, the kernel pacman fixtures, and the docs/passwordless-sudo.md / omarchy-pkgs#257 prerequisite. Splitting those into their own PR would make this one much easier to review. It conflicts with quattro right now too.

Keep the change scoped to plugin cleanup, validation, documentation, and regression coverage. Transfer inherited environment through a private pipe and require normal zero-exit completion in addition to successful cgroup supervision.
@tomismeta
tomismeta force-pushed the feature/plugin-pre-remove-hook branch from 1d361a7 to abb5af7 Compare October 13, 2026 17:32
@tomismeta

Copy link
Copy Markdown
Author

Thanks @jandrusk — I’ve narrowed the PR to the generic pre-removal cleanup feature, its documentation, and regression coverage.

  • Removed the unrelated VS Code test repairs, kernel fixture repairs, and passwordless-sudo prerequisite documentation from the proposed changes.
  • Refreshed the feature onto quattro at 492b883; the retained changes applied without conflicts.
  • Kept the implementation and fixtures plugin-independent, with no Aperture or OMP dependency.

An adversarial review also identified two executor issues, now addressed:

  • The caller’s environment is passed through a private pipe rather than supervisor arguments or unit metadata.
  • Removal requires a completion receipt written only after the hook exits normally with status zero, in addition to successful service completion. This prevents systemd’s treatment of certain signal deaths as “success” from authorizing removal.

Aperture has since been accepted into the marketplace, so this proposal is no longer a prerequisite for its listing.

@dhh @ryanrhughes: would you prefer this failure-blocking hooks.preRemove contract, the alternative in #11470, or an aligned approach? I agree that naming and ordering should be coordinated with #13743’s separate lifecycle notifications before detailed review proceeds.

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.

3 participants