@engenty/wizards-runtime 0.0.0-stage → 0.7.5

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

@@ -0,0 +1,276 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { join, resolve } from "node:path";
+import { mintLocalTicket } from "../auth/local-ticket.js";
+import { readRunning } from "../running.js";
+import { RESTART_EXIT } from "../update.js";
+import { applyPendingUpdate, autoUpdatePolicy, notesUrl } from "./autoupdate.js";
+import { runtimeEnv } from "./environment.js";
+import { installedByScript, packageRoot, readEnvFile } from "./home.js";
+import { findOnPath } from "./machine.js";
+import { cmd, cyan, dim, live, tilde } from "./ui.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(/\/$/, ""),
+    };
+}
+/**
+ * The secret the runtime this command starts signs with, read the way it reads it (env.ts): its
+ * APP_SECRET, else the one it keeps in the data folder; null before it made one. The runtime
+ * never sees the terminal's APP_SECRET (cli/environment.ts), only its folder's `.env.local` and
+ * `.env`, so the terminal's is left out here too: a ticket signed with it would be refused.
+ */
+export function readSecret(paths, env = process.env) {
+    const { fileEnv, dataDir } = settings(paths, env);
+    const given = readEnvFile(join(paths.home, ".env.local")).APP_SECRET?.trim() || fileEnv.APP_SECRET?.trim();
+    if (given) {
+        return given;
+    }
+    try {
+        return readFileSync(join(dataDir, "secret"), "utf8").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+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 runtime's secret. */
+export function entryUrl(running, paths, env = process.env) {
+    const secret = readSecret(paths, env);
+    // No secret to be read here: the browser gets in if it was let in before.
+    return secret ? `${running.url}/api/local/enter?t=${mintLocalTicket(secret)}` : `${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(`  ${live} engenty wizards is running: ${cyan(url)}`);
+    if (opened) {
+        console.log(dim("    The studio opens in your browser."));
+    }
+    else {
+        console.log(`    Open the studio: ${cyan(entry)}`);
+        console.log(dim("    The link signs in one browser and works only once."));
+    }
+}
+/** The command of this install, as it is on disk now: `wizards <args>`. */
+function spawnCommand(paths, args, options) {
+    const wrapper = join(paths.bin, "wizards");
+    return existsSync(wrapper)
+        ? spawn(wrapper, args, options)
+        : spawn(process.execPath, [join(packageRoot, "bin/wizards.mjs"), ...args], options);
+}
+/**
+ * `wizards start --no-open` detached from this terminal, its output in logs/runtime.log; the
+ * runtime once it answers, or null when it ended or did not answer within a minute.
+ */
+export async function startInBackground(paths) {
+    const { dataDir } = settings(paths);
+    mkdirSync(paths.logs, { recursive: true });
+    const log = openSync(join(paths.logs, "runtime.log"), "a");
+    const child = spawnCommand(paths, ["start", "--no-open"], {
+        cwd: paths.home,
+        detached: true,
+        stdio: ["ignore", log, log],
+    });
+    let exited = false;
+    child.on("error", () => {
+        exited = true;
+    });
+    child.on("exit", () => {
+        exited = true;
+    });
+    child.unref();
+    const began = Date.now();
+    while (!exited && Date.now() - began < START_TIMEOUT_MS) {
+        await new Promise((wait) => setTimeout(wait, 300));
+        const started = await runningRuntime(dataDir);
+        if (started) {
+            return started;
+        }
+    }
+    return null;
+}
+/**
+ * Starts the runtime of this install and opens the studio: in the foreground, or with
+ * `background` detached from this terminal. 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, paths), options.open);
+        console.log(dim(`    It was already running. To stop it: ${cmd("stop")}`));
+        return 0;
+    }
+    // Nothing runs, so no run is cut off: a version downloaded meanwhile becomes current and
+    // takes this process's place (the login item keeps waiting on the same pid). In the
+    // background, the `start` spawned below does it.
+    if (!options.background && installedByScript(paths) && process.execve) {
+        const switched = autoUpdatePolicy(paths, { installed: true }).on && applyPendingUpdate(paths);
+        if (switched) {
+            console.log(`  ${live} Updated to ${switched.to}. What changed: ${notesUrl(switched.to)}`);
+            const wrapper = join(paths.bin, "wizards");
+            try {
+                process.execve(wrapper, [wrapper, "start", ...(options.open ? [] : ["--no-open"])]);
+            }
+            catch {
+                // This version starts once more; the next start is the new one.
+            }
+        }
+    }
+    if (options.background) {
+        const started = await startInBackground(paths);
+        if (!started) {
+            console.error(`engenty wizards didn’t start. Its log is in ${tilde(join(paths.logs, "runtime.log"))}.`);
+            return 1;
+        }
+        show(started.url, entryUrl(started, paths), options.open);
+        console.log(dim(`    It’s running in the background. To stop it: ${cmd("stop")}`));
+        console.log(dim(`    Its log is in ${tilde(join(paths.logs, "runtime.log"))}.`));
+        return 0;
+    }
+    const port = wanted ?? (await freePort());
+    if (!wanted && port !== DEFAULT_PORT) {
+        console.log(dim(`  Port ${DEFAULT_PORT} is taken, so it uses ${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(`engenty wizards didn’t 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("engenty wizards didn’t respond 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(dim("    To stop it, press Ctrl-C."));
+    console.log("");
+    const code = await ended;
+    if (code !== RESTART_EXIT) {
+        return code;
+    }
+    // Updated or `wizards restart`: the command as it is on disk now starts it again, in this
+    // terminal or under the login item, which keeps waiting on this process.
+    console.log(dim("  Restarting…"));
+    current = spawnCommand(paths, ["start", "--no-open"], { stdio: "inherit" });
+    return new Promise((done) => {
+        current.on("error", () => done(1));
+        current.on("exit", (exit) => done(exit ?? 0));
+    });
+}
+/** `wizards studio`: opens the studio in the browser; when nothing runs, it starts as a service first. */
+export async function studio(paths) {
+    const { dataDir } = settings(paths);
+    const running = await runningRuntime(dataDir);
+    if (running) {
+        show(running.url, entryUrl(running, paths), true);
+        return 0;
+    }
+    return start(paths, { open: true, background: true });
+}
+/** `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 isn’t running. To start it: ${cmd("start")}`);
+        return 1;
+    }
+    const entry = entryUrl(running, paths);
+    if (print || !openBrowser(entry)) {
+        console.log(entry);
+    }
+    return 0;
+}

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

@@ -0,0 +1,203 @@
+import { accessSync, constants, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { accountState, describeAccount } from "./account.js";
+import { autostartForStatus, autostartState, setAutostart } from "./autostart.js";
+import { autoUpdatePolicy, updateNotice } from "./autoupdate.js";
+import { installedByScript, isCheckout, packageRoot, packageVersion } from "./home.js";
+import { detectClients, findChrome, findFfmpeg, nodeIsCurrent } from "./machine.js";
+import { findWizardsProcesses, stopProcesses } from "./processes.js";
+import { entryUrl, runningRuntime, settings, startInBackground } from "./start.js";
+import { bad, badge, cmd, 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, account] = await Promise.all([
+        runningRuntime(dataDir),
+        detectClients(paths),
+        findFfmpeg(),
+        autostartForStatus(paths),
+        accountState(),
+    ]);
+    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 ${new Date(running.startedAt).toLocaleString()}`)}`
+        : `${no} not running`);
+    if (!("unavailable" in atLogin)) {
+        row("At login", atLogin.on ? `${ok} starts ${dim(`(${atLogin.how})`)}` : `${no} doesn’t start`);
+    }
+    if (installedByScript(paths)) {
+        const policy = autoUpdatePolicy(paths, { installed: true });
+        row("Updates", policy.on ? `${ok} automatic` : `${no} ${policy.reason} ${dim(`(${cmd("autoupdate on")})`)}`);
+    }
+    row("Account", `${account.kind === "linked" ? ok : no} ${describeAccount(account)}`);
+    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} not found (needed for PDF and PNG)`);
+    row("ffmpeg", ffmpeg.path ? `${ok} ${ffmpeg.version ?? ""}` : `${no} not found (needed for MP4)`);
+    const { updated, pending } = updateNotice(paths, packageVersion());
+    if (updated) {
+        console.log(`\n  ${ok} Updated to ${updated.to}. What changed: ${cyan(updated.notes)}`);
+    }
+    else if (pending) {
+        console.log(`\n  ${ok} Version ${pending.version} is downloaded; it runs from the next start.`);
+    }
+    console.log("");
+    if (!checks) {
+        return 0;
+    }
+    const problems = [];
+    if (!nodeIsCurrent()) {
+        problems.push(`Node ${process.version} is too old. engenty wizards needs 24.11 or newer.`);
+    }
+    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)} can’t be written to.`);
+    }
+    if (!clients.some((state) => state.path)) {
+        console.log(`  ${no} No AI client. The studio needs an API key, Ollama or Apple Intelligence (Mac only) instead. ${dim(`To install one: ${cmd("setup")}`)}`);
+    }
+    for (const problem of problems) {
+        console.log(`  ${bad} ${problem}`);
+    }
+    if (!problems.length) {
+        console.log(`  ${ok} No problems found.`);
+    }
+    console.log("");
+    return problems.length ? 1 : 0;
+}
+/** Waits for a process to end; false when it still runs after `ms`. */
+async function ended(pid, ms) {
+    for (let waited = 0; waited < ms; waited += 100) {
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            return true;
+        }
+        await new Promise((wait) => setTimeout(wait, 100));
+    }
+    return false;
+}
+/**
+ * Stops engenty wizards: the runtime that runs on this install's data folder, and every other
+ * runtime or `start` of this install still about (an older `start --no-open` whose note another
+ * one overwrote). `wizards mcp` processes belong to the AI apps and stay.
+ */
+export async function stop(paths) {
+    const { dataDir } = settings(paths);
+    const running = await runningRuntime(dataDir);
+    const found = findWizardsProcesses(paths.home);
+    const pids = [
+        ...new Set([
+            ...(running ? [running.pid] : []),
+            ...found.filter((p) => p.kind === "runtime" || p.kind === "start").map((p) => p.pid),
+        ]),
+    ];
+    if (!pids.length) {
+        console.log("engenty wizards isn’t running.");
+        return 0;
+    }
+    const left = await stopProcesses(pids);
+    const stopped = pids.length - left.length;
+    if (stopped) {
+        console.log(pids.length === 1
+            ? `Stopped (pid ${pids[0]}). Your data is kept.`
+            : `Stopped ${stopped} processes (pid ${pids.filter((pid) => !left.includes(pid)).join(", ")}). Your data is kept.`);
+    }
+    const apps = found.filter((p) => p.kind === "mcp").length;
+    if (apps && !left.length) {
+        console.log(dim(`${apps === 1 ? "An AI app connection still runs" : `${apps} AI app connections still run`}. Using a wizard there starts engenty wizards again.`));
+    }
+    if (left.length) {
+        console.error(`${left.length === 1 ? "A process" : `${left.length} processes`} of engenty wizards didn’t stop (pid ${left.join(", ")}). To stop ${left.length === 1 ? "it" : "them"}: ${cyan(`kill -9 ${left.join(" ")}`)}`);
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Stops the runtime and starts it again, the version on disk now. One the command started (a
+ * terminal, the login item) is started again by that command, where it ran; any other is
+ * stopped and started in the background. When nothing runs, it is started in the background.
+ */
+export async function restart(paths) {
+    const { dataDir } = settings(paths);
+    const running = await runningRuntime(dataDir);
+    if (running?.restarts && process.platform !== "win32") {
+        process.kill(running.pid, "SIGUSR2");
+        for (let waited = 0; waited < 60_000; waited += 300) {
+            await new Promise((wait) => setTimeout(wait, 300));
+            const again = await runningRuntime(dataDir);
+            if (again && again.pid !== running.pid) {
+                console.log(`${ok} Restarted: ${cyan(again.url)} ${dim(`pid ${again.pid}`)}`);
+                return 0;
+            }
+        }
+        console.error("engenty wizards didn’t restart within a minute.");
+        return 1;
+    }
+    if (running) {
+        process.kill(running.pid, "SIGTERM");
+        if (!(await ended(running.pid, 8000))) {
+            console.error(`engenty wizards (pid ${running.pid}) didn’t stop within 8 seconds.`);
+            return 1;
+        }
+    }
+    const started = await startInBackground(paths);
+    if (!started) {
+        console.error(`engenty wizards didn’t start. Its log is in ${tilde(join(paths.logs, "runtime.log"))}.`);
+        return 1;
+    }
+    console.log(`${ok} ${running ? "Restarted" : "Started"}: ${cyan(started.url)} ${dim(`pid ${started.pid}, in the background`)}`);
+    if (!running) {
+        console.log(`  Open the studio: ${cyan(entryUrl(started, paths))}`);
+    }
+    return 0;
+}
+/** `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(`Use ${cmd("autostart on")} or ${cmd("autostart off")}.`);
+        return 2;
+    }
+    let state;
+    try {
+        state = await autostartState(paths);
+        if (value && !("unavailable" in state)) {
+            state = await setAutostart(paths, value === "on");
+        }
+    }
+    catch (error) {
+        console.error(`Couldn’t ${value ? `turn start at login ${value}` : "check start at login"}: ${error.message}`);
+        return 1;
+    }
+    if ("unavailable" in state) {
+        console.error(`Start at login isn’t available here: ${state.unavailable}.`);
+        return value ? 1 : 0;
+    }
+    console.log(state.on
+        ? `${ok} engenty wizards starts at login: ${state.how}.`
+        : `${no} engenty wizards doesn’t start at login. ${dim(`To turn it on: ${cmd("autostart on")}`)}`);
+    if (state.on && process.platform === "linux") {
+        console.log(dim(`  To start it even before anyone logs in: ${cyan("loginctl enable-linger")}`));
+    }
+    return value && state.on !== (value === "on") ? 1 : 0;
+}

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

