basepad 0.0.0-stage → 0.0.0

package/dist/catalogue/redis.js

@@ -0,0 +1,135 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+import { z } from "zod";
+import { BasepadError, shellQuote } from "../internal/exec.js";
+import { freePort, waitFor } from "../internal/ports.js";
+import { recordRunning, runningPort } from "../internal/processes.js";
+import { install } from "../tools.js";
+import { REDIS_VERSION } from "../versions.js";
+/**
+ * A Redis of the environment's own: mise's Redis, on loopback only, kept in memory (nothing is
+ * saved), on a port derived from the environment's name. Each environment's server has a folder of
+ * its own in the service's folder, holding its pid and port while it runs.
+ */
+const HOST = "127.0.0.1";
+/** How long `up` waits for the server to answer before it gives up. */
+const READY_MS = 30_000;
+/**
+ * A Redis of the environment's own, in memory. `worktree` is what a worktree uses: its own empty
+ * Redis (`empty`, the default), or main's (`shared`).
+ */
+export function redis(options = {}) {
+    return { kind: "redis", worktree: options.worktree ?? "empty" };
+}
+/** The file in a server's folder naming the checkout it belongs to. */
+const OWNER = "owner";
+export const redisKind = {
+    schema: z.strictObject({
+        kind: z.literal("redis"),
+        worktree: z.enum(["empty", "shared"], {
+            error: "Redis `worktree` must be empty or shared",
+        }),
+    }),
+    perEnvironment(service) {
+        return service.worktree !== "shared";
+    },
+    names(service, { dir, suffix }) {
+        const worktrees = join(dir, "worktrees");
+        const own = suffix !== undefined && service.worktree !== "shared";
+        return { server: own ? join(worktrees, suffix) : join(dir, "main"), worktrees };
+    },
+    async prepare(_service, place) {
+        const redis = await install("redis", REDIS_VERSION, place.machine.home);
+        const { server } = place;
+        await mkdir(server, { recursive: true });
+        const port = (await runningPort(pidFile(server))) ?? (await freePort(place.port));
+        const argv = [
+            redis.bin("redis-server"),
+            "--port",
+            String(port),
+            "--bind",
+            HOST,
+            // In memory: nothing is saved, so a worktree's starts empty and none outlives its server.
+            "--save",
+            "",
+            "--appendonly",
+            "no",
+            "--dir",
+            server,
+        ];
+        return {
+            run: `${recordRunning(pidFile(server), port)} && exec ${argv.map(shellQuote).join(" ")}`,
+            dir: server,
+            listens: port,
+        };
+    },
+    async provision(_service, place, { started, stopped }) {
+        const outputs = (port) => ({ url: `redis://${HOST}:${port}`, host: HOST, port });
+        // Not started: where it will listen, which is where `prepare` put it.
+        if (!started)
+            return outputs((await runningPort(pidFile(place.server))) ?? (await freePort(place.port)));
+        const port = await waitFor(async () => {
+            const port = await runningPort(pidFile(place.server));
+            if (port === undefined)
+                throw new Error("It has not started.");
+            await ping(port);
+            return port;
+        }, `Redis for \`${place.key}\` didn't answer within ${READY_MS / 1000} s.`, READY_MS, stopped);
+        if (place.suffix !== undefined && place.server.startsWith(place.worktrees)) {
+            await writeFile(join(place.server, OWNER), place.owner);
+        }
+        return outputs(port);
+    },
+    worktreeData: {
+        async list(_service, place) {
+            if (!existsSync(place.worktrees))
+                return [];
+            const all = [];
+            for (const name of await readdir(place.worktrees)) {
+                const owner = await readFile(join(place.worktrees, name, OWNER), "utf8").catch(() => "");
+                all.push({ name, owner });
+            }
+            if (place.suffix === undefined)
+                return all;
+            return all.filter((data) => data.owner === place.owner || (data.owner === "" && data.name === place.suffix));
+        },
+        async drop(_service, place, names) {
+            for (const name of names) {
+                if (name === "" || name.includes("/") || name === "." || name === "..") {
+                    throw new BasepadError(`\`${name}\` is no worktree's Redis.`);
+                }
+                await rm(join(place.worktrees, name), { recursive: true, force: true });
+            }
+        },
+    },
+    async address(_service, place) {
+        return `redis://${HOST}:${(await runningPort(pidFile(place.server))) ?? place.port}`;
+    },
+};
+/** The file in a server's folder with its process id and port while it runs. */
+function pidFile(server) {
+    return join(server, "redis.pid");
+}
+/** Resolves once Redis on `port` answers PING with PONG. */
+function ping(port) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection({ host: HOST, port });
+        socket.setTimeout(2000);
+        let reply = "";
+        socket.on("connect", () => socket.write("PING\r\n"));
+        socket.on("data", (chunk) => {
+            reply += chunk.toString();
+            if (!reply.includes("\r\n"))
+                return;
+            socket.destroy();
+            if (reply.startsWith("+PONG"))
+                resolve();
+            else
+                reject(new Error(`Redis replied ${reply.trim()}`));
+        });
+        socket.on("timeout", () => socket.destroy(new Error("Redis didn't answer PING.")));
+        socket.on("error", reject);
+    });
+}

