keryx 0.0.1 → 0.2.0

package/classes/API.ts

@@ -1,5 +1,8 @@
+import { Glob } from "bun";
+import fs from "fs";
 import path from "path";
 import { config } from "../config";
+import { deepMerge } from "../util/config";
 import { globLoader } from "../util/glob";
 import type { Initializer, InitializerSortKeys } from "./Initializer";
 import { Logger } from "./Logger";
@@ -43,6 +46,7 @@ export class API {
     this.logger.warn("--- 🔄  Initializing process ---");
     this.initialized = false;
 
+    await this.loadLocalConfig();
     await this.findInitializers();
     this.sortInitializers("loadPriority");
 
@@ -138,6 +142,26 @@ export class API {
     flapPreventer = false;
   }
 
+  private async loadLocalConfig() {
+    if (this.rootDir === this.packageDir) return;
+
+    const configDir = path.join(this.rootDir, "config");
+    if (!fs.existsSync(configDir)) return;
+
+    const glob = new Glob("**/*.ts");
+    for await (const file of glob.scan(configDir)) {
+      if (file.startsWith(".")) continue;
+
+      const fullPath = path.join(configDir, file);
+      const mod = await import(fullPath);
+      const overrides = mod.default ?? mod;
+      if (overrides && typeof overrides === "object") {
+        deepMerge(config, overrides);
+        this.logger.debug(`Loaded user config from config/${file}`);
+      }
+    }
+  }
+
   private async findInitializers() {
     // Load framework initializers from the package directory
     const frameworkInitializers = await globLoader<Initializer>(

package/config/index.ts

@@ -21,3 +21,5 @@ export const config = {
   server: { cli: configServerCli, web: configServerWeb, mcp: configServerMcp },
   tasks: configTasks,
 };
+
+export type KeryxConfig = typeof config;

package/index.ts

@@ -19,7 +19,8 @@ import "./initializers/swagger";
 export * from "./api";
 export type { ActionMiddleware } from "./classes/Action";
 export { ErrorStatusCodes, ErrorType, TypedError } from "./classes/TypedError";
-export { loadFromEnvIfSet } from "./util/config";
+export type { KeryxConfig } from "./config";
+export { deepMerge, loadFromEnvIfSet } from "./util/config";
 export { globLoader } from "./util/glob";
 export {
   isSecret,

package/keryx.ts

@@ -6,10 +6,56 @@ import { Action, api } from "./api";
 import pkg from "./package.json";
 import { addActionToProgram } from "./util/cli";
 import { globLoader } from "./util/glob";
+import {
+  interactiveScaffold,
+  scaffoldProject,
+  type ScaffoldOptions,
+} from "./util/scaffold";
 
 const program = new Command();
 program.name(pkg.name).description(pkg.description).version(pkg.version);
 
+program
+  .command("new [project-name]")
+  .summary("Create a new Keryx project")
+  .description("Scaffold a new Keryx application with project boilerplate")
+  .option("--no-interactive", "Skip prompts and use defaults")
+  .option("--no-db", "Skip database setup files")
+  .option("--no-example", "Skip example action")
+  .action(async (projectName: string | undefined, opts) => {
+    let options: ScaffoldOptions;
+
+    if (opts.interactive === false) {
+      // --no-interactive: use defaults
+      projectName = projectName || "my-keryx-app";
+      options = {
+        includeDb: opts.db !== false,
+        includeExample: opts.example !== false,
+      };
+    } else {
+      const result = await interactiveScaffold(projectName);
+      projectName = result.projectName;
+      options = result.options;
+    }
+
+    const targetDir = path.resolve(process.cwd(), projectName);
+
+    console.log(`\nCreating new Keryx project: ${projectName}\n`);
+
+    const files = await scaffoldProject(projectName, targetDir, options);
+    files.forEach((f) => console.log(`  ${f}`));
+
+    console.log(`
+Done! To get started:
+
+  cd ${projectName}
+  cp .env.example .env
+  bun install
+  bun dev
+`);
+    process.exit(0);
+  });
+
 program
   .command("start")
   .summary("Run the server")

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "keryx",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",
   "description": "Keryx - the messenger of the gods. The greatest framework for building realtime AI, CLI, and web applications, and other applications too!",
-  "author": "Evan Tahler <evantahler@gmail.com>",
+  "author": "Evan Tahler <evan@evantahler.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/evantahler/keryx.git",
@@ -61,6 +61,7 @@
     "start": "bun keryx.ts start",
     "dev": "bun --watch keryx.ts start",
     "migrations": "bun run migrations.ts",
+    "test": "tsc && bun test",
     "compile": "bun build keryx.ts --compile --outfile keryx",
     "lint": "tsc && prettier --check .",
     "format": "tsc && prettier --write ."

package/templates/scaffold/env.example.mustache

@@ -0,0 +1,38 @@
+PROCESS_NAME={{projectName}}
+PROCESS_NAME_TEST=test-server
+PROCESS_SHUTDOWN_TIMEOUT=30000
+
+LOG_LEVEL=info
+LOG_LEVEL_TEST=fatal
+LOG_INCLUDE_TIMESTAMPS=false
+LOG_COLORIZE=true
+
+WEB_SERVER_ENABLED=true
+WEB_SERVER_PORT=8080
+WEB_SERVER_PORT_TEST=0
+WEB_SERVER_HOST=localhost
+WEB_SERVER_API_ROUTE="/api"
+WEB_SERVER_ALLOWED_ORIGINS="http://localhost:3000"
+WEB_SERVER_ALLOWED_METHODS="GET, POST, PUT, DELETE, OPTIONS"
+
+MCP_SERVER_ENABLED=true
+
+SESSION_TTL=86400000
+SESSION_COOKIE_NAME="__session"
+
+DATABASE_URL="postgres://$USER@localhost:5432/{{projectName}}"
+DATABASE_URL_TEST="postgres://$USER@localhost:5432/{{projectName}}-test"
+DATABASE_AUTO_MIGRATE=true
+
+REDIS_URL="redis://localhost:6379/0"
+REDIS_URL_TEST="redis://localhost:6379/1"
+
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_UNAUTH_LIMIT=20
+RATE_LIMIT_AUTH_LIMIT=200
+
+TASKS_ENABLED=true
+TASK_PROCESSORS=1
+TASK_TIMEOUT=5000
+TASK_TIMEOUT_TEST=100

package/templates/scaffold/gitignore.mustache

@@ -0,0 +1,3 @@
+node_modules/
+.env
+drizzle/

package/templates/scaffold/hello-action.ts.mustache

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { Action, type ActionParams } from "keryx";
+import { HTTP_METHOD } from "keryx/classes/Action.ts";
+
+export class Hello implements Action {
+  name = "hello";
+  description = "Say hello";
+  inputs = z.object({
+    name: z.string().default("World"),
+  });
+  web = { route: "/hello", method: HTTP_METHOD.GET };
+
+  async run(params: ActionParams<Hello>) {
+    return { message: `Hello, ${params.name}!` };
+  }
+}

package/templates/scaffold/index.ts.mustache

@@ -0,0 +1,10 @@
+import { api } from "keryx";
+
+// Tell the framework where this project lives so it can auto-discover
+// actions, initializers, channels, etc. from this directory.
+// Every entry point (keryx.ts, migrations.ts, test setup) should
+// `import "./index"` to ensure rootDir is set before anything runs.
+api.rootDir = import.meta.dir;
+
+// Re-export everything from keryx for convenience
+export * from "keryx";

package/templates/scaffold/keryx.ts.mustache

@@ -0,0 +1,62 @@
+#! /usr/bin/env bun
+
+// Set rootDir before any framework code loads actions
+import { api } from "./index";
+
+import { Command } from "commander";
+import { Action, globLoader } from "keryx";
+import { addActionToProgram } from "keryx/util/cli.ts";
+import path from "path";
+import pkg from "./package.json";
+
+const program = new Command();
+program.name(pkg.name).description(pkg.description).version(pkg.version);
+
+program
+  .command("start")
+  .summary("Run the server")
+  .description("Start the Keryx server")
+  .action(async () => {
+    await api.start();
+  });
+
+// Load framework actions from the package directory
+const frameworkActions = await globLoader<Action>(
+  path.join(api.packageDir, "actions"),
+);
+
+// Load user project actions
+let userActions: Action[] = [];
+try {
+  userActions = await globLoader<Action>(path.join(api.rootDir, "actions"));
+} catch {
+  // user project may not have actions, that's fine
+}
+
+const actions = [...frameworkActions, ...userActions];
+actions.forEach((action) => addActionToProgram(program, action));
+
+program
+  .command("actions")
+  .summary("List all actions")
+  .action(async () => {
+    const actionSpacing =
+      actions.map((a) => a.name.length).reduce((a, b) => Math.max(a, b), 0) +
+      2;
+    const routeSpacing =
+      actions
+        .map((a) =>
+          a.web ? a.web.route.toString().length + a.web.method.length : 0,
+        )
+        .reduce((a, b) => Math.max(a, b), 0) + 2;
+
+    actions
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .forEach((action) => {
+        console.log(
+          `${action.name}${" ".repeat(actionSpacing - action.name.length)} ${action.web ? `[${action.web.method}] ${action.web.route}` : " "}${" ".repeat(routeSpacing - (action.web ? action.web.method.length + action.web.route.toString().length + 2 : 0))} ${action.description ?? ""}`,
+        );
+      });
+  });
+
+program.parse();

package/templates/scaffold/migrations.ts.mustache

@@ -0,0 +1,8 @@
+// Set rootDir before any framework code loads
+import "./index";
+
+import { api } from "keryx";
+
+await api.initialize();
+await api.db.generateMigrations();
+process.exit(0);

package/util/config.ts

@@ -1,3 +1,32 @@
+/**
+Deep-merges source into target, mutating target in place.
+Only plain objects are recursively merged; arrays and primitives are overwritten.
+*/
+export function deepMerge<T extends Record<string, any>>(
+  target: T,
+  source: Record<string, any>,
+): T {
+  for (const key of Object.keys(source)) {
+    const targetVal = target[key];
+    const sourceVal = source[key];
+
+    if (
+      targetVal &&
+      sourceVal &&
+      typeof targetVal === "object" &&
+      typeof sourceVal === "object" &&
+      !Array.isArray(targetVal) &&
+      !Array.isArray(sourceVal)
+    ) {
+      deepMerge(targetVal, sourceVal);
+    } else {
+      (target as any)[key] = sourceVal;
+    }
+  }
+
+  return target;
+}
+
 /**
 Loads a value from the environment, if it's set, otherwise returns the default value.
 */

package/util/scaffold.ts

@@ -0,0 +1,211 @@
+import { Glob } from "bun";
+import fs from "fs";
+import Mustache from "mustache";
+import path from "path";
+import * as readline from "readline";
+import pkg from "../package.json";
+
+export interface ScaffoldOptions {
+  includeDb: boolean;
+  includeExample: boolean;
+}
+
+const templatesDir = path.join(import.meta.dir, "..", "templates", "scaffold");
+
+async function loadTemplate(name: string): Promise<string> {
+  return Bun.file(path.join(templatesDir, name)).text();
+}
+
+async function prompt(question: string, defaultValue: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(`${question} `, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+async function promptYesNo(
+  question: string,
+  defaultYes: boolean,
+): Promise<boolean> {
+  const hint = defaultYes ? "Y/n" : "y/N";
+  const answer = await prompt(`${question} (${hint})`, defaultYes ? "y" : "n");
+  return answer.toLowerCase().startsWith("y");
+}
+
+export async function interactiveScaffold(
+  projectName?: string,
+): Promise<{ projectName: string; options: ScaffoldOptions }> {
+  if (!projectName) {
+    projectName = await prompt("Project name:", "my-keryx-app");
+  }
+
+  const includeDb = await promptYesNo("Include database setup?", true);
+  const includeExample = await promptYesNo("Include example action?", true);
+
+  return { projectName, options: { includeDb, includeExample } };
+}
+
+export async function scaffoldProject(
+  projectName: string,
+  targetDir: string,
+  options: ScaffoldOptions,
+): Promise<string[]> {
+  const keryxVersion = pkg.version;
+  const createdFiles: string[] = [];
+
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Directory "${projectName}" already exists`);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const view = { projectName, keryxVersion };
+
+  const write = async (filePath: string, content: string) => {
+    const fullPath = path.join(targetDir, filePath);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    await Bun.write(fullPath, content);
+    createdFiles.push(filePath);
+  };
+
+  const writeTemplate = async (filePath: string, templateName: string) => {
+    const template = await loadTemplate(templateName);
+    await write(filePath, Mustache.render(template, view));
+  };
+
+  // --- Always generated ---
+
+  // package.json is built programmatically (conditional deps/scripts)
+  await write(
+    "package.json",
+    JSON.stringify(
+      {
+        name: projectName,
+        version: "0.0.1",
+        module: "index.ts",
+        type: "module",
+        private: true,
+        license: "MIT",
+        bin: { keryx: "keryx.ts" },
+        scripts: {
+          start: "bun keryx.ts start",
+          dev: "bun --watch keryx.ts start",
+          ...(options.includeDb ? { migrations: "bun run migrations.ts" } : {}),
+          lint: "tsc && prettier --check .",
+          format: "tsc && prettier --write .",
+        },
+        dependencies: {
+          keryx: `^${keryxVersion}`,
+          ...(options.includeDb ? { "drizzle-zod": "^0.8.3" } : {}),
+        },
+        devDependencies: {
+          "@types/bun": "latest",
+          prettier: "^3.8.1",
+          ...(options.includeDb ? { "drizzle-kit": "^0.20.18" } : {}),
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  // tsconfig.json is static JSON (no interpolation needed)
+  await write(
+    "tsconfig.json",
+    JSON.stringify(
+      {
+        compilerOptions: {
+          lib: ["ESNext"],
+          target: "ESNext",
+          module: "ESNext",
+          moduleResolution: "bundler",
+          types: ["bun-types"],
+          strict: true,
+          skipLibCheck: true,
+          noEmit: true,
+          esModuleInterop: true,
+          resolveJsonModule: true,
+          isolatedModules: true,
+          verbatimModuleSyntax: true,
+          noImplicitAny: true,
+          noImplicitReturns: true,
+          noUnusedLocals: true,
+          noUnusedParameters: true,
+          noFallthroughCasesInSwitch: true,
+          forceConsistentCasingInFileNames: true,
+          allowImportingTsExtensions: true,
+        },
+        include: ["**/*.ts"],
+        exclude: ["node_modules", "drizzle"],
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  await writeTemplate("index.ts", "index.ts.mustache");
+  await writeTemplate("keryx.ts", "keryx.ts.mustache");
+  await writeTemplate(".env.example", "env.example.mustache");
+  await writeTemplate(".gitignore", "gitignore.mustache");
+  // Copy config files from the framework, adjusting imports for user projects
+  const configDir = path.join(import.meta.dir, "..", "config");
+  const glob = new Glob("**/*.ts");
+  for await (const file of glob.scan(configDir)) {
+    let content = await Bun.file(path.join(configDir, file)).text();
+
+    // Rewrite relative imports to package imports
+    content = content.replace(
+      /from ["']\.\.\/\.\.\/util\/config["']/g,
+      'from "keryx"',
+    );
+    content = content.replace(
+      /from ["']\.\.\/util\/config["']/g,
+      'from "keryx"',
+    );
+    content = content.replace(
+      /from ["']\.\.\/classes\/Logger["']/g,
+      'from "keryx/classes/Logger.ts"',
+    );
+
+    // In index.ts, change `export const config` to `export default`
+    // and remove the KeryxConfig type export (it comes from the package)
+    if (file === "index.ts") {
+      content = content.replace("export const config =", "export default");
+      content = content.replace(
+        /\nexport type KeryxConfig = typeof config;\n/,
+        "\n",
+      );
+    }
+
+    await write(`config/${file}`, content);
+  }
+
+  // Create empty directories with .gitkeep
+  await write("initializers/.gitkeep", "");
+  await write("middleware/.gitkeep", "");
+  await write("channels/.gitkeep", "");
+
+  // --- Database setup ---
+
+  if (options.includeDb) {
+    await writeTemplate("migrations.ts", "migrations.ts.mustache");
+    await write("schema/.gitkeep", "");
+    await write("drizzle/.gitkeep", "");
+  }
+
+  // --- Example action ---
+
+  if (options.includeExample) {
+    await writeTemplate("actions/hello.ts", "hello-action.ts.mustache");
+  } else {
+    await write("actions/.gitkeep", "");
+  }
+
+  return createdFiles;
+}