@katajs/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaseer A. Okino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @katajs/cli
+
+Project commands for [katajs](https://github.com/ookino/katajs) apps. Install as a devDependency in your scaffolded project (it's already there if you used `pnpm create katajs`).
+
+```bash
+pnpm add -D @katajs/cli
+```
+
+## Commands
+
+### `katajs add module <name>`
+
+Scaffolds a new module: `src/modules/<name>/` with the standard 5 files, plus mutations to wire it into the app.
+
+```bash
+pnpm katajs add module comments
+```
+
+Generates:
+- `src/modules/comments/index.ts` — `defineModule` call + `CommentsRegistry` type export
+- `src/modules/comments/comments.service.ts` — service factory with a `ping()` example method
+- `src/modules/comments/comments.routes.ts` — Hono routes with one example `GET /`
+- `src/modules/comments/comments.schema.ts` — Zod schema starter
+- `src/modules/comments/comments.errors.ts` — `AppError` subclass starter
+
+Mutates:
+- `src/types.d.ts` — adds `CommentsRegistry` import + extends entry
+- `src/app.ts` — adds `commentsModule` import, modules-array entry, and route mount
+- `scripts/graph.ts` — adds `commentsModule` to the graph script (if present)
+
+The mutations rely on anchor comments (`// katajs:registry`, `// katajs:modules`, `// katajs:routes`, etc.) that ship in the scaffolder templates. If you've removed them, the command prints the snippet for manual paste instead of failing.
+
+#### Naming
+
+Names are normalized into kebab-case (directory), camelCase (variable), PascalCase (type), and snake_case (error code):
+
+```bash
+katajs add module user-profile
+# directory: src/modules/user-profile/
+# variable:  userProfileModule, userProfileService
+# type:      UserProfileService, UserProfileRegistry, UserProfileNotFoundError
+# code:      'user_profile_not_found'
+```
+
+Names must start with a letter and contain only letters, digits, and hyphens.
+
+### `katajs add service <name> --in <module>`
+
+Adds a single service to an existing module.
+
+```bash
+pnpm katajs add service featured --in posts
+```
+
+Generates `src/modules/posts/featured.service.ts` and wires it into the module's `index.ts`:
+
+- New `import { makeFeaturedService, type FeaturedService } from './featured.service';` line
+- New `featuredService: (c) => makeFeaturedService(c),` entry in `provides`
+- New `featuredService: FeaturedService;` entry in the `PostsRegistry` slice
+
+The mutations target the `// katajs:module-service-imports`, `// katajs:module-provides`, and `// katajs:module-registry` anchors that ship in scaffolded modules.
+
+### `katajs add route <method> <path> --in <module>`
+
+Appends a new route handler to a module's `<module>.routes.ts` chain.
+
+```bash
+pnpm katajs add route post /comments --in posts
+```
+
+Methods: `get`, `post`, `put`, `patch`, `delete`, `options`, `head`. Path must start with `/`. The handler is inserted before the `// katajs:module-routes` anchor with a `// TODO: implement <METHOD> <path>` body.
+
+### `katajs add queue <name> --in <module>`
+
+Adds a queue consumer to an existing module — generates the consumer file, wires it into the module via anchors, and prints wrangler.jsonc + Bindings type snippets for manual paste.
+
+```bash
+pnpm katajs add queue orders --in orders
+pnpm katajs add queue order-events --in posts --dlq ORDER_EVENTS_DLQ
+pnpm katajs add queue analytics --in analytics --batch
+```
+
+Flags:
+
+- `--in <module>` *(required)* — target module
+- `--binding <BINDING>` *(optional)* — wrangler binding name. Default: `<NAME>_QUEUE` (kebab → SCREAMING_SNAKE)
+- `--dlq <DLQ_BINDING>` *(optional)* — dead-letter queue binding. When set, the generated consumer adds `dlq:` and `maxRetries: 5`
+- `--batch` *(optional flag)* — generate `handleBatch` instead of `handle`
+
+Generates `src/modules/<module>/<name>.consumer.ts` using `defineConsumer` from `@katajs/core` (drives full contextual typing on the handler — `message.body` is inferred from the schema, no `any`). Mutates `<module>/index.ts` to import the consumer and add it to `defineModule({ ..., consumer: <name>Consumer })` via the `// katajs:module-service-imports` and `// katajs:module-consumer` anchors.
+
+Two manual paste steps the CLI doesn't auto-mutate (because both touch user-customizable territory):
+
+1. **wrangler.jsonc** — add the producer, consumer, and (if `--dlq`) DLQ producer entries to the `queues` block.
+2. **`Bindings` type** in `src/app.ts` — add `<BINDING>: Queue<XxxEvent>` so `c.env.<BINDING>.send(...)` typechecks.
+
+Both snippets are printed by the command, ready to paste.
+
+### Coming in later versions
+
+- `katajs add migration <name>`
+- `katajs add cron <name>`
+- `katajs add do <name>`
+- `katajs upgrade`
+
+## How it works
+
+The CLI walks up from your current working directory looking for a `package.json` that declares `@katajs/core`. If found, that's your project root and `src/` is where files land. Run `katajs add module foo` from anywhere inside your project — the CLI finds the right place.
+
+## License
+
+[MIT](./LICENSE) © Yaseer A. Okino

package/dist/index.js

@@ -0,0 +1,782 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import cac from "cac";
+import * as p5 from "@clack/prompts";
+import { red as red2 } from "kolorist";
+
+// src/commands/add-module.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  readdirSync,
+  writeFileSync
+} from "fs";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+import * as p from "@clack/prompts";
+import { cyan, dim, green, red, yellow } from "kolorist";
+
+// src/codemod.ts
+var AnchorMissingError = class extends Error {
+  constructor(anchor) {
+    super(`Anchor "// katajs:${anchor}" not found`);
+    this.anchor = anchor;
+    this.name = "AnchorMissingError";
+  }
+  anchor;
+};
+function insertBeforeAnchor(content, anchor, lines) {
+  const anchorMatch = new RegExp(`^(\\s*)// katajs:${escapeRe(anchor)}\\s*$`, "m");
+  const m = content.match(anchorMatch);
+  if (!m) throw new AnchorMissingError(anchor);
+  const indent = m[1] ?? "";
+  const arr = Array.isArray(lines) ? lines : [lines];
+  const toInsert = arr.map((l) => indent + l).join("\n");
+  const allPresent = arr.every((l) => content.includes(l.trim()));
+  if (allPresent) return content;
+  return content.replace(anchorMatch, `${toInsert}
+${m[0]}`);
+}
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function appendRouteToChain(content, moduleVar) {
+  const newCallSig = `.route(${moduleVar}.prefix, ${moduleVar}.routes)`;
+  if (content.includes(newCallSig)) return content;
+  const lines = content.split("\n");
+  const anchorIdx = lines.findIndex(
+    (l) => /^\s*\/\/ katajs:routes\s*$/.test(l)
+  );
+  if (anchorIdx === -1) throw new AnchorMissingError("routes");
+  let lastChainIdx = -1;
+  const chainLineRe = /^\s*\.route\(\w+\.prefix,\s*\w+\.routes\)/;
+  for (let i = anchorIdx - 1; i >= Math.max(0, anchorIdx - 25); i--) {
+    if (chainLineRe.test(lines[i] ?? "")) {
+      lastChainIdx = i;
+      break;
+    }
+  }
+  if (lastChainIdx === -1) {
+    throw new Error(
+      "appendRouteToChain: could not locate a `.route(<X>.prefix, <X>.routes)` line above // katajs:routes"
+    );
+  }
+  const lastLine = lines[lastChainIdx];
+  const indent = lastLine.match(/^(\s*)/)?.[1] ?? "      ";
+  lines[lastChainIdx] = lastLine.replace(/,(\s*)$/, "$1");
+  lines.splice(
+    lastChainIdx + 1,
+    0,
+    `${indent}.route(${moduleVar}.prefix, ${moduleVar}.routes),`
+  );
+  return lines.join("\n");
+}
+
+// src/utils/project.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+function findKatajsProject(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  while (true) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      if (declaresKatajs(pkg)) {
+        const srcDir = join(dir, "src");
+        if (!existsSync(srcDir)) {
+          throw new Error(
+            `Found @katajs/core in ${pkgPath}, but no src/ directory. Run from a katajs project root.`
+          );
+        }
+        return { root: dir, srcDir, pkg };
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error(
+        `Not in a katajs project \u2014 couldn't find a package.json with @katajs/core in this directory or any parent.
+Run this command from inside a project created with \`pnpm create katajs\`.`
+      );
+    }
+    dir = parent;
+  }
+}
+function declaresKatajs(pkg) {
+  for (const key of ["dependencies", "devDependencies", "peerDependencies"]) {
+    const deps = pkg[key];
+    if (deps && typeof deps === "object" && "@katajs/core" in deps) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// src/utils/text.ts
+function normalizeName(input) {
+  const cleaned = input.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^[-_]+|[-_]+$/g, "").toLowerCase();
+  if (!cleaned) {
+    throw new Error(`Invalid name: "${input}". Use lowercase letters, digits, and hyphens.`);
+  }
+  if (!/^[a-z]/.test(cleaned)) {
+    throw new Error(`Name must start with a letter: "${input}".`);
+  }
+  const parts = cleaned.split(/[-_]+/).filter(Boolean);
+  const camel = parts[0] + parts.slice(1).map(capitalize).join("");
+  const pascal = parts.map(capitalize).join("");
+  return { kebab: parts.join("-"), pascal, camel };
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// src/commands/add-module.ts
+async function addModule(opts) {
+  const project = findKatajsProject(opts.cwd);
+  const casings = normalizeName(opts.name);
+  const moduleDir = join2(project.srcDir, "modules", casings.kebab);
+  if (existsSync2(moduleDir)) {
+    throw new Error(
+      `Module directory already exists: ${moduleDir}
+Refusing to overwrite. Delete the directory first or pick a different name.`
+    );
+  }
+  generateModuleFiles(moduleDir, casings);
+  const fallbacks = [];
+  applyMutation({
+    file: join2(project.srcDir, "types.d.ts"),
+    fn: (content) => {
+      const c1 = insertBeforeAnchor(
+        content,
+        "registry-imports",
+        `import type { ${casings.pascal}Registry } from './modules/${casings.kebab}/index';`
+      );
+      return insertBeforeAnchor(c1, "registry", `, ${casings.pascal}Registry`);
+    },
+    onFallback: (msg) => fallbacks.push(msg),
+    snippet: () => [
+      `// In ${join2(project.srcDir, "types.d.ts")}:`,
+      `import type { ${casings.pascal}Registry } from './modules/${casings.kebab}/index';`,
+      `// Add to the Registry interface extends list:`,
+      `, ${casings.pascal}Registry`
+    ].join("\n")
+  });
+  applyMutation({
+    file: join2(project.srcDir, "app.ts"),
+    fn: (content) => {
+      const c1 = insertBeforeAnchor(
+        content,
+        "module-imports",
+        `import { ${casings.camel}Module } from './modules/${casings.kebab}/index';`
+      );
+      const c2 = insertBeforeAnchor(c1, "modules", `${casings.camel}Module,`);
+      return appendRouteToChain(c2, `${casings.camel}Module`);
+    },
+    onFallback: (msg) => fallbacks.push(msg),
+    snippet: () => [
+      `// In ${join2(project.srcDir, "app.ts")}:`,
+      `import { ${casings.camel}Module } from './modules/${casings.kebab}/index';`,
+      `// Add to the modules array:`,
+      `${casings.camel}Module,`,
+      `// And in the routes callback chain:`,
+      `.route(${casings.camel}Module.prefix, ${casings.camel}Module.routes)`
+    ].join("\n")
+  });
+  const modulesScript = join2(project.root, "scripts", "modules.ts");
+  const graphScript = join2(project.root, "scripts", "graph.ts");
+  const registryFile = existsSync2(modulesScript) ? modulesScript : existsSync2(graphScript) ? graphScript : null;
+  if (registryFile) {
+    applyMutation({
+      file: registryFile,
+      fn: (content) => {
+        const c1 = insertBeforeAnchor(
+          content,
+          "graph-imports",
+          `import { ${casings.camel}Module } from '../src/modules/${casings.kebab}/index';`
+        );
+        return insertBeforeAnchor(c1, "graph-modules", `${casings.camel}Module,`);
+      },
+      onFallback: (msg) => fallbacks.push(msg),
+      snippet: () => [
+        `// In ${registryFile}:`,
+        `import { ${casings.camel}Module } from '../src/modules/${casings.kebab}/index';`,
+        `// Add to the modules array:`,
+        `${casings.camel}Module,`
+      ].join("\n")
+    });
+  }
+  p.outro(`${green("\u2713")} Created module ${cyan(casings.kebab)}`);
+  console.log(dim("  Files:"));
+  for (const f of [
+    "index.ts",
+    `${casings.kebab}.service.ts`,
+    `${casings.kebab}.routes.ts`,
+    `${casings.kebab}.schema.ts`,
+    `${casings.kebab}.errors.ts`
+  ]) {
+    console.log(dim(`    src/modules/${casings.kebab}/${f}`));
+  }
+  if (fallbacks.length > 0) {
+    console.log("\n" + yellow("  Some files couldn\u2019t be auto-edited."));
+    console.log(yellow("  Paste these snippets manually:\n"));
+    for (const f of fallbacks) {
+      console.log(f + "\n");
+    }
+  }
+}
+function generateModuleFiles(moduleDir, casings) {
+  mkdirSync(moduleDir, { recursive: true });
+  const templatesDir = getTemplatesDir();
+  const files = [
+    ["index.ts", "index.ts"],
+    ["service.ts", `${casings.kebab}.service.ts`],
+    ["routes.ts", `${casings.kebab}.routes.ts`],
+    ["schema.ts", `${casings.kebab}.schema.ts`],
+    ["errors.ts", `${casings.kebab}.errors.ts`]
+  ];
+  for (const [srcName, dstName] of files) {
+    const srcPath = join2(templatesDir, "module", srcName);
+    if (!existsSync2(srcPath)) {
+      throw new Error(`Template file missing: ${srcPath}`);
+    }
+    const content = readFileSync2(srcPath, "utf8");
+    const replaced = applyCasings(content, casings);
+    writeFileSync(join2(moduleDir, dstName), replaced);
+  }
+}
+function applyCasings(content, casings) {
+  return content.replace(/\{\{kebab\}\}/g, casings.kebab).replace(/\{\{Pascal\}\}/g, casings.pascal).replace(/\{\{camel\}\}/g, casings.camel).replace(/\{\{snake\}\}/g, casings.kebab.replace(/-/g, "_"));
+}
+function applyMutation(step) {
+  if (!existsSync2(step.file)) {
+    step.onFallback(red(`Skipped ${step.file} (not found)
+${step.snippet()}`));
+    return;
+  }
+  const before = readFileSync2(step.file, "utf8");
+  try {
+    const after = step.fn(before);
+    if (after !== before) {
+      writeFileSync(step.file, after);
+    }
+  } catch (err) {
+    if (err instanceof AnchorMissingError) {
+      step.onFallback(
+        yellow(`Anchor "${err.anchor}" missing in ${step.file}.
+${step.snippet()}`)
+      );
+    } else {
+      throw err;
+    }
+  }
+}
+function getTemplatesDir() {
+  const here = dirname2(fileURLToPath(import.meta.url));
+  const candidates = [
+    join2(here, "templates"),
+    join2(here, "..", "src", "templates"),
+    join2(here, "..", "..", "src", "templates")
+  ];
+  for (const c of candidates) {
+    if (existsSync2(c)) {
+      try {
+        const sub = readdirSync(c);
+        if (sub.includes("module")) return c;
+      } catch {
+      }
+    }
+  }
+  throw new Error(
+    `Could not locate templates directory. Tried: ${candidates.join(", ")}`
+  );
+}
+
+// src/commands/add-service.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname3, join as join3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import * as p2 from "@clack/prompts";
+import { cyan as cyan2, dim as dim2, green as green2, yellow as yellow2 } from "kolorist";
+async function addService(opts) {
+  const project = findKatajsProject(opts.cwd);
+  const moduleCasings = normalizeName(opts.inModule);
+  const serviceCasings = normalizeName(opts.name);
+  const moduleDir = join3(project.srcDir, "modules", moduleCasings.kebab);
+  if (!existsSync3(moduleDir)) {
+    throw new Error(
+      `Module "${moduleCasings.kebab}" not found at ${moduleDir}. Run \`katajs add module ${moduleCasings.kebab}\` first.`
+    );
+  }
+  const servicePath = join3(moduleDir, `${serviceCasings.kebab}.service.ts`);
+  if (existsSync3(servicePath)) {
+    throw new Error(
+      `Service file already exists: ${servicePath}
+Refusing to overwrite.`
+    );
+  }
+  writeServiceFile(servicePath, serviceCasings);
+  const indexPath = join3(moduleDir, "index.ts");
+  const fallbacks = [];
+  if (!existsSync3(indexPath)) {
+    fallbacks.push(
+      yellow2(`Module index not found: ${indexPath}
+Wire up the new service manually.`)
+    );
+  } else {
+    let content = readFileSync3(indexPath, "utf8");
+    let snippet = "";
+    try {
+      content = insertBeforeAnchor(
+        content,
+        "module-service-imports",
+        `import { make${serviceCasings.pascal}Service, type ${serviceCasings.pascal}Service } from './${serviceCasings.kebab}.service';`
+      );
+    } catch (err) {
+      if (err instanceof AnchorMissingError) {
+        snippet += `import { make${serviceCasings.pascal}Service, type ${serviceCasings.pascal}Service } from './${serviceCasings.kebab}.service';
+`;
+      } else throw err;
+    }
+    try {
+      content = insertBeforeAnchor(
+        content,
+        "module-provides",
+        `${serviceCasings.camel}Service: (c): ${serviceCasings.pascal}Service => make${serviceCasings.pascal}Service(c),`
+      );
+    } catch (err) {
+      if (err instanceof AnchorMissingError) {
+        snippet += `// Add to provides:
+${serviceCasings.camel}Service: (c): ${serviceCasings.pascal}Service => make${serviceCasings.pascal}Service(c),
+`;
+      } else throw err;
+    }
+    try {
+      content = insertBeforeAnchor(
+        content,
+        "module-registry",
+        `${serviceCasings.camel}Service: ${serviceCasings.pascal}Service;`
+      );
+    } catch (err) {
+      if (err instanceof AnchorMissingError) {
+        snippet += `// Add to ${moduleCasings.pascal}Registry:
+${serviceCasings.camel}Service: ${serviceCasings.pascal}Service;
+`;
+      } else throw err;
+    }
+    writeFileSync2(indexPath, content);
+    if (snippet) {
+      fallbacks.push(
+        yellow2(`Some anchors missing in ${indexPath}.
+Paste manually:
+`) + snippet
+      );
+    }
+  }
+  p2.outro(
+    `${green2("\u2713")} Created service ${cyan2(serviceCasings.camel + "Service")} in module ${cyan2(moduleCasings.kebab)}`
+  );
+  console.log(dim2("  File:"));
+  console.log(
+    dim2(`    src/modules/${moduleCasings.kebab}/${serviceCasings.kebab}.service.ts`)
+  );
+  if (fallbacks.length > 0) {
+    console.log("\n" + yellow2("  Some snippets need manual paste:\n"));
+    for (const f of fallbacks) {
+      console.log(f + "\n");
+    }
+  }
+}
+function writeServiceFile(dst, casings) {
+  const tmpl = `import type { RequestContainer } from '@katajs/core';
+
+export type ${casings.pascal}Service = {
+  ping(): Promise<{ ok: true; service: string }>;
+};
+
+export function make${casings.pascal}Service(_c: RequestContainer): ${casings.pascal}Service {
+  return {
+    async ping() {
+      return { ok: true as const, service: '${casings.kebab}' };
+    },
+  };
+}
+`;
+  writeFileSync2(dst, tmpl);
+}
+var __dirname = dirname3(fileURLToPath2(import.meta.url));
+
+// src/commands/add-route.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { join as join4 } from "path";
+import * as p3 from "@clack/prompts";
+import { cyan as cyan3, dim as dim3, green as green3, yellow as yellow3 } from "kolorist";
+var VALID_METHODS = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete", "options", "head"]);
+async function addRoute(opts) {
+  const project = findKatajsProject(opts.cwd);
+  const method = opts.method.toLowerCase();
+  if (!VALID_METHODS.has(method)) {
+    throw new Error(
+      `Invalid HTTP method: "${opts.method}". Supported: ${[...VALID_METHODS].join(", ")}.`
+    );
+  }
+  if (!opts.path.startsWith("/")) {
+    throw new Error(`Path must start with "/": got "${opts.path}".`);
+  }
+  const moduleCasings = normalizeName(opts.inModule);
+  const moduleDir = join4(project.srcDir, "modules", moduleCasings.kebab);
+  const routesPath = join4(moduleDir, `${moduleCasings.kebab}.routes.ts`);
+  if (!existsSync4(routesPath)) {
+    throw new Error(
+      `Routes file not found: ${routesPath}
+Is "${moduleCasings.kebab}" a routed module? Service-only modules don't have routes.`
+    );
+  }
+  const content = readFileSync4(routesPath, "utf8");
+  const snippet = buildRouteSnippet(method, opts.path);
+  let updated;
+  try {
+    updated = insertBeforeAnchor(content, "module-routes", snippet.split("\n"));
+  } catch (err) {
+    if (err instanceof AnchorMissingError) {
+      p3.outro(
+        yellow3(
+          `Anchor "// katajs:module-routes" missing in ${routesPath}.
+Paste this snippet into the chain manually:
+
+${snippet}`
+        )
+      );
+      return;
+    }
+    throw err;
+  }
+  if (updated === content) {
+    p3.outro(yellow3(`No change \u2014 ${method.toUpperCase()} ${opts.path} appears to already exist.`));
+    return;
+  }
+  writeFileSync3(routesPath, updated);
+  p3.outro(
+    `${green3("\u2713")} Added ${cyan3(method.toUpperCase() + " " + opts.path)} to module ${cyan3(moduleCasings.kebab)}`
+  );
+  console.log(dim3(`  Edited src/modules/${moduleCasings.kebab}/${moduleCasings.kebab}.routes.ts`));
+}
+function buildRouteSnippet(method, path) {
+  return [
+    `.${method}('${path}', async (c) => {`,
+    `  // TODO: implement ${method.toUpperCase()} ${path}`,
+    `  return c.json({});`,
+    `})`
+  ].join("\n");
+}
+
+// src/commands/add-queue.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
+import { join as join5 } from "path";
+import * as p4 from "@clack/prompts";
+import { cyan as cyan4, dim as dim4, green as green4, yellow as yellow4 } from "kolorist";
+async function addQueue(opts) {
+  const project = findKatajsProject(opts.cwd);
+  const moduleCasings = normalizeName(opts.inModule);
+  const queueCasings = normalizeName(opts.name);
+  const bindingName = opts.binding ?? deriveBindingName(queueCasings.kebab);
+  const dlqBinding = opts.dlq;
+  const moduleDir = join5(project.srcDir, "modules", moduleCasings.kebab);
+  if (!existsSync5(moduleDir)) {
+    throw new Error(
+      `Module "${moduleCasings.kebab}" not found at ${moduleDir}. Run \`katajs add module ${moduleCasings.kebab}\` first.`
+    );
+  }
+  const consumerPath = join5(moduleDir, `${queueCasings.kebab}.consumer.ts`);
+  if (existsSync5(consumerPath)) {
+    throw new Error(
+      `Consumer file already exists: ${consumerPath}
+Refusing to overwrite.`
+    );
+  }
+  writeConsumerFile({
+    dst: consumerPath,
+    queue: queueCasings,
+    binding: bindingName,
+    dlq: dlqBinding,
+    batch: opts.batch ?? false
+  });
+  const indexPath = join5(moduleDir, "index.ts");
+  const fallbacks = [];
+  if (!existsSync5(indexPath)) {
+    fallbacks.push(
+      yellow4(`Module index not found: ${indexPath}
+Wire up the consumer manually.`)
+    );
+  } else {
+    let content = readFileSync5(indexPath, "utf8");
+    let snippet = "";
+    try {
+      content = insertBeforeAnchor(
+        content,
+        "module-service-imports",
+        `import { ${queueCasings.camel}Consumer } from './${queueCasings.kebab}.consumer';`
+      );
+    } catch (err) {
+      if (err instanceof AnchorMissingError) {
+        snippet += `import { ${queueCasings.camel}Consumer } from './${queueCasings.kebab}.consumer';
+`;
+      } else throw err;
+    }
+    try {
+      content = insertBeforeAnchor(
+        content,
+        "module-consumer",
+        `consumer: ${queueCasings.camel}Consumer,`
+      );
+    } catch (err) {
+      if (err instanceof AnchorMissingError) {
+        snippet += `// Add to defineModule call:
+consumer: ${queueCasings.camel}Consumer,
+`;
+      } else throw err;
+    }
+    writeFileSync4(indexPath, content);
+    if (snippet) {
+      fallbacks.push(
+        yellow4(`Some anchors missing in ${indexPath}.
+Paste manually:
+`) + snippet
+      );
+    }
+  }
+  if (!opts.noProducer) {
+    const appPath = join5(project.srcDir, "app.ts");
+    if (existsSync5(appPath)) {
+      let appSrc = readFileSync5(appPath, "utf8");
+      const importLine = `import { ${queueCasings.pascal}EventSchema } from './modules/${moduleCasings.kebab}/${queueCasings.kebab}.consumer';`;
+      const queuesEntry = [
+        `${queueCasings.camel}: {`,
+        `  binding: '${bindingName}',`,
+        `  schema: ${queueCasings.pascal}EventSchema,`,
+        `},`
+      ];
+      let appFallback = "";
+      if (!appSrc.includes(importLine)) {
+        try {
+          appSrc = insertBeforeAnchor(appSrc, "module-imports", importLine);
+        } catch (err) {
+          if (err instanceof AnchorMissingError) {
+            appFallback += importLine + "\n";
+          } else throw err;
+        }
+      }
+      try {
+        appSrc = insertBeforeAnchor(appSrc, "queues", queuesEntry);
+      } catch (err) {
+        if (err instanceof AnchorMissingError) {
+          appFallback += `// Add to createApp's queues:
+${queueCasings.camel}: { binding: '${bindingName}', schema: ${queueCasings.pascal}EventSchema },
+`;
+        } else throw err;
+      }
+      writeFileSync4(appPath, appSrc);
+      if (appFallback) {
+        fallbacks.push(
+          yellow4(`Some anchors missing in ${appPath}.
+Paste manually:
+`) + appFallback
+        );
+      }
+    }
+    const typesPath = join5(project.srcDir, "types.d.ts");
+    if (existsSync5(typesPath)) {
+      let typesSrc = readFileSync5(typesPath, "utf8");
+      let typesFallback = "";
+      const typeImportLine = `import type { ${queueCasings.pascal}Event } from './modules/${moduleCasings.kebab}/${queueCasings.kebab}.consumer';`;
+      const typedQueueImport = `import type { TypedQueue } from '@katajs/core';`;
+      const registryEntry = `${queueCasings.camel}: TypedQueue<${queueCasings.pascal}Event>;`;
+      if (!typesSrc.includes(typedQueueImport)) {
+        typesSrc = typesSrc.replace(
+          /^import type \{ DrizzleClient \} from '@katajs\/drizzle';/m,
+          `${typedQueueImport}
+$&`
+        );
+      }
+      if (!typesSrc.includes(typeImportLine)) {
+        try {
+          typesSrc = insertBeforeAnchor(typesSrc, "registry-imports", typeImportLine);
+        } catch (err) {
+          if (err instanceof AnchorMissingError) {
+            typesFallback += typeImportLine + "\n";
+          } else throw err;
+        }
+      }
+      try {
+        typesSrc = insertBeforeAnchor(typesSrc, "queues-registry", registryEntry);
+      } catch (err) {
+        if (err instanceof AnchorMissingError) {
+          typesFallback += `// Add to QueuesRegistry interface:
+${registryEntry}
+`;
+        } else throw err;
+      }
+      writeFileSync4(typesPath, typesSrc);
+      if (typesFallback) {
+        fallbacks.push(
+          yellow4(`Some anchors missing in ${typesPath}.
+Paste manually:
+`) + typesFallback
+        );
+      }
+    }
+  }
+  p4.outro(
+    `${green4("\u2713")} Added queue consumer ${cyan4(queueCasings.camel + "Consumer")} to module ${cyan4(moduleCasings.kebab)}` + (opts.noProducer ? "" : `
+  Wired ${cyan4(`c.var.queues.${queueCasings.camel}.send(...)`)} producer`)
+  );
+  console.log(dim4("  File:"));
+  console.log(
+    dim4(`    src/modules/${moduleCasings.kebab}/${queueCasings.kebab}.consumer.ts`)
+  );
+  if (fallbacks.length > 0) {
+    console.log("\n" + yellow4("  Some snippets need manual paste:\n"));
+    for (const f of fallbacks) {
+      console.log(f + "\n");
+    }
+  }
+  console.log("\n" + cyan4("  Next: add the wrangler bindings"));
+  console.log(
+    dim4("  In wrangler.jsonc, add (or extend) the queues section:\n")
+  );
+  console.log(buildWranglerSnippet(queueCasings.kebab, bindingName, dlqBinding));
+  if (!opts.noProducer) {
+    console.log(
+      "\n" + dim4(
+        `  Producer wired automatically \u2014 call ${cyan4(`c.var.queues.${queueCasings.camel}.send(...)`)} from any service or route.`
+      )
+    );
+  }
+}
+function deriveBindingName(kebab) {
+  return kebab.replace(/-/g, "_").toUpperCase() + "_QUEUE";
+}
+function writeConsumerFile(args) {
+  const { queue, binding, dlq, batch } = args;
+  const optionalDlq = dlq ? `
+  dlq: '${dlq}',
+  maxRetries: 5,` : "";
+  const handlerBlock = batch ? `  async handleBatch(batch, c) {
+    // TODO: implement batch processing.
+    // The framework has already validated each message body against ${queue.pascal}EventSchema.
+    for (const message of batch.messages) {
+      const event = message.body;
+      void event;
+      void c;
+      message.ack();
+    }
+  },` : `  async handle(message, c) {
+    // TODO: implement ${queue.kebab} message processing.
+    const event = message.body;
+    void event;
+    void c;
+  },`;
+  const tmpl = `import { z } from 'zod';
+import { defineConsumer } from '@katajs/core';
+
+/**
+ * Message body schema for the ${queue.kebab} queue. Update this to match
+ * the actual messages your producers send.
+ */
+export const ${queue.pascal}EventSchema = z.object({
+  // TODO: define your message shape
+  id: z.string().uuid(),
+});
+export type ${queue.pascal}Event = z.infer<typeof ${queue.pascal}EventSchema>;
+
+export const ${queue.camel}Consumer = defineConsumer({
+  queue: '${binding}',
+  schema: ${queue.pascal}EventSchema,${optionalDlq}
+${handlerBlock}
+});
+`;
+  writeFileSync4(args.dst, tmpl);
+}
+function buildWranglerSnippet(queueName, binding, dlq) {
+  const producers = [`    { "binding": "${binding}", "queue": "${queueName}" }`];
+  const dlqProducer = dlq ? `    ,
+    { "binding": "${dlq}", "queue": "${queueName}-dlq" }` : "";
+  const consumerEntry = dlq ? `    {
+      "queue": "${queueName}",
+      "max_batch_size": 100,
+      "max_batch_timeout": 30,
+      "max_retries": 5,
+      "dead_letter_queue": "${queueName}-dlq"
+    }` : `    {
+      "queue": "${queueName}",
+      "max_batch_size": 100,
+      "max_batch_timeout": 30,
+      "max_retries": 3
+    }`;
+  return `  "queues": {
+    "producers": [
+${producers.join(",\n")}${dlqProducer}
+    ],
+    "consumers": [
+${consumerEntry}
+    ]
+  }`;
+}
+
+// src/index.ts
+var cli = cac("katajs");
+cli.command("add <kind> <name> [path]", "Add something to your katajs project").option("--in <module>", "Target module (for `add service`, `add route`, `add queue`)").option("--binding <BINDING>", "wrangler binding name (for `add queue`; defaults to <NAME>_QUEUE)").option("--dlq <DLQ_BINDING>", "wrangler binding name for the dead-letter queue (for `add queue`)").option("--batch", "Generate `handleBatch` instead of `handle` (for `add queue`)").option("--no-producer", "Skip the producer manifest entry (for consumer-only Workers, e.g. apps/worker)").example("  katajs add module comments").example("  katajs add service featured --in posts").example("  katajs add route post /comments --in posts").example("  katajs add queue orders --in orders").example("  katajs add queue orders --in orders --dlq ORDERS_DLQ --batch").example("  katajs add queue orders --in orders --no-producer  # consumer-only (apps/worker)").action(
+  async (kind, name, path, opts) => {
+    try {
+      switch (kind) {
+        case "module":
+        case "m":
+          p5.intro("katajs add module");
+          await addModule({ name });
+          return;
+        case "service":
+        case "s":
+          if (!opts.in)
+            throw new Error("Missing --in <module>. Example: katajs add service featured --in posts");
+          p5.intro("katajs add service");
+          await addService({ name, inModule: opts.in });
+          return;
+        case "route":
+        case "r": {
+          if (!path)
+            throw new Error("Missing path. Example: katajs add route post /comments --in posts");
+          if (!opts.in)
+            throw new Error("Missing --in <module>. Example: katajs add route post /comments --in posts");
+          p5.intro("katajs add route");
+          await addRoute({ method: name, path, inModule: opts.in });
+          return;
+        }
+        case "queue":
+        case "q":
+          if (!opts.in)
+            throw new Error("Missing --in <module>. Example: katajs add queue orders --in orders");
+          p5.intro("katajs add queue");
+          await addQueue({
+            name,
+            inModule: opts.in,
+            binding: opts.binding,
+            dlq: opts.dlq,
+            batch: opts.batch ?? false,
+            // cac maps `--no-producer` to producer=false
+            noProducer: opts.producer === false
+          });
+          return;
+        default:
+          console.error(red2(`Unknown target: '${kind}'.`));
+          console.error("Supported: module, service, route, queue");
+          process.exit(1);
+      }
+    } catch (err) {
+      p5.cancel(red2(err.message));
+      process.exit(1);
+    }
+  }
+);
+cli.help();
+cli.version("0.1.0");
+cli.parse();

package/dist/templates/module/errors.ts

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

package/dist/templates/module/index.ts

@@ -0,0 +1,24 @@
+import { defineModule } from '@katajs/core';
+import { make{{Pascal}}Service, type {{Pascal}}Service } from './{{kebab}}.service';
+// katajs:module-service-imports
+import { {{camel}}Routes } from './{{kebab}}.routes';
+
+export const {{camel}}Module = defineModule({
+  name: '{{kebab}}',
+  provides: {
+    {{camel}}Service: (c): {{Pascal}}Service => make{{Pascal}}Service(c),
+    // katajs:module-provides
+  },
+  requires: [] as const,
+  routes: {{camel}}Routes,
+  prefix: '/{{kebab}}',
+  // katajs:module-consumer
+});
+
+/** Services this module contributes to the container's `Registry`. */
+export type {{Pascal}}Registry = {
+  {{camel}}Service: {{Pascal}}Service;
+  // katajs:module-registry
+};
+
+export type { {{Pascal}}Service };

package/dist/templates/module/routes.ts

@@ -0,0 +1,11 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../../app';
+
+export const {{camel}}Routes = new Hono<AppEnv>()
+  .get('/', async (c) => {
+    const service = c.var.resolve('{{camel}}Service');
+    const result = await service.ping();
+    return c.json(result);
+  })
+  // katajs:module-routes
+  ;

package/dist/templates/module/schema.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+// Add Zod schemas for this module's request bodies, query params, and route
+// params. Example:
+//
+//   export const Create{{Pascal}}Schema = z.object({
+//     name: z.string().min(1),
+//   });
+//   export type Create{{Pascal}}Input = z.infer<typeof Create{{Pascal}}Schema>;
+
+export const {{Pascal}}IdParam = z.object({
+  id: z.string().uuid(),
+});
+export type {{Pascal}}IdParamInput = z.infer<typeof {{Pascal}}IdParam>;

package/dist/templates/module/service.ts

@@ -0,0 +1,13 @@
+import type { RequestContainer } from '@katajs/core';
+
+export type {{Pascal}}Service = {
+  ping(): Promise<{ ok: true; module: string }>;
+};
+
+export function make{{Pascal}}Service(_c: RequestContainer): {{Pascal}}Service {
+  return {
+    async ping() {
+      return { ok: true as const, module: '{{kebab}}' };
+    },
+  };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@katajs/cli",
+  "version": "0.1.0",
+  "description": "Project commands for katajs apps — `katajs add module/service/route`, codemods, and upgrades.",
+  "keywords": [
+    "katajs",
+    "cli",
+    "codemod",
+    "scaffold",
+    "hono",
+    "cloudflare",
+    "workers"
+  ],
+  "license": "MIT",
+  "author": "Yaseer A. Okino <yaseerokino@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ookino/katajs.git",
+    "directory": "packages/katajs-cli"
+  },
+  "homepage": "https://github.com/ookino/katajs/tree/main/packages/katajs-cli#readme",
+  "bugs": {
+    "url": "https://github.com/ookino/katajs/issues"
+  },
+  "type": "module",
+  "bin": {
+    "katajs": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.8.2",
+    "cac": "^6.7.14",
+    "kolorist": "^1.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}