okengine 0.1.4

package/src/cli/docker-cli.test.ts

@@ -0,0 +1,221 @@
+/**
+ * `oke docker` / `oke stack` / `oke images pin` / `oke schema` / `oke dev --stack`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDev } from "./dev.ts";
+import { runDockerDerive } from "./docker.ts";
+import { runImagesPin } from "./images.ts";
+import { emitSchemaSource, runSchemaGenerate } from "./schema.ts";
+import { runStackPreview } from "./stack.ts";
+import { runStart, resolveStartEntry } from "./start.ts";
+import { vaultCli } from "./vault-cmd.ts";
+
+const images = {
+  "store.sql": "pgvector/pgvector:pg17",
+} as const;
+
+const credentials = {
+  "store.sql": {
+    user: "oke",
+    password: "test-password-not-in-yaml",
+    database: "oke",
+  },
+} as const;
+
+describe("oke docker CLI", () => {
+  test("writes Dockerfile and compose without credentials in YAML", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-cli-docker-"));
+    const logs: string[] = [];
+    const { code, result } = await runDockerDerive({
+      cwd: dir,
+      outDir: dir,
+      images,
+      credentials,
+      write: (t) => logs.push(t),
+    });
+    expect(code).toBe(0);
+    expect(result).toBeDefined();
+    expect(await Bun.file(join(dir, "Dockerfile")).exists()).toBe(true);
+    expect(await Bun.file(join(dir, "compose.store.sql.yml")).exists()).toBe(
+      true,
+    );
+    const yml = await Bun.file(join(dir, "compose.store.sql.yml")).text();
+    expect(yml).not.toContain("test-password-not-in-yaml");
+    expect(logs.join("")).toContain("compose.override.yml");
+  });
+});
+
+describe("oke stack", () => {
+  test("previews without writing files", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-cli-stack-"));
+    let out = "";
+    const code = await runStackPreview({
+      cwd: dir,
+      images,
+      write: (t) => {
+        out += t;
+      },
+    });
+    expect(code).toBe(0);
+    expect(out).toContain("store.sql");
+    expect(out).toContain("postgres");
+    expect(await Bun.file(join(dir, "compose.yml")).exists()).toBe(false);
+  });
+});
+
+describe("oke images pin", () => {
+  test("writes oke.images.lock via injected resolver", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-cli-pin-"));
+    const code = await runImagesPin({
+      cwd: dir,
+      images,
+      resolveDigest: async () => "sha256:abc123",
+      write: () => {},
+    });
+    expect(code).toBe(0);
+    const lock = await Bun.file(join(dir, "oke.images.lock")).json();
+    expect(lock.images["store.sql"].digest).toBe("sha256:abc123");
+  });
+});
+
+describe("oke images list", () => {
+  test("lists recipe/image/tag/digest/size without writing", async () => {
+    const { runImagesList } = await import("./images.ts");
+    const dir = await mkdtemp(join(tmpdir(), "oke-cli-images-list-"));
+    let out = "";
+    const code = await runImagesList({
+      cwd: dir,
+      images,
+      lock: {
+        oke: "1.0",
+        images: {
+          "store.sql": {
+            image: "pgvector/pgvector:pg17@sha256:abc123",
+            digest: "sha256:abc123",
+            pinnedAt: "2026-01-01T00:00:00.000Z",
+          },
+        },
+      },
+      write: (t) => {
+        out += t;
+      },
+    });
+    expect(code).toBe(0);
+    expect(out).toContain("RECIPE");
+    expect(out).toContain("DIGEST");
+    expect(out).toContain("SIZE");
+    expect(out).toContain("store.sql");
+    expect(out).toContain("postgres");
+    expect(out).toContain("pgvector/pgvector");
+    expect(out).toContain("pg17");
+    expect(out).toContain("sha256:abc123");
+    expect(await Bun.file(join(dir, "oke.images.lock")).exists()).toBe(false);
+  });
+});
+
+describe("oke schema generate", () => {
+  test("emits schema/oke.ts and --check catches drift", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-cli-schema-"));
+    const code = await runSchemaGenerate({
+      cwd: dir,
+      extraTables: ["bookings"],
+      write: () => {},
+    });
+    expect(code).toBe(0);
+    const src = await Bun.file(join(dir, "schema/oke.ts")).text();
+    expect(src).toContain("bookings");
+    expect(src).toContain("oke_roles");
+
+    const checkOk = await runSchemaGenerate({
+      cwd: dir,
+      extraTables: ["bookings"],
+      check: true,
+      write: () => {},
+    });
+    expect(checkOk).toBe(0);
+
+    await Bun.write(join(dir, "schema/oke.ts"), emitSchemaSource(["other"]));
+    const checkFail = await runSchemaGenerate({
+      cwd: dir,
+      extraTables: ["bookings"],
+      check: true,
+      write: () => {},
+    });
+    expect(checkFail).toBe(1);
+  });
+});
+
+describe("oke dev --stack", () => {
+  test("plans stack with postgres and writes nothing on dryRun", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-cli-dev-dry-"));
+    await Bun.write(join(dir, "src/app.ts"), "export {}\n");
+    const { code, plan } = await runDev({
+      cwd: dir,
+      stack: ["store.sql"],
+      images,
+      credentials,
+      dryRun: true,
+      write: () => {},
+    });
+    expect(code).toBe(0);
+    expect(plan?.stackRoles).toEqual(["store.sql"]);
+    expect(plan?.composeFiles?.some((f) => f.includes("store.sql"))).toBe(true);
+    expect(plan?.stackEnv?.DATABASE_URL).toContain("postgres://");
+    expect(await Bun.file(join(dir, "compose.yml")).exists()).toBe(false);
+  });
+});
+
+describe("oke start", () => {
+  test("resolves entry and invokes runEntry", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-cli-start-"));
+    await Bun.write(join(dir, "src/app.ts"), "export {}\n");
+    const entry = await resolveStartEntry(dir);
+    expect(entry).toEndWith("src/app.ts");
+    let ran = "";
+    const code = await runStart({
+      cwd: dir,
+      runEntry: async (e) => {
+        ran = e;
+      },
+      write: () => {},
+    });
+    expect(code).toBe(0);
+    expect(ran).toBe(entry);
+  });
+});
+
+describe("oke vault", () => {
+  test("set and list", async () => {
+    const store = new Map<string, string>();
+    const bag = {
+      get: (n: string) => store.get(n),
+      set: (n: string, v: string) => {
+        store.set(n, v);
+      },
+      names: () => [...store.keys()],
+    };
+    let out = "";
+    expect(
+      await vaultCli(["set", "STRIPE_KEY", "sk_test"], {
+        store: bag,
+        write: (t) => {
+          out += t;
+        },
+      }),
+    ).toBe(0);
+    out = "";
+    expect(
+      await vaultCli(["list"], {
+        store: bag,
+        write: (t) => {
+          out += t;
+        },
+      }),
+    ).toBe(0);
+    expect(out).toContain("STRIPE_KEY");
+  });
+});

package/src/cli/docker.ts

@@ -0,0 +1,127 @@
+/**
+ * `oke docker` — Dockerfile + per-role compose files.
+ */
+
+import { resolve } from "node:path";
+import {
+  deriveInfrastructure,
+  writeDerivedFiles,
+  type DeriveOptions,
+  type DeriveResult,
+} from "../docker/index.ts";
+import { loadOkeConfig, loadManifest, resolveImages } from "./load-config.ts";
+
+/** Options for {@link runDockerDerive}. */
+export interface DockerCliOptions {
+  readonly cwd?: string;
+  readonly outDir?: string;
+  readonly prod?: boolean;
+  readonly configPath?: string;
+  readonly manifestPath?: string;
+  readonly write?: (text: string) => void;
+  /** Injected images (tests). */
+  readonly images?: Readonly<Record<string, string>>;
+  /** Injected credentials (tests). */
+  readonly credentials?: DeriveOptions["credentials"];
+  /** Skip filesystem writes (tests). */
+  readonly dryRun?: boolean;
+}
+
+/**
+ * Derive and write Docker / compose artefacts.
+ *
+ * @param options - Flags
+ * @returns Exit code
+ */
+export async function runDockerDerive(
+  options: DockerCliOptions = {},
+): Promise<{ readonly code: number; readonly result?: DeriveResult }> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const cwd = options.cwd ?? process.cwd();
+  const outDir = resolve(cwd, options.outDir ?? ".");
+
+  let images = options.images;
+  let app = "app";
+  if (!images) {
+    try {
+      const loaded = await loadOkeConfig(cwd, options.configPath);
+      images = resolveImages(loaded.config);
+      app = "app";
+    } catch {
+      if (options.manifestPath) {
+        const manifest = await loadManifest(options.manifestPath);
+        images = resolveImages(undefined, manifest);
+        app = manifest.app;
+      } else {
+        write("oke docker: no oke.config.ts / images — nothing to derive\n");
+        return { code: 1 };
+      }
+    }
+  }
+
+  if (!images || Object.keys(images).length === 0) {
+    write("oke docker: images map is empty\n");
+    return { code: 1 };
+  }
+
+  try {
+    const result = deriveInfrastructure({
+      images,
+      app,
+      prod: options.prod ?? false,
+      outDir,
+      ...(options.credentials ? { credentials: options.credentials } : {}),
+    });
+
+    if (!options.dryRun) {
+      await writeDerivedFiles(result, outDir, { writeStackEnv: false });
+    }
+
+    write(`oke docker: wrote ${result.files.length} file(s)\n`);
+    for (const f of result.files) write(`  ${f.path}\n`);
+    write(
+      `compose merge order:\n${result.composeFiles.map((f) => `  -f ${f}`).join("\n")}\n`,
+    );
+    write(
+      "(compose.override.yml is layer 4 — user-owned, never written by oke)\n",
+    );
+    return { code: 0, result };
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return { code: 1 };
+  }
+}
+
+/**
+ * CLI entry for `oke docker [--prod|-p] [--out|-o dir]`.
+ *
+ * @param args - Args after `docker`
+ */
+export async function dockerCli(args: readonly string[]): Promise<number> {
+  let prod = false;
+  let outDir: string | undefined;
+  let configPath: string | undefined;
+  let manifestPath: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--prod" || a === "-p") prod = true;
+    else if (a === "--out" || a === "-o") outDir = args[++i];
+    else if (a === "--config" || a === "-c") configPath = args[++i];
+    else if (a === "--manifest" || a === "-m") manifestPath = args[++i];
+    else if (a === "--help" || a === "-h") {
+      console.log(`oke docker [--prod|-p] [--out|-o .] [--config|-c oke.config.ts]
+
+Derive Dockerfile + compose.<role>.yml files.
+--prod is opt-in (never the default). Credentials are never written into YAML.
+`);
+      return 0;
+    }
+  }
+  const { code } = await runDockerDerive({
+    prod,
+    outDir,
+    configPath,
+    manifestPath,
+  });
+  return code;
+}

