wizards 0.1.11 → 0.2.1

package/apps/runtime/dist/mcp/tools.js

@@ -3,13 +3,15 @@ import { authoringGuide } from "../authoring/guide.js";
 import { wizardOpSchema } from "../authoring/ops.js";
 import { importFromRegistry, listConnectors, searchRegistry } from "../connectors/external.js";
 import { RunConflict } from "../engine/runner.js";
+import { pluginToolsOf } from "../plugins/registry.js";
 import { ServiceError } from "../services/errors.js";
 import { deleteFile, listFiles, readFileText, writeFile } from "../services/files.js";
 import { marketplaceWizard, searchMarketplace } from "../services/marketplace.js";
 import { defaultProject, listProjects, ownedProject } from "../services/projects.js";
-import { startTestRun, testRunReport } from "../services/runs.js";
+import { answerRunAsk, answerRunPage, controlRun, reviewRun, runReport, startRun, startTestRun, testRunReport, } from "../services/runs.js";
 import { checkDraftWidget } from "../services/widgets.js";
 import { createWizard, editWizard, listWizards, ownedWizard, parseDraft, publishWizard, shareUrl, studioUrl, updateWizardSettings, wizardState, writeDraft, } from "../services/wizards.js";
+import { FLOW_VIEW_KEY, flowAppMeta, flowView } from "./flow-app.js";
 const definition = z
     .record(z.string(), z.unknown())
     .describe("The complete wizard JSON as described by get_authoring_guide.");
@@ -67,6 +69,31 @@ export function registerTools(server, who) {
             }
         }));
     };
