@engenty/wizards-runtime 0.0.0-stage → 0.7.5

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

@@ -0,0 +1,202 @@
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import * as p from "@clack/prompts";
+import { updateStatus } from "../update.js";
+import { accountMenu, accountState, describeAccount } from "./account.js";
+import { autostartForStatus, setAutostart } from "./autostart.js";
+import { connectCommand } from "./connect.js";
+import { command, packageRoot, packageVersion, readInstallNote } from "./home.js";
+import { setup } from "./setup.js";
+import { open, runningRuntime, settings, start } from "./start.js";
+import { restart, status, stop } from "./status.js";
+import { badge, busy, cmd, cyan, dim, no, ok } from "./ui.js";
+import { update } from "./update.js";
+async function look(paths) {
+    const { dataDir } = settings(paths);
+    const [running, atLogin, release, account] = await Promise.all([
+        runningRuntime(dataDir),
+        autostartForStatus(paths),
+        updateStatus().catch(() => null),
+        accountState(),
+    ]);
+    return { running, atLogin, release, account };
+}
+function report({ running, atLogin, release, account }) {
+    const lines = [
+        running
+            ? `${ok} running  ${cyan(running.url)} ${dim(`pid ${running.pid}, since ${new Date(running.startedAt).toLocaleString()}`)}`
+            : `${no} not running`,
+    ];
+    if (!("unavailable" in atLogin)) {
+        lines.push(atLogin.on ? `${ok} starts at login` : `${no} doesn’t start at login`);
+    }
+    lines.push(account.kind === "linked"
+        ? `${ok} signed in as ${describeAccount(account)}`
+        : `${no} ${describeAccount(account)}`);
+    if (release?.newer) {
+        lines.push(`${cyan("↑")} ${release.latest} is out ${dim(`(you have ${release.current})`)}`);
+    }
+    return lines.join("\n");
+}
+function choices({ running, atLogin, release, account }) {
+    const options = running
+        ? [
+            { value: "open", label: "Open the studio", hint: "in your browser" },
+            { value: "restart", label: "Restart" },
+            { value: "stop", label: "Stop", hint: "your data is kept" },
+        ]
+        : [
+            { value: "start", label: "Start in the background", hint: "and open the studio" },
+            { value: "foreground", label: "Start in this terminal", hint: "Ctrl-C stops it" },
+        ];
+    options.push({
+        value: "update",
+        label: "Update",
+        hint: release?.newer ? `${release.latest} is out` : release?.latest ? "up to date" : undefined,
+    });
+    if (!("unavailable" in atLogin)) {
+        options.push({
+            value: "service",
+            label: "Start at login",
+            hint: atLogin.on ? "on" : "off",
+        });
+    }
+    options.push({
+        value: "connect",
+        label: "Connect AI apps",
+        hint: "add your wizards as an MCP server in Claude, Cursor, Codex…",
+    }, {
+        value: "account",
+        label: "Account",
+        hint: account.kind === "linked"
+            ? `signed in as ${describeAccount(account)}`
+            : describeAccount(account),
+    }, { value: "status", label: "Status", hint: "what’s installed, and any problems" }, { value: "setup", label: "Setup", hint: "account, AI client, ffmpeg, start at login" }, {
+        value: "uninstall",
+        label: "Uninstall",
+        hint: "remove it from this computer; asks about your data first",
+    }, { value: "help", label: "Help", hint: "every command" }, { value: "quit", label: "Quit", hint: running ? "engenty wizards keeps running" : undefined });
+    return options;
+}
+/** Whether it starts at login. Esc goes back to the menu. */
+async function serviceSettings(paths, atLogin) {
+    if ("unavailable" in atLogin) {
+        return;
+    }
+    const on = await p.select({
+        message: "Start at login?",
+        initialValue: atLogin.on,
+        options: [
+            {
+                value: true,
+                label: "Yes",
+                hint: "runs in the background whenever you log in to this computer",
+            },
+            { value: false, label: "No", hint: "only when you start it" },
+        ],
+    });
+    if (p.isCancel(on) || on === atLogin.on) {
+        return;
+    }
+    try {
+        await setAutostart(paths, on);
+    }
+    catch (error) {
+        p.log.warn(`Couldn’t change start at login: ${error.message}`);
+    }
+}
+/** The commands used most, for when the menu ends. */
+function commands() {
+    const name = command();
+    return [
+        [`${name} start`, "start engenty wizards and open the studio"],
+        [`${name} studio`, "open the studio, starting engenty wizards if needed"],
+        [`${name} stop`, "stop engenty wizards (your data is kept)"],
+        [`${name} status`, "show what’s installed and running"],
+        [`${name} update`, "install the latest version"],
+        [`${name} --version`, "print the version you have"],
+        [`${name} help`, "list every command"],
+    ]
+        .map(([line, what]) => `${cyan(line.padEnd(name.length + 12))}${dim(what)}`)
+        .join("\n");
+}
+/**
+ * `wizards` on a terminal: what runs, and a menu of what the commands do. The first time, the
+ * setup runs first. Returns the exit code; "Start in this terminal" ends it with the runtime in the
+ * foreground.
+ */
+export async function menu(paths, setupOptions, help) {
+    if (!readInstallNote(paths).setupAt) {
+        if (!(await setup(paths, { ...setupOptions, next: "menu" }))) {
+            return 130;
+        }
+    }
+    p.intro(`${badge("engenty wizards")} ${dim(packageVersion())}`);
+    for (;;) {
+        const spinner = busy("Checking status…");
+        const state = await look(paths);
+        spinner.stop(report(state));
+        const action = await p.select({
+            message: "What would you like to do?",
+            options: choices(state),
+        });
+        if (p.isCancel(action) || action === "quit") {
+            p.outro(dim(`${cmd()} opens this menu again. ${cmd("help")} lists every command.`));
+            return 0;
+        }
+        switch (action) {
+            case "start":
+                await start(paths, { open: true, background: true });
+                break;
+            case "foreground":
+                p.outro("Starting engenty wizards here…");
+                return start(paths, { open: true });
+            case "open":
+                await open(paths, false);
+                break;
+            case "restart":
+                await restart(paths);
+                break;
+            case "stop":
+                await stop(paths);
+                break;
+            case "update": {
+                // What runs restarts into the new version.
+                if ((await update(paths, { restart: true })) !== 0) {
+                    break;
+                }
+                // This menu is still the old version, so it ends here.
+                p.note(commands(), "Updated");
+                p.outro(dim(`${cmd()} opens this menu again, in the new version.`));
+                return 0;
+            }
+            case "service":
+                await serviceSettings(paths, state.atLogin);
+                break;
+            case "connect":
+                await connectCommand(paths, [], false);
+                break;
+            case "account":
+                await accountMenu(paths);
+                break;
+            case "status":
+                await status(paths, true);
+                break;
+            case "setup":
+                await setup(paths, setupOptions);
+                break;
+            case "uninstall": {
+                // Its own process, as `wizards uninstall` is: this one's modules write to the install.
+                const { status: code } = spawnSync(process.execPath, [join(packageRoot, "bin", "wizards.mjs"), "uninstall"], { stdio: "inherit" });
+                // 130: the person said no, so the menu goes on.
+                if (code !== 130) {
+                    return code ?? 1;
+                }
+                break;
+            }
+            case "help":
+                console.log(help);
+                break;
+        }
+    }
+}

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

