Add portreaper extension

[fanhefeng]

Description

Portreaper finds orphaned dev-server processes squatting on your ports and lets you reap them from Raycast.

You kill a terminal, but the vite / node / cargo run it launched keeps running — reparented to the OS, still holding port 3000. Next time you npm run dev the port is "already in use" and you have no idea which ghost to kill.

This is not a generic port viewer. Its job is to decide which listeners are orphaned dev-server zombies, so you act on a verdict instead of a raw process list:

• Every TCP listener, plus orphaned dev processes that hold no port at all — a leftover electron-vite main process, adopted by launchd after its parent node died, is invisible to a port scan but is exactly the kind of residue worth clearing.
• A verdict with its evidence. Suspects are tiered confirmed / likely / possible, and each row shows the signals behind the call (reparented to PID 1, launcher chain ends at a dead shell, dead terminal session, dev-server command line, duplicate instance of the same project).
• Exemptions applied automatically — anything managed by launchd, brew services, or pm2, and anything installed in a standard location, is never flagged.
• Star to exempt permanently. A daemon you detached on purpose is behaviorally identical to an accidental zombie; star it once and it stops being flagged.

Terminating always asks for confirmation, and the engine re-checks the process creation time immediately before killing — if it moved, the kill is refused. That closes the window where a PID gets recycled between looking at the list and pressing Enter.

The classification engine is shared with the Portreaper macOS menubar app; both frontends read the same whitelist file, so a star added here shows up in the desktop app's next scan and vice versa. The desktop app is optional — this extension works standalone.

About the binary dependency (please read)

The classification logic lives in a small Rust CLI, portreaper-cli. On first run the extension downloads it and verifies it against the project's published SHA-256 checksum; a binary that fails verification is deleted, never executed. Nothing is installed system-wide — it lives in the extension's own support directory, and the UI states plainly what it is doing while downloading.

This follows the "Binary Dependencies" guidance — downloaded from a trusted location with hash verification, rather than bundling an opaque binary:

• Source: the project's own GitHub Releases (fanhefeng/portreaper), built by a public GitHub Actions workflow — traceable build sources, not an opaque blob.
• Integrity: SHA-256 checked against the release's published portreaper-cli-SHA256SUMS; mismatch ⇒ file removed and an error surfaced.
• Self-healing: if the cached copy later fails to execute (truncated download, arch change, lost exec bit) it is removed and re-fetched once.
• No user action required — the guidance explicitly asks extensions to avoid making users perform additional downloads.

Same pattern as recently approved extensions: glean-search #28995, lumen #28909, and speedtest.

platforms is ["macOS"] only: the CLI's Windows leg has no manual QA yet, so the extension does not claim support it cannot back.

Screencast

Screenshots are in metadata/ (light theme, 2000×1250):

1. Filtered list — Suspects / Healthy grouping with confidence tags
2. Detail panel — the signals behind a verdict, PID, category, ports, uptime
3. Action panel — Terminate / Force Kill styled as destructive, plus Star
4. Confirmation dialog — names the process, PID and port before terminating

The suspects shown are three deliberately orphaned node dev servers created for the capture; the list is filtered to node so the screenshots do not expose the unrelated applications running on the author's machine.

Checklist

• I read the extension guidelines
• I read the documentation about publishing
• I ran npm run build and tested this distribution build in Raycast
• I checked that files in the assets folder are used by the extension itself
• I checked that assets used by the README are placed outside of the metadata folder

