rocketflare-plugins

The first-party plugins for Rocketflare.

These are not npm packages. A Rocketflare plugin is a git repository copied into your app — exactly like the kit itself — so its code lands as ordinary source you can read, debug and edit, translated into your app's own vocabulary on the way in. The price is that an upgrade is a patch rather than a version bump, which the kit's tooling already knows how to do.

The plugins

Each plugin has its own README with what it adds, requirements, install and first-run steps, who sees what and its known gaps. They are also published at rocketflare.dev/plugins.

Plugin	What it adds	Needs
analytics	Dashboards, tenant-scoped drizzle-cube cubes at /cubejs-api and /mcp, an hourly fact table, CLI, and four analytics-* agent skills. Installed by the kit's bootstrap	kit 0.17.1
web-knowledge	web_search and fetch_page tools for agents and chat on each organisation's own key (Tavily, Brave, Exa, Serper, Firecrawl), Settings → Web search	kit 0.9.0
connectors	Organisation connections: admin consent once, then directory and calendar sync every 15 minutes; Settings → Connections, My calendar, CLI and the connectors setup skill	kit 0.13.0 and a provider
m365	Microsoft 365 as a connectors provider: Entra admin consent, app-only Graph delta sync of users, groups and calendars	kit 0.12.0 and connectors
issue-reports	Ideas & issues: anyone talks a bug or an idea through with an agent that asks until it is clear, checks for a duplicate, and logs it as a GitHub issue (or a comment) once they approve the draft	kit 0.21.0 and a GitHub token
inbox	Inbound email through Cloudflare Email Routing: per-organisation address and sender allow-list, SPF/DKIM/DMARC checks, parsed bodies and attachments, Gmail/Proton forwarding-confirmation codes, an Inbox page, CLI, read-only agent tools, and an inbox:consumers extension other plugins build on	kit 0.22.0 and Email Routing on the domain
freeagent	FreeAgent (UK accounting) per organisation: OAuth connection, a 30-minute incremental mirror of bank transactions, explanations, categories, contacts, bills and invoices, Settings → FreeAgent and a FreeAgent page, read tools plus approval-gated write tools for agents, analytics cubes, CLI, a service API and a freeagent:sync-listeners extension for plugins built on top	kit 0.21.0 and a FreeAgent app

Installing one

# Read the plan first — it always prints and stops.
pnpm plugin add https://github.com/rocketflare-dev/rocketflare-plugins.git@3.8.1 --subdir plugins/analytics
# Then install it.
pnpm plugin add https://github.com/rocketflare-dev/rocketflare-plugins.git@3.8.1 --subdir plugins/analytics --apply
# The HOST generates the migration. Always.
pnpm db:generate --name plugin-analytics-<version> && pnpm db:migrate

--subdir is what tells pnpm plugin add which plugin in this repository you mean; each plugin also records its own subdirectory in its rocketflare-plugin.json, so pnpm plugin upgrade <id> later needs no flag.

Installing a plugin gives it full Worker and database access — it is as trusting as merging a pull request — which is why every command prints its plan and waits for --apply.

Layout

