okengine 0.6.0 → 0.7.0

package/src/docker/cleanup.ts

@@ -0,0 +1,355 @@
+/**
+ * Discover and tear down leftover `oke-dev-<id>` compose stacks.
+ *
+ * Identity matches {@link stackAppSlug}: compose project `oke-dev-<6hex>`.
+ * Cleanup uses `docker compose -p <project> down -v` (no compose files required).
+ */
+
+import { join } from "node:path";
+import { stackAppSlug } from "./stack-id.ts";
+
+/** Compose project names created by `oke dev --docker`. */
+export const OKE_DEV_PROJECT_RE = /^oke-dev-[0-9a-f]{6}$/;
+
+/** Result of one `docker …` invocation. */
+export interface DockerRunResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+}
+
+/** Injectable docker CLI runner (tests). */
+export type DockerRunner = (args: readonly string[]) => Promise<DockerRunResult>;
+
+/** One container belonging to an OKE compose project. */
+export interface OkeContainer {
+  readonly id: string;
+  readonly name: string;
+  readonly service: string;
+  readonly state: string;
+  readonly project: string;
+}
+
+/** One compose project with zero or more containers. */
+export interface OkeStack {
+  readonly project: string;
+  readonly containers: readonly OkeContainer[];
+}
+
+/**
+ * Compose project name for a project root (`oke-dev-<id>`).
+ *
+ * @param cwd - Project root
+ */
+export function composeProjectName(cwd: string): string {
+  return `oke-${stackAppSlug(cwd)}`;
+}
+
+/**
+ * Whether a compose project name is an OKE local stack.
+ *
+ * @param name - Compose project name
+ */
+export function isOkeDevProject(name: string): boolean {
+  return OKE_DEV_PROJECT_RE.test(name);
+}
+
+/**
+ * Unique compose projects implied by a container selection.
+ *
+ * @param containers - Selected containers
+ */
+export function projectsFromContainerSelection(
+  containers: readonly OkeContainer[],
+): readonly string[] {
+  return [...new Set(containers.map((c) => c.project))].sort();
+}
+
+/**
+ * True when cwd looks like an okengine app root.
+ *
+ * @param cwd - Directory to probe
+ */
+export async function isOkeProjectRoot(cwd: string): Promise<boolean> {
+  for (const name of ["oke.config.ts", "oke.config.mts", "oke.config.js"] as const) {
+    if (await Bun.file(join(cwd, name)).exists()) return true;
+  }
+  return false;
+}
+
+/**
+ * Default runner — `docker` on PATH.
+ *
+ * @param args - Args after `docker`
+ */
+export async function defaultDockerRunner(args: readonly string[]): Promise<DockerRunResult> {
+  const proc = Bun.spawn(["docker", ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { stdout, stderr, exitCode };
+}
+
+/**
+ * Discover every `oke-dev-*` compose project on this machine.
+ *
+ * Sources: `compose ls`, container labels, volume/network name prefixes.
+ *
+ * @param run - Docker runner
+ */
+export async function listOkeComposeProjects(
+  run: DockerRunner = defaultDockerRunner,
+): Promise<readonly OkeStack[]> {
+  const projectNames = new Set<string>();
+
+  for (const name of await listComposeProjectNames(run)) {
+    if (isOkeDevProject(name)) projectNames.add(name);
+  }
+  for (const c of await listAllOkeContainers(run)) {
+    projectNames.add(c.project);
+  }
+  for (const name of await listOkeResourceProjectNames(run, "volume")) {
+    projectNames.add(name);
+  }
+  for (const name of await listOkeResourceProjectNames(run, "network")) {
+    projectNames.add(name);
+  }
+
+  const stacks: OkeStack[] = [];
+  for (const project of [...projectNames].sort()) {
+    const containers = await listStackContainers(project, run);
+    stacks.push({ project, containers });
+  }
+  return stacks;
+}
+
+/**
+ * List containers for one compose project.
+ *
+ * @param project - Compose project name
+ * @param run - Docker runner
+ */
+export async function listStackContainers(
+  project: string,
+  run: DockerRunner = defaultDockerRunner,
+): Promise<readonly OkeContainer[]> {
+  const result = await run([
+    "ps",
+    "-a",
+    "--filter",
+    `label=com.docker.compose.project=${project}`,
+    "--format",
+    "{{json .}}",
+  ]);
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `oke docker clean: docker ps failed (${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}`,
+    );
+  }
+  return parseContainerJsonLines(result.stdout, project);
+}
+
+/**
+ * Tear down one stack — containers, networks, and named volumes.
+ *
+ * @param project - Compose project name
+ * @param run - Docker runner
+ */
+export async function downStack(
+  project: string,
+  run: DockerRunner = defaultDockerRunner,
+): Promise<void> {
+  if (!isOkeDevProject(project)) {
+    throw new Error(`oke docker clean: refusing non-OKE project ${project}`);
+  }
+  const result = await run(["compose", "-p", project, "down", "-v", "--remove-orphans"]);
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `oke docker clean: docker compose down failed for ${project} (${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}`,
+    );
+  }
+}
+
+/**
+ * Stable selection key for a container (or empty stack sentinel).
+ *
+ * @param project - Compose project
+ * @param containerName - Container name, or empty for volume-only stacks
+ */
+export function selectionKey(project: string, containerName = ""): string {
+  return containerName ? `${project}\0${containerName}` : `${project}\0`;
+}
+
+/**
+ * Parse selection keys back into projects (and optional container filter).
+ *
+ * @param keys - Values from multiselect
+ * @param stacks - Known stacks (for container lookup)
+ */
+export function resolveSelection(
+  keys: readonly string[],
+  stacks: readonly OkeStack[],
+): {
+  readonly projects: readonly string[];
+  readonly containers: readonly OkeContainer[];
+} {
+  const byProject = new Map(stacks.map((s) => [s.project, s] as const));
+  const projects = new Set<string>();
+  const containers: OkeContainer[] = [];
+
+  for (const key of keys) {
+    const sep = key.indexOf("\0");
+    const project = sep === -1 ? key : key.slice(0, sep);
+    const containerName = sep === -1 ? "" : key.slice(sep + 1);
+    if (!isOkeDevProject(project)) continue;
+    projects.add(project);
+    const stack = byProject.get(project);
+    if (!stack) continue;
+    if (!containerName) continue;
+    const found = stack.containers.find((c) => c.name === containerName);
+    if (found) containers.push(found);
+  }
+
+  return { projects: [...projects].sort(), containers };
+}
+
+async function listComposeProjectNames(run: DockerRunner): Promise<readonly string[]> {
+  const result = await run(["compose", "ls", "-a", "--format", "json"]);
+  if (result.exitCode !== 0) {
+    // Compose plugin missing or Docker down — other probes may still find leftovers.
+    return [];
+  }
+  const names: string[] = [];
+  for (const row of parseJsonRecords(result.stdout)) {
+    const name = stringField(row, "Name") ?? stringField(row, "name");
+    if (name) names.push(name);
+  }
+  return names;
+}
+
+async function listAllOkeContainers(run: DockerRunner): Promise<readonly OkeContainer[]> {
+  const result = await run([
+    "ps",
+    "-a",
+    "--filter",
+    "label=com.docker.compose.project",
+    "--format",
+    "{{json .}}",
+  ]);
+  if (result.exitCode !== 0) return [];
+  const out: OkeContainer[] = [];
+  for (const row of parseJsonRecords(result.stdout)) {
+    const project =
+      labelValue(row, "com.docker.compose.project") ??
+      stringField(row, "ComposeProject") ??
+      stringField(row, "Project");
+    if (!project || !isOkeDevProject(project)) continue;
+    out.push(containerFromRow(row, project));
+  }
+  return out;
+}
+
+async function listOkeResourceProjectNames(
+  run: DockerRunner,
+  kind: "volume" | "network",
+): Promise<readonly string[]> {
+  const result = await run([kind, "ls", "--format", "{{json .}}"]);
+  if (result.exitCode !== 0) return [];
+  const names = new Set<string>();
+  for (const row of parseJsonRecords(result.stdout)) {
+    const name = stringField(row, "Name") ?? stringField(row, "name");
+    if (!name) continue;
+    const project = projectFromResourceName(name);
+    if (project) names.add(project);
+  }
+  return [...names];
+}
+
+/**
+ * Extract `oke-dev-<id>` from a volume/network name like `oke-dev-abc123_oke`.
+ *
+ * @param name - Docker resource name
+ */
+export function projectFromResourceName(name: string): string | null {
+  const m = /^(oke-dev-[0-9a-f]{6})(?:_|$)/.exec(name);
+  return m?.[1] ?? null;
+}
+
+function parseContainerJsonLines(stdout: string, project: string): readonly OkeContainer[] {
+  return parseJsonRecords(stdout).map((row) => containerFromRow(row, project));
+}
+
+function containerFromRow(row: Record<string, unknown>, project: string): OkeContainer {
+  const names = stringField(row, "Names") ?? stringField(row, "Name") ?? "";
+  const name = names.split(",")[0]?.replace(/^\//, "") || names;
+  const service =
+    labelValue(row, "com.docker.compose.service") ?? stringField(row, "Service") ?? name;
+  const id = stringField(row, "ID") ?? stringField(row, "Id") ?? name;
+  const state =
+    stringField(row, "State") ?? stringField(row, "Status") ?? stringField(row, "state") ?? "";
+  return { id, name, service, state, project };
+}
+
+function labelValue(row: Record<string, unknown>, key: string): string | null {
+  const labels = row.Labels ?? row.labels;
+  if (typeof labels === "string") {
+    for (const part of labels.split(",")) {
+      const eq = part.indexOf("=");
+      if (eq === -1) continue;
+      if (part.slice(0, eq) === key) return part.slice(eq + 1);
+    }
+    return null;
+  }
+  if (labels && typeof labels === "object") {
+    const v = (labels as Record<string, unknown>)[key];
+    return typeof v === "string" ? v : null;
+  }
+  return null;
+}
+
+function stringField(row: Record<string, unknown>, key: string): string | null {
+  const v = row[key];
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+/**
+ * Parse Docker `--format json` / `{{json .}}` output (array or NDJSON).
+ *
+ * @param text - stdout
+ */
+export function parseJsonRecords(text: string): readonly Record<string, unknown>[] {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) {
+      return parsed.filter(
+        (x): x is Record<string, unknown> => typeof x === "object" && x !== null,
+      );
+    }
+    if (typeof parsed === "object" && parsed !== null) {
+      return [parsed as Record<string, unknown>];
+    }
+  } catch {
+    // NDJSON — one object per line
+  }
+  const out: Record<string, unknown>[] = [];
+  for (const line of trimmed.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      const row: unknown = JSON.parse(t);
+      if (typeof row === "object" && row !== null && !Array.isArray(row)) {
+        out.push(row as Record<string, unknown>);
+      }
+    } catch {
+      // skip malformed lines
+    }
+  }
+  return out;
+}

