create-oke 0.1.6 → 0.2.2

package/README.md

@@ -8,21 +8,41 @@ cd my-app
 oke dev
 ```
 
+On a TTY, create-oke opens a Clack wizard: confirm name, pick a template, and
+optionally install + start `oke dev`. Pass `--yes` or `--template` /
+`--from-example` for non-interactive (CI / agents).
+
 | Port | What |
 |---|---|
 | `:6530` | your app |
 | `:6533` | Console |
 | `:6535` | MCP |
 
-Default template is **Notes** (same tree as [`examples/notes`](https://github.com/omqkhafi/okengine/tree/main/examples/notes)). Pick another with `--template`:
+Default template is **standard** (full recommended file layout, empty scaffolding).
+Pick another with `--template`, or start from a teaching example with `--from-example`:
 
 ```bash
-bunx create-oke@latest my-links --template linkly
-bunx create-oke@latest my-shop --template provisions
-bunx create-oke@latest my-sky --template skyport
+bunx create-oke@latest my-app --template hello
+bunx create-oke@latest my-app --template minimal
+bunx create-oke@latest my-app --template full
+bunx create-oke@latest my-app --yes
+bunx create-oke@latest my-notes --from-example notes
 ```
 
-| Template | Adds |
+| Template | Purpose |
+|---|---|
+| `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 (default) |
+| `full` | Every element present and wired, no business logic |
+
+Every scaffold writes an `AGENTS.md` so coding agents know the OKE contract
+(`--no-agents-md` to skip).
+
+`--from-example` copies a teaching example (including its business logic and
+comments) — most new projects want `--template` instead.
+
+| Example | Adds |
 |---|---|
 | `notes` | `oke` · `flow` · `http` · `store.sql` · typed client |
 | `linkly` | `signal` · `clock` · `gate` |
