wizards 0.1.9

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

@@ -0,0 +1,190 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { join, resolve } from "node:path";
+import { styleText } from "node:util";
+import { mintLocalTicket } from "../auth/local-ticket.js";
+import { readRunning } from "../running.js";
+import { RESTART_EXIT } from "../update.js";
+import { runtimeEnv } from "./environment.js";
+import { packageRoot, readEnvFile } from "./home.js";
+import { findOnPath } from "./machine.js";
+const DEFAULT_PORT = 24368;
+const START_TIMEOUT_MS = 60_000;
+/** The settings this install starts with: its `.env`, overridden by the terminal's variables. */
+export function settings(paths, env = process.env) {
+    const fileEnv = readEnvFile(paths.envFile);
+    const value = (key) => env[key]?.trim() || fileEnv[key]?.trim() || "";
+    return {
+        fileEnv,
+        dataDir: value("DATA_DIR") ? resolve(paths.home, value("DATA_DIR")) : paths.data,
+        port: Number(value("API_PORT")) || null,
+        appUrl: value("APP_URL").replace(/\/$/, ""),
+    };
+}
+export async function healthy(port) {
+    try {
+        const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+            signal: AbortSignal.timeout(1500),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+function portIsFree(port) {
+    return new Promise((done) => {
+        const probe = createServer();
+        probe.once("error", () => done(false));
+        probe.listen(port, "127.0.0.1", () => probe.close(() => done(true)));
+    });
+}
+/** The usual port, or the next free one after it. */
+async function freePort() {
+    for (let port = DEFAULT_PORT; port < DEFAULT_PORT + 20; port++) {
+        if (await portIsFree(port)) {
+            return port;
+        }
+    }
+    throw new Error(`No free port between ${DEFAULT_PORT} and ${DEFAULT_PORT + 19}.`);
+}
+/** The runtime that already runs on this install's data folder and answers. */
+export async function runningRuntime(dataDir) {
+    const running = readRunning(dataDir);
+    return running && (await healthy(running.port)) ? running : null;
+}
+/** A link that lets this browser into a running runtime: a ticket signed with the data folder's secret. */
+export function entryUrl(running, dataDir) {
+    try {
+        const secret = readFileSync(join(dataDir, "secret"), "utf8").trim();
+        return `${running.url}/api/local/enter?t=${mintLocalTicket(secret)}`;
+    }
+    catch {
+        // APP_SECRET is set elsewhere: the browser gets in if it was let in before.
+        return `${running.url}/`;
+    }
+}
+/** Opens an address in the person's browser; false when this machine has none to open it with. */
+export function openBrowser(url) {
+    const opener = process.platform === "darwin"
+        ? "open"
+        : process.env.DISPLAY || process.env.WAYLAND_DISPLAY
+            ? "xdg-open"
+            : null;
+    if (!opener || !findOnPath(opener, process.env.PATH ?? "")) {
+        return false;
+    }
+    try {
+        spawn(opener, [url], { stdio: "ignore", detached: true }).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function show(url, entry, open) {
+    const opened = open && openBrowser(entry);
+    console.log("");
+    console.log(`  ${styleText("green", "●")} engenty wizards is running: ${styleText("cyan", url)}`);
+    if (opened) {
+        console.log(styleText("dim", "    The studio opens in your browser."));
+    }
+    else {
+        console.log(`    Open the studio: ${entry}`);
+        console.log(styleText("dim", "    The link lets one browser in and works once."));
+    }
+}
+/**
+ * Starts the runtime of this install in the foreground and opens the studio. If one already
+ * runs on the same data folder (another terminal, the desktop app), that one is opened instead.
+ */
+export async function start(paths, options) {
+    const { fileEnv, dataDir, port: wanted, appUrl } = settings(paths);
+    mkdirSync(dataDir, { recursive: true });
+    mkdirSync(paths.logs, { recursive: true });
+    const running = await runningRuntime(dataDir);
+    if (running) {
+        show(running.url, entryUrl(running, dataDir), options.open);
+        console.log(styleText("dim", "    It was already running; stop it with `wizards stop`."));
+        return 0;
+    }
+    const port = wanted ?? (await freePort());
+    if (!wanted && port !== DEFAULT_PORT) {
+        console.log(styleText("dim", `  Port ${DEFAULT_PORT} is taken, using ${port}.`));
+    }
+    const accessKey = randomBytes(24).toString("hex");
+    const url = appUrl || `http://localhost:${port}`;
+    const child = spawn(process.execPath, [join(packageRoot, "apps/runtime/dist/index.js")], {
+        cwd: paths.home,
+        env: {
+            ...runtimeEnv(paths, { port, url, dataDir, accessKey }, process.env, fileEnv),
+            // This command starts it again when it exits with RESTART_EXIT.
+            ENGENTY_WIZARDS_RESTARTS: "1",
+        },
+        stdio: ["ignore", "inherit", "inherit"],
+    });
+    let current = child;
+    let exited = null;
+    const ended = new Promise((done) => {
+        child.on("error", (error) => {
+            console.error(`The runtime did not start: ${error.message}`);
+            exited = 1;
+            done(1);
+        });
+        child.on("exit", (code, signal) => {
+            exited = code ?? (signal ? 0 : 1);
+            done(exited);
+        });
+    });
+    // Ctrl-C reaches the runtime as well (same terminal); it closes its browser and its databases.
+    process.on("SIGINT", () => undefined);
+    process.on("SIGTERM", () => current.kill("SIGTERM"));
+    const began = Date.now();
+    while (exited === null && !(await healthy(port))) {
+        if (Date.now() - began > START_TIMEOUT_MS) {
+            child.kill("SIGTERM");
+            console.error("The runtime did not answer within 60 seconds.");
+            return 1;
+        }
+        await new Promise((wait) => setTimeout(wait, 150));
+    }
+    if (exited !== null) {
+        return exited || 1;
+    }
+    show(url, `${url}/api/local/enter?k=${accessKey}`, options.open);
+    console.log(styleText("dim", "    Stop it with Ctrl-C."));
+    console.log("");
+    const code = await ended;
+    if (code !== RESTART_EXIT) {
+        return code;
+    }
+    // Updated: the command as it is on disk now starts the new version, in this terminal or
+    // under the login item, which keeps waiting on this process.
+    console.log(styleText("dim", "  Updated; starting the new version."));
+    const wrapper = join(paths.bin, "wizards");
+    current = existsSync(wrapper)
+        ? spawn(wrapper, ["start", "--no-open"], { stdio: "inherit" })
+        : spawn(process.execPath, [join(packageRoot, "bin/wizards.mjs"), "start", "--no-open"], {
+            stdio: "inherit",
+        });
+    return new Promise((done) => {
+        current.on("error", () => done(1));
+        current.on("exit", (exit) => done(exit ?? 0));
+    });
+}
+/** `wizards open`: lets the browser into the runtime that runs. */
+export async function open(paths, print) {
+    const { dataDir } = settings(paths);
+    const running = await runningRuntime(dataDir);
+    if (!running) {
+        console.error("engenty wizards is not running. Start it with `wizards`.");
+        return 1;
+    }
+    const entry = entryUrl(running, dataDir);
+    if (print || !openBrowser(entry)) {
+        console.log(entry);
+    }
+    return 0;
+}

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

@@ -0,0 +1,120 @@
+import { accessSync, constants, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { autostartState, setAutostart } from "./autostart.js";
+import { installedByScript, isCheckout, packageRoot, packageVersion } from "./home.js";
+import { detectClients, findChrome, findFfmpeg, nodeIsCurrent } from "./machine.js";
+import { runningRuntime, settings } from "./start.js";
+import { bad, badge, cyan, dim, no, ok, tilde } from "./ui.js";
+/**
+ * What is installed and what runs. With `checks` (`doctor`) it also says what is wrong and
+ * returns 1 when something is.
+ */
+export async function status(paths, checks) {
+    const { dataDir } = settings(paths);
+    const [running, clients, ffmpeg, atLogin] = await Promise.all([
+        runningRuntime(dataDir),
+        detectClients(paths),
+        findFfmpeg(),
+        autostartState(paths),
+    ]);
+    const chrome = findChrome();
+    const row = (label, value) => console.log(`  ${label.padEnd(9)} ${value}`);
+    console.log(`\n${badge("engenty wizards")} ${dim(packageVersion())}\n`);
+    row("Install", installedByScript()
+        ? tilde(paths.home)
+        : `${tilde(packageRoot)} ${dim(isCheckout() ? "(a checkout)" : "(npm)")}`);
+    row("Data", tilde(dataDir));
+    row("Node", `${process.version} ${dim(tilde(process.execPath))}`);
+    row("Running", running
+        ? `${ok} ${cyan(running.url)} ${dim(`pid ${running.pid}, since ${running.startedAt}`)}`
+        : `${no} not running`);
+    if (!("unavailable" in atLogin)) {
+        row("At login", atLogin.on ? `${ok} starts ${dim(`(${atLogin.how})`)}` : `${no} does not start`);
+    }
+    for (const { client, path, version } of clients) {
+        row(client.name.split(" ")[0], path ? `${ok} ${version} ${dim(tilde(path))}` : `${no} not installed`);
+    }
+    row("Browser", chrome ? `${ok} ${dim(tilde(chrome))}` : `${no} none for PDF and PNG`);
+    row("ffmpeg", ffmpeg.path ? `${ok} ${ffmpeg.version ?? ""}` : `${no} none for MP4`);
+    console.log("");
+    if (!checks) {
+        return 0;
+    }
+    const problems = [];
+    if (!nodeIsCurrent()) {
+        problems.push(`Node ${process.version} is too old: 24.11 or newer is needed.`);
+    }
+    for (const part of ["apps/runtime/dist/index.js", "apps/web/dist/index.html", "plugin"]) {
+        if (!existsSync(join(packageRoot, part))) {
+            problems.push(`${part} is missing from this install (${tilde(packageRoot)}).`);
+        }
+    }
+    try {
+        mkdirSync(paths.home, { recursive: true });
+        accessSync(paths.home, constants.W_OK);
+    }
+    catch {
+        problems.push(`${tilde(paths.home)} cannot be written to.`);
+    }
+    if (!clients.some((state) => state.path)) {
+        console.log(`  ${no} No AI client: the studio needs an API key or Ollama instead. ${dim("`setup` installs one.")}`);
+    }
+    for (const problem of problems) {
+        console.log(`  ${bad} ${problem}`);
+    }
+    if (!problems.length) {
+        console.log(`  ${ok} Nothing wrong with this install.`);
+    }
+    console.log("");
+    return problems.length ? 1 : 0;
+}
+/** Stops the runtime that runs on this install's data folder. */
+export async function stop(paths) {
+    const { dataDir } = settings(paths);
+    const running = await runningRuntime(dataDir);
+    if (!running) {
+        console.log("engenty wizards is not running.");
+        return 0;
+    }
+    process.kill(running.pid, "SIGTERM");
+    for (let waited = 0; waited < 8000; waited += 100) {
+        try {
+            process.kill(running.pid, 0);
+        }
+        catch {
+            console.log(`Stopped (pid ${running.pid}). Your data is kept.`);
+            return 0;
+        }
+        await new Promise((wait) => setTimeout(wait, 100));
+    }
+    console.error(`The runtime (pid ${running.pid}) did not stop within 8 seconds.`);
+    return 1;
+}
+/** `autostart [on|off]`: whether it starts at login, and the switch. */
+export async function autostart(paths, value) {
+    if (value && value !== "on" && value !== "off") {
+        console.error("autostart takes on or off.");
+        return 2;
+    }
+    let state = await autostartState(paths);
+    if (value && !("unavailable" in state)) {
+        try {
+            state = await setAutostart(paths, value === "on");
+        }
+        catch (error) {
+            console.error(`Starting at login could not be switched ${value}: ${error.message}`);
+            return 1;
+        }
+    }
+    if ("unavailable" in state) {
+        console.error(`Starting at login is not possible here: ${state.unavailable}.`);
+        return value ? 1 : 0;
+    }
+    console.log(state.on
+        ? `${ok} engenty wizards starts at login: ${state.how}.`
+        : `${no} engenty wizards does not start at login. ${dim("`autostart on` switches it on.")}`);
+    if (state.on && process.platform === "linux") {
+        console.log(dim("  Before anybody logs in, too: loginctl enable-linger"));
+    }
+    return value && state.on !== (value === "on") ? 1 : 0;
+}

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

@@ -0,0 +1,12 @@
+import { homedir } from "node:os";
+import { styleText } from "node:util";
+const colours = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+/** The name on engenty's orange. */
+export const badge = (text) => colours ? `\x1b[48;2;224;83;27m\x1b[97m\x1b[1m ${text} \x1b[0m` : text;
+export const dim = (text) => styleText("dim", text);
+export const cyan = (text) => styleText("cyan", text);
+export const ok = styleText("green", "✓");
+export const no = styleText("yellow", "–");
+export const bad = styleText("red", "✗");
+/** A path as the person would write it. */
+export const tilde = (path) => path.startsWith(homedir()) ? `~${path.slice(homedir().length)}` : path;

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

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { installedByScript, isCheckout } from "./home.js";
+import { runningRuntime, settings } from "./start.js";
+import { cyan } from "./ui.js";
+/** The installer this install was made with; it also updates one. */
+const INSTALLER = "https://engenty.ai/install.sh";
+async function installer(into) {
+    const source = process.env.ENGENTY_WIZARDS_INSTALLER?.trim() || INSTALLER;
+    if (!/^https?:\/\//.test(source)) {
+        return source;
+    }
+    const response = await fetch(source);
+    const text = response.ok ? await response.text() : "";
+    // The address answers with the studio's page while a server has no installer yet.
+    if (!text.startsWith("#!")) {
+        throw new Error(`${source} did not answer with the installer.`);
+    }
+    const file = join(into, "install.sh");
+    writeFileSync(file, text, { mode: 0o700 });
+    return file;
+}
+/**
+ * Brings an install made by install.sh to the newest version by running the installer again
+ * without its questions: Node, the runtime and the command.
+ */
+export async function update(paths) {
+    if (!installedByScript(paths)) {
+        console.log(isCheckout()
+            ? `This copy is a checkout. The newest version: ${cyan("git pull && pnpm install && pnpm build")}`
+            : `This copy runs from npm. The newest version: ${cyan("npx wizards@latest")}`);
+        return 0;
+    }
+    const tmp = mkdtempSync(join(paths.home, "update-"));
+    try {
+        const script = await installer(tmp);
+        const code = await new Promise((done) => {
+            const child = spawn("bash", [script, "--no-setup"], { stdio: "inherit" });
+            child.on("error", () => done(127));
+            child.on("exit", (exit) => done(exit ?? 1));
+        });
+        if (code !== 0) {
+            return code;
+        }
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    if (await runningRuntime(settings(paths).dataDir)) {
+        console.log(`  The runtime that is running is still the old one. Restart it: ${cyan("wizards stop")}, then ${cyan("wizards")}.`);
+    }
+    return 0;
+}

package/apps/runtime/dist/connectors/builtin.js

@@ -0,0 +1,70 @@
+import { createGuardedFetch } from "../engenty/connections-external/net/guarded-fetch.js";
+import { githubConnector } from "../engenty/connections-github/connector.js";
+import { googleConnectors } from "../engenty/connections-google/definitions.js";
+import { hubspotConnector } from "../engenty/connections-hubspot/connector.js";
+import { microsoftOneDriveConnector } from "../engenty/connections-microsoft/onedrive.js";
+import { microsoftOutlookConnector } from "../engenty/connections-microsoft/outlook.js";
+import { s3Connector } from "../engenty/connections-s3/s3.js";
+import { hasOAuth2ClientCredentials, } from "../engenty/connections-sdk/oauth2.js";
+import { registerConnectorDefinition } from "../engenty/connections-sdk/registry.js";
+import { slackConnector } from "../engenty/connections-slack/connector.js";
+import { gmailConnector as mailGmail } from "./gmail.js";
+import { imapConnector } from "./imap.js";
+import { outlookConnector as mailOutlook } from "./outlook.js";
+/**
+ * engenty's own connectors, as engenty ships them: Gmail, Drive, Calendar, Contacts, Outlook,
+ * OneDrive, Slack, GitHub, HubSpot, S3. Every project has them; an OAuth one can be connected
+ * once its client is configured.
+ */
+export const BUILTIN_CONNECTORS = [
+    ...googleConnectors,
+    microsoftOutlookConnector,
+    microsoftOneDriveConnector,
+    slackConnector,
+    githubConnector,
+    hubspotConnector,
+    s3Connector,
+];
+/** The connectors behind a connection of kind "mail": one read-only shape for any mailbox. */
+export const MAIL_CONNECTORS = [mailGmail, mailOutlook, imapConnector];
+// One registry for all of them, so an imported connector can never take a built-in's id.
+for (const connector of [...BUILTIN_CONNECTORS, ...MAIL_CONNECTORS]) {
+    registerConnectorDefinition(connector);
+}
+export function builtinConnector(id) {
+    return BUILTIN_CONNECTORS.find((c) => c.id === id);
+}
+/**
+ * engenty names OAuth clients `<VENDOR>_OAUTH_CLIENT_ID`. Google and Microsoft allow one client
+ * several redirect addresses, so the client this product signs people in with (`<VENDOR>_CLIENT_ID`)
+ * serves connections too. GitHub and Slack tie a client to one address: they need their own.
+ */
+export const resolveEnv = async (key) => {
+    const own = process.env[key]?.trim();
+    if (own || !/^(GOOGLE|MICROSOFT)_OAUTH_/.test(key)) {
+        return own || undefined;
+    }
+    return process.env[key.replace("_OAUTH_", "_")]?.trim() || undefined;
+};
+/** Whether a person can connect an account with this connector right now. */
+export async function usable(connector) {
+    if (connector.auth.kind !== "oauth2") {
+        return connector.auth.kind === "api_key";
+    }
+    // A connector that registers its own OAuth client needs none configured.
+    return (connector.auth.oauth2.dynamicClientRegistration === true ||
+        hasOAuth2ClientCredentials(connector.auth.oauth2, resolveEnv));
+}
+/** What the server's owner has to set for an OAuth connector that is not usable yet. */
+export function missingSetup(connector) {
+    if (connector.auth.kind !== "oauth2") {
+        return null;
+    }
+    const { clientIdEnv, clientSecretEnv } = connector.auth.oauth2;
+    return clientIdEnv && clientSecretEnv ? `${clientIdEnv}, ${clientSecretEnv}` : null;
+}
+/**
+ * Connector actions reach addresses that come from a person or a spec (an S3 endpoint, an API's
+ * base URL): every request is checked to stay on the public internet.
+ */
+export const connectorFetch = createGuardedFetch();