okengine 0.2.6 → 0.3.2

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 { extraHostPortForInstance, hostPortForInstance, STACK_CONTROL_KEYS } 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)
@@ -119,22 +113,36 @@ export function emitComposeLayers(
   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) => {
+        const hostPort = options.instanceId
+          ? extraHostPortForInstance(spec.role, p.host, options.instanceId)
+          : p.host;
+        return `${hostPort}:${p.container}`;
+      }),
+    ];
     const service: Record<string, unknown> = {
       image: spec.image,
-      ports: [`${spec.hostPort}:${spec.port}`],
+      ports,
       networks: ["oke"],
       env_file: [paths.envFile],
     };
     if (applied.environment) service.environment = applied.environment;
     if (applied.command) service.command = applied.command;
+    if (applied.entrypoint) service.entrypoint = applied.entrypoint;
     if (applied.healthcheck) service.healthcheck = applied.healthcheck;
     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 +189,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
@@ -191,13 +199,12 @@ export function buildStackEnv(
   specs: readonly ServiceSpec[],
   recipes: readonly ImageRecipe[] = [],
   host = "127.0.0.1",
+  controls: Readonly<Record<string, string>> = {},
+  instanceId?: string,
 ): Record<string, string> {
   const env: Record<string, string> = {};
   for (const spec of specs) {
     const prefix = envPrefix(spec.role);
-    env[`${prefix}_USER`] = spec.credentials.user;
-    env[`${prefix}_PASSWORD`] = spec.credentials.password;
-    env[`${prefix}_DB`] = spec.credentials.database;
     const recipe = recipeFor(spec.image, recipes);
     const url = recipe.url(spec, {
       host,
@@ -206,25 +213,189 @@ export function buildStackEnv(
       password: spec.credentials.password,
       database: spec.credentials.database,
     });
-    env[`${prefix}_URL`] = url;
-    // Friendly alias for the common sql role
-    if (spec.role === "store.sql") env.DATABASE_URL = url;
-    if (spec.role === "store.kv") env.REDIS_URL = url;
+    const applied = recipe.apply(spec);
+    const uiExtra = applied.extraPorts?.[0];
+    const uiHost =
+      uiExtra === undefined
+        ? undefined
+        : instanceId
+          ? extraHostPortForInstance(spec.role, uiExtra.host, instanceId)
+          : uiExtra.host;
+    if (spec.role === "store.sql") {
+      env[`${prefix}_USER`] = spec.credentials.user;
+      env[`${prefix}_PASSWORD`] = spec.credentials.password;
+      env[`${prefix}_DB`] = spec.credentials.database;
+      env[`${prefix}_URL`] = url;
+      env.DATABASE_URL = url;
+    } else if (spec.role === "store.kv") {
+      env[`${prefix}_PASSWORD`] = spec.credentials.password;
+      env[`${prefix}_URL`] = url;
+      env.REDIS_URL = url;
+    } else if (spec.role === "store.files") {
+      env[`${prefix}_URL`] = url;
+      env.S3_ACCESS_KEY_ID = spec.credentials.user;
+      env.S3_SECRET_ACCESS_KEY = spec.credentials.password;
+      env.S3_BUCKET = spec.credentials.database;
+      env.S3_URL = url;
+      env.S3_ENDPOINT = new URL(url).origin;
+      env.S3_REGION = "us-east-1";
+      if (uiHost !== undefined) env.S3_CONSOLE_URL = `http://${host}:${uiHost}`;
+    } else if (spec.role === "channel.email") {
+      env[`${prefix}_URL`] = url;
+      env.SMTP_URL = url;
+      env.SMTP_HOST = host;
+      env.SMTP_PORT = String(spec.hostPort);
+      if (uiHost !== undefined) env.MAILPIT_UI_URL = `http://${host}:${uiHost}`;
+    } else if (spec.role === "vault") {
+      // Token is minted by the bootstrap — never a generated password here.
+      env[`${prefix}_URL`] = url;
+      env.OKE_VAULT_URL = url;
+    } else {
+      env[`${prefix}_USER`] = spec.credentials.user;
+      env[`${prefix}_PASSWORD`] = spec.credentials.password;
+      env[`${prefix}_DB`] = spec.credentials.database;
+      env[`${prefix}_URL`] = url;
+    }
+  }
+  for (const key of STACK_CONTROL_KEYS) {
+    const value = controls[key];
+    if (value !== undefined) env[key] = value;
   }
   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",
+  vault: "vault — OpenBao",
+};
+
+/** Friendly aliases emitted beside their role block. */
+const ROLE_ALIASES: Readonly<Record<string, readonly string[]>> = {
+  "store.sql": ["DATABASE_URL", "PGDATA", "POSTGRES_INITDB_ARGS"],
+  "store.kv": ["REDIS_URL", "OKE_STORE_KV_MAXMEMORY", "OKE_STORE_KV_MAXMEMORY_POLICY"],
+  "store.files": [
+    "S3_ACCESS_KEY_ID",
+    "S3_SECRET_ACCESS_KEY",
+    "S3_BUCKET",
+    "S3_URL",
+    "S3_ENDPOINT",
+    "S3_CONSOLE_URL",
+    "S3_REGION",
+    "S3_SESSION_TOKEN",
+  ],
+  "channel.email": [
+    "SMTP_URL",
+    "SMTP_HOST",
+    "SMTP_PORT",
+    "MAILPIT_UI_URL",
+    "SMTP_USER",
+    "SMTP_PASSWORD",
+    "MP_MAX_MESSAGES",
+    "MP_SMTP_AUTH_ACCEPT_ANY",
+    "MP_SMTP_AUTH_ALLOW_INSECURE",
+  ],
+};
+
+/** Optional controls documented in `.env.docker` and preserved on regeneration. */
+const ROLE_CONTROL_EXAMPLES: Readonly<Record<string, readonly string[]>> = {
+  "store.sql": ["PGDATA=/var/lib/postgresql/data/pgdata", "POSTGRES_INITDB_ARGS=--data-checksums"],
+  "store.kv": ["OKE_STORE_KV_MAXMEMORY=256mb", "OKE_STORE_KV_MAXMEMORY_POLICY=allkeys-lru"],
+  "store.files": ["S3_SESSION_TOKEN="],
+  "channel.email": [
+    "SMTP_USER=",
+    "SMTP_PASSWORD=",
+    "MP_MAX_MESSAGES=500",
+    "MP_SMTP_AUTH_ACCEPT_ANY=1",
+    "MP_SMTP_AUTH_ALLOW_INSECURE=1",
+  ],
+};
+
 /**
- * Serialise stack env to dotenv text.
+ * Infer role from an `OKE_<ROLE>_*` key (`OKE_STORE_SQL_URL` → `store.sql`).
  *
- * @param env - Key/value map
+ * @param key - Env key
+ */
+function roleFromEnvKey(key: string): string | undefined {
+  const m = /^OKE_(.+)_(USER|PASSWORD|DB|URL)$/.exec(key);
+  if (m) return m[1]!.toLowerCase().replaceAll("_", ".");
+  if (key.startsWith("S3_")) return "store.files";
+  if (key.startsWith("SMTP_") || key.startsWith("MP_") || key === "MAILPIT_UI_URL") {
+    return "channel.email";
+  }
+  if (key === "PGDATA" || key === "POSTGRES_INITDB_ARGS") return "store.sql";
+  if (key.startsWith("OKE_STORE_KV_MAXMEMORY")) return "store.kv";
+  return undefined;
+}
+
+/**
+ * Serialise stack env to commented, role-grouped dotenv text.
+ *
+ * @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 key of [`${prefix}_USER`, `${prefix}_PASSWORD`, `${prefix}_DB`, `${prefix}_URL`]) {
+      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);
+    }
+    const controls = ROLE_CONTROL_EXAMPLES[role] ?? [];
+    const inactive = controls.filter(
+      (example) => env[example.slice(0, example.indexOf("="))] === undefined,
+    );
+    if (inactive.length > 0) {
+      lines.push("# Optional controls (uncomment to override; preserved on regeneration):");
+      for (const example of inactive) lines.push(`# ${example}`);
+    }
+    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 +420,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 }),
@@ -61,6 +58,8 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
     specs,
     normalised.recipes ?? [],
     normalised.host ?? "127.0.0.1",
+    normalised.controls,
+    normalised.instanceId,
   );
 
   return { specs, files, stackEnv, composeFiles };
@@ -68,7 +67,7 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
 
 /**
  * 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 +78,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 +89,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,16 +186,89 @@ 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=");
   });
 
+  test("emits protocol-specific env keys plus optional control notes", () => {
+    const result = deriveInfrastructure({
+      images: {
+        "store.sql": "postgres:18-alpine",
+        "store.kv": "redis:8-alpine",
+        "store.files": "rustfs/rustfs:1.0.0-beta.11",
+        "channel.email": "axllent/mailpit:v1.22.3",
+      },
+      credentials: {
+        ...fixedCreds,
+        "store.files": {
+          user: "files-key",
+          password: "files-secret",
+          database: "oke",
+        },
+        "channel.email": {
+          user: "unused",
+          password: "unused-secret",
+          database: "oke",
+        },
+      },
+    });
+    expect(result.stackEnv.S3_ACCESS_KEY_ID).toBe("files-key");
+    expect(result.stackEnv.S3_SECRET_ACCESS_KEY).toBe("files-secret");
+    expect(result.stackEnv.S3_BUCKET).toBe("oke");
+    expect(result.stackEnv.S3_URL).toContain("http://files-key:");
+    expect(result.stackEnv.S3_ENDPOINT).toBe("http://127.0.0.1:9000");
+    expect(result.stackEnv.S3_CONSOLE_URL).toBe("http://127.0.0.1:9001");
+    expect(result.stackEnv.SMTP_URL).toBe("smtp://127.0.0.1:1025");
+    expect(result.stackEnv.SMTP_HOST).toBe("127.0.0.1");
+    expect(result.stackEnv.SMTP_PORT).toBe("1025");
+    expect(result.stackEnv.MAILPIT_UI_URL).toBe("http://127.0.0.1:8025");
+    expect(result.stackEnv.OKE_STORE_KV_PASSWORD).toBe(fixedCreds["store.kv"].password);
+    expect(result.stackEnv.OKE_STORE_KV_USER).toBeUndefined();
+    expect(result.stackEnv.OKE_STORE_KV_DB).toBeUndefined();
+    expect(result.stackEnv.OKE_CHANNEL_EMAIL_PASSWORD).toBeUndefined();
+
+    const text = formatStackEnv(result.stackEnv);
+    expect(text).toContain("# OKE_STORE_KV_MAXMEMORY=256mb");
+    expect(text).toContain("# S3_SESSION_TOKEN=");
+    expect(text).toContain("# SMTP_USER=");
+    expect(text).toContain("# POSTGRES_INITDB_ARGS=--data-checksums");
+  });
+
+  test("instance-offset UI aliases land in stack env", () => {
+    const id = "a3f791";
+    const n = Number.parseInt(id.slice(0, 4), 16) % 1000;
+    const result = deriveInfrastructure({
+      images: {
+        "channel.email": "axllent/mailpit:v1.22.3",
+        "store.files": "rustfs/rustfs:1.0.0-beta.11",
+      },
+      instanceId: id,
+      credentials: {
+        "channel.email": {
+          user: "oke",
+          password: "unused-mail-password",
+          database: "oke",
+        },
+        "store.files": {
+          user: "files-key",
+          password: "files-secret",
+          database: "oke",
+        },
+      },
+    });
+    expect(result.stackEnv.SMTP_PORT).toBe(String(20_000 + n));
+    expect(result.stackEnv.MAILPIT_UI_URL).toBe(`http://127.0.0.1:${21_000 + n}`);
+    expect(result.stackEnv.S3_ENDPOINT).toBe(`http://127.0.0.1:${18_000 + n}`);
+    expect(result.stackEnv.S3_CONSOLE_URL).toBe(`http://127.0.0.1:${19_000 + n}`);
+  });
+
   test("resolveStack previews without writing", () => {
     const rows = resolveStack({
       images: { "store.sql": "postgres:16" },
@@ -205,5 +277,36 @@ describe("deriveInfrastructure", () => {
     expect(rows).toHaveLength(1);
     expect(rows[0]!.recipe).toBe("postgres");
     expect(rows[0]!.hostPort).toBe(5432);
+    expect(rows[0]!.extraPorts).toEqual([]);
+  });
+
+  test("resolveStack includes instance-offset Mailpit UI / RustFS console", () => {
+    const id = "a3f791";
+    const n = Number.parseInt(id.slice(0, 4), 16) % 1000;
+    const rows = resolveStack({
+      images: {
+        "channel.email": "axllent/mailpit:v1.22.3",
+        "store.files": "rustfs/rustfs:1.0.0-beta.11",
+      },
+      instanceId: id,
+      credentials: {
+        "channel.email": {
+          user: "oke",
+          password: "stack-preview-mail-password",
+          database: "oke",
+        },
+        "store.files": {
+          user: "oke",
+          password: "stack-preview-files-password",
+          database: "oke",
+        },
+      },
+    });
+    const mail = rows.find((r) => r.role === "channel.email")!;
+    const files = rows.find((r) => r.role === "store.files")!;
+    expect(mail.hostPort).toBe(20_000 + n);
+    expect(mail.extraPorts).toEqual([{ hostPort: 21_000 + n, containerPort: 8025 }]);
+    expect(files.hostPort).toBe(18_000 + n);
+    expect(files.extraPorts).toEqual([{ hostPort: 19_000 + n, containerPort: 9001 }]);
   });
 });

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,21 +36,23 @@ 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 { builtinRecipes, mailpit, postgres, recipeFor, redis, rustfs } from "./recipes/index.ts";
 export {
   formatStackPreview,
+  resolveExtraPorts,
   resolveStack,
+  type StackExtraPort,
   type StackRow,
 } from "./stack.ts";
 export {
+  extraHostPortForInstance,
   hostPortForInstance,
+  instancePortOffset,
+  loadExistingStackControls,
   loadExistingStackCredentials,
+  parseStackControls,
   parseStackCredentials,
+  STACK_CONTROL_KEYS,
   stackAppSlug,
   stackInstanceId,
 } from "./stack-id.ts";