create-katajs 0.1.0

package/dist/templates/api/README.md

@@ -0,0 +1,95 @@
+# {{PROJECT_NAME}}
+
+Scaffolded with [`create-katajs`](https://github.com/yasr/katajs).
+
+## Setup
+
+```sh
+pnpm install
+```
+
+Spin up a local Postgres for development (Docker example):
+
+```sh
+docker run -d --name {{PROJECT_NAME}}-pg \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB={{PROJECT_NAME}}_dev \
+  -p 5432:5432 \
+  postgres:16
+```
+
+Copy `.dev.vars.example` to `.dev.vars` (for `wrangler dev`).
+
+## Develop
+
+```sh
+pnpm db:generate   # generate Drizzle migrations after schema changes
+pnpm db:migrate    # apply migrations to your dev Postgres
+pnpm dev           # wrangler dev
+```
+
+`wrangler dev` connects directly to the Postgres URL in `.dev.vars` (or
+`localConnectionString` in `wrangler.jsonc`). Hyperdrive's pooling/caching
+applies on Cloudflare's edge in production; locally you get a transparent
+passthrough.
+
+## Module graph
+
+```sh
+pnpm graph
+# writes graph.html — open in any browser
+```
+
+Generates a self-contained HTML page showing your modules, their dependency
+edges, and a flat routes table. Useful for reviewing your app's structure or
+embedding in PR descriptions. Regenerate after structural changes.
+
+## Type-safe clients with Hono RPC
+
+`AppType` is exported from `src/app.ts`. Consume it from another package:
+
+```ts
+import { hc } from 'hono/client';
+import type { AppType } from '<your-api-package>';
+
+const client = hc<AppType>('https://api.example.com');
+const res = await client.posts.$post({ json: { title: 'Hi', body: 'Hello' } });
+```
+
+## Adding tests
+
+If you add unit tests with synthetic services (e.g. test fixtures that
+augment `@katajs/core`'s `Registry` with throwaway service keys), keep them
+in their own tsconfig so test-only augmentations don't pollute editor
+autocomplete in `src/`. TypeScript module augmentations are global per
+program — splitting the program is the only fix.
+
+Pattern:
+
+```jsonc
+// tsconfig.json — for editor + `pnpm typecheck`
+{ "include": ["src/**/*"] }
+
+// tsconfig.test.json — for `pnpm test:typecheck`
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/**/*", "test/**/*"]
+}
+```
+
+Run both in your `typecheck` script:
+```json
+"typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json"
+```
+
+## Deploy
+
+CI pushes to `main` deploy via the included workflow. Locally:
+
+```sh
+pnpm deploy
+```
+
+You'll need `CLOUDFLARE_API_TOKEN` in CI secrets and a real Hyperdrive
+configuration before the first deploy. See
+[Cloudflare Hyperdrive docs](https://developers.cloudflare.com/hyperdrive).

package/dist/templates/api/_dev.vars.example

@@ -0,0 +1,3 @@
+# Local connection string used by Hyperdrive in `wrangler dev`.
+# Wrangler reads this env var if set; it overrides `localConnectionString` in wrangler.jsonc.
+CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://postgres:postgres@localhost:5432/{{PROJECT_NAME}}_dev"

package/dist/templates/api/_gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+.wrangler/
+.dev.vars
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+coverage/
+*.tsbuildinfo

package/dist/templates/api/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+  dbCredentials: {
+    url: process.env.DATABASE_URL ?? 'postgres://postgres:postgres@localhost:5432/{{PROJECT_NAME}}_dev',
+  },
+});

package/dist/templates/api/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "graph": "tsx scripts/graph.ts",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hono/zod-validator": "^0.4.1",
+    "@katajs/core": "^0.1.0",
+    "@katajs/drizzle": "^0.1.0",
+    "drizzle-orm": "^0.36.4",
+    "hono": "^4.6.10",
+    "pg": "^8.13.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241112.0",
+    "@types/node": "^22.9.0",
+    "@types/pg": "^8.11.10",
+    "drizzle-kit": "^0.28.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "wrangler": "^3.86.0"
+  }
+}

package/dist/templates/api/scripts/graph.ts