+    /** A tool whose result also opens the flow widget, in hosts that render MCP Apps. */
+    const appTool = (name, scope, config, run) => {
+        if (!who.scopes.includes(scope)) {
+            return;
+        }
+        server.registerTool(name, {
+            title: config.title,
+            description: config.description,
+            inputSchema: config.input,
+            annotations: { readOnlyHint: config.readOnly ?? false, openWorldHint: false },
+            _meta: flowAppMeta,
+        }, (async (args) => {
+            try {
+                const { result, view } = await run(args);
+                return {
+                    ...ok(result),
+                    structuredContent: result,
+                    _meta: { [FLOW_VIEW_KEY]: view },
+                };
+            }
+            catch (err) {
+                return failure(err);
+            }
+        }));
+    };
     // --- read ------------------------------------------------------------------
     tool("get_authoring_guide", "wizards:read", {
         title: "Authoring guide",
@@ -79,7 +106,7 @@ export function registerTools(server, who) {
         const project = projectId
             ? await ownedProject(who.userId, projectId)
             : await defaultProject(who.userId);
-        return authoringGuide(project.mcpServers.map((s) => ({ id: s.id, name: s.name })), await listConnectors(project.id));
+        return authoringGuide(project.mcpServers.map((s) => ({ id: s.id, name: s.name })), await listConnectors(project.id), await pluginToolsOf(who.tenantId));
     });
     // --- connectors ------------------------------------------------------------
     tool("find_connectors", "wizards:read", {
@@ -274,9 +301,9 @@ Returns the new revision and the issues.`,
         };
     });
     // --- test runs ---------------------------------------------------------------
-    tool("start_test_run", "runs:test", {
+    appTool("start_test_run", "runs:test", {
         title: "Start test run",
-        description: "Run the draft once with your answers. SPENDS THE ADMIN'S CREDITS (short copy + image ~15, research ~150, video ~250). Pages are filled from `answers`, reviews accepted when acceptReviews is true. Follow it with get_test_run.",
+        description: "Run the draft once with your answers. SPENDS THE ADMIN'S CREDITS (short copy + image ~15, research ~150, video ~250). Pages are filled from `answers`, reviews accepted when acceptReviews is true. Follow it with get_test_run. Shows the flow with the run on it.",
         input: z.object({
             wizardId: z.string(),
             answers: z
@@ -285,7 +312,14 @@ Returns the new revision and the issues.`,
                 .describe("Field id → value, for every page (field ids are unique in a wizard). Items fields take an array of row objects."),
             acceptReviews: z.boolean().default(true),
         }),
-    }, async ({ wizardId, answers, acceptReviews }) => startTestRun(who.userId, wizardId, { answers, acceptReviews }));
+    }, async ({ wizardId, answers, acceptReviews }) => {
+        const { runId } = await startTestRun(who.userId, wizardId, { answers, acceptReviews });
+        const report = await runReport(who.userId, runId, 2, "test");
+        return {
+            result: report,
+            view: await flowView(who.userId, wizardId, { shows: "draft", run: report }),
+        };
+    });
     tool("get_test_run", "runs:test", {
         title: "Get test run",
         description: "Status, recent events, outputs (text clipped) with signed download links valid one hour, credits spent, and what the run waits for.",
@@ -301,6 +335,125 @@ Returns the new revision and the issues.`,
         }),
         readOnly: true,
     }, async ({ runId, waitSeconds }) => testRunReport(who.userId, runId, waitSeconds));
+    // --- using wizards: the flow, and runs of the published version -------------
+    appTool("show_wizard", "wizards:read", {
+        title: "Show wizard",
+        description: "Show a wizard as its flow diagram: its pages, AI steps, reviews and branches. The published version when there is one, else the draft. Also returns the steps as text.",
+        input: z.object({
+            wizardId: z.string(),
+            version: z.enum(["published", "draft"]).optional().describe("Default: published, if any."),
+        }),
+        readOnly: true,
+    }, async ({ wizardId, version }) => {
+        const view = await flowView(who.userId, wizardId, { shows: version });
+        return {
+            result: {
+                wizardId,
+                title: view.wizard.title,
+                shows: view.wizard.shows,
+                published: view.wizard.published,
+                steps: view.definition.steps.map((s) => ({
+                    id: s.id,
+                    type: s.type,
+                    title: s.title,
+                    ...(s.type === "page"
+                        ? { fields: s.fields.map((f) => ({ id: f.id, label: f.label, kind: f.kind })) }
+                        : {}),
+                })),
+            },
+            view,
+        };
+    });
+    appTool("run_wizard", "runs:test", {
+        title: "Run wizard",
+        description: `Start a run of a published wizard for the person, here in the chat. Spends credits like any run.
+Start it right away — no show_wizard first: the widget shows the wizard's pages and the person can answer there. What the person already said goes to the first page with answer_page, using the field ids in waitingFor. Then follow waitingFor:
+- page: ask the person for the fields with inChat=true, answer_page; fields with inChat=false (files, recordings, signatures) need the run page at browserUrl
+- review: show the outputs, then review_step
+- ask: answer_ask (allow/skip a change in a connected account) or the run page for a sign-in
+While status is running, get_run with waitSeconds. Hosts with MCP Apps also show the run as a widget the person can answer in.`,
+        input: z.object({
+            wizardId: z.string(),
+            answers: z.record(z.string(), z.unknown()).default({}),
+        }),
+    }, async ({ wizardId, answers }) => {
+        const { runId, refused } = await startRun(who.userId, wizardId, answers);
+        const report = await runReport(who.userId, runId, 2);
+        return {
+            result: { ...report, ...(refused ? { refusedAnswers: refused } : {}) },
+            view: await flowView(who.userId, wizardId, { run: report }),
+        };
+    });
+    const waitSeconds = z
+        .number()
+        .int()
+        .min(0)
+        .max(45)
+        .default(0)
+        .describe("Wait up to this long while the run is still working.");
+    tool("get_run", "runs:test", {
+        title: "Get run",
+        description: "A run's status, what it waits for, its outputs (text clipped) with signed download links valid one hour, and the credits it spent.",
+        input: z.object({ runId: z.string(), waitSeconds }),
+        readOnly: true,
+    }, async ({ runId, waitSeconds }) => runReport(who.userId, runId, waitSeconds));
+    tool("answer_page", "runs:test", {
+        title: "Answer page",
+        description: "Fill the page a run waits for: field id → value (items: an array of row objects; toggle: true/false; multiselect: an array). Returns the run, after waitSeconds.",
+        input: z.object({
+            runId: z.string(),
+            stepId: z.string().describe("waitingFor.page"),
+            values: z.record(z.string(), z.unknown()),
+            waitSeconds,
+        }),
+    }, async ({ runId, stepId, values, waitSeconds }) => {
+        await answerRunPage(who.userId, runId, stepId, values);
+        return runReport(who.userId, runId, waitSeconds);
+    });
+    tool("review_step", "runs:test", {
+        title: "Review step",
+        description: "Answer the review a run waits for: accept (optionally with edited texts, step id → text, when the review is editable) or regenerate one step it shows, with a note what to change.",
+        input: z.object({
+            runId: z.string(),
+            stepId: z.string().describe("waitingFor.review"),
+            action: z.discriminatedUnion("type", [
+                z.object({
+                    type: z.literal("accept"),
+                    edits: z.record(z.string(), z.string()).optional(),
+                }),
+                z.object({
+                    type: z.literal("regenerate"),
+                    target: z.string().describe("One of waitingFor.show."),
+                    note: z.string().max(2000),
+                }),
+            ]),
+            waitSeconds,
+        }),
+    }, async ({ runId, stepId, action, waitSeconds }) => {
+        await reviewRun(who.userId, runId, stepId, action);
+        return runReport(who.userId, runId, waitSeconds);
+    });
+    tool("answer_ask", "runs:test", {
+        title: "Answer ask",
+        description: "A running step asks before it changes something in a connected account (waitingFor.ask, kind confirm): allow it once, or skip it. Ask the person first.",
+        input: z.object({
+            runId: z.string(),
+            askId: z.string(),
+            answer: z.enum(["allow", "skip"]),
+            waitSeconds,
+        }),
+    }, async ({ runId, askId, answer, waitSeconds }) => {
+        await answerRunAsk(who.userId, runId, askId, answer);
+        return runReport(who.userId, runId, waitSeconds);
+    });
+    tool("control_run", "runs:test", {
+        title: "Control run",
+        description: "back: to the previous page or review. retry: a failed step again. cancel: stop the run.",
+        input: z.object({ runId: z.string(), action: z.enum(["back", "retry", "cancel"]) }),
+    }, async ({ runId, action }) => {
+        await controlRun(who.userId, runId, action);
+        return runReport(who.userId, runId);
+    });
     // --- workspace (widget code, libraries, reference data) --------------------
     tool("list_files", "wizards:read", {
         title: "List workspace files",

package/apps/runtime/dist/plugins/discovery.js

@@ -0,0 +1,144 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, resolve, sep } from "node:path";
+import { PLUGIN_ID } from "@engenty-wizards/shared/definition";
+import { z } from "zod";
+/**
+ * Finding plugins. A folder of plugins holds, in any mix:
+ *
+ *   notify.ts                    one file: the server half, its id is the file's name
+ *   contacts/engenty.plugin.json a folder with a manifest: `src/plugin.ts`, `dist/client.js`
+ *   hello/index.ts               a folder without one: the server half, its id is the folder's name
+ *   node_modules/<package>       packages installed there that carry a manifest
+ */
+export const MANIFEST_FILE = "engenty.plugin.json";
+/** Further fields (an engenty module's `provides`, `capabilities`, …) are kept as they are. */
+const manifestSchema = z.looseObject({
+    id: z.string().regex(PLUGIN_ID),
+    name: z.string().min(1),
+    version: z.string().default("0.0.0"),
+    description: z.string().optional(),
+    server: z.string().optional(),
+    studio: z.string().optional(),
+    styles: z.string().optional(),
+});
+/** `.mjs` is left out: Node keeps such a file once imported, so a reload would not read it again. */
+const CODE = new Set([".ts", ".js"]);
+const SERVER_ENTRIES = ["src/plugin.ts", "src/plugin.js", "dist/plugin.js"];
+const INDEX_ENTRIES = ["index.ts", "index.js"];
+const isDir = (path) => statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
+const firstExisting = (root, names) => names.map((name) => join(root, name)).find((path) => existsSync(path)) ?? null;
+/** A path of the manifest must stay inside the plugin's folder. */
+function inside(root, relative) {
+    const path = resolve(root, relative);
+    return path.startsWith(root + sep) && existsSync(path) ? path : null;
+}
+function fromManifest(root) {
+    const parsed = manifestSchema.safeParse(JSON.parse(readFileSync(join(root, MANIFEST_FILE), "utf8")));
+    if (!parsed.success) {
+        throw new Error(`${MANIFEST_FILE}: ${z.prettifyError(parsed.error)}`);
+    }
+    const manifest = parsed.data;
+    const entry = manifest.server
+        ? inside(root, manifest.server)
+        : firstExisting(root, SERVER_ENTRIES);
+    if (manifest.server && !entry) {
+        throw new Error(`"server": ${manifest.server} is not a file of the plugin.`);
+    }
+    return {
+        id: manifest.id,
+        manifest,
+        root,
+        entry,
+        studio: inside(root, manifest.studio ?? "dist/client.js"),
+        styles: inside(root, manifest.styles ?? "dist/client.css"),
+        single: false,
+    };
+}
+/** A plugin without a manifest: its id is the name of its file or folder. */
+function bare(id, root, entry, single) {
+    if (!PLUGIN_ID.test(id)) {
+        throw new Error(`"${id}" is no plugin id: lower case, digits and "-", starting with a letter.`);
+    }
+    return {
+        id,
+        manifest: { id, name: id, version: "0.0.0" },
+        root,
+        entry,
+        studio: null,
+        styles: null,
+        single,
+    };
+}
+/** Packages below `node_modules` that are plugins: `<name>` and `@scope/<name>`. */
+function packagesIn(nodeModules) {
+    const out = [];
+    for (const name of readdirSync(nodeModules).sort()) {
+        if (name.startsWith(".")) {
+            continue;
+        }
+        const path = join(nodeModules, name);
+        const candidates = name.startsWith("@")
+            ? readdirSync(path)
+                .sort()
+                .map((child) => join(path, child))
+            : [path];
+        out.push(...candidates.filter((dir) => existsSync(join(dir, MANIFEST_FILE))));
+    }
+    return out;
+}
+function sourceAt(path) {
+    if (!isDir(path)) {
+        const ext = extname(path);
+        return CODE.has(ext) && !path.endsWith(".d.ts")
+            ? bare(basename(path, ext), resolve(path, ".."), path, true)
+            : null;
+    }
+    if (existsSync(join(path, MANIFEST_FILE))) {
+        return fromManifest(path);
+    }
+    const index = firstExisting(path, INDEX_ENTRIES);
+    return index ? bare(basename(path), path, index, false) : null;
+}
+/** The plugins in these folders. Of two with one id the first found stays. */
+export function discoverPlugins(dirs) {
+    const found = new Map();
+    const problems = [];
+    const take = (path) => {
+        try {
+            const source = sourceAt(path);
+            if (!source) {
+                return;
+            }
+            const first = found.get(source.id);
+            if (first) {
+                problems.push({
+                    path,
+                    message: `Plugin "${source.id}" is already loaded from ${first.root}.`,
+                });
+                return;
+            }
+            found.set(source.id, source);
+        }
+        catch (err) {
+            problems.push({ path, message: err.message });
+        }
+    };
+    for (const dir of dirs) {
+        if (!isDir(dir)) {
+            continue;
+        }
+        for (const name of readdirSync(dir).sort()) {
+            if (name.startsWith(".") || name.startsWith("_")) {
+                continue;
+            }
+            const path = join(dir, name);
+            if (name === "node_modules") {
+                packagesIn(path).forEach(take);
+            }
+            else {
+                take(path);
+            }
+        }
+    }
+    return { found: [...found.values()], problems };
+}

package/apps/runtime/dist/plugins/events.js

@@ -0,0 +1,40 @@
+import { eq } from "drizzle-orm";
+import { db, schema } from "../db/client.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { pluginsOf } from "./registry.js";
+/**
+ * Tells the tenant's plugins that a run reached its end. A plugin cannot fail a run: what a
+ * listener throws is logged and nothing more.
+ */
+export async function runEnded(runId, status) {
+    try {
+        const event = `run.${status}`;
+        const listening = (await pluginsOf(currentTenant())).filter((p) => p.listeners[event]?.length);
+        if (!listening.length) {
+            return;
+        }
+        const run = await db.query.run.findFirst({ where: eq(schema.run.id, runId) });
+        const wizard = run && (await db.query.wizard.findFirst({ where: eq(schema.wizard.id, run.wizardId) }));
+        if (!run || !wizard) {
+            return;
+        }
+        const payload = {
+            run: { id: run.id, wizardId: run.wizardId, mode: run.mode, status },
+            wizard: { id: wizard.id, title: run.definition.title, projectId: wizard.projectId },
+            values: run.state.values,
+        };
+        for (const plugin of listening) {
+            for (const listener of plugin.listeners[event] ?? []) {
+                try {
+                    await listener(payload);
+                }
+                catch (err) {
+                    console.error(`[plugin ${plugin.source.id}] ${event}:`, err);
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error("[plugins] run event:", err);
+    }
+}

package/apps/runtime/dist/plugins/loader.js

@@ -0,0 +1,277 @@
+import { existsSync, mkdirSync, watch } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PLUGIN_TOOL_NAME } from "@engenty-wizards/shared/definition";
+import { createJiti } from "jiti";
+import { packageRoot } from "../cli/home.js";
+import { db, onTenantOpen } from "../db/client.js";
+import { env } from "../env.js";
+import { discoverPlugins } from "./discovery.js";
+import { migrateOpenTenants, migratePlugins } from "./migrations.js";
+import { announceChange, compileRoute, dropPlugin, emptyRecord, loadedPlugin, loadedPlugins, setPlugin, } from "./registry.js";
+/**
+ * Loading plugins (docs/plugins.md). A plugin's server half is TypeScript or JavaScript read
+ * from its file as it is: no build step, and a reload reads the files again. What a plugin
+ * imports of the runtime's own packages comes from the runtime's copies, wherever the plugin's
+ * file lies.
+ */
+/** What ships with this runtime, then the folders of `PLUGINS_DIR`. */
+export function pluginDirs() {
+    return [join(packageRoot, "modules"), ...env.plugins.dirs];
+}
+const own = (specifier) => fileURLToPath(import.meta.resolve(specifier));
+/** The longer name first: an alias also matches what begins with it. */
+function aliases() {
+    return {
+        "@engenty-wizards/plugin-sdk": own("@engenty-wizards/plugin-sdk"),
+        "drizzle-orm/sqlite-core": own("drizzle-orm/sqlite-core"),
+        "drizzle-orm": own("drizzle-orm"),
+        zod: own("zod"),
+    };
+}
+async function importFactory(entry) {
+    // No module cache: every load evaluates the plugin's files anew.
+    const jiti = createJiti(import.meta.url, { moduleCache: false, alias: aliases() });
+    const factory = await jiti.import(entry, { default: true });
+    if (typeof factory !== "function") {
+        throw new Error("The default export is not a function.");
+    }
+    return factory;
+}
+function apiFor(record) {
+    const { source } = record;
+    const tag = `[plugin ${source.id}]`;
+    return {
+        plugin: source.manifest,
+        resolvePath: (relative) => resolve(source.root, relative),
+        config: { get: (key) => process.env[key]?.trim() || undefined },
+        log: {
+            info: (...args) => console.log(tag, ...args),
+            warn: (...args) => console.warn(tag, ...args),
+            error: (...args) => console.error(tag, ...args),
+        },
+        server: {
+            registerHttpRoute(route) {
+                record.routes.push(compileRoute(route));
+            },
+            registerTool(tool) {
+                if (!PLUGIN_TOOL_NAME.test(tool.name)) {
+                    throw new Error(`Tool "${tool.name}": a name is lower case, digits and "_".`);
+                }
+                if (record.tools.has(tool.name)) {
+                    throw new Error(`Tool "${tool.name}" is registered twice.`);
+                }
+                record.tools.set(tool.name, tool);
+            },
+            registerMigrations(folder) {
+                record.migrations.push(resolve(source.root, folder));
+            },
+            on(event, listener) {
+                const listeners = (record.listeners[event] ?? []);
+                listeners.push(listener);
+                record.listeners[event] = listeners;
+            },
+            getTenantDb: () => db,
+            onUnload(dispose) {
+                record.disposers.push(dispose);
+            },
+        },
+    };
+}
+/** Runs what the plugin asked to have undone, the last first. */
+async function dispose(record) {
+    for (const undo of record.disposers.splice(0).reverse()) {
+        try {
+            await undo();
+        }
+        catch (err) {
+            console.error(`[plugins] ${record.source.id}: undoing failed:`, err);
+        }
+    }
+}
+async function load(source) {
+    const record = emptyRecord(source);
+    if (source.entry) {
+        try {
+            const factory = await importFactory(source.entry);
+            await factory(apiFor(record));
+        }
+        catch (err) {
+            // Half a plugin is worse than none: what it registered before it failed goes as well.
+            await dispose(record);
+            record.routes = [];
+            record.tools.clear();
+            record.listeners = {};
+            record.migrations = [];
+            record.error = err?.message || String(err);
+            console.error(`[plugins] ${source.id} did not load:`, err);
+        }
+    }
+    setPlugin(record);
+    return record;
+}
+async function unload(id) {
+    const record = dropPlugin(id);
+    if (record) {
+        await dispose(record);
+    }
+}
+let problems = [];
+/** Files and folders that look like a plugin and are none, as of the last look. */
+export function pluginProblems() {
+    return problems;
+}
+function discover() {
+    const result = discoverPlugins(pluginDirs());
+    problems = result.problems;
+    for (const problem of problems) {
+        console.error(`[plugins] ${problem.path}: ${problem.message}`);
+    }
+    return result.found;
+}
+/** One load at a time: the watcher and a person may ask for a reload at the same moment. */
+let queue = Promise.resolve();
+function inTurn(work) {
+    const next = queue.catch(() => undefined).then(work);
+    queue = next;
+    return next;
+}
+let hooked = false;
+/** At start: finds the plugins and loads each. Must run before a tenant database opens. */
+export function loadPlugins() {
+    return inTurn(async () => {
+        if (!hooked) {
+            hooked = true;
+            // A plugin whose tables cannot be made must not keep the tenant's database from opening.
+            onTenantOpen((tenantId, client) => migratePlugins(tenantId, client).catch((err) => console.error(`[plugins] tables for tenant ${tenantId}:`, err.message)));
+        }
+        const found = discover();
+        for (const source of found) {
+            await load(source);
+        }
+        if (found.length) {
+            console.log(`plugins: ${found.map((s) => s.id).join(", ")}`);
+        }
+        await migrateOpenTenants();
+        if (env.plugins.watch) {
+            watchPlugins();
+        }
+    });
+}
+/** Loads one plugin again from its files; a plugin whose files are gone unloads. */
+export function reloadPlugin(id) {
+    return inTurn(async () => {
+        const found = discover();
+        const source = found.find((s) => s.id === id);
+        await unload(id);
+        const record = source ? await load(source) : null;
+        // Its manifest may name another id now: under the old one it is gone, under the new one new.
+        await loadMissing(found);
+        await migrateOpenTenants();
+        announceChange({ id });
+        return record;
+    });
+}
+/** Loads what was found and is not loaded yet. */
+async function loadMissing(found) {
+    const missing = found.filter((source) => !loadedPlugin(source.id));
+    for (const source of missing) {
+        await load(source);
+    }
+    return missing.length > 0;
+}
+/**
+ * Looks again and leaves what is loaded alone: plugins that are new load, plugins whose files
+ * went unload.
+ */
+export function findNewPlugins() {
+    return inTurn(async () => {
+        const found = discover();
+        const gone = loadedPlugins().filter((p) => !found.some((s) => s.id === p.source.id));
+        for (const plugin of gone) {
+            await unload(plugin.source.id);
+        }
+        if ((await loadMissing(found)) || gone.length) {
+            await migrateOpenTenants();
+            announceChange({ id: null });
+        }
+    });
+}
+/** Loads every plugin anew, new ones included, and unloads what is gone. */
+export function rescanPlugins() {
+    return inTurn(async () => {
+        const found = discover();
+        for (const loaded of loadedPlugins()) {
+            await unload(loaded.source.id);
+        }
+        for (const source of found) {
+            await load(source);
+        }
+        await migrateOpenTenants();
+        announceChange({ id: null });
+    });
+}
+/** The studio half was built again: the server half stays as it is, the studio fetches the files. */
+function refreshStudioHalf(id) {
+    return inTurn(async () => {
+        const record = loadedPlugin(id);
+        const source = discover().find((s) => s.id === id);
+        if (record && source) {
+            record.source = { ...record.source, studio: source.studio, styles: source.styles };
+            announceChange({ id });
+        }
+    });
+}
+const watchers = [];
+/**
+ * Reloads a plugin when one of its files changes. `ui/` is left alone: it only counts once it
+ * is built, and a change below `dist/` is that build.
+ */
+function watchPlugins() {
+    for (const watcher of watchers.splice(0)) {
+        watcher.close();
+    }
+    const timers = new Map();
+    const soon = (key, run) => {
+        clearTimeout(timers.get(key));
+        timers.set(key, setTimeout(() => {
+            timers.delete(key);
+            run().catch((err) => console.error("[plugins]", err));
+        }, 150));
+    };
+    for (const dir of pluginDirs()) {
+        // A folder of this install's own plugins is made, so the first plugin put there is seen.
+        if (env.plugins.dirs.includes(dir)) {
+            try {
+                mkdirSync(dir, { recursive: true });
+            }
+            catch {
+                // a place that cannot be written to
+            }
+        }
+        if (!existsSync(dir)) {
+            continue;
+        }
+        const watcher = watch(dir, { recursive: true }, (_event, file) => {
+            const parts = file?.toString().split(sep) ?? [];
+            if (!parts.length || parts.includes("node_modules") || parts.some((p) => p.startsWith("."))) {
+                return;
+            }
+            const top = join(dir, parts[0]);
+            const plugin = loadedPlugins().find((p) => p.source.single ? p.source.entry === top : p.source.root === top);
+            const { id, entry } = plugin?.source ?? {};
+            if (!id) {
+                // A plugin that is new here, or what is left of one that went. The others stay loaded.
+                soon("*", findNewPlugins);
+            }
+            else if (parts[1] === "dist" && !entry?.startsWith(join(top, "dist") + sep)) {
+                soon(`${id}/studio`, () => refreshStudioHalf(id));
+            }
+            else if (parts[1] !== "ui") {
+                soon(id, () => reloadPlugin(id));
+            }
+        });
+        watcher.unref();
+        watchers.push(watcher);
+    }
+}