wizards 0.6.1 → 0.7.0

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/setup.js

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import * as p from "@clack/prompts";
 import { accountStep } from "./account.js";
-import { autostartState, setAutostart } from "./autostart.js";
+import { autostartForStatus, setAutostart } from "./autostart.js";
 import { installClient, installCommand } from "./clients.js";
 import { appStates, connectApps } from "./connect.js";
 import { runLogged } from "./exec.js";
@@ -129,7 +129,7 @@ async function toolsStep(interactive) {
  * service does. Asked, never assumed; `autostart off` undoes it.
  */
 async function autostartStep(paths, interactive) {
-    const state = await autostartState(paths);
+    const state = await autostartForStatus(paths);
     if ("unavailable" in state) {
         return;
     }
@@ -261,7 +261,7 @@ async function pathStep(interactive) {
 async function howToUse(paths) {
     const [running, atLogin] = await Promise.all([
         runningRuntime(settings(paths).dataDir),
-        autostartState(paths),
+        autostartForStatus(paths),
     ]);
     const wizards = command();
     const row = (what, cmd, note = "") => `${what.padEnd(9)}${cyan(cmd.padEnd(wizards.length + 12))}${note ? dim(note) : ""}`;
@@ -322,7 +322,12 @@ export async function setup(paths, options) {
     if ((await pathStep(interactive)) === "cancelled") {
         return false;
     }
-    writeInstallNote({ ...readInstallNote(paths), setupAt: new Date().toISOString(), version }, paths);
+    writeInstallNote({
+        ...readInstallNote(paths),
+        setupAt: new Date().toISOString(),
+        version,
+        unattended: !process.stdout.isTTY,
+    }, paths);
     p.log.info(CHROME_APP);
     await howToUse(paths);
     return true;

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

@@ -6,8 +6,9 @@ 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 { packageRoot, readEnvFile } from "./home.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;
@@ -163,6 +164,22 @@ export async function start(paths, options) {
         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) {

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

@@ -1,9 +1,11 @@
 import { accessSync, constants, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { accountState, describeAccount } from "./account.js";
-import { autostartState, setAutostart } from "./autostart.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";
 /**
@@ -16,7 +18,7 @@ export async function status(paths, checks) {
         runningRuntime(dataDir),
         detectClients(paths),
         findFfmpeg(),
-        autostartState(paths),
+        autostartForStatus(paths),
         accountState(),
     ]);
     const chrome = findChrome();
@@ -33,12 +35,23 @@ export async function status(paths, checks) {
     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;
@@ -84,21 +97,41 @@ async function ended(pid, ms) {
     }
     return false;
 }
-/** Stops the runtime that runs on this install's data folder. */
+/**
+ * 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);
-    if (!running) {
+    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;
     }
-    process.kill(running.pid, "SIGTERM");
-    if (await ended(running.pid, 8000)) {
-        console.log(`Stopped (pid ${running.pid}). Your data is kept.`);
-        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.`);
     }
-    console.error(`engenty wizards (pid ${running.pid}) didn’t stop within 8 seconds.`);
-    return 1;
+    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
@@ -145,15 +178,16 @@ export async function autostart(paths, value) {
         console.error(`Use ${cmd("autostart on")} or ${cmd("autostart off")}.`);
         return 2;
     }
-    let state = await autostartState(paths);
-    if (value && !("unavailable" in state)) {
-        try {
+    let state;
+    try {
+        state = await autostartState(paths);
+        if (value && !("unavailable" in state)) {
             state = await setAutostart(paths, value === "on");
         }
-        catch (error) {
-            console.error(`Couldn’t turn start at login ${value}: ${error.message}`);
-            return 1;
-        }
+    }
+    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}.`);

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);
+}

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

@@ -0,0 +1,231 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readlinkSync, rmdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import * as p from "@clack/prompts";
+import { LOGIN_LABEL, present, removeUnit, UNIT, unloadLoginItem } from "./autostart.js";
+import { apps as allApps } from "./connect.js";
+import { findWizardsProcesses, stopProcesses } from "./processes.js";
+import { settings } from "./start.js";
+import { bad, cyan, dim, no, ok } from "./ui.js";
+export const realSystem = () => ({
+    userHome: homedir(),
+    platform: process.platform,
+    env: process.env,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    apps: allApps,
+    processes: findWizardsProcesses,
+    stop: (pids) => stopProcesses(pids),
+    unloadLoginItem,
+    removeUnit,
+});
+/** Parts of the install folder that are the person's: kept or deleted with the data. */
+const WITH_DATA = [".env", ".env.local", "plugins"];
+function loginItemPath(system) {
+    if (system.platform === "darwin") {
+        return join(system.userHome, "Library", "LaunchAgents", `${LOGIN_LABEL}.plist`);
+    }
+    if (system.platform === "linux") {
+        const config = system.env.XDG_CONFIG_HOME || join(system.userHome, ".config");
+        return join(config, "systemd", "user", UNIT);
+    }
+    return null;
+}
+/** The links install.sh put into ~/.local/bin that point into the install. */
+function ourLinks(home, system) {
+    return ["wizards", "engenty-wizards"]
+        .map((name) => join(system.userHome, ".local", "bin", name))
+        .filter((link) => {
+        try {
+            return (lstatSync(link).isSymbolicLink() &&
+                resolve(dirname(link), readlinkSync(link)).startsWith(home + sep));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Works out what an uninstall takes away, without changing anything. */
+export async function makePlan(paths, system) {
+    const apps = [];
+    for (const app of system.apps(paths)) {
+        if (await app.connected().catch(() => false)) {
+            apps.push(app);
+        }
+    }
+    const item = loginItemPath(system);
+    let loginItem = null;
+    try {
+        loginItem = item && present(item) ? item : null;
+    }
+    catch {
+        // Can't look: count it as there, so the uninstall tries and says so.
+        loginItem = item;
+    }
+    const { dataDir } = settings(paths, system.env);
+    const program = [];
+    const data = existsSync(dataDir) ? [dataDir] : [];
+    for (const name of existsSync(paths.home) ? readdirSync(paths.home) : []) {
+        const path = join(paths.home, name);
+        if (path === dataDir) {
+            continue;
+        }
+        const empty = name === "plugins" && readdirSync(path).length === 0;
+        (WITH_DATA.includes(name) && !empty ? data : program).push(path);
+    }
+    return {
+        home: paths.home,
+        apps,
+        loginItem,
+        processes: system.processes(paths.home),
+        program,
+        links: ourLinks(paths.home, system),
+        data,
+    };
+}
+/** Size of a folder as `du` counts it, e.g. " (805 MB)"; "" where it can't tell. */
+function size(path) {
+    const kb = Number(spawnSync("du", ["-sk", path], { encoding: "utf8" }).stdout?.split(/\s/)[0]);
+    return kb > 0 ? ` (${kb < 1024 ? `${kb} KB` : `${Math.round(kb / 1024)} MB`})` : "";
+}
+const processes = (n) => `${n} running process${n === 1 ? "" : "es"}`;
+/** `wizards uninstall [--dry-run] [--yes] [--delete-data]`. */
+export async function uninstall(paths, options, system = realSystem()) {
+    const t = (path) => path.startsWith(system.userHome + sep) ? `~${path.slice(system.userHome.length)}` : path;
+    if (!options.dryRun && !options.yes && !system.interactive) {
+        console.error("The uninstall asks before it deletes anything, and there is no terminal to ask in.\n" +
+            "Run it with --yes (your data is kept), --yes --delete-data, or --dry-run to only look.");
+        return 2;
+    }
+    const plan = await makePlan(paths, system);
+    const steps = [
+        ...plan.apps.map((app) => `Disconnect ${app.name}`),
+        ...(plan.loginItem ? [`Remove the login item ${t(plan.loginItem)}`] : []),
+        ...(plan.processes.length ? [`Stop ${processes(plan.processes.length)}`] : []),
+        ...(plan.program.length ? [`Delete the program in ${t(plan.home)}${size(plan.home)}`] : []),
+        ...plan.links.map((link) => `Delete the command ${t(link)}`),
+    ];
+    if (!steps.length && !plan.data.length) {
+        console.log(`${ok} engenty wizards isn’t installed here.`);
+        return 0;
+    }
+    if (steps.length) {
+        console.log("\nThis removes engenty wizards:");
+    }
+    for (const step of steps) {
+        console.log(`  ${no} ${step}`);
+    }
+    if (plan.data.length) {
+        console.log(`\nYour data: ${plan.data.map((path) => t(path) + size(path)).join(", ")}`);
+        console.log(dim("  Kept unless you choose to delete it. A reinstall picks it up again."));
+    }
+    console.log("");
+    if (options.dryRun) {
+        console.log(dim("Nothing was changed (--dry-run)."));
+        return 0;
+    }
+    let deleteData = options.yes && options.deleteData;
+    if (!options.yes) {
+        if (plan.data.length) {
+            const answer = await p.confirm({
+                message: "Delete your data too? Your wizards, runs and results are gone for good.",
+                initialValue: false,
+            });
+            if (p.isCancel(answer)) {
+                return 130;
+            }
+            deleteData = answer;
+        }
+        const go = await p.confirm({
+            message: deleteData ? "Uninstall and delete your data now?" : "Uninstall now?",
+        });
+        if (p.isCancel(go) || !go) {
+            p.cancel("Nothing was changed.");
+            return 130;
+        }
+    }
+    const failed = (what, error) => console.log(`${bad} ${what}: ${error.message.split("\n")[0]}`);
+    for (const app of plan.apps) {
+        const result = await app
+            .disconnect()
+            .catch((error) => ({ ok: false, message: error.message }));
+        console.log(result.ok ? `${ok} Disconnected ${app.name}` : `${bad} ${app.name}: ${result.message}`);
+    }
+    if (plan.loginItem) {
+        try {
+            if (system.platform === "darwin") {
+                await system.unloadLoginItem();
+                rmSync(plan.loginItem, { force: true });
+            }
+            else {
+                await system.removeUnit(plan.loginItem);
+            }
+            console.log(`${ok} Removed the login item`);
+        }
+        catch (error) {
+            failed("The login item", error);
+        }
+    }
+    // Twice: an AI app's `wizards mcp` may start the studio again meanwhile.
+    for (let round = 0; round < 2; round++) {
+        const running = system.processes(paths.home);
+        if (running.length && !(await system.stop(running.map((proc) => proc.pid))).length) {
+            console.log(`${ok} Stopped ${processes(running.length)}`);
+        }
+    }
+    for (const path of [...plan.program, ...plan.links, ...(deleteData ? plan.data : [])]) {
+        try {
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch (error) {
+            failed(`Couldn’t delete ${t(path)}`, error);
+        }
+    }
+    for (const dir of [plan.home, join(system.userHome, ".engenty")]) {
+        try {
+            rmdirSync(dir);
+        }
+        catch {
+            // not empty, or not there
+        }
+    }
+    // A second look: what is still there.
+    const after = await makePlan(paths, system);
+    const left = [
+        ...after.apps.map((app) => `${app.name} still lists the wizards: ${cyan(`npx wizards disconnect ${app.id}`)}`),
+        ...(after.loginItem ? [t(after.loginItem)] : []),
+        ...after.processes.map((proc) => `process ${proc.pid}: ${cyan(`kill -9 ${proc.pid}`)}`),
+        ...[...after.program, ...after.links, ...(deleteData ? after.data : [])].map(t),
+    ];
+    if (!deleteData && after.data.length) {
+        console.log(`${ok} Kept your data: ${after.data.map(t).join(", ")}`);
+    }
+    if (left.length) {
+        console.log(`\n${bad} Still there:`);
+        for (const line of left) {
+            console.log(`  ${line}`);
+        }
+        return 1;
+    }
+    console.log(`\n${ok} engenty wizards is uninstalled.\n`);
+    return 0;
+}
+/** The options of `uninstall` from its command line; a message when something is off. */
+export function parseUninstall(argv) {
+    const options = { dryRun: false, yes: false, deleteData: false };
+    for (const arg of argv) {
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+        }
+        else if (arg === "--yes" || arg === "-y") {
+            options.yes = true;
+        }
+        else if (arg === "--delete-data") {
+            options.deleteData = true;
+        }
+        else if (arg !== "uninstall") {
+            return `Unknown option ${arg}. The uninstall takes --dry-run, --yes and --delete-data.`;
+        }
+    }
+    return options;
+}

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

@@ -1,10 +1,12 @@
 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 { autoUpdatePolicy, noteUpdated } from "./autoupdate.js";
+import { installedByScript, isCheckout, readInstallNote, writeInstallNote, } from "./home.js";
 import { runningRuntime, settings } from "./start.js";
 import { restart } from "./status.js";
-import { cmd, cyan } from "./ui.js";
+import { cmd, cyan, no, ok } from "./ui.js";
+import { currentVersion } from "./versions.js";
 /** The installer this install was made with; it also updates one. */
 const INSTALLER = "https://engenty.ai/install.sh";
 async function installer(into) {
@@ -34,6 +36,7 @@ export async function update(paths, options = {}) {
             : `This copy runs from npm. To update: ${cyan("npx wizards@latest")}`);
         return 0;
     }
+    const before = currentVersion(paths);
     const tmp = mkdtempSync(join(paths.home, "update-"));
     try {
         const script = await installer(tmp);
@@ -53,6 +56,10 @@ export async function update(paths, options = {}) {
     finally {
         rmSync(tmp, { recursive: true, force: true });
     }
+    const after = currentVersion(paths);
+    if (before && after) {
+        noteUpdated(paths, before, after);
+    }
     if (await runningRuntime(settings(paths).dataDir)) {
         if (options.restart) {
             return restart(paths);
@@ -61,3 +68,19 @@ export async function update(paths, options = {}) {
     }
     return 0;
 }
+/** `wizards autoupdate [on|off]`: whether updates come by themselves (autoupdate.ts). */
+export function autoUpdateCommand(paths, value) {
+    if (value && value !== "on" && value !== "off") {
+        console.error(`Use ${cmd("autoupdate on")} or ${cmd("autoupdate off")}.`);
+        return 2;
+    }
+    const installed = installedByScript(paths);
+    if (value && installed) {
+        writeInstallNote({ ...readInstallNote(paths), autoUpdate: value === "on" }, paths);
+    }
+    const policy = autoUpdatePolicy(paths, { installed });
+    console.log(policy.on
+        ? `${ok} Updates come by themselves: downloaded in the background, used from the next start.`
+        : `${no} Updates don’t come by themselves: ${policy.reason}. To update now: ${cmd("update")}`);
+    return value && !installed ? 1 : 0;
+}

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

@@ -0,0 +1,106 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, } from "node:fs";
+import { join } from "node:path";
+/**
+ * The runtimes of an install made by install.sh, one folder per version, side by side:
+ *
+ *   runtime/<version>/     an npm prefix: node_modules/wizards, package.json, package-lock.json
+ *   runtime/current        → <version>, the one `bin/wizards` starts
+ *   runtime/node_modules   → current/node_modules, for commands written before the versions
+ *
+ * Up to 0.6.2 `runtime/` itself was the prefix; `switchTo` moves such an install into its
+ * version folder first. A process keeps the files of the version it started with.
+ */
+const VERSION = /^\d+\.\d+\.\d+$/;
+export const runtimeDir = (paths, version) => join(paths.runtime, version);
+const currentLink = (paths) => join(paths.runtime, "current");
+const modules = (paths) => join(paths.runtime, "node_modules");
+/** The version of the package `wizards` in an npm prefix; null when there is none. */
+export function versionIn(prefix) {
+    try {
+        const file = join(prefix, "node_modules", "wizards", "package.json");
+        const { version } = JSON.parse(readFileSync(file, "utf8"));
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+const isLink = (path) => {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
+/** The version `bin/wizards` starts; null without a runtime. */
+export function currentVersion(paths) {
+    if (isLink(currentLink(paths))) {
+        return versionIn(join(paths.runtime, readlinkSync(currentLink(paths))));
+    }
+    return versionIn(paths.runtime);
+}
+/** The version folders there are, each with a complete package in it. */
+export function installedVersions(paths) {
+    try {
+        return readdirSync(paths.runtime)
+            .filter((name) => VERSION.test(name) && versionIn(join(paths.runtime, name)) === name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Points `link` at `target` in one step: a new link renamed over the old one. */
+function link(target, path) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    rmSync(tmp, { force: true });
+    symlinkSync(target, tmp);
+    renameSync(tmp, path);
+}
+/** Moves a runtime from before the version folders into `runtime/<version>/`. */
+function adoptLegacy(paths) {
+    const version = versionIn(paths.runtime);
+    if (isLink(modules(paths)) || !version) {
+        return;
+    }
+    const into = runtimeDir(paths, version);
+    rmSync(into, { recursive: true, force: true });
+    mkdirSync(into, { recursive: true });
+    for (const name of ["node_modules", "package.json", "package-lock.json"]) {
+        if (existsSync(join(paths.runtime, name))) {
+            renameSync(join(paths.runtime, name), join(into, name));
+        }
+    }
+    link(version, currentLink(paths));
+}
+/** Makes `version` the one `bin/wizards` starts from now on. */
+export function switchTo(paths, version) {
+    if (versionIn(runtimeDir(paths, version)) !== version) {
+        throw new Error(`${runtimeDir(paths, version)} holds no complete runtime ${version}.`);
+    }
+    adoptLegacy(paths);
+    link(version, currentLink(paths));
+    link(join("current", "node_modules"), modules(paths));
+}
+/** Deletes the version folders other than `keep` and the current one; returns what went. */
+export function prune(paths, keep) {
+    const current = currentVersion(paths);
+    const stale = installedVersions(paths).filter((v) => v !== current && !keep.includes(v));
+    for (const version of stale) {
+        rmSync(runtimeDir(paths, version), { recursive: true, force: true });
+    }
+    return stale;
+}
+/** Puts an npm prefix installed elsewhere into its version folder (never the current one). */
+export function promote(paths, staged, version) {
+    if (versionIn(staged) !== version) {
+        throw new Error(`The download holds version ${versionIn(staged) ?? "none"}, not ${version}.`);
+    }
+    if (currentVersion(paths) === version) {
+        rmSync(staged, { recursive: true, force: true });
+        return;
+    }
+    rmSync(runtimeDir(paths, version), { recursive: true, force: true });
+    renameSync(staged, runtimeDir(paths, version));
+}