Extensions system: third-party search providers and commands

[xarbit]

Working on adding an extension system to AppGrid so the community can ship new search providers and quick commands (web search, conversions, lookups, custom workflows) without touching the core.

What this looks like for users:

• Type a keyword in the search bar (gh, wiki, color, …) and the matching extension takes over the rest of the line and shows results.
• Every extension declares what it can do (network, clipboard, open links, …) and the install dialog spells it out in plain language before anything runs.

What becomes possible:

Community-requested prefixes like #124 (system status s:) and #125 (running processes p:) are exactly the shape this is designed for. Today they would have to land in the core; with extensions they become opt-in installs anyone can write and ship.

How well prove the API:

First step is converting some of AppGrids own prefix commands into extensions running on the same engine third parties will use. If the API can host our own features cleanly it can host yours. The launcher core (grid, search, favorites, categories) stays native; only the command-shaped pieces move.

Runtime and isolation:

The idea is to run extension code in QJSEngine, Qts built-in JavaScript engine. It ships inside Qt6Qml (zero new dependency) and starts with zero ambient authority, meaning no filesystem, no network, no shell, no node access by default. Anything an extension can do comes from a capability the manifest asked for and the user approved. Smaller attack surface than starting with a full runtime and clawing things back. The capability bridge maps cleanly onto Qt objects so the host code stays small and reviewable.

On top of the engine we could harden further by launching the extension host inside bubblewrap, the unprivileged sandbox Flatpak already uses under the hood. That gives an OS-level boundary (no home, no display socket, no D-Bus, no network unless the manifest grants it) so even if the engine were ever subverted the damage stays contained. Treated as an extra belt on top of the suspenders.

Why not Node/Bun + React the way Raycast and friends do it:

• Bundles a full JavaScript runtime AppGrid would have to ship, update, and security-patch across every distro package. QJSEngine is already linked.
• Pulls in the npm ecosystem with it. Every extension drags transitive dependencies, postinstall scripts, and the typosquatting / supply-chain surface that comes with that.
• Raycasts model trusts the store curation more than the extension. Ours is the inverse: assume the extension is hostile, lean on capability + sandbox boundaries first, curation second.
• React-style extension UIs need their own renderer and window per extension. Our extensions show results in the existing search list. Simpler contract, less to break, less to learn.

Tradeoff to be honest about: QJSEngine is ES2016, which is older than modern JavaScript and missing some library methods authors are used to. Extensions get written in TypeScript and the registry tooling transpiles down so this is mostly invisible to authors, but it is a real ceiling. If it ever becomes painful enough we revisit by adopting QuickJS-ng, but that costs a new C dependency every distro packager has to carry and a hand-written bridge, so its not the default.

Why this is worth doing:

• Keeps the launcher focused while letting the long tail of "wouldnt it be nice if it did X" live as opt-in.
• Lower barrier for contributors. New ideas land as extensions instead of patches against the core.
• Privacy and isolation are the whole point. AppGrid sees everything you type, an extension model has to take that seriously from day one.

Open ideas (not decided):

• A curated in-app registry where extensions are reviewed and installed with one click, similar in spirit to KDE Store or Raycast Store. Could also be just a github repo people clone from for the first cut. Will figure out what makes sense as we get closer.

Timing:

Starting this in the 1.9.0 cycle as soon as 1.8.0 ships.

Looking for thoughts and ideas. What would you want to build with this? What worries you about it?

[xarbit]

@Caelestis94 @Kingproone fyi, lets start the discussion :)

[Caelestis94]

I did some thinking, do excuse my use of lists here to structure my thoughts lol

1. Full AppGrid extension ecosystem (current proposal)

Pros

• Much lower barrier to entry than KDE/C++ plugins.
• Easier experimentation and community contributions.
• Better security model than arbitrary native plugins if capability + sandboxing is done well.
• Lets niche ideas live outside core.
• Faster iteration cycle.

Concerns

• Risk of rebuilding a parallel ecosystem to KRunner.

• Potential overlap/confusion (KRunner plugins vs AppGrid extensions.)