@@ -0,0 +1,19 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inspectModules } from '@katajs/core';
+
+import { modules } from './modules';
+
+const here = fileURLToPath(new URL('.', import.meta.url));
+const out = resolve(here, '..', 'graph.html');
+
+const insp = inspectModules(modules);
+writeFileSync(out, insp.html({ title: '{{PROJECT_NAME}} — module graph' }));
+
+// eslint-disable-next-line no-console
+console.log(`✓ wrote ${out}`);
+// eslint-disable-next-line no-console
+console.log(
+  `  ${insp.modules.length} modules • ${insp.edges.length} dependencies • ${insp.routes.length} routes`,
+);

package/dist/templates/api/scripts/modules.ts

@@ -0,0 +1,7 @@
+import { postsModule } from '../src/modules/posts/index';
+// katajs:graph-imports
+
+export const modules = [
+  postsModule,
+  // katajs:graph-modules
+];

package/dist/templates/api/src/app.ts

@@ -0,0 +1,39 @@
+import { createApp, type RequestVariables } from '@katajs/core';
+import { drizzleAdapter } from '@katajs/drizzle';
+import * as schema from './db/schema';
+
+import { postsModule } from './modules/posts/index';
+// katajs:module-imports
+
+export type Bindings = {
+  HYPERDRIVE: Hyperdrive;
+};
+
+export type AppEnv = {
+  Bindings: Bindings;
+  Variables: RequestVariables;
+};
+
+const { app, queue } = createApp({
+  bindings: {} as Bindings,
+  db: drizzleAdapter({ schema }),
+  modules: [
+    postsModule,
+    // katajs:modules
+  ],
+  // Producer manifest. Each entry surfaces a typed wrapper at
+  // c.var.queues.<name>.send(body), validated against the schema.
+  queues: {
+    // katajs:queues
+  },
+  // Define your HTTP surface here. Add `.get()` / `.post()` for ad-hoc routes
+  // (health checks, webhooks) and `.route(prefix, module.routes)` per module.
+  routes: (base) =>
+    base
+      .route(postsModule.prefix, postsModule.routes),
+  // katajs:routes
+});
+
+export { queue };
+export default app;
+export type AppType = typeof app;

package/dist/templates/api/src/db/schema.ts

