basepad 0.0.0-stage → 0.0.0

package/dist/internal/ports.js

@@ -0,0 +1,63 @@
+import { createConnection, createServer } from "node:net";
+import { BasepadError } from "./exec.js";
+/** How many ports past the first one `freePort` tries. */
+const SPAN = 100;
+/** The first port from `from` on loopback that nothing listens on and basepad can bind. */
+export async function freePort(from) {
+    for (let port = from; port < from + SPAN && port <= 65535; port++) {
+        if (!(await answers(port)) && (await canListen(port)))
+            return port;
+    }
+    throw new BasepadError(`No free port on 127.0.0.1 from ${from} to ${from + SPAN - 1}.`);
+}
+/** Whether something accepts connections on `port` at any of `hosts`, tried in order. */
+export async function answers(port, hosts = ["127.0.0.1"]) {
+    for (const host of hosts) {
+        const ok = await new Promise((resolve) => {
+            const socket = createConnection({ host, port });
+            socket.setTimeout(500);
+            socket.on("connect", () => {
+                socket.destroy();
+                resolve(true);
+            });
+            socket.on("timeout", () => {
+                socket.destroy();
+                resolve(false);
+            });
+            socket.on("error", () => resolve(false));
+        });
+        if (ok)
+            return true;
+    }
+    return false;
+}
+function canListen(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.listen({ port, host: "127.0.0.1", exclusive: true }, () => server.close(() => resolve(true)));
+    });
+}
+/** What `waitFor` throws when what it waits on has stopped: waiting longer cannot help. */
+export class Stopped extends Error {
+}
+/**
+ * Polls `check` until it resolves, or throws `failure` with the last error after `timeoutMs`.
+ * After each failed check it asks `stopped`, and throws `Stopped` at once when it says so.
+ */
+export async function waitFor(check, failure, timeoutMs, stopped = async () => false) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            return await check();
+        }
+        catch (error) {
+            if (await stopped())
+                throw new Stopped(failure);
+            if (Date.now() > deadline) {
+                throw new BasepadError(`${failure}\n${error.message}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+    }
+}

package/dist/internal/processes.js

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { shellQuote } from "./exec.js";
+/**
+ * Whether process `pid` is there, whoever runs it: a server basepad runs as its service user
+ * cannot be signalled, and is there all the same.
+ */
+export function alive(pid) {
+    return signalled(pid) !== "gone";
+}
+/** Whether process `pid` is there and ours: one we may not signal is another user's. */
+export function aliveAndOurs(pid) {
+    return signalled(pid) === "ours";
+}
+function signalled(pid) {
+    try {
+        process.kill(pid, 0);
+        return "ours";
+    }
+    catch (error) {
+        return error.code === "EPERM" ? "another's" : "gone";
+    }
+}
+/**
+ * A shell command writing the shell's process id and `port` to `file`, a line each, for a daemon's
+ * `run` that then `exec`s its server: `exec` keeps the shell's process id, so the file names the
+ * running server. `runningPort(file)` reads it back.
+ */
+export function recordRunning(file, port) {
+    return `printf '%s\\n%s\\n' "$$" ${port} > ${shellQuote(file)}`;
+}
+/**
+ * The port in pid file `file` while its process runs: the process id is its first line, the port
+ * its line `portLine` (from 0). None when the file or either line is missing, or the process is gone.
+ */
+export async function runningPort(file, portLine = 1) {
+    const lines = (await readFile(file, "utf8").catch(() => "")).split("\n");
+    const pid = Number(lines[0]);
+    const port = Number(lines[portLine]);
+    if (!pid || !port || !alive(pid))
+        return undefined;
+    return port;
+}

package/dist/internal/service-user.js

@@ -0,0 +1,53 @@
+import { chmod, chown, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { BasepadError, exec, must } from "./exec.js";
+const NAME = "basepad";
+const self = { wrap: (argv) => [...argv], grant: async () => { } };
+export async function serviceUser() {
+    if (process.getuid?.() !== 0)
+        return self;
+    if (process.platform !== "linux") {
+        throw new BasepadError("As root, basepad runs services as a system user, which it supports on Linux only.");
+    }
+    const exists = async () => (await exec("id", ["-u", NAME])).code === 0;
+    if (!(await exists())) {
+        // Another basepad, such as a second project's `up`, may create the user at the same time.
+        await must("useradd", [
+            "--system",
+            "--no-create-home",
+            "--shell",
+            "/usr/sbin/nologin",
+            NAME,
+        ]).catch(async (error) => {
+            if (!(await exists()))
+                throw error;
+        });
+    }
+    const uid = Number((await must("id", ["-u", NAME])).trim());
+    const gid = Number((await must("id", ["-g", NAME])).trim());
+    return {
+        // setpriv execs the program itself, so the supervisor's pid is the server's and its stop
+        // signal reaches the server directly; runuser would stay in between.
+        wrap: (argv) => [
+            "setpriv",
+            `--reuid=${uid}`,
+            `--regid=${gid}`,
+            "--clear-groups",
+            "--",
+            ...argv,
+        ],
+        async grant({ traverse, owned }) {
+            // mise installs under /root (0700), so the service user can't even reach Postgres's binaries.
+            // o+x on each ancestor grants passing through, without listing or reading anything.
+            for (const path of traverse) {
+                for (let dir = path; dir !== dirname(dir); dir = dirname(dir)) {
+                    const { mode } = await stat(dir);
+                    if ((mode & 0o001) === 0)
+                        await chmod(dir, mode | 0o001);
+                }
+            }
+            for (const path of owned)
+                await chown(path, uid, gid);
+        },
+    };
+}

package/dist/internal/table.js

@@ -0,0 +1,7 @@
+/** Rows as aligned columns, two spaces apart, the first row being the header. */
+export function table(rows) {
+    const widths = rows[0]?.map((_, i) => Math.max(...rows.map((row) => row[i]?.length ?? 0))) ?? [];
+    return rows
+        .map((row) => row.map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i] ?? 0))).join("  "))
+        .join("\n");
+}

package/dist/launcher.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * The `basepad` bin. It runs on whatever Node the project has, so it is kept to syntax and APIs
+ * that Node 18 understands: it checks mise, then runs basepad here when this Node is new enough,
+ * or again on a Node that mise provides.
+ */
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { MISE_MIN_VERSION, NODE_MAJOR } from "./versions.js";
+const INSTALL_MISE = "https://mise.jdx.dev/getting-started.html";
+function fail(message) {
+    process.stderr.write(`basepad: ${message}\n`);
+    process.exit(1);
+}
+/** `2026.10.24` as comparable numbers. */
+function calver(version) {
+    return version.split(".").map((part) => Number.parseInt(part, 10) || 0);
+}
+function older(version, floor) {
+    const a = calver(version);
+    const b = calver(floor);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] || 0;
+        const y = b[i] || 0;
+        if (x !== y)
+            return x < y;
+    }
+    return false;
+}
+const probe = spawnSync("mise", ["--version"], { encoding: "utf8" });
+if (probe.error) {
+    fail(`basepad needs mise ${MISE_MIN_VERSION} or newer, and \`mise\` is not on PATH. Install it: ${INSTALL_MISE}`);
+}
+const found = /\d+\.\d+\.\d+/.exec(probe.stdout || "");
+if (!found) {
+    fail(`basepad needs mise ${MISE_MIN_VERSION} or newer, and \`mise --version\` printed no version. Reinstall mise: ${INSTALL_MISE}`);
+}
+if (older(found[0], MISE_MIN_VERSION)) {
+    fail(`basepad needs mise ${MISE_MIN_VERSION} or newer; this is mise ${found[0]}. Update mise (\`mise self-update\`, or the way you installed it).`);
+}
+const major = Number(process.versions.node.split(".")[0]);
+if (major >= NODE_MAJOR) {
+    await import("./cli.js");
+}
+else {
+    const cli = fileURLToPath(new URL("./cli.js", import.meta.url));
+    const child = spawnSync("mise", ["exec", `node@${NODE_MAJOR}`, "--", "node", cli].concat(process.argv.slice(2)), 
+    // The PATH before mise puts its Node first, for the apps basepad's supervisor starts.
+    { stdio: "inherit", env: Object.assign({}, process.env, { BASEPAD_PATH: process.env.PATH }) });
+    if (child.error)
+        fail(`could not run basepad on Node ${NODE_MAJOR} through mise: ${child.error.message}`);
+    process.exit(child.status === null ? 1 : child.status);
+}

package/dist/layout.js

@@ -0,0 +1,234 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { kindOf } from "./catalogue.js";
+import { BasepadError } from "./internal/exec.js";
+/** The proxy's default port: high, so it needs no privilege, and unlike pitchfork's own suggestion. */
+const PROXY_PORT = 7443;
+/**
+ * Reads `BASEPAD_HOME` (default `~/.basepad`) and `BASEPAD_PROXY_PORT` (default 7443, or 443 as root
+ * on Linux, where the proxy binds it itself). `portFree` starts as what the port alone tells.
+ */
+export function machine(env, rootOnLinux = isRootOnLinux(), platform = process.platform) {
+    const raw = env.BASEPAD_PROXY_PORT;
+    const unset = raw === undefined || raw === "";
+    const proxyPort = unset ? (rootOnLinux ? 443 : PROXY_PORT) : Number(raw);
+    if (!Number.isInteger(proxyPort) || proxyPort < 1 || proxyPort > 65535) {
+        throw new BasepadError(`BASEPAD_PROXY_PORT must be a port number; got \`${raw}\`.`);
+    }
+    return {
+        home: env.BASEPAD_HOME || join(env.HOME || homedir(), ".basepad"),
+        proxyPort,
+        portFree: proxyPort === 443,
+        forwards443: unset && platform === "darwin",
+    };
+}
+/** Root on Linux needs no prompt for anything machine setup does: `up` does it itself. */
+export function isRootOnLinux() {
+    return process.platform === "linux" && process.getuid?.() === 0;
+}
+/** A DNS label's limit, in characters. */
+const LABEL_MAX = 63;
+/** App ports start in [20000, 32000): clear of common dev ports and of Linux's ephemeral range. */
+const APP_PORT_BASE = 20000;
+/** Each project gets a block of this many starting ports, chosen by its name. */
+const APP_PORT_BLOCK = 20;
+const APP_PORT_BLOCKS = 600;
+/** Service ports are in [15000, 20000): below the apps', clear of common dev ports. */
+const SERVICE_PORT_BASE = 15000;
+const SERVICE_PORTS = 5000;
+/**
+ * The worktree suffix a layout is checked against at load, so a name that leaves too little room
+ * fails before any worktree is made: the prefix with a three-digit number.
+ */
+const LONGEST_NUMBER = 999;
+/**
+ * Main's layout, or with `suffix` a worktree's. Main's also checks that a worktree's names will
+ * fit, with the longest suffix the prefix makes.
+ */
+export function layout(project, machine, suffix) {
+    const fail = (reason) => {
+        throw new BasepadError(`${project.file}: ${reason}`);
+    };
+    const { name } = project;
+    if (name.length > LABEL_MAX) {
+        fail(`\`name\` is ${name.length} characters; a domain label allows ${LABEL_MAX}.`);
+    }
+    if (suffix !== undefined && suffix.length > LABEL_MAX) {
+        fail(`the worktree suffix is ${suffix.length} characters; a domain label allows ${LABEL_MAX}.`);
+    }
+    /** What `env` sees. The one place the URL form is decided. */
+    const urlOf = (host) => `https://${host}${machine.portFree ? "" : `:${machine.proxyPort}`}`;
+    const apps = {};
+    const block = APP_PORT_BASE + (hash(name) % APP_PORT_BLOCKS) * APP_PORT_BLOCK;
+    for (const [i, [key, app]] of Object.entries(project.apps).entries()) {
+        if (app.port === false) {
+            apps[key] = {};
+            continue;
+        }
+        if (key.length > LABEL_MAX) {
+            fail(`app \`${key}\` is ${key.length} characters; a domain label allows ${LABEL_MAX}.`);
+        }
+        const port = block + (i % APP_PORT_BLOCK);
+        if (app.domain === false) {
+            apps[key] = { port };
+            continue;
+        }
+        const host = appHost(key, name, suffix);
+        apps[key] = { host, url: urlOf(host), port };
+    }
+    const namespace = namespaceOf(name, suffix);
+    const services = {};
+    for (const [key, service] of Object.entries(project.services)) {
+        const dir = join(servicesHome(machine, name), key);
+        let names;
+        try {
+            names = kindOf(service).names(service, { name, key, dir, suffix });
+        }
+        catch (error) {
+            if (error instanceof BasepadError)
+                fail(error.message);
+            throw error;
+        }
+        const web = kindOf(service).web === true;
+        // The service is main's, so its domain is main's in every environment, as its daemon is.
+        const host = appHost(key, name);
+        if (web && key in project.apps) {
+            fail(`service \`${key}\` is served at ${host}, which is app \`${key}\`'s domain. Rename one.`);
+        }
+        // A worktree's own server runs in its namespace, on a port from its name; else main's.
+        const runsIn = kindOf(service).perEnvironment?.(service) ? namespace : name;
+        services[key] = {
+            ...names,
+            port: servicePort(`${runsIn}.${key}`),
+            dir,
+            daemon: daemonId(runsIn, key),
+            ...(web ? { web: { host, url: urlOf(host), port: servicePort(`${name}.${key}.web`) } } : {}),
+        };
+    }
+    // Last, so a name main itself cannot have is reported in main's words.
+    if (suffix === undefined) {
+        const longest = `${project.worktrees.prefix}-${LONGEST_NUMBER}`;
+        try {
+            layout(project, machine, longest);
+        }
+        catch (error) {
+            if (!(error instanceof BasepadError) || !error.message.startsWith(`${project.file}: `)) {
+                throw error;
+            }
+            const reason = error.message.slice(project.file.length + 2);
+            const shorten = reason.startsWith("the worktree suffix")
+                ? "Shorten `worktrees.prefix`."
+                : "Shorten `name`, the service key or `worktrees.prefix`.";
+            fail(`worktree suffixes like "${longest}" leave too little room: ${reason} ${shorten}`);
+        }
+    }
+    return {
+        apps,
+        services,
+        definitions: definitionsFile(machine, namespace),
+        namespace,
+        mainNamespace: name,
+        ...(suffix === undefined ? {} : { suffix }),
+    };
+}
+/** Where one of the project's services lives in the layout `lay`, for its kind in the catalogue. */
+export function placeOf(project, lay, machine, key) {
+    const service = lay.services[key];
+    const suffix = lay.suffix === undefined ? {} : { suffix: lay.suffix };
+    return { name: project.name, key, owner: project.root, machine, ...suffix, ...service };
+}
+/**
+ * The keys of the services whose servers run in the environment's own namespace: every one in
+ * main, a worktree's own servers (`perEnvironment`) in a worktree. The others run in main's.
+ */
+export function ownServers(lay) {
+    return Object.entries(lay.services)
+        .filter(([, place]) => ofDaemon(place.daemon).namespace === lay.namespace)
+        .map(([key]) => key);
+}
+/**
+ * An app's domain: `<app>.<name>.localhost` in main, `<app>.<suffix>.<name>.localhost` in a
+ * worktree, as the supervisor's proxy serves it.
+ */
+export function appHost(app, name, suffix) {
+    return suffix === undefined ? `${app}.${name}.localhost` : `${app}.${suffix}.${name}.localhost`;
+}
+/**
+ * An environment's namespace with the supervisor: `<name>` for main, `<name>.<suffix>` for a
+ * worktree. Unchecked, so what basepad made for a worktree is found whatever its names' limits.
+ */
+export function namespaceOf(name, suffix) {
+    return suffix === undefined ? name : `${name}.${suffix}`;
+}
+/** The file in basepad's home holding a namespace's supervisor definitions. */
+export function definitionsFile(machine, namespace) {
+    return join(machine.home, "environments", `${namespace}.toml`);
+}
+/** A daemon's id with the supervisor: `<namespace>/<name>`. */
+export function daemonId(namespace, name) {
+    return `${namespace}/${name}`;
+}
+/** `daemonId` undone: a daemon's namespace and name from its id. */
+export function ofDaemon(id) {
+    const slash = id.lastIndexOf("/");
+    return { namespace: id.slice(0, slash), name: id.slice(slash + 1) };
+}
+/** The suffix of `namespace` when it is a worktree's of the project `name`; else none. */
+export function suffixOf(name, namespace) {
+    return namespace.startsWith(`${name}.`) ? namespace.slice(name.length + 1) : undefined;
+}
+/**
+ * The folder worktrees are checked out in: `worktrees.dir`, else `<name>.worktrees` beside the
+ * repository's top folder `top`. With `suffix`, that worktree's own folder in it.
+ */
+export function worktreeFolder(project, top, suffix) {
+    const dir = project.worktrees.dir ?? join(dirname(top), `${project.name}.worktrees`);
+    return suffix === undefined ? dir : join(dir, suffix);
+}
+/** A new worktree's suffix: `<prefix>-<n>` with the lowest `n` from 1 that no name in `taken` has. */
+export function nextSuffix(prefix, taken) {
+    const names = new Set(taken);
+    let n = 1;
+    while (names.has(`${prefix}-${n}`))
+        n++;
+    return `${prefix}-${n}`;
+}
+/** The folder in basepad's home holding a project's services, one folder per service key. */
+export function servicesHome(machine, name) {
+    return join(machine.home, "services", name);
+}
+/**
+ * The folder in basepad's home holding a project's worktree additions and removals started from
+ * mission control, while they run and until a view reads how they ended.
+ */
+export function workHome(machine, name) {
+    return join(machine.home, "work", name);
+}
+/** basepad's own pitchfork's folders in the home, and the CA its proxy signs with, and its key. */
+export function supervisorPaths(machine) {
+    const root = join(machine.home, "pitchfork");
+    const state = join(root, "state");
+    return {
+        state,
+        config: join(root, "config"),
+        logs: join(root, "logs"),
+        ca: join(state, "proxy", "ca.pem"),
+        caKey: join(state, "proxy", "ca-key.pem"),
+    };
+}
+/** A service's starting port, spread over the service range by `seed`. */
+function servicePort(seed) {
+    return SERVICE_PORT_BASE + (hash(seed) % SERVICE_PORTS);
+}
+/** The certificate for `localhost` that apps with no domain serve HTTPS with, and its key. */
+export function localhostCertificate(machine) {
+    const dir = join(machine.home, "tls");
+    return { cert: join(dir, "localhost.pem"), key: join(dir, "localhost-key.pem") };
+}
+/** FNV-1a: a stable spread of names over port blocks. */
+function hash(text) {
+    let h = 0x811c9dc5;
+    for (const byte of Buffer.from(text))
+        h = Math.imul(h ^ byte, 0x01000193) >>> 0;
+    return h;
+}

package/dist/mission-control/act.js

@@ -0,0 +1,91 @@
+import { spawn } from "node:child_process";
+/** How long a start waits for each daemon to listen or fail before it says how it went. */
+const START_WAIT_MS = 10_000;
+/** Does what the developer asked. Resolves to what to tell them; never rejects. */
+export async function perform(intent, hands) {
+    const { supervisor } = hands;
+    switch (intent.kind) {
+        case "add":
+        case "remove": {
+            // Its progress, and how it ended, the feed reads from its files.
+            const doing = intent.kind === "add" ? "Adding a worktree" : `Removing ${intent.suffix}`;
+            const what = intent.kind === "add" ? "add a worktree" : `remove ${intent.suffix}`;
+            return hands.worktrees(intent).then(() => `${doing}: it goes on if you close the view.`, (error) => `Could not ${what}: ${reason(error)}`);
+        }
+        case "open":
+            return hands.open(intent.url).then(() => `Opened ${intent.url} in the browser.`, (error) => `Could not open a browser (${reason(error)}). The URL: ${intent.url}`);
+        case "copy":
+            return hands.copy(intent.text).then((where) => `Copied ${intent.text} to ${where}.`, (error) => `Could not copy (${reason(error)}). It is: ${intent.text}`);
+    }
+    const { kind, namespace, apps, services, label } = intent;
+    const names = [...apps, ...services];
+    try {
+        if (kind === "stop") {
+            // Held first, as `basepad down` does, so no request starts an app again while it stops.
+            await supervisor.hold(namespace, apps);
+            await supervisor.stop(namespace, names);
+            return `Stopped ${label}.`;
+        }
+        if (kind === "restart")
+            await supervisor.stop(namespace, names);
+        const states = await supervisor.start(namespace, names, START_WAIT_MS, {});
+        const failed = names.filter((name) => states[name] === "failed");
+        if (failed.length > 0) {
+            const which = failed.length === 1 && failed[0] === label ? "it" : failed.join(", ");
+            return `${label} ${kind === "start" ? "started" : "restarted"}, but ${which} failed: its last lines are in the logs.`;
+        }
+        return `${kind === "start" ? "Started" : "Restarted"} ${label}.`;
+    }
+    catch (error) {
+        return `Could not ${kind} ${label}: ${reason(error)}`;
+    }
+}
+function reason(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The developer's own desktop: `open` on macOS, `xdg-open` on Linux; the clipboard through the
+ * platform's command, else through the terminal itself (OSC 52), which reaches the developer's
+ * clipboard over SSH too, in terminals that allow it.
+ */
+export function desktopHands(supervisor, worktrees, terminal) {
+    const mac = process.platform === "darwin";
+    const clipboards = mac
+        ? [["pbcopy", []]]
+        : [
+            ...(process.env.WAYLAND_DISPLAY ? [["wl-copy", []]] : []),
+            ...(process.env.DISPLAY
+                ? [
+                    ["xclip", ["-selection", "clipboard"]],
+                    ["xsel", ["--clipboard", "--input"]],
+                ]
+                : []),
+        ];
+    return {
+        supervisor,
+        worktrees,
+        async open(url) {
+            await runWith(mac ? "open" : "xdg-open", [url]);
+        },
+        async copy(text) {
+            for (const [command, args] of clipboards) {
+                const done = await runWith(command, args, text).then(() => true, () => false);
+                if (done)
+                    return "the clipboard";
+            }
+            terminal.write(`\u001b]52;c;${Buffer.from(text).toString("base64")}\u0007`);
+            return "the clipboard, through the terminal";
+        },
+    };
+}
+/** Runs a desktop command with `input` on its stdin. Rejects when it is missing or fails. */
+function runWith(command, args, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: [input === undefined ? "ignore" : "pipe", "ignore", "ignore"],
+        });
+        child.on("error", (error) => reject(new Error(error.code === "ENOENT" ? `${command} not found` : error.message)));
+        child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`${command} exited ${code}`)));
+        child.stdin?.end(input);
+    });
+}