wizards 0.2.0 → 0.2.2

package/apps/runtime/dist/cli/main.js

@@ -1,5 +1,7 @@
+import { apps, connectCommand } from "./connect.js";
 import { layout, packageVersion, readInstallNote } from "./home.js";
 import { CLIENTS, nodeIsCurrent } from "./machine.js";
+import { mcp } from "./mcp.js";
 import { command, setup } from "./setup.js";
 import { open, start } from "./start.js";
 import { autostart, status, stop } from "./status.js";
@@ -14,6 +16,12 @@ const HELP = `engenty wizards ${packageVersion()}
   ${command()} stop       stop it; the data is kept
   ${command()} update     the newest version
   ${command()} autostart  start it at login: on, off (macOS: a LaunchAgent; Linux: a systemd service)
+  ${command()} connect    your wizards in your AI apps: every app found, or name them —
+                        ${apps(layout())
+    .map((app) => app.id)
+    .join(", ")}
+  ${command()} disconnect take them out again (same names)
+  ${command()} mcp        the MCP server over stdio, as the AI apps start it
 
   --yes, -y          ask nothing and install nothing optional
   --client <name>    install this AI client without asking: ${CLIENTS.map((c) => c.id).join(", ")}
@@ -26,6 +34,7 @@ function parse(argv) {
     const args = {
         command: "",
         value: "",
+        apps: [],
         yes: false,
         open: true,
         print: false,
@@ -61,6 +70,9 @@ function parse(argv) {
         else if (args.command === "autostart" && !args.value) {
             args.value = arg;
         }
+        else if (args.command === "connect" || args.command === "disconnect") {
+            args.apps.push(arg);
+        }
         else if (args.command) {
             return `Unexpected argument ${arg}.`;
         }
@@ -113,6 +125,11 @@ async function main(argv) {
             return update(paths);
         case "autostart":
             return autostart(paths, args.value);
+        case "connect":
+        case "disconnect":
+            return connectCommand(paths, args.apps, args.command === "disconnect");
+        case "mcp":
+            return mcp(paths);
         default:
             console.error(`Unknown command ${args.command}.\n\n${HELP}`);
             return 2;

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

@@ -0,0 +1,175 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { LOCAL_CLIENT_HEADER, LOCAL_MCP_HEADER, mintLocalTicket } from "../auth/local-ticket.js";
+import { runningRuntime, settings } from "./start.js";
+/**
+ * `wizards mcp`: this install's MCP server over stdio, for AI clients that start their
+ * servers as a command — Claude Desktop, Cursor, Codex and the ChatGPT app, VS Code, Windsurf,
+ * Gemini CLI, Goose, OpenClaw, LM Studio. Each message goes on to the running runtime's
+ * `/api/mcp`, signed with the data folder's secret, so no client's config holds a key and a new
+ * port after a restart changes nothing. When nothing runs, the runtime is started.
+ *
+ * stdout carries only MCP messages; everything else goes to stderr.
+ */
+const START_TIMEOUT_MS = 60_000;
+/** The JSON-RPC messages of a response: a JSON body (one or a batch) or a server-sent stream. */
+export function messagesOf(contentType, body) {
+    if (!body.trim()) {
+        return [];
+    }
+    if (contentType.includes("text/event-stream")) {
+        const out = [];
+        for (const event of body.split(/\r?\n\r?\n/)) {
+            const data = event
+                .split(/\r?\n/)
+                .filter((line) => line.startsWith("data:"))
+                .map((line) => line.slice(5).replace(/^ /, ""))
+                .join("\n");
+            if (data.trim()) {
+                out.push(JSON.parse(data));
+            }
+        }
+        return out;
+    }
+    const parsed = JSON.parse(body);
+    return Array.isArray(parsed) ? parsed : [parsed];
+}
+function readSecret(paths, dataDir) {
+    const given = process.env.APP_SECRET?.trim() || settings(paths).fileEnv.APP_SECRET?.trim();
+    if (given) {
+        return given;
+    }
+    try {
+        return readFileSync(join(dataDir, "secret"), "utf8").trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Starts the runtime in the background, the way `wizards start --no-open` would. */
+function startInBackground(paths) {
+    mkdirSync(paths.logs, { recursive: true });
+    const log = openSync(join(paths.logs, "runtime.log"), "a");
+    const child = spawn(process.execPath, [process.argv[1], "start", "--no-open"], {
+        detached: true,
+        stdio: ["ignore", log, log],
+        env: process.env,
+    });
+    child.unref();
+}
+export async function mcp(paths) {
+    const { dataDir } = settings(paths);
+    let running = null;
+    let clientName = "";
+    let protocolVersion = "";
+    const runtime = () => {
+        running ??= (async () => {
+            const found = await runningRuntime(dataDir);
+            if (found) {
+                return found;
+            }
+            process.stderr.write("engenty wizards is not running; starting it …\n");
+            startInBackground(paths);
+            const began = Date.now();
+            while (Date.now() - began < START_TIMEOUT_MS) {
+                await new Promise((wait) => setTimeout(wait, 300));
+                const started = await runningRuntime(dataDir);
+                if (started) {
+                    return started;
+                }
+            }
+            throw new Error(`engenty wizards did not start within a minute; see ${join(paths.logs, "runtime.log")}.`);
+        })();
+        running.catch(() => {
+            running = null;
+        });
+        return running;
+    };
+    const post = async (message) => {
+        const at = await runtime();
+        const secret = readSecret(paths, dataDir);
+        if (!secret) {
+            throw new Error("The data folder has no secret; start engenty wizards once.");
+        }
+        const response = await fetch(`http://127.0.0.1:${at.port}/api/mcp`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream",
+                [LOCAL_MCP_HEADER]: mintLocalTicket(secret, Date.now(), "local-mcp"),
+                ...(clientName ? { [LOCAL_CLIENT_HEADER]: clientName } : {}),
+                ...(protocolVersion ? { "mcp-protocol-version": protocolVersion } : {}),
+            },
+            body: JSON.stringify(message),
+        });
+        const body = await response.text();
+        if (!response.ok && response.status !== 202) {
+            throw new Error(`engenty wizards answered ${response.status}: ${body.slice(0, 300)}`);
+        }
+        return messagesOf(response.headers.get("content-type") ?? "", body);
+    };
+    const write = (message) => {
+        process.stdout.write(`${JSON.stringify(message)}\n`);
+    };
+    const handle = async (message) => {
+        if (message.method === "initialize") {
+            const info = message.params?.clientInfo;
+            clientName = info?.title || info?.name || "";
+        }
+        let answers;
+        try {
+            answers = await post(message);
+        }
+        catch (error) {
+            // The runtime went away (stopped, restarted on another port): once more, with a fresh look.
+            running = null;
+            try {
+                answers = await post(message);
+            }
+            catch {
+                if (message.id !== undefined && message.method) {
+                    write({
+                        jsonrpc: "2.0",
+                        id: message.id,
+                        error: { code: -32603, message: error.message },
+                    });
+                }
+                process.stderr.write(`${error.message}\n`);
+                return;
+            }
+        }
+        for (const answer of answers) {
+            const version = answer.result?.protocolVersion;
+            if (message.method === "initialize" && typeof version === "string") {
+                protocolVersion = version;
+            }
+            write(answer);
+        }
+    };
+    const pending = new Set();
+    const lines = createInterface({ input: process.stdin, crlfDelay: Number.POSITIVE_INFINITY });
+    for await (const line of lines) {
+        if (!line.trim()) {
+            continue;
+        }
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            write({
+                jsonrpc: "2.0",
+                id: null,
+                error: { code: -32700, message: "Parse error" },
+            });
+            continue;
+        }
+        // Requests are answered as they finish: a long get_run never holds up the next call.
+        const job = handle(message).finally(() => pending.delete(job));
+        pending.add(job);
+    }
+    await Promise.all(pending);
+    return 0;
+}