@@ -0,0 +1,11 @@
+import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+
+export const posts = pgTable('posts', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  title: text('title').notNull(),
+  body: text('body').notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export type Post = typeof posts.$inferSelect;
+export type NewPost = typeof posts.$inferInsert;

package/dist/templates/api/src/index.ts

@@ -0,0 +1,6 @@
+import app, { queue } from './app';
+
+// Worker default export. `queue` is undefined when no module declares a
+// `consumer:` field — Cloudflare Workers handles either case fine. When
+// you add your first consumer, no change to this file is needed.
+export default { fetch: app.fetch, queue };

package/dist/templates/api/src/modules/posts/index.ts

@@ -0,0 +1,31 @@
+import { defineModule } from '@katajs/core';
+import { makePostRepository, type PostRepository } from './posts.repository';
+import { makePostService, type PostsService } from './posts.service';
+// katajs:module-service-imports
+import { postsRoutes } from './posts.routes';
+
+export const postsModule = defineModule({
+  name: 'posts',
+  provides: {
+    postRepository: (c): PostRepository => makePostRepository(c.db),
+    postService: (c): PostsService => makePostService(c),
+    // katajs:module-provides
+  },
+  requires: [] as const,
+  routes: postsRoutes,
+  prefix: '/posts',
+  // katajs:module-consumer
+});
+
+/**
+ * Services this module contributes to the container's `Registry`. Compose it
+ * in `app.ts` via `interface Registry extends PostsRegistry {}`. Adding a new
+ * module is one extra `extends` clause — no key-by-key bookkeeping.
+ */
+export type PostsRegistry = {
+  postRepository: PostRepository;
+  postService: PostsService;
+  // katajs:module-registry
+};
+
+export type { PostRepository, PostsService };

package/dist/templates/api/src/modules/posts/posts.errors.ts

@@ -0,0 +1,15 @@
+import { AppError } from '@katajs/core';
+
+export class PostNotFoundError extends AppError {
+  override readonly status = 404;
+  override readonly code = 'post_not_found';
+  override readonly publicMessage = 'Post not found';
+
+  constructor(public readonly postId: string) {
+    super(`Post ${postId} not found`);
+  }
+
+  override get publicPayload() {
+    return { postId: this.postId };
+  }
+}

package/dist/templates/api/src/modules/posts/posts.repository.ts

@@ -0,0 +1,22 @@
+import { eq } from 'drizzle-orm';
+import type { DrizzleClientOrTx } from '@katajs/drizzle';
+import { posts, type NewPost, type Post } from '../../db/schema';
+import * as schema from '../../db/schema';
+
+type Schema = typeof schema;
+
+export function makePostRepository(dbOrTx: DrizzleClientOrTx<Schema>) {
+  return {
+    async findById(id: string): Promise<Post | undefined> {
+      const rows = await dbOrTx.select().from(posts).where(eq(posts.id, id)).limit(1);
+      return rows[0];
+    },
+    async insert(input: NewPost): Promise<Post> {
+      const [row] = await dbOrTx.insert(posts).values(input).returning();
+      if (!row) throw new Error('insert returned no row');
+      return row;
+    },
+  };
+}
+
+export type PostRepository = ReturnType<typeof makePostRepository>;

package/dist/templates/api/src/modules/posts/posts.routes.ts

@@ -0,0 +1,20 @@
+import { Hono } from 'hono';
+import { validate } from '@katajs/core';
+import type { AppEnv } from '../../app';
+import { CreatePostSchema, PostIdParam } from './posts.schema';
+
+export const postsRoutes = new Hono<AppEnv>()
+  .get('/:id', ...validate({ param: PostIdParam }), async (c) => {
+    const { id } = c.req.valid('param');
+    const service = c.var.resolve('postService');
+    const post = await service.getById(id);
+    return c.json({ post });
+  })
+  .post('/', ...validate({ body: CreatePostSchema }), async (c) => {
+    const input = c.req.valid('json');
+    const service = c.var.resolve('postService');
+    const post = await service.create(input);
+    return c.json({ post }, 201);
+  })
+  // katajs:module-routes
+  ;

package/dist/templates/api/src/modules/posts/posts.schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const CreatePostSchema = z.object({
+  title: z.string().min(1).max(200),
+  body: z.string().min(1).max(10_000),
+});
+export type CreatePostInput = z.infer<typeof CreatePostSchema>;
+
+export const PostIdParam = z.object({
+  id: z.string().uuid(),
+});
+export type PostIdParamInput = z.infer<typeof PostIdParam>;

package/dist/templates/api/src/modules/posts/posts.service.ts

@@ -0,0 +1,26 @@
+import type { RequestContainer } from '@katajs/core';
+import { PostNotFoundError } from './posts.errors';
+import type { CreatePostInput } from './posts.schema';
+import type { Post } from '../../db/schema';
+
+export type PostsService = {
+  getById(id: string): Promise<Post>;
+  create(input: CreatePostInput): Promise<Post>;
+};
+
+export function makePostService(c: RequestContainer): PostsService {
+  return {
+    async getById(id) {
+      const repo = c.resolve('postRepository');
+      const post = await repo.findById(id);
+      if (!post) throw new PostNotFoundError(id);
+      return post;
+    },
+    async create(input) {
+      return c.withTransaction(async (tx) => {
+        const repo = tx.resolve('postRepository');
+        return repo.insert(input);
+      });
+    },
+  };
+}

package/dist/templates/api/src/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Module augmentations for `@katajs/core`. Picked up automatically by
+ * tsconfig's `include` glob — no runtime import needed. Co-locate everything
+ * that teaches the framework about this app's concrete types here.
+ *
+ * The `katajs:registry-imports` and `katajs:registry` markers below are used
+ * by `katajs add module` to insert new module registry entries automatically.
+ * If you remove or relocate them, future `add module` runs will print the
+ * snippet for you to paste manually.
+ */
+import type { DrizzleClient } from '@katajs/drizzle';
+import type * as schema from './db/schema';
+import type { Bindings } from './app';
+
+import type { PostsRegistry } from './modules/posts/index';
+// katajs:registry-imports
+
+declare module '@katajs/core' {
+  interface AppDb extends DrizzleClient<typeof schema> {}
+  interface AppEnv extends Bindings {}
+  interface Registry
+    extends PostsRegistry
+    // katajs:registry
+  {}
+
+  // Typed producer queues. Each entry maps a queue name to its body type so
+  // c.var.queues.<name>.send(body) is fully typed.
+  interface QueuesRegistry {
+    // katajs:queues-registry
+  }
+}

package/dist/templates/api/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2023"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noEmit": true,
+    "types": ["@cloudflare/workers-types", "node"]
+  },
+  "include": ["src/**/*", "scripts/**/*", "drizzle.config.ts"]
+}