package/dist/catalogue.js

@@ -0,0 +1,13 @@
+import { mailpitKind } from "./catalogue/mailpit.js";
+import { postgresKind } from "./catalogue/postgres.js";
+import { redisKind } from "./catalogue/redis.js";
+/** Every kind, by the name its factory has in a config. */
+const CATALOGUE = { postgres: postgresKind, redis: redisKind, mailpit: mailpitKind };
+/** The kind that provides `service`. */
+export function kindOf(service) {
+    return CATALOGUE[service.kind];
+}
+/** Every kind's schema, for Config. */
+export const SCHEMAS = Object.values(CATALOGUE).map((kind) => kind.schema);
+/** Every kind's factory as a config calls it, for messages: `postgres()`. */
+export const FACTORIES = Object.keys(CATALOGUE).map((kind) => `\`${kind}()\``);

package/dist/claude-hooks.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { BasepadError } from "./internal/exec.js";
+/**
+ * Claude Code's worktree hooks (https://code.claude.com/docs/en/hooks#worktreecreate). A command
+ * hook gets the event as JSON on standard input, with the session's folder as `cwd`.
+ * `WorktreeCreate` adds the `name` asked for and must print the worktree's path as the last line of
+ * standard output; `WorktreeRemove` gets that path back as `worktree_path`.
+ */
+const INPUTS = {
+    WorktreeCreate: z.looseObject({ name: z.string().min(1), cwd: z.string().optional() }),
+    WorktreeRemove: z.looseObject({ worktree_path: z.string().min(1), cwd: z.string().optional() }),
+};
+/** Reads and checks the hook input for `event` from standard input. */
+export async function readHookInput(event) {
+    if (process.stdin.isTTY) {
+        throw new BasepadError(`\`--claude\` reads Claude Code's ${event} hook input on stdin.`);
+    }
+    let text = "";
+    for await (const chunk of process.stdin)
+        text += chunk;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new BasepadError(`\`--claude\` expects Claude Code's ${event} hook input, as JSON, on stdin.`);
+    }
+    const parsed = INPUTS[event].safeParse(raw);
+    if (!parsed.success) {
+        throw new BasepadError(`Claude Code's ${event} hook input is missing fields:\n${z.prettifyError(parsed.error)}`);
+    }
+    return parsed.data;
+}

package/dist/cli.js

