basepad 0.0.0-stage → 0.0.0

package/dist/commands.js

@@ -0,0 +1,989 @@
+import { existsSync } from "node:fs";
+import { readdir, realpath, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { z } from "zod";
+import { kindOf, } from "./catalogue.js";
+import { readHookInput } from "./claude-hooks.js";
+import { CONFIG_FILE, LABEL, loadProject } from "./config.js";
+import { copyEnvFiles, writeEnvFiles } from "./env-files.js";
+import { dropHosts, syncHosts } from "./hosts.js";
+import { init } from "./init.js";
+import { BasepadError, shellQuote } from "./internal/exec.js";
+import { Stopped } from "./internal/ports.js";
+import { table } from "./internal/table.js";
+import { daemonId, definitionsFile, isRootOnLinux, layout, localhostCertificate, machine, namespaceOf, ownServers, placeOf, servicesHome, suffixOf, supervisorPaths, } from "./layout.js";
+import { setup, trustAsRoot } from "./setup.js";
+import { openSupervisor } from "./supervisor.js";
+import { ensureLocalhostCertificate } from "./tls.js";
+import { checkedOut, checkOutWorktree, checkoutOf, clonePaths, hasChanges, listWorktrees, removeCheckout, runSetup, } from "./worktrees.js";
+const SERVICE_FLAG = {
+    short: "s",
+    value: "key",
+    description: "The database service to act on; needed when there are several",
+};
+export const COMMANDS = {
+    init: {
+        summary: `Write a starter ${CONFIG_FILE} in this folder`,
+        flags: {},
+        run: init,
+    },
+    setup: {
+        summary: "Once per machine: trust basepad's certificate and drop the port from URLs",
+        flags: {
+            "dry-run": { description: "Print the plan and change nothing" },
+            yes: { short: "y", description: "Apply the plan without asking" },
+        },
+        run: setup,
+    },
+    up: {
+        summary: "Start this project's services and apps, set its env files, then open mission control",
+        flags: {
+            detach: {
+                short: "d",
+                description: "Return once started, without opening mission control (as with no terminal)",
+            },
+            claim: {
+                description: "Make this folder the owner of the project's databases, which another checkout under the same name holds",
+            },
+        },
+        run: up,
+    },
+    down: {
+        summary: "Stop this project's apps and services; nothing is deleted",
+        flags: {},
+        run: down,
+    },
+    status: {
+        summary: "Show each app and service with its address and state",
+        flags: {},
+        run: status,
+    },
+    "worktree add": {
+        summary: "Make a worktree of main, with its own databases, domains and env files",
+        flags: {
+            json: { description: "Print only the worktree's name and path, as JSON" },
+            branch: {
+                value: "name",
+                description: "Check out this branch, or make it from main's HEAD when it does not exist",
+            },
+            start: { description: "Start its apps now, not on the first request to their domains" },
+            claude: {
+                description: "Claude Code's WorktreeCreate hook: read its input on stdin, use its name as the branch, print only the path",
+            },
+        },
+        run: worktreeAdd,
+    },
+    "worktree ls": {
+        summary: "List main's worktrees with their branches and folders",
+        flags: {},
+        run: worktreeLs,
+    },
+    "worktree rm": {
+        summary: "Remove a worktree: its apps, databases, registrations and git worktree; its branch stays",
+        args: ["worktree?"],
+        flags: {
+            force: { description: "Remove it even with uncommitted changes, which are lost" },
+            claude: {
+                description: "Claude Code's WorktreeRemove hook: remove the worktree at its input's path, as --force does",
+            },
+        },
+        run: worktreeRm,
+    },
+    prune: {
+        summary: "Remove what is left of worktrees whose folder is gone, after showing it",
+        flags: {
+            yes: {
+                short: "y",
+                description: "Remove worktrees' leftovers without asking; a removed service's data is still asked",
+            },
+        },
+        run: prune,
+    },
+    "db save": {
+        summary: "Save this environment's database as a snapshot, replacing one of the same label",
+        args: ["label?"],
+        flags: { service: SERVICE_FLAG },
+        run: dbSave,
+    },
+    "db load": {
+        summary: "Replace this environment's database with a snapshot, which is kept",
+        args: ["label?"],
+        flags: { service: SERVICE_FLAG },
+        run: dbLoad,
+    },
+    "db snapshots": {
+        summary: "List this environment's snapshots",
+        flags: {},
+        run: dbSnapshots,
+    },
+    "db rm": {
+        summary: "Delete one of this environment's snapshots",
+        args: ["label"],
+        flags: { service: SERVICE_FLAG },
+        run: dbRm,
+    },
+    "db import": {
+        summary: "Replace this environment's database with a dump file or a postgres:// URL's, after asking",
+        args: ["file or url"],
+        flags: {
+            service: SERVICE_FLAG,
+            yes: { short: "y", description: "Replace the database without asking" },
+        },
+        run: dbImport,
+    },
+    "db export": {
+        summary: "Write a dump of this environment's database to a file, or to standard output",
+        args: ["file?"],
+        flags: { service: SERVICE_FLAG },
+        run: dbExport,
+    },
+};
+/** How long `up` waits for apps to listen or fail before it shows their state and returns. */
+const APP_WAIT_MS = 5000;
+/** How many of a failed app's last lines `up` shows. */
+const FAILED_LINES = 20;
+/** The environment whose config is in `cwd` or its nearest parent with one. */
+async function environmentAt(cwd) {
+    const project = await loadProject(cwd);
+    const checkout = await checkoutOf(project.root);
+    if (checkout.suffix === undefined)
+        return { project };
+    if (!LABEL.test(checkout.suffix)) {
+        throw new BasepadError(`${project.root} is git worktree \`${checkout.suffix}\`, and a worktree's folder name is its suffix in domains and databases, so it must be a lowercase DNS label (letters, digits and inner hyphens). Rename it with \`git worktree move <folder> <new-folder>\`.`);
+    }
+    if (!existsSync(join(checkout.main, CONFIG_FILE))) {
+        throw new BasepadError(`${project.root} is git worktree \`${checkout.suffix}\`, made from ${checkout.main}, which has no ${CONFIG_FILE}. A worktree is made from main: commit the config there and run \`basepad up\` in it.`);
+    }
+    const main = await loadProject(checkout.main);
+    if (main.name !== project.name) {
+        throw new BasepadError(`This worktree's config names the project "${project.name}", and main's (${main.file}) "${main.name}". A worktree's services are main's, so their names must match.`);
+    }
+    return { project, suffix: checkout.suffix, main };
+}
+/**
+ * Makes an environment ready to start its apps: registers its definitions, starts its services
+ * (main's, in a worktree, and its own servers) and provisions them, and writes its env files.
+ * Starts no app. A worktree needs main ready first. Main's servers always start: every
+ * environment's services need them. Of a worktree's own servers, those `start` picks (all by
+ * default); the rest are left to its first start, and its env files say where they will listen.
+ */
+async function ready(environment, context, { start = () => true } = {}) {
+    const { project, suffix, main } = environment;
+    const { here, supervisor, print } = context;
+    // Ports, folders and databases; the URL form waits for the supervisor, which answers on 443.
+    const ports = layout(project, here, suffix);
+    const services = Object.keys(project.services);
+    const owner = await supervisor.owner(ports.namespace);
+    if (owner !== undefined && owner !== project.root && !context.claim) {
+        throw new BasepadError(`"${ports.namespace}" is the name of the checkout at ${owner}. Two checkouts under one name would share its databases and domains, so basepad stops here.\nIf that checkout moved here, or this one should take over, run \`basepad up --claim\`.`);
+    }
+    const missing = services.filter((key) => main !== undefined && !(key in main.services));
+    if (missing.length > 0) {
+        throw new BasepadError(`This worktree's config has ${missing.map((key) => `\`${key}\``).join(", ")}, which main's has not. A worktree's services run on main's servers: add ${missing.length > 1 ? "them" : "it"} to main's config and run \`basepad up\` there first.`);
+    }
+    const daemons = {};
+    // Main's servers, and a worktree's own; a worktree's other services run on main's.
+    for (const key of ownServers(ports)) {
+        const service = project.services[key];
+        daemons[key] = await kindOf(service).prepare(service, placeOf(project, ports, here, key));
+    }
+    const servers = Object.values(ports.services).map((place) => place.daemon);
+    // No request reaches these, so the apps with a domain start them.
+    const unreached = Object.keys(project.apps).filter((key) => ports.apps[key]?.host === undefined);
+    const tls = localhostCertificate(here);
+    for (const [key, app] of Object.entries(project.apps)) {
+        const run = withLocalBins(project, app.cwd, app.run);
+        const port = ports.apps[key]?.port;
+        daemons[key] = {
+            run: app.domain === false
+                ? `export BASEPAD_TLS_CERT=${shellQuote(tls.cert)} BASEPAD_TLS_KEY=${shellQuote(tls.key)} && ${run}`
+                : run,
+            dir: app.cwd,
+            port,
+            ...(app.domain === false ? { proxy: false } : {}),
+            // So the proxy's start on a first request starts the servers first, wherever they run,
+            // and the apps no request reaches.
+            depends: unreached.includes(key)
+                ? servers
+                : [...servers, ...unreached.map((name) => daemonId(ports.namespace, name))],
+        };
+    }
+    // Made before any app can start, once the proxy, which makes the CA, runs.
+    if (Object.values(project.apps).some((app) => app.domain === false)) {
+        await supervisor.serve();
+        const { ca, caKey } = supervisorPaths(here);
+        await ensureLocalhostCertificate({ ca, caKey, ...tls });
+    }
+    await supervisor.register({
+        namespace: ports.namespace,
+        ...(suffix === undefined ? { label: project.name } : {}),
+        dir: project.root,
+        definitions: ports.definitions,
+        daemons,
+    });
+    if (suffix === undefined && isRootOnLinux()) {
+        for (const line of await trustAsRoot(supervisor))
+            print(line);
+    }
+    const lay = layout(project, await machineWithPortFree(here, supervisor), suffix);
+    // Services' domains are main's, as the services are.
+    const domains = Object.values(lay.services).flatMap((place) => place.web === undefined || suffix !== undefined ? [] : [place.web.host]);
+    for (const line of await syncHosts(lay.namespace, [
+        ...Object.values(lay.apps).flatMap((a) => a.host ?? []),
+        ...domains,
+    ])) {
+        print(line);
+    }
+    const since = new Date(Date.now() - 1000);
+    const outputs = {};
+    const own = ownServers(lay);
+    const runsIn = (key) => (own.includes(key) ? lay.namespace : lay.mainNamespace);
+    const started = services.filter((key) => runsIn(key) === lay.mainNamespace || start(key));
+    for (const namespace of new Set(started.map(runsIn))) {
+        const keys = started.filter((key) => runsIn(key) === namespace);
+        const hosts = Object.fromEntries(keys.flatMap((key) => {
+            const web = lay.services[key]?.web;
+            return web === undefined ? [] : [[key, web.host]];
+        }));
+        const states = await supervisor.start(namespace, keys, APP_WAIT_MS, hosts);
+        const failed = keys.filter((key) => states[key] === "failed");
+        if (failed.length > 0)
+            throw new BasepadError(await failures(supervisor, namespace, failed, since));
+    }
+    for (const key of services) {
+        const service = project.services[key];
+        const namespace = runsIn(key);
+        try {
+            outputs[key] = await kindOf(service).provision(service, placeOf(project, lay, here, key), {
+                claim: context.claim,
+                started: started.includes(key),
+                print,
+                stopped: async () => {
+                    const state = (await supervisor.status(namespace))[key];
+                    return state === "failed" || state === "stopped";
+                },
+            });
+        }
+        catch (error) {
+            if (!(error instanceof Stopped))
+                throw error;
+            throw new BasepadError(await failures(supervisor, namespace, [key], since));
+        }
+    }
+    for (const [key, app] of Object.entries(lay.apps)) {
+        if (app.url !== undefined)
+            outputs[key] = { url: app.url };
+    }
+    const files = envFiles(project, outputs);
+    if (main !== undefined)
+        await copyEnvFiles(main.root, project.root, Object.keys(files));
+    await writeEnvFiles(project.root, files);
+    return lay;
+}
+/**
+ * Opens the supervisor (or takes the one opened), and readies main first when the environment is a
+ * worktree.
+ */
+async function open(environment, flags, print, opened) {
+    const here = machine(process.env);
+    const supervisor = opened ?? (await openSupervisor(here, print));
+    const context = { here, supervisor, claim: flags.claim === true, print };
+    // `--claim` in a worktree claims the worktree's, never main's.
+    if (environment.main !== undefined) {
+        await ready({ project: environment.main }, { ...context, claim: false });
+    }
+    return context;
+}
+async function up({ cwd, flags, print }) {
+    const environment = await environmentAt(cwd);
+    // Only on a terminal: scripts, CI and agents get `-d`'s behaviour without asking for it.
+    if (flags.detach !== true && process.stdin.isTTY && process.stdout.isTTY) {
+        return upOnTerminal(environment, flags, print);
+    }
+    const { project } = environment;
+    const context = await open(environment, flags, print);
+    const { supervisor, here } = context;
+    const lay = await ready(environment, context);
+    const { states, failure } = await startApps(supervisor, project, lay);
+    print(await stateTables(environment, lay, here, await withServices(supervisor, lay, states)));
+    if (failure !== undefined)
+        throw new BasepadError(failure);
+}
+/**
+ * `up` on a terminal: mission control opens at once and the environment readies meanwhile, so its
+ * logs show from the start. What readying prints waits for the view to close; a failure shows in it
+ * as a notice.
+ */
+async function upOnTerminal(environment, flags, print) {
+    const { project } = environment;
+    const here = machine(process.env);
+    // Loaded only here, so other commands never load the terminal UI.
+    const { missionControl } = await import("./mission-control/run.js");
+    const held = [];
+    const say = (line) => held.push(line);
+    const supervisor = await openSupervisor(here, say);
+    let served = here;
+    let outcome;
+    let error;
+    let notice;
+    const readying = (async () => {
+        const context = await open(environment, flags, say, supervisor);
+        const lay = await ready(environment, { ...context, print: say });
+        // The supervisor answers on 443 by now, so URLs show as they are served.
+        served = await machineWithPortFree(here, supervisor);
+        outcome = { lay, ...(await startApps(supervisor, project, lay)) };
+        if (outcome.failure !== undefined) {
+            const failed = Object.keys(project.apps).filter((key) => outcome?.states[key] === "failed");
+            notice = `${failed.map((key) => `\`${key}\``).join(", ")} exited on start; ${failed.length > 1 ? "their" : "its"} output is in the logs.`;
+        }
+    })().catch((caught) => {
+        error = caught;
+        notice = firstLine(caught instanceof Error ? caught.message : String(caught));
+    });
+    await missionControl({
+        main: environment.main ?? project,
+        machine: () => served,
+        supervisor,
+        failure: () => {
+            const told = notice;
+            notice = undefined;
+            return told;
+        },
+        selected: layout(project, here, environment.suffix).namespace,
+        // This very command, run again on the same Node: mission control adds and removes worktrees
+        // with it, in processes of their own that outlive the view.
+        basepad: [process.execPath, ...process.execArgv, process.argv[1]],
+    });
+    // Closed while it readies, the environment still finishes.
+    if (outcome === undefined && error === undefined)
+        print("Still starting; finishing…");
+    await readying;
+    for (const line of held)
+        print(line);
+    if (error !== undefined)
+        throw error;
+    if (outcome === undefined)
+        return;
+    const { lay, states, failure } = outcome;
+    print(await stateTables(environment, lay, here, await withServices(supervisor, lay, states)));
+    if (failure !== undefined)
+        throw new BasepadError(failure);
+}
+const firstLine = (text) => text.split("\n")[0] ?? text;
+/**
+ * Starts the environment's apps and waits briefly for them. Returns their states, and the report
+ * of those that failed, if any did.
+ */
+async function startApps(supervisor, project, lay) {
+    const since = new Date(Date.now() - 1000);
+    const apps = Object.keys(project.apps);
+    const hosts = Object.fromEntries(Object.entries(lay.apps).flatMap(([key, app]) => app.host === undefined ? [] : [[key, app.host]]));
+    const states = await supervisor.start(lay.namespace, apps, APP_WAIT_MS, hosts);
+    const failed = apps.filter((key) => states[key] === "failed");
+    if (failed.length === 0)
+        return { states };
+    return { states, failure: await failures(supervisor, lay.namespace, failed, since) };
+}
+/**
+ * `worktree add`: checks out a new worktree of main, copies the paths its config clones, readies it
+ * (its databases from main's, its env files from main's) and runs its setup commands. Its apps
+ * start on the first request to their domains, or now with `--start`. Prints where it is.
+ */
+async function worktreeAdd({ cwd, flags, print }) {
+    const hook = flags.claude === true;
+    if (hook && (flags.branch !== undefined || flags.json === true)) {
+        throw new BasepadError("`--claude` takes the branch from Claude Code's hook input and prints only the path, so it goes without `--branch` and `--json`.");
+    }
+    // With `--json` or `--claude`, stdout carries the answer alone.
+    const say = flags.json === true || hook ? (line) => console.error(line) : print;
+    const input = hook ? await readHookInput("WorktreeCreate") : undefined;
+    const at = await environmentAt(input?.cwd ?? cwd);
+    const main = at.main ?? at.project;
+    const context = await open({ project: main }, {}, say);
+    await ready({ project: main }, context);
+    // Main's config is read before checking out, so a name too long fails before anything is made.
+    const requested = input?.name ?? (typeof flags.branch === "string" ? flags.branch : undefined);
+    const { suffix, branch, root } = await checkOutWorktree(main, requested);
+    const kept = checkedOut(suffix, root);
+    say(`${kept}.`);
+    let environment;
+    let lay;
+    try {
+        environment = await environmentAt(root);
+        const { project } = environment;
+        for (const note of await clonePaths(main.root, project.root, project.worktrees.clone))
+            say(note);
+        // Its own servers with its apps: now with `--start`, else on their first start.
+        lay = await ready(environment, context, { start: () => flags.start === true });
+    }
+    catch (error) {
+        if (!(error instanceof BasepadError))
+            throw error;
+        throw new BasepadError(`${error.message}\n${kept}; once that is fixed, run \`basepad up\` there.`);
+    }
+    try {
+        await runSetup(environment.project.root, environment.project.worktrees.setup, say);
+    }
+    catch (error) {
+        if (!(error instanceof BasepadError))
+            throw error;
+        throw new BasepadError(`${error.message}\n${kept}; once that is fixed, run the rest of \`worktrees.setup\` there.`);
+    }
+    const { states, failure } = flags.start === true
+        ? await startApps(context.supervisor, environment.project, lay)
+        : { states: {}, failure: undefined };
+    if (flags.json === true) {
+        print(JSON.stringify({ name: suffix, path: root }));
+    }
+    else {
+        const all = await withServices(context.supervisor, lay, states);
+        say(await stateTables(environment, lay, context.here, all));
+        say("");
+        say(`Made worktree ${suffix} at ${root}, on branch ${branch}. ${flags.start === true ? "Its apps are started." : "Its apps start when their domains are first opened, or with `basepad up` there."}`);
+    }
+    if (hook)
+        print(root);
+    if (failure !== undefined)
+        throw new BasepadError(failure);
+}
+/** A worktree's daemon states with those of its services that run in main's namespace. */
+async function withServices(supervisor, lay, states) {
+    const own = ownServers(lay);
+    const mains = Object.keys(lay.services).filter((key) => !own.includes(key));
+    if (mains.length === 0)
+        return states;
+    const main = await supervisor.status(lay.mainNamespace);
+    return { ...states, ...Object.fromEntries(mains.map((key) => [key, main[key] ?? "stopped"])) };
+}
+/** The machine with `portFree` asked from its port 443, once the supervisor runs. */
+async function machineWithPortFree(here, supervisor) {
+    return { ...here, portFree: (await supervisor.standardPort()) === "proxy" };
+}
+/** Runs the config's `env` with each service's and app's outputs, and checks what it returns. */
+function envFiles(project, outputs) {
+    let files;
+    try {
+        files = project.env(outputs);
+    }
+    catch (error) {
+        throw new BasepadError(`${project.file}: \`env\` threw: ${error?.message ?? error}`);
+    }
+    const result = EnvFilesSchema.safeParse(files);
+    if (!result.success) {
+        throw new BasepadError(`${project.file}: \`env\` must return env file paths, each to keys with string or number values.`);
+    }
+    return result.data;
+}
+const EnvFilesSchema = z.record(z.string(), z.record(z.string(), z.union([z.string(), z.number()])));
+/** Runs an app's command with its own and the project's `node_modules/.bin` first, as npm does. */
+function withLocalBins(project, dir, run) {
+    const bins = [
+        ...new Set([join(dir, "node_modules/.bin"), join(project.root, "node_modules/.bin")]),
+    ];
+    return `export PATH=${bins.map(shellQuote).join(":")}:"$PATH" && ${run}`;
+}
+/** The apps table, then the services table, each when the project has any. */
+async function stateTables({ project }, lay, here, states) {
+    const tables = [];
+    if (Object.keys(lay.apps).length > 0) {
+        const rows = Object.entries(lay.apps).map(([key, app]) => [
+            key,
+            app.url ?? "",
+            states[key] ?? "stopped",
+        ]);
+        tables.push(table([["APP", "URL", "STATE"], ...rows]));
+    }
+    const services = Object.entries(project.services);
+    if (services.length > 0) {
+        const rows = [];
+        for (const [key, service] of services) {
+            const address = await kindOf(service).address(service, placeOf(project, lay, here, key));
+            rows.push([key, address, states[key] ?? "stopped"]);
+        }
+        tables.push(table([["SERVICE", "ADDRESS", "STATE"], ...rows]));
+    }
+    return tables.join("\n\n");
+}
+async function failures(supervisor, namespace, failed, since) {
+    const parts = [];
+    for (const key of failed) {
+        const lines = await supervisor.logs(namespace, key, since, FAILED_LINES);
+        parts.push([
+            `\`${key}\` exited on start. Its last output:`,
+            ...(lines.length > 0 ? lines : ["(none)"]).map((line) => `  ${line}`),
+            `For more, run: ${supervisor.logsCommand(namespace, key)}`,
+        ].join("\n"));
+    }
+    return parts.join("\n");
+}
+async function down({ cwd, print }) {
+    const { project, suffix } = await environmentAt(cwd);
+    const supervisor = await openSupervisor(machine(process.env), print);
+    const lay = layout(project, machine(process.env), suffix);
+    const { namespace } = lay;
+    const apps = Object.keys(project.apps);
+    // Its own servers stop with its apps; those on main's keep running for main.
+    const own = ownServers(lay);
+    const mains = Object.keys(project.services).filter((key) => !own.includes(key));
+    // On a terminal, the landing shows while they stop.
+    const landed = process.stdout.isTTY
+        ? await startLanding(project.name, suffix, [...apps, ...own], mains)
+        : undefined;
+    try {
+        // Held first, so no request starts an app again while it stops.
+        await supervisor.hold(namespace, apps);
+        await supervisor.stop(namespace);
+    }
+    catch (error) {
+        landed?.fail();
+        throw error;
+    }
+    if (landed !== undefined) {
+        await landed.land();
+        return;
+    }
+    const names = (keys) => keys.map((key) => `\`${key}\``).join(", ");
+    print(suffix === undefined
+        ? `Stopped ${project.name}'s apps and services.`
+        : `Stopped worktree ${suffix}'s apps${own.length > 0 ? ` and ${names(own)}` : ""}.${mains.length > 0 ? ` ${names(mains)} ${mains.length > 1 ? "run" : "runs"} on main's and keep${mains.length > 1 ? "" : "s"} running.` : ""}`);
+}
+/** Opens the landing for an environment's apps and services on the terminal. */
+async function startLanding(project, suffix, parts, kept) {
+    const [{ landing }, { colorsFor }, { default: chalk }] = await Promise.all([
+        import("./mission-control/launch.js"),
+        import("./mission-control/frame.js"),
+        import("chalk"),
+    ]);
+    return landing({
+        project,
+        environment: suffix ?? "main",
+        parts,
+        kept,
+        color: colorsFor(process.env.NO_COLOR, chalk.level),
+    });
+}
+async function status({ cwd, print }) {
+    const environment = await environmentAt(cwd);
+    const { project, suffix } = environment;
+    const here = machine(process.env);
+    if (Object.keys(project.apps).length === 0 && Object.keys(project.services).length === 0) {
+        print(`${project.file} names no apps or services.`);
+        return;
+    }
+    const supervisor = await openSupervisor(here, print);
+    const ports = layout(project, here, suffix);
+    const states = await withServices(supervisor, ports, await supervisor.status(ports.namespace));
+    // With no supervisor running nothing answers on 443, so the URL form is the port's default.
+    const lay = layout(project, Object.keys(states).length > 0 ? await machineWithPortFree(here, supervisor) : here, suffix);
+    print(await stateTables(environment, lay, here, states));
+    if (suffix === undefined)
+        await printWorktrees(project, here, supervisor, print);
+}
+/**
+ * Main's project, from main's folder or a worktree's, found through git. Reads main's config alone,
+ * so a worktree's broken or missing config does not stand in the way.
+ */
+async function mainAt(cwd) {
+    const here = await realpath(cwd);
+    const checkout = await checkoutOf(here);
+    return loadProject(checkout.suffix === undefined ? here : checkout.main);
+}
+/**
+ * `status` in main: each worktree git lists, with its tables from its own config, then what is left
+ * of worktrees whose folder is gone.
+ */
+async function printWorktrees(main, here, supervisor, print) {
+    for (const tree of await listWorktrees(main)) {
+        print("");
+        print(`${tree.suffix} on branch ${tree.branch ?? "(detached)"} at ${tree.root}`);
+        if (!tree.present) {
+            print("Its folder is gone; `basepad prune` clears what is left of it.");
+            continue;
+        }
+        try {
+            const environment = await environmentAt(tree.root);
+            const ports = layout(environment.project, here, tree.suffix);
+            const states = await withServices(supervisor, ports, await supervisor.status(ports.namespace));
+            const lay = layout(environment.project, await machineWithPortFree(here, supervisor), tree.suffix);
+            print(await stateTables(environment, lay, here, states));
+        }
+        catch (error) {
+            if (!(error instanceof BasepadError))
+                throw error;
+            print(error.message);
+        }
+    }
+    const left = await leftoversOf(main, here, supervisor);
+    const rows = leftoverRows({ ...left, checkouts: [] });
+    if (rows.length > 1) {
+        print("");
+        print("Left by worktrees whose folder is gone; `basepad prune` removes it:");
+        print(table(rows));
+    }
+}
+async function worktreeLs({ cwd, print }) {
+    const main = await mainAt(cwd);
+    const trees = await listWorktrees(main);
+    if (trees.length === 0) {
+        print("No worktrees. Make one with `basepad worktree add`.");
+        return;
+    }
+    const rows = trees.map((tree) => [
+        tree.suffix,
+        tree.branch ?? "(detached)",
+        tree.present ? tree.root : `${tree.root} (gone; \`basepad prune\` clears it)`,
+    ]);
+    print(table([["WORKTREE", "BRANCH", "FOLDER"], ...rows]));
+}
+/**
+ * `worktree rm`: removes a worktree from its suffix alone (git's record, the name pattern of its data,
+ * its registration), so it works whatever state its folder or config is in. Its branch stays.
+ */
+async function worktreeRm({ cwd, flags, args, print }) {
+    if (flags.claude === true)
+        return worktreeRmHook(cwd, args);
+    const [suffix] = args;
+    if (suffix === undefined)
+        throw new BasepadError("Usage: basepad worktree rm <worktree> [flags]");
+    const main = await mainAt(cwd);
+    const tree = (await listWorktrees(main)).find((listed) => listed.suffix === suffix);
+    if (tree === undefined) {
+        throw new BasepadError(`${main.name} has no worktree \`${suffix}\`. \`basepad worktree ls\` lists them; \`basepad prune\` clears what is left of one whose git worktree is gone.`);
+    }
+    if (tree.present && flags.force !== true && (await hasChanges(tree.path))) {
+        throw new BasepadError(`${tree.path} has uncommitted changes. Commit or stash them, or pass \`--force\` to lose them.`);
+    }
+    await removeWorktree(main, tree, print);
+}
+/**
+ * `worktree rm --claude`: removes the worktree at the hook input's `worktree_path`, changes and all:
+ * Claude Code has asked before discarding work, or found none. Says everything on stderr.
+ */
+async function worktreeRmHook(cwd, args) {
+    if (args.length > 0) {
+        throw new BasepadError("`--claude` takes the worktree from Claude Code's hook input, so it goes without a name.");
+    }
+    const input = await readHookInput("WorktreeRemove");
+    const path = await realpath(input.worktree_path).catch(() => input.worktree_path);
+    // From the worktree itself while it exists, so a session folder elsewhere does not matter.
+    const checkout = existsSync(path) ? await checkoutOf(path) : {};
+    const main = checkout.suffix === undefined
+        ? await mainAt(input.cwd ?? cwd)
+        : await loadProject(checkout.main);
+    const tree = (await listWorktrees(main)).find((t) => t.root === path || t.path === path);
+    if (tree === undefined) {
+        throw new BasepadError(`${input.worktree_path} is no worktree of ${main.name}'s main at ${main.root}. \`basepad worktree ls\` lists them.`);
+    }
+    await removeWorktree(main, tree, (line) => console.error(line));
+}
+/** Removes a listed worktree of main: what basepad made for it, then its git worktree. */
+async function removeWorktree(main, tree, print) {
+    // Main's servers hold the worktree's data, so they run for it to be dropped.
+    const context = await open({ project: main }, {}, print);
+    await ready({ project: main }, context);
+    await removeEnvironment(main, tree.suffix, tree.root, context);
+    await removeCheckout(main, tree.path);
+    print(`Removed worktree ${tree.suffix}: its apps, databases and git worktree.${tree.branch === undefined ? "" : ` Its branch ${tree.branch} is kept.`}`);
+}
+/**
+ * Removes what basepad made for worktree `suffix` of main, from main's config alone: its apps and
+ * registration, its domains in the hosts file, and its data on main's servers (never main's own: a
+ * `shared` service's is main's).
+ */
+async function removeEnvironment(main, suffix, root, { here, supervisor }) {
+    // From names alone: main's config may since have made this suffix's names too long.
+    const namespace = namespaceOf(main.name, suffix);
+    await supervisor.unregister({ namespace, definitions: definitionsFile(here, namespace) });
+    await dropHosts(namespace);
+    const lay = layout(main, here);
+    const tree = worktreeLayout(main, here, suffix);
+    for (const [key, service] of Object.entries(main.services)) {
+        const store = kindOf(service).worktreeData;
+        if (store === undefined)
+            continue;
+        const place = placeOf(main, lay, here, key);
+        // Its data by name or stamp; with no names that fit, by its stamp among every worktree's.
+        const data = tree === undefined
+            ? (await store.list(service, place)).filter((d) => d.owner === root)
+            : await store.list(service, { ...placeOf(main, tree, here, key), owner: root });
+        await store.drop(service, place, data.map((d) => d.name));
+    }
+}
+/** A worktree's layout, or none when its names are past their limits under main's config. */
+function worktreeLayout(main, here, suffix) {
+    try {
+        return layout(main, here, suffix);
+    }
+    catch (error) {
+        if (error instanceof BasepadError)
+            return undefined;
+        throw error;
+    }
+}
+/** Found by name alone: git's list, data stamped with a gone folder, registrations of a gone folder. */
+async function leftoversOf(main, here, supervisor) {
+    const checkouts = (await listWorktrees(main)).filter((tree) => !tree.present);
+    const lay = layout(main, here);
+    const data = [];
+    for (const [key, service] of Object.entries(main.services)) {
+        const store = kindOf(service).worktreeData;
+        if (store === undefined)
+            continue;
+        const found = await store.list(service, placeOf(main, lay, here, key));
+        const gone = found.filter((d) => d.owner !== "" && !existsSync(d.owner));
+        if (gone.length > 0)
+            data.push({ key, data: gone });
+    }
+    const registrations = (await supervisor.registrations()).filter((entry) => suffixOf(main.name, entry.namespace) !== undefined && !existsSync(entry.dir));
+    return { checkouts, data, registrations };
+}
+/** Leftovers as a table's rows, its header first. */
+function leftoverRows({ checkouts, data, registrations }) {
+    return [
+        ["LEFTOVER", "NAME", "FOLDER"],
+        ...checkouts.map((tree) => ["git worktree", tree.suffix, tree.path]),
+        ...data.flatMap(({ key, data }) => data.map((d) => [`${key} data`, d.name, d.owner])),
+        ...registrations.map((entry) => ["registration", entry.namespace, entry.dir]),
+    ];
+}
+/** The folders in basepad's home of services main's config no longer has, by key. */
+async function removedServices(main, here) {
+    const home = servicesHome(here, main.name);
+    if (!existsSync(home))
+        return [];
+    return (await readdir(home))
+        .filter((key) => !(key in main.services))
+        .map((key) => [key, join(home, key)]);
+}
+/**
+ * `prune`: lists what is left of worktrees whose folder is gone, and the data of services main's
+ * config no longer has, then asks before removing each. `--yes` answers for the first only: a
+ * removed service's data is main's too, so it is deleted only on a terminal's yes.
+ */
+async function prune({ cwd, flags, print }) {
+    const main = await mainAt(cwd);
+    const context = await open({ project: main }, {}, print);
+    await ready({ project: main }, context);
+    const { here, supervisor } = context;
+    const left = await leftoversOf(main, here, supervisor);
+    const rows = leftoverRows(left);
+    const services = await removedServices(main, here);
+    if (rows.length === 1 && services.length === 0) {
+        print("Nothing to prune.");
+        return;
+    }
+    if (rows.length > 1) {
+        print("Left by worktrees whose folder is gone:");
+        print(table(rows));
+    }
+    if (services.length > 0) {
+        print(`Data of services no longer in ${main.file}, main's included:`);
+        print(table([["SERVICE", "FOLDER"], ...services]));
+    }
+    let unasked = false;
+    if (rows.length > 1) {
+        const yes = flags.yes === true || (await ask("Remove what worktrees left?"));
+        if (yes === undefined)
+            unasked = true;
+        else if (yes) {
+            await removeLeftovers(main, left, context);
+            print("Removed what worktrees left.");
+        }
+        else
+            print("Kept what worktrees left.");
+    }
+    if (services.length > 0) {
+        const yes = await ask(`Delete the data of ${services.map(([key]) => `\`${key}\``).join(", ")}?`);
+        if (yes === true) {
+            // A service taken out of the config keeps running until stopped.
+            await supervisor.stop(layout(main, here).mainNamespace, services.map(([key]) => key));
+            for (const [, folder] of services)
+                await rm(folder, { recursive: true, force: true });
+            print(`Deleted ${services.map(([, folder]) => folder).join(", ")}.`);
+        }
+        else {
+            print(`Kept the data of removed services${yes === undefined ? "; `basepad prune` on a terminal asks to delete it" : ""}.`);
+        }
+    }
+    if (unasked) {
+        throw new BasepadError("Nothing worktrees left was removed: there is no terminal to ask. Run `basepad prune --yes` to remove it.");
+    }
+}
+async function removeLeftovers(main, left, context) {
+    const { here, supervisor } = context;
+    const lay = layout(main, here);
+    for (const { key, data } of left.data) {
+        const service = main.services[key];
+        await kindOf(service).worktreeData?.drop(service, placeOf(main, lay, here, key), data.map((d) => d.name));
+    }
+    for (const { namespace } of left.registrations) {
+        await supervisor.unregister({ namespace, definitions: definitionsFile(here, namespace) });
+        await dropHosts(namespace);
+    }
+    for (const tree of left.checkouts)
+        await removeCheckout(main, tree.path);
+}
+/** Asks a yes-or-no question on the terminal; with no terminal, no answer. */
+async function ask(question) {
+    if (!process.stdin.isTTY)
+        return undefined;
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await prompt.question(`${question} [y/N] `);
+    prompt.close();
+    return /^y(es)?$/i.test(answer.trim());
+}
+/** The label `db save` and `db load` use when given none. */
+const DEFAULT_LABEL = "default";
+/** The environment `cwd` is in, with its database services; throws when it has none. */
+async function databaseServicesAt(cwd) {
+    const environment = await environmentAt(cwd);
+    const { project } = environment;
+    const [first, ...rest] = Object.entries(project.services).flatMap(([key, service]) => {
+        const { database } = kindOf(service);
+        return database === undefined ? [] : [{ key, service, database }];
+    });
+    if (first === undefined) {
+        throw new BasepadError(`${project.file} names no database service.`);
+    }
+    return { environment, services: [first, ...rest] };
+}
+/**
+ * The database a `db` command acts on: `--service`'s, or the environment's one database. With
+ * several and no `--service`, says which there are.
+ */
+function chosen(project, services, wanted) {
+    const names = services.map(({ key }) => `\`${key}\``).join(", ");
+    if (typeof wanted === "string") {
+        const found = services.find(({ key }) => key === wanted);
+        if (found === undefined) {
+            throw new BasepadError(`${project.file} has no database service \`${wanted}\`. Its databases: ${names}.`);
+        }
+        return found;
+    }
+    const [only, ...more] = services;
+    if (more.length > 0) {
+        throw new BasepadError(`${project.file} has several databases: ${names}. Name one with \`--service <key>\`.`);
+    }
+    return only;
+}
+/**
+ * Makes the environment ready as `up` makes it, without starting apps, for `db` commands on
+ * `services`: of a worktree's own servers, only theirs start. Resolves to what puts a database
+ * service on its server.
+ */
+async function readyFor(environment, print, services) {
+    const keys = services.map(({ key }) => key);
+    const context = await open(environment, {}, print);
+    const lay = await ready(environment, context, { start: (key) => keys.includes(key) });
+    return (service) => ({
+        ...service,
+        place: placeOf(environment.project, lay, context.here, service.key),
+    });
+}
+/** The database a `db` command acts on, chosen as `chosen` says, ready on its server. */
+async function databaseAt({ cwd, flags, print }) {
+    const { environment, services } = await databaseServicesAt(cwd);
+    const service = chosen(environment.project, services, flags.service);
+    const onServer = await readyFor(environment, print, [service]);
+    return onServer(service);
+}
+/** A snapshot label given, or the default; a lowercase DNS label, as suffixes are. */
+function labelOf(args) {
+    const [label = DEFAULT_LABEL] = args;
+    if (!LABEL.test(label)) {
+        throw new BasepadError(`A snapshot label must be lowercase letters, digits and inner hyphens; got \`${label}\`.`);
+    }
+    return label;
+}
+async function dbSave(invocation) {
+    const label = labelOf(invocation.args);
+    const { key, service, place, database } = await databaseAt(invocation);
+    await database.save(service, place, label);
+    invocation.print(`Saved \`${key}\` as snapshot ${label}.`);
+}
+async function dbLoad(invocation) {
+    const label = labelOf(invocation.args);
+    const { key, service, place, database } = await databaseAt(invocation);
+    await database.load(service, place, label);
+    invocation.print(`Loaded snapshot ${label} into \`${key}\`.`);
+}
+async function dbRm(invocation) {
+    const label = labelOf(invocation.args);
+    const { key, service, place, database } = await databaseAt(invocation);
+    await database.remove(service, place, label);
+    invocation.print(`Deleted snapshot ${label} of \`${key}\`.`);
+}
+/** Every database's snapshots in the environment. */
+async function dbSnapshots({ cwd, print }) {
+    const { environment, services } = await databaseServicesAt(cwd);
+    const onServer = await readyFor(environment, print, services);
+    const targets = services.map(onServer);
+    const rows = [];
+    for (const { key, service, place, database } of targets) {
+        for (const snapshot of await database.snapshots(service, place)) {
+            rows.push([
+                snapshot.label,
+                key,
+                snapshot.database,
+                snapshot.invalid ? "invalid" : size(snapshot.bytes),
+            ]);
+        }
+    }
+    if (rows.length === 0) {
+        print("No snapshots. Make one with `basepad db save [label]`.");
+        return;
+    }
+    print(table([["LABEL", "SERVICE", "DATABASE", "SIZE"], ...rows]));
+}
+/** Bytes as a person reads them: `7.5 MB`. */
+function size(bytes) {
+    const units = ["B", "kB", "MB", "GB", "TB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1000 && unit < units.length - 1) {
+        value /= 1000;
+        unit++;
+    }
+    return `${unit === 0 ? value : value.toFixed(1)} ${units[unit]}`;
+}
+/**
+ * `db import`: replaces the database with a dump or another server's, after asking with its name
+ * on a terminal; `--yes` answers. With no terminal and no `--yes`, it changes nothing.
+ */
+async function dbImport(invocation) {
+    const [given = ""] = invocation.args;
+    const { key, service, place, database } = await databaseAt(invocation);
+    // A file is the developer's from where they ran it; anything else is the kind's to read.
+    const file = resolve(invocation.cwd, given);
+    const source = existsSync(file) ? file : given;
+    let replaced = "";
+    const read = await database.import(service, place, source, async (name) => {
+        replaced = name;
+        if (invocation.flags.yes === true)
+            return;
+        const yes = await ask(`Replace \`${key}\`'s database ${name}? Its data is lost.`);
+        if (yes === undefined) {
+            throw new BasepadError(`Import replaces \`${key}\`'s database ${name}, and there is no terminal to ask. Run it again with \`--yes\` to replace it.`);
+        }
+        if (!yes)
+            throw new BasepadError(`Nothing imported; ${name} is unchanged.`);
+    });
+    invocation.print(`Imported ${read} into \`${key}\`'s database ${replaced}.`);
+}
+/**
+ * `db export`: a dump of the database to a file, or to standard output, which then carries only
+ * the dump: anything else basepad says goes to standard error. Never a binary dump to a terminal.
+ */
+async function dbExport(invocation) {
+    const [given] = invocation.args;
+    if (given === undefined && process.stdout.isTTY) {
+        throw new BasepadError("With no file, `db export` writes the dump to standard output, which is a terminal here. Name a file, or redirect it: `basepad db export > db.dump`.");
+    }
+    const say = given === undefined ? (line) => console.error(line) : invocation.print;
+    const { key, service, place, database } = await databaseAt({ ...invocation, print: say });
+    const file = given === undefined ? undefined : resolve(invocation.cwd, given);
+    const format = await database.export(service, place, file);
+    if (file !== undefined)
+        invocation.print(`Exported \`${key}\` to ${file} as ${format}.`);
+}