create-oke 0.1.4

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "create-oke",
+  "version": "0.1.4",
+  "description": "Scaffold an okengine app — bunx create-oke@latest <name>",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omqkhafi/okengine.git",
+    "directory": "packages/create-oke"
+  },
+  "bin": {
+    "create-oke": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "templates"
+  ],
+  "scripts": {
+    "prepack": "bun ./src/sync-templates.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:integration": "CREATE_OKE_INTEGRATION=1 bun test tests/scaffold.integration.test.ts tests/dev.integration.test.ts"
+  },
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^7.0.2"
+  }
+}

package/src/cli.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Unit tests for create-oke argument parsing and transforms.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { formatCdPath, parseArgs } from "./cli.ts";
+import { listTemplateFiles, scaffold } from "./scaffold.ts";
+import { resolveTemplateDir, TEMPLATES } from "./templates.ts";
+import {
+  sanitizeProjectName,
+  shouldSkipTemplatePath,
+  transformPackageJson,
+} from "./transform.ts";
+
+describe("parseArgs", () => {
+  test("defaults template to notes", () => {
+    const a = parseArgs(["my-app"]);
+    expect(a.name).toBe("my-app");
+    expect(a.template).toBe("notes");
+  });
+
+  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",
+    );
+  });
+
+  test("rejects unknown template", () => {
+    expect(() => parseArgs(["x", "--template", "nope"])).toThrow(/template/);
+  });
+});
+
+describe("transformPackageJson", () => {
+  test("rewrites name and okengine file:../.. to installable ref", () => {
+    const next = transformPackageJson(
+      {
+        name: "@oke/example-notes",
+        private: true,
+        dependencies: {
+          okengine: "file:../..",
+          zod: "^4.4.3",
+        },
+      },
+      "my-app",
+      "0.0.26",
+    );
+    expect(next.name).toBe("my-app");
+    expect(next.dependencies?.["okengine"]).toBe("0.0.26");
+    expect(next.dependencies?.["okengine"]).not.toBe("file:../..");
+    expect(next.dependencies?.["zod"]).toBe("^4.4.3");
+  });
+});
+
+describe("shouldSkipTemplatePath", () => {
+  test("skips node_modules, locks, and monorepo docker test", () => {
+    expect(shouldSkipTemplatePath("node_modules/okengine/package.json")).toBe(
+      true,
+    );
+    expect(shouldSkipTemplatePath("bun.lock")).toBe(true);
+    expect(shouldSkipTemplatePath("tests/docker.test.ts")).toBe(true);
+    expect(shouldSkipTemplatePath("tests/support.test.ts")).toBe(false);
+    expect(shouldSkipTemplatePath("oke.config.ts")).toBe(false);
+  });
+});
+
+describe("sanitizeProjectName", () => {
+  test("lowercases and slugifies", () => {
+    expect(sanitizeProjectName("My App")).toBe("my-app");
+  });
+});
+
+describe("formatCdPath", () => {
+  test("keeps absolute paths outside cwd", () => {
+    expect(formatCdPath("/tmp/my-app")).toBe("/tmp/my-app");
+  });
+});
+
+describe("scaffold structure", () => {
+  test("each template produces the example tree (minus skips)", () => {
+    for (const id of TEMPLATES) {
+      const dir = mkdtempSync(join(tmpdir(), `create-oke-${id}-`));
+      try {
+        const templateDir = resolveTemplateDir(id);
+        const expected = listTemplateFiles(templateDir);
+        const result = scaffold({
+          targetDir: join(dir, id),
+          name: `app-${id}`,
+          template: id,
+        });
+        expect([...result.files].sort()).toEqual(expected);
+        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 });
+      }
+    }
+  });
+});

package/src/cli.ts