@@ -0,0 +1,182 @@
+import { readFileSync } from "node:fs";
+import { COMMANDS } from "./commands.js";
+import { BasepadError } from "./internal/exec.js";
+/** Flags every command takes. */
+const HELP = { help: { short: "h", description: "Show this help" } };
+/** Flags `basepad` takes before a command. */
+const TOP_FLAGS = {
+    ...HELP,
+    version: { short: "v", description: "Show basepad's version" },
+};
+async function main(argv) {
+    const [first, ...rest] = argv;
+    if (first === undefined) {
+        process.stdout.write(topHelp());
+        return 1;
+    }
+    if (first.startsWith("-")) {
+        const { flags } = parseFlags([first, ...rest], TOP_FLAGS, "basepad");
+        if (flags.version) {
+            process.stdout.write(`${version()}\n`);
+            return 0;
+        }
+        process.stdout.write(topHelp());
+        return 0;
+    }
+    // A group (`db`) with no command, or asking for help, lists its commands.
+    const verbs = Object.entries(COMMANDS).filter(([key]) => key.startsWith(`${first} `));
+    if (verbs.length > 0 && (rest[0] === undefined || ["-h", "--help"].includes(rest[0]))) {
+        process.stdout.write(groupHelp(first, verbs));
+        return rest[0] === undefined ? 1 : 0;
+    }
+    // A command is one word, or two for a group's (`worktree add`).
+    const pair = rest[0] === undefined ? undefined : `${first} ${rest[0]}`;
+    const name = pair !== undefined && pair in COMMANDS ? pair : first;
+    const command = COMMANDS[name];
+    if (!command) {
+        const typed = verbs.length > 0 ? (pair ?? first) : first;
+        throw new BasepadError(`Unknown command \`${typed}\`. The nearest is \`${nearest(typed, Object.keys(COMMANDS))}\`; run \`basepad --help\` for every command.`);
+    }
+    const args = name === pair ? rest.slice(1) : rest;
+    const { flags, positional } = parseFlags(args, { ...command.flags, ...HELP }, `basepad ${name}`);
+    if (flags.help) {
+        process.stdout.write(commandHelp(name, command));
+        return 0;
+    }
+    const wanted = command.args ?? [];
+    const required = wanted.filter((arg) => !arg.endsWith("?")).length;
+    if (positional.length < required || positional.length > wanted.length) {
+        throw new BasepadError(wanted.length === 0
+            ? `\`basepad ${name}\` takes no arguments; got \`${positional[0]}\`.`
+            : `Usage: basepad ${name} ${usageArgs(wanted)}[flags]`);
+    }
+    await command.run({
+        cwd: process.cwd(),
+        flags,
+        args: positional,
+        print: (line) => console.log(line),
+    });
+    return 0;
+}
+/**
+ * Reads flags by long or short name: a switch, or a flag with a value, which takes the next
+ * argument. Other words are the positional arguments; any other flag is an error naming the
+ * nearest.
+ */
+function parseFlags(args, known, usage) {
+    const flags = {};
+    const positional = [];
+    const spellings = Object.entries(known).flatMap(([name, flag]) => [
+        [`--${name}`, name],
+        ...(flag.short ? [[`-${flag.short}`, name]] : []),
+    ]);
+    const byArg = new Map(spellings);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const name = byArg.get(arg);
+        const value = name === undefined ? undefined : known[name]?.value;
+        if (name !== undefined && value === undefined) {
+            flags[name] = true;
+            continue;
+        }
+        if (name !== undefined) {
+            const given = args[++i];
+            if (given === undefined || given.startsWith("-")) {
+                throw new BasepadError(`\`${arg}\` needs a ${value}: \`${usage} ${arg} <${value}>\`.`);
+            }
+            flags[name] = given;
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            positional.push(arg);
+            continue;
+        }
+        const near = nearest(arg, Object.keys(known).map((n) => `--${n}`));
+        throw new BasepadError(`\`${usage}\` has no flag \`${arg}\`. The nearest is \`${near}\`; run \`${usage} --help\` for its flags.`);
+    }
+    return { flags, positional };
+}
+/** The candidate with the fewest edits from `word`. */
+function nearest(word, candidates) {
+    let best = candidates[0] ?? "";
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const d = distance(word, candidate);
+        if (d < bestDistance)
+            [best, bestDistance] = [candidate, d];
+    }
+    return best;
+}
+/** Levenshtein distance. */
+function distance(a, b) {
+    let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const next = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            next[j] = Math.min((row[j] ?? 0) + 1, (next[j - 1] ?? 0) + 1, (row[j - 1] ?? 0) + cost);
+        }
+        row = next;
+    }
+    return row[b.length] ?? 0;
+}
+function topHelp() {
+    return [
+        "Usage: basepad <command> [flags]",
+        "",
+        "Commands:",
+        ...columns(Object.entries(COMMANDS).map(([name, command]) => [name, command.summary])),
+        "",
+        "Flags:",
+        ...flagLines(TOP_FLAGS),
+        "",
+        "Run `basepad <command> --help` for a command's flags.",
+        "",
+    ].join("\n");
+}
+function groupHelp(group, verbs) {
+    return [
+        `Usage: basepad ${group} <command> [flags]`,
+        "",
+        "Commands:",
+        ...columns(verbs.map(([name, command]) => [name, command.summary])),
+        "",
+        `Run \`basepad ${group} <command> --help\` for a command's flags.`,
+        "",
+    ].join("\n");
+}
+function commandHelp(name, command) {
+    return [
+        `Usage: basepad ${name} ${usageArgs(command.args ?? [])}[flags]`,
+        "",
+        `${command.summary}.`,
+        "",
+        "Flags:",
+        ...flagLines({ ...command.flags, ...HELP }),
+        "",
+    ].join("\n");
+}
+/** A command's arguments for its usage line: `<name> `, or `[<name>] ` for an optional one. */
+function usageArgs(args) {
+    return args.map((arg) => (arg.endsWith("?") ? `[<${arg.slice(0, -1)}>] ` : `<${arg}> `)).join("");
+}
+function flagLines(flags) {
+    return columns(Object.entries(flags).map(([name, flag]) => [
+        `${flag.short ? `-${flag.short}, --${name}` : `    --${name}`}${flag.value ? ` <${flag.value}>` : ""}`,
+        flag.description,
+    ]));
+}
+function columns(rows) {
+    const width = Math.max(...rows.map(([left]) => left.length));
+    return rows.map(([left, right]) => `  ${left.padEnd(width)}  ${right}`);
+}
+function version() {
+    const pkg = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    return JSON.parse(pkg).version;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(error instanceof BasepadError ? `basepad: ${error.message}` : error);
+    process.exitCode = 1;
+});