@veducio/keja 0.0.0-stage → 0.3.0

package/src/cli/init-project.ts

@@ -0,0 +1,416 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import {
+  copyFile,
+  cp,
+  mkdir,
+  readdir,
+  readFile,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const projectName = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export type InitInput = {
+  name?: string;
+  dir?: string;
+  public?: string;
+  service?: string;
+};
+
+export type InitAnswers = {
+  name: string;
+  directory: string;
+  publicDir: string;
+  serviceDir: string;
+};
+
+type Ask = (label: string, fallback: string) => Promise<string>;
+
+type Run = (command: string, args: string[], cwd: string) => Promise<number>;
+
+const publicHello = `import { defineRoute, response } from "@veducio/keja";
+import { z } from "zod";
+
+export default defineRoute({
+  method: "get",
+  path: "/hello",
+  version: "v1",
+  responses: {
+    Hello: response({
+      code: 200,
+      json: z.object({ message: z.string() }),
+    }),
+  },
+  handler: ({ respond }) => respond.Hello({ message: "hello" }),
+});
+`;
+
+const publicMiddleware = `import { defineMiddleware } from "@veducio/keja";
+
+export default defineMiddleware(async ({ next }) => {
+  const response = await next();
+  response.headers.set("x-keja", "public");
+  return response;
+});
+`;
+
+const servicePing = `import { defineRoute, response } from "@veducio/keja";
+import { z } from "zod";
+
+export default defineRoute({
+  method: "post",
+  path: "/ping",
+  version: "v1",
+  responses: {
+    Pong: response({
+      code: 200,
+      json: z.object({ ok: z.literal(true) }),
+    }),
+  },
+  handler: ({ respond }) => respond.Pong({ ok: true }),
+});
+`;
+
+export async function resolveInitAnswers(input: InitInput, ask: Ask) {
+  const name = await valueOrAsk(
+    input.name,
+    "Name of the project",
+    "my-app",
+    ask,
+  );
+  if (!projectName.test(name)) {
+    throw new Error(
+      "Project name must use letters, numbers, dots, hyphens, or underscores.",
+    );
+  }
+  const directory = await valueOrAsk(
+    input.dir,
+    "Where you want to create the project",
+    `./${name}`,
+    ask,
+  );
+  if (directory.trim() === "") {
+    throw new Error("Project directory is required.");
+  }
+  return {
+    name,
+    directory: directory.trim(),
+    publicDir: routeFolder(
+      await valueOrAsk(
+        input.public,
+        "What folder should the public server be",
+        "./src/public",
+        ask,
+      ),
+      "Public server folder",
+    ),
+    serviceDir: routeFolder(
+      await valueOrAsk(
+        input.service,
+        "What folder should the service server be",
+        "./src/service",
+        ask,
+      ),
+      "Service server folder",
+    ),
+  } satisfies InitAnswers;
+}
+
+export async function createProject(options: {
+  answers: InitAnswers;
+  cwd: string;
+  templateDir: string;
+  packageRoot: string;
+  run: Run;
+}) {
+  await requireBun(options.run, options.cwd);
+  await requireGit(options.run, options.cwd);
+  const destination = path.resolve(options.cwd, options.answers.directory);
+  if (existsSync(destination)) {
+    const entries = await readdir(destination);
+    if (entries.length > 0) {
+      throw new Error(`${destination} already exists and is not empty.`);
+    }
+  }
+  await cp(options.templateDir, destination, {
+    recursive: true,
+    filter(source) {
+      const base = path.basename(source);
+      return base !== "node_modules" && base !== ".git";
+    },
+  });
+  const envFile = path.join(destination, ".env");
+  const envExample = path.join(destination, ".env.example");
+  if (!existsSync(envFile) && existsSync(envExample)) {
+    await copyFile(envExample, envFile);
+  }
+  const keja = await readKejaPackage(options.packageRoot);
+  await writeFile(
+    path.join(destination, "package.json"),
+    `${JSON.stringify(
+      {
+        name: options.answers.name,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: {
+          dev: "keja dev",
+          start: "keja start",
+        },
+        dependencies: {
+          [keja.name]: `^${keja.version}`,
+          zod: "^4.6.7",
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  await writeFile(
+    path.join(destination, "keja.config.ts"),
+    sourceFor(
+      keja.name,
+      configSource(options.answers.publicDir, options.answers.serviceDir),
+    ),
+  );
+  await writeFile(
+    path.join(destination, "tsconfig.json"),
+    `${JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2023",
+          lib: ["ES2023"],
+          module: "ESNext",
+          moduleResolution: "bundler",
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+          isolatedModules: true,
+          forceConsistentCasingInFileNames: true,
+          allowImportingTsExtensions: true,
+        },
+        include: ["**/*.ts"],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  if (usesGitHubPackages(keja)) {
+    await writeFile(
+      path.join(destination, ".npmrc"),
+      "@veducio:registry=https://npm.pkg.github.com\n",
+    );
+  }
+  await writeRoute(
+    destination,
+    options.answers.publicDir,
+    "_middleware.ts",
+    sourceFor(keja.name, publicMiddleware),
+  );
+  await writeRoute(
+    destination,
+    options.answers.publicDir,
+    "hello.ts",
+    sourceFor(keja.name, publicHello),
+  );
+  await writeRoute(
+    destination,
+    options.answers.serviceDir,
+    "ping.ts",
+    sourceFor(keja.name, servicePing),
+  );
+  const installCode = await options.run("bun", ["install"], destination);
+  if (installCode !== 0) {
+    throw new Error(`bun install failed in ${destination}`);
+  }
+  const initCode = await options.run("git", ["init"], destination);
+  if (initCode !== 0) {
+    throw new Error(`git init failed in ${destination}`);
+  }
+  return destination;
+}
+
+export async function runInit(options: {
+  input: InitInput;
+  cwd: string;
+  templateDir: string;
+  packageRoot: string;
+  interactive: boolean;
+  ask: Ask;
+  run: Run;
+  log: (message: string) => void;
+}) {
+  const answers = await resolveInitAnswers(
+    options.input,
+    options.interactive ? options.ask : async (_label, fallback) => fallback,
+  );
+  const directory = await createProject({
+    answers,
+    cwd: options.cwd,
+    templateDir: options.templateDir,
+    packageRoot: options.packageRoot,
+    run: options.run,
+  });
+  options.log(`\n  Created ${answers.name} at ${directory}\n`);
+  return directory;
+}
+
+export function starterPaths(moduleUrl = import.meta.url) {
+  return {
+    templateDir: fileUrl(new URL("../../examples/starter", moduleUrl)),
+    packageRoot: fileUrl(new URL("../..", moduleUrl)),
+  };
+}
+
+export async function askOnTerminal(label: string, fallback: string) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    return await rl.question(`  ${label} (${fallback}): `);
+  } finally {
+    rl.close();
+  }
+}
+
+export function runCommand(command: string, args: string[], cwd: string) {
+  const visible = command === "bun" && args[0] === "install";
+  return new Promise<number>((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: visible ? "inherit" : "ignore",
+      windowsHide: true,
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+
+async function requireBun(run: Run, cwd: string) {
+  try {
+    const code = await run("bun", ["--version"], cwd);
+    if (code !== 0) {
+      throw new Error("Bun is required to create a project.");
+    }
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message === "Bun is required to create a project."
+    ) {
+      throw error;
+    }
+    throw new Error("Bun is required to create a project.");
+  }
+}
+
+async function requireGit(run: Run, cwd: string) {
+  try {
+    const code = await run("git", ["--version"], cwd);
+    if (code !== 0) {
+      throw new Error("Git is required to create a project.");
+    }
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message === "Git is required to create a project."
+    ) {
+      throw error;
+    }
+    throw new Error("Git is required to create a project.");
+  }
+}
+
+async function valueOrAsk(
+  given: string | undefined,
+  label: string,
+  fallback: string,
+  ask: Ask,
+) {
+  if (typeof given === "string" && given.trim() !== "") {
+    return given.trim();
+  }
+  const answered = (await ask(label, fallback)).trim();
+  return answered === "" ? fallback : answered;
+}
+
+function routeFolder(value: string, label: string) {
+  const cleaned = value
+    .trim()
+    .replaceAll("\\", "/")
+    .replace(/^\.\//, "")
+    .replace(/\/+$/, "");
+  const parts = cleaned.split("/");
+  if (
+    cleaned === "" ||
+    cleaned === "." ||
+    path.isAbsolute(value.trim()) ||
+    /^[A-Za-z]:/.test(value.trim()) ||
+    parts.some((part) => part.length === 0 || part === "..")
+  ) {
+    throw new Error(`${label} must be a path inside the project.`);
+  }
+  return cleaned;
+}
+
+async function readKejaPackage(packageRoot: string) {
+  const source = await readFile(path.join(packageRoot, "package.json"), "utf8");
+  const parsed = JSON.parse(source) as {
+    version?: unknown;
+    name?: unknown;
+    publishConfig?: { registry?: unknown };
+  };
+  if (typeof parsed.version !== "string" || parsed.version.trim() === "") {
+    throw new Error("Keja package.json is missing a version.");
+  }
+  const name =
+    typeof parsed.name === "string" && parsed.name.trim() !== ""
+      ? parsed.name.trim()
+      : "@veducio/keja";
+  const registry =
+    typeof parsed.publishConfig?.registry === "string"
+      ? parsed.publishConfig.registry
+      : "";
+  return { version: parsed.version.trim(), name, registry };
+}
+
+function usesGitHubPackages(keja: { name: string; registry: string }) {
+  return (
+    keja.name.startsWith("@veducio/") &&
+    !keja.registry.includes("registry.npmjs.org")
+  );
+}
+
+function sourceFor(name: string, source: string) {
+  return source.replaceAll("@veducio/keja", name);
+}
+
+function configSource(publicDir: string, serviceDir: string) {
+  return `import { defineConfig } from "@veducio/keja";
+
+export default defineConfig({
+  public_path: ${JSON.stringify(publicDir)},
+  service_path: ${JSON.stringify(serviceDir)},
+  db: { enabled: true },
+});
+`;
+}
+
+async function writeRoute(
+  destination: string,
+  folder: string,
+  file: string,
+  source: string,
+) {
+  const directory = path.join(destination, ...folder.split("/"));
+  await mkdir(directory, { recursive: true });
+  await writeFile(path.join(directory, file), source);
+}
+
+function fileUrl(url: URL) {
+  return fileURLToPath(url);
+}

package/src/cli/migrate-project.ts

@@ -0,0 +1,31 @@
+import { migrateDatabase } from "../db/postgres.ts";
+import { DependencyNotMet } from "../errors/framework-errors.ts";
+import { loadConfig } from "../project/config.ts";
+import { printDatabase } from "./banner.ts";
+import { formatProjectFailure, readProjectFailure } from "./run-project.ts";
+
+export async function runMigrate(root = process.cwd()) {
+  try {
+    const project = await loadConfig(root);
+    if (!project.database.enabled) {
+      throw new DependencyNotMet("migrate", "db");
+    }
+    printDatabase(
+      await migrateDatabase(
+        project.database.migrations,
+        Bun.env.DATABASE_URL ?? "",
+      ),
+    );
+  } catch (error) {
+    console.error(
+      formatProjectFailure(readProjectFailure(error), {
+        wait: false,
+        color: process.stderr.isTTY === true,
+      }),
+    );
+    process.exitCode = 1;
+  }
+  if (process.exitCode === 1) {
+    process.exit(1);
+  }
+}

package/src/cli/run-project.test.ts

@@ -0,0 +1,50 @@
+import { Chalk } from "chalk";
+import { describe, expect, it } from "vitest";
+import { projectError } from "../errors/framework-errors.ts";
+import { formatProjectFailure, readProjectFailure } from "./run-project.ts";
+
+const unknownVersion = readProjectFailure(
+  projectError("unknownRouteVersion", "GET /posts uses unknown version v12"),
+);
+
+describe("formatProjectFailure", () => {
+  it("prints the scope, code, and name, then waits in dev", () => {
+    expect(formatProjectFailure(unknownVersion, { wait: true })).toBe(
+      [
+        "",
+        "   ERROR  Project  2001 UnknownRouteVersion",
+        "    GET /posts uses unknown version v12",
+        "    A route uses a version this project does not define.",
+        "    Add the version to keja.versioning.ts, or change the route version.",
+        "",
+        "  waiting for changes",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  it("prints the project error without waiting for start", () => {
+    expect(formatProjectFailure(unknownVersion, { wait: false })).toBe(
+      [
+        "",
+        "   ERROR  Project  2001 UnknownRouteVersion",
+        "    GET /posts uses unknown version v12",
+        "    A route uses a version this project does not define.",
+        "    Add the version to keja.versioning.ts, or change the route version.",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  it("colors the badge, scope, code, and name", () => {
+    const style = new Chalk({ level: 1 });
+    const printed = formatProjectFailure(unknownVersion, {
+      wait: true,
+      color: true,
+    });
+    expect(printed).toContain(style.bgRed.white.bold(" ERROR "));
+    expect(printed).toContain(style.bold("Project"));
+    expect(printed).toContain(style.dim("2001"));
+    expect(printed).toContain(style.bold("UnknownRouteVersion"));
+  });
+});

package/src/cli/run-project.ts

@@ -0,0 +1,93 @@
+import { Chalk } from "chalk";
+import { ProjectError } from "../errors/framework-errors.ts";
+import { listen } from "../server/index.ts";
+import {
+  printAddresses,
+  printDatabase,
+  printIdentity,
+  printProjectPaths,
+  printProjectReady,
+} from "./banner.ts";
+
+export type ProjectFailure = {
+  scope: string;
+  code?: number;
+  name?: string;
+  detail: string;
+  description?: string;
+  tip?: string;
+};
+
+export function printServers(servers: Awaited<ReturnType<typeof listen>>) {
+  printProjectPaths(servers.paths);
+  printIdentity(
+    servers.identity,
+    servers.argus.enabled ? servers.argus : null,
+    servers.vault.enabled
+      ? { address: servers.vault.address, mount: servers.vault.mount }
+      : null,
+  );
+  printDatabase(servers.database);
+  printAddresses(
+    `http://${servers.publicServer.hostname}:${servers.publicServer.port}`,
+    `http://${servers.serviceServer.hostname}:${servers.serviceServer.port}`,
+  );
+  printProjectReady();
+}
+
+export async function runProject(options?: { wait?: boolean }) {
+  try {
+    printServers(await listen());
+  } catch (error) {
+    console.error(
+      formatProjectFailure(readProjectFailure(error), {
+        wait: options?.wait === true,
+        color: process.stderr.isTTY === true,
+      }),
+    );
+    if (options?.wait) {
+      await new Promise(() => {});
+      return;
+    }
+    process.exit(1);
+  }
+}
+
+export function readProjectFailure(error: unknown): ProjectFailure {
+  if (error instanceof ProjectError) {
+    return {
+      scope: error.scope,
+      code: error.code,
+      name: error.errorName,
+      detail: error.message,
+      description: error.description,
+      tip: error.tip,
+    };
+  }
+  return {
+    scope: "Project",
+    detail: error instanceof Error ? error.message : "Failed to start",
+  };
+}
+
+export function formatProjectFailure(
+  failure: ProjectFailure,
+  options: { wait: boolean; color?: boolean },
+) {
+  const style = new Chalk({ level: options.color ? 1 : 0 });
+  const badge = style.bgRed.white.bold(" ERROR ");
+  const identity =
+    failure.code !== undefined && failure.name
+      ? `  ${style.dim(String(failure.code))} ${style.bold(failure.name)}`
+      : "";
+  const details = [failure.detail, failure.description, failure.tip]
+    .filter((line) => line !== undefined)
+    .join("\n")
+    .split("\n")
+    .map((line) => `    ${line}`)
+    .join("\n");
+  const waiting = options.wait
+    ? `\n\n  ${style.dim("waiting for changes")}\n`
+    : "\n";
+  return `\n  ${badge} ${style.bold(failure.scope)}${identity}\n${details}${waiting}`;
+}

package/src/cli/seed-project.ts

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { DBCall, setDatabase } from "../db/client.ts";
+import { connectDatabase } from "../db/postgres.ts";
+import { DependencyNotMet } from "../errors/framework-errors.ts";
+import { loadConfig } from "../project/config.ts";
+import { applySeeder } from "../seed/apply.ts";
+import { loadSeeders } from "../seed/load.ts";
+import { formatSeed } from "../seed/report.ts";
+import { formatProjectFailure, readProjectFailure } from "./run-project.ts";
+
+export async function runSeed(root = process.cwd()) {
+  let opened = false;
+  try {
+    const project = await loadConfig(root);
+    if (!project.database.enabled) {
+      throw new DependencyNotMet("seed", "db");
+    }
+    await connectDatabase(Bun.env.DATABASE_URL ?? "");
+    opened = true;
+    const seeders = await loadSeeders(path.join(root, "seed"));
+    const results = [];
+    for (const seeder of seeders) {
+      results.push({
+        table: seeder.table,
+        inserted: await applySeeder(seeder),
+      });
+    }
+    console.log(formatSeed(results, process.stdout.isTTY === true));
+  } catch (error) {
+    console.error(
+      formatProjectFailure(readProjectFailure(error), {
+        wait: false,
+        color: process.stderr.isTTY === true,
+      }),
+    );
+    process.exitCode = 1;
+  } finally {
+    if (opened) {
+      await DBCall.close();
+      setDatabase(null);
+    }
+  }
+  if (process.exitCode === 1) {
+    process.exit(1);
+  }
+}

package/src/db/client.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { DBCall, setDatabase } from "./client.ts";
+
+describe("DBCall", () => {
+  it("forwards queries to the connected client", async () => {
+    const calls: unknown[][] = [];
+    const client = Object.assign(
+      (...args: unknown[]) => {
+        calls.push(args);
+        return ["ok"];
+      },
+      {
+        close() {
+          return "closed";
+        },
+      },
+    );
+    setDatabase(client as never);
+    try {
+      expect(await DBCall`select 1`).toEqual(["ok"]);
+      expect(calls).toHaveLength(1);
+      expect(DBCall.close()).toBe("closed");
+    } finally {
+      setDatabase(null);
+    }
+  });
+
+  it("rejects an insert that is not an owned object", async () => {
+    const calls: unknown[][] = [];
+    setDatabase(((...args: unknown[]) => {
+      calls.push(args);
+      return [];
+    }) as never);
+    try {
+      expect(() => DBCall`insert into notes ${{ message: "hi" }}`).toThrow(
+        "OwnedObjects _id must be a typeid",
+      );
+      expect(calls).toHaveLength(0);
+      expect(await DBCall`select * from notes`).toEqual([]);
+    } finally {
+      setDatabase(null);
+    }
+  });
+
+  it("fails when the database is disabled", () => {
+    setDatabase(null);
+    expect(() => DBCall`select 1`).toThrow("DBCall requires db");
+  });
+});