package/src/cli/doctor-diff-examples.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env bun
+/**
+ * CI gate: `oke doctor --diff` across the four reference apps.
+ *
+ * Extracts Manifests from working-tree sources and from the git merge-base,
+ * then fails on undeclared contract breaks.
+ */
+
+import { resolve } from "node:path";
+import { extractManifest, type SourceFile } from "../compiler/extract.ts";
+import { undeclaredContractBreaks } from "../manifest/undeclared.ts";
+import { gitMergeBase, gitShow } from "./doctor-diff.ts";
+
+const ROOT = resolve(import.meta.dir, "../..");
+const APPS = ["notes", "linkly", "provisions", "skyport"] as const;
+
+/**
+ * Run undeclared-break checks for every example app.
+ *
+ * @returns Exit code
+ */
+export async function runDoctorDiffExamples(): Promise<number> {
+  const mergeBase = await gitMergeBase(ROOT);
+  let failed = 0;
+
+  for (const app of APPS) {
+    const rootDir = resolve(ROOT, `examples/${app}`);
+    const after = await extractManifest({ rootDir });
+    const extracted = mergeBase
+      ? await extractAtRevision(ROOT, mergeBase, `examples/${app}`)
+      : after;
+    // No sources at merge-base → empty baseline (additions are no-impact).
+    const before = extracted ?? { oke: after.oke, app: after.app };
+
+    const undeclared = undeclaredContractBreaks(before, after);
+    if (undeclared.length === 0) {
+      console.log(`oke doctor --diff examples/${app}: ok`);
+      continue;
+    }
+    failed++;
+    console.log(
+      `oke doctor --diff examples/${app}: ${undeclared.length} undeclared contract-breaking change(s)`,
+    );
+    for (const c of undeclared) {
+      console.log(`  [contract-breaking] ${c.path}: ${c.summary}`);
+    }
+  }
+
+  if (failed > 0) {
+    console.log(
+      "Acknowledge intentional breaks with `breaking: true` on the owning flow.",
+    );
+  }
+  return failed > 0 ? 1 : 0;
+}
+
+/**
+ * Extract a Manifest from sources as they existed at a git revision.
+ *
+ * @param repoRoot - Repository root
+ * @param rev - Commit-ish
+ * @param appRel - App directory relative to repo root (e.g. `examples/notes`)
+ */
+async function extractAtRevision(
+  repoRoot: string,
+  rev: string,
+  appRel: string,
+): Promise<Awaited<ReturnType<typeof extractManifest>> | null> {
+  const workingRoot = resolve(repoRoot, appRel);
+  // Bun.Glob (global) — bare `import … from "bun"` is rejected by JSR.
+  const glob = new Bun.Glob("**/*.{ts,tsx}");
+  const files: SourceFile[] = [];
+
+  for await (const rel of glob.scan({
+    cwd: workingRoot,
+    onlyFiles: true,
+  })) {
+    if (rel.includes("node_modules/") || rel.endsWith(".test.ts")) continue;
+    const repoPath = `${appRel}/${rel}`;
+    const source = await gitShow(repoRoot, rev, repoPath);
+    if (source === null) continue;
+    files.push({ path: rel, source });
+  }
+
+  if (files.length === 0) return null;
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  return extractManifest({ files });
+}
+
+if (import.meta.main) {
+  process.exit(await runDoctorDiffExamples());
+}

