slicetest 0.4.0 → 0.6.0

package/dist/init.js

@@ -1,22 +1,84 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { parse, stringify } from "yaml";
 const TODO_COMMAND = "echo 'TODO: the command that starts your app' && exit 1";
+/** SDKs whose API hosts are written into them: a stub with `hosts` answers there. Packages are npm or PyPI names. */
+const KNOWN_APIS = [
+    { packages: ["stripe"], stub: "stripe", hosts: ["api.stripe.com"], env: { STRIPE_SECRET_KEY: "sk_test_slicetest", STRIPE_WEBHOOK_SECRET: "whsec_slicetest" } },
+    { packages: ["@anthropic-ai/sdk", "anthropic"], stub: "anthropic", hosts: ["api.anthropic.com"], env: { ANTHROPIC_API_KEY: "sk-ant-slicetest" } },
+    { packages: ["openai"], stub: "openai", hosts: ["api.openai.com"], env: { OPENAI_API_KEY: "sk-slicetest" } },
+    { packages: ["resend"], stub: "resend", hosts: ["api.resend.com"], env: { RESEND_API_KEY: "re_slicetest" } },
+    { packages: ["@sendgrid/mail", "sendgrid"], stub: "sendgrid", hosts: ["api.sendgrid.com"], env: { SENDGRID_API_KEY: "SG.slicetest" } },
+    { packages: ["@slack/web-api", "slack_sdk"], stub: "slack", hosts: ["slack.com"], env: { SLACK_BOT_TOKEN: "xoxb-slicetest" } },
+    { packages: ["@octokit/rest", "octokit", "PyGithub"], stub: "github", hosts: ["api.github.com"], env: { GITHUB_TOKEN: "ghp_slicetest" } },
+    { packages: ["twilio"], stub: "twilio", hosts: ["api.twilio.com"], env: { TWILIO_ACCOUNT_SID: "AC00000000000000000000000000000000", TWILIO_AUTH_TOKEN: "slicetest" } },
+];
+/** Files that mark a directory as an app slicetest can start. */
+const APP_MARKERS = ["manage.py", "requirements.txt", "pyproject.toml", "Gemfile", "go.mod", "Cargo.toml", "build.gradle", "build.gradle.kts", "pom.xml"];
+/** Build files of a Gradle or Maven multi-project build (two levels down), for dependencies declared in a subproject. */
+async function subprojectBuildFiles(dir, gradle) {
+    const names = gradle ? ["build.gradle", "build.gradle.kts"] : ["pom.xml"];
+    const texts = [];
+    const walk = async (d, depth) => {
+        if (depth > 2)
+            return;
+        for (const entry of await readdir(d, { withFileTypes: true }).catch(() => [])) {
+            if (!entry.isDirectory() || entry.name.startsWith(".") || ["build", "target", "node_modules", "src", "gradle"].includes(entry.name))
+                continue;
+            const sub = path.join(d, entry.name);
+            for (const n of names)
+                if (existsSync(path.join(sub, n)))
+                    texts.push(await readFile(path.join(sub, n), "utf8"));
+            await walk(sub, depth + 1);
+        }
+    };
+    await walk(dir, 1);
+    return texts;
+}
+/** Where monorepos usually keep the server, when the root isn't one. */
+const APP_DIRS = ["backend", "server", "api", "app", "service"];
+function runnable(dir) {
+    if (APP_MARKERS.some((f) => existsSync(path.join(dir, f))))
+        return true;
+    try {
+        const scripts = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8")).scripts ?? {};
+        return !!(scripts.start || scripts.dev);
+    }
+    catch {
+        return false;
+    }
+}
 export async function detect(root) {
     const notes = [];
-    const has = (p) => existsSync(path.join(root, p));
-    const read = async (p) => (has(p) ? readFile(path.join(root, p), "utf8") : "");
+    // The app may live in a subdirectory (backend/, server/, …); everything about the app is read there.
+    const appDir = runnable(root) ? "" : (APP_DIRS.find((d) => runnable(path.join(root, d))) ?? "");
+    if (appDir)
+        notes.push(`app: in ${appDir}/ (app.cwd); commands for it run there`);
+    const appRoot = path.join(root, appDir);
+    const has = (p) => existsSync(path.join(appRoot, p));
+    const read = async (p) => (has(p) ? readFile(path.join(appRoot, p), "utf8") : "");
     const pkg = has("package.json") ? JSON.parse(await read("package.json")) : undefined;
     const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
     const python = `${await read("requirements.txt")}\n${await read("pyproject.toml")}`.toLowerCase();
     const gemfile = await read("Gemfile");
     // --- app ---
     let command = TODO_COMMAND;
+    let jvmBuild;
+    let build;
+    let readyPath = "/";
+    let scope;
+    let workers;
+    let readyTimeout;
     const env = { PORT: "{{app.port}}", DATABASE_URL: "{{db.url}}" };
     if (pkg?.scripts?.start) {
         command = "npm start";
         notes.push("app: `npm start` (package.json start script). It must listen on $PORT.");
+        if (pkg.scripts.build) {
+            // Otherwise `next start` and the like serve whatever was built last, and scenarios pass against stale code.
+            build = "npm run build";
+            notes.push("app: `npm run build` once per run, before starting (package.json build script).");
+        }
     }
     else if (pkg?.scripts?.dev) {
         command = "npm run dev";
@@ -38,6 +100,41 @@ export async function detect(root) {
         command = "bin/rails server -p {{app.port}}";
         notes.push("app: Rails");
     }
+    else if (has("build.gradle") || has("build.gradle.kts") || has("pom.xml")) {
+        const gradle = !has("pom.xml");
+        const buildFile = await read(gradle ? (has("build.gradle.kts") ? "build.gradle.kts" : "build.gradle") : "pom.xml");
+        jvmBuild = [buildFile, ...(await subprojectBuildFiles(appRoot, gradle))].join("\n");
+        const wrapper = gradle ? (process.platform === "win32" ? "gradlew.bat" : "./gradlew") : process.platform === "win32" ? "mvnw.cmd" : "./mvnw";
+        const tool = has(gradle ? "gradlew" : "mvnw") ? wrapper : gradle ? "gradle" : "mvn";
+        if (/spring-boot|org\.springframework\.boot/.test(buildFile)) {
+            // Built once up front: bootRun / spring-boot:run in several workers would otherwise all compile
+            // changed sources at the same moment, and download missing dependencies while the app runs
+            // with slicetest's proxy settings (which `offline` refuses). bootJar / package resolve them all.
+            build = gradle ? `${tool} bootJar -q` : `${tool} -q package -DskipTests`;
+            command = gradle ? `${tool} bootRun -q` : `${tool} -q spring-boot:run`;
+            // Spring reads these variables (relaxed binding).
+            delete env.PORT;
+            delete env.DATABASE_URL;
+            Object.assign(env, {
+                SERVER_PORT: "{{app.port}}",
+                SPRING_DATASOURCE_URL: "{{db.jdbcUrl}}",
+                SPRING_DATASOURCE_USERNAME: "{{db.user}}",
+                SPRING_DATASOURCE_PASSWORD: "{{db.password}}",
+            });
+            readyTimeout = 120_000;
+            // A JVM takes seconds to start: start it once per worker, and only in a couple of workers.
+            scope = "worker";
+            workers = 2;
+            if (/actuator/.test(buildFile) || (await subprojectBuildFiles(appRoot, gradle)).some((t) => /actuator/.test(t)))
+                readyPath = "/actuator/health";
+            notes.push(`app: Spring Boot (${gradle ? "Gradle" : "Maven"}). SERVER_PORT and SPRING_DATASOURCE_* override application.yml; {{db.jdbcUrl}} is the JDBC URL`);
+            notes.push("app: started once per worker (scope: worker) in 2 workers (workers: 2), since the JVM takes seconds to start");
+        }
+        else {
+            command = gradle ? `${tool} run -q` : `${tool} -q exec:java`;
+            notes.push(`app: ${gradle ? "Gradle" : "Maven"} project. Check the command; the app must listen on the port in {{app.port}}`);
+        }
+    }
     else if (has("go.mod")) {
         command = "go run .";
         notes.push("app: Go (go.mod). It must listen on $PORT.");
@@ -51,10 +148,11 @@ export async function detect(root) {
     }
     // --- migrations ---
     let migrate;
-    const migrationsSql = has("migrations") && (await readdir(path.join(root, "migrations"))).some((f) => f.endsWith(".sql"));
-    if (has("atlas.hcl") || has("migrations/atlas.sum")) {
-        migrate = { atlas: { dir: "file://migrations" } };
-        notes.push("db: Atlas migrations in migrations/");
+    const migrationsSql = has("migrations") && (await readdir(path.join(appRoot, "migrations"))).some((f) => f.endsWith(".sql"));
+    const atlas = await findAtlas(root, appDir);
+    if (atlas) {
+        migrate = { atlas: { dir: `file://${atlas}` } };
+        notes.push(`db: Atlas migrations in ${atlas}/`);
     }
     else if (has("prisma/schema.prisma")) {
         migrate = { command: "npx prisma migrate deploy", inputs: ["prisma/migrations"] };
@@ -74,8 +172,14 @@ export async function detect(root) {
         notes.push("db: Rails migrations");
     }
     else if (deps["drizzle-kit"]) {
-        migrate = { command: "npx drizzle-kit migrate", inputs: ["drizzle"] };
-        notes.push("db: Drizzle (drizzle-kit migrate). Check that `inputs` points at your migrations folder.");
+        // drizzle-kit migrate/push connect with whatever driver the project has (with only Neon's,
+        // over a WebSocket that a local server doesn't answer); the generated SQL needs no driver.
+        const configFile = ["drizzle.config.ts", "drizzle.config.js", "drizzle.config.mjs", "drizzle.config.json"].find(has);
+        const out = (configFile && /\bout\s*:\s*["'`]([^"'`]+)["'`]/.exec(await read(configFile))?.[1]?.replace(/^\.\//, "")) || "drizzle";
+        migrate = { sql: out };
+        notes.push(has(out)
+            ? `db: Drizzle migrations in ${out}/, applied as SQL in name order`
+            : `db: Drizzle, migrations expected in ${out}/ (drizzle.config's out), which doesn't exist yet: run \`npx drizzle-kit generate\` and commit them`);
     }
     else if (deps.knex) {
         migrate = { command: "npx knex migrate:latest", inputs: ["migrations"] };
@@ -92,22 +196,59 @@ export async function detect(root) {
     else {
         notes.push("db: no migrations found; the database starts empty. Set db.migrate.");
     }
+    // Migrations found in the app's directory: their paths are relative to it, and commands run there.
+    if (appDir && migrate && !("atlas" in migrate)) {
+        if ("sql" in migrate)
+            migrate = { sql: path.posix.join(appDir, migrate.sql) };
+        else
+            migrate = { command: `cd ${appDir} && ${migrate.command}`, ...(migrate.inputs ? { inputs: migrate.inputs.map((i) => path.posix.join(appDir, i)) } : {}) };
+    }
     // --- docker compose: the database image and other dependencies ---
-    const { db: composeDb, containers, appEnv, mail: composeMail } = await fromCompose(root, notes);
+    const { db: composeDb, containers, appEnv, mail: composeMail } = await fromCompose(root, notes, [...new Set(["", appDir])]);
     Object.assign(env, appEnv);
     let mail = composeMail;
-    if (!mail && (deps.nodemailer || /\b(flask-mail|fastapi-mail|django-anymail)\b/.test(python) || (has("manage.py") && /EMAIL_HOST/.test(await read(await djangoSettings(root)))))) {
+    if (!mail && (deps.nodemailer || /\b(flask-mail|fastapi-mail|django-anymail)\b/.test(python) || (has("manage.py") && /EMAIL_HOST/.test(await read(await djangoSettings(appRoot)))))) {
         mail = true;
         Object.assign(env, { SMTP_HOST: "{{mail.host}}", SMTP_PORT: "{{mail.port}}" });
         notes.push("mail: the app sends mail; slicetest catches it over SMTP (SMTP_HOST / SMTP_PORT, rename them to what your app reads)");
     }
-    const sqlite = await detectSqlite(root, read, deps, python, gemfile);
+    const sqlite = await detectSqlite(appRoot, read, deps, python, gemfile);
     if (sqlite && !composeDb.engine) {
         composeDb.engine = "sqlite";
         env.DATABASE_URL = sqlite.url;
         notes.push(`db: SQLite (${sqlite.why}), no container needed. The app gets DATABASE_URL=${sqlite.url}; {{db.path}} is the plain file path`);
     }
-    const stubs = await stubsFromEnvExample(root, read, env, notes);
+    let authClerk = false;
+    const auth = await authFromEnvExample(appRoot, read, env, notes);
+    const jwtDeps = ["jose", "jsonwebtoken", "passport-jwt", "express-oauth2-jwt-bearer", "express-jwt", "jwks-rsa", "@fastify/jwt", "next-auth"].filter((d) => deps[d]);
+    const jwtPython = /\b(pyjwt|python-jose|authlib|fastapi-azure-auth|djangorestframework-simplejwt)\b/i.exec(python)?.[1];
+    if (!auth && (jwtDeps.length || jwtPython)) {
+        notes.push(`auth: ${jwtDeps[0] ?? jwtPython} is a dependency, so the app may verify JWTs. To test with real tokens, add \`auth: true\` and pass {{auth.issuer}} / {{auth.jwks}} / {{auth.audience}} to the variables the app reads`);
+    }
+    const stubs = await stubsFromEnvExample(appRoot, read, env, notes);
+    const envExample = [".env.example", ".env.sample", ".env.template", ".env.dist"].map((f) => (has(f) ? f : "")).find(Boolean);
+    const exampleText = envExample ? await read(envExample) : "";
+    for (const api of KNOWN_APIS) {
+        if (!api.packages.some((p) => deps[p] || new RegExp(`\\b${p.replace(/[^\w-]/g, "")}\\b`).test(python)))
+            continue;
+        if (stubs.some((s) => (typeof s === "string" ? s : s.name) === api.stub))
+            continue;
+        stubs.push({ name: api.stub, hosts: api.hosts });
+        // Placeholder credentials for the variables the app is documented to read; the stub doesn't check them.
+        for (const [k, v] of Object.entries(api.env))
+            if (!(k in env) && new RegExp(`^\\s*${k}\\s*=`, "m").test(exampleText))
+                env[k] = v;
+        notes.push(`stubs.${api.stub}: ${api.packages.find((p) => deps[p]) ?? api.packages[0]} calls ${api.hosts.join(", ")}; the stub answers there (register its routes in scenarios)`);
+    }
+    if (deps["@clerk/nextjs"] || deps["@clerk/express"] || deps["@clerk/backend"]) {
+        // A publishable key is the Frontend API host, base64-encoded with a trailing "$".
+        env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY ??= `pk_test_${Buffer.from("clerk.slicetest.test$").toString("base64")}`;
+        env.CLERK_SECRET_KEY ??= "sk_test_slicetest";
+        authClerk = true;
+        stubs.push({ name: "clerk", hosts: ["api.clerk.com", "clerk.slicetest.test"] });
+        notes.push("auth: Clerk. Sessions are tokens from slicetest's issuer (auth: true); the clerk stub serves its keys at /v1/jwks and users at /v1/users/:id. See the README's Clerk section");
+    }
+    notes.push("network: URLs written in the code (https://api.example.com) can be stubbed with `hosts`. Add `offline: true` and the first run names every host the app calls");
     const mysqlDeps = !!deps.mysql2 || !!deps.mysql || /\b(pymysql|mysqlclient|aiomysql)\b/.test(python) || /\bgem ['"]mysql2['"]/.test(gemfile);
     if (!composeDb.engine && mysqlDeps) {
         composeDb.engine = "mysql";
@@ -117,11 +258,31 @@ export async function detect(root) {
     const openapi = ["openapi.yaml", "openapi.yml", "openapi.json", "docs/openapi.yaml", "docs/openapi.yml", "docs/openapi.json"].find(has);
     if (openapi)
         notes.push(`openapi: ${openapi}. Every response will be checked against it.`);
+    const neon = !!(deps["@neondatabase/serverless"] || deps["@vercel/postgres"]);
+    if (neon)
+        notes.push("db: Neon's serverless driver (db.neon): DATABASE_URL is a Neon-style URL whose HTTP queries slicetest answers from the test database");
+    // An app with no migrations, no database in compose and no database library gets no database at all.
+    const dbLibrary = Object.keys(deps).some((d) => /^(pg|postgres|mysql2?|@prisma\/client|prisma|drizzle-orm|knex|typeorm|sequelize|kysely|better-sqlite3|sqlite3|@neondatabase\/serverless|@vercel\/postgres|@libsql\/client|mongoose|mongodb)$/.test(d)) ||
+        /data-jpa|data-jdbc|spring-jdbc|r2dbc|postgresql|mysql|flyway|liquibase|hibernate/.test(jvmBuild ?? "") ||
+        /\b(psycopg|sqlalchemy|asyncpg|pymysql|mysqlclient|django|peewee|tortoise|sqlmodel)\b/.test(python) ||
+        /\b(rails|activerecord|sequel|pg|mysql2|sqlite3)\b/.test(gemfile);
+    const knownStack = !!pkg || jvmBuild !== undefined || python.trim().length > 0 || gemfile.length > 0;
+    const noDb = knownStack && !dbLibrary && !migrate && !composeDb.engine && !composeDb.image && !has("manage.py");
+    if (noDb) {
+        for (const k of ["DATABASE_URL", "SPRING_DATASOURCE_URL", "SPRING_DATASOURCE_USERNAME", "SPRING_DATASOURCE_PASSWORD"])
+            delete env[k];
+        const i = notes.indexOf("db: no migrations found; the database starts empty. Set db.migrate.");
+        if (i >= 0)
+            notes.splice(i, 1);
+        notes.push("db: none (no migrations, no database in compose, no database library), so `db: false`: no container is started");
+    }
     const config = {
-        app: { command, env, ready: { path: "/" } },
-        ...(migrate || Object.keys(composeDb).length ? { db: { ...composeDb, ...(migrate ? { migrate } : {}) } } : {}),
+        app: { ...(appDir ? { cwd: appDir } : {}), command, ...(build ? { build } : {}), env, ready: { path: readyPath }, ...(readyTimeout ? { readyTimeout } : {}), ...(scope ? { scope } : {}) },
+        ...(workers ? { workers } : {}),
+        ...(noDb ? { db: false } : migrate || neon || Object.keys(composeDb).length ? { db: { ...composeDb, ...(neon ? { neon: true } : {}), ...(migrate ? { migrate } : {}) } } : {}),
         ...(Object.keys(containers).length ? { containers } : {}),
         ...(mail ? { mail: true } : {}),
+        ...(auth || authClerk ? { auth: true } : {}),
         stubs,
         ...(openapi ? { openapi } : {}),
     };
@@ -150,6 +311,42 @@ async function detectSqlite(root, read, deps, python, gemfile) {
         return { why: "a SQLite driver is a dependency", url: "{{db.url}}" };
     return undefined;
 }
+/** Variables that tell the app which token issuer to trust, and what slicetest passes instead. */
+const AUTH_VARS = [
+    [/JWKS(_URL|_URI|_ENDPOINT)?$/, "{{auth.jwks}}"],
+    [/(ISSUER|ISSUER_URL|ISSUER_BASE_URL|AUTHORITY)$/, "{{auth.issuer}}"],
+    [/^(AUTH0|OKTA|KEYCLOAK|COGNITO|OIDC|OAUTH2?|AUTH|JWT)_?(DOMAIN|URL|BASE_URL)$/, "{{auth.issuer}}"],
+    [/(AUDIENCE|_AUD)$/, "{{auth.audience}}"],
+];
+/**
+ * `.env.example` variables naming a token issuer (`OIDC_ISSUER`, `AUTH0_DOMAIN`,
+ * `JWKS_URL`, `JWT_AUDIENCE`) turn on `auth`, with the variables pointed at
+ * slicetest's issuer. Returns whether any was found.
+ */
+async function authFromEnvExample(root, read, env, notes) {
+    const file = [".env.example", ".env.sample", ".env.template", ".env.dist"].find((f) => existsSync(path.join(root, f)));
+    if (!file)
+        return false;
+    const found = [];
+    for (const line of (await read(file)).split(/\r?\n/)) {
+        const name = /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/.exec(line)?.[1];
+        if (!name || name in env)
+            continue;
+        const match = AUTH_VARS.find(([re]) => re.test(name));
+        // AUDIENCE alone doesn't say the app verifies tokens; it comes along with an issuer or JWKS.
+        if (!match)
+            continue;
+        env[name] = match[1];
+        found.push(name);
+    }
+    if (!found.some((n) => env[n] !== "{{auth.audience}}")) {
+        for (const n of found)
+            delete env[n];
+        return false;
+    }
+    notes.push(`auth: ${found.join(", ")} in ${file} point at slicetest's OpenID issuer; scenarios mint tokens with auth.token({ sub, ... }) or \`auth:\` on a YAML request. An issuer the app expects as a bare domain (Auth0) may need the variable reshaped`);
+    return true;
+}
 /** Hosts that are never third-party APIs to stub. */
 const LOCAL_HOST = /^(localhost|127\.|0\.0\.0\.0|\[::1\]|host\.docker\.internal|[\w-]+$)/;
 /**
@@ -164,7 +361,7 @@ async function stubsFromEnvExample(root, read, env, notes) {
     const stubs = [];
     for (const line of (await read(file)).split(/\r?\n/)) {
         const m = /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*["']?(https?:\/\/[^\s"'#]+)/.exec(line);
-        if (!m || !/(URL|URI|ENDPOINT|HOST|BASE)$/.test(m[1]) || /DATABASE|REDIS|MONGO|AMQP|SMTP|MAIL|CALLBACK|REDIRECT|FRONTEND|PUBLIC|APP_URL|SITE_URL|WEBHOOK_URL$/.test(m[1]))
+        if (!m || m[1] in env || !/(URL|URI|ENDPOINT|HOST|BASE)$/.test(m[1]) || /DATABASE|REDIS|MONGO|AMQP|SMTP|MAIL|CALLBACK|REDIRECT|FRONTEND|PUBLIC|APP_URL|SITE_URL|WEBHOOK_URL$/.test(m[1]))
             continue;
         const url = new URL(m[2]);
         if (LOCAL_HOST.test(url.hostname))
@@ -179,14 +376,17 @@ async function stubsFromEnvExample(root, read, env, notes) {
     }
     return stubs;
 }
-const SCENARIO = `# yaml-language-server: $schema=https://unpkg.com/slicetest/schema/scenario.schema.json
+/**
+ * A first scenario against the path the app is checked for readiness on. At `/` an API often
+ * answers 404, so there it only checks that the app answers (and doesn't crash).
+ */
+const scenario = (readyPath) => `# yaml-language-server: $schema=https://unpkg.com/slicetest/schema/scenario.schema.json
 # A first scenario. Run it with: npx slicetest
 scenarios:
   - name: the app answers
     steps:
-      - request: GET /
-        expect: { status: 200 }
-`;
+      - request: GET ${readyPath}
+${readyPath === "/" ? "        # expect: { status: 200 }   (what should / answer? An API often has no page there)\n" : "        expect: { status: 200 }\n"}`;
 export async function init(root, { force = false } = {}) {
     const configFile = path.join(root, "slicetest.config.yaml");
     const scenarioFile = path.join(root, "scenarios", "smoke.scenario.yaml");
@@ -204,10 +404,31 @@ export async function init(root, { force = false } = {}) {
     ].join("\n");
     await writeFile(configFile, `${header}${stringify(config)}`);
     await mkdir(path.dirname(scenarioFile), { recursive: true });
-    await writeFile(scenarioFile, SCENARIO);
+    await writeFile(scenarioFile, scenario(config.app.ready?.path ?? "/"));
     return { files: [configFile, scenarioFile].map((f) => path.relative(root, f)), notes };
 }
-const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yml", "docker-compose.yaml"];
+const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yml", "docker-compose.yaml", "podman-compose.yml", "podman-compose.yaml"];
+/**
+ * The Atlas migrations directory, relative to the project root: from an atlas.hcl's
+ * `dir = "file://..."` (in the root, the app's directory or atlas/, db/), else a
+ * migrations/ folder with an atlas.sum.
+ */
+async function findAtlas(root, appDir) {
+    for (const dir of [...new Set(["", appDir, "atlas", "db", "database"])]) {
+        const hcl = path.join(root, dir, "atlas.hcl");
+        if (!existsSync(hcl))
+            continue;
+        const found = /\bdir\s*=\s*"file:\/\/([^"]+)"/.exec(await readFile(hcl, "utf8"))?.[1];
+        const rel = path.posix.join(dir.replace(/\\/g, "/"), (found ?? "migrations").replace(/^\.\//, ""));
+        if (existsSync(path.join(root, rel)))
+            return rel;
+    }
+    for (const dir of [...new Set(["migrations", path.posix.join(appDir, "migrations")])]) {
+        if (existsSync(path.join(root, dir, "atlas.sum")))
+            return dir;
+    }
+    return undefined;
+}
 /** Development mail servers; `mail: true` does their job in-process. */
 const MAIL_CATCHERS = /(^|\/)(mailpit|mailhog|maildev|smtp4dev|greenmail[\w-]*|mailcatcher|inbucket)(:|$)/;
 /** Known images: the port they listen on, how to empty them, and the variable apps usually read. */
@@ -229,12 +450,12 @@ const KNOWN = [
  * Reads docker compose: a postgres / mysql service sets the database engine
  * and image; Redis, Mongo, MinIO and other images become `containers`.
  */
-async function fromCompose(root, notes) {
+async function fromCompose(root, notes, dirs = [""]) {
     const db = {};
     const containers = {};
     const appEnv = {};
     let mail = false;
-    const file = COMPOSE_FILES.find((f) => existsSync(path.join(root, f)));
+    const file = dirs.flatMap((d) => COMPOSE_FILES.map((f) => path.join(d, f))).find((f) => existsSync(path.join(root, f)));
     if (!file)
         return { db, containers, appEnv, mail };
     let doc;

package/dist/intercept.d.ts

@@ -0,0 +1,37 @@
+import net from "node:net";
+/** Where an intercepted host's calls go: its stub's server (TLS connections) and port (plain HTTP). */
+export interface Route {
+    attach: (socket: net.Socket) => void;
+    port: number;
+}
+/**
+ * The entry of `map` for `host`: an exact name, else the closest `*.domain` pattern
+ * (which covers every subdomain, at any depth, but not the domain itself).
+ */
+export declare function lookupHost<T>(map: ReadonlyMap<string, T>, host: string): T | undefined;
+export declare class Interceptor {
+    #private;
+    readonly routes: ReadonlyMap<string, Route>;
+    readonly files: {
+        dir: string;
+        ca: string;
+        bundle: string;
+        trustStore: string;
+    };
+    /** Hosts the app reached that no stub intercepts, in the order first seen. */
+    readonly passedThrough: Set<string>;
+    /** With `offline`, hosts the app tried to reach and was refused. */
+    readonly blocked: Set<string>;
+    /** Refuse hosts no stub intercepts instead of passing calls through. */
+    offline: boolean;
+    private constructor();
+    get url(): string;
+    /** `routes` maps lower-case host names to the stub that answers for them. */
+    static start(routes: ReadonlyMap<string, Route>): Promise<Interceptor>;
+    /**
+     * The environment that sends a process's outbound HTTP(S) through the proxy and
+     * makes it trust the CA. Calls to localhost (the stubs' own URLs, the database) bypass it.
+     */
+    env(base?: NodeJS.ProcessEnv): Record<string, string>;
+    close(): Promise<void>;
+}

package/dist/intercept.js

@@ -0,0 +1,199 @@
+/**
+ * Catching calls to hosts the app has hard-coded (`https://api.github.com`), so
+ * stubs can answer them without the app reading a base URL from its environment.
+ *
+ * The app is started with the usual proxy variables pointing at this proxy and a
+ * throwaway CA in the trust settings each runtime reads (Node, Python, Ruby, Go,
+ * curl, the JVM). For an intercepted host the proxy terminates TLS with a
+ * certificate from that CA and hands the connection to the stub's HTTP server;
+ * every other host is tunnelled through untouched.
+ */
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import http from "node:http";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import tls from "node:tls";
+import { fileURLToPath } from "node:url";
+import { Authority, pemBundle, pemToDer, pkcs12TrustStore } from "./x509.js";
+let authority;
+/** preload/node-proxy.cjs, from src/ and dist/ alike. */
+const PRELOAD = fileURLToPath(new URL("../preload/node-proxy.cjs", import.meta.url));
+/**
+ * The entry of `map` for `host`: an exact name, else the closest `*.domain` pattern
+ * (which covers every subdomain, at any depth, but not the domain itself).
+ */
+export function lookupHost(map, host) {
+    host = host.toLowerCase();
+    const exact = map.get(host);
+    if (exact !== undefined)
+        return exact;
+    for (let i = host.indexOf("."); i >= 0; i = host.indexOf(".", i + 1)) {
+        const wildcard = map.get(`*${host.slice(i)}`);
+        if (wildcard !== undefined)
+            return wildcard;
+    }
+    return undefined;
+}
+export class Interceptor {
+    routes;
+    files;
+    /** Hosts the app reached that no stub intercepts, in the order first seen. */
+    passedThrough = new Set();
+    /** With `offline`, hosts the app tried to reach and was refused. */
+    blocked = new Set();
+    /** Refuse hosts no stub intercepts instead of passing calls through. */
+    offline = false;
+    #server;
+    #sockets = new Set();
+    #contexts = new Map();
+    constructor(server, routes, files) {
+        this.routes = routes;
+        this.files = files;
+        this.#server = server;
+    }
+    get url() {
+        return `http://127.0.0.1:${this.#server.address().port}`;
+    }
+    /** `routes` maps lower-case host names to the stub that answers for them. */
+    static async start(routes) {
+        authority ??= new Authority();
+        const dir = await mkdtemp(path.join(os.tmpdir(), "slicetest-intercept-"));
+        const files = { dir, ca: path.join(dir, "ca.pem"), bundle: path.join(dir, "ca-bundle.pem"), trustStore: path.join(dir, "truststore.p12") };
+        await writeFile(files.ca, authority.pem);
+        await writeFile(files.bundle, pemBundle(tls.rootCertificates, authority.pem));
+        const roots = tls.rootCertificates.flatMap((pem, i) => {
+            const der = pemToDer(pem);
+            return der ? [{ alias: `root-${i}`, der }] : [];
+        });
+        await writeFile(files.trustStore, pkcs12TrustStore([{ alias: "slicetest-ca", der: authority.der }, ...roots]));
+        const server = http.createServer();
+        const interceptor = new Interceptor(server, routes, files);
+        server.on("request", (req, res) => interceptor.#plain(req, res));
+        server.on("connect", (req, socket, head) => interceptor.#tunnel(req, socket, head));
+        server.on("connection", (s) => {
+            interceptor.#sockets.add(s);
+            s.on("close", () => interceptor.#sockets.delete(s));
+        });
+        await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+        return interceptor;
+    }
+    /**
+     * The environment that sends a process's outbound HTTP(S) through the proxy and
+     * makes it trust the CA. Calls to localhost (the stubs' own URLs, the database) bypass it.
+     */
+    env(base = process.env) {
+        const { port } = new URL(this.url);
+        const local = "localhost,127.0.0.1,::1";
+        const quote = (s) => (/\s/.test(s) ? `"${s}"` : s);
+        const java = [
+            `-Dhttp.proxyHost=127.0.0.1`,
+            `-Dhttp.proxyPort=${port}`,
+            `-Dhttps.proxyHost=127.0.0.1`,
+            `-Dhttps.proxyPort=${port}`,
+            `-Dhttp.nonProxyHosts=localhost|127.0.0.1|[::1]`,
+            quote(`-Djavax.net.ssl.trustStore=${this.files.trustStore}`),
+            `-Djavax.net.ssl.trustStoreType=PKCS12`,
+        ];
+        return {
+            HTTP_PROXY: this.url,
+            HTTPS_PROXY: this.url,
+            http_proxy: this.url,
+            https_proxy: this.url,
+            NO_PROXY: local,
+            no_proxy: local,
+            // Node 22.21+ / 24.5+ honour the proxy variables for fetch and the default agents with this set;
+            // the preload extends that to agents libraries make themselves.
+            NODE_USE_ENV_PROXY: "1",
+            NODE_OPTIONS: [base.NODE_OPTIONS, `--require ${quote(PRELOAD)}`].filter(Boolean).join(" "),
+            NODE_EXTRA_CA_CERTS: this.files.ca,
+            // OpenSSL-based runtimes (Python, Ruby, PHP), Go, requests and curl replace their
+            // default roots with these files, so the bundle also holds the public roots.
+            SSL_CERT_FILE: this.files.bundle,
+            REQUESTS_CA_BUNDLE: this.files.bundle,
+            CURL_CA_BUNDLE: this.files.bundle,
+            JAVA_TOOL_OPTIONS: [base.JAVA_TOOL_OPTIONS, ...java].filter(Boolean).join(" "),
+        };
+    }
+    #context(host) {
+        let ctx = this.#contexts.get(host);
+        if (!ctx) {
+            const leaf = authority.leaf(host);
+            ctx = tls.createSecureContext({ key: leaf.key.export({ type: "pkcs8", format: "pem" }), cert: leaf.pem });
+            this.#contexts.set(host, ctx);
+        }
+        return ctx;
+    }
+    /** `CONNECT host:443`: TLS to a stub for intercepted hosts, a plain tunnel for the rest. */
+    #tunnel(req, socket, head) {
+        // "host:port" or "[::1]:port". (Not via URL, which drops a default port such as 80.)
+        const at = (req.url ?? "").lastIndexOf(":");
+        const host = (req.url ?? "").slice(0, at).replace(/^\[|\]$/g, "").toLowerCase();
+        const port = (req.url ?? "").slice(at + 1);
+        socket.on("error", () => { });
+        const route = lookupHost(this.routes, host);
+        if (route) {
+            socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            if (head.length)
+                socket.unshift(head);
+            // Some clients tunnel plain HTTP too (Node does with NODE_USE_ENV_PROXY): port 80 stays plain.
+            if (port === "80")
+                return route.attach(socket);
+            const secure = new tls.TLSSocket(socket, { isServer: true, secureContext: this.#context(host), ALPNProtocols: ["http/1.1"] });
+            secure.on("error", () => socket.destroy());
+            route.attach(secure);
+            return;
+        }
+        if (this.offline) {
+            this.blocked.add(host);
+            socket.end("HTTP/1.1 403 Forbidden\r\ncontent-length: 0\r\n\r\n");
+            return;
+        }
+        this.passedThrough.add(host);
+        const upstream = net.connect(Number(port) || 443, host, () => {
+            socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+            if (head.length)
+                upstream.write(head);
+            upstream.pipe(socket).pipe(upstream);
+        });
+        upstream.on("error", () => socket.end("HTTP/1.1 502 Bad Gateway\r\n\r\n"));
+    }
+    /** A plain-HTTP proxy request (`GET http://host/path`). */
+    #plain(req, res) {
+        let target;
+        try {
+            target = new URL(req.url ?? "");
+        }
+        catch {
+            res.writeHead(400).end("slicetest proxy: expected an absolute URL");
+            return;
+        }
+        const host = target.hostname.toLowerCase();
+        const route = lookupHost(this.routes, host);
+        if (!route && this.offline) {
+            this.blocked.add(host);
+            res.writeHead(403, { "content-type": "text/plain" }).end(`slicetest: offline, ${host} is not stubbed`);
+            return;
+        }
+        if (!route)
+            this.passedThrough.add(host);
+        const forward = http.request({
+            method: req.method,
+            path: target.pathname + target.search,
+            headers: req.headers,
+            ...(route ? { host: "127.0.0.1", port: route.port } : { host, port: Number(target.port || 80) }),
+        }, (upstream) => {
+            res.writeHead(upstream.statusCode ?? 502, upstream.headers);
+            upstream.pipe(res);
+        });
+        forward.on("error", () => res.headersSent || res.writeHead(502).end());
+        req.pipe(forward);
+    }
+    async close() {
+        for (const s of this.#sockets)
+            s.destroy();
+        await new Promise((resolve) => this.#server.close(resolve));
+        // On Windows a client still shutting down may hold the trust store open for a moment.
+        await rm(this.files.dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }).catch(() => { });
+    }
+}

package/dist/neon.d.ts

@@ -0,0 +1,14 @@
+/** The made-up domain of the connection string the app gets; `*.` of it is intercepted. */
+export declare const NEON_DOMAIN = "neon.slicetest";
+/** `url` (the real test database) with its host replaced by a Neon-style endpoint host. */
+export declare function neonUrl(url: string): string;
+export declare class NeonEndpoint {
+    #private;
+    private constructor();
+    /** `databaseUrl` is where queries really run: the worker database, or the `db.queries` proxy in front of it. */
+    static start(databaseUrl: string): Promise<NeonEndpoint>;
+    get port(): number;
+    /** Serve a connection the intercepting proxy terminated. */
+    attach(socket: import("node:net").Socket): void;
+    close(): Promise<void>;
+}