• Long-term maintenance burden:

  • API stability,
  • registry moderation,
  • sandbox edge cases,
  • extension compatibility.

• AppGrid today is still mostly a launcher/UI layer, so the long-term differentiation from KRunner is not fully clear yet.

---

2. Improve KRunner plugin contribution ergonomics instead

Instead of introducing a new extension runtime, reduce the friction around existing KDE/KRunner development.

Examples:

• devcontainer,
• bootstrap tooling,
• templates/examples,
• SDK/helper wrapper,
• better docs,
• hot reload/dev workflow improvements.

Pros

• Builds on existing KDE ecosystem instead of fragmenting it.

• Reuses mature KRunner infrastructure:

  • plugin system,
  • marketplace/distribution,
  • performance,
  • native integration.

• Avoids maintaining a second extension platform.

Concerns

• Even with good tooling, native Qt/KDE/C++ contribution still has a much higher barrier than JS/TS.
• Does not solve the “I just want to write a quick provider/workflow” use case as well as scripting would.

---

3. Hybrid / bridge approach

AppGrid exposes a lightweight extension layer, but leverages KRunner/KDE infrastructure underneath where possible instead of replacing it.

Example idea:

• AppGrid extensions are mostly orchestration/UI logic.
• Heavy lifting/search providers still come from KRunner or KDE services.
• AppGrid-specific APIs only exist where deeper launcher integration is actually needed.

Pros

• Keeps AppGrid extensible without fully becoming “another KRunner”.
• Lower contributor barrier while still aligning with KDE ecosystem.
• Avoids duplicating functionality already solved upstream.

Concerns

• May become awkward architecturally if KRunner internals are not designed to be consumed this way.
• Could end up adding complexity without fully escaping ecosystem overlap.

A full extension ecosystem makes more sense if AppGrid eventually grows beyond being tightly coupled to KDE/KRunner concepts. Right now though, AppGrid sits right in the middle of the KDE ecosystem, so there’s naturally a question of how much should extend existing KDE infrastructure vs build parallel abstractions on top of it. “When in Rome…” basically 😄

PS : Not that a full extension infra feature doesn't sound exciting to build, it does and that's the trap lol.

[xarbit]

@Caelestis94 if anything, the hybrid option is what i am talking about.

to be clear: this isn't about krunner. krunner stays as is, we already plug into it for
extended search, no plan to replace any of that or to do anything about its ecosystem.
i dont even want to replace it, i love it. its about extending appgrid where it makes
sense, to keep the core small. not about creating an ecosystem, not sure if that was clear.

[Caelestis94]

For my p: and s: examples specifically, I’m not sure how far a TS extension gets without native host APIs. Process management and system status would still need AppGrid to expose explicit capabilities over the bridge. So the extension system helps keep the workflow/UI outside core, but the underlying native capabilities still have to be designed and maintained in core.

[xarbit]

that is correct. we will need capabilities. QJSEngine is not capable of doing anything alone.

[Caelestis94]

Alright, I do like the idea ngl. I was an avid user of Raycast when I had my Macbook Pro, and in Windows I use the new Command Palette which offers the possibility to extend it with plugins also. That means we would need UI Primitives that the plugins can populate with structured return data like so :

return {
  view: "list",
  items: [
    {
      title: "firefox",
      subtitle: "PID 1234 · 812 MB RAM",
      icon: "firefox",
      badges: ["12% CPU"],
      actions: [
        { id: "kill", label: "Kill process", capability: "process.manage" }
      ]
    }
  ]
}

The core of the work really will be in how well the UI Primitives are built so as to allow as much flexibility and customizability as possible to the user. Which also means a well thought out SDK and Docs

[xarbit]

heads up.. I'm almost done refactoring the core application, which puts us in a position to actually consider this topic. A few small pieces remain, but this refactor was long overdue, and now the core functionality is finally in place.

[Kingproone]

Please send a ping when the git version becomes stable enough for testing, I wanna check for regressions!

[xarbit]

sure .. can do ..

[xarbit]

