okengine 0.2.6 → 0.2.8

package/src/docker/compose.ts

@@ -7,12 +7,7 @@
  * 4. `compose.override.yml`   — user-owned; oke never writes it
  */
 
-import {
-  defaultHostPort,
-  envPrefix,
-  serviceNameFor,
-  toYaml,
-} from "./helpers.ts";
+import { defaultHostPort, envPrefix, serviceNameFor, toYaml } from "./helpers.ts";
 import { recipeFor } from "./recipes/index.ts";
 import type {
   DeriveOptions,
@@ -23,7 +18,7 @@ import type {
 } from "./types.ts";
 import { DEFAULT_DOCKER_DIR } from "./types.ts";
 import { generateCredentials } from "./credentials.ts";
-import { hostPortForInstance } from "./stack-id.ts";
+import { hostPortForInstance, instancePortOffset } from "./stack-id.ts";
 import { APP_PORT } from "../runtime/types.ts";
 
 /** Canonical layer-4 filename — never written by derivation. */
@@ -41,7 +36,7 @@ export function composePathRefs(composeDir: string = DEFAULT_DOCKER_DIR): {
 } {
   const flat = composeDir === "." || composeDir === "";
   return {
-    envFile: flat ? ".env.stack" : "../.env.stack",
+    envFile: ".env.docker",
     buildContext: flat ? "." : "..",
     dockerfile: "Dockerfile",
   };
@@ -57,8 +52,7 @@ export function buildSpecs(options: DeriveOptions): ServiceSpec[] {
   const specs: ServiceSpec[] = [];
   for (const [role, image] of Object.entries(options.images)) {
     const recipe = recipeFor(image, recipes);
-    const creds =
-      options.credentials?.[role] ?? generateCredentials(role);
+    const creds = options.credentials?.[role] ?? generateCredentials(role);
     const port = recipe.port;
     const hostPort = options.instanceId
       ? hostPortForInstance(role, port, options.instanceId)
@@ -116,12 +110,17 @@ export function emitComposeLayers(
   files.push({ path: "compose.yml", content: `${toYaml(base)}\n` });
 
   // Layer 2 — per-role
+  const extraHostOffset = options.instanceId ? instancePortOffset(options.instanceId) : 0;
   for (const spec of specs) {
     const recipe = recipeFor(spec.image, recipes);
     const applied = recipe.apply(spec);
+    const ports = [
+      `${spec.hostPort}:${spec.port}`,
+      ...(applied.extraPorts ?? []).map((p) => `${p.host + extraHostOffset}:${p.container}`),
+    ];
     const service: Record<string, unknown> = {
       image: spec.image,
-      ports: [`${spec.hostPort}:${spec.port}`],
+      ports,
       networks: ["oke"],
       env_file: [paths.envFile],
     };
@@ -131,10 +130,14 @@ export function emitComposeLayers(
     if (applied.volumes) service.volumes = applied.volumes;
     if (applied.user) service.user = applied.user;
 
-    const doc = {
+    const namedVolumes = namedVolumeDecls(applied.volumes);
+    const doc: Record<string, unknown> = {
       services: { [spec.serviceName]: service },
       networks: { oke: { external: false } },
     };
+    if (Object.keys(namedVolumes).length > 0) {
+      doc.volumes = namedVolumes;
+    }
     const path = `compose.${spec.role}.yml`;
     files.push({ path, content: `${toYaml(doc)}\n` });
   }
@@ -181,7 +184,7 @@ export function emitComposeLayers(
 }
 
 /**
- * Build `.env.stack` key/value map (credentials + connection URLs).
+ * Build docker env key/value map (credentials + connection URLs).
  *
  * @param specs - Services
  * @param recipes - Extra recipes
@@ -214,17 +217,89 @@ export function buildStackEnv(
   return env;
 }
 
+/** Friendly section titles for known compose roles. */
+const ROLE_SECTION_TITLE: Readonly<Record<string, string>> = {
+  "store.sql": "store.sql — Postgres",
+  "store.kv": "store.kv — Redis",
+  "store.files": "store.files — object storage (S3)",
+  "store.index": "store.index — search index",
+  "channel.email": "channel.email — Mailpit (SMTP + UI)",
+  signal: "signal — message bus",
+};
+
+/** Friendly aliases emitted beside their role block. */
+const ROLE_ALIASES: Readonly<Record<string, readonly string[]>> = {
+  "store.sql": ["DATABASE_URL"],
+  "store.kv": ["REDIS_URL"],
+};
+
+/**
+ * Infer role from an `OKE_<ROLE>_*` key (`OKE_STORE_SQL_URL` → `store.sql`).
+ *
+ * @param key - Env key
+ */
+function roleFromEnvKey(key: string): string | undefined {
+  const m = /^OKE_(.+)_(USER|PASSWORD|DB|URL)$/.exec(key);
+  if (!m) return undefined;
+  return m[1]!.toLowerCase().replaceAll("_", ".");
+}
+
 /**
- * Serialise stack env to dotenv text.
+ * Serialise stack env to commented, role-grouped dotenv text.
  *
- * @param env - Key/value map
+ * @param env - Key/value map from {@link buildStackEnv}
  */
 export function formatStackEnv(env: Readonly<Record<string, string>>): string {
-  return (
-    Object.entries(env)
-      .map(([k, v]) => `${k}=${escapeEnv(v)}`)
-      .join("\n") + "\n"
-  );
+  const roles = new Set<string>();
+  for (const key of Object.keys(env)) {
+    const role = roleFromEnvKey(key);
+    if (role) roles.add(role);
+  }
+  const ordered = [...roles].sort((a, b) => a.localeCompare(b));
+  const used = new Set<string>();
+  const lines: string[] = [
+    "# docker/.env.docker — generated by `oke dev --docker`",
+    "# Credentials + connection URLs for the local compose stack.",
+    "# Host ports are unique per project (instance offset). Do not commit.",
+    "# Vault resolution: process.env → .env.local → docker/.env.docker → driver",
+    "#",
+    "# Re-run `oke dev --docker` to regenerate. Put compose tweaks in",
+    "# compose.override.yml — never put secrets in YAML.",
+    "",
+  ];
+
+  for (const role of ordered) {
+    const prefix = envPrefix(role);
+    const title = ROLE_SECTION_TITLE[role] ?? role;
+    lines.push(`# ── ${title} ${"─".repeat(Math.max(4, 56 - title.length))}`);
+    for (const field of ["USER", "PASSWORD", "DB", "URL"] as const) {
+      const key = `${prefix}_${field}`;
+      const value = env[key];
+      if (value === undefined) continue;
+      lines.push(`${key}=${escapeEnv(value)}`);
+      used.add(key);
+    }
+    for (const alias of ROLE_ALIASES[role] ?? []) {
+      const value = env[alias];
+      if (value === undefined) continue;
+      lines.push(`${alias}=${escapeEnv(value)}`);
+      used.add(alias);
+    }
+    lines.push("");
+  }
+
+  const leftover = Object.keys(env)
+    .filter((k) => !used.has(k))
+    .sort((a, b) => a.localeCompare(b));
+  if (leftover.length > 0) {
+    lines.push(`# ── other ${"─".repeat(50)}`);
+    for (const key of leftover) {
+      lines.push(`${key}=${escapeEnv(env[key]!)}`);
+    }
+    lines.push("");
+  }
+
+  return `${lines.join("\n")}\n`;
 }
 
 /**
@@ -249,6 +324,23 @@ function secretNames(spec: ServiceSpec): string[] {
   return [`${p}_PASSWORD`];
 }
 
+/**
+ * Collect named volume declarations from recipe volume mounts (`name:/path`).
+ *
+ * @param volumes - Compose volume strings
+ */
+function namedVolumeDecls(
+  volumes: readonly string[] | undefined,
+): Record<string, Record<string, never>> {
+  const out: Record<string, Record<string, never>> = {};
+  for (const v of volumes ?? []) {
+    if (v.startsWith(".") || v.startsWith("/") || v.startsWith("~")) continue;
+    const name = v.split(":")[0];
+    if (name) out[name] = {};
+  }
+  return out;
+}
+
 function escapeEnv(value: string): string {
   if (/[\s#"'$\\]/.test(value)) {
     return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;

package/src/docker/derive.ts

@@ -17,7 +17,7 @@ import { DEFAULT_DOCKER_DIR } from "./types.ts";
 /**
  * Derive infrastructure files from normalised image pins.
  *
- * Credentials land only in the returned `stackEnv` (for `.env.stack`);
+ * Credentials land only in the returned `stackEnv` (for `.env.docker`);
  * generated YAML never contains cleartext secrets. Layer 4
  * (`compose.override.yml`) is listed in `composeFiles` but never written.
  *
@@ -37,10 +37,7 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
   };
 
   const specs = buildSpecs(normalised);
-  const { files: composeFilesContent, composeFiles } = emitComposeLayers(
-    specs,
-    normalised,
-  );
+  const { files: composeFilesContent, composeFiles } = emitComposeLayers(specs, normalised);
   const dockerfile: GeneratedFile = {
     path: "Dockerfile",
     content: emitDockerfile({ appPort: normalised.appPort }),
@@ -57,18 +54,14 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
     }
   }
 
-  const stackEnv = buildStackEnv(
-    specs,
-    normalised.recipes ?? [],
-    normalised.host ?? "127.0.0.1",
-  );
+  const stackEnv = buildStackEnv(specs, normalised.recipes ?? [], normalised.host ?? "127.0.0.1");
 
   return { specs, files, stackEnv, composeFiles };
 }
 
 /**
  * Write derived files to disk. Never writes `compose.override.yml` or
- * credential values into YAML. Optionally writes `.env.stack`.
+ * credential values into YAML. Optionally writes `docker/.env.docker`.
  *
  * @param result - Derive result
  * @param outDir - Destination for Dockerfile / compose (usually `docker/`)
@@ -79,11 +72,6 @@ export async function writeDerivedFiles(
   outDir: string,
   options: {
     readonly writeStackEnv?: boolean;
-    /**
-     * Directory for `.env.stack` (project root). Defaults to `outDir`.
-     * Prefer the project cwd when compose lives under `docker/`.
-     */
-    readonly stackEnvDir?: string;
   } = {},
 ): Promise<readonly string[]> {
   const written: string[] = [];
@@ -95,9 +83,7 @@ export async function writeDerivedFiles(
     written.push(path);
   }
   if (options.writeStackEnv) {
-    const envRoot = (options.stackEnvDir ?? outDir).replace(/\/$/, "");
-    mkdirSync(envRoot, { recursive: true });
-    const envPath = `${envRoot}/.env.stack`;
+    const envPath = `${root}/.env.docker`;
     await Bun.write(envPath, formatStackEnv(result.stackEnv));
     written.push(envPath);
   }

package/src/docker/docker.test.ts

@@ -78,7 +78,12 @@ describe("image recipes", () => {
       match: (i) => /nats/i.test(i),
       apply: () => ({
         command: ["--js"],
-        healthcheck: { test: ["CMD", "nats-server", "--signal", "ldm"], interval: "5s", timeout: "3s", retries: 5 },
+        healthcheck: {
+          test: ["CMD", "nats-server", "--signal", "ldm"],
+          interval: "5s",
+          timeout: "3s",
+          retries: 5,
+        },
       }),
       url: (_s, c) => `nats://${c.host}:${c.port}`,
     };
@@ -120,29 +125,23 @@ describe("deriveInfrastructure", () => {
       COMPOSE_OVERRIDE,
     ]);
 
-    const sqlYml = result.files.find((f) => f.path === "compose.store.sql.yml")!
-      .content;
+    const sqlYml = result.files.find((f) => f.path === "compose.store.sql.yml")!.content;
     expect(sqlYml).toContain("pgvector/pgvector:pg17");
     expect(sqlYml).toContain("POSTGRES_PASSWORD");
     expect(sqlYml).toContain("${OKE_STORE_SQL_PASSWORD}");
-    expect(sqlYml).toContain("../.env.stack");
+    expect(sqlYml).toContain(".env.docker");
     expect(sqlYml).not.toContain(fixedCreds["store.sql"].password);
 
     const baseYml = result.files.find((f) => f.path === "compose.yml")!.content;
-    expect(baseYml).toContain("context: \"..\"");
+    expect(baseYml).toContain('context: ".."');
     expect(baseYml).toContain("app:");
 
     for (const f of result.files) {
-      assertNoCredentialsInYaml(
-        f.content,
-        Object.values(fixedCreds),
-      );
+      assertNoCredentialsInYaml(f.content, Object.values(fixedCreds));
     }
 
     expect(result.stackEnv.DATABASE_URL).toContain("postgres://");
-    expect(result.stackEnv.OKE_STORE_SQL_PASSWORD).toBe(
-      fixedCreds["store.sql"].password,
-    );
+    expect(result.stackEnv.OKE_STORE_SQL_PASSWORD).toBe(fixedCreds["store.sql"].password);
   });
 
   test("includeApp false omits app service (infra-only stack)", () => {
@@ -187,13 +186,14 @@ describe("deriveInfrastructure", () => {
     });
     const written = await writeDerivedFiles(result, dockerDir, {
       writeStackEnv: true,
-      stackEnvDir: root,
     });
     expect(written.some((p) => p.endsWith(COMPOSE_OVERRIDE))).toBe(false);
-    expect(await Bun.file(join(root, ".env.stack")).exists()).toBe(true);
+    expect(await Bun.file(join(dockerDir, ".env.docker")).exists()).toBe(true);
     expect(await Bun.file(join(dockerDir, "compose.yml")).exists()).toBe(true);
-    const envText = await Bun.file(join(root, ".env.stack")).text();
+    const envText = await Bun.file(join(dockerDir, ".env.docker")).text();
     expect(envText).toContain("DATABASE_URL=");
+    expect(envText).toContain("# docker/.env.docker — generated by");
+    expect(envText).toContain("# ── store.sql — Postgres");
     expect(formatStackEnv(result.stackEnv)).toContain("OKE_STORE_SQL_PASSWORD=");
   });
 

package/src/docker/dockerfile.integration.test.ts

@@ -96,10 +96,10 @@ console.log("listening", server.port);
       await Bun.write(join(dir, "Dockerfile"), df);
 
       const tag = `oke-docker-fixture:${Date.now()}`;
-      const build = Bun.spawn(
-        ["docker", "build", "-t", tag, dir],
-        { stdout: "pipe", stderr: "pipe" },
-      );
+      const build = Bun.spawn(["docker", "build", "-t", tag, dir], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
       const [buildOut, buildErr, buildCode] = await Promise.all([
         new Response(build.stdout).text(),
         new Response(build.stderr).text(),
@@ -111,19 +111,10 @@ console.log("listening", server.port);
       }
 
       const name = `oke-fixture-run-${Date.now()}`;
-      const run = Bun.spawn(
-        [
-          "docker",
-          "run",
-          "-d",
-          "--name",
-          name,
-          "-p",
-          "0:6530",
-          tag,
-        ],
-        { stdout: "pipe", stderr: "pipe" },
-      );
+      const run = Bun.spawn(["docker", "run", "-d", "--name", name, "-p", "0:6530", tag], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
       const [runOut, runErr, runCode] = await Promise.all([
         new Response(run.stdout).text(),
         new Response(run.stderr).text(),
@@ -133,10 +124,10 @@ console.log("listening", server.port);
       if (runCode !== 0) console.error(runOut, runErr);
 
       // Resolve published port
-      const portProc = Bun.spawn(
-        ["docker", "port", name, "6530"],
-        { stdout: "pipe", stderr: "pipe" },
-      );
+      const portProc = Bun.spawn(["docker", "port", name, "6530"], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
       const portOut = await new Response(portProc.stdout).text();
       await portProc.exited;
       const m = portOut.match(/:(\d+)/);

package/src/docker/helpers.ts

@@ -74,10 +74,11 @@ export function toYaml(value: unknown, indent = 0): string {
           const body = toYaml(item, indent + 1);
           const lines = body.split("\n");
           const first = lines[0] ?? "";
-          const rest = lines.slice(1).map((l) => `${pad}  ${l}`).join("\n");
-          return rest
-            ? `${pad}- ${first}\n${rest}`
-            : `${pad}- ${first}`;
+          const rest = lines
+            .slice(1)
+            .map((l) => `${pad}  ${l}`)
+            .join("\n");
+          return rest ? `${pad}- ${first}\n${rest}` : `${pad}- ${first}`;
         }
         return `${pad}- ${toYaml(item, 0)}`;
       })

package/src/docker/index.ts

@@ -14,6 +14,7 @@ export type {
   GeneratedFile,
   ImageRecipe,
   RecipeApplyResult,
+  RecipeExtraPort,
   ServiceCredentials,
   ServiceEndpoint,
   ServiceSpec,
@@ -35,19 +36,11 @@ export { deriveInfrastructure, writeDerivedFiles } from "./derive.ts";
 export { emitDockerfile } from "./dockerfile.ts";
 export { credEnv, envPrefix, serviceNameFor } from "./helpers.ts";
 export { generateCredentials } from "./credentials.ts";
-export {
-  builtinRecipes,
-  postgres,
-  recipeFor,
-  redis,
-} from "./recipes/index.ts";
-export {
-  formatStackPreview,
-  resolveStack,
-  type StackRow,
-} from "./stack.ts";
+export { builtinRecipes, mailpit, postgres, recipeFor, redis, rustfs } from "./recipes/index.ts";
+export { formatStackPreview, resolveStack, type StackRow } from "./stack.ts";
 export {
   hostPortForInstance,
+  instancePortOffset,
   loadExistingStackCredentials,
   parseStackCredentials,
   stackAppSlug,

package/src/docker/pin.ts

@@ -61,15 +61,7 @@ export function formatImagesLock(lock: ImagesLock): string {
  */
 async function dockerDigest(image: string): Promise<string> {
   const proc = Bun.spawn(
-    [
-      "docker",
-      "buildx",
-      "imagetools",
-      "inspect",
-      "--format",
-      "{{.Manifest.Digest}}",
-      image,
-    ],
+    ["docker", "buildx", "imagetools", "inspect", "--format", "{{.Manifest.Digest}}", image],
     { stdout: "pipe", stderr: "pipe" },
   );
   const [stdout, stderr, code] = await Promise.all([

package/src/docker/recipes/index.ts

@@ -3,13 +3,15 @@
  */
 
 import type { ImageRecipe } from "../types.ts";
+import { mailpit } from "./mailpit.ts";
 import { postgres } from "./postgres.ts";
 import { redis } from "./redis.ts";
+import { rustfs } from "./rustfs.ts";
 
 /** Default recipe catalogue. */
-export const builtinRecipes: readonly ImageRecipe[] = [postgres, redis];
+export const builtinRecipes: readonly ImageRecipe[] = [postgres, redis, mailpit, rustfs];
 
-export { postgres, redis };
+export { mailpit, postgres, redis, rustfs };
 
 /**
  * Resolve the recipe for an image reference.
@@ -17,10 +19,7 @@ export { postgres, redis };
  * @param image - Image pin
  * @param extra - Plugin / test recipes (tried first)
  */
-export function recipeFor(
-  image: string,
-  extra: readonly ImageRecipe[] = [],
-): ImageRecipe {
+export function recipeFor(image: string, extra: readonly ImageRecipe[] = []): ImageRecipe {
   for (const r of extra) {
     if (r.match(image)) return r;
   }

package/src/docker/recipes/mailpit.ts

@@ -0,0 +1,22 @@
+/**
+ * Mailpit image recipe — local SMTP catcher for docker ≈ prod email.
+ */
+
+import type { ImageRecipe } from "../types.ts";
+
+/** SMTP catcher (Mailpit) — UI on 8025. */
+export const mailpit: ImageRecipe = {
+  id: "mailpit",
+  port: 1025,
+  match: (i) => /mailpit/i.test(i),
+  apply: () => ({
+    extraPorts: [{ host: 8025, container: 8025 }],
+    healthcheck: {
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:8025/api/v1/info || exit 1"],
+      interval: "5s",
+      timeout: "3s",
+      retries: 10,
+    },
+  }),
+  url: (_s, c) => `smtp://${c.host}:${c.port}`,
+};

package/src/docker/recipes/postgres.ts

@@ -3,16 +3,27 @@
  */
 
 import { credEnv } from "../helpers.ts";
-import type { ImageRecipe } from "../types.ts";
+import type { ImageRecipe, ServiceSpec } from "../types.ts";
+
+const postgresEnv = (s: ServiceSpec) => ({
+  POSTGRES_USER: credEnv(s, "USER"),
+  POSTGRES_PASSWORD: credEnv(s, "PASSWORD"),
+  POSTGRES_DB: credEnv(s, "DB"),
+});
+
+const postgresHealth = {
+  test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER"],
+  interval: "5s",
+  timeout: "3s",
+  retries: 10,
+};
 
 /** Postgres-protocol servers (Postgres · Neon · Supabase · pgvector · Timescale). */
 export const postgres: ImageRecipe = {
   id: "postgres",
   port: 5432,
   match: (i) => /postgres|pgvector|timescale/i.test(i),
-  apply: (s) => ({
-    environment: { POSTGRES_USER: credEnv(s, "USER"), POSTGRES_PASSWORD: credEnv(s, "PASSWORD"), POSTGRES_DB: credEnv(s, "DB") },
-    healthcheck: { test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER"], interval: "5s", timeout: "3s", retries: 10 },
-  }),
-  url: (_s, c) => `postgres://${c.user}:${encodeURIComponent(c.password)}@${c.host}:${c.port}/${c.database}`,
+  apply: (s) => ({ environment: postgresEnv(s), healthcheck: postgresHealth }),
+  url: (_s, c) =>
+    `postgres://${c.user}:${encodeURIComponent(c.password)}@${c.host}:${c.port}/${c.database}`,
 };

package/src/docker/recipes/redis.ts

@@ -12,7 +12,12 @@ export const redis: ImageRecipe = {
   match: (i) => /redis|valkey|dragonfly|keydb/i.test(i),
   apply: (s) => ({
     command: ["redis-server", "--requirepass", credEnv(s, "PASSWORD")],
-    healthcheck: { test: ["CMD", "redis-cli", "-a", credEnv(s, "PASSWORD"), "ping"], interval: "5s", timeout: "3s", retries: 10 },
+    healthcheck: {
+      test: ["CMD", "redis-cli", "-a", credEnv(s, "PASSWORD"), "ping"],
+      interval: "5s",
+      timeout: "3s",
+      retries: 10,
+    },
   }),
   url: (_s, c) => `redis://:${encodeURIComponent(c.password)}@${c.host}:${c.port}`,
 };

package/src/docker/recipes/rustfs.ts

@@ -0,0 +1,33 @@
+/**
+ * RustFS image recipe — S3-compatible object store (Apache 2.0 MinIO alternative).
+ */
+
+import { credEnv } from "../helpers.ts";
+import type { ImageRecipe } from "../types.ts";
+
+/** S3-protocol object storage (RustFS). Console on 9001. */
+export const rustfs: ImageRecipe = {
+  id: "rustfs",
+  port: 9000,
+  match: (i) => /rustfs/i.test(i),
+  apply: (s) => ({
+    environment: {
+      RUSTFS_ACCESS_KEY: credEnv(s, "USER"),
+      RUSTFS_SECRET_KEY: credEnv(s, "PASSWORD"),
+      RUSTFS_CONSOLE_ENABLE: "true",
+      RUSTFS_ADDRESS: ":9000",
+    },
+    command: ["/data"],
+    volumes: [`${s.serviceName}-data:/data`],
+    extraPorts: [{ host: 9001, container: 9001 }],
+    healthcheck: {
+      test: ["CMD-SHELL", "curl -f http://127.0.0.1:9000/health || exit 1"],
+      interval: "5s",
+      timeout: "5s",
+      retries: 12,
+      start_period: "10s",
+    },
+  }),
+  url: (_s, c) =>
+    `http://${encodeURIComponent(c.user)}:${encodeURIComponent(c.password)}@${c.host}:${c.port}/${c.database}`,
+};

package/src/docker/stack-id.test.ts

@@ -5,6 +5,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   hostPortForInstance,
+  instancePortOffset,
   parseStackCredentials,
   stackAppSlug,
   stackInstanceId,
@@ -83,4 +84,36 @@ describe("deriveInfrastructure instanceId", () => {
     expect(result.stackEnv.DATABASE_URL).toMatch(/:15\d{3}\//);
     expect(result.stackEnv.REDIS_URL).toMatch(/:16\d{3}/);
   });
+
+  test("offsets Mailpit UI and RustFS console so stacks do not share 8025/9001", () => {
+    const id = "abcd12";
+    const n = instancePortOffset(id);
+    const result = deriveInfrastructure({
+      images: {
+        "channel.email": "axllent/mailpit:v1.22.3",
+        "store.files": "rustfs/rustfs:1.0.0-beta.11",
+      },
+      app: `dev-${id}`,
+      instanceId: id,
+      includeApp: false,
+      credentials: {
+        "channel.email": {
+          user: "oke",
+          password: "stack-id-test-mail-password",
+          database: "oke",
+        },
+        "store.files": {
+          user: "oke",
+          password: "stack-id-test-files-password",
+          database: "oke",
+        },
+      },
+    });
+    const mailYml = result.files.find((f) => f.path === "compose.channel.email.yml")!.content;
+    const filesYml = result.files.find((f) => f.path === "compose.store.files.yml")!.content;
+    expect(mailYml).toContain(`${8025 + n}:8025`);
+    expect(mailYml).not.toContain("8025:8025");
+    expect(filesYml).toContain(`${9001 + n}:9001`);
+    expect(filesYml).not.toContain("9001:9001");
+  });
 });