okengine 0.6.1 → 0.8.0

package/src/cli/dev.ts

@@ -101,7 +101,7 @@ export interface DevServeDocsMcpOptions {
 /** Live `oke dev` session — returned when {@link DevOptions.keepAlive} is false. */
 export interface DevSession {
   readonly plan: DevPlan;
-  /** Stop app · Console · MCP · watcher. */
+  /** Stop app · Console · MCP · watcher · docker compose (when this session started it). */
   readonly stop: () => void;
   readonly appPort: number;
   readonly consolePort: number;
@@ -185,6 +185,19 @@ export interface DevOptions {
    * @param cwd - Compose directory (`docker/`)
    */
   readonly composeUp?: (composeFiles: readonly string[], cwd: string) => Promise<void>;
+  /**
+   * Stop compose containers on session exit (injectable). Keeps volumes.
+   * Default: `docker compose … stop` with the same `-f` / cwd / env as up.
+   *
+   * @param composeFiles - `-f` list used at up
+   * @param cwd - Compose directory (`docker/`)
+   * @param env - Stack env merged into the process env for compose
+   */
+  readonly composeStop?: (
+    composeFiles: readonly string[],
+    cwd: string,
+    env: Readonly<Record<string, string>>,
+  ) => void;
   /**
    * Regenerate client types (injectable).
    *
@@ -330,6 +343,12 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   let stackRoles: string[] | null = null;
   let composeFiles: string[] | null = null;
   let stackEnv: Record<string, string> | null = null;
+  /** Set only after a successful `compose up` — torn down on SIGINT / stop. */
+  let dockerStarted: {
+    files: readonly string[];
+    cwd: string;
+    env: Record<string, string>;
+  } | null = null;
   let stackSqlDriver = "postgres";
   let stackKvDriver = "redis";
   let loadedConfig: Awaited<ReturnType<typeof loadOkeConfig>>["config"] | null = null;
@@ -437,6 +456,12 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           });
         // Compose files live under docker/; cwd for compose is that directory.
         await up(composeFiles, dockerOut);
+        // Remember for SIGINT / terminal close — `stop` keeps volumes (not `down -v`).
+        dockerStarted = {
+          files: composeFiles,
+          cwd: dockerOut,
+          env: { ...stackEnv! },
+        };
 
         // Real OpenBao vault: init once / unseal every start, then expose the
         // least-privilege app token to the app + Console (never root).
@@ -450,6 +475,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
             names: vaultNames,
           });
           Object.assign(stackEnv!, openbaoStackEnv(boot));
+          Object.assign(dockerStarted.env, openbaoStackEnv(boot));
           const envPath = resolve(dockerOut, ".env.docker");
           const current = await Bun.file(envPath).text();
           const tokenLine = `OKE_VAULT_TOKEN=${boot.appToken}`;
@@ -779,8 +805,34 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     consoleServer.stop();
     mcpServer?.stop();
     docsMcpServer?.stop();
+    if (dockerStarted) {
+      const started = dockerStarted;
+      dockerStarted = null;
+      const stopCompose =
+        options.composeStop ??
+        ((files, dir, env) => {
+          const args = ["compose", ...files.flatMap((f) => ["-f", f]), "stop"];
+          const result = Bun.spawnSync(["docker", ...args], {
+            cwd: dir,
+            stdout: "inherit",
+            stderr: "inherit",
+            env: { ...process.env, ...env },
+          });
+          if (result.exitCode !== 0) {
+            console.error(
+              `oke dev: docker compose stop exited ${result.exitCode ?? "unknown"} (containers may still be running)`,
+            );
+          }
+        });
+      try {
+        stopCompose(started.files, started.cwd, started.env);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+      }
+    }
     process.off("SIGINT", onSignal);
     process.off("SIGTERM", onSignal);
+    process.off("SIGHUP", onSignal);
   };
 
   const onSignal = () => {
@@ -789,6 +841,8 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   };
   process.on("SIGINT", onSignal);
   process.on("SIGTERM", onSignal);
