basepad 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aysnc Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/rocket.svg" width="220" alt="basepad's rocket on its launch pad">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">basepad</h1>
+
+<p align="center">
+  A local environment for coding agents.<br>
+  On your machine, or in a cloud sandbox.
+</p>
+
+---
+
+Tell basepad what your project runs:
+
+```ts
+// basepad.config.ts
+import { defineConfig, mailpit, postgres, redis } from "basepad";
+
+export default defineConfig({
+	name: "shop",
+	services: { db: postgres(), cache: redis(), mail: mailpit() },
+	apps: {
+		web: { run: "next dev" },
+		api: { run: "php artisan serve --port=$PORT" },
+	},
+	env: ({ db, cache, mail, web }) => ({
+		".env.local": {
+			DATABASE_URL: db.url,
+			REDIS_URL: cache.url,
+			MAIL_URL: mail.url,
+			APP_URL: web.url,
+		},
+	}),
+});
+```
+
+`basepad up` starts it. Every agent working in a worktree gets its own copy, with its own data and its own URLs:
+
+```
+https://web.shop.localhost              you, on main
+https://web.worktree-1.shop.localhost   the agent fixing checkout
+https://web.worktree-2.shop.localhost   the agent rewriting search
+```
+
+Mail it sends lands in a local inbox at `https://mail.shop.localhost`, and `basepad db save` snapshots its database before it tries something risky.
+
+## Try it
+
+```sh
+curl https://mise.run | sh                 # basepad installs everything else through mise
+npm install --save-dev basepad
+npx basepad init                           # writes a starter config
+npx basepad up
+```
+
+Run `npx basepad setup` once per machine and your browser will trust the local HTTPS domains. It's worth it for the rocket alone.
+
+Works on macOS (Apple Silicon) and Linux (x64 and ARM).
+
+## Commands
+
+| | |
+| --- | --- |
+| `basepad up` | Start everything and open mission control (`-d` skips it) |
+| `basepad down` | Stop everything. Data and env files stay put |
+| `basepad status` | Every app's URL and state |
+| `basepad worktree add` | A new branch with its own environment |
+| `basepad worktree rm <name>` | Throw one away. The branch survives |
+| `basepad db save`, `db load` | Snapshot this environment's database, and put it back |
+| `basepad setup` | Once per machine, for trusted URLs with no port |
+
+The [guide](docs/guide.md) has the rest: every config option, how worktrees copy data, the Claude Code hooks, CI and sandboxes, and every key in mission control.
+
+## Hacking on basepad
+
+```sh
+mise install && npm ci
+npm run check
+```
+
+The tests run the real thing against real mise, pitchfork and Postgres. [`AGENTS.md`](AGENTS.md) explains how to keep a test run away from your own setup.
+
+MIT licensed.

package/dist/catalogue/mailpit.js

@@ -0,0 +1,82 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { BasepadError, shellQuote } from "../internal/exec.js";
+import { answers, freePort, waitFor } from "../internal/ports.js";
+import { recordRunning, runningPort } from "../internal/processes.js";
+import { install } from "../tools.js";
+import { MAILPIT_VERSION } from "../versions.js";
+/**
+ * Mailpit: one inbox per project, which catches every message the project's environments send.
+ * Its inbox is its domain; its SMTP server is on loopback. Main and every worktree share it, and
+ * each sends as its own SMTP user, which Mailpit tags each message with. Its messages are kept in
+ * the service's folder, so they survive a restart.
+ */
+const HOST = "127.0.0.1";
+/** Mailpit accepts any password, but some mailers authenticate only with one. */
+const PASSWORD = "basepad";
+/** How long `up` waits for its SMTP server to answer before it gives up. */
+const READY_MS = 30_000;
+/**
+ * Catches all mail the project sends. Its inbox is at `https://<key>.<name>.localhost`; each
+ * message is tagged with the environment that sent it: `main`, or a worktree's suffix.
+ */
+export function mailpit() {
+    return { kind: "mailpit" };
+}
+export const mailpitKind = {
+    schema: z.strictObject({ kind: z.literal("mailpit") }),
+    web: true,
+    names(_service, { dir, suffix }) {
+        return { user: suffix ?? "main", data: join(dir, "mailpit.db"), pid: join(dir, "mailpit.pid") };
+    },
+    async prepare(_service, place) {
+        const bin = (await install("mailpit", MAILPIT_VERSION, place.machine.home)).bin("mailpit");
+        await mkdir(place.dir, { recursive: true });
+        const smtp = (await runningPort(place.pid)) ?? (await freePort(place.port));
+        const argv = [
+            bin,
+            "--smtp",
+            `${HOST}:${smtp}`,
+            "--database",
+            place.data,
+            // Any user and password, over plain SMTP on loopback: the user becomes the message's tag.
+            "--smtp-auth-accept-any",
+            "--smtp-auth-allow-insecure",
+            "--tags-username",
+            "--smtp-disable-rdns",
+            "--disable-version-check",
+        ];
+        return {
+            run: `${recordRunning(place.pid, smtp)} && exec ${argv.map(shellQuote).join(" ")} --listen "${HOST}:$PORT"`,
+            dir: place.dir,
+            port: webOf(place).port,
+        };
+    },
+    async provision(_service, place, { stopped }) {
+        const port = await waitFor(async () => {
+            const port = await runningPort(place.pid);
+            if (port === undefined)
+                throw new Error("It has not started.");
+            if (!(await answers(port, [HOST])))
+                throw new Error(`Nothing answers on port ${port}.`);
+            return port;
+        }, `Mailpit for \`${place.key}\` didn't answer within ${READY_MS / 1000} s.`, READY_MS, stopped);
+        return {
+            url: `smtp://${place.user}:${PASSWORD}@${HOST}:${port}`,
+            host: HOST,
+            port,
+            user: place.user,
+            password: PASSWORD,
+            inbox: webOf(place).url,
+        };
+    },
+    async address(_service, place) {
+        return webOf(place).url;
+    },
+};
+function webOf(place) {
+    if (place.web === undefined)
+        throw new BasepadError(`\`${place.key}\` has no domain.`);
+    return place.web;
+}