@@ -0,0 +1,156 @@
+/**
+ * `create-oke` CLI — one command, sensible default, done.
+ *
+ * ```bash
+ * bunx create-oke@latest <name> [--template notes|linkly|provisions|skyport]
+ * ```
+ */
+
+import { basename, relative, resolve } from "node:path";
+import { scaffold } from "./scaffold.ts";
+import {
+  DEFAULT_TEMPLATE,
+  TEMPLATES,
+  isTemplateId,
+  type TemplateId,
+} from "./templates.ts";
+
+/** Parsed CLI arguments. */
+export type CliArgs = {
+  readonly name: string | undefined;
+  readonly template: TemplateId;
+  readonly help: boolean;
+  readonly targetDir: string | undefined;
+};
+
+/**
+ * Parse argv after the binary name.
+ *
+ * @param argv - Process arguments (no node/bun binary)
+ */
+export function parseArgs(argv: readonly string[]): CliArgs {
+  let name: string | undefined;
+  let template: TemplateId = DEFAULT_TEMPLATE;
+  let help = false;
+  let targetDir: string | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--help" || a === "-h") {
+      help = 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("|")}`,
+        );
+      }
+      template = next;
+      continue;
+    }
+    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("|")}`,
+        );
+      }
+      template = value;
+      continue;
+    }
+    if (a.startsWith("-")) {
+      throw new Error(`create-oke: unknown option ${a}`);
+    }
+    if (name === undefined) {
+      name = a;
+      continue;
+    }
+    throw new Error(`create-oke: unexpected argument ${a}`);
+  }
+
+  if (name !== undefined) {
+    targetDir = resolve(name);
+  }
+
+  return { name, template, help, targetDir };
+}
+
+/**
+ * Path for the post-scaffold `cd` line — relative when under cwd, else absolute.
+ *
+ * @param targetDir - Absolute project directory
+ */
+export function formatCdPath(targetDir: string): string {
+  const rel = relative(process.cwd(), targetDir);
+  if (!rel || rel.startsWith("..") || rel.includes("..")) return targetDir;
+  return rel;
+}
+
+/**
+ * Help text — next steps match four-applications.md (`bun install` · `oke dev`).
+ */
+export function helpText(): string {
+  return `create-oke — scaffold an okengine app
+
+Usage:
+  bunx create-oke@latest <name> [--template notes|linkly|provisions|skyport]
+
+Templates (from examples/):
+  notes        basic — Flow · Store                         (default)
+  linkly       intermediate — + Signal · Clock · Gate
+  provisions   advanced — + Vault · Channel · plugins
+  skyport      complex — all eight elements · AI · tenancy
+
+No telemetry. Bun only. No interactive wizard.
+`;
+}
+
+/**
+ * Run the CLI.
+ *
+ * @param argv - Args after the binary
+ * @returns Exit code
+ */
+export async function run(argv: readonly string[]): Promise<number> {
+  let args: CliArgs;
+  try {
+    args = parseArgs(argv);
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : e);
+    return 1;
+  }
+
+  if (args.help || args.name === undefined) {
+    console.log(helpText());
+    if (args.name === undefined && !args.help) {
+      console.error("create-oke: missing <name>");
+      return 1;
+    }
+    return args.help ? 0 : 1;
+  }
+
+  const projectName = basename(resolve(args.name));
+  try {
+    const result = scaffold({
+      targetDir: args.targetDir!,
+      name: projectName,
+      template: args.template,
+    });
+
+    console.log(`
+Scaffolded ${result.template} → ${result.targetDir}
+
+Next steps:
+
+  cd ${formatCdPath(result.targetDir)}
+  bun install
+  oke dev          # app :6530 · Console :6533 · MCP :6535
+`);
+    return 0;
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : e);
+    return 1;
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+/**
+ * `create-oke` binary entry.
+ */
+
+import { run } from "./cli.ts";
+
+process.exit(await run(process.argv.slice(2)));

package/src/scaffold.ts

