* init plugin * Spec-driven plugin loading Single source of truth for the plugin list lives in `executor.config.ts` (local + cloud). Each plugin's spec contributes its own HttpApiGroup, late-binding handlers Layer, and a Service tag the host satisfies — at boot for local, per request for cloud. New SDK helpers compose them: composePluginApi(plugins) composePluginHandlers(plugins, executor) // local: eager binding composePluginHandlerLayer(plugins) // cloud: leave Tag unbound providePluginExtensions(plugins)(executor) // cloud: per-request Frontend mirrors the same shape: `defineClientPlugin` declares pages, widgets, slot components, plus optional `sourcePlugin` / `secretProviderPlugin` contributions. The new `@executor-js/vite-plugin` reads `executor.config.ts` and emits a `virtual:executor/plugins-client` module from each plugin's `./client` export. The host wraps once with `<ExecutorPluginsProvider>` at the route root; pages call `useSourcePlugins()` / `useSecretProviderPlugins()` / `useClientPlugins()` instead of importing from any per-app aggregator. The SDK ships re-exports of Effect, Schema, HttpApi*, plus reactive primitives on the client side, so plugin authors can stay within `@executor-js/sdk` and `@executor-js/sdk/client` without reaching for `effect/*` directly. Each plugin declares two strings: `id` for runtime ergonomics (`executor.openapi.foo()`) and `packageName` for build-time resolution (`${packageName}/client`). No transforms, no scope conventions, no fallback magic. The Vite plugin warns loudly if `packageName` is set but unresolvable so typos fail visibly. Six existing plugins migrated (openapi, mcp, graphql, google-discovery, onepassword, workos-vault). New plugin-example serves as a canary — shared HttpApiGroup, server with extension/routes/handlers, client contributing a navbar page through the catch-all `/plugins/$pluginId/$` route. Local + cloud servers no longer manually wire each plugin's `*Group` / `*Handlers` / `*ExtensionService`; cloud retains a few type-only `*ExtensionService` imports for the per-request middleware's `provides` clause (framework requires static Tag identifiers there). Routes/shells/pages have zero plugin imports. Adding a plugin is a single edit to `executor.config.ts` plus a Vite restart. * Address PR feedback: derive types from plugin tuple, drop fanout - composePluginApi<TPlugins> now returns precisely typed HttpApi<"executor", CoreGroups | PluginGroups<TPlugins>> via a new TGroup generic on PluginSpec — cloud no longer imports OpenApiGroup, McpGroup, GraphqlGroup as types just to recover the API shape. - Cloud middleware provides clauses use PluginExtensionServices<typeof cloudPlugins> instead of importing each plugin's *ExtensionService type directly. Single tuple drives both runtime and types. - createPluginAtomClient reads plugin id from group.identifier — no more pluginId duplication at every call site. - defineExecutorConfig infers TDeps from the factory parameter, so apps annotate their deps inline (interface CloudPluginDeps {...} on the factory) instead of declare-module-augmenting a global ConfigPluginDeps interface. - cloud-plugins.ts holds the single executorConfig.plugins({}) call shared by protected-layers, protected, and the test harness. - Restore the apps/local blob table (accidental delete). * PR feedback round 2: optional deps, generic collapse, client test - ExecutorPluginsFactory takes `deps?` so the schema-gen CLI and Vite plugin call `config.plugins()` (not `config.plugins({})`). Apps annotate their deps inline with `({…}: Deps = {})`. - PluginSpec / Plugin defaults are now `any` for the wide slots so `AnyPlugin = Plugin<string>` covers any concrete plugin without a cascade of `any, any, any, …` at every callsite. PluginExtensions drops the same cascade. - Add `client.test.ts` covering the pluginId-from-group.identifier change: Service Tag key ("Plugin_<id>Client"), distinct keys per group, atom factories reachable. * Fix CI: lint, typecheck, and empty-test-suite failures - Add `passWithNoTests: true` vitest configs for the new vite-plugin and example plugin packages — they have no tests yet and were exiting non-zero on `vitest run`. - Add `bun-types` devDep to plugin-example so its tsconfig (`types: ["bun-types", "node"]`) resolves on CI. - Fix `aBody`/`bBody` `unknown` typecheck error in cloud/api.request-scope.node.test.ts (pre-existing on main). - Annotate the three `Layer.empty as unknown as …` widenings in plugin-routes.ts with `oxlint-disable-next-line executor/no-double-cast` + a one-line reason — TS can't witness that `Layer.empty` matches the computed merged-handler type through Layer's variance markers. - Suppress react/forbid-elements on the example plugin's raw `<input>` / `<button>` (the example demonstrates the SDK without depending on `@executor-js/react`'s component lib) and pass an explicit empty `reactivityKeys: []` on the demo mutation to satisfy the require-reactivity-keys rule. * Fix Cloudflare cloud build: pre-build vite-plugin via turbo Cloudflare's `vite build` runs through Node, which externalizes the workspace `@executor-js/vite-plugin` dep and then can't load its `./src/index.ts` source (Node ESM rejects `.ts`). Two coordinated fixes: - vite-plugin's exports are now condition-aware: `bun` keeps the TS source path (zero-build dev/test loop in Bun), `default` falls back to `./dist/index.js` for any non-Bun resolver (Node, the Cloudflare build). - cloud's `build` script now runs `turbo run build --filter @executor-js/vite-plugin && vite build` so the dist/ exists by the time vite resolves the import. Turbo caches the build, so repeated invocations are no-ops. * Pre-build vite-plugin for the local app's preview tarball build The CI's Build-preview-binary job runs `bunx --bun vite build` on `apps/local`. With vite-plugin's new condition-aware exports, Vite falls back to `default → ./dist/index.js`, which doesn't exist without a build. Mirror the cloud app's fix: prefix the build with `turbo run build --filter @executor-js/vite-plugin`. Turbo caches the artifact, so re-runs are no-ops. * Stop loading the example plugin in the local app The plugin package itself stays in the workspace as a reference implementation; just unwiring it from `apps/local/executor.config.ts` + dropping the workspace dep so it's no longer bundled into the local app's frontend.
Showing the changes to packages/plugins/example/src (3 of 94 files). Show all
Unified · Split
| @@ -0,0 +1,88 @@ | ||
| 1 | +// --------------------------------------------------------------------------- | |
| 2 | +// @executor-js/plugin-example/client | |
| 3 | +// | |
| 4 | +// Frontend half: a single page that calls the plugin's `greet` mutation | |
| 5 | +// and renders the response. Demonstrates the typed reactive client | |
| 6 | +// pattern — `ExampleClient.mutation(...)` is fully typed against | |
| 7 | +// `ExampleApi` from `./shared` with no codegen. | |
| 8 | +// | |
| 9 | +// Server-only deps (Effect, Node, executor.config) MUST NOT be imported | |
| 10 | +// here — the Vite plugin bundles this entry into the frontend. | |
| 11 | +// --------------------------------------------------------------------------- | |
| 12 | + | |
| 13 | +import { useState } from "react"; | |
| 14 | +import { | |
| 15 | + defineClientPlugin, | |
| 16 | + createPluginAtomClient, | |
| 17 | + useAtomSet, | |
| 18 | +} from "@executor-js/sdk/client"; | |
| 19 | + | |
| 20 | +import { ExampleApi } from "./shared"; | |
| 21 | + | |
| 22 | +const ExampleClient = createPluginAtomClient(ExampleApi); | |
| 23 | + | |
| 24 | +const greetAtom = ExampleClient.mutation("example", "greet"); | |
| 25 | + | |
| 26 | +function ExamplePage() { | |
| 27 | + const [name, setName] = useState("world"); | |
| 28 | + const [result, setResult] = useState<string>(); | |
| 29 | + const doGreet = useAtomSet(greetAtom, { mode: "promise" }); | |
| 30 | + | |
| 31 | + return ( | |
| 32 | + <div style={{ maxWidth: 480, margin: "2rem auto", padding: "1rem" }}> | |
| 33 | + <h1 style={{ fontSize: "1.25rem", marginBottom: "1rem" }}>Example plugin</h1> | |
| 34 | + <div style={{ display: "flex", gap: 8 }}> | |
| 35 | + {/* The example plugin demonstrates the SDK in isolation, so it | |
| 36 | + uses raw HTML controls instead of `@executor-js/react`'s | |
| 37 | + wrapped components — third-party plugin authors don't have | |
| 38 | + to depend on the host's component library. */} | |
| 39 | + {/* oxlint-disable-next-line react/forbid-elements */} | |
| 40 | + <input | |
| 41 | + value={name} | |
| 42 | + onChange={(e) => setName(e.target.value)} | |
| 43 | + style={{ | |
| 44 | + flex: 1, | |
| 45 | + padding: "0.5rem 0.75rem", | |
| 46 | + border: "1px solid #ccc", | |
| 47 | + borderRadius: 6, | |
| 48 | + }} | |
| 49 | + /> | |
| 50 | + {/* oxlint-disable-next-line react/forbid-elements */} | |
| 51 | + <button | |
| 52 | + type="button" | |
| 53 | + onClick={async () => { | |
| 54 | + // Mutation has no shared state to invalidate — explicit | |
| 55 | + // empty `reactivityKeys` documents the intent for the | |
| 56 | + // `require-reactivity-keys` rule. | |
| 57 | + const g = await doGreet({ payload: { name }, reactivityKeys: [] }); | |
| 58 | + setResult(`${g.message} (#${g.count})`); | |
| 59 | + }} | |
| 60 | + style={{ | |
| 61 | + padding: "0.5rem 0.75rem", | |
| 62 | + border: "1px solid #ccc", | |
| 63 | + borderRadius: 6, | |
| 64 | + cursor: "pointer", | |
| 65 | + }} | |
| 66 | + > | |
| 67 | + Greet | |
| 68 | + </button> | |
| 69 | + </div> | |
| 70 | + {result && ( | |
| 71 | + <pre style={{ marginTop: "1rem", padding: "0.5rem", background: "#f5f5f5" }}> | |
| 72 | + {result} | |
| 73 | + </pre> | |
| 74 | + )} | |
| 75 | + </div> | |
| 76 | + ); | |
| 77 | +} | |
| 78 | + | |
| 79 | +export default defineClientPlugin({ | |
| 80 | + id: "example" as const, | |
| 81 | + pages: [ | |
| 82 | + { | |
| 83 | + path: "/", | |
| 84 | + component: ExamplePage, | |
| 85 | + nav: { label: "Example" }, | |
| 86 | + }, | |
| 87 | + ], | |
| 88 | +}); | |
| @@ -0,0 +1,75 @@ | ||
| 1 | +// --------------------------------------------------------------------------- | |
| 2 | +// @executor-js/plugin-example/server | |
| 3 | +// | |
| 4 | +// The server half of the example plugin. Demonstrates: | |
| 5 | +// - extension methods that hold the canonical implementation | |
| 6 | +// - an HttpApiGroup contributed via `routes` | |
| 7 | +// - a late-binding `handlers` Layer that consumes the plugin's | |
| 8 | +// extension via a Service tag (`ExampleExtensionService`); the host | |
| 9 | +// binds the tag at boot for local or per request for cloud | |
| 10 | +// | |
| 11 | +// React and other browser-only deps live in `./client` — never here. | |
| 12 | +// --------------------------------------------------------------------------- | |
| 13 | + | |
| 14 | +import { | |
| 15 | + Context, | |
| 16 | + definePlugin, | |
| 17 | + Effect, | |
| 18 | + HttpApi, | |
| 19 | + HttpApiBuilder, | |
| 20 | +} from "@executor-js/sdk"; | |
| 21 | + | |
| 22 | +import { ExampleApi } from "./shared"; | |
| 23 | + | |
| 24 | +// Bundle the group into a single-group HttpApi for typing purposes only. | |
| 25 | +// The runtime composition uses group identity to merge into the host's | |
| 26 | +// FullApi, so this bundle never touches the host's wiring. | |
| 27 | +const ExampleApiBundle = HttpApi.make("example").add(ExampleApi); | |
| 28 | + | |
| 29 | +interface ExampleExtension { | |
| 30 | + readonly greet: ( | |
| 31 | + name: string, | |
| 32 | + ) => Effect.Effect<{ readonly message: string; readonly count: number }>; | |
| 33 | +} | |
| 34 | + | |
| 35 | +export class ExampleExtensionService extends Context.Service< | |
| 36 | + ExampleExtensionService, | |
| 37 | + ExampleExtension | |
| 38 | +>()("ExampleExtensionService") {} | |
| 39 | + | |
| 40 | +const ExampleHandlers = HttpApiBuilder.group(ExampleApiBundle, "example", (h) => | |
| 41 | + h.handle("greet", ({ payload }) => | |
| 42 | + Effect.gen(function* () { | |
| 43 | + const ext = yield* ExampleExtensionService; | |
| 44 | + return yield* ext.greet(payload.name); | |
| 45 | + }), | |
| 46 | + ), | |
| 47 | +); | |
| 48 | + | |
| 49 | +export const examplePlugin = definePlugin(() => ({ | |
| 50 | + id: "example" as const, | |
| 51 | + packageName: "@executor-js/plugin-example", | |
| 52 | + | |
| 53 | + // No DB schema — the counter lives in plugin storage (in-memory) so | |
| 54 | + // the example plugin doesn't pull in migration plumbing. | |
| 55 | + storage: () => ({ count: 0 }), | |
| 56 | + | |
| 57 | + // Canonical implementation. CLI/tests/embedded callers and the HTTP | |
| 58 | + // handler all hit this same code path. | |
| 59 | + extension: (ctx): ExampleExtension => ({ | |
| 60 | + greet: (name: string) => | |
| 61 | + Effect.sync(() => { | |
| 62 | + ctx.storage.count += 1; | |
| 63 | + return { | |
| 64 | + message: `hello ${name}`, | |
| 65 | + count: ctx.storage.count, | |
| 66 | + }; | |
| 67 | + }), | |
| 68 | + }), | |
| 69 | + | |
| 70 | + routes: () => ExampleApi, | |
| 71 | + handlers: () => ExampleHandlers, | |
| 72 | + extensionService: ExampleExtensionService, | |
| 73 | +})); | |
| 74 | + | |
| 75 | +export default examplePlugin; | |
| @@ -0,0 +1,25 @@ | ||
| 1 | +// --------------------------------------------------------------------------- | |
| 2 | +// @executor-js/plugin-example/shared | |
| 3 | +// | |
| 4 | +// Schemas and the HttpApiGroup definition shared between the server and | |
| 5 | +// client halves. Both `./server` and `./client` import from here so the | |
| 6 | +// frontend's typed reactive client and the backend's handlers see the | |
| 7 | +// exact same payload/response/error contracts. | |
| 8 | +// | |
| 9 | +// No React or Node imports here — server and client both import this. | |
| 10 | +// --------------------------------------------------------------------------- | |
| 11 | + | |
| 12 | +import { HttpApiEndpoint, HttpApiGroup, Schema } from "@executor-js/sdk"; | |
| 13 | + | |
| 14 | +export const Greeting = Schema.Struct({ | |
| 15 | + message: Schema.String, | |
| 16 | + count: Schema.Number, | |
| 17 | +}); | |
| 18 | +export type Greeting = typeof Greeting.Type; | |
| 19 | + | |
| 20 | +export const ExampleApi = HttpApiGroup.make("example").add( | |
| 21 | + HttpApiEndpoint.post("greet", "/greet", { | |
| 22 | + payload: Schema.Struct({ name: Schema.String }), | |
| 23 | + success: Greeting, | |
| 24 | + }), | |
| 25 | +); | |