create-oke 0.1.6 → 0.2.2

package/src/index.ts

@@ -4,7 +4,9 @@
  *
  * ```bash
  * bunx create-oke@latest my-app
- * bunx create-oke@latest my-app --template linkly
+ * bunx create-oke@latest my-app --yes
+ * bunx create-oke@latest my-app --template hello
+ * bunx create-oke@latest my-app --from-example notes
  * ```
  *
  * @module

package/src/scaffold.ts

@@ -1,5 +1,5 @@
 /**
- * Copy an `examples/<template>` tree and apply the package.json transform.
+ * Copy a template or example tree and apply the package.json transform.
  */
 
 import {
@@ -8,15 +8,19 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import {
+  resolveExampleDir,
   resolveLocalOkengineRoot,
   resolveTemplateDir,
+  type ExampleId,
   type TemplateId,
 } from "./templates.ts";
+import { agentsMdContent } from "./agents-md.ts";
 import {
   sanitizeProjectName,
   shouldSkipTemplatePath,
@@ -25,35 +29,48 @@ import {
   type ScaffoldPackageJson,
 } from "./transform.ts";
 
+/** Where the scaffold copies from. */
+export type ScaffoldSource =
+  | { readonly kind: "template"; readonly id: TemplateId }
+  | { readonly kind: "example"; readonly id: ExampleId };
+
 /** Options for {@link scaffold}. */
 export type ScaffoldOptions = {
   /** Destination directory (created). Absolute or cwd-relative. */
   readonly targetDir: string;
   /** npm package / folder name. */
   readonly name: string;
-  /** Template id (default: notes). */
-  readonly template: TemplateId;
+  /** Template or teaching-example source. */
+  readonly source: ScaffoldSource;
+  /** Write root `AGENTS.md` (default true). */
+  readonly writeAgentsMd?: boolean;
 };
 
 /** Result of a successful scaffold. */
 export type ScaffoldResult = {
   readonly targetDir: string;
   readonly name: string;
-  readonly template: TemplateId;
+  readonly source: ScaffoldSource;
+  /** Display label (`standard`, `notes`, …). */
+  readonly label: string;
   readonly okengineDependency: string;
   /** Relative paths written (POSIX), sorted. */
   readonly files: readonly string[];
 };
 
 /**
- * Scaffold a new okengine project from `examples/<template>`.
+ * Scaffold a new okengine project from a clean template or teaching example.
  *
- * @param options - Name, template, destination
+ * @param options - Name, source, destination
  */
 export function scaffold(options: ScaffoldOptions): ScaffoldResult {
   const name = sanitizeProjectName(options.name);
   const targetDir = resolve(options.targetDir);
-  const templateDir = resolveTemplateDir(options.template);
+  const sourceDir =
+    options.source.kind === "template"
+      ? resolveTemplateDir(options.source.id)
+      : resolveExampleDir(options.source.id);
+  const label = options.source.id;
 
   if (existsSync(targetDir)) {
     const entries = readdirSync(targetDir);
@@ -66,33 +83,43 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
     mkdirSync(targetDir, { recursive: true });
   }
 
-  const okengineDependency = resolveOkengineDependency(
-    resolveLocalOkengineRoot(),
-  );
-  const written: string[] = [];
+  try {
+    const okengineDependency = resolveOkengineDependency(
+      resolveLocalOkengineRoot(),
+    );
+    const written: string[] = [];
 
-  copyTree(templateDir, targetDir, "", written);
+    copyTree(sourceDir, targetDir, "", written);
 
-  const pkgPath = join(targetDir, "package.json");
-  if (!existsSync(pkgPath)) {
-    throw new Error(
-      `create-oke: template "${options.template}" has no package.json`,
-    );
-  }
-  const sourcePkg = JSON.parse(
-    readFileSync(pkgPath, "utf8"),
-  ) as ScaffoldPackageJson;
-  const nextPkg = transformPackageJson(sourcePkg, name, okengineDependency);
-  writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`, "utf8");
+    const pkgPath = join(targetDir, "package.json");
+    if (!existsSync(pkgPath)) {
+      throw new Error(`create-oke: source "${label}" has no package.json`);
+    }
+    const sourcePkg = JSON.parse(
+      readFileSync(pkgPath, "utf8"),
+    ) as ScaffoldPackageJson;
+    const nextPkg = transformPackageJson(sourcePkg, name, okengineDependency);
+    writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`, "utf8");
+
+    if (options.writeAgentsMd !== false) {
+      const agentsPath = join(targetDir, "AGENTS.md");
+      writeFileSync(agentsPath, agentsMdContent(name), "utf8");
+      if (!written.includes("AGENTS.md")) written.push("AGENTS.md");
+    }
 
-  written.sort();
-  return {
-    targetDir,
-    name,
-    template: options.template,
-    okengineDependency,
-    files: written,
-  };
+    written.sort();
+    return {
+      targetDir,
+      name,
+      source: options.source,
+      label,
+      okengineDependency,
+      files: written,
+    };
+  } catch (e) {
+    rmSync(targetDir, { recursive: true, force: true });
+    throw e;
+  }
 }
 
 /**
@@ -129,7 +156,7 @@ function copyTree(
 }
 
 /**
- * List relative file paths in an example tree using the same skip rules as scaffold.
+ * List relative file paths in a source tree using the same skip rules as scaffold.
  *
  * @param templateDir - Absolute template directory
  */

package/src/sync-templates.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * prepack: copy `examples/<template>` into `templates/<template>` so the
+ * prepack: copy repo-root `templates/` and `examples/` into this package so the
  * published npm package can scaffold without the monorepo checkout.
  *
  * Applies the same skip rules as runtime scaffold (no node_modules, no
@@ -16,30 +16,51 @@ import {
   statSync,
 } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { packageRoot, TEMPLATES } from "./templates.ts";
+import { EXAMPLES, packageRoot, TEMPLATES } from "./templates.ts";
 import { shouldSkipTemplatePath } from "./transform.ts";
 
 const pkg = packageRoot();
+const templatesRoot = resolve(pkg, "../../templates");
 const examplesRoot = resolve(pkg, "../../examples");
-const outRoot = join(pkg, "templates");
+const outTemplates = join(pkg, "templates");
+const outExamples = join(pkg, "examples");
 
+if (!existsSync(templatesRoot)) {
+  console.error(
+    `create-oke prepack: templates/ not found at ${templatesRoot}`,
+  );
+  process.exit(1);
+}
 if (!existsSync(examplesRoot)) {
   console.error(`create-oke prepack: examples/ not found at ${examplesRoot}`);
   process.exit(1);
 }
 
-rmSync(outRoot, { recursive: true, force: true });
-mkdirSync(outRoot, { recursive: true });
+rmSync(outTemplates, { recursive: true, force: true });
+rmSync(outExamples, { recursive: true, force: true });
+mkdirSync(outTemplates, { recursive: true });
+mkdirSync(outExamples, { recursive: true });
 
 for (const id of TEMPLATES) {
+  const src = join(templatesRoot, id);
+  const dst = join(outTemplates, id);
+  if (!existsSync(src)) {
+    console.error(`create-oke prepack: missing template ${src}`);
+    process.exit(1);
+  }
+  copyFiltered(src, dst, src);
+  console.log(`create-oke prepack: template ${id}`);
+}
+
+for (const id of EXAMPLES) {
   const src = join(examplesRoot, id);
-  const dst = join(outRoot, id);
+  const dst = join(outExamples, id);
   if (!existsSync(src)) {
     console.error(`create-oke prepack: missing example ${src}`);
     process.exit(1);
   }
   copyFiltered(src, dst, src);
-  console.log(`create-oke prepack: ${id}`);
+  console.log(`create-oke prepack: example ${id}`);
 }
 
 /**

package/src/templates.ts

@@ -1,20 +1,52 @@
 /**
- * Template ids and resolution — always sourced from `examples/<id>`,
- * with a published-package fallback at `templates/<id>` (filled by prepack).
+ * Template / example ids and 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.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** Canonical template ids — match `examples/*` and four-applications.md. */
-export const TEMPLATES = ["notes", "linkly", "provisions", "skyport"] as const;
+/** Clean starter template ids — match repo-root `templates/*`. */
+export const TEMPLATES = ["hello", "minimal", "standard", "full"] as const;
 
-/** A known scaffold template. */
+/** A known clean starter template. */
 export type TemplateId = (typeof TEMPLATES)[number];
 
-/** Default when `--template` is omitted (smallest quickstart). */
-export const DEFAULT_TEMPLATE: TemplateId = "notes";
+/** Default when `--template` is omitted (recommended project layout). */
+export const DEFAULT_TEMPLATE: TemplateId = "standard";
+
+/** One-line purpose for each clean template (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.",
+};
 
 /**
  * Whether `value` is a known {@link TemplateId}.
@@ -25,6 +57,15 @@ 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`).
  */
@@ -33,25 +74,25 @@ export function packageRoot(): string {
 }
 
 /**
- * Resolve the directory to copy for `template`.
+ * Resolve the directory to copy for a clean `--template`.
  *
  * Order:
- * 1. `CREATE_OKE_EXAMPLES` env (absolute path to an `examples/` tree)
- * 2. Monorepo `examples/<template>` (two levels up from this package)
+ * 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)
  *
  * @param template - Template id
  * @returns Absolute path to the template source tree
  */
 export function resolveTemplateDir(template: TemplateId): string {
-  const envRoot = process.env["CREATE_OKE_EXAMPLES"];
+  const envRoot = process.env["CREATE_OKE_TEMPLATES"];
   if (envRoot) {
     const fromEnv = resolve(envRoot, template);
     if (existsSync(fromEnv)) return fromEnv;
   }
 
   const pkg = packageRoot();
-  const monorepo = resolve(pkg, "../../examples", template);
+  const monorepo = resolve(pkg, "../../templates", template);
   if (existsSync(monorepo)) return monorepo;
 
   const bundled = resolve(pkg, "templates", template);
@@ -64,6 +105,38 @@ export function resolveTemplateDir(template: TemplateId): string {
   );
 }
 
+/**
+ * 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);
+  if (existsSync(bundled)) return bundled;
+
+  throw new Error(
+    `create-oke: example "${example}" not found.\n` +
+      `  looked at: ${monorepo}\n` +
+      `             ${bundled}`,
+  );
+}
+
 /**
  * Absolute path to the okengine package root when running inside this monorepo.
  *

package/src/transform.ts

@@ -1,11 +1,12 @@
 /**
- * Rewrites applied when copying an `examples/<template>` tree into a new project.
+ * Rewrites applied when copying a `templates/<id>` or `examples/<id>` tree
+ * into a new project.
  *
  * Exactly:
  * 1. `package.json` `"name"` → the user-provided project name
  * 2. `package.json` `"okengine": "file:../.."` → an installable reference
  *    (absolute `file:<okengine-root>` in the monorepo; registry version otherwise)
- * 3. Drop monorepo-only files that import paths outside the example tree
+ * 3. Drop monorepo-only files that import paths outside the source tree
  *    (today: `tests/docker.test.ts`)
  */
 
@@ -61,6 +62,8 @@ export function transformPackageJson(
   return {
     ...source,
     name: projectName,
+    // Starter apps always begin at 0.0.1 — never the framework lockstep version.
+    version: "0.0.1",
     dependencies,
   };
 }

package/templates/full/README.md

@@ -0,0 +1,49 @@
+# full
+
+**Every element present and wired** — no business logic. Use when you want the
+complete surface ready to fill in.
+
+## Run
+
+```bash
+bun install
+oke dev          # app :6530 · Console :6533 · MCP :6535
+```
+
+| Port | Try |
+|---|---|
+| `:6530` | `GET /` · `GET /health` |
+| `:6533` | Console |
+| `:6535` | MCP |
+
+## What’s in this template
+
+```text
+full/
+├── oke.config.ts
+├── src/
+│   ├── app.ts                 # gates, secrets, signals, stores, channel, ai
+│   ├── core.ts / schema.ts    # Store
+│   ├── gates.ts               # open gate (used on HTTP)
+│   ├── vault.ts               # appSecret
+│   ├── channels.ts            # welcome template
+│   ├── ai.ts                  # stub model + echo prompt
+│   ├── locales/en.ts · ar.ts
+│   └── flows/main/
+│       ├── index.ts           # GET / · GET /health · every("1d")
+│       ├── shapes.ts
+│       └── signals.ts         # pinged
+└── tests/full.test.ts
+```
+
+- **Elements wired:** Flow · Store · Signal · Clock (`every`) · Gate · Vault · Channel · AI
+- **Unit:** `main`
+- **App `$options`:** `gates`, `secrets`, `signals`, `stores`, `channel`, `ai`
+- **Flows:** `root`, `health` (emits `pinged`), plus a trivial daily cron
+
+Replace stubs with real models, prompts, channels, and domain flows. Prefer
+`standard` if you do not need AI / clock / vault on day one.
+
+## Agent contract
+
+See [`AGENTS.md`](./AGENTS.md). Handbook: [okengine.vercel.app/docs](https://okengine.vercel.app/docs)

package/templates/full/oke.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    store: {
+      sql: { dev: "sqlite", test: "memory", prod: "postgres" },
+      kv: { dev: "memory", test: "memory", prod: "redis" },
+    },
+    signal: { dev: "memory", test: "memory", prod: "postgres" },
+    clock: { dev: "memory", test: "frozen", prod: "postgres" },
+    vault: { dev: "dotenv", test: "memory", prod: "sops" },
+    channel: {
+      email: { dev: "console", test: "console", prod: "smtp" },
+      sms: { dev: "console", test: "console", prod: "unifonic" },
+      whatsapp: { dev: "console", test: "console", prod: "wa-cloud" },
+    },
+    ai: {
+      dev: "mock",
+      test: "mock",
+    },
+  },
+  i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
+});

