#1: implement F0 foundation - monorepo, migrations, Go domain layer, service skeletons, CI

Stands up the LambdaMail monorepo per PLAN.md's F0 milestone: local dev
scaffolding (.env.example, Makefile, .gitignore excluding PLAN.md/docs/
.superpowers/), the full initial Postgres schema as a golang-migrate
migration, the complete Go domain layer for services/protocols (value
objects, entities, domain events - zero external imports beyond
github.com/google/uuid) with unit tests, health-checked service skeletons
for auth/storage (TypeScript) and webmail (Next.js), a local
docker-compose.yaml wiring all services together, a language-enforcement
lint script, and a GitHub Actions CI workflow.

Built via 11 sequential tasks under subagent-driven development, each with
an independent implementer + reviewer cycle. Fixes applied during review:
DomainName.IsPunycode() added to satisfy the promised interface; ioredis
default-import typing under NodeNext; next.js bumped 15.0.3->15.5.21 to
resolve high/critical CVEs; lang-lint.mjs corrected to not flag its own
banned-terms list; web service healthcheck added so compose --wait
actually waits on it; webmail Dockerfile's missing public/ directory:
protocols go.mod version aligned with CI's Go 1.22 pin.

Known follow-ups for later phases (not blocking F0): go-arch-lint isn't
wired into CI yet; live docker compose up and migration apply have not
been exercised in this dev environment (no Docker/psql available here)
and will get their first real run in CI, which does have Docker.

services/auth/src/health.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { buildHealthHandler } from "./health.js";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+
+async function withServer(
+  handler: ReturnType<typeof buildHealthHandler>,
+  run: (baseUrl: string) => Promise<void>,
+) {
+  const server = createServer(handler);
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  const { port } = server.address() as AddressInfo;
+  try {
+    await run(`http://127.0.0.1:${port}`);
+  } finally {
+    server.close();
+  }
+}
+
+describe("buildHealthHandler", () => {
+  it("returns 200 on /health/live regardless of dependency state", async () => {
+    const handler = buildHealthHandler(
+      async () => { throw new Error("db down"); },
+      async () => { throw new Error("redis down"); },
+    );
+    await withServer(handler, async (base) => {
+      const res = await fetch(`${base}/health/live`);
+      expect(res.status).toBe(200);
+    });
+  });
+
+  it("returns 200 on /health/ready when both dependencies respond", async () => {
+    const handler = buildHealthHandler(async () => {}, async () => {});
+    await withServer(handler, async (base) => {
+      const res = await fetch(`${base}/health/ready`);
+      expect(res.status).toBe(200);
+    });
+  });
+
+  it("returns 503 on /health/ready when a dependency fails", async () => {
+    const handler = buildHealthHandler(
+      async () => { throw new Error("db down"); },
+      async () => {},
+    );
+    await withServer(handler, async (base) => {
+      const res = await fetch(`${base}/health/ready`);
+      expect(res.status).toBe(503);
+    });
+  });
+});

services/auth/src/health.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+type PingFn = () => Promise<void>;
+
+/**
+ * Builds the /health/live and /health/ready handler shared by the auth and
+ * storage services (PLAN.md section 11.5 and the compose healthcheck in section 13).
+ */
+export function buildHealthHandler(pingDb: PingFn, pingRedis: PingFn) {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.url === "/health/live") {
+      res.writeHead(200).end();
+      return;
+    }
+    if (req.url === "/health/ready") {
+      try {
+        await Promise.all([pingDb(), pingRedis()]);
+        res.writeHead(200).end();
+      } catch {
+        res.writeHead(503).end();
+      }
+      return;
+    }
+    res.writeHead(404).end();
+  };
+}

services/auth/src/server.ts

@@ -0,0 +1,25 @@
+import { createServer } from "node:http";
+import { Client } from "pg";
+import { Redis } from "ioredis";
+import { buildHealthHandler } from "./health.js";
+
+const port = Number(process.env.PORT ?? 3001);
+
+const handler = buildHealthHandler(
+  async () => {
+    const client = new Client({ connectionString: process.env.DATABASE_URL });
+    await client.connect();
+    await client.query("SELECT 1");
+    await client.end();
+  },
+  async () => {
+    const redis = new Redis(process.env.REDIS_URL ?? "");
+    await redis.ping();
+    redis.disconnect();
+  },
+);
+
+createServer(handler).listen(port, () => {
+  // F0 scaffold: only health endpoints are wired. Auth use cases land in F1+.
+  console.log(`auth service listening on ${port}`);
+});