package/apps/runtime/dist/cli/setup.js

@@ -4,6 +4,7 @@ import { delimiter, join } from "node:path";
 import * as p from "@clack/prompts";
 import { autostartState, setAutostart } from "./autostart.js";
 import { installClient, installCommand } from "./clients.js";
+import { appStates, connectApps } from "./connect.js";
 import { runLogged } from "./exec.js";
 import { installedByScript, isCheckout, packageVersion, readInstallNote, writeInstallNote, } from "./home.js";
 import { CLIENTS, detectClients, findChrome, findFfmpeg, findOnPath, suggestedClient, vendorApp, } from "./machine.js";
@@ -176,6 +177,51 @@ async function autostartStep(paths, interactive) {
         p.log.warn(`Starting at login could not be switched on. ${error.message}`);
     }
 }
+/**
+ * The wizards in the person's AI apps (Claude Desktop, Cursor, Codex …): offered for each app on
+ * this machine that does not have them yet. Asked, never assumed; `disconnect` undoes it.
+ */
+async function appsStep(paths, interactive) {
+    const states = await appStates(paths);
+    const connected = states.filter((s) => s.connected);
+    const offered = states.filter((s) => s.installed && !s.connected);
+    if (connected.length) {
+        p.log.success(`In your AI apps: ${connected.map((s) => s.name).join(", ")}`);
+    }
+    if (!offered.length) {
+        return;
+    }
+    if (!interactive) {
+        p.log.info(dim(`To use your wizards in ${offered.map((s) => s.name).join(", ")}: \`${command()} connect\``));
+        return;
+    }
+    const answer = await p.multiselect({
+        message: "Use your wizards in these AI apps? (space to pick, enter to go on)",
+        options: offered.map((s) => ({
+            value: s.id,
+            label: s.name,
+            hint: s.widgets ? "shows runs as a widget" : "as text",
+        })),
+        initialValues: offered.map((s) => s.id),
+        required: false,
+    });
+    if (cancelled(answer)) {
+        return "cancelled";
+    }
+    if (!answer.length) {
+        p.log.info(dim(`Later: \`${command()} connect\``));
+        return;
+    }
+    for (const { app, outcome } of await connectApps(paths, answer)) {
+        if (outcome.ok) {
+            p.log.success(`${app.name}: ${dim(tilde(outcome.message))}`);
+        }
+        else {
+            p.log.warn(`${app.name}: ${outcome.message}${outcome.snippet ? `\n${outcome.snippet}` : ""}`);
+        }
+    }
+    p.log.info(dim("Restart those apps to see the wizards in them."));
+}
 /** The line that puts `~/.local/bin` on the PATH, and the shell file it belongs in. */
 function pathLine() {
     const shell = process.env.SHELL ?? "";
@@ -244,6 +290,9 @@ export async function setup(paths, options) {
     if ((await autostartStep(paths, interactive)) === "cancelled") {
         return null;
     }
+    if ((await appsStep(paths, interactive)) === "cancelled") {
+        return null;
+    }
     if ((await pathStep(interactive)) === "cancelled") {
         return null;
     }

package/apps/runtime/dist/env.js

@@ -192,7 +192,7 @@ export const env = {
         secretAccessKey: str("S3_SECRET_ACCESS_KEY"),
     },
     turnstile: { siteKey: str("TURNSTILE_SITE_KEY"), secret: str("TURNSTILE_SECRET_KEY") },
-    /** Plugins (docs/plugins.md). Code in these folders runs with the runtime's own rights. */
+    /** Plugins (docs/content/dev/plugins). Code in these folders runs with the runtime's own rights. */
     plugins: {
         /** Folders to look in, besides the `modules/` this runtime ships with. */
         dirs: list("PLUGINS_DIR").map((dir) => resolve(dir)),

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

@@ -1,4 +1,5 @@
 import { API_KEY_PREFIX, verifyLocalKey } from "../auth/keys.js";
+import { LOCAL_CLIENT_HEADER, LOCAL_MCP_HEADER, localTicketExpiry } from "../auth/local-ticket.js";
 import { env } from "../env.js";
 import { managed, verifyKey, verifyToken } from "../manage.js";
 import { LOCAL_TENANT } from "../tenants/tenant.js";
@@ -87,8 +88,33 @@ async function tokenAuth(token) {
     };
     return authInfoFor(who, token, claims.clientId);
 }
+/**
+ * A request from `wizards mcp` on this machine: signed with the data folder's secret,
+ * which only a runtime alone has. It acts as the admin, like a key from the settings.
+ */
+function localAuth(request, ticket) {
+    if (managed || !localTicketExpiry(env.authSecret, ticket, Date.now(), "local-mcp")) {
+        return challenge(401, "invalid_token", "This local signature is invalid or expired.");
+    }
+    const client = request.headers
+        .get(LOCAL_CLIENT_HEADER)
+        ?.replace(/[^\p{L}\p{N} ._-]/gu, "")
+        .trim()
+        .slice(0, 60) || "MCP";
+    const who = {
+        userId: "local",
+        tenantId: LOCAL_TENANT,
+        client,
+        scopes: [...SCOPES],
+    };
+    return authInfoFor(who, ticket, "local");
+}
 /** Who an MCP or API request acts for: an API key (`x-api-key` or a `wz_…` bearer) or an OAuth access token. */
 export async function authenticate(request) {
+    const local = request.headers.get(LOCAL_MCP_HEADER)?.trim();
+    if (local) {
+        return localAuth(request, local);
+    }
     const header = request.headers.get("x-api-key")?.trim();
     const token = bearer(request);
     const key = header || (token?.startsWith(API_KEY_PREFIX) ? token : null);

package/apps/runtime/dist/mcp/flow-app.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RESOURCE_MIME_TYPE, registerAppResource } from "@modelcontextprotocol/ext-apps/server";
+import { env } from "../env.js";
+import { runTicket } from "../secrets/signing.js";
+import { draftIssues, ownedWizard, publishedVersion } from "../services/wizards.js";
+/**
+ * The flow widget (MCP Apps): a wizard as its diagram, and a run on it — where it stands, what
+ * it made, the page it waits for. Hosts that render MCP Apps (Claude Desktop, Cursor, VS Code,
+ * Goose, ChatGPT) show it in the chat; the others get the same tools as text.
+ */
+/** Built by the web app (`vite.mcp-app.config.ts`) into one HTML file with everything inline. */
+const FLOW_APP_FILE = resolve(dirname(fileURLToPath(import.meta.url)), "../../../web/dist/mcp/flow.html");
+const MISSING = `<!doctype html><meta charset="utf-8"><body style="font:14px system-ui;padding:16px">
+The flow widget is not built: run <code>pnpm --filter @engenty-wizards/web build</code>.</body>`;
+function readWidget() {
+    try {
+        return readFileSync(FLOW_APP_FILE, "utf8");
+    }
+    catch {
+        return MISSING;
+    }
+}
+const FLOW_APP_HTML = readWidget();
+/**
+ * Hosts keep a widget by its URI, so the URI names the build: a new widget gets a new address
+ * instead of the cached old one.
+ */
+export const FLOW_APP_URI = `ui://engenty-wizards/flow-${createHash("sha256").update(FLOW_APP_HTML).digest("hex").slice(0, 10)}.html`;
+export function registerFlowApp(server) {
+    const origin = new URL(env.appUrl).origin;
+    registerAppResource(server, "Wizard flow", FLOW_APP_URI, {
+        description: "A wizard as a diagram, and a run on it.",
+        mimeType: RESOURCE_MIME_TYPE,
+    }, async () => ({
+        contents: [
+            {
+                uri: FLOW_APP_URI,
+                mimeType: RESOURCE_MIME_TYPE,
+                text: FLOW_APP_HTML,
+                _meta: {
+                    ui: {
+                        // The run and its files are served by this runtime; the fonts by Google.
+                        csp: {
+                            connectDomains: [origin],
+                            resourceDomains: [
+                                origin,
+                                "https://fonts.googleapis.com",
+                                "https://fonts.gstatic.com",
+                            ],
+                        },
+                        prefersBorder: true,
+                    },
+                },
+            },
+        ],
+    }));
+}
+/**
+ * The widget's data for a wizard: the published version when there is one (that is what runs),
+ * else the draft. A run brings the definition it started on.
+ */
+export async function flowView(userId, wizardId, options = {}) {
+    const w = await ownedWizard(userId, wizardId);
+    const published = options.shows === "draft" ? null : await publishedVersion(w);
+    const shows = published ? "published" : "draft";
+    const definition = options.definition ?? published?.definition ?? w.draft;
+    return {
+        wizard: {
+            id: w.id,
+            title: definition.title,
+            description: definition.description,
+            avatar: definition.avatar,
+            shows,
+            published: w.publishedVersion !== null,
+            issues: shows === "draft" ? (await draftIssues(w)).length : undefined,
+        },
+        definition,
+        run: options.run,
+        runtime: options.run ? { base: env.appUrl, ticket: runTicket(options.run.runId) } : undefined,
+    };
+}
+/** A tool's `_meta` that opens the widget with the tool's result. */
+export const flowAppMeta = {
+    ui: { resourceUri: FLOW_APP_URI },
+    "openai/outputTemplate": FLOW_APP_URI,
+};
+/**
+ * Where a result carries the widget's data. The definition stays out of `structuredContent`,
+ * which hosts hand to the model as well; `_meta` only reaches the widget.
+ */
+export const FLOW_VIEW_KEY = "engenty/flow";

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

@@ -3,11 +3,13 @@ import { withTenant } from "../db/client.js";
 import { env } from "../env.js";
 import { tenantStatus } from "../tenants/control.js";
 import { authenticate, principalOf } from "./auth.js";
+import { registerFlowApp } from "./flow-app.js";
+import { noteRequest } from "./seen.js";
 import { registerPrompts, registerTools } from "./tools.js";
-const INSTRUCTIONS = `engenty wizards: build page-by-page AI wizards that people open on a shared link.
-Start with get_authoring_guide (schema + design rules), look at a close starter with get_starter, then create_wizard and refine with edit_wizard until "issues" is empty.
-Check it with start_test_run + get_test_run (waitSeconds) — test runs spend the admin's credits.
-Publish only when the admin asks. Hand the admin the studioUrl: the studio shows the wizard as a diagram.`;
+const INSTRUCTIONS = `engenty wizards: page-by-page AI wizards — the person answers pages, AI steps write, research and make images or videos, the person reviews, the result is files.
+Use one: list_wizards, then run_wizard straight away — its widget shows the wizard itself (show_wizard only when the person wants to see a wizard before running it), then follow waitingFor (answer_page, review_step, answer_ask, get_run with waitSeconds). Runs spend credits.
+Build one: get_authoring_guide (schema + design rules), a close starter with get_starter, create_wizard, edit_wizard until "issues" is empty, check with start_test_run + get_test_run. Publish only when the admin asks.
+When a run needs the browser, hand over its browserUrl, the wizard's own run page. The studioUrl is for building only: never send someone who uses a wizard to the studio.`;
 /** A wizard definition is a few KB; this leaves room and refuses anything far beyond it. */
 const MAX_BODY_BYTES = 300_000;
 /**
@@ -18,10 +20,11 @@ const MAX_BODY_BYTES = 300_000;
 export function mcpHandler() {
     const allowedHosts = [new URL(env.appUrl).hostname, "localhost", "127.0.0.1"];
     const handler = createMcpHandler((ctx) => {
-        const server = new McpServer({ name: "engenty-wizards", version: "0.1.0" }, { instructions: INSTRUCTIONS, capabilities: { tools: {}, prompts: {} } });
+        const server = new McpServer({ name: "engenty-wizards", version: "0.1.0" }, { instructions: INSTRUCTIONS, capabilities: { tools: {}, prompts: {}, resources: {} } });
         const who = principalOf(ctx.authInfo);
         registerTools(server, who);
         registerPrompts(server);
+        registerFlowApp(server);
         return server;
     }, { legacy: "stateless", maxRequestBodySize: MAX_BODY_BYTES });
     return async (request) => {
@@ -37,6 +40,13 @@ export function mcpHandler() {
         if ((await tenantStatus(who.tenantId)) === "suspended") {
             return new Response(JSON.stringify({ error: "tenant_suspended" }), { status: 403 });
         }
+        if (request.method === "POST") {
+            const body = await request
+                .clone()
+                .json()
+                .catch(() => null);
+            noteRequest(who.tenantId, authInfo.clientId, who.client, body);
+        }
         return withTenant(who.tenantId, () => handler.fetch(request, { authInfo }));
     };
 }

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

@@ -0,0 +1,65 @@
+/**
+ * What each AI client did with the MCP server since the runtime started: the test on the
+ * "Integrate" page waits for a client to show up, call a tool and show the widget. Kept in memory
+ * only; a restart starts the test over.
+ */
+/** The ids the studio lists the AI apps by, and the names they give themselves (`clientInfo`). */
+const CLIENT_NAMES = [
+    // Claude Desktop calls itself claude-ai, as claude.ai does.
+    ["claude-desktop", /claude[- ]?ai|claude desktop/i],
+    ["claude-ai", /claude[- ]?ai/i],
+    ["claude-code", /claude[- ]?code/i],
+    ["codex", /codex/i],
+    ["chatgpt", /openai|chatgpt/i],
+    ["cursor", /cursor/i],
+    // Cursor calls itself cursor-vscode.
+    ["vscode", /^(?!.*cursor).*(visual studio code|vs ?code)/i],
+    ["windsurf", /windsurf|codeium/i],
+    ["gemini", /gemini/i],
+    ["goose", /goose/i],
+    ["openclaw", /openclaw/i],
+    ["lm-studio", /lm[- ]?studio/i],
+];
+/** The apps a client's name stands for; mostly one. */
+export function appIdsOf(client) {
+    return CLIENT_NAMES.filter(([, name]) => name.test(client)).map(([id]) => id);
+}
+const seen = new Map();
+/** The name a client gave on `initialize`, by its sign-in: later requests do not repeat it. */
+const names = new Map();
+/** Notes one MCP request: its JSON-RPC messages, from the client signed in as `signIn`. */
+export function noteRequest(tenantId, signIn, client, body) {
+    const messages = (Array.isArray(body) ? body : [body]).filter((m) => Boolean(m) && typeof m === "object");
+    const info = messages.find((m) => m.method === "initialize")?.params?.clientInfo;
+    const given = info?.title || info?.name;
+    if (given) {
+        names.set(signIn, given);
+    }
+    const name = names.get(signIn) ?? client;
+    const now = Date.now();
+    for (const id of appIdsOf(name)) {
+        const key = `${tenantId}\n${id}`;
+        const last = seen.get(key) ?? { at: now, toolAt: null, widgetAt: null };
+        last.at = now;
+        for (const m of messages) {
+            if (m.method === "tools/call") {
+                last.toolAt = now;
+            }
+            if (m.method === "resources/read" && String(m.params?.uri ?? "").startsWith("ui://")) {
+                last.widgetAt = now;
+            }
+        }
+        seen.set(key, last);
+    }
+}
+/** What the tenant's clients did, by app id. */
+export function seenApps(tenantId) {
+    const out = {};
+    for (const [key, value] of seen) {
+        const [tenant, id] = key.split("\n");
+        if (tenant === tenantId) {
+            out[id] = value;
+        }
+    }
+    return out;
+}