package/templates/full/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@oke/template-full",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "okengine": "file:../..",
+    "drizzle-orm": "^1.0.0-rc.4",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "test": "bun test",
+    "dev": "oke dev"
+  }
+}

package/templates/full/src/ai.ts

@@ -0,0 +1,11 @@
+import { ai } from "okengine";
+import { z } from "zod";
+
+export const stub = ai.model("stub", { provider: "anthropic", tier: "haiku" });
+
+/** Stub prompt — replace with real versioned prompts. */
+export const echo = stub.prompt("echo", {
+  in: z.object({ text: z.string() }),
+  out: z.object({ text: z.string() }),
+  version: 1,
+});

package/templates/full/src/app.ts

@@ -0,0 +1,34 @@
+import { db } from "./core";
+import { open } from "./gates";
+import { appSecret } from "./vault";
+import { welcome } from "./channels";
+import { stub, echo } from "./ai";
+import { pinged } from "./flows/main/signals";
+import "./channels";
+import "./gates";
+import "./ai";
+import "./locales/en";
+import "./locales/ar";
+
+import { oke } from "okengine";
+import * as main from "./flows/main";
+
+export const app = oke({ name: "full" }).adopt({ main });
+
+export type App = typeof app;
+
+Object.assign(app.$options, {
+  env: "test",
+  gates: [open],
+  secrets: [appSecret],
+  signals: [pinged],
+  stores: [db],
+  channel: {
+    templates: [welcome],
+    defaultLocale: "en",
+  },
+  ai: {
+    models: [stub],
+    prompts: [echo],
+  },
+});