package/dist/templates/api/wrangler.jsonc

@@ -0,0 +1,35 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "{{PROJECT_NAME}}",
+  "main": "src/index.ts",
+  "compatibility_date": "{{TODAY_ISO}}",
+  "compatibility_flags": ["nodejs_compat"],
+  "observability": { "enabled": true },
+  "hyperdrive": [
+    {
+      "binding": "HYPERDRIVE",
+      "id": "<your-hyperdrive-id>",
+      "localConnectionString": "postgres://postgres:postgres@localhost:5432/{{PROJECT_NAME}}_dev"
+    }
+  ]
+
+  // Cloudflare Queues bindings. Uncomment + adjust when a module in this app
+  // declares a `consumer:` field (see docs/concepts/queues.md). Both halves
+  // are needed: producers (to send) and consumers (to receive).
+  //
+  // "queues": {
+  //   "producers": [
+  //     { "binding": "ORDER_QUEUE", "queue": "orders" },
+  //     { "binding": "ORDER_DLQ",   "queue": "orders-dlq" }
+  //   ],
+  //   "consumers": [
+  //     {
+  //       "queue": "orders",
+  //       "max_batch_size": 100,
+  //       "max_batch_timeout": 30,
+  //       "max_retries": 3,
+  //       "dead_letter_queue": "orders-dlq"
+  //     }
+  //   ]
+  // }
+}

package/dist/templates/auth-snippets/api/src/db/auth-schema.ts

