okengine 0.1.4

package/src/docker/dockerfile.ts

@@ -0,0 +1,39 @@
+/**
+ * Dockerfile derivation — production image whose CMD is `oke start`.
+ */
+
+import { APP_PORT } from "../runtime/types.ts";
+
+/** Options for {@link emitDockerfile}. */
+export interface DockerfileOptions {
+  /** App listen port. */
+  readonly appPort?: number;
+  /** Bun base image. */
+  readonly baseImage?: string;
+}
+
+/**
+ * Emit a production Dockerfile. CMD is exactly `oke start`.
+ *
+ * @param options - Port / base image
+ */
+export function emitDockerfile(options: DockerfileOptions = {}): string {
+  const port = options.appPort ?? APP_PORT;
+  const base = options.baseImage ?? "oven/bun:1.3";
+  return `# generated by oke docker — do not edit
+FROM ${base} AS deps
+WORKDIR /app
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile --production
+
+FROM ${base} AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV PORT=${port}
+ENV PATH="/app/node_modules/.bin:\${PATH}"
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+EXPOSE ${port}
+CMD ["oke", "start"]
+`;
+}

package/src/docker/helpers.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared helpers for image recipes — keep recipe files ≤15 lines.
+ */
+
+import type { ServiceSpec } from "./types.ts";
+
+/**
+ * Env-var *reference* for a credential field — value never enters YAML.
+ *
+ * @param spec - Service
+ * @param field - USER | PASSWORD | DB
+ */
+export function credEnv(spec: ServiceSpec, field: "USER" | "PASSWORD" | "DB"): string {
+  const key = `OKE_${spec.role.replaceAll(".", "_").toUpperCase()}_${field}`;
+  return `\${${key}}`;
+}
+
+/**
+ * Compose service name for a role (`store.sql` → `store-sql`).
+ *
+ * @param role - Role key
+ */
+export function serviceNameFor(role: string): string {
+  return role.replaceAll(".", "-");
+}
+
+/**
+ * Env key prefix for a role (`store.sql` → `OKE_STORE_SQL`).
+ *
+ * @param role - Role key
+ */
+export function envPrefix(role: string): string {
+  return `OKE_${role.replaceAll(".", "_").toUpperCase()}`;
+}
+
+/**
+ * Default host port for well-known roles.
+ *
+ * @param role - Role key
+ * @param containerPort - Container port
+ */
+export function defaultHostPort(role: string, containerPort: number): number {
+  if (role === "store.sql") return 5432;
+  if (role === "store.kv") return 6379;
+  if (role === "signal") return 4222;
+  return containerPort;
+}
+
+/**
+ * Escape a YAML double-quoted string.
+ *
+ * @param value - Raw string
+ */
+export function yamlQuote(value: string): string {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+/**
+ * Render a plain YAML mapping (2-space indent, no library).
+ *
+ * @param value - JSON-like structure
+ * @param indent - Current indent level
+ */
+export function toYaml(value: unknown, indent = 0): string {
+  const pad = "  ".repeat(indent);
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "string") return yamlQuote(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return value
+      .map((item) => {
+        if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+          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}`;
+        }
+        return `${pad}- ${toYaml(item, 0)}`;
+      })
+      .join("\n");
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).filter(
+      ([, v]) => v !== undefined,
+    );
+    if (entries.length === 0) return "{}";
+    return entries
+      .map(([k, v]) => {
+        if (v !== null && typeof v === "object") {
+          const nested = toYaml(v, indent + 1);
+          if (nested === "{}" || nested === "[]") return `${pad}${k}: ${nested}`;
+          return `${pad}${k}:\n${nested}`;
+        }
+        return `${pad}${k}: ${toYaml(v, 0)}`;
+      })
+      .join("\n");
+  }
+  return yamlQuote(String(value));
+}

package/src/docker/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Image recipes and compose derivation.
+ *
+ * Recipes translate a normalised {@link ServiceSpec} into image-specific
+ * env / command / healthcheck and expose {@link ImageRecipe.url} so the
+ * kernel never learns an env-var name. Four compose override layers end
+ * in an untouched `compose.override.yml`. Credentials never enter YAML.
+ */
+
+export type {
+  ComposeHealthcheck,
+  DeriveOptions,
+  DeriveResult,
+  GeneratedFile,
+  ImageRecipe,
+  RecipeApplyResult,
+  ServiceCredentials,
+  ServiceEndpoint,
+  ServiceSpec,
+} from "./types.ts";
+
+export {
+  COMPOSE_OVERRIDE,
+  assertNoCredentialsInYaml,
+  buildSpecs,
+  buildStackEnv,
+  emitComposeLayers,
+  formatStackEnv,
+} from "./compose.ts";
+
+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 {
+  formatImagesLock,
+  pinImages,
+  type DigestResolver,
+  type ImageLockEntry,
+  type ImagesLock,
+} from "./pin.ts";

package/src/docker/pin.ts

@@ -0,0 +1,90 @@
+/**
+ * `oke images pin` — tags → digests in `oke.images.lock`.
+ */
+
+/** One lock entry. */
+export interface ImageLockEntry {
+  readonly image: string;
+  readonly digest: string;
+  readonly pinnedAt: string;
+}
+
+/** Lock file shape. */
+export interface ImagesLock {
+  readonly oke: "1.0";
+  readonly images: Readonly<Record<string, ImageLockEntry>>;
+}
+
+/** Resolve a tag to a digest (injectable for tests). */
+export type DigestResolver = (image: string) => Promise<string>;
+
+/**
+ * Pin every image tag to a digest.
+ *
+ * @param images - Role → image tag
+ * @param resolveDigest - Digest resolver (defaults to `docker buildx imagetools`)
+ */
+export async function pinImages(
+  images: Readonly<Record<string, string>>,
+  resolveDigest: DigestResolver = dockerDigest,
+): Promise<ImagesLock> {
+  const entries: Record<string, ImageLockEntry> = {};
+  const pinnedAt = new Date().toISOString();
+  for (const [role, image] of Object.entries(images)) {
+    if (image.includes("@sha256:")) {
+      entries[role] = { image, digest: image.split("@")[1]!, pinnedAt };
+      continue;
+    }
+    const digest = await resolveDigest(image);
+    entries[role] = {
+      image: `${image.replace(/@sha256:[a-f0-9]+$/i, "")}@${digest}`,
+      digest,
+      pinnedAt,
+    };
+  }
+  return { oke: "1.0", images: entries };
+}
+
+/**
+ * Format lock file JSON.
+ *
+ * @param lock - Lock document
+ */
+export function formatImagesLock(lock: ImagesLock): string {
+  return `${JSON.stringify(lock, null, 2)}\n`;
+}
+
+/**
+ * Default digest resolver via `docker buildx imagetools inspect`.
+ *
+ * @param image - Image tag
+ */
+async function dockerDigest(image: string): Promise<string> {
+  const proc = Bun.spawn(
+    [
+      "docker",
+      "buildx",
+      "imagetools",
+      "inspect",
+      "--format",
+      "{{.Manifest.Digest}}",
+      image,
+    ],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (code !== 0) {
+    throw new Error(
+      `oke images pin: failed to resolve ${image}: ${stderr.trim() || `exit ${code}`}`,
+    );
+  }
+  const digest = stdout.trim();
+  if (!digest.startsWith("sha256:")) {
+    throw new Error(`oke images pin: unexpected digest for ${image}: ${digest}`);
+  }
+  return digest;
+}

package/src/docker/recipes/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Built-in image recipes — match by image ref, never by vendor driver id.
+ */
+
+import type { ImageRecipe } from "../types.ts";
+import { postgres } from "./postgres.ts";
+import { redis } from "./redis.ts";
+
+/** Default recipe catalogue. */
+export const builtinRecipes: readonly ImageRecipe[] = [postgres, redis];
+
+export { postgres, redis };
+
+/**
+ * Resolve the recipe for an image reference.
+ *
+ * @param image - Image pin
+ * @param extra - Plugin / test recipes (tried first)
+ */
+export function recipeFor(
+  image: string,
+  extra: readonly ImageRecipe[] = [],
+): ImageRecipe {
+  for (const r of extra) {
+    if (r.match(image)) return r;
+  }
+  for (const r of builtinRecipes) {
+    if (r.match(image)) return r;
+  }
+  throw new Error(
+    `oke docker: no image recipe matches ${JSON.stringify(image)} — add a recipe (≤15 lines) or pin a known image`,
+  );
+}

package/src/docker/recipes/postgres.ts

@@ -0,0 +1,18 @@
+/**
+ * Postgres / pgvector / Timescale image recipe (≤15 lines of recipe body).
+ */
+
+import { credEnv } from "../helpers.ts";
+import type { ImageRecipe } from "../types.ts";
+
+/** 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}`,
+};

package/src/docker/recipes/redis.ts

@@ -0,0 +1,18 @@
+/**
+ * Redis-protocol image recipe (Redis · Valkey · Dragonfly · KeyDB).
+ */
+
+import { credEnv } from "../helpers.ts";
+import type { ImageRecipe } from "../types.ts";
+
+/** Redis-protocol servers. */
+export const redis: ImageRecipe = {
+  id: "redis",
+  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 },
+  }),
+  url: (_s, c) => `redis://:${encodeURIComponent(c.password)}@${c.host}:${c.port}`,
+};

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