package/templates/full/src/channels.ts

@@ -0,0 +1,9 @@
+import { channel } from "okengine";
+import { z } from "zod";
+
+export const mail = channel.email({ from: "App <no-reply@example.com>" });
+
+/** Stub channel template — replace with real copy. */
+export const welcome = mail.template("welcome", {
+  schema: z.object({ name: z.string() }),
+});

package/templates/full/src/core.ts

@@ -0,0 +1,4 @@
+import { store } from "okengine";
+import * as schema from "./schema";
+
+export const db = store.sql("app", { schema });

package/templates/full/src/flows/main/index.ts

@@ -0,0 +1,45 @@
+import { on, flow, http, every } from "okengine";
+import { z } from "zod";
+import { open } from "../../gates";
+import { Health } from "./shapes";
+import { pinged } from "./signals";
+
+/** First-run welcome — visit :6530/ after `oke dev`. */
+export const root = on(
+  http.get("/").gate(open),
+  flow({
+    out: z.object({
+      ok: z.literal(true),
+      console: z.string(),
+      try: z.string(),
+    }),
+    do: () => ({
+      ok: true as const,
+      console: "http://127.0.0.1:6533",
+      try: "/health",
+    }),
+  }),
+);
+
+export const health = on(
+  http.get("/health").gate(open),
+  flow({
+    out: Health,
+    do: async (_input, fx) => {
+      await fx.emit(pinged, { at: Date.now() });
+      return { ok: true as const };
+    },
+  }),
+);
+
+on(pinged, flow({
+  do: async () => {},
+}));
+
+/** Trivial cron — replace with real schedules. */
+on(
+  every("1d"),
+  flow({
+    do: async () => {},
+  }),
+);

