okengine 0.1.4

package/src/docker/compose.ts

@@ -0,0 +1,226 @@
+/**
+ * Four compose override layers ending in an untouched `compose.override.yml`.
+ *
+ * 1. `compose.yml`            — app + network (generated)
+ * 2. `compose.<role>.yml`     — per-role services (generated)
+ * 3. `compose.prod.yml`       — prod overlays (generated when `--prod`)
+ * 4. `compose.override.yml`   — user-owned; oke never writes it
+ */
+
+import {
+  defaultHostPort,
+  envPrefix,
+  serviceNameFor,
+  toYaml,
+} from "./helpers.ts";
+import { recipeFor } from "./recipes/index.ts";
+import type {
+  DeriveOptions,
+  GeneratedFile,
+  ImageRecipe,
+  ServiceCredentials,
+  ServiceSpec,
+} from "./types.ts";
+import { generateCredentials } from "./credentials.ts";
+import { APP_PORT } from "../runtime/types.ts";
+
+/** Canonical layer-4 filename — never written by derivation. */
+export const COMPOSE_OVERRIDE = "compose.override.yml";
+
+/**
+ * Build normalised {@link ServiceSpec} list from image pins.
+ *
+ * @param options - Derive options
+ */
+export function buildSpecs(options: DeriveOptions): ServiceSpec[] {
+  const recipes = options.recipes ?? [];
+  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 port = recipe.port;
+    specs.push({
+      role,
+      serviceName: serviceNameFor(role),
+      image,
+      port,
+      hostPort: defaultHostPort(role, port),
+      credentials: creds,
+    });
+  }
+  return specs.sort((a, b) => a.role.localeCompare(b.role));
+}
+
+/**
+ * Emit compose layers 1–3 (+ Dockerfile companion handled elsewhere).
+ *
+ * @param specs - Normalised services
+ * @param options - Derive options
+ */
+export function emitComposeLayers(
+  specs: readonly ServiceSpec[],
+  options: DeriveOptions,
+): { files: GeneratedFile[]; composeFiles: string[] } {
+  const recipes = options.recipes ?? [];
+  const appPort = options.appPort ?? APP_PORT;
+  const app = options.app ?? "app";
+  const files: GeneratedFile[] = [];
+
+  // Layer 1 — app + network
+  const base = {
+    name: `oke-${app}`,
+    services: {
+      app: {
+        build: { context: ".", dockerfile: "Dockerfile" },
+        ports: [`${appPort}:${appPort}`],
+        env_file: [".env.stack"],
+        depends_on: Object.fromEntries(
+          specs.map((s) => [s.serviceName, { condition: "service_healthy" }]),
+        ),
+        networks: ["oke"],
+      },
+    },
+    networks: { oke: { driver: "bridge" } },
+  };
+  files.push({ path: "compose.yml", content: `${toYaml(base)}\n` });
+
+  // Layer 2 — per-role
+  for (const spec of specs) {
+    const recipe = recipeFor(spec.image, recipes);
+    const applied = recipe.apply(spec);
+    const service: Record<string, unknown> = {
+      image: spec.image,
+      ports: [`${spec.hostPort}:${spec.port}`],
+      networks: ["oke"],
+      env_file: [".env.stack"],
+    };
+    if (applied.environment) service.environment = applied.environment;
+    if (applied.command) service.command = applied.command;
+    if (applied.healthcheck) service.healthcheck = applied.healthcheck;
+    if (applied.volumes) service.volumes = applied.volumes;
+    if (applied.user) service.user = applied.user;
+
+    const doc = {
+      services: { [spec.serviceName]: service },
+      networks: { oke: { external: false } },
+    };
+    const path = `compose.${spec.role}.yml`;
+    files.push({ path, content: `${toYaml(doc)}\n` });
+  }
+
+  // Layer 3 — prod overlay
+  if (options.prod) {
+    const prodServices: Record<string, unknown> = {
+      app: {
+        deploy: {
+          replicas: 1,
+          resources: {
+            limits: { cpus: "1.0", memory: "512M" },
+          },
+        },
+        secrets: specs.flatMap((s) => secretNames(s)),
+      },
+    };
+    for (const spec of specs) {
+      prodServices[spec.serviceName] = {
+        deploy: {
+          resources: {
+            limits: { cpus: "1.0", memory: "512M" },
+          },
+        },
+        secrets: secretNames(spec),
+      };
+    }
+    files.push({
+      path: "compose.prod.yml",
+      content: `${toYaml({ services: prodServices })}\n`,
+    });
+  }
+
+  // Layer 4 — never written. Document merge order only.
+  const composeFiles = [
+    "compose.yml",
+    ...specs.map((s) => `compose.${s.role}.yml`),
+    ...(options.prod ? ["compose.prod.yml"] : []),
+    COMPOSE_OVERRIDE,
+  ];
+
+  return { files, composeFiles };
+}
+
+/**
+ * Build `.env.stack` key/value map (credentials + connection URLs).
+ *
+ * @param specs - Services
+ * @param recipes - Extra recipes
+ * @param host - Hostname for URL builders
+ */
+export function buildStackEnv(
+  specs: readonly ServiceSpec[],
+  recipes: readonly ImageRecipe[] = [],
+  host = "127.0.0.1",
+): 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,
+      port: spec.hostPort,
+      user: spec.credentials.user,
+      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;
+  }
+  return env;
+}
+
+/**
+ * Serialise stack env to dotenv text.
+ *
+ * @param env - Key/value map
+ */
+export function formatStackEnv(env: Readonly<Record<string, string>>): string {
+  return (
+    Object.entries(env)
+      .map(([k, v]) => `${k}=${escapeEnv(v)}`)
+      .join("\n") + "\n"
+  );
+}
+
+/**
+ * Assert generated YAML contains no cleartext credential values.
+ *
+ * @param yaml - File content
+ * @param credentials - Values that must not appear
+ */
+export function assertNoCredentialsInYaml(
+  yaml: string,
+  credentials: Iterable<ServiceCredentials>,
+): void {
+  for (const c of credentials) {
+    if (yaml.includes(c.password)) {
+      throw new Error("oke docker: credential leaked into generated YAML");
+    }
+  }
+}
+
+function secretNames(spec: ServiceSpec): string[] {
+  const p = envPrefix(spec.role);
+  return [`${p}_PASSWORD`];
+}
+
+function escapeEnv(value: string): string {
+  if (/[\s#"'$\\]/.test(value)) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+  }
+  return value;
+}

package/src/docker/credentials.ts

@@ -0,0 +1,25 @@
+/**
+ * Credential generation for stack env — never written into compose YAML.
+ */
+
+import type { ServiceCredentials } from "./types.ts";
+
+/**
+ * Generate random credentials for a role.
+ *
+ * @param role - Role key (selects database name defaults)
+ */
+export function generateCredentials(role: string): ServiceCredentials {
+  const password = randomToken(24);
+  const database = role === "store.sql" ? "oke" : "oke";
+  return { user: "oke", password, database };
+}
+
+/**
+ * @param bytes - Entropy size
+ */
+function randomToken(bytes: number): string {
+  const buf = new Uint8Array(bytes);
+  crypto.getRandomValues(buf);
+  return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/docker/derive.ts

@@ -0,0 +1,83 @@
+/**
+ * Derive Dockerfile + compose files from config image pins.
+ */
+
+import {
+  assertNoCredentialsInYaml,
+  buildSpecs,
+  buildStackEnv,
+  emitComposeLayers,
+  formatStackEnv,
+} from "./compose.ts";
+import { emitDockerfile } from "./dockerfile.ts";
+import type { DeriveOptions, DeriveResult, GeneratedFile } from "./types.ts";
+
+/**
+ * Derive infrastructure files from normalised image pins.
+ *
+ * Credentials land only in the returned `stackEnv` (for `.env.stack`);
+ * generated YAML never contains cleartext secrets. Layer 4
+ * (`compose.override.yml`) is listed in `composeFiles` but never written.
+ *
+ * @param options - Images / app / prod flag
+ */
+export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
+  if (!options.images || Object.keys(options.images).length === 0) {
+    throw new Error("oke docker: no images configured — set `images` in oke.config.ts");
+  }
+
+  const specs = buildSpecs(options);
+  const { files: composeFilesContent, composeFiles } = emitComposeLayers(
+    specs,
+    options,
+  );
+  const dockerfile: GeneratedFile = {
+    path: "Dockerfile",
+    content: emitDockerfile({ appPort: options.appPort }),
+  };
+  const files = [dockerfile, ...composeFilesContent];
+
+  for (const f of files) {
+    if (f.path.endsWith(".yml") || f.path === "Dockerfile") {
+      assertNoCredentialsInYaml(
+        f.content,
+        specs.map((s) => s.credentials),
+      );
+    }
+  }
+
+  const stackEnv = buildStackEnv(
+    specs,
+    options.recipes ?? [],
+    options.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`.
+ *
+ * @param result - Derive result
+ * @param outDir - Destination
+ * @param options - Write controls
+ */
+export async function writeDerivedFiles(
+  result: DeriveResult,
+  outDir: string,
+  options: { readonly writeStackEnv?: boolean } = {},
+): Promise<readonly string[]> {
+  const written: string[] = [];
+  for (const file of result.files) {
+    const path = `${outDir.replace(/\/$/, "")}/${file.path}`;
+    await Bun.write(path, file.content);
+    written.push(path);
+  }
+  if (options.writeStackEnv) {
+    const envPath = `${outDir.replace(/\/$/, "")}/.env.stack`;
+    await Bun.write(envPath, formatStackEnv(result.stackEnv));
+    written.push(envPath);
+  }
+  return written;
+}

package/src/docker/docker.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Image recipes + compose derivation.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  COMPOSE_OVERRIDE,
+  assertNoCredentialsInYaml,
+  builtinRecipes,
+  deriveInfrastructure,
+  emitDockerfile,
+  formatStackEnv,
+  postgres,
+  recipeFor,
+  redis,
+  resolveStack,
+  writeDerivedFiles,
+  type ImageRecipe,
+  type ServiceSpec,
+} from "./index.ts";
+
+const fixedCreds = {
+  "store.sql": {
+    user: "oke",
+    password: "s3cret-sql-password-xyz",
+    database: "oke",
+  },
+  "store.kv": {
+    user: "oke",
+    password: "s3cret-kv-password-xyz",
+    database: "oke",
+  },
+} as const;
+
+describe("image recipes", () => {
+  test("postgres and redis match vendor images by protocol", () => {
+    expect(recipeFor("pgvector/pgvector:pg17").id).toBe("postgres");
+    expect(recipeFor("valkey/valkey:8-alpine").id).toBe("redis");
+    expect(postgres.match("postgres:16")).toBe(true);
+    expect(redis.match("redis:7")).toBe(true);
+  });
+
+  test("a new image recipe is ≤15 lines", async () => {
+    const src = await Bun.file(`${import.meta.dir}/recipes/postgres.ts`).text();
+    const exportLines = src
+      .slice(src.indexOf("export const"))
+      .split("\n")
+      .filter((l) => l.trim().length > 0);
+    expect(exportLines.length).toBeLessThanOrEqual(15);
+  });
+
+  test("recipe.url builds a connection string without env-var names in the kernel", () => {
+    const spec: ServiceSpec = {
+      role: "store.sql",
+      serviceName: "store-sql",
+      image: "postgres:16",
+      port: 5432,
+      hostPort: 5432,
+      credentials: fixedCreds["store.sql"],
+    };
+    const url = postgres.url(spec, {
+      host: "127.0.0.1",
+      port: 5432,
+      ...fixedCreds["store.sql"],
+    });
+    expect(url).toStartWith("postgres://oke:");
+    expect(url).toContain("@127.0.0.1:5432/oke");
+    expect(url).not.toContain("POSTGRES_");
+  });
+
+  test("plugin recipe can be registered in ≤15 lines", () => {
+    const nats: ImageRecipe = {
+      id: "nats",
+      port: 4222,
+      match: (i) => /nats/i.test(i),
+      apply: () => ({
+        command: ["--js"],
+        healthcheck: { test: ["CMD", "nats-server", "--signal", "ldm"], interval: "5s", timeout: "3s", retries: 5 },
+      }),
+      url: (_s, c) => `nats://${c.host}:${c.port}`,
+    };
+    const src = `export const nats: ImageRecipe = {
+  id: "nats",
+  port: 4222,
+  match: (i) => /nats/i.test(i),
+  apply: () => ({ command: ["--js"], healthcheck: { test: ["CMD", "nats-server", "--signal", "ldm"], interval: "5s", timeout: "3s", retries: 5 } }),
+  url: (_s, c) => \`nats://\${c.host}:\${c.port}\`,
+};`;
+    expect(src.trim().split("\n").length).toBeLessThanOrEqual(15);
+    expect(recipeFor("nats:2.10", [nats]).id).toBe("nats");
+    expect(builtinRecipes.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+describe("deriveInfrastructure", () => {
+  test("emits Dockerfile + per-role compose + four-layer merge order", () => {
+    const result = deriveInfrastructure({
+      images: {
+        "store.sql": "pgvector/pgvector:pg17",
+        "store.kv": "valkey/valkey:8-alpine",
+      },
+      credentials: fixedCreds,
+      app: "skyport",
+    });
+
+    const paths = result.files.map((f) => f.path);
+    expect(paths).toContain("Dockerfile");
+    expect(paths).toContain("compose.yml");
+    expect(paths).toContain("compose.store.sql.yml");
+    expect(paths).toContain("compose.store.kv.yml");
+    expect(paths).not.toContain(COMPOSE_OVERRIDE);
+
+    expect(result.composeFiles).toEqual([
+      "compose.yml",
+      "compose.store.kv.yml",
+      "compose.store.sql.yml",
+      COMPOSE_OVERRIDE,
+    ]);
+
+    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).not.toContain(fixedCreds["store.sql"].password);
+
+    for (const f of result.files) {
+      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,
+    );
+  });
+
+  test("prod overlay adds deploy.replicas and is layer 3", () => {
+    const result = deriveInfrastructure({
+      images: { "store.sql": "postgres:16" },
+      credentials: { "store.sql": fixedCreds["store.sql"] },
+      prod: true,
+    });
+    expect(result.files.some((f) => f.path === "compose.prod.yml")).toBe(true);
+    expect(result.composeFiles).toContain("compose.prod.yml");
+    expect(result.composeFiles.at(-1)).toBe(COMPOSE_OVERRIDE);
+    const prod = result.files.find((f) => f.path === "compose.prod.yml")!.content;
+    expect(prod).toContain("replicas");
+  });
+
+  test("Dockerfile CMD is oke start", () => {
+    const df = emitDockerfile();
+    expect(df).toContain('CMD ["oke", "start"]');
+    expect(df).toContain("oven/bun:1.3");
+  });
+
+  test("writeDerivedFiles never writes compose.override.yml", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-docker-"));
+    const result = deriveInfrastructure({
+      images: { "store.sql": "postgres:16" },
+      credentials: { "store.sql": fixedCreds["store.sql"] },
+    });
+    const written = await writeDerivedFiles(result, dir, { writeStackEnv: true });
+    expect(written.some((p) => p.endsWith(COMPOSE_OVERRIDE))).toBe(false);
+    expect(await Bun.file(join(dir, ".env.stack")).exists()).toBe(true);
+    const envText = await Bun.file(join(dir, ".env.stack")).text();
+    expect(envText).toContain("DATABASE_URL=");
+    expect(formatStackEnv(result.stackEnv)).toContain("OKE_STORE_SQL_PASSWORD=");
+  });
+
+  test("resolveStack previews without writing", () => {
+    const rows = resolveStack({
+      images: { "store.sql": "postgres:16" },
+      credentials: { "store.sql": fixedCreds["store.sql"] },
+    });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!.recipe).toBe("postgres");
+    expect(rows[0]!.hostPort).toBe(5432);
+  });
+});

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

@@ -0,0 +1,170 @@
+/**
+ * Integration: generated Dockerfile builds (and optionally runs).
+ */
+
+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, writeDerivedFiles } from "./index.ts";
+
+async function dockerAvailable(): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["docker", "info"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const code = await proc.exited;
+    return code === 0;
+  } catch {
+    return false;
+  }
+}
+
+describe("generated Dockerfile integration", () => {
+  test("oke docker output builds and runs", async () => {
+    if (!(await dockerAvailable())) {
+      console.warn("skipping: docker daemon not available");
+      return;
+    }
+
+    const dir = await mkdtemp(join(tmpdir(), "oke-df-build-"));
+    try {
+      // Minimal app that `oke start` can import.
+      await Bun.write(
+        join(dir, "package.json"),
+        JSON.stringify(
+          {
+            name: "oke-docker-fixture",
+            private: true,
+            type: "module",
+            bin: { oke: "./oke.ts" },
+            scripts: { start: "bun ./app.ts" },
+            okengine: { entry: "./app.ts" },
+          },
+          null,
+          2,
+        ),
+      );
+      await Bun.write(
+        join(dir, "oke.ts"),
+        `#!/usr/bin/env bun
+const [cmd] = process.argv.slice(2);
+if (cmd === "start") {
+  await import("./app.ts");
+} else {
+  console.error("fixture oke: unknown", cmd);
+  process.exit(1);
+}
+`,
+      );
+      await Bun.write(
+        join(dir, "app.ts"),
+        `const server = Bun.serve({
+  port: Number(process.env.PORT ?? 6530),
+  hostname: "0.0.0.0",
+  fetch() {
+    return Response.json({ ok: true });
+  },
+});
+console.log("listening", server.port);
+`,
+      );
+
+      // No lockfile — adjust Dockerfile install for the fixture.
+      const derived = deriveInfrastructure({
+        images: { "store.sql": "postgres:16-alpine" },
+        credentials: {
+          "store.sql": {
+            user: "oke",
+            password: "fixture-pass",
+            database: "oke",
+          },
+        },
+        app: "fixture",
+      });
+      await writeDerivedFiles(derived, dir);
+
+      // Fixture has no bun.lock — rewrite install step.
+      let df = await Bun.file(join(dir, "Dockerfile")).text();
+      df = df.replace(
+        "RUN bun install --frozen-lockfile --production",
+        "RUN bun install --production",
+      );
+      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 [buildOut, buildErr, buildCode] = await Promise.all([
+        new Response(build.stdout).text(),
+        new Response(build.stderr).text(),
+        build.exited,
+      ]);
+      expect(buildCode).toBe(0);
+      if (buildCode !== 0) {
+        console.error(buildOut, buildErr);
+      }
+
+      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 [runOut, runErr, runCode] = await Promise.all([
+        new Response(run.stdout).text(),
+        new Response(run.stderr).text(),
+        run.exited,
+      ]);
+      expect(runCode).toBe(0);
+      if (runCode !== 0) console.error(runOut, runErr);
+
+      // Resolve published port
+      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+)/);
+      expect(m).toBeTruthy();
+      const hostPort = m![1]!;
+
+      let body: { ok?: boolean } | null = null;
+      for (let i = 0; i < 20; i++) {
+        try {
+          const res = await fetch(`http://127.0.0.1:${hostPort}/`);
+          if (res.ok) {
+            body = (await res.json()) as { ok?: boolean };
+            break;
+          }
+        } catch {
+          await Bun.sleep(250);
+        }
+      }
+      expect(body?.ok).toBe(true);
+
+      await Bun.spawn(["docker", "rm", "-f", name], {
+        stdout: "pipe",
+        stderr: "pipe",
+      }).exited;
+      await Bun.spawn(["docker", "rmi", "-f", tag], {
+        stdout: "pipe",
+        stderr: "pipe",
+      }).exited;
+    } finally {
+      await rm(dir, { recursive: true, force: true }).catch(() => {});
+    }
+  }, 180_000);
+});