@@ -36,4 +56,4 @@ bunx create-oke@latest my-sky --template skyport
 | npm (CLI) | [`create-oke`](https://www.npmjs.com/package/create-oke) — use this with `bunx` |
 | JSR | [`@omqkhafi/create-oke`](https://jsr.io/@omqkhafi/create-oke) — same sources; prefer npm for the binary |
 
-Requires **Bun ≥ 1.3**. Framework docs: [okengine README](https://github.com/omqkhafi/okengine#readme) · [unified theory](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).
+Requires **Bun ≥ 1.3**. Docs: [okengine.vercel.app](https://okengine.vercel.app) · [handbook](https://okengine.vercel.app/docs) · [unified theory](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).

package/{templates → examples}/linkly/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/example-linkly",
-  "version": "0.1.6",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/{templates → examples}/notes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/example-notes",
-  "version": "0.1.6",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/{templates → examples}/provisions/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/example-provisions",
-  "version": "0.1.6",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/{templates → examples}/skyport/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oke/example-skyport",
-  "version": "0.1.6",
+  "version": "0.0.1",
   "private": true,
   "type": "module",
   "dependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-oke",
-  "version": "0.1.6",
+  "version": "0.2.2",
   "description": "Scaffold an okengine app — bunx create-oke@latest <name>",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
   },
   "files": [
     "src",
-    "templates"
+    "templates",
+    "examples"
   ],
   "scripts": {
     "prepack": "bun ./src/sync-templates.ts",
@@ -29,6 +30,9 @@
   "engines": {
     "bun": ">=1.3"
   },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
+  },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^7.0.2"

package/src/agents-md.ts

@@ -0,0 +1,99 @@
+/**
+ * Slim `AGENTS.md` written into every scaffolded app for coding agents.
+ */
+
+import { docsUrl } from "./docs-origin.ts";
+
+/**
+ * Render the app-facing agent contract for a new project.
+ *
+ * @param projectName - Sanitized package / folder name
+ */
+export function agentsMdContent(projectName: string): string {
+  const handbook = docsUrl("/docs");
+  return `# ${projectName} — OKE Agent Contract
+
+This file is for coding agents (Cursor, Claude Code, Codex, …). Read it before
+changing backend code. Handbook: ${handbook}
+
+**If the docs are silent, stop and ask.**
+
+## The one law
+
+Every backend behavior is a Flow:
+
+\`\`\`text
+on(Trigger) → Effects
+\`\`\`
+
+There are no separate species called endpoints, handlers, consumers, jobs,
+subscribers, or workflows. There is one species — the **Flow** — and triggers
+are typed values.
+
+## The eight elements
+
+| Element | Essence |
+|---|---|
+| **Flow** | behavior |
+| **Signal** | data in motion |
+| **Store** | data at rest (\`sql\` · \`kv\` · \`files\` · \`index\`) |
+| **Clock** | time |
+| **Gate** | permission to act |
+| **Vault** | protected knowledge |
+| **Channel** | reaching humans |
+| **AI** | reaching machine intelligence |
+
+An element earns its place only if it has irreducible physics. New
+infrastructure becomes a new **driver** for an existing element — never a
+ninth element.
+
+## The ten exports
+
+\`\`\`typescript
+import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
+\`\`\`
+
+That is the entire public vocabulary. Everything else is derived.
+
+## The fx rule
+
+**All world access goes through \`fx\`. No exceptions.**
+
+A direct \`node:\` import (or any other side-channel I/O) in element or flow
+code is a **defect**. \`fx\` is the single door to the outside world; effects
+are inferred from what a Flow touches through it.
+
+## Ports
+
+| Port | Surface |
+|---|---|
+| **6530** | App |
+| **6533** | Console |
+| **6535** | MCP |
+
+Mnemonic: O·K·E = 6·5·3.
+
+## How to run
+
+\`\`\`bash
+bun install
+oke dev          # or: bun run dev
+\`\`\`
+
+App \`:6530\` · Console \`:6533\` · MCP \`:6535\`.
+
+## Common mistakes
+
+- ❌ I/O outside \`fx\` (raw \`fetch\`, \`node:fs\`, vendor SDKs in flow bodies)
+- ✅ \`fx.store\` / \`fx.emit\` / \`fx.ask\` / channel sends through \`fx\`
+- ❌ Inventing a ninth “element” or a parallel handler stack beside Flows
+- ✅ New capability = new **driver** on an existing element, or a new Flow
+- ❌ Untyped HTTP handlers that skip \`on\` / \`flow\` / contracts
+- ✅ \`on(http.get("/…"), flow({ in, out, do }))\`
+
+## Learn more
+
+- Handbook: ${handbook}
+- Get started: ${docsUrl("/docs/get-started/introduction")}
+`;
+}

package/src/cli.test.ts

@@ -1,14 +1,38 @@
 /**
- * Unit tests for create-oke argument parsing and transforms.
+ * Unit tests for create-oke argument parsing, transforms, and non-TTY behavior.
  */
 
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { formatCdPath, parseArgs } from "./cli.ts";
+import {
+  FROM_EXAMPLE_CHOICE,
+  formatCdPath,
+  nextStepsText,
+  parseArgs,
+  run,
+  scaffoldArgsFromAnswers,
+  scaffoldArgsFromCli,
+  shouldPrompt,
+  sourceFromArgs,
+  type InteractiveAnswers,
+} from "./cli.ts";
 import { listTemplateFiles, scaffold } from "./scaffold.ts";
-import { resolveTemplateDir, TEMPLATES } from "./templates.ts";
+import {
+  DEFAULT_TEMPLATE,
+  EXAMPLES,
+  TEMPLATES,
+  packageRoot,
+  resolveExampleDir,
+  resolveTemplateDir,
+} from "./templates.ts";
 import {
   sanitizeProjectName,
   shouldSkipTemplatePath,
@@ -16,22 +40,130 @@ import {
 } from "./transform.ts";
 
 describe("parseArgs", () => {
-  test("defaults template to notes", () => {
+  test("defaults template to standard", () => {
     const a = parseArgs(["my-app"]);
     expect(a.name).toBe("my-app");
-    expect(a.template).toBe("notes");
+    expect(a.template).toBe("standard");
+    expect(a.templateExplicit).toBe(false);
+    expect(a.fromExample).toBeUndefined();
   });
 
   test("accepts --template and -t", () => {
-    expect(parseArgs(["x", "--template", "linkly"]).template).toBe("linkly");
-    expect(parseArgs(["x", "-t", "skyport"]).template).toBe("skyport");
-    expect(parseArgs(["x", "--template=provisions"]).template).toBe(
-      "provisions",
+    expect(parseArgs(["x", "--template", "hello"]).template).toBe("hello");
+    expect(parseArgs(["x", "-t", "full"]).template).toBe("full");
+    expect(parseArgs(["x", "--template=minimal"]).template).toBe("minimal");
+    expect(parseArgs(["x", "--template", "hello"]).templateExplicit).toBe(true);
+  });
+
+  test("accepts --from-example", () => {
+    expect(parseArgs(["x", "--from-example", "notes"]).fromExample).toBe(
+      "notes",
+    );
+    expect(parseArgs(["x", "--from-example=skyport"]).fromExample).toBe(
+      "skyport",
     );
   });
 
-  test("rejects unknown template", () => {
+  test("rejects unknown template / example / both", () => {
     expect(() => parseArgs(["x", "--template", "nope"])).toThrow(/template/);
+    expect(() => parseArgs(["x", "--from-example", "nope"])).toThrow(/example/);
+    expect(() =>
+      parseArgs(["x", "--template", "hello", "--from-example", "notes"]),
+    ).toThrow(/either/);
+  });
+});
+
+describe("shouldPrompt", () => {
+  test("TTY + no args → interactive", () => {
+    expect(shouldPrompt(parseArgs([]), true)).toBe(true);
+  });
+
+  test("TTY + name alone → still interactive (confirm name / template)", () => {
+    expect(shouldPrompt(parseArgs(["my-app"]), true)).toBe(true);
+  });
+
+  test("non-TTY, --yes, or config flags → no prompts", () => {
+    expect(shouldPrompt(parseArgs([]), false)).toBe(false);
+    expect(shouldPrompt(parseArgs(["my-app"]), false)).toBe(false);
+    expect(shouldPrompt(parseArgs(["my-app", "--yes"]), true)).toBe(false);
+    expect(shouldPrompt(parseArgs(["my-app", "--template", "hello"]), true)).toBe(
+      false,
+    );
+    expect(shouldPrompt(parseArgs(["--template", "hello"]), true)).toBe(false);
+    expect(shouldPrompt(parseArgs(["--from-example", "notes"]), true)).toBe(
+      false,
+    );
+    expect(shouldPrompt(parseArgs(["--help"]), true)).toBe(false);
+  });
+});
+
+describe("parseArgs flags", () => {
+  test("accepts --yes / --install / --no-install / --no-agents-md", () => {
+    expect(parseArgs(["x", "--yes"]).yes).toBe(true);
+    expect(parseArgs(["x", "-y"]).yes).toBe(true);
+    expect(parseArgs(["x", "--install"]).install).toBe(true);
+    expect(parseArgs(["x", "--no-install"]).install).toBe(false);
+    expect(parseArgs(["x", "--no-agents-md"]).agentsMd).toBe(false);
+    expect(parseArgs(["x"]).agentsMd).toBe(true);
+  });
+
+  test("rejects --install with --no-install", () => {
+    expect(() => parseArgs(["x", "--install", "--no-install"])).toThrow(
+      /install/,
+    );
+  });
+});
+
+describe("sourceFromArgs", () => {
+  test("prefers example when set", () => {
+    expect(sourceFromArgs(parseArgs(["x", "--from-example", "linkly"]))).toEqual(
+      { kind: "example", id: "linkly" },
+    );
+    expect(sourceFromArgs(parseArgs(["x"]))).toEqual({
+      kind: "template",
+      id: DEFAULT_TEMPLATE,
+    });
+  });
+});
+
+describe("scaffoldArgsFromAnswers ≡ flag-driven", () => {
+  test("each --template path matches interactive choice", () => {
+    for (const id of TEMPLATES) {
+      const answers: InteractiveAnswers = {
+        name: "x",
+        choice: id,
+        installAndRun: false,
+        agentsMd: true,
+      };
+      const fromAnswers = scaffoldArgsFromAnswers(answers);
+      const fromFlags = scaffoldArgsFromCli(
+        parseArgs(["x", "--template", id]),
+      );
+      expect(fromAnswers).toEqual(fromFlags);
+      expect(fromAnswers.source).toEqual({ kind: "template", id });
+    }
+  });
+
+  test("each --from-example path matches interactive from-example choice", () => {
+    for (const id of EXAMPLES) {
+      const answers: InteractiveAnswers = {
+        name: "x",
+        choice: FROM_EXAMPLE_CHOICE,
+        example: id,
+        installAndRun: false,
+        agentsMd: true,
+      };
+      const fromAnswers = scaffoldArgsFromAnswers(answers);
+      const fromFlags = scaffoldArgsFromCli(
+        parseArgs(["x", "--from-example", id]),
+      );
+      expect(fromAnswers).toEqual(fromFlags);
+      expect(fromAnswers.source).toEqual({ kind: "example", id });
+    }
+  });
+
+  test("8 paths cover every template and every example", () => {
+    expect(TEMPLATES.length + EXAMPLES.length).toBe(8);
   });
 });
 
@@ -39,7 +171,7 @@ describe("transformPackageJson", () => {
   test("rewrites name and okengine file:../.. to installable ref", () => {
     const next = transformPackageJson(
       {
-        name: "@oke/example-notes",
+        name: "@oke/template-hello",
         private: true,
         dependencies: {
           okengine: "file:../..",
@@ -50,6 +182,7 @@ describe("transformPackageJson", () => {
       "0.0.26",
     );
     expect(next.name).toBe("my-app");
+    expect(next.version).toBe("0.0.1");
     expect(next.dependencies?.["okengine"]).toBe("0.0.26");
     expect(next.dependencies?.["okengine"]).not.toBe("file:../..");
     expect(next.dependencies?.["zod"]).toBe("^4.4.3");
@@ -81,7 +214,7 @@ describe("formatCdPath", () => {
 });
 
 describe("scaffold structure", () => {
-  test("each template produces the example tree (minus skips)", () => {
+  test("each clean template produces its source tree (minus skips)", () => {
     for (const id of TEMPLATES) {
       const dir = mkdtempSync(join(tmpdir(), `create-oke-${id}-`));
       try {
@@ -90,21 +223,187 @@ describe("scaffold structure", () => {
         const result = scaffold({
           targetDir: join(dir, id),
           name: `app-${id}`,
-          template: id,
+          source: { kind: "template", id },
         });
-        expect([...result.files].sort()).toEqual(expected);
+        expect([...result.files].sort()).toEqual(
+          [...expected, "AGENTS.md"].sort(),
+        );
+        expect(result.files).toContain(".gitignore");
+        expect(result.files).toContain("README.md");
+        expect(
+          readFileSync(join(result.targetDir, "AGENTS.md"), "utf8"),
+        ).toMatch(/one law|on\(Trigger\)/i);
+        const readme = readFileSync(join(result.targetDir, "README.md"), "utf8");
+        expect(readme).toMatch(/oke dev/);
+        expect(readme).toMatch(new RegExp(`^# ${id}`, "m"));
+        expect(
+          readFileSync(join(result.targetDir, ".gitignore"), "utf8"),
+        ).toMatch(/node_modules/);
         const pkg = JSON.parse(
           readFileSync(join(result.targetDir, "package.json"), "utf8"),
         ) as { name: string; dependencies: { okengine: string } };
         expect(pkg.name).toBe(`app-${id}`);
         expect(pkg.dependencies.okengine).not.toBe("file:../..");
-        expect(
-          pkg.dependencies.okengine.startsWith("file:") ||
-            /^\d+\.\d+\.\d+/.test(pkg.dependencies.okengine),
-        ).toBe(true);
       } finally {
         rmSync(dir, { recursive: true, force: true });
       }
     }
   });
+
+  test("hello has exactly one flow and no Store", () => {
+    const dir = mkdtempSync(join(tmpdir(), "create-oke-hello-assert-"));
+    try {
+      const result = scaffold({
+        targetDir: join(dir, "hello"),
+        name: "hello-app",
+        source: { kind: "template", id: "hello" },
+      });
+      const flowFiles = result.files.filter(
+        (f) => f.startsWith("src/flows/") && f.endsWith(".ts"),
+      );
+      expect(flowFiles).toEqual(["src/flows/hello/index.ts"]);
+      const flowSrc = readFileSync(
+        join(result.targetDir, "src/flows/hello/index.ts"),
+        "utf8",
+      );
+      expect(flowSrc).toMatch(/export const hello/);
+      expect(flowSrc).not.toMatch(/\bstore\b/);
+      expect(result.files.some((f) => f.includes("core.ts"))).toBe(false);
+      expect(result.files.some((f) => f.includes("schema.ts"))).toBe(false);
+      const all = result.files
+        .filter((f) => f.endsWith(".ts"))
+        .map((f) => readFileSync(join(result.targetDir, f), "utf8"))
+        .join("\n");
+      expect(all).not.toMatch(/store\.sql/);
+      expect(all).not.toMatch(/\bbookings\b|\borders\b|\blinks\b|\bnotes\b/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("standard has full four-applications layout and no business domain", () => {
+    const dir = mkdtempSync(join(tmpdir(), "create-oke-standard-assert-"));
+    try {
+      const result = scaffold({
+        targetDir: join(dir, "standard"),
+        name: "standard-app",
+        source: { kind: "template", id: "standard" },
+      });
+      for (const path of [
+        "src/gates.ts",
+        "src/vault.ts",
+        "src/channels.ts",
+        "src/locales/en.ts",
+        "src/locales/ar.ts",
+        "src/flows/main/shapes.ts",
+        "src/flows/main/signals.ts",
+        "src/core.ts",
+        "src/schema.ts",
+        "src/app.ts",
+      ]) {
+        expect(result.files).toContain(path);
+      }
+      const all = result.files
+        .filter((f) => f.endsWith(".ts") || f.endsWith(".md"))
+        .map((f) => readFileSync(join(result.targetDir, f), "utf8"))
+        .join("\n");
+      expect(all).not.toMatch(/\bbookings\b|\borders\b|\blinks\b|\bstripe\b/i);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("--from-example notes matches today's example tree", () => {
+    const dir = mkdtempSync(join(tmpdir(), "create-oke-from-example-"));
+    try {
+      const exampleDir = resolveExampleDir("notes");
+      const expected = listTemplateFiles(exampleDir);
+      const result = scaffold({
+        targetDir: join(dir, "notes"),
+        name: "from-notes",
+        source: { kind: "example", id: "notes" },
+      });
+      expect([...result.files].sort()).toEqual(
+        [...expected, "AGENTS.md"].sort(),
+      );
+      expect(result.files).toContain("src/flows/notes/index.ts");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("--no-agents-md skips AGENTS.md", () => {
+    const dir = mkdtempSync(join(tmpdir(), "create-oke-no-agents-"));
+    try {
+      const result = scaffold({
+        targetDir: join(dir, "hello"),
+        name: "no-agents",
+        source: { kind: "template", id: "hello" },
+        writeAgentsMd: false,
+      });
+      expect(result.files).not.toContain("AGENTS.md");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("non-TTY CLI", () => {
+  test("no args + non-TTY → zero prompts, exit 1", async () => {
+    const code = await run([], { stdinIsTTY: false, runPostScaffold: false });
+    expect(code).toBe(1);
+  });
+
+  test("spawned with piped stdin shows no clack prompts", async () => {
+    const proc = Bun.spawn(["bun", "run", join(packageRoot(), "src/index.ts")], {
+      cwd: packageRoot(),
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    proc.stdin.end();
+    const code = await proc.exited;
+    const out = await new Response(proc.stdout).text();
+    const err = await new Response(proc.stderr).text();
+    expect(code).toBe(1);
+    expect(err).toMatch(/missing <name>/);
+    // Clack intro / select chrome must not appear.
+    expect(out + err).not.toMatch(/Project name|Start from a worked example/);
+    expect(out + err).not.toMatch(/│/);
+  });
+
+  test("flag-driven scaffold prints the shared next-steps text", async () => {
+    const root = mkdtempSync(join(tmpdir(), "create-oke-flag-"));
+    const target = join(root, "flag-app");
+    try {
+      const code = await run(
+        [target, "--template", "hello", "--no-install"],
+        { stdinIsTTY: false, runPostScaffold: false },
+      );
+      expect(code).toBe(0);
+      expect(readdirSync(target).length).toBeGreaterThan(0);
+      expect(existsSync(join(target, "AGENTS.md"))).toBe(true);
+      const result = {
+        targetDir: target,
+        name: "flag-app",
+        source: { kind: "template" as const, id: "hello" as const },
+        label: "hello",
+        okengineDependency: "x",
+        files: [],
+      };
+      expect(nextStepsText(result)).toContain("oke dev");
+      expect(nextStepsText(result)).toContain("bun install");
+      expect(nextStepsText(result)).toContain("okengine.vercel.app");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("examples catalogue", () => {
+  test("all four teaching examples resolve", () => {
+    for (const id of EXAMPLES) {
+      expect(resolveExampleDir(id)).toBeTruthy();
+    }
+  });
 });