package/src/docker/docker.test.ts

@@ -81,6 +81,10 @@ describe("image recipes", () => {
     expect(applied.volumes).toContain("ai-data:/root/.ollama");
     expect(applied.healthcheck?.test.join(" ")).toContain("ollama list");
     expect(String(applied.command)).toContain("ollama pull");
+    // Compose must see `$$` so `$pid` / `$i` are not treated as project env.
+    expect(String(applied.command)).toContain("pid=$$!");
+    expect(String(applied.command)).toContain("wait $$pid");
+    expect(String(applied.command)).not.toMatch(/(?<!\$)\$pid\b/);
     const url = recipeFor(spec.image).url(spec, {
       host: "127.0.0.1",
       port: 11434,

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

@@ -1,5 +1,7 @@
 /**
  * Integration: generated Dockerfile builds (and optionally runs).
+ *
+ * Opt-in via `OKE_TEST_DOCKER=1` plus a live Docker daemon. Never an empty pass.
  */
 
 import { describe, expect, test } from "bun:test";
@@ -8,47 +10,50 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { deriveInfrastructure, writeDerivedFiles } from "./index.ts";
 
-async function dockerAvailable(): Promise<boolean> {
+function dockerAvailable(): boolean {
   try {
-    const proc = Bun.spawn(["docker", "info"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const code = await proc.exited;
-    return code === 0;
+    return Bun.spawnSync(["docker", "info"], { stdout: "pipe", stderr: "pipe" }).exitCode === 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 WANT = process.env.OKE_TEST_DOCKER === "1";
+const DOCKER = WANT && dockerAvailable();
+if (!DOCKER) {
+  console.log(
+    WANT
+      ? "skip: generated Dockerfile e2e (docker daemon not available)"
+      : "skip: generated Dockerfile e2e (OKE_TEST_DOCKER≠1)",
+  );
+}
+const live = DOCKER ? test : test.skip;
 
-    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
+describe("generated Dockerfile integration", () => {
+  live(
+    "oke docker output builds and runs",
+    async () => {
+      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");
@@ -57,10 +62,10 @@ if (cmd === "start") {
   process.exit(1);
 }
 `,
-      );
-      await Bun.write(
-        join(dir, "app.ts"),
-        `const server = Bun.serve({
+        );
+        await Bun.write(
+          join(dir, "app.ts"),
+          `const server = Bun.serve({
   port: Number(process.env.PORT ?? 6530),
   hostname: "0.0.0.0",
   fetch() {
@@ -69,95 +74,97 @@ if (cmd === "start") {
 });
 console.log("listening", server.port);
 `,
-      );
+        );
 
-      // No lockfile — adjust Dockerfile install for the fixture.
-      const derived = deriveInfrastructure({
-        images: { "store.sql": "postgres:18-alpine" },
-        credentials: {
-          "store.sql": {
-            user: "oke",
-            password: "fixture-pass",
-            database: "oke",
+        // No lockfile — adjust Dockerfile install for the fixture.
+        const derived = deriveInfrastructure({
+          images: { "store.sql": "postgres:18-alpine" },
+          credentials: {
+            "store.sql": {
+              user: "oke",
+              password: "fixture-pass",
+              database: "oke",
+            },
           },
-        },
-        app: "fixture",
-        // Flat fixture root (build context `.`).
-        composeDir: ".",
-      });
-      await writeDerivedFiles(derived, dir);
+          app: "fixture",
+          // Flat fixture root (build context `.`).
+          composeDir: ".",
+        });
+        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);
+        // 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 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);
+        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]!;
+        // 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;
+        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);
           }
-        } catch {
-          await Bun.sleep(250);
         }
-      }
-      expect(body?.ok).toBe(true);
+        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);
+        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,
+  );
 });

package/src/docker/index.ts

@@ -66,6 +66,25 @@ export {
   stackAppSlug,
   stackInstanceId,
 } from "./stack-id.ts";
+export {
+  OKE_DEV_PROJECT_RE,
+  composeProjectName,
+  defaultDockerRunner,
+  downStack,
+  isOkeDevProject,
+  isOkeProjectRoot,
+  listOkeComposeProjects,
+  listStackContainers,
+  parseJsonRecords,
+  projectFromResourceName,
+  projectsFromContainerSelection,
+  resolveSelection,
+  selectionKey,
+  type DockerRunResult,
+  type DockerRunner,
+  type OkeContainer,
+  type OkeStack,
+} from "./cleanup.ts";
 export {
   formatImagesLock,
   pinImages,