create-oke 0.2.6 → 0.3.2

package/src/templates.ts

@@ -1,17 +1,15 @@
 /**
- * Template / example ids and resolution.
+ * Standard template resolution.
  *
- * Clean starters live in repo-root `templates/<id>`.
- * Teaching apps live in repo-root `examples/<id>` (`--from-example`).
- * Published installs use the prepack copies under this package.
+ * The only starter lives in this package at `template/`.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** Clean starter template ids — match repo-root `templates/*`. */
-export const TEMPLATES = ["hello", "minimal", "standard", "full"] as const;
+/** The single supported starter template. */
+export const TEMPLATES = ["standard"] as const;
 
 /** A known clean starter template. */
 export type TemplateId = (typeof TEMPLATES)[number];
@@ -19,33 +17,9 @@ export type TemplateId = (typeof TEMPLATES)[number];
 /** Default when `--template` is omitted (recommended project layout). */
 export const DEFAULT_TEMPLATE: TemplateId = "standard";
 
-/** One-line purpose for each clean template (interactive select + help). */
+/** One-line purpose for the starter (interactive select + help). */
 export const TEMPLATE_PURPOSES: Readonly<Record<TemplateId, string>> = {
-  hello: 'Fastest possible "it works" — one flow, no Store',
-  minimal: "Smallest shape you'd actually ship — Store + 1–2 flows",
   standard: "Full recommended file layout, empty scaffolding",
-  full: "Every element present and wired, no business logic",
-};
-
-/** Teaching example ids — match `examples/*` and four-applications.md. */
-export const EXAMPLES = ["notes", "linkly", "provisions", "skyport"] as const;
-
-/** A known teaching example. */
-export type ExampleId = (typeof EXAMPLES)[number];
-
-/**
- * "New ideas" one-liners from four-applications.md — reused for
- * `--from-example` help and the interactive example select.
- */
-export const EXAMPLE_NEW_IDEAS: Readonly<Record<ExampleId, string>> = {
-  notes:
-    "`oke`, `on`, `flow`, `http`, `store.sql`, `fx`, typed errors, the typed client.",
-  linkly:
-    "`signal` and its three delivery physics · `clock` · `gate` · triggers beyond HTTP · transactional emit · cross-unit decoupling.",
-  provisions:
-    "`durable` flows and the journal · `vault` · `channel` with fallback chains and i18n · live queries · plugins · a CDC trigger · the three cache tiers.",
-  skyport:
-    "the `ai` element (models, prompts, RAG, agents) · multi-tenancy · SLOs and journeys · distributed topology · the three scaling axes.",
 };
 
 /**
@@ -57,15 +31,6 @@ export function isTemplateId(value: string): value is TemplateId {
   return (TEMPLATES as readonly string[]).includes(value);
 }
 
-/**
- * Whether `value` is a known {@link ExampleId}.
- *
- * @param value - Candidate string
- */
-export function isExampleId(value: string): value is ExampleId {
-  return (EXAMPLES as readonly string[]).includes(value);
-}
-
 /**
  * Directory that contains this package (`packages/create-oke`).
  */