Additionally verified on a real machine: first-run download + SHA-256 verification end to end (all cached and local copies removed to simulate a fresh install — the re-downloaded binary's digest matched the published manifest byte for byte), scan and grouping, detail panel, action panel, terminate confirmation, search filtering, and the no-port orphan case.

[raycastbot]

Congratulations on your new Raycast extension! 🚀

We're currently experiencing a high volume of incoming requests. As a result, the initial review may take up to 15 business days.

Once the PR is approved and merged, the extension will be available on our Store.

[greptile-apps]

Greptile Summary

The PR adds Portreaper, a macOS Raycast extension that downloads and verifies its Rust classification engine before scanning and managing orphaned development processes.

• Adds process scanning, verdict filtering, details, termination, and shared-whitelist actions.
• Adds managed CLI discovery, verified installation, compatibility recovery, and user-facing failure states.
• Adds the extension manifest, documentation, changelog, icon, and Store screenshots.

Confidence Score: 4/5

The PR does not yet appear safe to merge because concurrent recovery can remove a newly installed CLI and leave scans failing or the managed executable absent.

The previously reported recovery race remains: stale and current load() calls independently remove and reinstall the same managed path, while request IDs protect only React state updates and do not coordinate those filesystem operations.

Files Needing Attention: extensions/portreaper/src/search-ports.tsx, extensions/portreaper/src/install.ts

Important Files Changed

Filename	Overview
extensions/portreaper/src/search-ports.tsx	Implements the primary UI and process-management lifecycle; overlapping managed-CLI recoveries still mutate one shared executable path without serialization.
extensions/portreaper/src/install.ts	Downloads, checksum-verifies, and atomically installs the platform-specific CLI, but installation is not coordinated across concurrent callers.
extensions/portreaper/src/cli.ts	Defines the CLI schema, discovery, scan, termination, and whitelist process boundary.
extensions/portreaper/package.json	Defines a macOS view command, valid extension metadata, dependencies, and the corrected title-cased CLI-path preference.
extensions/portreaper/CHANGELOG.md	Adds an initial release entry using the required merge-date placeholder.

_{Reviews (6): Last reviewed commit: "Update portreaper extension" | Re-trigger Greptile}

[fanhefeng]

Thanks for the review — all three findings were valid and are fixed in 22a742f0.

1. Schema-incompatible cached CLI could not be replaced. Correct, and this one was the real bug. verifyCli() only runs --version, so a stale-but-runnable managed copy passes; scan() then rejects the schema and Retry keeps selecting the same binary — a dead end from the user's side. Now a SchemaMismatchError fetches a fresh copy, reusing the existing replace an unusable copy path. Two deliberate limits: it only replaces our own downloaded copy (a user-specified path is never deleted), and it retries once — if the fresh download still mismatches, the extension and the published CLI genuinely are different generations, and that must be reported rather than looped on.

2. Terminate/Force Kill shown for entries without an identity token. Correct. The maintainer notes already said those rows should not offer a kill entry point, but the code never implemented it — the actions rendered identically to working ones and could only produce a failure toast. The whole section is now gated on start_unix != null. The check inside doKill() stays: this gate is about not presenting the action, that one is about never proceeding even if some future call site presents it.

3. Preference title casing. Fixed: Portreaper CLI Path. The README and maintainer notes referenced the old label by name, so those were updated too — docs pointing at a label that no longer exists in the UI are worse than no docs.

Verified with tsc --noEmit, ray lint and ray build.

Unrelated but worth noting for reviewers: the engine this extension downloads was released as v0.9.0 today, which fixes a cross-frontend bug where a star added here stayed invisible to the desktop app — the starred process kept counting as a suspect there and stayed in the one-click sweep target set. The extension pulls from releases/latest, so no change was needed on this side.

[pernielsentikaer]

Similar extensions already in the Store

Automated first pass. Overlap is not a blocker on its own, but the README should make the difference clear.

• Port Manager (ports, 1,285 installs by @diegoleteliers10) — Monitor and manage open ports on your system with the ability to kill processes using specific ports.
  _{similarity 0.56}

[fanhefeng]

Thanks — the README now has a "How this differs from a port viewer" section that names Port Manager directly and links to its Store page.

Two things worth putting in front of the human reviewer:

The two extensions never meet. Port Manager declares "platforms": ["Windows"]; Portreaper declares "platforms": ["macOS"]. A macOS user does not see Port Manager in the Store, and vice versa. That is not an argument for accepting this one — just a fact that bounds the overlap.

The overlap that does exist is the list, not the product. Both render listening TCP ports and offer to kill what is behind one. Everything this extension is for sits after that point:

• A verdict, not a list. Each row is classified confirmed / likely / possible from orphan signals — reparented to PID 1, launcher chain terminating at a dead shell, dead tty session, duplicate instance of the same project — with hard exemptions for anything launchd, brew services, or pm2 already manages. A dev server with a live terminal behind it is never flagged. That classification, not the port list, is the deliverable.
• Processes with no port. It also lists orphaned dev processes holding no port at all — an electron-vite main process adopted by launchd after its parent node died, for example — which a port scan cannot reach by construction.
• Guarded termination. The engine captures each process's creation time during the scan and re-reads it in the instant before signalling; a drift means the PID was recycled and the kill is refused. After the signal it re-scans until the process is actually gone (~2.5s deadline) and reports "still running" honestly rather than painting a checkmark over a survivor. A suspended process (Ctrl-Z) also gets a SIGCONT right after SIGTERM — a caught SIGTERM is never processed while stopped, which is the single most common "I killed it and nothing happened" case.
• Shared engine. The classification lives in a Rust binary that the Portreaper desktop app drives as well, over one shared whitelist file, so a star added here is honoured in the desktop app's next scan.

The README section says all of this in user terms, including the line that matters most to someone choosing between the two: if you only want to free port 3000, a plain port viewer is the simpler tool.

[fanhefeng]

Updated again — a correction and a rewrite of the section from my last comment, plus a new icon.

The Port Manager link in that section was broken, and I should flag that directly. I built the URL from the GitHub handle in the duplicate-check comment (diegoleteliers10), but Store pages use the author field — the correct one is raycast.com/dleteliers_/ports. So when I said the README "links to its Store page," anyone who clicked it got a 404. Fixed and verified.

The section itself is rewritten. The first version conceded twice — at the top ("if that is your whole problem, a plain port viewer is the simpler tool") and again at the bottom ("if what you want is a list of ports, this is a heavy way to get one") — with a feature comparison in between. That reads as "yes, this overlaps, but it also does these extra things," which does not actually answer the duplicate question.

It now frames the two as answering different questions:

A port viewer answers "what is on port 3000?" — you already know something is in your way, and you need to find it and free it.

Portreaper answers "what is still running that nobody is responsible for?" — you are not looking up a port you already care about; you are finding out what the last three days of development left behind.

That framing does more work than the feature list did. The clearest example: Portreaper lists orphaned dev processes holding no port at all (an electron-vite main process adopted by launchd, listening on nothing). Under "free this port" that is out of scope by definition; under "what did I leave behind" it is the whole point. The concession is now half a sentence, and the section closes on the distinction rather than on self-deprecation.

Also in this push: a new extension icon, matching a redesign of the desktop app's icon.

[greptile-apps]

Concurrent recovery deletes the CLI

If two refresh, retry, or post-action loads overlap while the managed CLI is incompatible, both requests can delete and replace the same path because the stale-request check does not guard these filesystem mutations. A stale request can remove the newer request's successful installation, and a subsequent download failure leaves the extension without a CLI while scans during the deletion window fail with ENOENT.

Prompt To Fix With AI

This is a comment left during a code review.
Path: extensions/portreaper/src/search-ports.tsx
Line: 227-228

Comment:
**Concurrent recovery deletes the CLI**

If two refresh, retry, or post-action loads overlap while the managed CLI is incompatible, both requests can delete and replace the same path because the stale-request check does not guard these filesystem mutations. A stale request can remove the newer request's successful installation, and a subsequent download failure leaves the extension without a CLI while scans during the deletion window fail with `ENOENT`.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.