@Kingproone I'd say the refactoring is settled — it feels noticeably snappier to me. I also knocked out a few of the remaining issues. Whenever you're ready, please do a smoke test and check for regressions. Hopefully if anything turns up it'll only be minor :)

[xarbit]

Update Prototype (PoC)

@Caelestis94 @Kingproone

Been prototyping extension support and it's far enough along to share where it's headed. It's on a local branch, experimental,
and gated behind a build flag (off by default)... but the core loop works end to end.

The idea

Type a keyword + colon to hand the search bar over to an extension.. same opt-in feel as the existing i: / h: prefixes. For example:

• gh: kde/dolphin → GitHub repo details
• aur: yay → AUR search results
• sys: ssh → running services

The extension fetches/runs something, parses it, and returns a small description of what to show — AppGrid draws it.

How it works (high level)

• Extensions are plain JS (manifest.json + parse.mjs). They run in a QJSEngine that has no network, filesystem, or environment
  access on its own.
• Capabilities are host-provided and permission-gated. An extension only gets appgrid.fetch (network) or appgrid.run (commands)
  if its manifest asks for it. No permission → the function isn't reachable. That's the security model: absence, not a blocklist.
• Views are declarative, not code. An extension returns a tree of typed nodes (text, list, table, key/value, badges, buttons…),
  and a trusted renderer maps those to real UI. Extensions never ship QML or native code, so a bad/compromised extension can't
  paint arbitrary widgets or run arbitrary code.. it can only describe one of a fixed set of views.
• Queries run on a worker thread, so a slow network call never freezes the launcher.

What's done

• Keyword routing, the JS host, fetch + run, and view renderer.
• Three example extensions (GitHub, AUR, system services) that exercise every view type.
• Permission gating + tests covering the runtime.

Images

Code example

here is a example of how the parse.mjs currently looks like to search AUR packages, this is all that is needed:

export default {
    query(text) {
        const q = (text || "").trim()
        if (!q)
            return { view: { type: "text", text: "Type to search the AUR…", dim: true } }

        const res = appgrid.fetch(
            `https://aur.archlinux.org/rpc/v5/search/${encodeURIComponent(q)}`)
        const json = JSON.parse(res)
        const results = (json.results || [])
            .sort((a, b) => (b.NumVotes || 0) - (a.NumVotes || 0))
            .slice(0, 20)

        if (results.length === 0)
            return { view: { type: "text", text: `No AUR packages for "${q}".`, dim: true } }

        // Trim cell text so descriptions with stray whitespace don't throw
        // the table columns off; drop any result missing a package name.
        const rows = results
            .filter(p => (p.Name || "").trim().length > 0)
            .map(p => [
                (p.Name || "").trim(),
                (p.Version || "").trim(),
                String(p.NumVotes || 0),
                (p.Description || "").trim(),
            ])

        return {
            view: {
                type: "table",
                columns: ["Package", "Version", "Votes", "Description"],
                rows,
            },
        }
    },
}

The manifest looks like this:

{
  "schemaVersion": 1,
  "id": "dev.appgrid.ext.aur",
  "name": "AUR Search",
  "description": "Search the Arch User Repository, ranked by votes.",
  "version": "1.0.0",
  "author": "AppGrid Contributors",
  "license": "GPL-2.0-or-later",
  "keyword": "aur",
  "entry": "parse.mjs",
  "permissions": {
    "network": true,
    "openUrl": true
  }
}

[Caelestis94]

That's pretty much what I had in mind. Now I wonder if we shouldn't be able to define a config/setting space for these plugins, either via appgrid or an extension panel in the settings for appgrid itself, e.g I might want to use an extension that requires an API key.

[Caelestis94]

I myself actually had the idea of creating an extension that would interface with Home assistant and allow me to turn lights on and off lol, but id need a space to set the webhooks, credentials if required etc...

[xarbit]

Yeah, api keys or credential is on the list. HomeAssistant is actually a good example, will add that on the list too ..

The idea is not to over complicate it and to have a simple interface. It's not going to be a raycast or something like that.

I have to see if we can interface settings

[xarbit]

will not do.