create-oke 0.6.0 → 0.7.0

package/src/scaffold.ts

@@ -12,11 +12,18 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import { join, relative, resolve } from "node:path";
-import { resolveLocalOkengineRoot, resolveTemplateDir, type TemplateId } from "./templates.ts";
+import { basename, join, relative, resolve } from "node:path";
+import {
+  resolveLocalOkengineRoot,
+  resolveTemplateDir,
+  TEMPLATE_DEFAULT_MODE,
+  type TemplateId,
+} from "./templates.ts";
 import { agentsMdContent } from "./agents-md.ts";
+import type { CreateDefaults } from "./create-defaults.ts";
 import {
   DEFAULT_SQL_DRIVER,
+  applyCreateAnswers,
   sanitizeProjectName,
   shouldSkipTemplatePath,
   transformConfigForSqlDriver,
@@ -42,8 +49,11 @@ export type ScaffoldOptions = {
   /**
    * Store SQL driver — pins `oke.config.ts` `store.sql` local/docker/prod
    * when `postgres`. Default `sqlite` keeps the dual-mode config.
+   * Ignored when {@link createDefaults} is set.
    */
   readonly sqlDriver?: SqlDriverId;
+  /** Full customize / reuse answers — applied after copy. */
+  readonly createDefaults?: CreateDefaults;
 };
 
 /** Result of a successful scaffold. */
@@ -56,10 +66,36 @@ export type ScaffoldResult = {
   readonly okengineDependency: string;
   /** Store SQL driver applied to schema + config. */
   readonly sqlDriver: SqlDriverId;
+  /** Customize answers applied, if any. */
+  readonly createDefaults?: CreateDefaults;
   /** Relative paths written (POSIX), sorted. */
   readonly files: readonly string[];
 };
 
+/**
+ * Why `targetDir` cannot host a new project, or `null` when it is free / empty.
+ *
+ * Used by the wizard (early name validation) and {@link scaffold}.
+ *
+ * @param targetDir - Absolute or cwd-relative destination
+ */
+export function targetDirectoryBlockReason(targetDir: string): string | null {
+  const abs = resolve(targetDir);
+  if (!existsSync(abs)) return null;
+  let entries: string[];
+  try {
+    entries = readdirSync(abs);
+  } catch {
+    return `create-oke: cannot read target directory: ${abs}`;
+  }
+  if (entries.length === 0) return null;
+  const folder = basename(abs);
+  return (
+    `create-oke: "${folder}" already exists and is not empty (${abs}). ` +
+    `Pick another name, or remove that directory first.`
+  );
+}
+
 /**
  * Scaffold a new okengine project from the standard template.
  *
@@ -70,14 +106,15 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
   const targetDir = resolve(options.targetDir);
   const sourceDir = resolveTemplateDir(options.source.id);
   const label = options.source.id;
-  const sqlDriver = options.sqlDriver ?? DEFAULT_SQL_DRIVER;
+  const createDefaults = options.createDefaults;
+  const sqlDriver =
+    createDefaults?.drivers.store.sql.local === "postgres" || options.sqlDriver === "postgres"
+      ? "postgres"
+      : (options.sqlDriver ?? DEFAULT_SQL_DRIVER);
 
-  if (existsSync(targetDir)) {
-    const entries = readdirSync(targetDir);
-    if (entries.length > 0) {
-      throw new Error(`create-oke: target directory is not empty: ${targetDir}`);
-    }
-  } else {
+  const blocked = targetDirectoryBlockReason(targetDir);
+  if (blocked) throw new Error(blocked);
+  if (!existsSync(targetDir)) {
     mkdirSync(targetDir, { recursive: true });
   }
 
@@ -95,7 +132,11 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
     const nextPkg = transformPackageJson(sourcePkg, name, okengineDependency);
     writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`, "utf8");
 
-    applySqlDriverTransforms(targetDir, sqlDriver);
+    if (createDefaults) {
+      applyCreateDefaultsTransforms(targetDir, createDefaults);
+    } else {
+      applySqlDriverTransforms(targetDir, sqlDriver);
+    }
 
     if (options.writeAgentsMd !== false) {
       const agentsPath = join(targetDir, "AGENTS.md");
@@ -110,6 +151,10 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
       if (!written.includes(".env.local")) written.push(".env.local");
     }
 
+    // Seed `.oke/mode` so `oke dev` does not re-ask local vs docker.
+    writeProjectDevMode(targetDir, resolveInitialDevMode(createDefaults, options.source.id));
+    if (!written.includes(".oke/mode")) written.push(".oke/mode");
+
     written.sort();
     return {
       targetDir,
@@ -118,6 +163,7 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
       label,
       okengineDependency,
       sqlDriver,
+      ...(createDefaults !== undefined ? { createDefaults } : {}),
       files: written,
     };
   } catch (e) {
@@ -147,6 +193,47 @@ function applySqlDriverTransforms(targetDir: string, sqlDriver: SqlDriverId): vo
   }
 }
 
+/**
+ * Apply full customize / reuse defaults to `oke.config.ts`.
+ *
+ * @param targetDir - Scaffolded project root
+ * @param defaults - Persisted create answers
+ */
+function applyCreateDefaultsTransforms(targetDir: string, defaults: CreateDefaults): void {
+  const configPath = join(targetDir, "oke.config.ts");
+  if (!existsSync(configPath)) {
+    throw new Error("create-oke: scaffolded project has no oke.config.ts");
+  }
+  const next = applyCreateAnswers(readFileSync(configPath, "utf8"), defaults);
+  writeFileSync(configPath, next, "utf8");
+}
+
+/**
+ * Map create-oke profile / template → persisted `oke dev` mode.
+ *
+ * @param defaults - Customize / reuse answers, or undefined for recommended
+ * @param template - Starter id (recommended path uses template default mode)
+ */
+export function resolveInitialDevMode(
+  defaults: CreateDefaults | undefined,
+  template: TemplateId = "standard",
+): "local" | "docker" {
+  if (defaults?.profile === "docker-ready") return "docker";
+  if (defaults?.profile === "local-only") return "local";
+  return TEMPLATE_DEFAULT_MODE[template];
+}
+
+/**
+ * Write project-local `.oke/mode` (same shape as `oke mode` / `oke dev`).
+ *
+ * @param targetDir - Scaffolded project root
+ * @param mode - Mode to save
+ */
+function writeProjectDevMode(targetDir: string, mode: "local" | "docker"): void {
+  mkdirSync(join(targetDir, ".oke"), { recursive: true });
+  writeFileSync(join(targetDir, ".oke", "mode"), `${mode}\n`, "utf8");
+}
+
 /**
  * Recursively copy template files, applying {@link shouldSkipTemplatePath}.
  *

package/src/templates.ts

@@ -1,25 +1,30 @@
 /**
- * Standard template resolution.
- *
- * The only starter lives in this package at `template/`.
+ * Starter template resolution — `templates/standard` · `templates/advanced`.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** The single supported starter template. */
-export const TEMPLATES = ["standard"] as const;
+/** Supported starter templates. */
+export const TEMPLATES = ["standard", "advanced"] as const;
 
 /** A known clean starter template. */
 export type TemplateId = (typeof TEMPLATES)[number];
 
-/** Default when `--template` is omitted (recommended project layout). */
+/** Default when `--template` is omitted. */
 export const DEFAULT_TEMPLATE: TemplateId = "standard";
 
 /** One-line purpose for the starter (interactive select + help). */
 export const TEMPLATE_PURPOSES: Readonly<Record<TemplateId, string>> = {
-  standard: "Full recommended file layout, empty scaffolding",
+  standard: "Notes app — local-first (sqlite · memory · console email)",
+  advanced: "Notes app — docker-ready (postgres · redis · s3 · openbao)",
+};
+
+/** Recommended `.oke/mode` when using recommended defaults (no customize). */
+export const TEMPLATE_DEFAULT_MODE: Readonly<Record<TemplateId, "local" | "docker">> = {
+  standard: "local",
+  advanced: "docker",
 };
 
 /**
@@ -43,7 +48,7 @@ export function packageRoot(): string {
  *
  * Order:
  * 1. `CREATE_OKE_TEMPLATE` env (absolute path to a template)
- * 2. Bundled `template/`
+ * 2. Bundled `templates/<id>/`
  *
  * @param template - Template id
  * @returns Absolute path to the template source tree
@@ -52,7 +57,7 @@ export function resolveTemplateDir(template: TemplateId): string {
   const envRoot = process.env["CREATE_OKE_TEMPLATE"];
   if (envRoot && existsSync(envRoot)) return resolve(envRoot);
   const pkg = packageRoot();
-  const bundled = resolve(pkg, "template");
+  const bundled = resolve(pkg, "templates", template);
   if (existsSync(bundled)) return bundled;
 
   throw new Error(`create-oke: template "${template}" not found at ${bundled}`);

package/src/transform.test.ts

@@ -0,0 +1,105 @@
+/**
+ * create-oke config transforms — images must stay role→image pins.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { toCreateDefaults } from "./create-defaults.ts";
+import { pinsDockerReady, pinsLocalOnly } from "./drivers-catalog.ts";
+import { resolveTemplateDir } from "./templates.ts";
+import { applyCreateAnswers, upsertAiDrivers } from "./transform.ts";
+import type { EnvDriverPins } from "./create-defaults.ts";
+
+function templateConfig(): string {
+  return readFileSync(join(resolveTemplateDir("standard"), "oke.config.ts"), "utf8");
+}
+
+function defaultsWithIndex(indexLocal: string, indexDocker: string) {
+  return toCreateDefaults({
+    template: "advanced",
+    profile: "docker-ready",
+    drivers: {
+      store: {
+        sql: pinsDockerReady("libsql", "postgres", "memory"),
+        kv: pinsLocalOnly("memory", "redis", "memory"),
+        files: pinsLocalOnly("fs", "s3", "memory"),
+        index: pinsDockerReady(indexLocal, indexDocker, "memory"),
+      },
+      signal: pinsLocalOnly("memory", "redis", "memory"),
+      clock: pinsLocalOnly("memory", "file", "frozen"),
+      vault: pinsLocalOnly("env", "openbao", "memory"),
+      channel: { email: pinsLocalOnly("console", "smtp", "console") },
+      ai: null,
+    },
+    ai: { enabled: false, provider: null, driver: null },
+  });
+}
+
+describe("applyCreateAnswers images", () => {
+  test("index: libsql does not poison images with driver pins", () => {
+    const next = applyCreateAnswers(templateConfig(), defaultsWithIndex("libsql", "libsql"));
+    expect(next).toContain('local: "libsql"');
+    expect(next).toMatch(/index:\s*\{\s*local: "libsql"/);
+    // Role pins only — never env-column keys or bare driver ids as images.
+    expect(next).not.toMatch(/images:\s*\{[^}]*\blocal:\s*"/s);
+    expect(next).not.toMatch(/images:\s*\{[^}]*\bdocker:\s*"/s);
+    expect(next).not.toMatch(/images:\s*\{[^}]*:\s*"libsql"/s);
+    expect(next).toContain('"store.sql": "postgres:18-alpine"');
+  });
+
+  test("index meilisearch pins store.index image without comment leakage", () => {
+    const next = applyCreateAnswers(
+      templateConfig(),
+      defaultsWithIndex("meilisearch", "meilisearch"),
+    );
+    expect(next).toContain('"store.index": "getmeili/meilisearch:v1.37"');
+    expect(next).not.toMatch(/images:\s*\{[^}]*\btest:\s*"memory"/s);
+  });
+});
+
+describe("upsertAiDrivers", () => {
+  const ollamaPins: EnvDriverPins = {
+    local: "ollama",
+    docker: "ollama",
+    test: "mock",
+    prod: "ollama",
+  };
+
+  test("inserts drivers.ai as sibling of channel (not inside email)", () => {
+    const next = upsertAiDrivers(templateConfig(), ollamaPins);
+    expect(next).toMatch(/^ {4}ai:\s*\{/m);
+    expect(next).toContain('local: "ollama"');
+    const channel = next.match(/^ {4}channel:\s*\{[\s\S]*?\n {4}\},?\n/m)?.[0] ?? "";
+    expect(channel).toContain("email:");
+    expect(channel).not.toContain("ai:");
+  });
+
+  test("applyCreateAnswers with ai pins keeps top-level drivers.ai", () => {
+    const next = applyCreateAnswers(
+      templateConfig(),
+      toCreateDefaults({
+        template: "advanced",
+        profile: "docker-ready",
+        drivers: {
+          store: {
+            sql: pinsDockerReady("libsql", "postgres", "memory"),
+            kv: pinsLocalOnly("memory", "redis", "memory"),
+            files: pinsLocalOnly("fs", "s3", "memory"),
+            index: null,
+          },
+          signal: pinsLocalOnly("memory", "redis", "memory"),
+          clock: pinsLocalOnly("memory", "file", "frozen"),
+          vault: pinsLocalOnly("env", "openbao", "memory"),
+          channel: { email: pinsLocalOnly("console", "smtp", "console") },
+          ai: ollamaPins,
+        },
+        ai: { enabled: true, provider: "ollama", driver: "ollama" },
+      }),
+    );
+    expect(next).toMatch(/^ {4}ai:\s*\{/m);
+    expect(next).toContain('ai: "ollama/ollama:latest"');
+    const channel = next.match(/^ {4}channel:\s*\{[\s\S]*?\n {4}\},?\n/m)?.[0] ?? "";
+    expect(channel).not.toContain("ai:");
+  });
+});

package/src/transform.ts

@@ -13,6 +13,8 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import type { CreateDefaults, EnvDriverPins } from "./create-defaults.ts";
+import { DEFAULT_IMAGES } from "./drivers-catalog.ts";
 import { packageRoot } from "./templates.ts";
 
 /** SQL store drivers selectable at scaffold time. */
@@ -148,6 +150,231 @@ export function transformConfigForSqlDriver(source: string, driver: SqlDriverId)
   );
 }
 
