okengine 0.11.2 → 0.13.0

package/src/console/ui-next/vite-console-kernel-plugin.ts

@@ -0,0 +1,195 @@
+/**
+ * Vite `apply: "serve"` plugin — boots an ephemeral Console kernel on :6533
+ * so `bun run dev:console` prints login (or claim) details in the same terminal.
+ *
+ * Set `OKE_CONSOLE_SEEDED=1` (or `bun run dev:console:seed`) to
+ * load the keel Manifest + WideEvent as the Playwright fixture.
+ *
+ * Set `OKE_CONSOLE_FRESH=1` (or `bun run dev:console:fresh`) to
+ * skip the fixed operator and keep first-admin claim open.
+ *
+ * Requires Vite under Bun (`bunx --bun vite`): Node lacks `import.meta.dir`
+ * used by the Console graph.
+ */
+
+import type { Plugin, ViteDevServer } from "vite";
+import { isPortInUse } from "../../cli/ports.ts";
+import { CONSOLE_PORT } from "../../runtime/types.ts";
+import { serveConsole, type ConsoleServerHandle } from "../server/serve.ts";
+import {
+  isConsoleFresh,
+  isConsoleKernelSkipped,
+  UI_NEXT_DEV_OPERATOR,
+  seedUiNextDevOperator,
+} from "./ui-next-dev-operator.ts";
+import {
+  appendUiNextSeedRun,
+  isConsoleSeeded,
+  UI_NEXT_SEEDED_MANIFEST,
+  UI_NEXT_SEED_VAULT_LAYERS,
+  uiNextSeededSummary,
+} from "./ui-next-seed.ts";
+
+/** Vite SPA URL for ui-next (proxies `/console` → kernel :6533). */
+const UI_NEXT_DEV_URL = "http://127.0.0.1:6537";
+
+/**
+ * Print post-boot instructions for console-next (operator login or fresh claim).
+ *
+ * @param log - Vite logger line writer
+ * @param options - Mode flags + optional claim code when fresh
+ */
+function printConsoleNextBanner(
+  log: (msg: string) => void,
+  options: {
+    readonly seeded: boolean;
+    readonly fresh: boolean;
+    readonly claimCode: string;
+  },
+): void {
+  const { seeded, fresh, claimCode } = options;
+  log("");
+  log(`[oke] console ready`);
+  log(`      URL:   ${UI_NEXT_DEV_URL}`);
+  if (fresh) {
+    log(`      Claim: ${claimCode}`);
+    log(`      Mode:  fresh (first-admin claim open)`);
+  } else {
+    log(`      Login: ${UI_NEXT_DEV_OPERATOR.email} / ${UI_NEXT_DEV_OPERATOR.password}`);
+  }
+  if (seeded) {
+    log(`      Seed:  ${uiNextSeededSummary()}`);
+    if (fresh) {
+      log(`      Next:  open URL → claim → Overview (graph + Traces row already present)`);
+    } else {
+      log(`      Next:  open URL → Sign in → Overview (graph + Traces row already present)`);
+    }
+  } else if (!fresh) {
+    log(`      Tip:   bun run dev:console:seed  — all 8 elements + ~80 lived-in traces`);
+  } else {
+    log(`      Tip:   bun run dev:console:fresh:seed  — claim + all 8 elements + ~80 traces`);
+  }
+  log("");
+}
+
+/**
+ * Start Console beside the ui-next Vite server (dev only, not `vite build`).
+ */
+export function okeConsoleKernelPlugin(): Plugin {
+  let handle: ConsoleServerHandle | null = null;
+  let stopping = false;
+
+  const stop = (): void => {
+    if (stopping || !handle) return;
+    stopping = true;
+    try {
+      handle.stop(true);
+    } catch {
+      // ignore
+    }
+    handle = null;
+  };
+
+  return {
+    name: "oke-console-kernel",
+    apply: "serve",
+    async configureServer(server: ViteDevServer) {
+      // `oke dev` already bound the kernel — Vite is SPA / HMR only.
+      if (isConsoleKernelSkipped()) return;
+
+      if (typeof Bun === "undefined") {
+        server.config.logger.error(
+          `\n[oke] Run Vite under Bun:\n` +
+            `        bunx --bun vite --config src/console/ui-next/vite.config.ts\n` +
+            `      (package script \`dev:console\` already does this)\n`,
+        );
+        process.exit(1);
+      }
+
+      const port = CONSOLE_PORT;
+      const hostname = "127.0.0.1";
+      const seeded = isConsoleSeeded();
+      const fresh = isConsoleFresh();
+
+      if (await isPortInUse(port)) {
+        server.config.logger.error(
+          `\n[oke] Console port :${port} is already in use.\n` +
+            `      Stop the other process, then re-run: bun run ${
+              fresh
+                ? seeded
+                  ? "dev:console:fresh:seed"
+                  : "dev:console:fresh"
+                : seeded
+                  ? "dev:console:seed"
+                  : "dev:console"
+            }\n`,
+        );
+        process.exit(1);
+      }
+
+      // Local SPA kernel: claim + Vite matter; Channel/OPEN-token honesty
+      // lines are noise here (same latch `oke dev` uses on Backend children).
+      process.env["OKE_SUPPRESS_BOOT_WARN"] = "1";
+
+      const operators = fresh ? undefined : (await seedUiNextDevOperator()).store;
+
+      handle = await serveConsole({
+        port,
+        hostname,
+        cwd: process.cwd(),
+        persist: false,
+        silentClaim: !fresh,
+        env: "test",
+        secret: process.env.OKE_CONSOLE_SECRET ?? "oke-console-next-dev-secret",
+        ...(operators ? { operators } : {}),
+        ...(seeded
+          ? { manifest: UI_NEXT_SEEDED_MANIFEST, vaultLayerSeed: UI_NEXT_SEED_VAULT_LAYERS }
+          : {}),
+      });
+
+      if (seeded) {
+        const runs = handle.console.app.bootResult?.runs;
+        if (!runs) {
+          throw new Error("console seeded: Console bootResult.runs missing");
+        }
+        await appendUiNextSeedRun(runs);
+        if (handle.console.state.storeRuntime) {
+          const { seedUiNextStoreData } = await import("./ui-next-seed.ts");
+          await seedUiNextStoreData(handle.console.state.storeRuntime);
+        }
+        // Same thin host substitute as the Playwright fixture — Replay hits
+        // real console.traces.replay → runReplay without a project entry.
+        handle.console.state.replayTrace = async ({ event, dryRun }) => ({
+          output: { replayed: event.id, dryRun, input: event.input ?? null },
+        });
+        const { bootUiNextSeedInvoke } = await import("./seed-invoke-host.ts");
+        const seedInvoke = await bootUiNextSeedInvoke({
+          ...(handle.console.state.storeRuntime
+            ? { storeRuntime: handle.console.state.storeRuntime }
+            : {}),
+          manifest: UI_NEXT_SEEDED_MANIFEST,
+        });
+        handle.console.state.invokeUserFlow = seedInvoke.invokeUserFlow;
+      }
+
+      server.config.logger.info(`[oke] Console ${handle.url}`);
+      printConsoleNextBanner(
+        (msg) => {
+          server.config.logger.info(msg);
+        },
+        {
+          seeded,
+          fresh,
+          claimCode: handle.console.state.claim.code,
+        },
+      );
+
+      const onClose = (): void => {
+        stop();
+      };
+      server.httpServer?.once("close", onClose);
+      process.once("SIGINT", onClose);
+      process.once("SIGTERM", onClose);
+    },
+  };
+}