@@ -0,0 +1,72 @@
+import { execFileSync } from "node:child_process";
+import { sep } from "node:path";
+/** Every process, as `ps` lists it; empty where there is no `ps` (Windows). */
+function listProcesses() {
+    try {
+        return execFileSync("ps", ["-axww", "-o", "pid=,ppid=,command="], { encoding: "utf8" })
+            .split("\n")
+            .map((line) => line.match(/^\s*(\d+)\s+(\d+)\s+(.*)$/))
+            .filter((match) => match !== null)
+            .map((match) => ({ pid: Number(match[1]), ppid: Number(match[2]), command: match[3] }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The processes in `list` that run from `home`, apart from `self` and the processes that started
+ * it (npx, a shell).
+ */
+export function wizardsProcesses(home, list, self = process.pid) {
+    const parents = new Map(list.map((entry) => [entry.pid, entry.ppid]));
+    const skip = new Set();
+    for (let at = self; at && !skip.has(at); at = parents.get(at)) {
+        skip.add(at);
+    }
+    return list
+        .filter((entry) => !skip.has(entry.pid) && entry.command.includes(home + sep))
+        .map(({ pid, command }) => {
+        const args = command.split(/\s+/);
+        const kind = /apps[\\/]runtime[\\/]dist[\\/]index\.js/.test(command)
+            ? "runtime"
+            : args.includes("mcp")
+                ? "mcp"
+                : args.includes("start")
+                    ? "start"
+                    : "other";
+        return { pid, kind };
+    });
+}
+export const findWizardsProcesses = (home) => wizardsProcesses(home, listProcesses());
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+/** SIGTERM, then SIGKILL after 8 seconds; the processes still there after that. */
+export async function stopProcesses(pids) {
+    const signal = (name) => {
+        for (const pid of pids.filter(alive)) {
+            try {
+                process.kill(pid, name);
+            }
+            catch {
+                // gone meanwhile, or not ours: the check below tells
+            }
+        }
+    };
+    const wait = async (ms) => {
+        for (let waited = 0; waited < ms && pids.some(alive); waited += 100) {
+            await new Promise((done) => setTimeout(done, 100));
+        }
+    };
+    signal("SIGTERM");
+    await wait(8000);
+    signal("SIGKILL");
+    await wait(2000);
+    return pids.filter(alive);
+}

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

@@ -0,0 +1,66 @@
+import { join } from "node:path";
+import { LOCAL_MCP_HEADER, mintLocalTicket } from "../auth/local-ticket.js";
+import { readSecret, runningRuntime, settings } from "./start.js";
+import { bad, cmd, dim, ok, tilde } from "./ui.js";
+/**
+ * `wizards logs` shows the last lines the running runtime printed; `wizards report` sends its
+ * status, model settings and those lines to the linked account, where an operator reads them
+ * (docs/plans/remote-debug.md). Both talk to the running process, signed with the data folder's
+ * secret as `wizards mcp` does; neither sends anything by itself.
+ */
+async function ask(paths, method, path) {
+    const { dataDir } = settings(paths);
+    const running = await runningRuntime(dataDir);
+    if (!running) {
+        return `engenty wizards isn’t running. To start it: ${cmd("start")}`;
+    }
+    const secret = readSecret(paths);
+    if (!secret) {
+        return `Couldn’t read the data folder’s secret (${tilde(join(dataDir, "secret"))}).`;
+    }
+    const res = await fetch(`http://127.0.0.1:${running.port}/api/local/debug${path}`, {
+        method,
+        headers: { [LOCAL_MCP_HEADER]: mintLocalTicket(secret, Date.now(), "local-debug") },
+        signal: AbortSignal.timeout(30_000),
+    });
+    return {
+        status: res.status,
+        body: (await res.json().catch(() => ({}))),
+    };
+}
+/** The last lines of the running runtime; `value` may name how many (default 100). */
+export async function logsCommand(paths, value) {
+    const limit = Math.min(Math.max(1, Number(value) || 100), 2000);
+    const answer = await ask(paths, "GET", `/logs?limit=${limit}`);
+    if (typeof answer === "string") {
+        console.error(answer);
+        return 1;
+    }
+    const lines = answer.body.lines ?? [];
+    for (const line of lines) {
+        const at = new Date(line.at).toISOString().slice(11, 19);
+        const level = line.level === "info" ? "     " : line.level.padEnd(5);
+        console.log(`${dim(at)} ${level} ${line.text}`);
+    }
+    if (!lines.length) {
+        console.log(dim("No log lines yet."));
+    }
+    return 0;
+}
+export async function reportCommand(paths) {
+    const answer = await ask(paths, "POST", "/report");
+    if (typeof answer === "string") {
+        console.error(answer);
+        return 1;
+    }
+    if (answer.status === 409) {
+        console.error(`${bad} This computer isn’t connected to an account. Sign in under Settings → Account in the studio, or with ${cmd("account sign-in")}. Then try again.`);
+        return 1;
+    }
+    if (answer.status !== 200) {
+        console.error(`${bad} ${answer.body.error ?? `engenty wizards responded with an error (${answer.status}).`}`);
+        return 1;
+    }
+    console.log(`${ok} Sent report ${answer.body.id} to ${answer.body.to}. Quote this ID when you ask for help.`);
+    return 0;
+}

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

@@ -0,0 +1,335 @@
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import * as p from "@clack/prompts";
+import { accountStep } from "./account.js";
+import { autostartForStatus, setAutostart } from "./autostart.js";
+import { installClient, installCommand } from "./clients.js";
+import { appStates, connectApps } from "./connect.js";
+import { runLogged } from "./exec.js";
+import { command, installedByScript, isCheckout, packageVersion, readInstallNote, writeInstallNote, } from "./home.js";
+import { CLIENTS, detectClients, findChrome, findFfmpeg, findOnPath, suggestedClient, vendorApp, } from "./machine.js";
+import { runningRuntime, settings } from "./start.js";
+import { badge, busy, cmd, cyan, dim, tilde } from "./ui.js";
+/** The studio as an app of its own: Chrome (or Edge) installs it from the page. */
+const CHROME_APP = "Tip: in Chrome or Edge you can install the studio as an app, with its own window and icon. Use the offer at the top of the studio, or the install icon in the address bar.";
+function cancelled(value) {
+    if (p.isCancel(value)) {
+        p.cancel(`Setup stopped. To run it again: ${cmd("setup")}`);
+        return true;
+    }
+    return false;
+}
+async function install(client, paths) {
+    const task = p.taskLog({ title: `Installing ${client.name}`, limit: 6 });
+    task.message(dim(installCommand(client, paths)));
+    const { code, tail } = await installClient(client, paths, (line) => task.message(line));
+    const installed = (await detectClients(paths)).find((state) => state.client.id === client.id);
+    if (code === 0 && installed?.path) {
+        task.success(`${client.name} ${installed.version ?? ""} installed`.trim());
+        return true;
+    }
+    task.error(`${client.name} didn’t install${code === 0 ? ": its command isn’t on the PATH" : ""}. ${tail.split("\n").pop() ?? ""}`);
+    return false;
+}
+async function clientsStep(paths, options, interactive) {
+    const spinner = busy("Looking for AI clients on this computer…");
+    const found = await detectClients(paths);
+    const installed = found.filter((state) => state.path);
+    const missing = found.filter((state) => !state.path);
+    spinner.stop(installed.length
+        ? `Found AI clients: ${installed.map((s) => `${s.client.name} ${s.version}`).join(", ")}.`
+        : "No AI client on this computer yet.");
+    if (!installed.length) {
+        p.log.message(dim("engenty wizards runs its AI through an AI client, like Claude Code or Codex, on a subscription you already have."));
+    }
+    let wanted = missing.filter((s) => options.clients.includes(s.client.id));
+    // With a client already here, setup asks nothing more; another one is a `--client` away.
+    if (interactive && !installed.length && missing.length && !wanted.length) {
+        const suggested = suggestedClient(missing);
+        // A client whose app is on this Mac comes first: its subscription is most likely paid for.
+        const offered = [...missing].sort((a, b) => Number(!vendorApp(a.client)) - Number(!vendorApp(b.client)));
+        const answer = await p.multiselect({
+            message: "Which AI client should be installed? (space to choose, enter to continue)",
+            options: offered.map(({ client }) => {
+                const app = vendorApp(client);
+                return {
+                    value: client.id,
+                    label: client.name,
+                    hint: [
+                        `${client.account} subscription`,
+                        app ? `the ${app} app is on this Mac` : "",
+                        client.id === suggested?.client.id ? "recommended" : "",
+                    ]
+                        .filter(Boolean)
+                        .join(", "),
+                };
+            }),
+            initialValues: suggested ? [suggested.client.id] : [],
+            required: false,
+        });
+        if (cancelled(answer)) {
+            return "cancelled";
+        }
+        wanted = missing.filter((s) => answer.includes(s.client.id));
+    }
+    let any = installed.length > 0;
+    for (const { client } of wanted) {
+        any = (await install(client, paths)) || any;
+    }
+    if (any) {
+        p.log.info("Sign in to the AI client on the first page of the studio.");
+    }
+    else {
+        p.log.warn(`No AI client yet. The first page of the studio can install one, or you can use an API key (Vercel AI Gateway, OpenAI, Anthropic) or a local model (Ollama).\n${dim(`To install ${CLIENTS.map((c) => c.name).join(", ")} here later: ${cmd("setup")}`)}`);
+    }
+    return any;
+}
+async function toolsStep(interactive) {
+    const chrome = findChrome();
+    if (chrome) {
+        p.log.success(`Browser for PDF and PNG exports: ${dim(tilde(chrome))}`);
+    }
+    else {
+        p.log.warn("No Chrome, Edge or Chromium found. PDF and PNG exports and browser steps need one.\nhttps://www.google.com/chrome");
+    }
+    const ffmpeg = await findFfmpeg();
+    if (ffmpeg.path) {
+        p.log.success(`ffmpeg ${ffmpeg.version ?? ""} for videos`.replace("  ", " "));
+        return;
+    }
+    const brew = findOnPath("brew", process.env.PATH ?? "");
+    if (!interactive || !brew) {
+        p.log.warn(`No ffmpeg found. MP4 videos of animated widgets need it.${brew ? `\n${dim(`To install it: ${cyan("brew install ffmpeg")}`)}` : ""}`);
+        return;
+    }
+    const answer = await p.confirm({
+        message: "No ffmpeg (for MP4 videos of animated widgets). Install it with Homebrew?",
+        initialValue: false,
+    });
+    if (cancelled(answer)) {
+        return "cancelled";
+    }
+    if (answer) {
+        const task = p.taskLog({ title: "Installing ffmpeg", limit: 6 });
+        const { code, tail } = await runLogged(brew, ["install", "ffmpeg"], {
+            onLine: (line) => task.message(line),
+        });
+        if (code === 0) {
+            task.success("ffmpeg installed");
+        }
+        else {
+            task.error(`ffmpeg didn’t install. ${tail.split("\n").pop() ?? ""}`);
+        }
+    }
+}
+/**
+ * Starting at login: on a Mac a LaunchAgent starts the runtime, on Linux a systemd user
+ * service does. Asked, never assumed; `autostart off` undoes it.
+ */
+async function autostartStep(paths, interactive) {
+    const state = await autostartForStatus(paths);
+    if ("unavailable" in state) {
+        return;
+    }
+    if (state.on) {
+        p.log.success(`Starts when you log in to this computer: ${dim(state.how)}`);
+        return;
+    }
+    if (!interactive) {
+        p.log.info(dim(`To start it when you log in to this computer: ${cmd("autostart on")}`));
+        return;
+    }
+    const answer = await p.confirm({
+        message: "Start engenty wizards when you log in to this computer? It runs as a background process, without a terminal window, so links and your AI apps can always reach it.",
+        initialValue: true,
+    });
+    if (cancelled(answer)) {
+        return "cancelled";
+    }
+    if (!answer) {
+        p.log.info(dim(`To do it later: ${cmd("autostart on")}`));
+        return;
+    }
+    try {
+        const after = await setAutostart(paths, true);
+        if ("on" in after && after.on) {
+            p.log.success(`Starts when you log in to this computer: ${dim(after.how)}`);
+        }
+        else {
+            p.log.warn("Couldn’t set it to start when you log in.");
+        }
+    }
+    catch (error) {
+        p.log.warn(`Couldn’t set it to start when you log in. ${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(`Already 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(", ")}: ${cmd("connect")}`));
+        return;
+    }
+    const answer = await p.multiselect({
+        message: "Add your wizards to these AI apps, as an MCP server in each app’s settings? (space to choose, enter to continue)",
+        options: offered.map((s) => ({ value: s.id, label: s.name })),
+        initialValues: offered.map((s) => s.id),
+        required: false,
+    });
+    if (cancelled(answer)) {
+        return "cancelled";
+    }
+    if (!answer.length) {
+        p.log.info(dim(`To do it later: ${cmd("connect")}`));
+        return;
+    }
+    for (const { app, outcome } of await connectApps(paths, answer)) {
+        if (outcome.ok) {
+            p.log.success(`${app.name}: ${dim(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 ?? "";
+    if (shell.endsWith("fish")) {
+        return {
+            file: join(homedir(), ".config/fish/config.fish"),
+            line: "fish_add_path ~/.local/bin",
+        };
+    }
+    const file = shell.endsWith("zsh")
+        ? ".zshrc"
+        : process.platform === "darwin"
+            ? ".bash_profile"
+            : ".bashrc";
+    return { file: join(homedir(), file), line: 'export PATH="$HOME/.local/bin:$PATH"' };
+}
+/** An install made by install.sh has its command in `~/.local/bin`: is that on the PATH? */
+async function pathStep(interactive) {
+    const local = join(homedir(), ".local", "bin");
+    if (!installedByScript() || (process.env.PATH ?? "").split(delimiter).includes(local)) {
+        return;
+    }
+    const { file, line } = pathLine();
+    if (existsSync(file) && readFileSync(file, "utf8").includes(".local/bin")) {
+        p.log.info(`Open a new terminal to use the ${cyan("wizards")} command.`);
+        return;
+    }
+    const hint = `Until then, use ${cyan(tilde(join(local, "wizards")))}`;
+    if (!interactive) {
+        p.log.warn(`~/.local/bin isn’t on your PATH. Add this to ${tilde(file)}:\n${line}\n${dim(hint)}`);
+        return;
+    }
+    const answer = await p.confirm({
+        message: `The wizards command is in ~/.local/bin, which isn’t on your PATH. Add it in ${tilde(file)}?`,
+        initialValue: true,
+    });
+    if (cancelled(answer)) {
+        return "cancelled";
+    }
+    if (answer) {
+        appendFileSync(file, `\n# engenty wizards\n${line}\n`);
+        p.log.success(`Added to ${tilde(file)}. Open a new terminal to use it.\n${dim(hint)}`);
+    }
+    else {
+        p.log.info(hint);
+    }
+}
+/** What runs now, and the commands to start, stop and check it from now on. */
+async function howToUse(paths) {
+    const [running, atLogin] = await Promise.all([
+        runningRuntime(settings(paths).dataDir),
+        autostartForStatus(paths),
+    ]);
+    const wizards = command();
+    const row = (what, cmd, note = "") => `${what.padEnd(9)}${cyan(cmd.padEnd(wizards.length + 12))}${note ? dim(note) : ""}`;
+    p.log.message([
+        running
+            ? `engenty wizards is running: ${cyan(running.url)}`
+            : "engenty wizards isn’t running yet.",
+        "unavailable" in atLogin || !atLogin.on
+            ? ""
+            : dim("It starts automatically when you log in to this computer."),
+    ]
+        .filter(Boolean)
+        .join("\n"));
+    p.outro([
+        "From now on, in a terminal:",
+        "",
+        row("Start", `${wizards} start`, "runs in this terminal; Ctrl-C stops it"),
+        row("", `${wizards} start -s`, "runs in the background; the terminal stays free"),
+        row("Studio", `${wizards} studio`, "opens the studio, starting it first if needed"),
+        row("Stop", `${wizards} stop`, "your data is kept"),
+        row("Check", `${wizards} status`, "shows what’s running and where"),
+        row("Restart", `${wizards} restart`),
+        row("Menu", wizards, "everything in one menu"),
+        "",
+        dim("It’s installed, so there’s no need to run the installer again. To update: ") +
+            cmd("update"),
+    ].join("\n"));
+}
+/**
+ * The guided setup: the account this computer joins, then what this machine has, what is
+ * missing, and what to install — an AI client to think with, ffmpeg, starting at login. It
+ * starts nothing; it ends with what runs and how to start, stop and check it. Returns false
+ * when it was stopped.
+ */
+export async function setup(paths, options) {
+    const interactive = !options.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const version = packageVersion();
+    p.intro(`${badge("engenty wizards")} ${dim(version)}`);
+    p.log.message([
+        `Install  ${tilde(paths.home)}${installedByScript() ? "" : dim(`  (data; the code runs from ${isCheckout() ? "this checkout" : "npm"})`)}`,
+        `Node     ${process.version}  ${dim(tilde(process.execPath))}`,
+    ].join("\n"));
+    if ((await accountStep(paths, options, interactive)) === "cancelled") {
+        return false;
+    }
+    if ((await clientsStep(paths, options, interactive)) === "cancelled") {
+        return false;
+    }
+    if ((await toolsStep(interactive)) === "cancelled") {
+        return false;
+    }
+    if ((await autostartStep(paths, interactive)) === "cancelled") {
+        return false;
+    }
+    if ((await appsStep(paths, interactive)) === "cancelled") {
+        return false;
+    }
+    if ((await pathStep(interactive)) === "cancelled") {
+        return false;
+    }
+    writeInstallNote({
+        ...readInstallNote(paths),
+        setupAt: new Date().toISOString(),
+        version,
+        unattended: !process.stdout.isTTY,
+    }, paths);
+    p.log.info(CHROME_APP);
+    if (options.next) {
+        p.outro(options.next === "start"
+            ? "Setup is done. Starting engenty wizards…"
+            : `Setup is done. ${dim(`${cmd("help")} lists every command.`)}`);
+        return true;
+    }
+    await howToUse(paths);
+    return true;
+}