@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/plugin.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { zipSync } from "fflate";
+import { env } from "./env.js";
+/**
+ * The Claude Code plugin for this deployment: the `plugin/` folder with this server's URL filled
+ * in, served as a marketplace (`url` source) whose one plugin is a zip (`archive` source). So
+ * every deployment hands out its own plugin and no domain is baked into the repo.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+/** The folder that holds `plugin/` and the root package.json: three levels above this file. */
+const base = resolve(here, "../../..");
+const root = existsSync(join(base, "plugin")) ? base : undefined;
+export const PLUGIN_NAME = "engenty-wizards";
+export const MARKETPLACE_NAME = "engenty";
+export const pluginBase = `${env.appUrl}/api/claude-plugin`;
+async function filesUnder(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const nested = await Promise.all(entries.map((e) => (e.isDirectory() ? filesUnder(join(dir, e.name)) : [join(dir, e.name)])));
+    return nested.flat();
+}
+let built = null;
+export function pluginArchive() {
+    built ??= (async () => {
+        if (!root) {
+            throw new Error("plugin/ folder missing");
+        }
+        const { version } = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+        const dir = join(root, "plugin");
+        const files = {};
+        for (const path of (await filesUnder(dir)).sort()) {
+            const text = (await readFile(path, "utf8"))
+                .replaceAll("{{APP_URL}}", env.appUrl)
+                .replaceAll("{{VERSION}}", version);
+            // Fixed timestamps keep the archive, and so its sha256, stable across restarts.
+            files[relative(dir, path)] = new TextEncoder().encode(text);
+        }
+        const zip = zipSync(files, { level: 9, mtime: new Date("2026-01-01T00:00:00Z") });
+        return { zip, sha256: createHash("sha256").update(zip).digest("hex"), version };
+    })();
+    return built;
+}
+export async function pluginMarketplace() {
+    const { sha256, version } = await pluginArchive();
+    return {
+        name: MARKETPLACE_NAME,
+        owner: { name: "engenty" },
+        description: "engenty wizards for Claude Code",
+        plugins: [
+            {
+                name: PLUGIN_NAME,
+                description: "Build page-by-page AI wizards that people open on a shared link — designed, tested and published from Claude Code.",
+                version,
+                source: { source: "archive", url: `${pluginBase}/${PLUGIN_NAME}.zip`, sha256 },
+            },
+        ],
+    };
+}

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

@@ -0,0 +1,78 @@
+import { bookChannelUsage, ManageError, managed, requestChannelNumber, tenantChannels, withdrawChannelRequest, } from "../manage.js";
+import { currentTenant } from "../tenants/tenant.js";
+/**
+ * `server.channels`: the numbers the Manage-App gives the current tenant
+ * (docs/manage-contract.md, "Numbers of a tenant"). Without a Manage-App there are none.
+ */
+/** A refusal of the Manage-App as a plugin passes it on: its status and its code. */
+const asked = (work) => work.catch((err) => {
+    throw err instanceof ManageError
+        ? Object.assign(new Error(err.message), { status: err.status, code: err.code })
+        : err;
+});
+const unmanaged = () => Object.assign(new Error("This runtime has no Manage-App, so it has no numbers."), {
+    status: 404,
+    code: "not_managed",
+});
+export const channelsApi = {
+    async get() {
+        if (!managed) {
+            return null;
+        }
+        const c = await asked(tenantChannels(currentTenant()));
+        return {
+            number: c.number
+                ? {
+                    number: c.number.number,
+                    country: c.number.country,
+                    kinds: c.number.kinds,
+                    providerRef: c.number.providerRef ?? null,
+                }
+                : null,
+            request: c.request
+                ? {
+                    id: c.request.id,
+                    country: c.request.country,
+                    wish: c.request.wish,
+                    createdAt: c.request.createdAt,
+                }
+                : null,
+            shared: c.shared,
+            allowed: c.allowed !== false,
+        };
+    },
+    async request(input) {
+        if (!managed) {
+            throw unmanaged();
+        }
+        const { request } = await asked(requestChannelNumber(currentTenant(), {
+            userId: input.userId,
+            country: input.country.toUpperCase(),
+            wish: input.wish ?? null,
+            lang: input.lang,
+        }));
+        return {
+            id: request.id,
+            country: request.country,
+            wish: request.wish,
+            createdAt: request.createdAt,
+        };
+    },
+    async withdraw() {
+        if (!managed) {
+            throw unmanaged();
+        }
+        return (await asked(withdrawChannelRequest(currentTenant()))).withdrawn;
+    },
+    async book(input) {
+        if (!managed || input.quantity <= 0) {
+            return { credits: 0 };
+        }
+        return asked(bookChannelUsage(currentTenant(), {
+            kind: input.kind,
+            quantity: input.quantity,
+            idempotencyKey: input.key,
+            ...(input.runId ? { runId: input.runId } : {}),
+        }));
+    },
+};

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