package/src/console/ui-next/vite.config.ts

@@ -0,0 +1,88 @@
+/**
+ * Vite build for the Console SPA.
+ * Dev server :6537 with /console → kernel proxy.
+ * `oke dev` sets `OKE_CONSOLE_KERNEL=0` so Vite is SPA/HMR only.
+ *
+ * Scripts:
+ * - `dev:console` — fixed operator
+ * - `dev:console:seed` — fixed operator + Manifest/traces (`OKE_CONSOLE_SEEDED=1`)
+ * - `dev:console:fresh` — claim open (`OKE_CONSOLE_FRESH=1`)
+ * - `dev:console:fresh:seed` — claim + seed
+ */
+
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vite";
+import {
+  isConsoleFresh,
+  isConsoleKernelSkipped,
+  shouldPrefillDevOperator,
+  UI_NEXT_DEV_OPERATOR,
+} from "./ui-next-dev-operator.ts";
+import { okeConsoleKernelPlugin } from "./vite-console-kernel-plugin.ts";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(here, "../../../package.json"), "utf8")) as {
+  version: string;
+};
+
+export default defineConfig(({ command }) => {
+  const attachToOkeDev = isConsoleKernelSkipped();
+  const injectDevOperator = shouldPrefillDevOperator({
+    serve: command === "serve",
+    fresh: isConsoleFresh(),
+    kernelSkipped: attachToOkeDev,
+  })
+    ? UI_NEXT_DEV_OPERATOR
+    : null;
+  const consoleProxy = process.env["OKE_CONSOLE_PROXY"] ?? "http://127.0.0.1:6533";
+
+  return {
+    root: here,
+    plugins: [react(), tailwindcss(), ...(attachToOkeDev ? [] : [okeConsoleKernelPlugin()])],
+    define: {
+      __OKE_VERSION__: JSON.stringify(pkg.version),
+      __OKE_DEV_OPERATOR__: JSON.stringify(injectDevOperator),
+      __OKE_CONSOLE_SEEDED__: JSON.stringify(process.env["OKE_CONSOLE_SEEDED"] === "1"),
+    },
+    resolve: {
+      alias: {
+        "@": resolve(here, "src"),
+        "@console/password-policy": resolve(here, "../password-policy.ts"),
+      },
+    },
+    build: {
+      outDir: resolve(here, "dist"),
+      emptyOutDir: true,
+      sourcemap: false,
+      target: "esnext",
+      // Keep minified chunks under Vite's 500 kB warning. Route pages are
+      // lazy; these groups pull the remaining heavy static vendors out of
+      // the entry (Shiki is already a slim core + five grammars).
+      rolldownOptions: {
+        output: {
+          codeSplitting: {
+            groups: [
+              { name: "react-dom", test: /[\\/]node_modules[\\/]react-dom[\\/]/ },
+              { name: "xyflow", test: /[\\/]node_modules[\\/]@xyflow[\\/]/ },
+            ],
+          },
+        },
+      },
+    },
+    server: {
+      port: 6537,
+      strictPort: true,
+      proxy: {
+        "/console": {
+          target: consoleProxy,
+          changeOrigin: true,
+          ws: true,
+        },
+      },
+    },
+  };
+});