+  // Terminal close often delivers SIGHUP rather than SIGINT.
+  process.on("SIGHUP", onSignal);
 
   const session: DevSession = {
     plan: {

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

@@ -0,0 +1,179 @@
+/**
+ * `oke docker clean` — non-interactive flag matrix + wiring.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { composeProjectName, type DockerRunner } from "../docker/cleanup.ts";
+import { dockerCli } from "./docker.ts";
+import { dockerCleanHelp, parseDockerCleanArgs, runDockerClean } from "./docker-clean.ts";
+import { EXIT_OK, EXIT_USAGE } from "./exit.ts";
+import { formatOkeHelp, flagTokensFor, OKE_COMMANDS } from "./registry.ts";
+
+function fakeStacksRunner(projects: readonly string[]): DockerRunner {
+  return async (args) => {
+    const key = args.join(" ");
+    if (key.startsWith("compose ls")) {
+      return {
+        exitCode: 0,
+        stdout: JSON.stringify(projects.map((Name) => ({ Name, Status: "exited" }))),
+        stderr: "",
+      };
+    }
+    if (key.includes("label=com.docker.compose.project=") && key.startsWith("ps")) {
+      const filter = args[args.indexOf("--filter")! + 1]!;
+      const project = filter.replace(/^label=com\.docker\.compose\.project=/, "");
+      if (!projects.includes(project)) return { exitCode: 0, stdout: "", stderr: "" };
+      return {
+        exitCode: 0,
+        stdout: JSON.stringify({
+          ID: "id",
+          Names: `${project}-store-sql-1`,
+          State: "exited",
+          Labels: `com.docker.compose.project=${project},com.docker.compose.service=store-sql`,
+        }),
+        stderr: "",
+      };
+    }
+    if (key.startsWith("ps -a --filter label=com.docker.compose.project --format")) {
+      return {
+        exitCode: 0,
+        stdout: projects
+          .map((project) =>
+            JSON.stringify({
+              ID: "id",
+              Names: `${project}-store-sql-1`,
+              State: "exited",
+              Labels: `com.docker.compose.project=${project},com.docker.compose.service=store-sql`,
+            }),
+          )
+          .join("\n"),
+        stderr: "",
+      };
+    }
+    if (key.startsWith("volume ls") || key.startsWith("network ls")) {
+      return { exitCode: 0, stdout: "", stderr: "" };
+    }
+    if (key.startsWith("compose -p ") && key.includes("down")) {
+      return { exitCode: 0, stdout: "", stderr: "" };
+    }
+    return { exitCode: 1, stdout: "", stderr: `unexpected: ${key}` };
+  };
+}
+
+describe("oke docker clean", () => {
+  test("parseDockerCleanArgs", () => {
+    expect(parseDockerCleanArgs(["--yes", "--all"])).toEqual({ yes: true, all: true });
+    expect(parseDockerCleanArgs(["-y"])).toEqual({ yes: true, all: false });
+    expect(parseDockerCleanArgs(["--help"]).help).toBe(true);
+    expect(() => parseDockerCleanArgs(["--nope"])).toThrow(/unknown flag/);
+  });
+
+  test("non-TTY outside without --all --yes → usage", async () => {
+    const err: string[] = [];
+    const code = await runDockerClean({
+      cwd: await mkdtemp(join(tmpdir(), "oke-clean-out-")),
+      stdinIsTTY: false,
+      yes: true,
+      all: false,
+      runDocker: fakeStacksRunner(["oke-dev-aaaaaa"]),
+      writeErr: (t) => err.push(t),
+    });
+    expect(code).toBe(EXIT_USAGE);
+    expect(err.join("")).toContain("--all --yes");
+  });
+
+  test("non-TTY outside --all --yes tears down every stack", async () => {
+    const downs: string[] = [];
+    const run: DockerRunner = async (args) => {
+      if (args[0] === "compose" && args[1] === "-p" && args.includes("down")) {
+        downs.push(args[2]!);
+        return { exitCode: 0, stdout: "", stderr: "" };
+      }
+      return fakeStacksRunner(["oke-dev-aaaaaa", "oke-dev-bbbbbb"])(args);
+    };
+    const logs: string[] = [];
+    const code = await runDockerClean({
+      cwd: await mkdtemp(join(tmpdir(), "oke-clean-all-")),
+      stdinIsTTY: false,
+      yes: true,
+      all: true,
+      runDocker: run,
+      write: (t) => logs.push(t),
+    });
+    expect(code).toBe(EXIT_OK);
+    expect(downs.sort()).toEqual(["oke-dev-aaaaaa", "oke-dev-bbbbbb"]);
+    expect(logs.join("")).toContain("down -v");
+  });
+
+  test("non-TTY inside --yes cleans current project only", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-clean-in-"));
+    await Bun.write(join(dir, "oke.config.ts"), "export default {};\n");
+    const current = composeProjectName(dir);
+    const other = "oke-dev-ffffff";
+    const downs: string[] = [];
+    const run: DockerRunner = async (args) => {
+      if (args[0] === "compose" && args[1] === "-p" && args.includes("down")) {
+        downs.push(args[2]!);
+        return { exitCode: 0, stdout: "", stderr: "" };
+      }
+      return fakeStacksRunner([current, other])(args);
+    };
+    const code = await runDockerClean({
+      cwd: dir,
+      stdinIsTTY: false,
+      yes: true,
+      runDocker: run,
+      write: () => {},
+    });
+    expect(code).toBe(EXIT_OK);
+    expect(downs).toEqual([current]);
+  });
+
+  test("non-TTY without --yes → usage", async () => {
+    const code = await runDockerClean({
+      cwd: await mkdtemp(join(tmpdir(), "oke-clean-noy-")),
+      stdinIsTTY: false,
+      runDocker: fakeStacksRunner(["oke-dev-aaaaaa"]),
+      writeErr: () => {},
+    });
+    expect(code).toBe(EXIT_USAGE);
+  });
+
+  test("TTY empty selection exits 0", async () => {
+    const code = await runDockerClean({
+      cwd: await mkdtemp(join(tmpdir(), "oke-clean-empty-")),
+      stdinIsTTY: true,
+      runDocker: fakeStacksRunner(["oke-dev-aaaaaa"]),
+      pickKeys: async () => [],
+      write: () => {},
+    });
+    expect(code).toBe(EXIT_OK);
+  });
+
+  test("TTY cancel exits 0", async () => {
+    const code = await runDockerClean({
+      cwd: await mkdtemp(join(tmpdir(), "oke-clean-cancel-")),
+      stdinIsTTY: true,
+      runDocker: fakeStacksRunner(["oke-dev-aaaaaa"]),
+      pickKeys: async () => null,
+      write: () => {},
+    });
+    expect(code).toBe(EXIT_OK);
+  });
+
+  test("dockerCli routes clean subcommand", async () => {
+    const code = await dockerCli(["clean", "--help"]);
+    expect(code).toBe(EXIT_OK);
+    expect(dockerCleanHelp()).toContain("--all");
+  });
+
+  test("registry lists clean flags and help mentions clean", () => {
+    const docker = OKE_COMMANDS.find((c) => c.name === "docker")!;
+    expect(flagTokensFor(docker, "clean")).toContain("--yes");
+    expect(flagTokensFor(docker, "clean")).toContain("--all");
+    expect(formatOkeHelp()).toContain("clean");
+  });
+});

package/src/cli/docker-clean.ts

@@ -0,0 +1,406 @@
+/**
+ * `oke docker clean` — remove leftover `oke-dev-*` compose stacks.
+ */
+
+import { cancel, confirm, intro, isCancel, multiselect, outro } from "@clack/prompts";
+import {
+  composeProjectName,
+  defaultDockerRunner,
+  downStack,
+  isOkeProjectRoot,
+  listOkeComposeProjects,
+  resolveSelection,
+  selectionKey,
+  type DockerRunner,
+  type OkeContainer,
+  type OkeStack,
+} from "../docker/cleanup.ts";
+import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
+
+/** Parsed flags for {@link runDockerClean}. */
+export interface DockerCleanFlags {
+  readonly yes?: boolean;
+  readonly all?: boolean;
+}
+
+/** Options for {@link runDockerClean} (injectable for tests). */
+export interface DockerCleanOptions extends DockerCleanFlags {
+  readonly cwd?: string;
+  readonly stdinIsTTY?: boolean;
+  readonly runDocker?: DockerRunner;
+  readonly write?: (text: string) => void;
+  readonly writeErr?: (text: string) => void;
+  /** Override interactive container pick (tests). `null` = cancel. */
+  readonly pickKeys?: (
+    stacks: readonly OkeStack[],
+    scope: "current" | "other" | "all",
+  ) => Promise<readonly string[] | null>;
+  /** Override confirm (tests). */
+  readonly confirmDown?: (projects: readonly string[]) => Promise<boolean>;
+  /** When inside a project and other stacks exist — ask to include them. */
+  readonly askIncludeOthers?: () => Promise<boolean | null>;
+}
+
+/**
+ * Help text for `oke docker clean`.
+ */
+export function dockerCleanHelp(): string {
+  return `oke docker clean [--yes|-y] [--all]
+
+Remove leftover OKE docker compose stacks (containers, networks, volumes).
+
+Inside a project: focuses the current stack (oke-dev-<id>); optionally
+include other stacks on this machine.
+Outside a project: list every oke-dev-* stack and pick what to remove.
+
+  --yes, -y   Non-interactive; required when stdin is not a TTY
+  --all       With --yes outside a project: remove every oke-dev-* stack
+`;
+}
+
+/**
+ * Parse args after `docker clean`.
+ *
+ * @param args - Flag tokens
+ */
+export function parseDockerCleanArgs(args: readonly string[]): DockerCleanFlags & {
+  readonly help?: boolean;
+} {
+  let yes = false;
+  let all = false;
+  for (const a of args) {
+    if (a === "--help" || a === "-h") return { help: true };
+    if (a === "--yes" || a === "-y") yes = true;
+    else if (a === "--all") all = true;
+    else if (a.startsWith("-")) {
+      throw new Error(`oke docker clean: unknown flag ${a}`);
+    } else {
+      throw new Error(`oke docker clean: unexpected argument ${a}`);
+    }
+  }
+  return { yes, all };
+}
+
+/**
+ * Run stack cleanup.
+ *
+ * @param options - Flags + seams
+ * @returns Exit code
+ */
+export async function runDockerClean(options: DockerCleanOptions = {}): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const writeErr = options.writeErr ?? ((t) => process.stderr.write(t));
+  const cwd = options.cwd ?? process.cwd();
+  const run = options.runDocker ?? defaultDockerRunner;
+  const tty = options.stdinIsTTY ?? Boolean(process.stdin.isTTY);
+  const yes = options.yes === true;
+  const all = options.all === true;
+
+  let stacks: readonly OkeStack[];
+  try {
+    stacks = await listOkeComposeProjects(run);
+  } catch (err) {
+    writeErr(`${err instanceof Error ? err.message : String(err)}\n`);
+    return EXIT_RUNTIME;
+  }
+
+  const inside = await isOkeProjectRoot(cwd);
+  const currentProject = inside ? composeProjectName(cwd) : null;
+
+  if (stacks.length === 0) {
+    write("oke docker clean: no oke-dev-* stacks found\n");
+    return EXIT_OK;
+  }
+
+  if (!tty) {
+    return runNonInteractive({
+      stacks,
+      inside,
+      currentProject,
+      yes,
+      all,
+      run,
+      write,
+      writeErr,
+    });
+  }
+
+  return runInteractive({
+    stacks,
+    inside,
+    currentProject,
+    run,
+    write,
+    writeErr,
+    pickKeys: options.pickKeys,
+    confirmDown: options.confirmDown,
+    askIncludeOthers: options.askIncludeOthers,
+  });
+}
+
+/**
+ * CLI entry for `oke docker clean …`.
+ *
+ * @param args - Args after `clean`
+ */
+export async function dockerCleanCli(args: readonly string[]): Promise<number> {
+  let flags: ReturnType<typeof parseDockerCleanArgs>;
+  try {
+    flags = parseDockerCleanArgs(args);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    console.error(dockerCleanHelp());
+    return EXIT_USAGE;
+  }
+  if (flags.help) {
+    console.log(dockerCleanHelp());
+    return EXIT_OK;
+  }
+  return runDockerClean(flags);
+}
+
+async function runNonInteractive(options: {
+  readonly stacks: readonly OkeStack[];
+  readonly inside: boolean;
+  readonly currentProject: string | null;
+  readonly yes: boolean;
+  readonly all: boolean;
+  readonly run: DockerRunner;
+  readonly write: (t: string) => void;
+  readonly writeErr: (t: string) => void;
+}): Promise<number> {
+  const { stacks, inside, currentProject, yes, all, run, write, writeErr } = options;
+
+  if (!yes) {
+    writeErr("oke docker clean: non-TTY requires --yes (and --all when outside a project)\n");
+    return EXIT_USAGE;
+  }
+
+  let projects: string[];
+  if (inside && currentProject) {
+    if (all) {
+      projects = stacks.map((s) => s.project);
+    } else {
+      const hasCurrent = stacks.some((s) => s.project === currentProject);
+      if (!hasCurrent) {
+        write(`oke docker clean: no stack for this project (${currentProject})\n`);
+        return EXIT_OK;
+      }
+      projects = [currentProject];
+    }
+  } else {
+    if (!all) {
+      writeErr(
+        "oke docker clean: outside a project, pass --all --yes to remove every oke-dev-* stack\n",
+      );
+      return EXIT_USAGE;
+    }
+    projects = stacks.map((s) => s.project);
+  }
+
+  return tearDownProjects(projects, run, write, writeErr);
+}
+
+async function runInteractive(options: {
+  readonly stacks: readonly OkeStack[];
+  readonly inside: boolean;
+  readonly currentProject: string | null;
+  readonly run: DockerRunner;
+  readonly write: (t: string) => void;
+  readonly writeErr: (t: string) => void;
+  readonly pickKeys?: DockerCleanOptions["pickKeys"];
+  readonly confirmDown?: DockerCleanOptions["confirmDown"];
+  readonly askIncludeOthers?: DockerCleanOptions["askIncludeOthers"];
+}): Promise<number> {
+  const {
+    stacks,
+    inside,
+    currentProject,
+    run,
+    write,
+    writeErr,
+    pickKeys,
+    confirmDown,
+    askIncludeOthers,
+  } = options;
+
+  intro("oke docker clean");
+
+  const selectedKeys: string[] = [];
+
+  if (inside && currentProject) {
+    const current = stacks.filter((s) => s.project === currentProject);
+    const others = stacks.filter((s) => s.project !== currentProject);
+
+    if (current.length === 0) {
+      write(`No stack for this project (${currentProject}).\n`);
+    } else {
+      const keys = await pickContainerKeys({
+        stacks: current,
+        scope: "current",
+        message: `Containers for this project (${currentProject})`,
+        initialAll: true,
+        pickKeys,
+      });
+      if (keys === null) {
+        cancel("Cancelled.");
+        return EXIT_OK;
+      }
+      selectedKeys.push(...keys);
+    }
+
+    if (others.length > 0) {
+      const include = askIncludeOthers ? await askIncludeOthers() : await askIncludeOthersPrompt();
+      if (include === null) {
+        cancel("Cancelled.");
+        return EXIT_OK;
+      }
+      if (include) {
+        const keys = await pickContainerKeys({
+          stacks: others,
+          scope: "other",
+          message: "Other OKE stacks on this machine",
+          initialAll: false,
+          pickKeys,
+        });
+        if (keys === null) {
+          cancel("Cancelled.");
+          return EXIT_OK;
+        }
+        selectedKeys.push(...keys);
+      }
+    }
+  } else {
+    const keys = await pickContainerKeys({
+      stacks,
+      scope: "all",
+      message: "OKE docker stacks on this machine",
+      initialAll: false,
+      pickKeys,
+    });
+    if (keys === null) {
+      cancel("Cancelled.");
+      return EXIT_OK;
+    }
+    selectedKeys.push(...keys);
+  }
+
+  if (selectedKeys.length === 0) {
+    outro("Nothing selected.");
+    return EXIT_OK;
+  }
+
+  const { projects } = resolveSelection(selectedKeys, stacks);
+  if (projects.length === 0) {
+    outro("Nothing selected.");
+    return EXIT_OK;
+  }
+
+  const summary = projects
+    .map((p) => {
+      const stack = stacks.find((s) => s.project === p);
+      const n = stack?.containers.length ?? 0;
+      return n === 0 ? `  ${p} (volumes/networks only)` : `  ${p} (${n} container(s))`;
+    })
+    .join("\n");
+
+  const ok = confirmDown
+    ? await confirmDown(projects)
+    : await confirm({
+        message: `Remove these stack(s) — containers, networks, and volumes?\n${summary}`,
+        initialValue: false,
+      });
+
+  if (isCancel(ok) || ok === false) {
+    cancel("Cancelled.");
+    return EXIT_OK;
+  }
+
+  const code = await tearDownProjects(projects, run, write, writeErr);
+  if (code === EXIT_OK) outro(`Removed ${projects.length} stack(s).`);
+  return code;
+}
+
+async function askIncludeOthersPrompt(): Promise<boolean | null> {
+  const value = await confirm({
+    message: "Also clean other OKE stacks on this machine?",
+    initialValue: false,
+  });
+  if (isCancel(value)) return null;
+  return value;
+}
+
+async function pickContainerKeys(options: {
+  readonly stacks: readonly OkeStack[];
+  readonly scope: "current" | "other" | "all";
+  readonly message: string;
+  readonly initialAll: boolean;
+  readonly pickKeys?: DockerCleanOptions["pickKeys"];
+}): Promise<readonly string[] | null> {
+  const { stacks, scope, message, initialAll, pickKeys } = options;
+  if (pickKeys) return pickKeys(stacks, scope);
+
+  const entries = selectionEntries(stacks);
+  if (entries.length === 0) return [];
+
+  const value = await multiselect({
+    message: `${message} — selecting any container removes its whole stack`,
+    options: entries.map((e) => ({
+      value: e.key,
+      label: e.label,
+      hint: e.hint,
+    })),
+    initialValues: initialAll ? entries.map((e) => e.key) : [],
+    required: false,
+  });
+  if (isCancel(value)) return null;
+  return value;
+}
+
+function selectionEntries(stacks: readonly OkeStack[]): readonly {
+  readonly key: string;
+  readonly label: string;
+  readonly hint?: string;
+}[] {
+  const out: { key: string; label: string; hint?: string }[] = [];
+  for (const stack of stacks) {
+    if (stack.containers.length === 0) {
+      out.push({
+        key: selectionKey(stack.project),
+        label: stack.project,
+        hint: "no containers · volumes/networks may remain",
+      });
+      continue;
+    }
+    for (const c of stack.containers) {
+      out.push({
+        key: selectionKey(stack.project, c.name),
+        label: `${stack.project} · ${displayContainer(c)}`,
+        hint: c.state || undefined,
+      });
+    }
+  }
+  return out;
+}
+
+function displayContainer(c: OkeContainer): string {
+  return c.service && c.service !== c.name ? `${c.service} (${c.name})` : c.name;
+}
+
+async function tearDownProjects(
+  projects: readonly string[],
+  run: DockerRunner,
+  write: (t: string) => void,
+  writeErr: (t: string) => void,
+): Promise<number> {
+  for (const project of projects) {
+    try {
+      write(`oke docker clean: down -v ${project}\n`);
+      await downStack(project, run);
+    } catch (err) {
+      writeErr(`${err instanceof Error ? err.message : String(err)}\n`);
+      return EXIT_RUNTIME;
+    }
+  }
+  return EXIT_OK;
+}