@@ -0,0 +1,160 @@
+/**
+ * Copy an `examples/<template>` tree and apply the package.json transform.
+ */
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join, relative, resolve } from "node:path";
+import {
+  resolveLocalOkengineRoot,
+  resolveTemplateDir,
+  type TemplateId,
+} from "./templates.ts";
+import {
+  sanitizeProjectName,
+  shouldSkipTemplatePath,
+  transformPackageJson,
+  resolveOkengineDependency,
+  type ScaffoldPackageJson,
+} from "./transform.ts";
+
+/** 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;
+};
+
+/** Result of a successful scaffold. */
+export type ScaffoldResult = {
+  readonly targetDir: string;
+  readonly name: string;
+  readonly template: TemplateId;
+  readonly okengineDependency: string;
+  /** Relative paths written (POSIX), sorted. */
+  readonly files: readonly string[];
+};
+
+/**
+ * Scaffold a new okengine project from `examples/<template>`.
+ *
+ * @param options - Name, template, destination
+ */
+export function scaffold(options: ScaffoldOptions): ScaffoldResult {
+  const name = sanitizeProjectName(options.name);
+  const targetDir = resolve(options.targetDir);
+  const templateDir = resolveTemplateDir(options.template);
+
+  if (existsSync(targetDir)) {
+    const entries = readdirSync(targetDir);
+    if (entries.length > 0) {
+      throw new Error(
+        `create-oke: target directory is not empty: ${targetDir}`,
+      );
+    }
+  } else {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  const okengineDependency = resolveOkengineDependency(
+    resolveLocalOkengineRoot(),
+  );
+  const written: string[] = [];
+
+  copyTree(templateDir, 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");
+
+  written.sort();
+  return {
+    targetDir,
+    name,
+    template: options.template,
+    okengineDependency,
+    files: written,
+  };
+}
+
+/**
+ * Recursively copy template files, applying {@link shouldSkipTemplatePath}.
+ *
+ * @param srcRoot - Template root
+ * @param dstRoot - Destination root
+ * @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 {
+  const src = rel ? join(srcRoot, rel) : srcRoot;
+  const st = statSync(src);
+  if (st.isDirectory()) {
+    if (rel && shouldSkipTemplatePath(rel)) return;
+    if (rel) mkdirSync(join(dstRoot, rel), { recursive: true });
+    for (const entry of readdirSync(src)) {
+      copyTree(srcRoot, dstRoot, rel ? join(rel, entry) : entry, written);
+    }
+    return;
+  }
+  if (!st.isFile()) return;
+  const posixRel = rel.split(/[/\\]/).join("/");
+  if (shouldSkipTemplatePath(posixRel)) return;
+  const dst = join(dstRoot, rel);
+  mkdirSync(join(dst, ".."), { recursive: true });
+  cpSync(src, dst);
+  written.push(posixRel);
+}
+
+/**
+ * List relative file paths in an example tree using the same skip rules as scaffold.
+ *
+ * @param templateDir - Absolute template directory
+ */
+export function listTemplateFiles(templateDir: string): string[] {
+  const out: string[] = [];
+  walk(templateDir, templateDir, out);
+  out.sort();
+  return out;
+}
+
+/**
+ * @param root - Template root
+ * @param dir - Current directory
+ * @param out - Accumulator
+ */
+function walk(root: string, dir: string, out: string[]): void {
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    const rel = relative(root, abs).split(/[/\\]/).join("/");
+    const st = statSync(abs);
+    if (st.isDirectory()) {
+      if (shouldSkipTemplatePath(rel)) continue;
+      walk(root, abs, out);
+      continue;
+    }
+    if (st.isFile() && !shouldSkipTemplatePath(rel)) out.push(rel);
+  }
+}

package/src/sync-templates.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env bun
+/**
+ * prepack: copy `examples/<template>` into `templates/<template>` so the
+ * published npm package can scaffold without the monorepo checkout.
+ *
+ * Applies the same skip rules as runtime scaffold (no node_modules, no
+ * monorepo-only docker.test.ts).
+ */
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { packageRoot, TEMPLATES } from "./templates.ts";
+import { shouldSkipTemplatePath } from "./transform.ts";
+
+const pkg = packageRoot();
+const examplesRoot = resolve(pkg, "../../examples");
+const outRoot = join(pkg, "templates");
+
+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 });
+
+for (const id of TEMPLATES) {
+  const src = join(examplesRoot, id);
+  const dst = join(outRoot, 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}`);
+}
+
+/**
+ * @param src - Source file or directory
+ * @param dst - Destination path
+ * @param root - Template root for relative skip paths
+ */
+function copyFiltered(src: string, dst: string, root: string): void {
+  const st = statSync(src);
+  const rel = relative(root, src).split(/[/\\]/).join("/");
+  if (rel && shouldSkipTemplatePath(rel)) return;
+  if (st.isDirectory()) {
+    mkdirSync(dst, { recursive: true });
+    for (const entry of readdirSync(src)) {
+      copyFiltered(join(src, entry), join(dst, entry), root);
+    }
+    return;
+  }
+  if (st.isFile()) {
+    mkdirSync(join(dst, ".."), { recursive: true });
+    cpSync(src, dst);
+  }
+}

package/src/templates.ts

@@ -0,0 +1,85 @@
+/**
+ * Template ids and resolution — always sourced from `examples/<id>`,
+ * with a published-package fallback at `templates/<id>` (filled by prepack).
+ */
+
+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;
+
+/** A known scaffold template. */
+export type TemplateId = (typeof TEMPLATES)[number];
+
+/** Default when `--template` is omitted (smallest quickstart). */
+export const DEFAULT_TEMPLATE: TemplateId = "notes";
+
+/**
+ * Whether `value` is a known {@link TemplateId}.
+ *
+ * @param value - Candidate string
+ */
+export function isTemplateId(value: string): value is TemplateId {
+  return (TEMPLATES as readonly string[]).includes(value);
+}
+
+/**
+ * Directory that contains this package (`packages/create-oke`).
+ */
+export function packageRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+/**
+ * Resolve the directory to copy for `template`.
+ *
+ * Order:
+ * 1. `CREATE_OKE_EXAMPLES` env (absolute path to an `examples/` tree)
+ * 2. Monorepo `examples/<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"];
+  if (envRoot) {
+    const fromEnv = resolve(envRoot, template);
+    if (existsSync(fromEnv)) return fromEnv;
+  }
+
+  const pkg = packageRoot();
+  const monorepo = resolve(pkg, "../../examples", 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}`,
+  );
+}
+
+/**
+ * Absolute path to the okengine package root when running inside this monorepo.
+ *
+ * @returns Repo root, or `null` when create-oke is used from a published install
+ */
+export function resolveLocalOkengineRoot(): string | null {
+  const env = process.env["CREATE_OKE_OKENGINE"];
+  if (env && existsSync(join(env, "package.json"))) return resolve(env);
+
+  const candidate = resolve(packageRoot(), "../..");
+  const pkgPath = join(candidate, "package.json");
+  if (!existsSync(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: string };
+    return pkg.name === "okengine" ? candidate : null;
+  } catch {
+    return null;
+  }
+}