+/**
+ * Apply full customize answers to `oke.config.ts` source.
+ *
+ * Rewrites driver maps and syncs `images` keys for docker-backed roles.
+ *
+ * @param source - Config TypeScript source
+ * @param defaults - Customize / reuse payload
+ */
+export function applyCreateAnswers(source: string, defaults: CreateDefaults): string {
+  let next = source;
+  next = replaceEnvMap(next, "sql", defaults.drivers.store.sql, { nestedUnderStore: true });
+  next = replaceEnvMap(next, "kv", defaults.drivers.store.kv, { nestedUnderStore: true });
+  next = replaceEnvMap(next, "files", defaults.drivers.store.files, { nestedUnderStore: true });
+
+  if (defaults.drivers.store.index) {
+    next = upsertStoreIndex(next, defaults.drivers.store.index);
+  }
+
+  next = replaceEnvMap(next, "signal", defaults.drivers.signal, { nestedUnderStore: false });
+  next = replaceEnvMap(next, "clock", defaults.drivers.clock, { nestedUnderStore: false });
+  next = replaceEnvMap(next, "vault", defaults.drivers.vault, { nestedUnderStore: false });
+  next = replaceChannelEmail(next, defaults.drivers.channel.email);
+
+  if (defaults.drivers.ai) {
+    next = upsertAiDrivers(next, defaults.drivers.ai);
+  }
+
+  next = syncImages(next, defaults);
+  return next;
+}
+
+/**
+ * Replace a top-level or store-nested env map block by key name.
+ *
+ * @param source - Config source
+ * @param key - Map key (`sql`, `signal`, …)
+ * @param pins - New pins
+ * @param options - Nesting
+ */
+function replaceEnvMap(
+  source: string,
+  key: string,
+  pins: EnvDriverPins,
+  options: { readonly nestedUnderStore: boolean },
+): string {
+  const block = formatEnvMap(pins, options.nestedUnderStore ? 3 : 2);
+  // Match `key: { … }` at the driver indentation used in the template.
+  const re = new RegExp(`${key}:\\s*\\{[\\s\\S]*?\\n\\s*\\}`, "m");
+  if (!re.test(source)) {
+    throw new Error(`create-oke: oke.config.ts missing drivers.${key} block`);
+  }
+  return source.replace(re, `${key}: ${block}`);
+}
+
+/**
+ * Replace `channel.email` env map.
+ *
+ * @param source - Config source
+ * @param pins - Email pins
+ */
+function replaceChannelEmail(source: string, pins: EnvDriverPins): string {
+  const block = formatEnvMap(pins, 3);
+  const re = /email:\s*\{[\s\S]*?\n\s*\}/;
+  if (!re.test(source)) {
+    throw new Error("create-oke: oke.config.ts missing channel.email block");
+  }
+  return source.replace(re, `email: ${block}`);
+}
+
+/**
+ * Insert or replace `store.index` under `drivers.store`.
+ *
+ * Matches only a real `index:` key at store-facet indentation — never
+ * `index: { … }` inside comments (e.g. the images opt-in note).
+ *
+ * @param source - Config source
+ * @param pins - Index pins
+ */
+function upsertStoreIndex(source: string, pins: EnvDriverPins): string {
+  const block = formatEnvMap(pins, 3);
+  const indexRe = /^( {6})index:\s*\{[\s\S]*?\n\1\}/m;
+  if (indexRe.test(source)) {
+    return source.replace(indexRe, `$1index: ${block}`);
+  }
+  // Insert after files block inside store.
+  const filesRe = /(files:\s*\{[\s\S]*?\n\s*\},)/;
+  if (!filesRe.test(source)) {
+    throw new Error("create-oke: oke.config.ts missing store.files to insert index");
+  }
+  return source.replace(filesRe, `$1\n      index: ${block},`);
+}
+
+/**
+ * Insert or replace top-level `drivers.ai` (sibling of `channel`, never nested).
+ *
+ * Indentation-anchored: only matches `ai:` / `channel:` at the drivers-body
+ * indent (4 spaces). The old non-greedy `channel: { … },` regex closed on
+ * `email`'s `},` and nested `ai` inside `channel` — hero then showed `ai: —`.
+ *
+ * @param source - Config source
+ * @param pins - AI pins
+ */
+export function upsertAiDrivers(source: string, pins: EnvDriverPins): string {
+  const block = formatEnvMap(pins, 2);
+  const aiRe = /^( {4})ai:\s*\{[\s\S]*?\n\1\}/m;
+  if (aiRe.test(source)) {
+    return source.replace(aiRe, `$1ai: ${block}`);
+  }
+  const channelRe = /^( {4})channel:\s*\{[\s\S]*?\n\1\},?\n/m;
+  if (!channelRe.test(source)) {
+    throw new Error("create-oke: oke.config.ts missing channel block to insert ai");
+  }
+  return source.replace(channelRe, (match) => `${match}    ai: ${block},\n`);
+}
+
+/**
+ * Format an env driver map literal.
+ *
+ * @param pins - Pins
+ * @param indentLevel - Indent depth (2 spaces each)
+ */
+function formatEnvMap(pins: EnvDriverPins, indentLevel: number): string {
+  const pad = "  ".repeat(indentLevel);
+  const close = "  ".repeat(indentLevel - 1);
+  return `{
+${pad}local: "${pins.local}",
+${pad}docker: "${pins.docker}",
+${pad}test: "${pins.test}",
+${pad}prod: "${pins.prod}",
+${close}}`;
+}
+
+/** Env-column keys that must never appear under `images`. */
+const IMAGE_ENV_COLUMNS = new Set(["local", "docker", "test", "prod"]);
+
+/** Known compose role keys written into `images`. */
+const IMAGE_ROLE_KEY = /^(?:store\.(?:sql|kv|files|index)|channel\.email|vault|ai)$/;
+
+/**
+ * Keep `images` in sync with chosen docker drivers.
+ *
+ * Rebuilds from known roles only — never spreads poisoned env-column keys
+ * leaked from comments or driver maps.
+ *
+ * @param source - Config source
+ * @param defaults - Answers
+ */
+function syncImages(source: string, defaults: CreateDefaults): string {
+  const existing = extractImages(source);
+  const images: Record<string, string> = {};
+  const d = defaults.drivers;
+  const pin = (role: string, fallback: string): void => {
+    images[role] = existing[role] ?? fallback;
+  };
+
+  if (
+    d.store.sql.docker === "postgres" ||
+    d.store.sql.prod === "postgres" ||
+    d.store.sql.docker === "pgvector" ||
+    d.store.sql.prod === "pgvector"
+  ) {
+    pin("store.sql", DEFAULT_IMAGES["store.sql"]!);
+  }
+  if (d.store.kv.docker === "redis" || d.signal.docker === "redis") {
+    pin("store.kv", DEFAULT_IMAGES["store.kv"]!);
+  }
+  if (d.store.files.docker === "s3") {
+    pin("store.files", DEFAULT_IMAGES["store.files"]!);
+  }
+  if (d.channel.email.docker === "smtp") {
+    pin("channel.email", DEFAULT_IMAGES["channel.email"]!);
+  }
+  if (d.vault.docker === "openbao") {
+    pin("vault", DEFAULT_IMAGES.vault!);
+  }
+  if (d.store.index?.docker === "meilisearch") {
+    pin("store.index", DEFAULT_IMAGES["store.index"]!);
+  }
+  if (d.ai && (d.ai.docker === "ollama" || d.ai.local === "ollama")) {
+    pin("ai", DEFAULT_IMAGES.ai!);
+  }
+
+  return replaceImagesBlock(source, images);
+}
+
+/**
+ * Parse role→image pins from an `images` block.
+ *
+ * Skips `//` comment lines and rejects env-column keys (`local`/`docker`/…).
+ *
+ * @param source - Config source
+ */
+function extractImages(source: string): Record<string, string> {
+  const m = /images:\s*\{([\s\S]*?)\n\s*\},/.exec(source);
+  if (!m) return {};
+  const out: Record<string, string> = {};
+  for (const line of m[1]!.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("//")) continue;
+    const hit = /["']?([\w.]+)["']?\s*:\s*"([^"]+)"/.exec(trimmed);
+    if (!hit) continue;
+    const key = hit[1]!;
+    if (IMAGE_ENV_COLUMNS.has(key) || !IMAGE_ROLE_KEY.test(key)) continue;
+    out[key] = hit[2]!;
+  }
+  return out;
+}
+
+/**
+ * @param source - Config source
+ * @param images - Role → image
+ */
+function replaceImagesBlock(source: string, images: Record<string, string>): string {
+  const lines = Object.entries(images).map(([k, v]) => {
+    const key = k.includes(".") ? `"${k}"` : k;
+    return `    ${key}: "${v}",`;
+  });
+  const block = `images: {\n${lines.join("\n")}\n  }`;
+  const re = /images:\s*\{[\s\S]*?\n\s*\}/;
+  if (!re.test(source)) {
+    throw new Error("create-oke: oke.config.ts missing images block");
+  }
+  return source.replace(re, block);
+}
+
 /**
  * Sanitize a directory / package name for npm.
  *

package/src/wizard-select.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared Clack select helpers with optional ← Back.
+ */
+
+import { isCancel, select } from "@clack/prompts";
+
+/** Sentinel — go back one wizard step (shown as "← Back" in selects). */
+export const WIZARD_BACK = "__back__" as const;
+/** {@link WIZARD_BACK} type alias. */
+export type WizardBack = typeof WIZARD_BACK;
+
+/**
+ * Append "← Back" when allowed — pure helper for tests + {@link selectWithBack}.
+ *
+ * @param options - Choices
+ * @param allowBack - Whether to append Back
+ */
+export function withBackOption(
+  options: readonly { value: string; label: string; hint?: string }[],
+  allowBack: boolean,
+): readonly { value: string; label: string; hint?: string }[] {
+  if (!allowBack) return options;
+  return [...options, { value: WIZARD_BACK, label: "←  Back" }];
+}
+
+/**
+ * Select with an optional trailing "← Back" option.
+ *
+ * @param message - Prompt
+ * @param options - Choices (without back)
+ * @param initialValue - Initial selection
+ * @param opts - Whether Back is offered
+ */
+export async function selectWithBack(
+  message: string,
+  options: readonly { value: string; label: string; hint?: string }[],
+  initialValue: string,
+  opts: { readonly allowBack: boolean },
+): Promise<string | WizardBack | null> {
+  const list = [...withBackOption(options, opts.allowBack)];
+  const value = await select({
+    message,
+    options: list,
+    initialValue,
+  });
+  if (isCancel(value)) return null;
+  const picked = String(value);
+  if (picked === WIZARD_BACK) return WIZARD_BACK;
+  return picked;
+}