package/src/console/xss.gate.test.ts

@@ -3,37 +3,31 @@
  *
  * console §10.2: this is a build gate, not a review convention.
  *
- * The scan walks all of `src/console/ui` recursively (not a hard-coded panel
- * list from Prompt 16). The panel-directory assertion below fails the build
- * if a new `ui/<panel>` folder appears without being covered by that walk.
+ * The scan walks `src/console/ui-next/src` recursively. The feature-directory
+ * assertion fails the build if a new `features/<name>` folder appears without
+ * being covered by that walk.
  */
 
 import { describe, expect, test } from "bun:test";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 
-const UI_ROOT = `${import.meta.dir}/ui`;
+const UI_ROOT = `${import.meta.dir}/ui-next/src`;
+const FEATURES_ROOT = `${UI_ROOT}/features`;
 
 /**
- * Panel feature directories that must be covered by the XSS scan today.
- * Update this list when a 18th panel lands — the recursive walk already
- * covers it; the list makes coverage explicit in CI output.
+ * Feature directories that must be covered by the XSS scan today.
+ * Update this list when a new Console module lands — the recursive walk
+ * already covers it; the list makes coverage explicit in CI output.
  */
-export const CONSOLE_UI_PANEL_DIRS = [
-  "access",
-  "ai",
-  "architecture",
-  "channels",
-  "clock",
-  "diff",
+export const CONSOLE_UI_FEATURE_DIRS = [
+  "auth",
   "flows",
-  "gates",
-  "overview",
-  "plugins",
-  "runs",
-  "signals",
+  "not-found",
+  "observability",
+  "setup",
   "store",
-  "traces",
+  "units",
   "vault",
 ] as const;
 
@@ -77,18 +71,19 @@ export function findXssViolations(text: string): string[] {
 }
 
 describe("console XSS gate", () => {
-  test("scan glob covers every ui/<panel> directory that exists today", async () => {
-    const entries = await readdir(UI_ROOT, { withFileTypes: true });
+  test("scan glob covers every features/<module> directory that exists today", async () => {
+    const entries = await readdir(FEATURES_ROOT, { withFileTypes: true });
     const dirs = entries
       .filter((e) => e.isDirectory())
       .map((e) => e.name)
-      .filter((name) => name !== "dist" && name !== "shell" && name !== "node_modules")
       .sort();
-    expect(dirs).toEqual([...CONSOLE_UI_PANEL_DIRS].sort());
+    expect(dirs).toEqual([...CONSOLE_UI_FEATURE_DIRS].sort());
 
     const files = await collectSources(UI_ROOT);
-    for (const panel of CONSOLE_UI_PANEL_DIRS) {
-      const hit = files.some((f) => f.includes(`/ui/${panel}/`) || f.includes(`\\ui\\${panel}\\`));
+    for (const feature of CONSOLE_UI_FEATURE_DIRS) {
+      const hit = files.some(
+        (f) => f.includes(`/features/${feature}/`) || f.includes(`\\features\\${feature}\\`),
+      );
       expect(hit).toBe(true);
     }
   });

package/src/docker/compose.ts

@@ -58,7 +58,7 @@ export function composePathRefs(composeDir: string = DEFAULT_DOCKER_DIR): {
 } {
   const flat = composeDir === "." || composeDir === "";
   return {
-    envFile: ".env.docker",
+    envFile: flat ? ".env.local" : "../.env.local",
     buildContext: flat ? "." : "..",
     dockerfile: "Dockerfile",
   };
@@ -169,6 +169,7 @@ export function emitComposeLayers(
       env_file: [paths.envFile],
     };
     if (applied.environment) service.environment = applied.environment;
+    if (applied.build) service.build = applied.build;
     if (applied.command) service.command = applied.command;
     if (applied.entrypoint) service.entrypoint = applied.entrypoint;
     if (applied.healthcheck) service.healthcheck = applied.healthcheck;
@@ -184,12 +185,13 @@ export function emitComposeLayers(
       if (Object.keys(deps).length > 0) service.depends_on = deps;
     }
 
+    const extraServices = peerServices(applied.services, includeApp);
     const namedVolumes = namedVolumeDecls([
       ...(applied.volumes ?? []),
-      ...extraServiceVolumes(applied.services),
+      ...extraServiceVolumes(extraServices),
     ]);
     const doc: Record<string, unknown> = {
-      services: { [spec.serviceName]: service, ...applied.services },
+      services: { [spec.serviceName]: service, ...extraServices },
       networks: { oke: { external: false } },
     };
     if (Object.keys(namedVolumes).length > 0) {
@@ -507,7 +509,7 @@ const ROLE_SECTION_TITLE: Readonly<Record<string, string>> = {
   "channel.email": "channel.email — Mailpit (SMTP + UI)",
   signal: "signal — message bus",
   ai: "ai — local inference (llama.cpp / Ollama / vLLM / SGLang)",
-  proxy: "proxy — TLS terminator (Caddy / Traefik)",
+  proxy: "proxy — edge reverse proxy (Caddy / Traefik / nginx)",
 };
 
 /**
@@ -564,7 +566,7 @@ const ROLE_ALIASES: Readonly<Record<string, readonly string[]>> = {
   "store.index": ["OKE_STORE_INDEX_KEY"],
 };
 
-/** Optional controls documented in `.env.docker` and preserved on regeneration. */
+/** Optional controls documented in `.env.local` and preserved on regeneration. */
 const ROLE_CONTROL_EXAMPLES: Readonly<Record<string, readonly string[]>> = {
   "store.sql": ["PGDATA=/var/lib/postgresql/data/pgdata", "POSTGRES_INITDB_ARGS=--data-checksums"],
   "store.kv": ["OKE_STORE_KV_MAXMEMORY=256mb", "OKE_STORE_KV_MAXMEMORY_POLICY=allkeys-lru"],
@@ -627,10 +629,10 @@ export function formatStackEnv(env: Readonly<Record<string, string>>): string {
   const ordered = [...roles].sort((a, b) => a.localeCompare(b));
   const used = new Set<string>();
   const lines: string[] = [
-    "# docker/.env.docker — generated by `oke dev --docker`",
+    "# .env.local — stack keys written by `oke dev --docker`",
     "# Credentials + connection URLs for the local compose stack.",
     "# Host ports are unique per project (instance offset). Do not commit.",
-    "# Vault resolution: process.env → .env.local → docker/.env.docker → driver",
+    "# Vault resolution: driver → process.env → .env.local → dev-fallback",
     "#",
     "# Re-run `oke dev --docker` to regenerate. Put compose tweaks in",
     "# docker-compose.override.yml (or compose.override.yml for --split) — never put secrets in YAML.",
@@ -717,6 +719,23 @@ function namedVolumeDecls(
   return out;
 }
 
+/**
+ * Recipe extra services, minus peer overlays that only exist when `app` is
+ * in the stack (Traefik routing labels). A label-only `app` with no image
+ * or build is invalid Compose — `oke dev` is infra-only (`includeApp: false`).
+ *
+ * @param services - Extra compose service fragments from a recipe
+ * @param includeApp - Whether the stack includes the `app` service
+ */
+function peerServices(
+  services: Readonly<Record<string, Record<string, unknown>>> | undefined,
+  includeApp: boolean,
+): Record<string, Record<string, unknown>> {
+  const extra = { ...(services ?? {}) };
+  if (!includeApp) delete extra.app;
+  return extra;
+}
+
 /**
  * Volume mounts declared on companion services from {@link RecipeApplyResult.services}.
  *

package/src/docker/derive.ts

@@ -3,7 +3,8 @@
  */
 
 import { mkdirSync, readdirSync, rmSync, statSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { mergeDotenvAssignments } from "../drivers/vault-dotenv-parse.ts";
 import {
   assertNoCredentialsInYaml,
   buildSpecs,
@@ -15,6 +16,7 @@ import {
 } from "./compose.ts";
 import { emitDockerfile } from "./dockerfile.ts";
 import { buildCaddyfile } from "./recipes/caddy.ts";
+import { buildNginxConf } from "./recipes/nginx.ts";
 import {
   buildLlamaCppEntrypoint,
   LLAMA_CPP_ENTRYPOINT_FILE,
@@ -22,6 +24,11 @@ import {
   llamaCpp,
 } from "./recipes/llama-cpp.ts";
 import { buildPgDogToml, buildPgDogUsersToml, PGDOG_CONFIG_DIR } from "./recipes/pgdog.ts";
+import {
+  emitPostgresAdvisorDockerfile,
+  POSTGRES_ADVISOR_DOCKERFILE,
+  postgresAdvisor,
+} from "./recipes/postgres-advisor.ts";
 import type { DeriveOptions, DeriveResult, GeneratedFile } from "./types.ts";
 import { DEFAULT_DOCKER_DIR } from "./types.ts";
 import { APP_PORT } from "../runtime/types.ts";
@@ -29,8 +36,8 @@ import { APP_PORT } from "../runtime/types.ts";
 /**
  * Derive infrastructure files from normalised image pins.
  *
- * Credentials land only in the returned `stackEnv` (for `.env.docker`) and
- * in `pgdog/users.toml` when PgDog is present — never in generated YAML.
+ * Credentials land only in the returned `stackEnv` (merged into `.env.local`)
+ * and in `pgdog/users.toml` when PgDog is present — never in generated YAML.
  * User-owned overrides are listed in `composeFiles` but never written.
  *
  * @param options - Images / app / prod / layout flags
@@ -70,10 +77,15 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
     ...pgdogConfigFiles(specs),
     ...proxyConfigFiles(specs, normalised.appPort),
     ...llamaCppEntrypointFiles(specs),
+    ...postgresAdvisorDockerfileFiles(specs),
   ];
 
   for (const f of files) {
-    if (f.path.endsWith(".yml") || f.path === "Dockerfile") {
+    if (
+      f.path.endsWith(".yml") ||
+      f.path === "Dockerfile" ||
+      f.path === POSTGRES_ADVISOR_DOCKERFILE
+    ) {
       assertNoCredentialsInYaml(
         f.content,
         specs.map((s) => s.credentials),
@@ -84,6 +96,22 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
   return { specs, files, stackEnv, composeFiles };
 }
 
+/**
+ * Emit `Dockerfile.postgres-advisor` when `store.sql` pins the opt-in advisor image.
+ *
+ * @param specs - Normalised services
+ */
+function postgresAdvisorDockerfileFiles(specs: DeriveResult["specs"]): GeneratedFile[] {
+  const sql = specs.find((s) => s.role === "store.sql");
+  if (!sql || !postgresAdvisor.match(sql.image)) return [];
+  return [
+    {
+      path: POSTGRES_ADVISOR_DOCKERFILE,
+      content: emitPostgresAdvisorDockerfile(),
+    },
+  ];
+}
+
 /**
  * Emit `.oke/llama-entrypoint.py` (path relative to compose dir) when the AI
  * role is llama.cpp so first boot can Hub-pull then serve single-model
@@ -107,7 +135,7 @@ function llamaCppEntrypointFiles(specs: DeriveResult["specs"]): GeneratedFile[]
  * Emit PgDog TOML configs when both `pgdog` and `store.sql` are in the stack.
  *
  * `pgdog/pgdog.toml` has no secrets; `pgdog/users.toml` mirrors store.sql
- * credentials (same trust boundary as `.env.docker` — do not commit).
+ * credentials (same trust boundary as `.env.local` — do not commit).
  *
  * @param specs - Normalised services
  */
@@ -137,8 +165,8 @@ function pgdogConfigFiles(specs: DeriveResult["specs"]): GeneratedFile[] {
 /**
  * Emit proxy companion configs when `images.proxy` is pinned.
  *
- * Caddy gets a generated `Caddyfile`. Traefik configures via Docker labels
- * (no companion file).
+ * Caddy gets a generated `Caddyfile`. nginx gets `nginx.conf`. Traefik
+ * configures via Docker labels (no companion file).
  *
  * @param specs - Normalised services
  * @param appPort - App listen port (default 6530)
@@ -149,8 +177,12 @@ function proxyConfigFiles(
 ): GeneratedFile[] {
   const proxy = specs.find((s) => s.role === "proxy");
   if (!proxy) return [];
+  const port = appPort ?? APP_PORT;
   if (/caddy/i.test(proxy.image)) {
-    return [{ path: "Caddyfile", content: buildCaddyfile({ appPort: appPort ?? APP_PORT }) }];
+    return [{ path: "Caddyfile", content: buildCaddyfile({ appPort: port }) }];
+  }
+  if (/nginx/i.test(proxy.image)) {
+    return [{ path: "nginx.conf", content: buildNginxConf({ appPort: port }) }];
   }
   return [];
 }
@@ -158,7 +190,7 @@ function proxyConfigFiles(
 /**
  * Write derived files to disk. Never writes user overrides or credential
  * values into YAML. Prunes stale generated compose / PgDog artefacts from a
- * previous layout. Optionally writes `docker/.env.docker`.
+ * previous layout. Optionally merges stack keys into project `.env.local`.
  *
  * @param result - Derive result
  * @param outDir - Destination for Dockerfile / compose (usually `docker/`)
@@ -184,22 +216,45 @@ export async function writeDerivedFiles(
     written.push(path);
   }
   if (options.writeStackEnv) {
-    const envPath = `${root}/.env.docker`;
-    await Bun.write(envPath, formatStackEnv(result.stackEnv));
+    const envPath = join(stackEnvProjectRoot(root), ".env.local");
+    let existing = "";
+    try {
+      existing = await Bun.file(envPath).text();
+    } catch {
+      existing = "";
+    }
+    const next =
+      existing.trim().length === 0
+        ? formatStackEnv(result.stackEnv)
+        : mergeDotenvAssignments(existing, result.stackEnv);
+    await Bun.write(envPath, next);
     written.push(envPath);
   }
   return written;
 }
 
+/**
+ * Project root that owns `.env.local` — parent of `docker/` or the compose
+ * dir itself when the layout is flat.
+ *
+ * @param composeOutDir - Derive output directory
+ */
+function stackEnvProjectRoot(composeOutDir: string): string {
+  const base = composeOutDir.replace(/\/$/, "");
+  return basename(base) === DEFAULT_DOCKER_DIR ? dirname(base) : base;
+}
+
 /** Generated compose / companion paths safe to delete when absent from a derive. */
 const PRUNE_ROOT_FILES = new Set([
   "Dockerfile",
+  POSTGRES_ADVISOR_DOCKERFILE,
   "docker-compose.yml",
   "docker-stack.yml",
   "compose.yml",
   "compose.all.yml",
   "compose.prod.yml",
   "Caddyfile",
+  "nginx.conf",
   // Legacy: entrypoint used to land in `docker/`; now `.oke/` only.
   LLAMA_CPP_ENTRYPOINT_FILE,
   "pgdog.toml",
@@ -224,7 +279,7 @@ function pruneLlamaEntrypoint(root: string, keep: ReadonlySet<string>): void {
 
 /**
  * Remove previously generated artefacts that the current layout no longer emits.
- * Never touches user overrides or `.env.docker`.
+ * Never touches user overrides or project `.env.local`.
  *
  * @param root - Compose directory
  * @param keep - Relative paths that will be rewritten
@@ -238,7 +293,6 @@ function pruneStaleGenerated(root: string, keep: ReadonlySet<string>): void {
   }
   for (const name of entries) {
     if (name === COMPOSE_OVERRIDE || name === DOCKER_COMPOSE_OVERRIDE) continue;
-    if (name === ".env.docker") continue;
     const abs = join(root, name);
     let st: ReturnType<typeof statSync>;
     try {