wizards 0.1.11 → 0.2.1

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

@@ -0,0 +1,531 @@
+import { execFile, execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { installedByScript, packageRoot } from "./home.js";
+import { findOnPath } from "./machine.js";
+import { bad, dim, ok, tilde } from "./ui.js";
+const run = promisify(execFile);
+/**
+ * The wizards in the person's own AI apps: `wizards connect` writes this install's MCP
+ * server into each app's config, as the command `wizards mcp` (stdio). Every app starts
+ * servers that way; the command finds the running runtime itself and signs in with the data
+ * folder's secret, so a config holds neither a port nor a key.
+ */
+/** The name the server has in every app's config. */
+export const SERVER_NAME = "engenty-wizards";
+/**
+ * How an app starts this install's MCP server. An install made by install.sh has a command that
+ * stays where it is across updates; any other copy is started by its Node and its script. The
+ * studio connects apps too: from the runtime, which is not the command.
+ */
+export function serverCommand(paths, script = join(packageRoot, "bin", "wizards.mjs")) {
+    const moved = dirname(paths.home) !== join(homedir(), ".engenty");
+    const env = moved ? { env: { ENGENTY_HOME: dirname(paths.home) } } : {};
+    if (installedByScript(paths)) {
+        return { command: join(paths.bin, "wizards"), args: ["mcp"], ...env };
+    }
+    return { command: process.execPath, args: [script, "mcp"], ...env };
+}
+/** A JSON config with the server set under `at` (e.g. ["mcpServers"]); null when it is no JSON. */
+export function withJsonServer(text, at, entry, name = SERVER_NAME) {
+    let root;
+    try {
+        root = text?.trim() ? JSON.parse(text) : {};
+    }
+    catch {
+        return null;
+    }
+    if (!root || typeof root !== "object" || Array.isArray(root)) {
+        return null;
+    }
+    let node = root;
+    for (const key of at) {
+        const next = node[key];
+        if (!next || typeof next !== "object" || Array.isArray(next)) {
+            node[key] = {};
+        }
+        node = node[key];
+    }
+    node[name] = entry;
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+/** The same config without the server; null when it is no JSON. */
+export function withoutJsonServer(text, at, name = SERVER_NAME) {
+    let root;
+    try {
+        root = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    let node = root;
+    for (const key of at) {
+        node = node?.[key];
+    }
+    if (node && typeof node === "object") {
+        delete node[name];
+    }
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+export function jsonHasServer(text, at, name = SERVER_NAME) {
+    try {
+        let node = JSON.parse(text);
+        for (const key of at) {
+            node = node?.[key];
+        }
+        return Boolean(node && typeof node === "object" && name in node);
+    }
+    catch {
+        return false;
+    }
+}
+const tomlString = (value) => JSON.stringify(value);
+/** A TOML config (Codex) without the server's tables `[mcp_servers.<name>]` and below. */
+export function withoutTomlServer(text, name = SERVER_NAME) {
+    const lines = text.split("\n");
+    const out = [];
+    let skipping = false;
+    for (const line of lines) {
+        const table = line.match(/^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/)?.[1];
+        if (table !== undefined) {
+            const key = table.replaceAll('"', "");
+            skipping = key === `mcp_servers.${name}` || key.startsWith(`mcp_servers.${name}.`);
+        }
+        if (!skipping) {
+            out.push(line);
+        }
+    }
+    return out.join("\n").replace(/\n{3,}$/, "\n\n");
+}
+export function withTomlServer(text, server, name = SERVER_NAME) {
+    const rest = withoutTomlServer(text ?? "", name).trimEnd();
+    const table = [
+        `[mcp_servers.${name}]`,
+        `command = ${tomlString(server.command)}`,
+        `args = [${server.args.map(tomlString).join(", ")}]`,
+        // A run waits up to 45 s for a step; the default of 60 s leaves room for it.
+        "tool_timeout_sec = 120",
+        ...(server.env
+            ? [
+                `env = { ${Object.entries(server.env)
+                    .map(([key, value]) => `${key} = ${tomlString(value)}`)
+                    .join(", ")} }`,
+            ]
+            : []),
+    ].join("\n");
+    return `${rest ? `${rest}\n\n` : ""}${table}\n`;
+}
+export function tomlHasServer(text, name = SERVER_NAME) {
+    return text.split("\n").some((line) => line.trim() === `[mcp_servers.${name}]`);
+}
+/** Goose's YAML: the server's block below `extensions:`, at two spaces. */
+export function withoutYamlExtension(text, name = SERVER_NAME) {
+    const lines = text.split("\n");
+    const out = [];
+    let skipping = false;
+    for (const line of lines) {
+        if (line === `  ${name}:`) {
+            skipping = true;
+            continue;
+        }
+        if (skipping && line.trim() && !line.startsWith("   ")) {
+            skipping = false;
+        }
+        if (!skipping) {
+            out.push(line);
+        }
+    }
+    return out.join("\n");
+}
+export function withYamlExtension(text, server, name = SERVER_NAME) {
+    const quote = (value) => JSON.stringify(value);
+    const block = [
+        `  ${name}:`,
+        `    name: ${name}`,
+        "    type: stdio",
+        `    cmd: ${quote(server.command)}`,
+        `    args: [${server.args.map(quote).join(", ")}]`,
+        "    enabled: true",
+        "    timeout: 300",
+        ...(server.env
+            ? [
+                "    envs:",
+                ...Object.entries(server.env).map(([key, value]) => `      ${key}: ${quote(value)}`),
+            ]
+            : []),
+    ];
+    const lines = withoutYamlExtension(text ?? "", name).split("\n");
+    const at = lines.findIndex((line) => /^extensions:\s*(\{\s*\})?\s*$/.test(line));
+    if (at === -1) {
+        const rest = lines.join("\n").trimEnd();
+        return `${rest ? `${rest}\n` : ""}extensions:\n${block.join("\n")}\n`;
+    }
+    lines[at] = "extensions:";
+    lines.splice(at + 1, 0, ...block);
+    return lines.join("\n");
+}
+export function yamlHasExtension(text, name = SERVER_NAME) {
+    return text.split("\n").includes(`  ${name}:`);
+}
+const home = homedir();
+const appData = process.env.APPDATA || join(home, "AppData", "Roaming");
+/** A folder below the per-user application data: Library/Application Support, %APPDATA%, ~/.config. */
+function appSupport(...parts) {
+    if (process.platform === "darwin") {
+        return join(home, "Library", "Application Support", ...parts);
+    }
+    if (process.platform === "win32") {
+        return join(appData, ...parts);
+    }
+    return join(process.env.XDG_CONFIG_HOME || join(home, ".config"), ...parts);
+}
+/** Claude Desktop's main process, as `ps` (macOS) or `tasklist` (Windows) names it. */
+const CLAUDE_DESKTOP_PROCESS = {
+    darwin: /\/Claude\.app\/Contents\/MacOS\/Claude$/m,
+    win32: /^"?Claude\.exe"?,/im,
+};
+/** Whether an app's process runs; false where it cannot be told (Linux, no `ps`). */
+export function processRunning(names, platform = process.platform, list = () => platform === "win32"
+    ? execFileSync("tasklist", ["/FO", "CSV", "/NH"], { encoding: "utf8" })
+    : execFileSync("ps", ["-axo", "comm"], { encoding: "utf8" })) {
+    const pattern = names[platform];
+    if (!pattern) {
+        return false;
+    }
+    try {
+        return pattern.test(list());
+    }
+    catch {
+        return false;
+    }
+}
+const read = (file) => (existsSync(file) ? readFileSync(file, "utf8") : null);
+/** Writes a config, keeping the version before it once next to it. */
+function save(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    if (existsSync(file)) {
+        copyFileSync(file, `${file}.before-engenty`);
+    }
+    writeFileSync(file, text);
+}
+function jsonApp(def) {
+    const running = () => def.ownsFileWhileRunning?.()
+        ? {
+            ok: false,
+            message: `${def.name} is running and would overwrite its config. Quit it (Cmd+Q), then run this again.`,
+        }
+        : null;
+    const snippet = (server) => JSON.stringify(def.at.reduceRight((inner, key) => ({ [key]: inner }), {
+        [SERVER_NAME]: def.entry(server),
+    }), null, 2);
+    return {
+        id: def.id,
+        name: def.name,
+        widgets: def.widgets,
+        where: def.file,
+        installed: () => existsSync(def.marker),
+        connected: async () => jsonHasServer(read(def.file) ?? "", def.at),
+        async connect(server) {
+            const busy = running();
+            if (busy) {
+                return busy;
+            }
+            const next = withJsonServer(read(def.file), def.at, def.entry(server));
+            if (next === null) {
+                return {
+                    ok: false,
+                    message: `${def.file} is not plain JSON (comments?); add this to it:`,
+                    snippet: snippet(server),
+                };
+            }
+            save(def.file, next);
+            return { ok: true, message: `added to ${def.file}` };
+        },
+        async disconnect() {
+            const text = read(def.file);
+            if (!text || !jsonHasServer(text, def.at)) {
+                return { ok: true, message: "was not connected" };
+            }
+            const busy = running();
+            if (busy) {
+                return busy;
+            }
+            const next = withoutJsonServer(text, def.at);
+            if (next === null) {
+                return {
+                    ok: false,
+                    message: `${def.file} is not plain JSON; remove "${SERVER_NAME}" there.`,
+                };
+            }
+            save(def.file, next);
+            return { ok: true, message: `removed from ${def.file}` };
+        },
+    };
+}
+const stdioEntry = (server) => ({
+    command: server.command,
+    args: server.args,
+    ...(server.env ? { env: server.env } : {}),
+});
+/** A command of an app: on the PATH, or among the clients this install brought. */
+function appCommand(paths, name) {
+    return findOnPath(name, [join(paths.clients, "bin"), process.env.PATH ?? ""].join(delimiter));
+}
+function claudeCode(paths) {
+    const file = join(home, ".claude.json");
+    return {
+        id: "claude-code",
+        name: "Claude Code",
+        widgets: false,
+        where: "claude mcp (user scope)",
+        installed: () => Boolean(appCommand(paths, "claude")),
+        connected: async () => jsonHasServer(read(file) ?? "", ["mcpServers"]),
+        async connect(server) {
+            const claude = appCommand(paths, "claude");
+            if (!claude) {
+                return { ok: false, message: "the claude command was not found" };
+            }
+            // Claude Code keeps rewriting its own file: its command changes it, not we.
+            await run(claude, ["mcp", "remove", "--scope", "user", SERVER_NAME]).catch(() => undefined);
+            try {
+                await run(claude, [
+                    "mcp",
+                    "add",
+                    "--scope",
+                    "user",
+                    ...Object.entries(server.env ?? {}).flatMap(([key, value]) => ["-e", `${key}=${value}`]),
+                    SERVER_NAME,
+                    "--",
+                    server.command,
+                    ...server.args,
+                ]);
+                return { ok: true, message: "added with `claude mcp add --scope user`" };
+            }
+            catch (error) {
+                return { ok: false, message: error.message.split("\n")[0] };
+            }
+        },
+        async disconnect() {
+            const claude = appCommand(paths, "claude");
+            if (!claude) {
+                return { ok: true, message: "was not connected" };
+            }
+            await run(claude, ["mcp", "remove", "--scope", "user", SERVER_NAME]).catch(() => undefined);
+            return { ok: true, message: "removed with `claude mcp remove`" };
+        },
+    };
+}
+function codex() {
+    const dir = process.env.CODEX_HOME || join(home, ".codex");
+    const file = join(dir, "config.toml");
+    return {
+        id: "codex",
+        name: "Codex · ChatGPT app",
+        widgets: false,
+        where: file,
+        installed: () => existsSync(dir),
+        connected: async () => tomlHasServer(read(file) ?? ""),
+        async connect(server) {
+            save(file, withTomlServer(read(file), server));
+            return { ok: true, message: `added to ${file}` };
+        },
+        async disconnect() {
+            const text = read(file);
+            if (!text || !tomlHasServer(text)) {
+                return { ok: true, message: "was not connected" };
+            }
+            save(file, withoutTomlServer(text));
+            return { ok: true, message: `removed from ${file}` };
+        },
+    };
+}
+function goose() {
+    const dir = process.platform === "win32"
+        ? join(appData, "Block", "goose", "config")
+        : join(process.env.XDG_CONFIG_HOME || join(home, ".config"), "goose");
+    const file = join(dir, "config.yaml");
+    return {
+        id: "goose",
+        name: "Goose",
+        widgets: true,
+        where: file,
+        installed: () => existsSync(dir),
+        connected: async () => yamlHasExtension(read(file) ?? ""),
+        async connect(server) {
+            save(file, withYamlExtension(read(file), server));
+            return { ok: true, message: `added to ${file}` };
+        },
+        async disconnect() {
+            const text = read(file);
+            if (!text || !yamlHasExtension(text)) {
+                return { ok: true, message: "was not connected" };
+            }
+            save(file, withoutYamlExtension(text));
+            return { ok: true, message: `removed from ${file}` };
+        },
+    };
+}
+function openClaw(paths) {
+    const dir = join(home, ".openclaw");
+    const file = join(dir, "openclaw.json");
+    const json = jsonApp({
+        id: "openclaw",
+        name: "OpenClaw",
+        widgets: false,
+        file,
+        marker: dir,
+        at: ["mcp", "servers"],
+        entry: stdioEntry,
+    });
+    return {
+        ...json,
+        // Its config is JSON5: its own command writes it when it is there.
+        async connect(server) {
+            const openclaw = appCommand(paths, "openclaw");
+            if (!openclaw) {
+                return json.connect(server);
+            }
+            try {
+                await run(openclaw, [
+                    "mcp",
+                    "set",
+                    SERVER_NAME,
+                    "--command",
+                    server.command,
+                    "--args",
+                    ...server.args,
+                ]);
+                return { ok: true, message: "added with `openclaw mcp set`" };
+            }
+            catch (error) {
+                return { ok: false, message: error.message.split("\n")[0] };
+            }
+        },
+        async disconnect() {
+            const openclaw = appCommand(paths, "openclaw");
+            if (!openclaw) {
+                return json.disconnect();
+            }
+            await run(openclaw, ["mcp", "unset", SERVER_NAME]).catch(() => undefined);
+            return { ok: true, message: "removed with `openclaw mcp unset`" };
+        },
+    };
+}
+/** The AI apps this install can connect to, in the order they are offered. */
+export function apps(paths) {
+    const vscodeUser = appSupport("Code", "User");
+    return [
+        jsonApp({
+            id: "claude-desktop",
+            name: "Claude Desktop",
+            widgets: true,
+            file: join(appSupport("Claude"), "claude_desktop_config.json"),
+            marker: appSupport("Claude"),
+            at: ["mcpServers"],
+            entry: stdioEntry,
+            ownsFileWhileRunning: () => processRunning(CLAUDE_DESKTOP_PROCESS),
+        }),
+        claudeCode(paths),
+        codex(),
+        jsonApp({
+            id: "cursor",
+            name: "Cursor",
+            widgets: true,
+            file: join(home, ".cursor", "mcp.json"),
+            marker: join(home, ".cursor"),
+            at: ["mcpServers"],
+            entry: stdioEntry,
+        }),
+        jsonApp({
+            id: "vscode",
+            name: "VS Code (Copilot)",
+            widgets: true,
+            file: join(vscodeUser, "mcp.json"),
+            marker: vscodeUser,
+            at: ["servers"],
+            entry: (server) => ({ type: "stdio", ...stdioEntry(server) }),
+        }),
+        jsonApp({
+            id: "windsurf",
+            name: "Windsurf",
+            widgets: false,
+            file: join(home, ".codeium", "windsurf", "mcp_config.json"),
+            marker: join(home, ".codeium", "windsurf"),
+            at: ["mcpServers"],
+            entry: stdioEntry,
+        }),
+        jsonApp({
+            id: "gemini",
+            name: "Gemini CLI",
+            widgets: false,
+            file: join(home, ".gemini", "settings.json"),
+            marker: join(home, ".gemini"),
+            at: ["mcpServers"],
+            entry: (server) => ({ ...stdioEntry(server), timeout: 120_000 }),
+        }),
+        goose(),
+        openClaw(paths),
+        jsonApp({
+            id: "lm-studio",
+            name: "LM Studio",
+            widgets: false,
+            file: join(home, ".lmstudio", "mcp.json"),
+            marker: join(home, ".lmstudio"),
+            at: ["mcpServers"],
+            entry: stdioEntry,
+        }),
+    ];
+}
+export async function appStates(paths) {
+    return Promise.all(apps(paths).map(async (app) => ({
+        id: app.id,
+        name: app.name,
+        widgets: app.widgets,
+        where: app.where,
+        installed: app.installed(),
+        connected: await app.connected(),
+    })));
+}
+/** `wizards connect [app …]` and `disconnect`: what was done, app by app. */
+export async function connectCommand(paths, ids, remove) {
+    const unknown = ids.filter((id) => !apps(paths).some((app) => app.id === id));
+    if (unknown.length) {
+        console.error(`Unknown app ${unknown.join(", ")}. One of: ${apps(paths)
+            .map((app) => app.id)
+            .join(", ")}`);
+        return 2;
+    }
+    const results = await connectApps(paths, ids, remove);
+    if (!results.length) {
+        console.log("No AI app found on this machine. Name one: connect cursor");
+        return 0;
+    }
+    for (const { app, outcome } of results) {
+        console.log(`${outcome.ok ? ok : bad} ${app.name.padEnd(22)} ${dim(tilde(outcome.message))}`);
+        if (!outcome.ok && outcome.snippet) {
+            console.log(outcome.snippet);
+        }
+    }
+    if (!remove && results.some((r) => r.outcome.ok)) {
+        console.log("");
+        console.log(dim("Restart the app (or reload its MCP servers) to see the wizards in it."));
+        console.log(dim("Claude Desktop, Cursor, VS Code and Goose show a run as a widget; the others as text."));
+    }
+    return results.every((r) => r.outcome.ok) ? 0 : 1;
+}
+/** Connects (or disconnects) the named apps; without names every app found on this machine. */
+export async function connectApps(paths, ids, remove = false) {
+    const all = apps(paths);
+    const picked = ids.length
+        ? all.filter((app) => ids.includes(app.id))
+        : all.filter((app) => app.installed());
+    const server = serverCommand(paths);
+    const out = [];
+    for (const app of picked) {
+        const outcome = await (remove ? app.disconnect() : app.connect(server)).catch((error) => ({ ok: false, message: error.message }));
+        out.push({ app, outcome });
+    }
+    return out;
+}

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

@@ -1,4 +1,4 @@
-import { delimiter, dirname, join } from "node:path";
+import { basename, delimiter, dirname, join } from "node:path";
 /**
  * Variables of the terminal the runtime inherits. Everything else it gets comes from the
  * install's `.env` or is set by the command line. A key or a database address that the shell
@@ -35,6 +35,8 @@ const INHERITED = new Set([
     "SANDBOX",
     "SANDBOX_ENABLED",
     "SANDBOX_IMAGE",
+    "PLUGINS_DIR",
+    "PLUGINS_WATCH",
     "ACCOUNT_URL",
     "ACCOUNT_GATEWAY_URL",
     "CLOUD_URL",
@@ -67,7 +69,10 @@ export function runtimePath(paths, env, node = process.execPath) {
  */
 export function runtimeEnv(paths, start, env = process.env, fileEnv = {}, platform = process.platform) {
     const secretsGiven = env.SECRETS !== undefined || fileEnv.SECRETS !== undefined;
+    const pluginsGiven = env.PLUGINS_DIR !== undefined || fileEnv.PLUGINS_DIR !== undefined;
     return {
+        // Plugins live beside the data, in the install's own folder.
+        ...(pluginsGiven ? {} : { PLUGINS_DIR: paths.plugins }),
         ...inherited(env),
         PATH: runtimePath(paths, env),
         NODE_ENV: "production",
@@ -75,6 +80,8 @@ export function runtimeEnv(paths, start, env = process.env, fileEnv = {}, platfo
         APP_URL: start.url,
         DATA_DIR: start.dataDir,
         LOCAL_ACCESS_KEY: start.accessKey,
+        // The install the runtime belongs to: the studio connects AI apps to its command.
+        ...(basename(paths.home) === "wizards" ? { ENGENTY_HOME: dirname(paths.home) } : {}),
         // Keys entered in the settings live in the Keychain, as with the desktop app.
         ...(platform === "darwin" && !secretsGiven ? { SECRETS: "keychain" } : {}),
     };

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

@@ -21,6 +21,7 @@ export function layout(home = wizardsHome()) {
         tools: join(home, "tools"),
         clients: join(home, "clients"),
         bin: join(home, "bin"),
+        plugins: join(home, "plugins"),
     };
 }
 /** The folder this code was installed to: it holds `apps/`, `plugin/` and package.json. */

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;