package/templates/full/src/flows/main/shapes.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+
+export const Health = z.object({ ok: z.literal(true) });

package/templates/full/src/flows/main/signals.ts

@@ -0,0 +1,8 @@
+import { signal } from "okengine";
+import { z } from "zod";
+
+/** Trivial signal — replace with real events. */
+export const pinged = signal("pinged", {
+  schema: z.object({ at: z.number() }),
+  delivery: "once",
+});

package/templates/full/src/gates.ts

@@ -0,0 +1,4 @@
+import { gate } from "okengine";
+
+/** Trivial shared gate — replace with real policies. */
+export const open = gate.policy("open", () => true);

package/templates/full/src/locales/ar.ts

@@ -0,0 +1,3 @@
+export default {
+  "welcome.subject": "أهلاً",
+};

package/templates/full/src/locales/en.ts

@@ -0,0 +1,3 @@
+export default {
+  "welcome.subject": "Welcome",
+};

package/templates/full/src/schema.ts

@@ -0,0 +1,8 @@
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { id, now } from "okengine/store";
+
+export const entries = sqliteTable("entries", {
+  id: text("id").primaryKey().$defaultFn(id),
+  body: text("body").notNull(),
+  createdAt: integer("created_at").notNull().$defaultFn(now),
+});

package/templates/full/src/vault.ts

@@ -0,0 +1,9 @@
+import { vault } from "okengine";
+import { z } from "zod";
+
+/** Stub secret contract — replace with your secrets. */
+export const appSecret = vault.secret("APP_SECRET", {
+  schema: z.string().min(1),
+  description: "Application secret",
+  dev: "dev-only-secret",
+});

package/templates/full/tests/full.test.ts

@@ -0,0 +1,11 @@
+import { test, expect } from "bun:test";
+import { createTestApp } from "okengine/test";
+import { app } from "../src/app";
+
+test("boots — health flow with wired elements", async () => {
+  const t = await createTestApp(app);
+  const { data, error } = await t.api.main.health({});
+  expect(error).toBeNull();
+  expect(data).toEqual({ ok: true });
+  await t.signals.drain();
+});