@@ -0,0 +1,140 @@
+/**
+ * Integration: generated compose brings up postgres; app URL talks to it.
+ */
+
+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";
+
+async function dockerAvailable(): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["docker", "info"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    return (await proc.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+describe("oke dev --stack postgres integration", () => {
+  test("compose brings up postgres and the app talks to it", async () => {
+    if (!(await dockerAvailable())) {
+      console.warn("skipping: docker daemon not available");
+      return;
+    }
+
+    const dir = await mkdtemp(join(tmpdir(), "oke-stack-pg-"));
+    const project = `oke-pg-${Date.now()}`;
+    try {
+      const derived = deriveInfrastructure({
+        images: { "store.sql": "postgres:16-alpine" },
+        credentials: {
+          "store.sql": {
+            user: "oke",
+            password: "stack-integration-pass",
+            database: "oke",
+          },
+        },
+        app: "stacktest",
+        host: "127.0.0.1",
+      });
+      await writeDerivedFiles(derived, dir, { writeStackEnv: true });
+
+      // Stack-only: no app service — just the role compose file.
+      const composeFiles = ["compose.store.sql.yml"];
+      const up = Bun.spawn(
+        [
+          "docker",
+          "compose",
+          "-p",
+          project,
+          ...composeFiles.flatMap((f) => ["-f", f]),
+          "up",
+          "-d",
+        ],
+        {
+          cwd: dir,
+          stdout: "pipe",
+          stderr: "pipe",
+          env: {
+            ...process.env,
+            ...derived.stackEnv,
+          },
+        },
+      );
+      const [upOut, upErr, upCode] = await Promise.all([
+        new Response(up.stdout).text(),
+        new Response(up.stderr).text(),
+        up.exited,
+      ]);
+      expect(upCode).toBe(0);
+      if (upCode !== 0) console.error(upOut, upErr);
+
+      // Wait for healthy
+      let healthy = false;
+      for (let i = 0; i < 40; i++) {
+        const ps = Bun.spawn(
+          [
+            "docker",
+            "compose",
+            "-p",
+            project,
+            ...composeFiles.flatMap((f) => ["-f", f]),
+            "ps",
+            "--format",
+            "json",
+          ],
+          { cwd: dir, stdout: "pipe", stderr: "pipe" },
+        );
+        const text = await new Response(ps.stdout).text();
+        await ps.exited;
+        if (/healthy/i.test(text)) {
+          healthy = true;
+          break;
+        }
+        await Bun.sleep(500);
+      }
+      expect(healthy).toBe(true);
+
+      const url = derived.stackEnv.DATABASE_URL!;
+      // App talks to postgres via recipe URL (Bun.SQL) — kernel never sees env-var names.
+      const sql = new Bun.SQL(url);
+      try {
+        const rows = (await sql`select 1::int as n`) as Array<{ n: number }>;
+        expect(rows[0]?.n).toBe(1);
+      } finally {
+        await sql.close();
+      }
+
+      // Prove credentials live in .env.stack, not YAML.
+      const yml = await Bun.file(join(dir, "compose.store.sql.yml")).text();
+      expect(yml).not.toContain("stack-integration-pass");
+      expect(formatStackEnv(derived.stackEnv)).toContain(
+        "stack-integration-pass",
+      );
+    } finally {
+      await Bun.spawn(
+        [
+          "docker",
+          "compose",
+          "-p",
+          project,
+          "-f",
+          "compose.store.sql.yml",
+          "down",
+          "-v",
+        ],
+        { cwd: dir, stdout: "pipe", stderr: "pipe" },
+      ).exited.catch(() => {});
+      await rm(dir, { recursive: true, force: true }).catch(() => {});
+    }
+  }, 120_000);
+});

package/src/docker/stack.ts

@@ -0,0 +1,62 @@
+/**
+ * `oke stack` — preview resolved images / tags / ports (writes nothing).
+ */
+
+import { buildSpecs } from "./compose.ts";
+import { recipeFor } from "./recipes/index.ts";
+import type { DeriveOptions, ServiceSpec } from "./types.ts";
+
+/** One resolved stack row for preview. */
+export interface StackRow {
+  readonly role: string;
+  readonly image: string;
+  readonly recipe: string;
+  readonly service: string;
+  readonly containerPort: number;
+  readonly hostPort: number;
+}
+
+/**
+ * Resolve stack preview rows from image pins.
+ *
+ * @param options - Images (+ optional recipes)
+ */
+export function resolveStack(options: DeriveOptions): readonly StackRow[] {
+  const specs = buildSpecs(options);
+  return specs.map((s) => toRow(s, options));
+}
+
+/**
+ * Format stack preview for the CLI.
+ *
+ * @param rows - Resolved rows
+ */
+export function formatStackPreview(rows: readonly StackRow[]): string {
+  if (rows.length === 0) return "oke stack: no images configured\n";
+  const lines = [
+    "ROLE            RECIPE     IMAGE                              HOST:CONTAINER",
+    "--------------  ---------  ---------------------------------  --------------",
+  ];
+  for (const r of rows) {
+    lines.push(
+      `${pad(r.role, 14)}  ${pad(r.recipe, 9)}  ${pad(r.image, 33)}  ${r.hostPort}:${r.containerPort}`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function toRow(spec: ServiceSpec, options: DeriveOptions): StackRow {
+  const recipe = recipeFor(spec.image, options.recipes ?? []);
+  return {
+    role: spec.role,
+    image: spec.image,
+    recipe: recipe.id,
+    service: spec.serviceName,
+    containerPort: spec.port,
+    hostPort: spec.hostPort,
+  };
+}
+
+function pad(s: string, n: number): string {
+  return s.length >= n ? s.slice(0, n) : s + " ".repeat(n - s.length);
+}

package/src/docker/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Normalised service + image-recipe contracts for compose derivation.
+ *
+ * Recipes translate a {@link ServiceSpec} into image-specific env / command /
+ * healthcheck and expose {@link ImageRecipe.url} so the kernel never learns
+ * an env-var name.
+ */
+
+/** Credential material for a role — never serialised into generated YAML. */
+export interface ServiceCredentials {
+  readonly user: string;
+  readonly password: string;
+  readonly database: string;
+}
+
+/** Connection endpoint used by {@link ImageRecipe.url}. */
+export interface ServiceEndpoint {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  readonly password: string;
+  readonly database: string;
+}
+
+/**
+ * Normalised service description produced from config `images` + role.
+ * Image-agnostic — recipes specialise it.
+ */
+export interface ServiceSpec {
+  /** Role key (`store.sql`, `store.kv`, …). */
+  readonly role: string;
+  /** Compose service name (`store-sql`). */
+  readonly serviceName: string;
+  /** Image reference (tag or digest). */
+  readonly image: string;
+  /** Container listen port. */
+  readonly port: number;
+  /** Host port published in compose (dev defaults). */
+  readonly hostPort: number;
+  /** Credential placeholders (values live in `.env.stack`, not YAML). */
+  readonly credentials: ServiceCredentials;
+}
+
+/** Compose healthcheck block. */
+export interface ComposeHealthcheck {
+  readonly test: readonly string[];
+  readonly interval?: string;
+  readonly timeout?: string;
+  readonly retries?: number;
+  readonly start_period?: string;
+}
+
+/** Image-specific compose fragment from {@link ImageRecipe.apply}. */
+export interface RecipeApplyResult {
+  readonly environment?: Readonly<Record<string, string>>;
+  readonly command?: string | readonly string[];
+  readonly healthcheck?: ComposeHealthcheck;
+  readonly volumes?: readonly string[];
+  readonly user?: string;
+}
+
+/**
+ * Image recipe — match an image ref, specialise a {@link ServiceSpec},
+ * and build a connection URL without teaching the kernel env-var names.
+ */
+export interface ImageRecipe {
+  /** Stable recipe id (`postgres`, `redis`, …). */
+  readonly id: string;
+  /** Default container port when the spec does not override. */
+  readonly port: number;
+  /**
+   * Whether this recipe handles `image`.
+   *
+   * @param image - Image reference
+   */
+  match(image: string): boolean;
+  /**
+   * Translate a normalised spec into image-specific compose fields.
+   * Environment values must be `${VAR}` refs — never cleartext secrets.
+   *
+   * @param spec - Normalised service
+   */
+  apply(spec: ServiceSpec): RecipeApplyResult;
+  /**
+   * Build a driver URL from endpoint credentials.
+   *
+   * @param spec - Normalised service
+   * @param endpoint - Host / port / credentials
+   */
+  url(spec: ServiceSpec, endpoint: ServiceEndpoint): string;
+}
+
+/** Options for compose / Dockerfile derivation. */
+export interface DeriveOptions {
+  /** Role → image pin (from `oke.config.ts` / Manifest). */
+  readonly images: Readonly<Record<string, string>>;
+  /** Application name (compose project / app service). */
+  readonly app?: string;
+  /** App listen port (default 6530). */
+  readonly appPort?: number;
+  /** When true, emit prod overlays (limits, secret refs, deploy.replicas). */
+  readonly prod?: boolean;
+  /** Output directory (default `.`). */
+  readonly outDir?: string;
+  /** Inject credentials (tests). Defaults to generated randoms. */
+  readonly credentials?: Readonly<Record<string, ServiceCredentials>>;
+  /** Host for URL builders (default `127.0.0.1` in stack env). */
+  readonly host?: string;
+  /** Extra image recipes (plugins). */
+  readonly recipes?: readonly ImageRecipe[];
+}
+
+/** One generated file. */
+export interface GeneratedFile {
+  /** Relative path under `outDir`. */
+  readonly path: string;
+  /** File contents. */
+  readonly content: string;
+}
+
+/** Result of {@link deriveInfrastructure}. */
+export interface DeriveResult {
+  /** Normalised specs (one per image role). */
+  readonly specs: readonly ServiceSpec[];
+  /** Generated files (Dockerfile + compose layers). */
+  readonly files: readonly GeneratedFile[];
+  /**
+   * Stack env contents for `.env.stack` — written by `oke dev --stack`,
+   * never embedded in YAML.
+   */
+  readonly stackEnv: Readonly<Record<string, string>>;
+  /** Compose `-f` merge order (four override layers). */
+  readonly composeFiles: readonly string[];
+}