rocketflare-plugins/
  package.json                    the ONE version for the whole repository
  CHANGELOG.md                    the human index; the porting notes live per plugin
  scripts/                        the kit's release tooling, ONE copy (see below)
  .github/workflows/ci.yml        one job per plugin, calling the kit's reusable workflow
  plugins/<id>/
    rocketflare-plugin.json       what makes a directory a plugin
    apps/web/src/plugins/<id>/**  }
    packages/shared/src/plugins/<id>/**  }  mirrors the host tree exactly
    apps/cli/src/plugins/<id>/**  }
    docs/upgrades/*.md            one porting note per release

Each plugins/<id>/ mirrors the host tree exactly, because that is what the kit's installer expects: classifyPluginFile refuses any path outside apps/web/src/plugins/<id>/, packages/shared/src/plugins/<id>/, apps/cli/src/plugins/<id>/ and docs/plugins/<id>/ once the subdir prefix has been stripped. A plugin ships no migration, no wrangler toml and no package.json — those three are the host's, always.

A plugin's release notes live in plugins/<id>/docs/upgrades/ and nowhere else. pnpm plugin add copies them to the host's docs/plugins/<id>/upgrades/, and pnpm plugin export copies that host directory back verbatim. After an export, delete plugins/<id>/docs/plugins/ (find plugins -path '*docs/plugins*' should print nothing): that copy duplicates the notes at the same host path, and it is how 3.6.0 shipped two of them.

The plugin API

A plugin's compatibility with a kit is observed, not declared. pnpm plugin export derives the manifest's uses block from the plugin's actual imports, and pnpm plugin add checks it against the kit's surface ledger (docs/plugin-api.md in the kit) before copying anything. The one declared number is the top-level minKit, the oldest kit release the plugin may be installed into. requires.kit and requires.pluginApi are gone and are refused by name.

One version, one tag

Every plugin here ships at the repository's version and is tagged plain X.Y.Z — no tag prefixes, no per-plugin version namespacing. A release cuts every plugin at once, whether or not its own files changed.

The trade is deliberate. Independent versions would mean prefixed tags (analytics-v1.3.0), a resolver to match them, and a matrix of which plugin versions have ever been proved against each other. Lockstep costs an occasional no-op version bump and buys one answer to "which release am I on" and one CI run that proves the whole set against a kit ref.

The shared tooling

scripts/ holds the kit's release machinery — release.mjs, release-check.mjs and the five lib/*.mjs they import — in one copy, at the repository root.

That location is load-bearing. It sits outside every plugins/<id>/ directory, so classifyPluginFile never sees these files and they cannot leak into a host app by construction — where before, each plugin repository vendored its own copy and nothing kept the copies in step. They are maintained in the kit (rocketflare-dev/rocketflare, scripts/) and copied here; when the kit's move, copy them again rather than editing them in place.

Releasing

Every plugin ships at one version, so a release covers all of plugins/*, on a branch:

1. Give every plugin a non-empty docs/upgrades/unreleased.md. A plugin with no change of its own gets a "version stamps only" note (plugins/<id>/docs/upgrades/3.7.0.md is the pattern); release.mjs refuses an empty one.

2. Run the kit's release script with every plugin named. Without --plugin it finds no manifest at the root and exits 1:

   args=(); for p in plugins/*/; do args+=(--plugin "${p%/}"); done
   node scripts/release.mjs X.Y.Z "${args[@]}"

   It folds each unreleased.md into X.Y.Z.md, stamps every rocketflare-plugin.json, its anchor plugin.json and the root package.json, and prepends the CHANGELOG.md section.

3. Move the rocketflare-plugins.git@<previous> install refs in README.md and plugins/*/README.md to @X.Y.Z; the script does not touch them.

4. node scripts/release-check.mjs --tag X.Y.Z must report release-check ok.

5. Commit Release X.Y.Z, open a PR, and once it merges tag the merge commit X.Y.Z and push the tag.

Released history is never rewritten. Every app pins a commit of this repository; a force-push to a released tag orphans them.

CI

.github/workflows/ci.yml calls the kit's reusable plugin-ci.yml once for the whole repository, passing plugin_subdirs. For each plugin it reads that plugin's minKit and the newest kit release, and for each of the two clones that kit, installs this checkout into it, generates and applies the migrations the host owns, and runs the kit's whole gate, off one include-matrix: the floor an adopter may still be on, and the ceiling the kit has just reached.

The kit also dispatches kit-released here on every tag it cuts, and ci.yml listens for it: that run proves the plugins against the ref just released rather than re-resolving the same range, so a kit that moves under a plugin is discovered on the day rather than whenever somebody next pushes.

Failing at the FLOOR means the plugin has started using something the kit only gained later — raise minKit and release. Failing at the CEILING means the kit has moved under it: port the plugin.

Adding a plugin to this repository

Create plugins/<id>/ with a rocketflare-plugin.json and a README.md (the site publishes it) (id, version, repo pointing here, subdir: "plugins/<id>", minKit), mirror the host tree beneath it, add a row to the table above and a line to the plugin_subdirs array in ci.yml. Namespace everything with the id — tables <id>_*, job types <id>.x, query-key roots <id>:…, the API prefix /api/<id> — because two plugins have to be able to live in one app.

History

analytics was released from rocketflare-dev/rocketflare-plugin-analytics up to and including 1.0.2. That repository is unchanged and its tags still install; this one continues from there.

Licence

MIT, the same as the kit. See LICENSE.