create-oke 0.2.6 → 0.3.2

package/src/cli.ts

@@ -1,25 +1,14 @@
 /**
- * `create-oke` CLI — clean templates by default; teaching examples opt-in.
+ * `create-oke` CLI — one standard starter.
  *
  * ```bash
- * bunx create-oke@latest <name> [--template hello|minimal|standard|full]
- * bunx create-oke@latest <name> --from-example notes|linkly|provisions|skyport
+ * bunx create-oke@latest <name> [--template standard]
  * bunx create-oke@latest <name> --yes
  * bunx create-oke@latest   # interactive when stdin is a TTY
  * ```
  */
 
-import {
-  cancel,
-  confirm,
-  intro,
-  isCancel,
-  note,
-  outro,
-  select,
-  spinner,
-  text,
-} from "@clack/prompts";
+import { cancel, confirm, intro, isCancel, note, outro, spinner, text } from "@clack/prompts";
 import { basename, relative, resolve } from "node:path";
 import { existsSync, rmSync } from "node:fs";
 import { agentsMdContent } from "./agents-md.ts";
@@ -27,23 +16,23 @@ import { docsUrl } from "./docs-origin.ts";
 import { scaffold, type ScaffoldResult, type ScaffoldSource } from "./scaffold.ts";
 import {
   DEFAULT_TEMPLATE,
-  EXAMPLE_NEW_IDEAS,
-  EXAMPLES,
   TEMPLATE_PURPOSES,
   TEMPLATES,
-  isExampleId,
   isTemplateId,
-  type ExampleId,
   type TemplateId,
 } from "./templates.ts";