@@ -74,67 +39,23 @@ export function packageRoot(): string {
 }
 
 /**
- * Resolve the directory to copy for a clean `--template`.
+ * Resolve the directory to copy for the starter.
  *
  * Order:
- * 1. `CREATE_OKE_TEMPLATES` env (absolute path to a `templates/` tree)
- * 2. Monorepo `templates/<template>` (two levels up from this package)
- * 3. Bundled `templates/<template>` (npm prepack copy)
+ * 1. `CREATE_OKE_TEMPLATE` env (absolute path to a template)
+ * 2. Bundled `template/`
  *
  * @param template - Template id
  * @returns Absolute path to the template source tree
  */
 export function resolveTemplateDir(template: TemplateId): string {
-  const envRoot = process.env["CREATE_OKE_TEMPLATES"];
-  if (envRoot) {
-    const fromEnv = resolve(envRoot, template);
-    if (existsSync(fromEnv)) return fromEnv;
-  }
-
+  const envRoot = process.env["CREATE_OKE_TEMPLATE"];
+  if (envRoot && existsSync(envRoot)) return resolve(envRoot);
   const pkg = packageRoot();
-  const monorepo = resolve(pkg, "../../templates", template);
-  if (existsSync(monorepo)) return monorepo;
-
-  const bundled = resolve(pkg, "templates", template);
-  if (existsSync(bundled)) return bundled;
-
-  throw new Error(
-    `create-oke: template "${template}" not found.\n` +
-      `  looked at: ${monorepo}\n` +
-      `             ${bundled}`,
-  );
-}
-
-/**
- * Resolve the directory to copy for `--from-example`.
- *
- * Order:
- * 1. `CREATE_OKE_EXAMPLES` env (absolute path to an `examples/` tree)
- * 2. Monorepo `examples/<example>` (two levels up from this package)
- * 3. Bundled `examples/<example>` (npm prepack copy)
- *
- * @param example - Example id
- * @returns Absolute path to the example source tree
- */
-export function resolveExampleDir(example: ExampleId): string {
-  const envRoot = process.env["CREATE_OKE_EXAMPLES"];
-  if (envRoot) {
-    const fromEnv = resolve(envRoot, example);
-    if (existsSync(fromEnv)) return fromEnv;
-  }
-
-  const pkg = packageRoot();
-  const monorepo = resolve(pkg, "../../examples", example);
-  if (existsSync(monorepo)) return monorepo;
-
-  const bundled = resolve(pkg, "examples", example);
+  const bundled = resolve(pkg, "template");
   if (existsSync(bundled)) return bundled;
 
-  throw new Error(
-    `create-oke: example "${example}" not found.\n` +
-      `  looked at: ${monorepo}\n` +
-      `             ${bundled}`,
-  );
+  throw new Error(`create-oke: template "${template}" not found at ${bundled}`);
 }
 
 /**

package/src/transform.ts

@@ -1,5 +1,5 @@
 /**
- * Rewrites applied when copying a `templates/<id>` or `examples/<id>` tree
+ * Rewrites applied when copying the bundled starter
  * into a new project.
  *
  * Exactly:
@@ -8,12 +8,31 @@
  *    (absolute `file:<okengine-root>` in the monorepo; registry version otherwise)
  * 3. Drop monorepo-only files that import paths outside the source tree
  *    (today: `tests/docker.test.ts`)
+ * 4. Optional `--sql` / wizard choice → Drizzle dialect + `store.sql` pins
  */
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { packageRoot } from "./templates.ts";
 