@@ -0,0 +1,56 @@
+import { and, eq } from "drizzle-orm";
+import { control, controlDb } from "../db/client.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { publicRefOf } from "./public.js";
+/**
+ * `server.claims`: keys a plugin holds across the runtime's tenants, each for one tenant at a
+ * time (control `plugin_claim`). A key is the plugin's own; another plugin's of the same name is
+ * another key.
+ */
+const MAX_KEY = 200;
+function checked(key) {
+    if (!key || key.length > MAX_KEY) {
+        throw Object.assign(new Error(`A key is 1 to ${MAX_KEY} characters.`), {
+            status: 400,
+            code: "invalid",
+        });
+    }
+    return key;
+}
+export function claimsApiFor(plugin) {
+    const where = (key) => and(eq(control.pluginClaim.plugin, plugin), eq(control.pluginClaim.key, checked(key)));
+    const holderOf = async (key) => (await controlDb.query.pluginClaim.findFirst({ where: where(key) }))?.tenantId ?? null;
+    return {
+        async take(key) {
+            const tenantId = currentTenant();
+            await controlDb
+                .insert(control.pluginClaim)
+                .values({ plugin, key: checked(key), tenantId, updatedAt: new Date() })
+                .onConflictDoNothing();
+            return (await holderOf(key)) === tenantId;
+        },
+        async put(key) {
+            const tenantId = currentTenant();
+            const updatedAt = new Date();
+            await controlDb
+                .insert(control.pluginClaim)
+                .values({ plugin, key: checked(key), tenantId, updatedAt })
+                .onConflictDoUpdate({
+                target: [control.pluginClaim.plugin, control.pluginClaim.key],
+                set: { tenantId, updatedAt },
+            });
+        },
+        async drop(key) {
+            await controlDb
+                .delete(control.pluginClaim)
+                .where(and(where(key), eq(control.pluginClaim.tenantId, currentTenant())));
+        },
+        async holder(key) {
+            const tenantId = await holderOf(key);
+            return tenantId ? publicRefOf(plugin, tenantId) : null;
+        },
+        async mine(key) {
+            return (await holderOf(key)) === currentTenant();
+        },
+    };
+}

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