+import { DEFAULT_SQL_DRIVER, SQL_DRIVERS, isSqlDriverId, type SqlDriverId } from "./transform.ts";
 
 /** Parsed CLI arguments. */
 export type CliArgs = {
   readonly name: string | undefined;
   readonly template: TemplateId;
-  readonly fromExample: ExampleId | undefined;
   /** True when `--template` / `-t` was present on the argv. */
   readonly templateExplicit: boolean;
+  /** Store SQL driver (`sqlite` default). */
+  readonly sqlDriver: SqlDriverId;
+  /** True when `--sql` was present on the argv. */
+  readonly sqlDriverExplicit: boolean;
   readonly help: boolean;
   /** Skip all prompts; use defaults. */
   readonly yes: boolean;
@@ -57,27 +46,13 @@ export type CliArgs = {
   readonly targetDir: string | undefined;
 };
 
-/**
- * Sentinel choice for "Start from a worked example" in interactive answers.
- * Distinct from clack's internal select value (`__example__`).
- */
-export const FROM_EXAMPLE_CHOICE = "from-example" as const;
-
 /** Answers collected by the interactive ask step (no clack types). */
-export type InteractiveAnswers =
-  | {
-      readonly name: string;
-      readonly choice: TemplateId;
-      readonly installAndRun: boolean;
-      readonly agentsMd: boolean;
-    }
-  | {
-      readonly name: string;
-      readonly choice: typeof FROM_EXAMPLE_CHOICE;
-      readonly example: ExampleId;
-      readonly installAndRun: boolean;
-      readonly agentsMd: boolean;
-    };
+export type InteractiveAnswers = {
+  readonly name: string;
+  readonly choice: TemplateId;
+  readonly installAndRun: boolean;
+  readonly agentsMd: boolean;
+};
 
 /**
  * Canonical scaffold invocation — shared by interactive and flag-driven paths.
@@ -87,6 +62,7 @@ export type ScaffoldCallArgs = {
   readonly targetDir: string;
   readonly source: ScaffoldSource;
   readonly agentsMd: boolean;
+  readonly sqlDriver: SqlDriverId;
 };
 
 /**
@@ -97,8 +73,9 @@ export type ScaffoldCallArgs = {
 export function parseArgs(argv: readonly string[]): CliArgs {
   let name: string | undefined;
   let template: TemplateId = DEFAULT_TEMPLATE;
-  let fromExample: ExampleId | undefined;
   let templateExplicit = false;
+  let sqlDriver: SqlDriverId = DEFAULT_SQL_DRIVER;
+  let sqlDriverExplicit = false;
   let help = false;
   let yes = false;
   let install: boolean | undefined;
@@ -131,12 +108,28 @@ export function parseArgs(argv: readonly string[]): CliArgs {
       agentsMd = true;
       continue;
     }
+    if (a === "--sql") {
+      const next = argv[++i];
+      if (!next || !isSqlDriverId(next)) {
+        throw new Error(`create-oke: --sql must be one of ${SQL_DRIVERS.join("|")}`);
+      }
+      sqlDriver = next;
+      sqlDriverExplicit = true;
+      continue;
+    }
+    if (a.startsWith("--sql=")) {
+      const value = a.slice("--sql=".length);
+      if (!isSqlDriverId(value)) {
+        throw new Error(`create-oke: --sql must be one of ${SQL_DRIVERS.join("|")}`);
+      }
+      sqlDriver = value;
+      sqlDriverExplicit = true;
+      continue;
+    }
     if (a === "--template" || a === "-t") {
       const next = argv[++i];
       if (!next || !isTemplateId(next)) {
-        throw new Error(
-          `create-oke: --template must be one of ${TEMPLATES.join("|")}`,
-        );
+        throw new Error(`create-oke: --template must be one of ${TEMPLATES.join("|")}`);
       }
       template = next;
       templateExplicit = true;
@@ -145,34 +138,12 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     if (a.startsWith("--template=")) {
       const value = a.slice("--template=".length);
       if (!isTemplateId(value)) {
-        throw new Error(
-          `create-oke: --template must be one of ${TEMPLATES.join("|")}`,
-        );
+        throw new Error(`create-oke: --template must be one of ${TEMPLATES.join("|")}`);
       }
       template = value;
       templateExplicit = true;
       continue;
     }
-    if (a === "--from-example") {
-      const next = argv[++i];
-      if (!next || !isExampleId(next)) {
-        throw new Error(
-          `create-oke: --from-example must be one of ${EXAMPLES.join("|")}`,
-        );
-      }
-      fromExample = next;
-      continue;
-    }
-    if (a.startsWith("--from-example=")) {
-      const value = a.slice("--from-example=".length);
-      if (!isExampleId(value)) {
-        throw new Error(
-          `create-oke: --from-example must be one of ${EXAMPLES.join("|")}`,
-        );
-      }
-      fromExample = value;
-      continue;
-    }
     if (a.startsWith("-")) {
       throw new Error(`create-oke: unknown option ${a}`);
     }
@@ -183,12 +154,6 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     throw new Error(`create-oke: unexpected argument ${a}`);
   }
 
-  if (templateExplicit && fromExample !== undefined) {
-    throw new Error(
-      "create-oke: use either --template or --from-example, not both",
-    );
-  }
-
   if (argv.includes("--install") && argv.includes("--no-install")) {
     throw new Error("create-oke: use either --install or --no-install, not both");
   }
@@ -200,8 +165,9 @@ export function parseArgs(argv: readonly string[]): CliArgs {
   return {
     name,
     template,
-    fromExample,
     templateExplicit,
+    sqlDriver,
+    sqlDriverExplicit,
     help,
     yes,
     install,
@@ -248,21 +214,18 @@ export function helpText(): string {
     (id) =>
       `  ${id.padEnd(12)}${TEMPLATE_PURPOSES[id]}${id === DEFAULT_TEMPLATE ? "  (default)" : ""}`,
   ).join("\n");
-  const exampleLines = EXAMPLES.map(
-    (id) => `  ${id.padEnd(12)}${EXAMPLE_NEW_IDEAS[id]}`,
-  ).join("\n");
-
   return `create-oke — scaffold an okengine app
 
 Usage:
-  bunx create-oke@latest <name> [--template hello|minimal|standard|full]
-  bunx create-oke@latest <name> --from-example notes|linkly|provisions|skyport
+  bunx create-oke@latest <name> [--template standard]
   bunx create-oke@latest <name> --yes
   bunx create-oke@latest          # interactive (TTY only)
 
 Options:
   -t, --template <id>   Clean starter (default: ${DEFAULT_TEMPLATE})
-  --from-example <id>   Teaching example (non-interactive)
+  --sql <id>            Opt-in Store SQL dialect: ${SQL_DRIVERS.join("|")}
+                        Default keeps local sqlite · docker/prod postgres.
+                        --sql postgres pins store.sql local/docker/prod to postgres.
   -y, --yes             No prompts; defaults + bun install (no oke dev)
   --install             Run bun install after scaffold
   --no-install          Skip bun install
@@ -270,16 +233,11 @@ Options:
   --no-agents-md        Skip AGENTS.md
   -h, --help            Show this help
 
-Templates (clean starters from templates/):
+Template:
 ${templateLines}
 
---from-example (copies a teaching example, including its business logic and
-comments — most new projects want --template instead):
-${exampleLines}
-
 No telemetry. Bun only. On a TTY, a project name alone still opens the wizard
-(confirm name, template, install). Non-TTY / --yes / --template /
---from-example stay fully scriptable.
+(confirm name and install). Non-TTY / --yes / --template stay fully scriptable.
 `;
 }
 
@@ -287,20 +245,16 @@ No telemetry. Bun only. On a TTY, a project name alone still opens the wizard
  * Whether the CLI should open the interactive Clack flow.
  *
  * TTY humans get the wizard even when a name is pre-filled. Config flags
- * (`--template`, `--from-example`) or `--yes` skip prompts for CI/agents.
+ * `--template` or `--yes` skips prompts for CI/agents.
  *
  * @param args - Parsed args
  * @param stdinIsTTY - `process.stdin.isTTY`
  */
-export function shouldPrompt(
-  args: CliArgs,
-  stdinIsTTY: boolean | undefined,
-): boolean {
+export function shouldPrompt(args: CliArgs, stdinIsTTY: boolean | undefined): boolean {
   if (!stdinIsTTY) return false;
   if (args.help) return false;
   if (args.yes) return false;
   if (args.templateExplicit) return false;
-  if (args.fromExample !== undefined) return false;
   return true;
 }
 
@@ -310,9 +264,6 @@ export function shouldPrompt(
  * @param args - Parsed args
  */
 export function sourceFromArgs(args: CliArgs): ScaffoldSource {
-  if (args.fromExample !== undefined) {
-    return { kind: "example", id: args.fromExample };
-  }
   return { kind: "template", id: args.template };
 }
 
@@ -332,6 +283,7 @@ export function scaffoldArgsFromCli(args: CliArgs): ScaffoldCallArgs {
     targetDir: args.targetDir,
     source: sourceFromArgs(args),
     agentsMd: args.agentsMd,
+    sqlDriver: args.sqlDriver,
   };
 }
 
@@ -339,28 +291,21 @@ export function scaffoldArgsFromCli(args: CliArgs): ScaffoldCallArgs {
  * Pure map from interactive answers → scaffold call args.
  *
  * Independent of clack — unit-tested against {@link scaffoldArgsFromCli}
- * for every template and every `--from-example` choice.
+ * for the standard template.
  *
  * @param answers - Collected interactive answers
  */
-export function scaffoldArgsFromAnswers(
-  answers: InteractiveAnswers,
-): ScaffoldCallArgs {
+export function scaffoldArgsFromAnswers(answers: InteractiveAnswers): ScaffoldCallArgs {
   const targetDir = resolve(answers.name.trim());
   const name = basename(targetDir);
-  if (answers.choice === FROM_EXAMPLE_CHOICE) {
-    return {
-      name,
-      targetDir,
-      source: { kind: "example", id: answers.example },
-      agentsMd: answers.agentsMd,
-    };
-  }
+  // Interactive always keeps the dual-mode default (local sqlite ·
+  // docker/prod postgres). Opt into postgres-everywhere with `--sql postgres`.
   return {
     name,
     targetDir,
     source: { kind: "template", id: answers.choice },
     agentsMd: answers.agentsMd,
+    sqlDriver: DEFAULT_SQL_DRIVER,
   };
 }
 
@@ -371,9 +316,10 @@ export function scaffoldArgsFromAnswers(
  *
  * @param partial - Name already known (pre-filled in the prompt)
  */
-export type AskInteractiveFn = (
-  partial: { readonly name?: string; readonly agentsMd?: boolean },
-) => Promise<InteractiveAnswers | null>;
+export type AskInteractiveFn = (partial: {
+  readonly name?: string;
+  readonly agentsMd?: boolean;
+}) => Promise<InteractiveAnswers | null>;
 
 /**
  * Collect interactive answers via `@clack/prompts`.
@@ -396,52 +342,8 @@ export async function askInteractiveAnswers(
   if (isCancel(nameValue)) return null;
   const name = String(nameValue).trim();
 
-  const templateValue = await select({
-    message: "Template",
-    options: [
-      ...TEMPLATES.map((id) => ({
-        value: id as string,
-        label: id,
-        hint: TEMPLATE_PURPOSES[id],
-      })),
-      {
-        value: "__example__",
-        label: "Start from a worked example",
-        hint: "Teaching apps with business logic — most projects want a template",
-      },
-    ],
-    initialValue: DEFAULT_TEMPLATE,
-  });
-  if (isCancel(templateValue)) return null;
-
   const agentsMd = partial.agentsMd ?? true;
 
-  if (templateValue === "__example__") {
-    const exampleValue = await select({
-      message: "Example",
-      options: EXAMPLES.map((id) => ({
-        value: id,
-        label: id,
-        hint: EXAMPLE_NEW_IDEAS[id],
-      })),
-    });
-    if (isCancel(exampleValue)) return null;
-
-    const installAndRunValue = await confirm({
-      message: "Install dependencies and start oke dev?",
-      initialValue: true,
-    });
-    if (isCancel(installAndRunValue)) return null;
-
-    return {
-      name,
-      choice: FROM_EXAMPLE_CHOICE,
-      example: exampleValue as ExampleId,
-      installAndRun: Boolean(installAndRunValue),
-      agentsMd,
-    };
-  }
-
   const installAndRunValue = await confirm({
     message: "Install dependencies and start oke dev?",
     initialValue: true,
@@ -450,7 +352,7 @@ export async function askInteractiveAnswers(
 
   return {
     name,
-    choice: templateValue as TemplateId,
+    choice: DEFAULT_TEMPLATE,
     installAndRun: Boolean(installAndRunValue),
     agentsMd,
   };
@@ -503,9 +405,7 @@ export async function run(
 
   if (args.name === undefined) {
     console.log(helpText());
-    console.error(
-      "create-oke: missing <name>. Pass a name, or run in a TTY for the wizard.",
-    );
+    console.error("create-oke: missing <name>. Pass a name, or run in a TTY for the wizard.");
     console.error("  Example: bunx create-oke@latest my-app --yes");
     return 1;
   }
@@ -513,7 +413,7 @@ export async function run(
   if (args.yes) {
     const source = sourceFromArgs(args);
     console.log(
-      `Using defaults: ${source.kind}=${source.id} agents-md=${args.agentsMd} install=${shouldInstall(args)}`,
+      `Using defaults: ${source.kind}=${source.id} sql=${args.sqlDriver} agents-md=${args.agentsMd} install=${shouldInstall(args)}`,
     );
   }
 
@@ -573,6 +473,7 @@ async function runScaffold(
     targetDir,
     source,
     agentsMd,
+    sqlDriver,
     interactive,
     install,
     startDev,
@@ -605,6 +506,7 @@ async function runScaffold(
       name,
       source,
       writeAgentsMd: agentsMd,
+      sqlDriver,
     });
     if (spun) spun.stop("Scaffolded.");
 

package/src/docs-origin.ts

@@ -2,11 +2,10 @@
  * Canonical public docs origin for scaffolded AGENTS.md and next-steps.
  *
  * Keep in lockstep with `src/docs-origin.ts` in the okengine package.
- * Flip both when the custom domain is attached: `https://oke.omqkhafi.dev`.
  */
 
-/** Live docs site (Vercel). Planned cutover: `https://oke.omqkhafi.dev`. */
-export const DOCS_ORIGIN = "https://okengine.vercel.app" as const;
+/** Live docs site. */
+export const DOCS_ORIGIN = "https://oke.omqkhafi.dev" as const;
 
 /**
  * Absolute docs URL for a path under the handbook / site.

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,26 +13,21 @@ 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,
   sanitizeProjectName,
   shouldSkipTemplatePath,
+  transformConfigForSqlDriver,
   transformPackageJson,
   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 = {
@@ -40,10 +35,15 @@ 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 — pins `oke.config.ts` `store.sql` local/docker/prod
+   * when `postgres`. Default `sqlite` keeps the dual-mode config.
+   */
+  readonly sqlDriver?: SqlDriverId;
 };
 
 /** Result of a successful scaffold. */
@@ -54,39 +54,35 @@ export type ScaffoldResult = {
   /** Display label (`standard`, `notes`, …). */
   readonly label: string;
   readonly okengineDependency: string;
+  /** Store SQL driver applied to schema + config. */
+  readonly sqlDriver: SqlDriverId;
   /** Relative paths written (POSIX), sorted. */
   readonly files: readonly string[];
 };
 
 /**
- * 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;
 
   if (existsSync(targetDir)) {
     const entries = readdirSync(targetDir);
     if (entries.length > 0) {
-      throw new Error(
-        `create-oke: target directory is not empty: ${targetDir}`,
-      );
+      throw new Error(`create-oke: target directory is not empty: ${targetDir}`);
     }
   } else {
     mkdirSync(targetDir, { recursive: true });
   }
 
   try {
-    const okengineDependency = resolveOkengineDependency(
-      resolveLocalOkengineRoot(),
-    );
+    const okengineDependency = resolveOkengineDependency(resolveLocalOkengineRoot());
     const written: string[] = [];
 
     copyTree(sourceDir, targetDir, "", written);
@@ -95,18 +91,25 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
     if (!existsSync(pkgPath)) {
       throw new Error(`create-oke: source "${label}" has no package.json`);
     }
-    const sourcePkg = JSON.parse(
-      readFileSync(pkgPath, "utf8"),
-    ) as ScaffoldPackageJson;
+    const sourcePkg = JSON.parse(readFileSync(pkgPath, "utf8")) as ScaffoldPackageJson;
     const nextPkg = transformPackageJson(sourcePkg, name, okengineDependency);
     writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`, "utf8");
 
+    applySqlDriverTransforms(targetDir, sqlDriver);
+
     if (options.writeAgentsMd !== false) {
       const agentsPath = join(targetDir, "AGENTS.md");
       writeFileSync(agentsPath, agentsMdContent(name), "utf8");
       if (!written.includes("AGENTS.md")) written.push("AGENTS.md");
     }
 
+    const envExample = join(targetDir, ".env.example");
+    const envLocal = join(targetDir, ".env.local");
+    if (existsSync(envExample) && !existsSync(envLocal)) {
+      cpSync(envExample, envLocal);
+      if (!written.includes(".env.local")) written.push(".env.local");
+    }
+
     written.sort();
     return {
       targetDir,
@@ -114,6 +117,7 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
       source: options.source,
       label,
       okengineDependency,
+      sqlDriver,
       files: written,
     };
   } catch (e) {
@@ -122,6 +126,27 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
   }
 }
 
+/**
+ * For postgres, pin `store.sql` local/docker/prod in `oke.config.ts`.
+ *
+ * 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 {
+  if (sqlDriver !== "postgres") return;
+
+  const configPath = join(targetDir, "oke.config.ts");
+  if (existsSync(configPath)) {
+    const next = transformConfigForSqlDriver(readFileSync(configPath, "utf8"), sqlDriver);
+    writeFileSync(configPath, next, "utf8");
+  }
+}
+
 /**
  * Recursively copy template files, applying {@link shouldSkipTemplatePath}.
  *
@@ -130,12 +155,7 @@ export function scaffold(options: ScaffoldOptions): ScaffoldResult {
  * @param rel - Relative path under the roots
  * @param written - Accumulator for relative paths written
  */
-function copyTree(
-  srcRoot: string,
-  dstRoot: string,
-  rel: string,
-  written: string[],
-): void {
+function copyTree(srcRoot: string, dstRoot: string, rel: string, written: string[]): void {
   const src = rel ? join(srcRoot, rel) : srcRoot;
   const st = statSync(src);
   if (st.isDirectory()) {