@decohere/scaffold 0.0.1-dev.125 → 0.0.1-dev.18

package/tests/cli.integration.spec.ts

@@ -0,0 +1,658 @@
+/**
+ * Behavior: running the create CLI the way Node runs the package bin writes a webapi tree.
+ *
+ * One suite — every example uses the same launch:
+ *   argv = [node, /node_modules/.bin/decohere, …userArgs]
+ * then load the bin entry (writes go to memfs).
+ *
+ * Examples are argv permutations only.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { resetMemfs } from "@decohere/nexus/testing";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { seedDevcontainerTemplates } from "./seed-devcontainer-templates.js";
+
+const realFs = await vi.importActual<typeof import("node:fs")>("node:fs");
+
+const { mockAsk, mockPick, mockInstall } = vi.hoisted(() => ({
+	mockAsk: vi.fn((_q: string, fallback = "") => Promise.resolve(fallback)),
+	mockPick: vi.fn(
+		<T>(_label: string, items: T[], _display: (item: T) => string): Promise<T | null> =>
+			Promise.resolve(items[0] ?? null),
+	),
+	mockInstall: vi.fn().mockResolvedValue({ message: "", data: [] }),
+}));
+
+const mockPm = {
+	name: "pnpm" as const,
+	install: mockInstall,
+	syncLockFile: vi.fn().mockResolvedValue({ message: "", data: [] }),
+};
+
+vi.mock("../src/domain/prompt.js", async () => {
+	const actual = await import("../src/domain/prompt.js");
+	return { ...actual, ask: mockAsk, pick: mockPick };
+});
+
+vi.mock(import("../../nexus/src/interop/index.js"), async (importOriginal) => {
+	const actual = await importOriginal();
+	return {
+		...actual,
+		detectPackageManager: () => mockPm,
+		promptForPackageManager: () => Promise.resolve(mockPm),
+	};
+});
+
+vi.mock(import("../src/webapi/features/auth0-cli.js"), () => ({
+	isInstalled: () => false,
+	login: () => true,
+	listTenants: () => [],
+}));
+
+vi.mock("../src/webapi/features/biome-format.js", () => ({
+	formatScaffoldedFiles: vi.fn(),
+}));
+
+const NODE = process.execPath;
+const CLI_FILE = realFs.realpathSync(fileURLToPath(new URL("../src/cli.ts", import.meta.url)));
+/** Same argv[1] shape npm/npx use for the package bin. */
+const NPM_BIN = "/node_modules/.bin/decohere";
+
+/** Feature flags only — does not skip install (use with builder env or `--install no`). */
+const NON_INTERACTIVE_FEATURES = [
+	"--database",
+	"none",
+	"--auth",
+	"none",
+	"--postman",
+	"none",
+] as const;
+
+const NON_INTERACTIVE = [...NON_INTERACTIVE_FEATURES, "--install", "no"] as const;
+
+function expectWebapiTree(root: string): void {
+	expect(existsSync(join(root, "package.json")), `${root}/package.json`).toBe(true);
+	expect(existsSync(join(root, "Dockerfile")), `${root}/Dockerfile`).toBe(true);
+	expect(existsSync(join(root, "tsconfig.json")), `${root}/tsconfig.json`).toBe(true);
+	expect(existsSync(join(root, "vitest.config.ts")), `${root}/vitest.config.ts`).toBe(true);
+	const vitestConfig = readFileSync(join(root, "vitest.config.ts"), "utf8");
+	expect(vitestConfig).toContain('from "@decohere/forge/vitest"');
+	expect(vitestConfig).toContain("forgeBuild");
+	expect(
+		existsSync(join(root, "projects/api/package.json")),
+		`${root}/projects/api/package.json`,
+	).toBe(true);
+	expect(
+		existsSync(join(root, "projects/api/src/main.ts")),
+		`${root}/projects/api/src/main.ts`,
+	).toBe(true);
+	expect(readFileSync(join(root, "projects/api/src/main.ts"), "utf8")).toContain(
+		"withHealth()",
+	);
+	expect(readFileSync(join(root, "projects/api/src/main.ts"), "utf8")).toContain(
+		"Number(process.env.PORT ?? 3000)",
+	);
+	expect(readFileSync(join(root, "projects/api/src/main.ts"), "utf8")).toContain(
+		"scribe.withPinoPretty().and.withPinoRoll",
+	);
+	expect(readFileSync(join(root, ".gitignore"), "utf8")).toContain("logs");
+	expect(readFileSync(join(root, ".gitignore"), "utf8")).toContain(".cursor/codebase-rag.env");
+	expect(readFileSync(join(root, ".gitignore"), "utf8")).toContain(".cursor/mcp.json");
+	expect(
+		existsSync(join(root, "projects/api/src/controllers/hello.controller.ts")),
+		`${root}/projects/api/src/controllers/hello.controller.ts`,
+	).toBe(true);
+
+	const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+		scripts?: Record<string, string>;
+		dependencies?: Record<string, string>;
+		devDependencies?: Record<string, string>;
+	};
+	expect(pkg.scripts?.build).toBeTruthy();
+	expect(pkg.scripts?.start).toBeTruthy();
+	expect(pkg.scripts?.dev).toBeTruthy();
+	expect(pkg.dependencies?.["pino-pretty"]).toBeTruthy();
+	expect(pkg.dependencies?.["pino-roll"]).toBeTruthy();
+	expect(pkg.devDependencies?.["@decohere/forge"]).toBeTruthy();
+
+	const apiPkg = JSON.parse(readFileSync(join(root, "projects/api/package.json"), "utf8")) as {
+		private?: boolean;
+	};
+	expect(apiPkg.private).toBe(true);
+
+	const dockerfile = readFileSync(join(root, "Dockerfile"), "utf8");
+	expect(dockerfile).toContain("pnpm run build");
+	expect(dockerfile).toContain("pnpm install --frozen-lockfile --prod");
+	expect(dockerfile).toContain("COPY --from=prod-deps /app/node_modules ./node_modules");
+	expect(dockerfile).not.toContain("COPY --from=build /app/node_modules");
+
+	const devcontainerJson = readFileSync(join(root, ".devcontainer/devcontainer.json"), "utf8");
+	expect(devcontainerJson).toContain(
+		'"postCreateCommand": "bash .devcontainer/post-create.sh"',
+	);
+	expect(devcontainerJson).toContain(
+		'"updateContentCommand": "bash .devcontainer/post-create.sh"',
+	);
+	expect(devcontainerJson).toContain('"postStartCommand": "bash .devcontainer/post-start.sh"');
+
+	const postCreate = readFileSync(join(root, ".devcontainer/post-create.sh"), "utf8");
+	expect(postCreate).toContain("pnpm install --frozen-lockfile");
+	expect(postCreate).toContain("pnpm install");
+
+	const postStart = readFileSync(join(root, ".devcontainer/post-start.sh"), "utf8");
+	expect(postStart).not.toContain("pnpm install");
+	expect(postStart).toContain("codebase-rag-mcp.ts");
+	expect(postStart).toContain('prompt_yn "Log in to npm?"');
+	expect(postStart).toContain('prompt_yn "Log in to GitHub CLI (gh)?"');
+	expect(postStart).toContain("gh auth login");
+	expect(postStart).toContain(".devcontainer/gh-auth/");
+	expect(postStart).not.toContain("exit 1");
+
+	const initialize = readFileSync(join(root, ".devcontainer/initialize.sh"), "utf8");
+	expect(initialize).toContain('prompt_yn "Configure npm auth for this workspace?"');
+	expect(initialize).toContain('prompt_yn "Configure GitHub CLI auth for this workspace?"');
+	expect(initialize).toContain('prompt_yn "Configure codebase RAG MCP (semantic search)?"');
+	expect(initialize).toContain('gh_dir="$root/.devcontainer/gh-auth"');
+	expect(initialize).toContain('gh_env="$root/.devcontainer/gh.env"');
+	expect(initialize).not.toContain("python3");
+	expect(existsSync(join(root, ".devcontainer/codebase-rag-mcp.ts"))).toBe(true);
+	expect(existsSync(join(root, ".devcontainer/tty-prompt.sh"))).toBe(true);
+
+	expect(initialize).toContain('cursor_dir="$root/.cursor"');
+	expect(initialize).toContain("codebase-rag.env");
+
+	const compose = readFileSync(join(root, ".devcontainer/docker-compose.yml"), "utf8");
+	expect(compose).toContain("codebase-rag-mcp.ts merge");
+	expect(compose).toContain("postStartCommand runs after Cursor's first MCP snapshot");
+	expect(compose).toContain("./gh-auth:/home/node/.config/gh");
+	expect(compose).toContain("./gh.env");
+	expect(compose).not.toContain("cursor-mcp");
+	expect(compose).not.toContain("${HOME}/.config/cursor/codebase-rag.env");
+	expect(compose).toContain("bashhistory:/commandhistory");
+	expect(compose).toMatch(/^ {2}bashhistory:\s*$/m);
+
+	const appDevDockerfile = readFileSync(join(root, ".devcontainer/Dockerfile"), "utf8");
+	expect(appDevDockerfile).toMatch(/^FROM ghcr\.io\/typesmiths\/decohere\/devcontainer:/m);
+	expect(appDevDockerfile).not.toContain("apt-get install -y --no-install-recommends gh");
+
+	const gitignore = readFileSync(join(root, ".gitignore"), "utf8");
+	expect(gitignore).toContain(".devcontainer/gh.env");
+}
+
+/** argv as `node node_modules/.bin/decohere …args`, then load the bin entry. */
+async function runCliAsNodeBin(
+	userArgs: string[],
+	options?: { resetFs?: boolean; builder?: boolean },
+): Promise<void> {
+	vi.resetModules();
+	if (options?.resetFs !== false) {
+		resetMemfs();
+		seedDevcontainerTemplates();
+	}
+	vi.spyOn(process, "cwd").mockReturnValue("/");
+	if (options?.builder === false) {
+		delete process.env.DECOHERE_BUILDER;
+	} else {
+		process.env.DECOHERE_BUILDER = "1";
+	}
+	process.argv = [NODE, NPM_BIN, ...userArgs];
+
+	const exited = new Promise<void>((resolve) => {
+		vi.spyOn(process, "exit").mockImplementation(() => {
+			resolve();
+			return undefined as never;
+		});
+	});
+
+	await import(`${pathToFileURL(CLI_FILE).href}?t=${Date.now()}`);
+	await Promise.race([
+		exited,
+		new Promise<void>((_, reject) => {
+			setTimeout(() => reject(new Error("CLI did not exit")), 5000);
+		}),
+	]);
+}
+
+beforeEach(() => {
+	mockInstall.mockClear();
+	mockAsk.mockClear();
+	mockPick.mockClear();
+});
+
+afterEach(() => {
+	resetMemfs();
+	vi.restoreAllMocks();
+	delete process.env.DECOHERE_BUILDER;
+	delete process.env.DECOHERE_PROJECT_NAME;
+});
+
+describe("scaffolder writes a webapi project", () => {
+	it("writes files for: webapi my-app (npm create after stealing -d)", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...NON_INTERACTIVE]);
+		expectWebapiTree("/my-app");
+	});
+
+	it("writes files for: webapi -d my-app (npx / direct bin)", async () => {
+		await runCliAsNodeBin(["create", "webapi", "-d", "my-app", ...NON_INTERACTIVE]);
+		expectWebapiTree("/my-app");
+	});
+
+	it("writes files for: webapi ./apps/api (relative directory)", async () => {
+		await runCliAsNodeBin(["create", "webapi", "./apps/api", ...NON_INTERACTIVE]);
+		expectWebapiTree("/apps/api");
+	});
+
+	it("writes files into cwd for: webapi (no directory)", async () => {
+		process.env.DECOHERE_PROJECT_NAME = "cwd-app";
+		await runCliAsNodeBin(["create", "webapi", ...NON_INTERACTIVE]);
+		expectWebapiTree("/");
+	});
+
+	it("uses DECOHERE_PROJECT_NAME when scaffolding into /workspace", async () => {
+		process.env.DECOHERE_PROJECT_NAME = "test1";
+		await runCliAsNodeBin(["create", "webapi", "-d", "/workspace", ...NON_INTERACTIVE]);
+
+		const settings = JSON.parse(
+			readFileSync(join("/workspace", ".vscode/settings.json"), "utf8"),
+		) as { "window.title"?: string };
+		expect(settings["window.title"]).toContain("test1");
+
+		const pkg = JSON.parse(readFileSync(join("/workspace", "package.json"), "utf8")) as {
+			name?: string;
+		};
+		expect(pkg.name).toBe("test1.api");
+	});
+});
+
+describe("scaffolder install behavior", () => {
+	it("installs dependencies when not in builder env and without --install no", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...NON_INTERACTIVE_FEATURES], {
+			builder: false,
+		});
+		expectWebapiTree("/my-app");
+		expect(mockInstall).toHaveBeenCalledOnce();
+	});
+
+	it("does not install when DECOHERE_BUILDER=1 even without --install no", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...NON_INTERACTIVE_FEATURES]);
+		expectWebapiTree("/my-app");
+		expect(mockInstall).not.toHaveBeenCalled();
+	});
+
+	it("does not install when --install no is set", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...NON_INTERACTIVE], {
+			builder: false,
+		});
+		expectWebapiTree("/my-app");
+		expect(mockInstall).not.toHaveBeenCalled();
+	});
+});
+
+function readJson(path: string): {
+	scripts?: Record<string, string>;
+	name?: string;
+	private?: boolean;
+} {
+	return JSON.parse(readFileSync(path, "utf8")) as {
+		scripts?: Record<string, string>;
+		name?: string;
+		private?: boolean;
+	};
+}
+
+function expectApiProject(root: string, apiName: string): void {
+	expect(existsSync(join(root, `projects/${apiName}/package.json`))).toBe(true);
+	expect(existsSync(join(root, `projects/${apiName}/src/main.ts`))).toBe(true);
+	const apiPkg = readJson(join(root, `projects/${apiName}/package.json`));
+	expect(apiPkg.private).toBe(true);
+	expect(apiPkg.name).toBe(`@${root === "/" ? "cwd-app" : root.slice(1)}/${apiName}`);
+}
+
+describe("scaffolder names APIs and can add more later", () => {
+	it("writes projects/billing when --name billing", async () => {
+		await runCliAsNodeBin([
+			"create",
+			"webapi",
+			"my-app",
+			"--name",
+			"billing",
+			...NON_INTERACTIVE,
+		]);
+
+		expect(existsSync("/my-app/projects/api")).toBe(false);
+		expectApiProject("/my-app", "billing");
+
+		const pkg = readJson("/my-app/package.json");
+		expect(pkg.scripts?.start).toContain("projects/billing");
+		expect(pkg.scripts?.["start:billing"]).toContain("projects/billing");
+
+		const docker = readFileSync("/my-app/Dockerfile", "utf8");
+		expect(docker).toContain("COPY projects/billing");
+		expect(docker).not.toContain("COPY projects/api");
+		expect(existsSync("/my-app/Dockerfile.billing")).toBe(true);
+	});
+
+	it("writes multiple APIs for repeated --name", async () => {
+		await runCliAsNodeBin([
+			"create",
+			"webapi",
+			"my-app",
+			"--name",
+			"api",
+			"--name",
+			"billing",
+			...NON_INTERACTIVE,
+		]);
+
+		expectApiProject("/my-app", "api");
+		expectApiProject("/my-app", "billing");
+
+		const pkg = readJson("/my-app/package.json");
+		expect(pkg.scripts?.start).toContain("projects/api");
+		expect(pkg.scripts?.["start:billing"]).toContain("projects/billing");
+
+		expect(readFileSync("/my-app/Dockerfile", "utf8")).toContain("COPY projects/api");
+		expect(existsSync("/my-app/Dockerfile.billing")).toBe(true);
+	});
+
+	it("adds a named API to an existing workspace without clobbering the first", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...NON_INTERACTIVE]);
+		writeFileSync("/my-app/biome.json", '{ "custom": true }\n');
+		writeFileSync("/my-app/Dockerfile", "# keep-root-dockerfile\n");
+		writeFileSync("/my-app/vitest.config.ts", "// keep-vitest-config\n");
+
+		await runCliAsNodeBin(["add", "api", "billing", "-d", "my-app", ...NON_INTERACTIVE], {
+			resetFs: false,
+		});
+
+		expect(readFileSync("/my-app/biome.json", "utf8")).toContain("custom");
+		expect(readFileSync("/my-app/Dockerfile", "utf8")).toBe("# keep-root-dockerfile\n");
+		expect(readFileSync("/my-app/vitest.config.ts", "utf8")).toBe("// keep-vitest-config\n");
+		expectApiProject("/my-app", "api");
+		expectApiProject("/my-app", "billing");
+
+		const pkg = readJson("/my-app/package.json");
+		expect(pkg.scripts?.start).toContain("projects/api");
+		expect(pkg.scripts?.["start:billing"]).toContain("projects/billing");
+		expect(existsSync("/my-app/Dockerfile.billing")).toBe(true);
+	});
+
+	it("refuses add when the API already exists", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...NON_INTERACTIVE]);
+		const errors: string[] = [];
+		vi.spyOn(console, "error").mockImplementation((msg?: unknown) => {
+			errors.push(String(msg ?? ""));
+		});
+
+		await runCliAsNodeBin(["add", "api", "api", "-d", "my-app", ...NON_INTERACTIVE], {
+			resetFs: false,
+		});
+
+		expect(errors.join("\n")).toMatch(/already exists/);
+	});
+
+	it("refuses add outside a Decohere workspace", async () => {
+		const errors: string[] = [];
+		vi.spyOn(console, "error").mockImplementation((msg?: unknown) => {
+			errors.push(String(msg ?? ""));
+		});
+
+		await runCliAsNodeBin(["add", "api", "billing", ...NON_INTERACTIVE]);
+
+		expect(errors.join("\n")).toMatch(/Not a Decohere workspace/);
+		expect(existsSync("/projects/billing")).toBe(false);
+	});
+
+	it("refuses an invalid --name", async () => {
+		const errors: string[] = [];
+		vi.spyOn(console, "error").mockImplementation((msg?: unknown) => {
+			errors.push(String(msg ?? ""));
+		});
+
+		await runCliAsNodeBin([
+			"create",
+			"webapi",
+			"my-app",
+			"--name",
+			"Billing",
+			...NON_INTERACTIVE,
+		]);
+
+		expect(errors.join("\n")).toMatch(/Invalid API name/);
+		expect(existsSync("/my-app/projects/Billing")).toBe(false);
+	});
+});
+
+const POSTGRES = [
+	"--database",
+	"postgres/typeorm",
+	"--auth",
+	"none",
+	"--postman",
+	"none",
+	"--install",
+	"no",
+] as const;
+
+describe("scaffolder writes a root README with CLI examples", () => {
+	it("includes webapi add and pnpm dev, and omits db:* when database is none", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...NON_INTERACTIVE]);
+
+		const readme = readFileSync("/my-app/README.md", "utf8");
+		expect(readme).toContain("decohere add api <name>");
+		expect(readme).toContain("pnpm dev");
+		expect(readme).toContain("pnpm install");
+		expect(readme).toContain("Reopen in Container");
+		expect(readme).toContain("y/N");
+		expect(readme).toContain("codebase RAG MCP");
+		expect(readme).toContain(".cursor/");
+		expect(readme).toContain("pnpm install --prod");
+		expect(readme).toContain("## Logging");
+		expect(readme).toContain("NODE_ENV=production");
+		expect(readme).not.toContain("pnpm db:up");
+		expect(readme).not.toContain("## Auth0");
+		expect(readme).not.toContain("## Postman");
+	});
+
+	it("includes db:up when postgres is enabled", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...POSTGRES]);
+
+		const readme = readFileSync("/my-app/README.md", "utf8");
+		expect(readme).toContain("pnpm db:up");
+		expect(readme).toContain("pnpm db:down");
+		expect(readme).toContain("pnpm db:reset");
+		expect(readme).toContain("decohere add api <name>");
+		expect(readme).toContain("pnpm dev");
+	});
+
+	it("refreshes API scripts when webapi add runs", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...NON_INTERACTIVE]);
+		await runCliAsNodeBin(["add", "api", "billing", "-d", "my-app", ...NON_INTERACTIVE], {
+			resetFs: false,
+		});
+
+		const readme = readFileSync("/my-app/README.md", "utf8");
+		expect(readme).toContain("pnpm run start:api");
+		expect(readme).toContain("pnpm run start:billing");
+		expect(readme).toContain("pnpm run dev:billing");
+		expect(readme).toContain("decohere add api <name>");
+	});
+
+	it("keeps db:* after webapi add when the workspace already has postgres", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...POSTGRES]);
+		await runCliAsNodeBin(["add", "api", "billing", "-d", "my-app", ...NON_INTERACTIVE], {
+			resetFs: false,
+		});
+
+		const readme = readFileSync("/my-app/README.md", "utf8");
+		expect(readme).toContain("pnpm db:up");
+		expect(readme).toContain("pnpm run start:billing");
+	});
+});
+
+describe("each API owns a database on the shared Postgres instance", () => {
+	it("names the default API datasource and prefixes env", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...POSTGRES]);
+
+		const config = readFileSync("/my-app/config/config.yaml", "utf8");
+		expect(config).toContain("name: api");
+		expect(config).toContain("${API_DB_HOST}");
+		expect(config).not.toContain("name: default");
+		expect(config).not.toContain("${DB_HOST}");
+
+		const env = readFileSync("/my-app/.env", "utf8");
+		expect(env).toContain("API_DB_HOST=postgres");
+		expect(env).toContain("API_DB_PORT=5432");
+		expect(env).toMatch(/API_DB_NAME=/);
+		expect(env).not.toMatch(/^DB_NAME=/m);
+		expect(env).toContain("DB_ADMIN_USER=decohere_bootstrap");
+
+		const main = readFileSync("/my-app/projects/api/src/main.ts", "utf8");
+		expect(main).toContain("withHealth()");
+		expect(main).toContain('withTypeOrm({ name: "api"');
+
+		const compose = readFileSync("/my-app/.devcontainer/docker-compose.yml", "utf8");
+		expect(compose).toContain("samples-my-app-postgres");
+		expect(compose).toContain("build: ./postgres");
+		expect(compose).toContain("./postgres-data:/var/lib/postgresql/data");
+		expect(compose).toMatch(/bind mount|dies with the working tree/i);
+		expect(compose).not.toContain("postgres-init");
+		expect(compose).not.toMatch(/^\s+my-app-postgres-data:\s*$/m);
+		expect(compose).not.toContain("adminer");
+
+		const gitignore = readFileSync("/my-app/.gitignore", "utf8");
+		expect(gitignore).toContain(".devcontainer/postgres-data");
+
+		const rootPkg = JSON.parse(readFileSync("/my-app/package.json", "utf8")) as {
+			scripts: Record<string, string>;
+			dependencies: Record<string, string>;
+		};
+		expect(rootPkg.scripts["db:reset"]).toContain("rm -rf .devcontainer/postgres-data");
+		expect(rootPkg.scripts["db:reset"]).not.toContain("down -v");
+
+		expect(
+			readFileSync("/my-app/.devcontainer/postgres/ensure-bootstrap-role.sh", "utf8"),
+		).toContain("ALTER ROLE");
+		expect(readFileSync("/my-app/.devcontainer/postgres/Dockerfile", "utf8")).toContain(
+			"FROM postgres:16",
+		);
+
+		const appDevDockerfile = readFileSync("/my-app/.devcontainer/Dockerfile", "utf8");
+		expect(appDevDockerfile).toContain("postgresql-client");
+		expect(appDevDockerfile).toContain("USER root");
+		expect(appDevDockerfile).toMatch(/^FROM ghcr\.io\/typesmiths\/decohere\/devcontainer:/m);
+		const devcontainerJson = readFileSync("/my-app/.devcontainer/devcontainer.json", "utf8");
+		expect(devcontainerJson).toContain("mtxr.sqltools-driver-pg");
+
+		const depKeys = Object.keys(rootPkg.dependencies);
+		expect(depKeys).toEqual([...depKeys].sort((a, b) => a.localeCompare(b, "en")));
+		expect(rootPkg.dependencies.tsx).toBeTruthy();
+		expect(rootPkg.scripts["db:migrate"]).toContain("migration:run");
+		expect(rootPkg.scripts["db:migrate"]).toContain("typeorm.data-source.ts");
+		expect(rootPkg.scripts["db:migrate:generate"]).toContain("migration:generate");
+		expect(rootPkg.scripts["db:migrate:api"]).toContain("projects/api");
+
+		expect(existsSync("/my-app/docs/database.md")).toBe(true);
+		const dbDocs = readFileSync("/my-app/docs/database.md", "utf8");
+		expect(dbDocs).toMatch(/synchronize: true/);
+		expect(dbDocs).toMatch(/migrations only/i);
+		expect(dbDocs).toContain("db:migrate");
+		expect(dbDocs).toMatch(/Adminer is \*\*not\*\* scaffolded/i);
+		expect(dbDocs).toContain("image: adminer");
+
+		expect(existsSync("/my-app/projects/api/src/typeorm.data-source.ts")).toBe(true);
+		const dataSource = readFileSync("/my-app/projects/api/src/typeorm.data-source.ts", "utf8");
+		expect(dataSource).toContain("API_DB_MIGRATE_USER");
+		expect(dataSource).toContain("synchronize: false");
+		expect(existsSync("/my-app/projects/api/src/migrations/.gitkeep")).toBe(true);
+	});
+
+	it("emits per-API migrate scripts and data sources for named APIs", async () => {
+		await runCliAsNodeBin([
+			"create",
+			"webapi",
+			"my-app",
+			"--name",
+			"api",
+			"--name",
+			"billing",
+			...POSTGRES,
+		]);
+
+		const pkg = JSON.parse(readFileSync("/my-app/package.json", "utf8")) as {
+			scripts: Record<string, string>;
+		};
+		expect(pkg.scripts["db:migrate:billing"]).toContain("projects/billing");
+		expect(pkg.scripts["db:migrate:generate:billing"]).toContain("migration:generate");
+		expect(existsSync("/my-app/projects/billing/src/typeorm.data-source.ts")).toBe(true);
+		expect(
+			readFileSync("/my-app/projects/billing/src/typeorm.data-source.ts", "utf8"),
+		).toContain("BILLING_DB_MIGRATE_USER");
+	});
+
+	it("gives each named API its own database on the same host", async () => {
+		await runCliAsNodeBin([
+			"create",
+			"webapi",
+			"my-app",
+			"--name",
+			"api",
+			"--name",
+			"billing",
+			...POSTGRES,
+		]);
+
+		const config = readFileSync("/my-app/config/config.yaml", "utf8");
+		expect(config).toContain("name: api");
+		expect(config).toContain("name: billing");
+		expect(config).toContain("${BILLING_DB_HOST}");
+
+		const env = readFileSync("/my-app/.env", "utf8");
+		expect(env).toContain("API_DB_HOST=postgres");
+		expect(env).toContain("BILLING_DB_HOST=postgres");
+		const apiDb = env.split("\n").find((l) => l.startsWith("API_DB_NAME="));
+		const billingDb = env.split("\n").find((l) => l.startsWith("BILLING_DB_NAME="));
+		expect(apiDb).toBeTruthy();
+		expect(billingDb).toBeTruthy();
+		expect(apiDb).not.toBe(billingDb);
+
+		expect(readFileSync("/my-app/projects/api/src/main.ts", "utf8")).toContain(
+			'withTypeOrm({ name: "api"',
+		);
+		expect(readFileSync("/my-app/projects/billing/src/main.ts", "utf8")).toContain(
+			'withTypeOrm({ name: "billing"',
+		);
+
+		const compose = readFileSync("/my-app/.devcontainer/docker-compose.yml", "utf8");
+		expect(compose).toContain("container_name: samples-my-app-postgres");
+		expect(compose).not.toContain("samples-my-app-billing-postgres");
+	});
+
+	it("adds a datasource for webapi add without replacing the first", async () => {
+		await runCliAsNodeBin(["create", "webapi", "my-app", ...POSTGRES]);
+		await runCliAsNodeBin(["add", "api", "billing", "-d", "my-app", ...POSTGRES], {
+			resetFs: false,
+		});
+
+		const config = readFileSync("/my-app/config/config.yaml", "utf8");
+		expect(config).toContain("name: api");
+		expect(config).toContain("name: billing");
+		expect(config.match(/^database:/gm)?.length).toBe(1);
+
+		const env = readFileSync("/my-app/.env", "utf8");
+		expect(env).toContain("API_DB_HOST=postgres");
+		expect(env).toContain("BILLING_DB_HOST=postgres");
+		expect(readFileSync("/my-app/projects/billing/src/main.ts", "utf8")).toContain(
+			'withTypeOrm({ name: "billing"',
+		);
+
+		const pkg = JSON.parse(readFileSync("/my-app/package.json", "utf8")) as {
+			scripts: Record<string, string>;
+		};
+		expect(pkg.scripts["db:migrate"]).toContain("projects/api");
+		expect(pkg.scripts["db:migrate:billing"]).toContain("projects/billing");
+		expect(existsSync("/my-app/projects/billing/src/typeorm.data-source.ts")).toBe(true);
+	});
+});