package/{template → templates/advanced}/.env.example

@@ -1,5 +1,4 @@
-# Environment template — copy to `.env.local` for local overrides.
-# create-oke copies this file to `.env.local` when you scaffold a new project.
+# Environment template — create-oke copies this to `.env.local` when you scaffold.
 #
 # Resolution order (first hit wins):
 #   process.env → .env.local → docker/.env.docker → vault driver → dev fallback
@@ -12,6 +11,13 @@
 # Uncomment to override compose credentials for a host-managed service.
 # Host ports under docker mode are unique per project — do not assume defaults.
 
+# ── App / Console ───────────────────────────────────────────
+# PORT=6530
+# OKE_APP_URL=http://127.0.0.1:6530
+# OKE_CONSOLE_SECRET=
+# MAINTENANCE_MODE=0
+# APP_WEBHOOK_SECRET=dev-webhook-secret-change-me
+
 # ── channel.email — Mailpit (SMTP + UI) ─────────────────────
 # OKE_CHANNEL_EMAIL_URL=smtp://127.0.0.1:1025
 # SMTP_URL=smtp://127.0.0.1:1025
@@ -25,6 +31,31 @@
 # MP_SMTP_AUTH_ACCEPT_ANY=1
 # MP_SMTP_AUTH_ALLOW_INSECURE=1
 
