create-oke 0.2.8 → 0.3.2

package/src/index.ts

@@ -5,8 +5,7 @@
  * ```bash
  * bunx create-oke@latest my-app
  * bunx create-oke@latest my-app --yes
- * bunx create-oke@latest my-app --template hello
- * bunx create-oke@latest my-app --from-example notes
+ * bunx create-oke@latest my-app --template standard
  * ```
  *
  * @module

package/src/scaffold.ts

@@ -13,13 +13,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import {
-  resolveExampleDir,
-  resolveLocalOkengineRoot,
-  resolveTemplateDir,
-  type ExampleId,
-  type TemplateId,
-} from "./templates.ts";
+import { resolveLocalOkengineRoot, resolveTemplateDir, type TemplateId } from "./templates.ts";
 import { agentsMdContent } from "./agents-md.ts";
 import {
   DEFAULT_SQL_DRIVER,
@@ -27,16 +21,13 @@ import {
   shouldSkipTemplatePath,
   transformConfigForSqlDriver,
   transformPackageJson,
-  transformSchemaForSqlDriver,
   resolveOkengineDependency,
   type ScaffoldPackageJson,
   type SqlDriverId,
 } from "./transform.ts";
 
-/** Where the scaffold copies from. */
-export type ScaffoldSource =
-  | { readonly kind: "template"; readonly id: TemplateId }
-  | { readonly kind: "example"; readonly id: ExampleId };
+/** The bundled starter copied by the scaffold. */
+export type ScaffoldSource = { readonly kind: "template"; readonly id: TemplateId };
 
 /** Options for {@link scaffold}. */
 export type ScaffoldOptions = {
@@ -44,14 +35,13 @@ export type ScaffoldOptions = {
   readonly targetDir: string;
   /** npm package / folder name. */
   readonly name: string;
-  /** Template or teaching-example source. */
+  /** Starter template source. */
   readonly source: ScaffoldSource;
   /** Write root `AGENTS.md` (default true). */
   readonly writeAgentsMd?: boolean;
   /**
-   * Store SQL driver — rewrites `src/schema.ts` dialect and pins
-   * `oke.config.ts` `store.sql` local/docker/prod when `postgres`.
-   * Default `sqlite`.
+   * Store SQL driver — pins `oke.config.ts` `store.sql` local/docker/prod
+   * when `postgres`. Default `sqlite` keeps the dual-mode config.
    */
   readonly sqlDriver?: SqlDriverId;
 };
@@ -71,17 +61,14 @@ export type ScaffoldResult = {
 };
 
 /**
- * Scaffold a new okengine project from a clean template or teaching example.
+ * Scaffold a new okengine project from the standard template.
  *
  * @param options - Name, source, destination
  */
 export function scaffold(options: ScaffoldOptions): ScaffoldResult {
   const name = sanitizeProjectName(options.name);
   const targetDir = resolve(options.targetDir);
-  const sourceDir =
-    options.source.kind === "template"
-      ? resolveTemplateDir(options.source.id)
-      : resolveExampleDir(options.source.id);
+  const sourceDir = resolveTemplateDir(options.source.id);
   const label = options.source.id;
   const sqlDriver = options.sqlDriver ?? DEFAULT_SQL_DRIVER;
 
@@ -140,22 +127,17 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
 }
 
 /**
- * Rewrite schema dialect + (for postgres) `store.sql` pins.
+ * For postgres, pin `store.sql` local/docker/prod in `oke.config.ts`.
  *
- * `sqlite` keeps the template dual-mode config (`local: sqlite` ·
- * `docker`/`prod: postgres`) — only the Drizzle dialect is ensured.
- * `postgres` writes `pgTable` and pins local/docker/prod to postgres.
+ * The default template ships abstract `src/schema.decl.ts` — dialect is
+ * emitted from the active `store.sql` driver, so there is no hand-written
+ * `sqliteTable`/`pgTable` source to rewrite. `sqlite` keeps the template
+ * dual-mode config (`local: sqlite` · `docker`/`prod: postgres`) untouched.
  *
  * @param targetDir - Scaffolded project root
  * @param sqlDriver - Chosen store.sql driver
  */
 function applySqlDriverTransforms(targetDir: string, sqlDriver: SqlDriverId): void {
-  const schemaPath = join(targetDir, "src/schema.ts");
-  if (existsSync(schemaPath)) {
-    const next = transformSchemaForSqlDriver(readFileSync(schemaPath, "utf8"), sqlDriver);
-    writeFileSync(schemaPath, next, "utf8");
-  }
-
   if (sqlDriver !== "postgres") return;
 
   const configPath = join(targetDir, "oke.config.ts");

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,32 +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.",
 };
 
 /**
@@ -56,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`).
  */
@@ -73,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:

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/{templates/standard → template}/README.md

@@ -8,10 +8,10 @@ business logic. Default `create-oke` template.
 ```bash
 bun install
 oke dev          # app :6530 · Console :6533 · MCP :6535
-# or: oke mode docker && oke dev   # postgres · redis · Mailpit · RustFS · sops
+# or: oke mode docker && oke dev   # postgres · redis · Mailpit · RustFS · OpenBao
 ```
 
-Local `oke dev` auto-runs `oke db push` when `schema.ts` changes (opt out:
+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                       |
@@ -29,7 +29,7 @@ standard/
 ├── oke.config.ts              # local: sqlite · docker/prod: postgres
 ├── src/
 │   ├── app.ts                 # adopt({ main }); wires stores + side modules
-│   ├── core.ts / schema.ts    # Store (replace the placeholder table)
+│   ├── core.ts / schema.decl.ts  # Store (replace the placeholder table)
 │   ├── gates.ts               # Gate stubs
 │   ├── vault.ts               # Vault stubs
 │   ├── channels.ts            # Channel stubs
@@ -45,20 +45,33 @@ standard/
 - **Unit:** `main`
 - **Flows to replace:** `root`, `health` — delete or rename once your domain exists
 
-Fill `schema.ts` (or `schema.decl.ts` + `oke db`), then add real flows under
-`src/flows/<unit>/`. Prefer this layout for new products; use `hello` / `minimal`
-only when you want less surface.
+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),
-vault `sops`/age. Compose credentials land in `docker/.env.docker`.
+and a real OpenBao vault (durable Raft storage, real init/unseal — not a
+`-dev` server). Compose credentials land in `docker/.env.docker`.
 
-| Surface        | URL                                              |
-| -------------- | ------------------------------------------------ |
-| Mailpit UI     | [http://127.0.0.1:8025](http://127.0.0.1:8025)   |
-| RustFS console | [http://127.0.0.1:9001](http://127.0.0.1:9001)   |
+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: [okengine.vercel.app/docs](https://okengine.vercel.app/docs)
+See [`AGENTS.md`](./AGENTS.md). Handbook: [oke.omqkhafi.dev/docs](https://oke.omqkhafi.dev/docs)