@@ -0,0 +1,155 @@
+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(),
+    features: z
+        .record(z.string().regex(/^[a-z][a-zA-Z0-9]*$/), z.union([
+        z.boolean(),
+        z.object({
+            kind: z.enum(["release", "plan"]).optional(),
+            default: z.boolean().optional(),
+            label: z.string().max(80).optional(),
+            hint: z.string().max(300).optional(),
+        }),
+    ]))
+        .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,63 @@
+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 current tenant's plugins what happened. A plugin cannot fail what the runtime does:
+ * what a listener throws is logged and nothing more.
+ */
+export async function emitPluginEvent(event, payload) {
+    try {
+        const listening = (await pluginsOf(currentTenant())).filter((p) => p.listeners[event]?.length);
+        if (!listening.length) {
+            return;
+        }
+        // What is costly to gather is gathered only when someone listens.
+        const told = typeof payload === "function" ? await payload() : payload;
+        if (!told) {
+            return;
+        }
+        for (const plugin of listening) {
+            for (const listener of plugin.listeners[event] ?? []) {
+                try {
+                    await listener(told);
+                }
+                catch (err) {
+                    console.error(`[plugin ${plugin.source.id}] ${event}:`, err);
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error(`[plugins] ${event}:`, err);
+    }
+}
+/** A run reached its end. */
+export function runEnded(runId, status) {
+    return emitPluginEvent(`run.${status}`, async () => {
+        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 null;
+        }
+        return {
+            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,
+        };
+    });
+}
+/**
+ * A space was made, changed or deleted. Not waited for: the request that changed the space
+ * answers without its plugins.
+ */
+export function spaceChanged(event, spaceId) {
+    void emitPluginEvent(event, { space: { id: spaceId } });
+}
+/** A file of a space was read and is ready, or was removed. Not waited for either. */
+export function spaceFileChanged(event, file) {
+    void emitPluginEvent(event, {
+        space: { id: file.projectId },
+        file: { id: file.id, name: file.name, kind: file.kind, mime: file.mime },
+    });
+}

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

@@ -0,0 +1,64 @@
+import { and, eq } from "drizzle-orm";
+import { control, controlDb, withTenant } from "../db/client.js";
+import { env } from "../env.js";
+import { loadedPlugins, pluginIdsOf } from "./registry.js";
+/**
+ * Plugins' jobs (`server.every`). A tick looks once a minute which job is due for which tenant
+ * and runs it inside that tenant. When a job ran is kept in the control database, so a restart
+ * does not start the count again; a runtime that was off runs a due job once when it starts,
+ * not once per turn it missed.
+ */
+/** Jobs that run right now, by tenant, plugin and name: one turn at a time each. */
+const running = new Set();
+/** Starts every job that is due, and is done when they are. */
+export async function runDueJobs(now = new Date()) {
+    const jobs = loadedPlugins().flatMap((plugin) => [...plugin.jobs].map(([name, job]) => ({ plugin, name, job })));
+    if (!jobs.length) {
+        return;
+    }
+    const tenants = await controlDb.query.tenant.findMany({
+        where: eq(control.tenant.status, "active"),
+    });
+    const started = [];
+    for (const tenant of tenants) {
+        const has = await pluginIdsOf(tenant.id);
+        for (const { plugin, name, job } of jobs) {
+            const id = plugin.source.id;
+            const key = `${tenant.id}/${id}/${name}`;
+            if (!has.has(id) || running.has(key)) {
+                continue;
+            }
+            const where = and(eq(control.pluginJob.tenantId, tenant.id), eq(control.pluginJob.plugin, id), eq(control.pluginJob.name, name));
+            const last = (await controlDb.query.pluginJob.findFirst({ where }))?.lastRunAt ?? null;
+            if (last && now.getTime() - last.getTime() < job.everyMs) {
+                continue;
+            }
+            running.add(key);
+            // The start counts as the run: a turn that throws or hangs is not repeated every minute.
+            await controlDb
+                .insert(control.pluginJob)
+                .values({ tenantId: tenant.id, plugin: id, name, lastRunAt: now })
+                .onConflictDoUpdate({
+                target: [control.pluginJob.tenantId, control.pluginJob.plugin, control.pluginJob.name],
+                set: { lastRunAt: now },
+            });
+            started.push(withTenant(tenant.id, () => job.handler({ tenantId: tenant.id, lastRun: last, signal: plugin.stopped.signal }))
+                .catch((err) => console.error(`[plugin ${id}] job ${name}:`, err))
+                .finally(() => running.delete(key)));
+        }
+    }
+    await Promise.all(started);
+}
+const TICK_MS = 60_000;
+let timer = null;
+/** Looks for due jobs now and then once a minute, while the runtime runs. */
+export function startJobs() {
+    if (timer || !env.plugins.jobs) {
+        return;
+    }
+    const tick = () => void runDueJobs().catch((err) => console.error("[plugins] jobs:", err));
+    // Soon after the start, not during it: tenant databases open first.
+    setTimeout(tick, 5_000).unref();
+    timer = setInterval(tick, TICK_MS);
+    timer.unref();
+}