+# ── channel.email — HTTP providers ──────────────────────────
+# RESEND_API_KEY=
+# SNDR_API_KEY=
+# SNDR_BASE_URL=https://api.sndr.sh
+# SNDR_FROM=hello@your-verified-domain.com
+
+# ── channel.sms — Taqnyat / Msegat / Unifonic ───────────────
+# TAQNYAT_BEARER_TOKEN=
+# TAQNYAT_SENDER=
+# MSEGAT_USERNAME=
+# MSEGAT_API_KEY=
+# MSEGAT_SENDER=
+# UNIFONIC_APPSID=
+# UNIFONIC_SENDER=
+
+# ── channel.whatsapp / push ─────────────────────────────────
+# WHATSAPP_TOKEN=
+# WHATSAPP_PHONE_NUMBER_ID=
+# VAPID_PUBLIC_KEY=
+# VAPID_PRIVATE_KEY=
+# VAPID_SUBJECT=mailto:ops@example.com
+# FCM_PROJECT_ID=
+# FCM_CLIENT_EMAIL=
+# FCM_PRIVATE_KEY=
+
 # ── store.files — object storage (S3) ───────────────────────
 # OKE_STORE_FILES_URL=http://access-key:secret-key@127.0.0.1:9000/oke
 # S3_ACCESS_KEY_ID=access-key
@@ -54,3 +85,10 @@
 # Optional controls:
 # PGDATA=/var/lib/postgresql/data/pgdata
 # POSTGRES_INITDB_ARGS=--data-checksums
+
+# ── AI ──────────────────────────────────────────────────────
+# OKE_AI_DRIVER=ollama
+# OKE_AI_URL=http://127.0.0.1:11434
+# OKE_AI_MODEL=qwen3.5:9b
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=