okengine 0.2.6 → 0.3.2

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,16 @@
  */
 
 import type { ImageRecipe } from "../types.ts";
+import { mailpit } from "./mailpit.ts";
+import { openbao } from "./openbao.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, openbao];
 
-export { postgres, redis };
+export { mailpit, openbao, postgres, redis, rustfs };
 
 /**
  * Resolve the recipe for an image reference.
@@ -17,10 +20,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/openbao.ts

@@ -0,0 +1,47 @@
+/**
+ * OpenBao image recipe — durable single-node secrets service (Raft storage).
+ *
+ * Never `-dev`: data lives on a named volume under `/openbao/data`; init +
+ * unseal is handled by the CLI bootstrap (keys stay on the host).
+ */
+
+import type { ImageRecipe } from "../types.ts";
+
+/**
+ * Server config passed via `BAO_LOCAL_CONFIG` (official image). Single-node
+ * Raft still requires `cluster_addr` / `api_addr` per the OpenBao docs.
+ */
+const OPENBAO_LOCAL_CONFIG = JSON.stringify({
+  listener: { tcp: { address: "0.0.0.0:8200", tls_disable: true } },
+  // Raft under /openbao/file — the stock entrypoint chowns that dir for the
+  // `openbao` user; a root-owned fresh named volume stays writable. Raft does
+  // not create nested dirs, so the path must be the chowned dir itself.
+  storage: { raft: { path: "/openbao/file", node_id: "oke" } },
+  api_addr: "http://0.0.0.0:8200",
+  cluster_addr: "http://127.0.0.1:8201",
+  disable_mlock: true,
+});
+
+/** OpenBao secrets service. API on 8200. */
+export const openbao: ImageRecipe = {
+  id: "openbao",
+  port: 8200,
+  match: (i) => /openbao/i.test(i),
+  apply: (s) => ({
+    environment: {
+      BAO_LOCAL_CONFIG: OPENBAO_LOCAL_CONFIG,
+    },
+    command: ["server"],
+    volumes: [`${s.serviceName}-data:/openbao/file`],
+    healthcheck: {
+      // `/sys/init` answers 200 even while sealed — only proves the server
+      // process is up; bootstrap owns the real unseal step.
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8200/v1/sys/init >/dev/null 2>&1 || exit 1"],
+      interval: "5s",
+      timeout: "5s",
+      retries: 12,
+      start_period: "5s",
+    },
+  }),
+  url: (_s, c) => `http://${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

@@ -11,8 +11,17 @@ export const redis: ImageRecipe = {
   port: 6379,
   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 },
+    command: [
+      "sh",
+      "-c",
+      'exec redis-server --requirepass "$$OKE_STORE_KV_PASSWORD" --maxmemory "$${OKE_STORE_KV_MAXMEMORY:-0}" --maxmemory-policy "$${OKE_STORE_KV_MAXMEMORY_POLICY:-noeviction}"',
+    ],
+    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,32 @@
+/**
+ * RustFS image recipe — S3-compatible object store (Apache 2.0 MinIO alternative).
+ */
+
+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: "${S3_ACCESS_KEY_ID}",
+      RUSTFS_SECRET_KEY: "${S3_SECRET_ACCESS_KEY}",
+      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

@@ -4,7 +4,10 @@
 
 import { describe, expect, test } from "bun:test";
 import {
+  extraHostPortForInstance,
   hostPortForInstance,
+  instancePortOffset,
+  parseStackControls,
   parseStackCredentials,
   stackAppSlug,
   stackInstanceId,
@@ -28,14 +31,23 @@ describe("stackInstanceId", () => {
 });
 
 describe("hostPortForInstance", () => {
-  test("offsets sql and kv into separate ranges", () => {
+  test("assigns built-in roles disjoint per-project ranges", () => {
     const id = "abcd12";
+    const n = instancePortOffset(id);
     const sql = hostPortForInstance("store.sql", 5432, id);
     const kv = hostPortForInstance("store.kv", 6379, id);
-    expect(sql).toBeGreaterThanOrEqual(15_000);
-    expect(sql).toBeLessThan(16_000);
-    expect(kv).toBeGreaterThanOrEqual(16_000);
-    expect(kv).toBeLessThan(17_000);
+    const files = hostPortForInstance("store.files", 9000, id);
+    const filesConsole = extraHostPortForInstance("store.files", 9001, id);
+    const email = hostPortForInstance("channel.email", 1025, id);
+    const emailUi = extraHostPortForInstance("channel.email", 8025, id);
+    expect([sql, kv, files, filesConsole, email, emailUi]).toEqual([
+      15_000 + n,
+      16_000 + n,
+      18_000 + n,
+      19_000 + n,
+      20_000 + n,
+      21_000 + n,
+    ]);
   });
 });
 
@@ -53,6 +65,26 @@ OKE_STORE_KV_DB=oke
     expect(creds["store.sql"]?.password).toBe("s3cret");
     expect(creds["store.kv"]?.password).toBe("kvpass");
   });
+
+  test("reads service-specific S3 credentials and optional controls", () => {
+    const text = `
+S3_ACCESS_KEY_ID=files-key
+S3_SECRET_ACCESS_KEY=files-secret
+S3_REGION=eu-central-1
+OKE_STORE_KV_MAXMEMORY=512mb
+# SMTP_USER=commented-out
+`;
+    const creds = parseStackCredentials(text, ["store.files"]);
+    expect(creds["store.files"]).toEqual({
+      user: "files-key",
+      password: "files-secret",
+      database: "oke",
+    });
+    expect(parseStackControls(text)).toEqual({
+      OKE_STORE_KV_MAXMEMORY: "512mb",
+      S3_REGION: "eu-central-1",
+    });
+  });
 });
 
 describe("deriveInfrastructure instanceId", () => {
@@ -83,4 +115,40 @@ 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", () => {
+    // Regression: offset 975 previously mapped Mailpit's 8025 UI onto RustFS's 9000 API.
+    const id = "a3f791";
+    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(`${20_000 + n}:1025`);
+    expect(mailYml).toContain(`${21_000 + n}:8025`);
+    expect(mailYml).not.toContain("8025:8025");
+    expect(filesYml).toContain(`${18_000 + n}:9000`);
+    expect(filesYml).toContain(`${19_000 + n}:9001`);
+    expect(filesYml).not.toContain("9001:9001");
+    expect(mailYml).not.toContain("9000:8025");
+  });
 });

package/src/docker/stack-id.ts

@@ -1,13 +1,14 @@
 /**
  * Per-project local stack identity — unique compose project + host ports.
  *
- * `oke dev --stack` must not share one `oke-dev` Postgres across every app on
+ * `oke dev --docker` must not share one `oke-dev` Postgres across every app on
  * the machine. Identity is a stable short hash of the project cwd.
  */
 
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import type { ServiceCredentials } from "./types.ts";
+import { DEFAULT_DOCKER_DIR } from "./types.ts";
 import { defaultHostPort, envPrefix } from "./helpers.ts";
 
 /**
@@ -16,10 +17,7 @@ import { defaultHostPort, envPrefix } from "./helpers.ts";
  * @param cwd - Project root
  */
 export function stackInstanceId(cwd: string): string {
-  return createHash("sha256")
-    .update(resolve(cwd))
-    .digest("hex")
-    .slice(0, 6);
+  return createHash("sha256").update(resolve(cwd)).digest("hex").slice(0, 6);
 }
 
 /**
@@ -31,6 +29,15 @@ export function stackAppSlug(cwd: string): string {
   return `dev-${stackInstanceId(cwd)}`;
 }
 
+/**
+ * Stable 0–999 offset derived from a stack instance id.
+ *
+ * @param instanceId - 6-hex stack id
+ */
+export function instancePortOffset(instanceId: string): number {
+  return Number.parseInt(instanceId.slice(0, 4), 16) % 1000;
+}
+
 /**
  * Host port for a role, offset by instance id so two stacks can run at once.
  *
@@ -43,15 +50,39 @@ export function hostPortForInstance(
   containerPort: number,
   instanceId: string,
 ): number {
-  const n = Number.parseInt(instanceId.slice(0, 4), 16) % 1000;
+  const n = instancePortOffset(instanceId);
   if (role === "store.sql") return 15_000 + n;
   if (role === "store.kv") return 16_000 + n;
   if (role === "signal") return 17_000 + n;
+  if (role === "store.files") return 18_000 + n;
+  if (role === "channel.email") return 20_000 + n;
+  if (role === "vault") return 22_000 + n;
   return defaultHostPort(role, containerPort) + n;
 }
 
 /**
- * Parse role credentials from an existing `.env.stack` body (reuse on restart).
+ * Host port for a recipe's additional published port.
+ *
+ * Built-in roles use disjoint ranges so an offset cannot move Mailpit's UI
+ * onto RustFS's API port (for example, `8025 + 975 = 9000`).
+ *
+ * @param role - Role key
+ * @param hostPort - Recipe's default additional host port
+ * @param instanceId - 6-hex stack id
+ */
+export function extraHostPortForInstance(
+  role: string,
+  hostPort: number,
+  instanceId: string,
+): number {
+  const n = instancePortOffset(instanceId);
+  if (role === "store.files") return 19_000 + n;
+  if (role === "channel.email") return 21_000 + n;
+  return hostPort + n;
+}
+
+/**
+ * Parse role credentials from an existing `.env.docker` body (reuse on restart).
  *
  * @param text - Dotenv contents
  * @param roles - Roles to look up
@@ -60,29 +91,16 @@ export function parseStackCredentials(
   text: string,
   roles: readonly string[],
 ): Record<string, ServiceCredentials> {
-  const map = new Map<string, string>();
-  for (const line of text.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const eq = trimmed.indexOf("=");
-    if (eq <= 0) continue;
-    const key = trimmed.slice(0, eq);
-    let value = trimmed.slice(eq + 1);
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
-    }
-    map.set(key, value);
-  }
-
+  const map = parseDotenv(text);
   const out: Record<string, ServiceCredentials> = {};
   for (const role of roles) {
     const prefix = envPrefix(role);
-    const user = map.get(`${prefix}_USER`);
-    const password = map.get(`${prefix}_PASSWORD`);
-    const database = map.get(`${prefix}_DB`);
+    const user =
+      map.get(`${prefix}_USER`) ?? (role === "store.files" ? map.get("S3_ACCESS_KEY_ID") : "oke");
+    const password =
+      map.get(`${prefix}_PASSWORD`) ??
+      (role === "store.files" ? map.get("S3_SECRET_ACCESS_KEY") : undefined);
+    const database = map.get(`${prefix}_DB`) ?? "oke";
     if (user && password && database) {
       out[role] = { user, password, database };
     }
@@ -90,8 +108,40 @@ export function parseStackCredentials(
   return out;
 }
 
+/** Optional `.env.docker` keys preserved when generated files refresh. */
+export const STACK_CONTROL_KEYS = [
+  "PGDATA",
+  "POSTGRES_INITDB_ARGS",
+  "OKE_STORE_KV_MAXMEMORY",
+  "OKE_STORE_KV_MAXMEMORY_POLICY",
+  "S3_REGION",
+  "S3_SESSION_TOKEN",
+  "SMTP_USER",
+  "SMTP_PASSWORD",
+  "MP_MAX_MESSAGES",
+  "MP_SMTP_AUTH_ACCEPT_ANY",
+  "MP_SMTP_AUTH_ALLOW_INSECURE",
+] as const;
+
 /**
- * Load credentials from project `.env.stack` when present.
+ * Read supported user controls from an existing `.env.docker`.
+ *
+ * @param text - Dotenv contents
+ */
+export function parseStackControls(text: string): Record<string, string> {
+  const parsed = parseDotenv(text);
+  return Object.fromEntries(
+    STACK_CONTROL_KEYS.flatMap((key) => {
+      const value = parsed.get(key);
+      return value === undefined ? [] : [[key, value]];
+    }),
+  );
+}
+
+/**
+ * Load credentials from `docker/.env.docker` when present.
+ *
+ * Soft-compat: also reads legacy project-root `.env.docker`.
  *
  * @param cwd - Project root
  * @param roles - Image roles
@@ -100,9 +150,50 @@ export async function loadExistingStackCredentials(
   cwd: string,
   roles: readonly string[],
 ): Promise<Readonly<Record<string, ServiceCredentials>> | undefined> {
-  const path = resolve(cwd, ".env.stack");
-  const file = Bun.file(path);
-  if (!(await file.exists())) return undefined;
-  const parsed = parseStackCredentials(await file.text(), roles);
-  return Object.keys(parsed).length > 0 ? parsed : undefined;
+  const candidates = [resolve(cwd, DEFAULT_DOCKER_DIR, ".env.docker"), resolve(cwd, ".env.docker")];
+  for (const path of candidates) {
+    const file = Bun.file(path);
+    if (!(await file.exists())) continue;
+    const parsed = parseStackCredentials(await file.text(), roles);
+    if (Object.keys(parsed).length > 0) return parsed;
+  }
+  return undefined;
+}
+
+/**
+ * Load optional controls from `docker/.env.docker` when present.
+ *
+ * @param cwd - Project root
+ */
+export async function loadExistingStackControls(
+  cwd: string,
+): Promise<Readonly<Record<string, string>> | undefined> {
+  const candidates = [resolve(cwd, DEFAULT_DOCKER_DIR, ".env.docker"), resolve(cwd, ".env.docker")];
+  for (const path of candidates) {
+    const file = Bun.file(path);
+    if (!(await file.exists())) continue;
+    const controls = parseStackControls(await file.text());
+    if (Object.keys(controls).length > 0) return controls;
+  }
+  return undefined;
+}
+
+function parseDotenv(text: string): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq);
+    let value = trimmed.slice(eq + 1);
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    map.set(key, value);
+  }
+  return map;
 }

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

@@ -6,11 +6,7 @@ import { describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import {
-  deriveInfrastructure,
-  formatStackEnv,
-  writeDerivedFiles,
-} from "./index.ts";
+import { deriveInfrastructure, formatStackEnv, writeDerivedFiles } from "./index.ts";
 
 async function dockerAvailable(): Promise<boolean> {
   try {
@@ -24,7 +20,7 @@ async function dockerAvailable(): Promise<boolean> {
   }
 }
 
-describe("oke dev --stack postgres integration", () => {
+describe("oke dev --docker postgres integration", () => {
   test("compose brings up postgres and the app talks to it", async () => {
     if (!(await dockerAvailable())) {
       console.warn("skipping: docker daemon not available");
@@ -51,21 +47,12 @@ describe("oke dev --stack postgres integration", () => {
       });
       await writeDerivedFiles(derived, dockerDir, {
         writeStackEnv: true,
-        stackEnvDir: dir,
       });
 
       // Infra-only: network + role compose (no app build).
       const composeFiles = ["compose.yml", "compose.store.sql.yml"];
       const up = Bun.spawn(
-        [
-          "docker",
-          "compose",
-          "-p",
-          project,
-          ...composeFiles.flatMap((f) => ["-f", f]),
-          "up",
-          "-d",
-        ],
+        ["docker", "compose", "-p", project, ...composeFiles.flatMap((f) => ["-f", f]), "up", "-d"],
         {
           cwd: dockerDir,
           stdout: "pipe",
@@ -120,13 +107,11 @@ describe("oke dev --stack postgres integration", () => {
         await sql.close();
       }
 
-      // Prove credentials live in .env.stack, not YAML.
+      // Prove credentials live in docker/.env.docker, not YAML.
       const yml = await Bun.file(join(dockerDir, "compose.store.sql.yml")).text();
       expect(yml).not.toContain("stack-integration-pass");
-      expect(formatStackEnv(derived.stackEnv)).toContain(
-        "stack-integration-pass",
-      );
-      expect(await Bun.file(join(dir, ".env.stack")).exists()).toBe(true);
+      expect(formatStackEnv(derived.stackEnv)).toContain("stack-integration-pass");
+      expect(await Bun.file(join(dockerDir, ".env.docker")).exists()).toBe(true);
     } finally {
       await Bun.spawn(
         [

package/src/docker/stack.ts

@@ -4,8 +4,15 @@
 
 import { buildSpecs } from "./compose.ts";
 import { recipeFor } from "./recipes/index.ts";
+import { extraHostPortForInstance } from "./stack-id.ts";
 import type { DeriveOptions, ServiceSpec } from "./types.ts";
 
+/** Extra published host↔container mapping for stack preview. */
+export interface StackExtraPort {
+  readonly hostPort: number;
+  readonly containerPort: number;
+}
+
 /** One resolved stack row for preview. */
 export interface StackRow {
   readonly role: string;
@@ -14,12 +21,14 @@ export interface StackRow {
   readonly service: string;
   readonly containerPort: number;
   readonly hostPort: number;
+  /** Additional published ports (Mailpit UI, RustFS console, …). */
+  readonly extraPorts: readonly StackExtraPort[];
 }
 
 /**
  * Resolve stack preview rows from image pins.
  *
- * @param options - Images (+ optional recipes)
+ * @param options - Images (+ optional recipes / instanceId)
  */
 export function resolveStack(options: DeriveOptions): readonly StackRow[] {
   const specs = buildSpecs(options);
@@ -38,13 +47,35 @@ export function formatStackPreview(rows: readonly StackRow[]): string {
     "--------------  ---------  ---------------------------------  --------------",
   ];
   for (const r of rows) {
-    lines.push(
-      `${pad(r.role, 14)}  ${pad(r.recipe, 9)}  ${pad(r.image, 33)}  ${r.hostPort}:${r.containerPort}`,
-    );
+    const ports = [
+      `${r.hostPort}:${r.containerPort}`,
+      ...r.extraPorts.map((p) => `${p.hostPort}:${p.containerPort}`),
+    ].join(", ");
+    lines.push(`${pad(r.role, 14)}  ${pad(r.recipe, 9)}  ${pad(r.image, 33)}  ${ports}`);
   }
   return `${lines.join("\n")}\n`;
 }
 
+/**
+ * Resolve additional published ports for a service (instance-aware).
+ *
+ * @param spec - Normalised service
+ * @param options - Derive options
+ */
+export function resolveExtraPorts(
+  spec: ServiceSpec,
+  options: DeriveOptions,
+): readonly StackExtraPort[] {
+  const recipe = recipeFor(spec.image, options.recipes ?? []);
+  const applied = recipe.apply(spec);
+  return (applied.extraPorts ?? []).map((p) => ({
+    containerPort: p.container,
+    hostPort: options.instanceId
+      ? extraHostPortForInstance(spec.role, p.host, options.instanceId)
+      : p.host,
+  }));
+}
+
 function toRow(spec: ServiceSpec, options: DeriveOptions): StackRow {
   const recipe = recipeFor(spec.image, options.recipes ?? []);
   return {
@@ -54,6 +85,7 @@ function toRow(spec: ServiceSpec, options: DeriveOptions): StackRow {
     service: spec.serviceName,
     containerPort: spec.port,
     hostPort: spec.hostPort,
+    extraPorts: resolveExtraPorts(spec, options),
   };
 }