package/src/cli/doctor-diff.test.ts

@@ -0,0 +1,91 @@
+/**
+ * `oke doctor --diff` — undeclared contract-break CI gate.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import type { Manifest } from "../manifest/types.ts";
+import { parseManifest } from "../manifest/validate.ts";
+import { runDoctorDiff } from "./doctor-diff.ts";
+
+const baseUrl = new URL(
+  "../manifest/fixtures/base.manifest.json",
+  import.meta.url,
+);
+
+async function loadBase(): Promise<Manifest> {
+  return parseManifest(await Bun.file(baseUrl).text());
+}
+
+function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+describe("oke doctor --diff", () => {
+  test("ok when manifests are identical", async () => {
+    const m = await loadBase();
+    const logs: string[] = [];
+    const { code, undeclared } = await runDoctorDiff({
+      before: m,
+      after: clone(m),
+      write: (t) => logs.push(t),
+    });
+    expect(code).toBe(0);
+    expect(undeclared).toHaveLength(0);
+    expect(logs.join("")).toContain("ok");
+  });
+
+  test("fails on undeclared contract break", async () => {
+    const before = await loadBase();
+    const after = clone(before);
+    const errors = after.flows!["reports.export"]!.errors;
+    after.flows!["reports.export"]!.errors = Array.isArray(errors)
+      ? errors.filter((e) => e !== "Forbidden")
+      : errors;
+    const { code, undeclared } = await runDoctorDiff({
+      before,
+      after,
+      write: () => {},
+    });
+    expect(code).toBe(2);
+    expect(undeclared.length).toBeGreaterThan(0);
+  });
+
+  test("passes when break is acknowledged with breaking: true", async () => {
+    const before = await loadBase();
+    const after = clone(before);
+    const errors = after.flows!["reports.export"]!.errors;
+    after.flows!["reports.export"]!.errors = Array.isArray(errors)
+      ? errors.filter((e) => e !== "Forbidden")
+      : errors;
+    after.flows!["reports.export"]!.breaking = true;
+    const { code } = await runDoctorDiff({
+      before,
+      after,
+      write: () => {},
+    });
+    expect(code).toBe(0);
+  });
+
+  test("explicit --before/--after paths", async () => {
+    const before = await loadBase();
+    const after = clone(before);
+    const dir = `${tmpdir()}/oke-doctor-diff-${crypto.randomUUID()}`;
+    await mkdir(dir, { recursive: true });
+    await Bun.write(`${dir}/before.json`, JSON.stringify(before));
+    await Bun.write(`${dir}/after.json`, JSON.stringify(after));
+    try {
+      const { code } = await runDoctorDiff({
+        cwd: dir,
+        beforePath: "before.json",
+        afterPath: "after.json",
+        write: () => {},
+      });
+      expect(code).toBe(0);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+