@@ -0,0 +1,53 @@
+import { boolean, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+
+/**
+ * Better Auth tables. The exact column shape is dictated by Better Auth's
+ * Drizzle adapter — keep these in sync with `better-auth` releases. Run
+ * `pnpm db:generate` after changes.
+ */
+export const user = pgTable('user', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email').notNull().unique(),
+  emailVerified: boolean('email_verified').notNull().default(false),
+  image: text('image'),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export const session = pgTable('session', {
+  id: text('id').primaryKey(),
+  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+  token: text('token').notNull().unique(),
+  ipAddress: text('ip_address'),
+  userAgent: text('user_agent'),
+  userId: text('user_id')
+    .notNull()
+    .references(() => user.id, { onDelete: 'cascade' }),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export const account = pgTable('account', {
+  id: text('id').primaryKey(),
+  accountId: text('account_id').notNull(),
+  providerId: text('provider_id').notNull(),
+  userId: text('user_id')
+    .notNull()
+    .references(() => user.id, { onDelete: 'cascade' }),
+  accessToken: text('access_token'),
+  refreshToken: text('refresh_token'),
+  idToken: text('id_token'),
+  password: text('password'),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export const verification = pgTable('verification', {
+  id: text('id').primaryKey(),
+  identifier: text('identifier').notNull(),
+  value: text('value').notNull(),
+  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+});

package/dist/templates/auth-snippets/api/src/modules/auth/auth.config.ts

@@ -0,0 +1,30 @@
+import { betterAuth } from 'better-auth';
+import { drizzleAdapter as betterAuthDrizzleAdapter } from 'better-auth/adapters/drizzle';
+import type { DrizzleClient } from '@katajs/drizzle';
+import * as schema from '../../db/schema';
+
+/**
+ * Build a Better Auth instance bound to the request-scoped Drizzle client.
+ *
+ * Note: Better Auth has its *own* `drizzleAdapter` (imported as
+ * `betterAuthDrizzleAdapter`) — distinct from `@katajs/drizzle`'s
+ * `drizzleAdapter`. The naming overlap is unavoidable.
+ */
+export function makeAuth(db: DrizzleClient<typeof schema>, env: { BETTER_AUTH_SECRET?: string; BETTER_AUTH_URL?: string }) {
+  return betterAuth({
+    database: betterAuthDrizzleAdapter(db, {
+      provider: 'pg',
+      schema: {
+        user: schema.user,
+        session: schema.session,
+        account: schema.account,
+        verification: schema.verification,
+      },
+    }),
+    secret: env.BETTER_AUTH_SECRET,
+    baseURL: env.BETTER_AUTH_URL,
+    emailAndPassword: { enabled: true },
+  });
+}
+
+export type AuthInstance = ReturnType<typeof makeAuth>;

package/dist/templates/auth-snippets/api/src/modules/auth/auth.errors.ts

@@ -0,0 +1,10 @@
+import { AppError } from '@katajs/core';
+
+export class UnauthorizedError extends AppError {
+  override readonly status = 401;
+  override readonly code = 'unauthorized';
+  override readonly publicMessage = 'Authentication required';
+  constructor() {
+    super('Unauthorized');
+  }
+}

package/dist/templates/auth-snippets/api/src/modules/auth/auth.middleware.ts

@@ -0,0 +1,37 @@
+import { defineMiddleware } from '@katajs/core';
+import type { AuthInstance } from './auth.config';
+import { UnauthorizedError } from './auth.errors';
+
+type SessionUser = {
+  id: string;
+  email: string;
+  name: string;
+};
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    user: SessionUser;
+  }
+}
+
+/**
+ * Attach the current user (if any) to `c.var.user`. Routes that require auth
+ * should use `requireAuthMiddleware` instead.
+ */
+export const attachUserMiddleware = (auth: AuthInstance) =>
+  defineMiddleware(async (c, next) => {
+    const session = await auth.api.getSession({ headers: c.req.raw.headers });
+    if (session?.user) {
+      c.set('user', session.user as SessionUser);
+    }
+    await next();
+  });
+
+/** Require an authenticated user — throws `UnauthorizedError` if absent. */
+export const requireAuthMiddleware = (auth: AuthInstance) =>
+  defineMiddleware(async (c, next) => {
+    const session = await auth.api.getSession({ headers: c.req.raw.headers });
+    if (!session?.user) throw new UnauthorizedError();
+    c.set('user', session.user as SessionUser);
+    await next();
+  });

package/dist/templates/auth-snippets/api/src/modules/auth/auth.routes.ts

@@ -0,0 +1,7 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../../app';
+
+export const authRoutes = new Hono<AppEnv>().all('/*', async (c) => {
+  const auth = c.var.container.resolve('authInstance');
+  return auth.handler(c.req.raw);
+});

package/dist/templates/auth-snippets/api/src/modules/auth/index.ts

@@ -0,0 +1,28 @@
+import { defineModule } from '@katajs/core';
+import * as schema from '../../db/schema';
+import type { DrizzleClient } from '@katajs/drizzle';
+import { makeAuth, type AuthInstance } from './auth.config';
+import { authRoutes } from './auth.routes';
+
+export const authModule = defineModule({
+  name: 'auth',
+  provides: {
+    authInstance: (c): AuthInstance =>
+      makeAuth(
+        c.db as DrizzleClient<typeof schema>,
+        c.env as { BETTER_AUTH_SECRET?: string; BETTER_AUTH_URL?: string },
+      ),
+  },
+  requires: [] as const,
+  routes: authRoutes,
+  prefix: '/auth',
+});
+
+/** Services this module contributes to the container's `Registry`. */
+export type AuthRegistry = {
+  authInstance: AuthInstance;
+};
+
+export type { AuthInstance } from './auth.config';
+export { UnauthorizedError } from './auth.errors';
+export { attachUserMiddleware, requireAuthMiddleware } from './auth.middleware';

package/dist/templates/auth-snippets/monorepo/apps/api/src/modules/auth/auth.errors.ts

@@ -0,0 +1,10 @@
+import { AppError } from '@katajs/core';
+
+export class UnauthorizedError extends AppError {
+  override readonly status = 401;
+  override readonly code = 'unauthorized';
+  override readonly publicMessage = 'Authentication required';
+  constructor() {
+    super('Unauthorized');
+  }
+}