+/** SQL store drivers selectable at scaffold time. */
+export const SQL_DRIVERS = ["sqlite", "postgres"] as const;
+
+/** A known store.sql driver id for create-oke. */
+export type SqlDriverId = (typeof SQL_DRIVERS)[number];
+
+/** Default when `--sql` / wizard choice is omitted (matches template sources). */
+export const DEFAULT_SQL_DRIVER: SqlDriverId = "sqlite";
+
+/**
+ * Whether `value` is a known {@link SqlDriverId}.
+ *
+ * @param value - Candidate string
+ */
+export function isSqlDriverId(value: string): value is SqlDriverId {
+  return (SQL_DRIVERS as readonly string[]).includes(value);
+}
+
 /** Shape of an example / scaffolded `package.json`. */
 export type ScaffoldPackageJson = {
   name?: string;
@@ -33,9 +52,7 @@ export type ScaffoldPackageJson = {
  *
  * @param localOkengineRoot - Absolute path when available
  */
-export function resolveOkengineDependency(
-  localOkengineRoot: string | null,
-): string {
+export function resolveOkengineDependency(localOkengineRoot: string | null): string {
   if (localOkengineRoot) return `file:${localOkengineRoot}`;
   const pkgPath = join(packageRoot(), "package.json");
   const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { version: string };
@@ -94,6 +111,43 @@ export function shouldSkipTemplatePath(relativePath: string): boolean {
   return false;
 }
 
+/**
+ * Rewrite a Drizzle schema file to the dialect for `driver`.
+ *
+ * Templates ship as `sqliteTable` / `drizzle-orm/sqlite-core`. Choosing
+ * `postgres` swaps to `pgTable` / `pg-core` (and the reverse is idempotent).
+ *
+ * @param source - Schema TypeScript source
+ * @param driver - Target store.sql driver
+ */
+export function transformSchemaForSqlDriver(source: string, driver: SqlDriverId): string {
+  if (driver === "postgres") {
+    return source
+      .replaceAll("drizzle-orm/sqlite-core", "drizzle-orm/pg-core")
+      .replaceAll("sqliteTable", "pgTable");
+  }
+  return source
+    .replaceAll("drizzle-orm/pg-core", "drizzle-orm/sqlite-core")
+    .replaceAll("pgTable", "sqliteTable");
+}
+
+/**
+ * Pin `store.sql` `local` / `docker` / `prod` in `oke.config.ts` to `driver`.
+ *
+ * Leaves `test: "memory"` (and every other facet) untouched.
+ *
+ * @param source - Config TypeScript source
+ * @param driver - Target store.sql driver
+ */
+export function transformConfigForSqlDriver(source: string, driver: SqlDriverId): string {
+  return source.replace(/sql:\s*\{[\s\S]*?\n\s*\}/, (block) =>
+    block
+      .replace(/local:\s*"(?:sqlite|postgres)"/, `local: "${driver}"`)
+      .replace(/docker:\s*"(?:sqlite|postgres)"/, `docker: "${driver}"`)
+      .replace(/prod:\s*"(?:sqlite|postgres)"/, `prod: "${driver}"`),
+  );
+}
+
 /**
  * Sanitize a directory / package name for npm.
  *
@@ -106,13 +160,9 @@ export function sanitizeProjectName(raw: string): string {
   }
   // Allow scoped names; otherwise lowercase npm-safe slug.
   if (trimmed.startsWith("@")) {
-    const m = /^(@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*)$/.exec(
-      trimmed,
-    );
+    const m = /^(@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*)$/.exec(trimmed);
     if (!m) {
-      throw new Error(
-        `create-oke: invalid scoped package name "${trimmed}"`,
-      );
+      throw new Error(`create-oke: invalid scoped package name "${trimmed}"`);
     }
     return trimmed;
   }

package/template/.env.example

@@ -0,0 +1,56 @@
+# Environment template — copy to `.env.local` for local overrides.
+# create-oke copies this file to `.env.local` when you scaffold a new project.
+#
+# Resolution order (first hit wins):
+#   process.env → .env.local → docker/.env.docker → vault driver → dev fallback
+#
+# --- Vault (app secrets) ---
+# Declare secrets in src/vault.ts with `vault.secret(...)`, then uncomment lines here.
+#
+# --- Infrastructure ---
+# Same keys as `docker/.env.docker` after `oke dev --docker`.
+# Uncomment to override compose credentials for a host-managed service.
+# Host ports under docker mode are unique per project — do not assume defaults.
+
+# ── channel.email — Mailpit (SMTP + UI) ─────────────────────
+# OKE_CHANNEL_EMAIL_URL=smtp://127.0.0.1:1025
+# SMTP_URL=smtp://127.0.0.1:1025
+# SMTP_HOST=127.0.0.1
+# SMTP_PORT=1025
+# MAILPIT_UI_URL=http://127.0.0.1:8025
+# Optional controls:
+# SMTP_USER=
+# SMTP_PASSWORD=
+# MP_MAX_MESSAGES=500
+# MP_SMTP_AUTH_ACCEPT_ANY=1
+# MP_SMTP_AUTH_ALLOW_INSECURE=1
+
+# ── 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
+# S3_SECRET_ACCESS_KEY=secret-key
+# S3_BUCKET=oke
+# S3_URL=http://access-key:secret-key@127.0.0.1:9000/oke
+# S3_ENDPOINT=http://127.0.0.1:9000
+# S3_CONSOLE_URL=http://127.0.0.1:9001
+# S3_REGION=us-east-1
+# Optional controls:
+# S3_SESSION_TOKEN=
+
+# ── store.kv — Redis ────────────────────────────────────────
+# OKE_STORE_KV_PASSWORD=password
+# OKE_STORE_KV_URL=redis://:password@127.0.0.1:6379
+# REDIS_URL=redis://:password@127.0.0.1:6379
+# Optional controls:
+# OKE_STORE_KV_MAXMEMORY=256mb
+# OKE_STORE_KV_MAXMEMORY_POLICY=allkeys-lru
+
+# ── store.sql — Postgres ────────────────────────────────────
+# OKE_STORE_SQL_USER=oke
+# OKE_STORE_SQL_PASSWORD=password
+# OKE_STORE_SQL_DB=oke
+# OKE_STORE_SQL_URL=postgres://oke:password@127.0.0.1:5432/oke
+# DATABASE_URL=postgres://oke:password@127.0.0.1:5432/oke
+# Optional controls:
+# PGDATA=/var/lib/postgresql/data/pgdata
+# POSTGRES_INITDB_ARGS=--data-checksums

package/template/README.md

@@ -0,0 +1,77 @@
+# standard
+
+Full recommended file layout with **empty scaffolding** — structure without
+business logic. Default `create-oke` template.
+
+## Run
+
+```bash
+bun install
+oke dev          # app :6530 · Console :6533 · MCP :6535
+# or: oke mode docker && oke dev   # postgres · redis · Mailpit · RustFS · OpenBao
+```
+
+Local `oke dev` auto-runs `oke db push` when `schema.decl.ts` changes (opt out:
+`--no-db-push`). Docker/prod never auto-apply DDL — use `oke db migrate`.
+
+| Port    | Try                       |
+| ------- | ------------------------- |
+| `:6530` | `GET /` · `GET /health`   |
+| `:6533` | Console                   |
+| `:6535` | MCP                       |
+
+## What’s in this template
+
+```text
+standard/
+├── .env.example               # copied to .env.local by create-oke
+├── drizzle.config.ts          # oke db push|generate|migrate
+├── oke.config.ts              # local: sqlite · docker/prod: postgres
+├── src/
+│   ├── app.ts                 # adopt({ main }); wires stores + side modules
+│   ├── core.ts / schema.decl.ts  # Store (replace the placeholder table)
+│   ├── gates.ts               # Gate stubs
+│   ├── vault.ts               # Vault stubs
+│   ├── channels.ts            # Channel stubs
+│   ├── locales/en.ts · ar.ts  # i18n stubs
+│   └── flows/main/
+│       ├── index.ts           # GET / · GET /health
+│       ├── shapes.ts          # contracts live next to flows
+│       └── signals.ts         # Signal stubs
+└── tests/standard.test.ts
+```
+
+- **Elements stubbed:** Flow · Store · Signal · Gate · Vault · Channel (+ locales)
+- **Unit:** `main`
+- **Flows to replace:** `root`, `health` — delete or rename once your domain exists
+
+Fill `schema.decl.ts` (abstract tables → `oke db` emits `schema.generated.ts`
+for the active dialect), then add real flows under
+`src/flows/<unit>/`.
+
+## Docker mode (`oke dev --docker`)
+
+Closest to production protocols: Postgres, Redis, SMTP (Mailpit), S3 (RustFS),
+and a real OpenBao vault (durable Raft storage, real init/unseal — not a
+`-dev` server). Compose credentials land in `docker/.env.docker`.
+
+On first `oke dev --docker` / `oke docker --prod` bring-up, `oke` initializes
+OpenBao, unseals it, and mints a least-privilege token for the app. The root
+token and the single unseal key stay on the host under `.oke/openbao/`
+(`0600`, gitignored) — never in `docker/.env.docker`, never in YAML.
+
+> **Single point of failure by design:** back up `.oke/openbao/unseal.key` to
+> a separate safe location. Losing it means losing every secret permanently,
+> with no recovery.
+
+Host ports are unique per project so multiple apps can run at once. Use
+`oke stack` or the `oke dev` Docker summary for the Mailpit UI and RustFS
+console URLs — do not assume `:8025` / `:9001`.
+
+`docker/.env.docker` uses protocol-native keys (`DATABASE_URL`, `REDIS_URL`,
+`S3_*`, `SMTP_*`, `MAILPIT_UI_URL`) and includes commented optional controls.
+Supported controls you uncomment are preserved when the generated stack refreshes.
+
+## Agent contract
+
+See [`AGENTS.md`](./AGENTS.md). Handbook: [oke.omqkhafi.dev/docs](https://oke.omqkhafi.dev/docs)