@@ -0,0 +1,59 @@
+import { homedir } from "node:os";
+import { emitKeypressEvents } from "node:readline";
+import { styleText } from "node:util";
+import * as p from "@clack/prompts";
+import { command } from "./home.js";
+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 bold = (text) => styleText("bold", text);
+export const cyan = (text) => styleText("cyan", text);
+export const ok = styleText("green", "✓");
+export const no = styleText("yellow", "–");
+export const bad = styleText("red", "✗");
+export const live = styleText("green", "●");
+/** A path as the person would write it. */
+export const tilde = (path) => path.startsWith(homedir()) ? `~${path.slice(homedir().length)}` : path;
+/** A command as the person types it, with this install's prefix: `cmd("stop")` → wizards stop. */
+export const cmd = (args = "") => cyan(args ? `${command()} ${args}` : command());
+/**
+ * A spinner on a terminal; where nobody watches, only what came of it. The message ends in "…"
+ * ("Checking status…"); clack animates its own dots in its place.
+ */
+export function busy(message) {
+    if (!process.stdout.isTTY) {
+        return { stop: (text) => p.log.step(text), fail: (text) => p.log.warn(text) };
+    }
+    exitOnCtrlC();
+    const spinner = p.spinner();
+    spinner.start(message.replace(/…$/, ""));
+    return {
+        stop: (text) => spinner.stop(text),
+        fail: (text) => spinner.error(text),
+    };
+}
+let watching = false;
+/**
+ * Ctrl-C under a spinner: clack ends the process itself, with code 0, as if all went well. The
+ * key is noted before clack sees it (this listener comes first), and the process ends with 130
+ * instead, as a command stopped by Ctrl-C does: `wizards setup && …` goes no further.
+ */
+function exitOnCtrlC() {
+    if (watching || !process.stdin.isTTY) {
+        return;
+    }
+    watching = true;
+    let pressed = false;
+    emitKeypressEvents(process.stdin);
+    process.stdin.on("keypress", (_text, key) => {
+        if (key?.ctrl && key.name === "c") {
+            pressed = true;
+        }
+    });
+    process.on("exit", () => {
+        if (pressed) {
+            process.exitCode = 130;
+        }
+    });
+}

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

@@ -0,0 +1,20 @@
+import { layout } from "./home.js";
+import { nodeIsCurrent } from "./machine.js";
+import { parseUninstall, uninstall } from "./uninstall.js";
+/**
+ * `wizards uninstall` on its own: bin/wizards.mjs starts it instead of main.ts, whose modules make
+ * the install folder, its data folder and a secret when they load (install-env.ts, env.ts,
+ * db/client.ts). An uninstall must find the computer as it is, and leave nothing behind.
+ */
+if (!nodeIsCurrent()) {
+    console.error(`engenty wizards needs Node.js 24.11 or newer. This is ${process.version}.`);
+    process.exit(1);
+}
+const options = parseUninstall(process.argv.slice(2));
+if (typeof options === "string") {
+    console.error(options);
+    process.exitCode = 2;
+}
+else {
+    process.exitCode = await uninstall(layout(), options);
+}