@katajs/devtools 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,69 @@
+# @katajs/devtools
+
+> Live interactive devtools for [Kata](https://github.com/ookino/katajs) apps — module graph, drawer, routes table, queue producer/consumer view, Cmd+K palette. Hot-reloads as you edit.
+
+`@katajs/devtools` is a dev-dependency-only package. It runs locally, reads your project's `scripts/modules.ts`, and serves a React UI from a small Node HTTP server with a chokidar watcher pushing updates over Server-Sent Events. No telemetry, no remote anything.
+
+## Install
+
+```bash
+pnpm add -D @katajs/devtools
+```
+
+A Kata project (`pnpm create katajs my-app`) ships with `scripts/modules.ts` that exports a canonical `modules` tuple — that's what devtools imports. If your project predates the `scripts/modules.ts` convention, devtools also accepts a legacy `scripts/graph.ts` that exports `modules`.
+
+## Run
+
+```bash
+npx katajs-devtools
+#   katajs-devtools — interactive module graph
+#   ➜ Local: http://127.0.0.1:4242
+```
+
+The bin opens a browser to the UI. Edit anything under `src/modules/**` or `scripts/modules.ts` and the canvas hot-reloads.
+
+## CLI flags
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--port <port>` | `4242` | Auto-bumps if busy. |
+| `--host <host>` | `127.0.0.1` | Pass `0.0.0.0` to bind all interfaces. |
+| `--no-open` | — | Don't auto-launch the browser. |
+| `--modules-file <path>` | auto-detect | Override the location of the modules file. |
+
+## What you see
+
+- **Graph canvas** — React Flow with dagre auto-layout. Each module is a card showing its prefix, provides count, requires count, route count, and a `consumes <BINDING>` line for queue consumers.
+- **Module sidebar** — every module with at-a-glance counts; a Producers section appears below if `createApp({ queues })` is declared.
+- **Module drawer** (right side, on selection) — full provides chips, requires with clickable backlinks, owned routes, and a "Consumes" section listing queue + DLQ + the producer that feeds it.
+- **Producer drawer** — click a producer in the sidebar to see the typed `c.var.queues.<name>.send(body)` call and the consumer modules that read from the same binding.
+- **Routes view** — flat searchable table; method-coloured chips with a free-text + per-method filter.
+- **Cmd+K palette** — fuzzy-search across modules, producers, and routes; selecting jumps to the appropriate view.
+
+## How the data flows
+
+```
+scripts/modules.ts (your modules tuple)
+        │ tsx ESM register
+        ▼
+inspectModules() ──────► JSON over /api/graph.sse ──────► React UI
+        ▲                                                     │
+        │  chokidar re-fires on src/modules/** change         │  Cmd+K, click,
+        └─────────────────────────────────────────────────────┘  filter
+```
+
+The data contract is the [`Inspection`](https://www.npmjs.com/package/@katajs/core) shape from `@katajs/core`. Anything renderable in the static `pnpm graph` snapshot is navigable here, with cross-module backlinks and live updates on top.
+
+## Endpoints (advanced)
+
+While the bin is running:
+
+- `GET /` — the React UI bundle.
+- `GET /api/graph.json` — pretty-printed `Inspection` JSON, fresh on each request.
+- `GET /api/graph.sse` — Server-Sent Events stream emitting `event: graph` with compact JSON on every snapshot change.
+
+Useful if you want to feed the graph into something else (e.g. a CI artefact step).
+
+## License
+
+MIT © Yaseer A. Okino

package/dist/cli.js

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { exec } from "child_process";
+import { resolve as resolve3 } from "path";
+import { cac } from "cac";
+import { bold, cyan, dim, green, red, yellow } from "kolorist";
+
+// src/server.ts
+import { createServer } from "http";
+import { readFile } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { resolve as resolve2, join, normalize } from "path";
+import { fileURLToPath } from "url";
+import { watch as chokidarWatch } from "chokidar";
+
+// src/loader.ts
+import { existsSync } from "fs";
+import { pathToFileURL } from "url";
+import { resolve } from "path";
+import { register } from "tsx/esm/api";
+import { inspectModules } from "@katajs/core";
+var tsxRegistered = false;
+function ensureTsx() {
+  if (tsxRegistered) return;
+  register();
+  tsxRegistered = true;
+}
+function resolveModulesFile(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  if (options.modulesFile) {
+    const abs = resolve(cwd, options.modulesFile);
+    if (!existsSync(abs)) {
+      throw new Error(
+        `katajs-devtools: modules file not found at ${options.modulesFile} (resolved: ${abs})`
+      );
+    }
+    return abs;
+  }
+  const preferred = resolve(cwd, "scripts/modules.ts");
+  if (existsSync(preferred)) return preferred;
+  const legacy = resolve(cwd, "scripts/graph.ts");
+  if (existsSync(legacy)) return legacy;
+  throw new Error(
+    `katajs-devtools: no modules file found. Looked for:
+  - scripts/modules.ts (preferred)
+  - scripts/graph.ts (legacy)
+Either of these must export \`const modules = [...]\` for devtools to load.
+Run \`katajs upgrade\` to migrate, or pass --modules-file <path> manually.`
+  );
+}
+async function loadInspection(options = {}) {
+  ensureTsx();
+  const resolvedAbsolutePath = resolveModulesFile(options);
+  const url = `${pathToFileURL(resolvedAbsolutePath).href}?t=${Date.now()}`;
+  const mod = await import(url);
+  if (!Array.isArray(mod.modules)) {
+    throw new Error(
+      `katajs-devtools: ${resolvedAbsolutePath} does not export a \`modules\` array.
+Expected:
+  export const modules = [postsModule, /* ... */];`
+    );
+  }
+  const inspection = inspectModules(mod.modules, { producers: mod.producers });
+  return { inspection, resolvedPath: url, resolvedAbsolutePath };
+}
+
+// src/server.ts
+var here = fileURLToPath(new URL(".", import.meta.url));
+var uiStaticDir = resolve2(here, "ui");
+function mimeFor(path) {
+  if (path.endsWith(".html")) return "text/html; charset=utf-8";
+  if (path.endsWith(".js")) return "application/javascript; charset=utf-8";
+  if (path.endsWith(".css")) return "text/css; charset=utf-8";
+  if (path.endsWith(".json")) return "application/json; charset=utf-8";
+  if (path.endsWith(".svg")) return "image/svg+xml";
+  if (path.endsWith(".ico")) return "image/x-icon";
+  return "application/octet-stream";
+}
+function send(res, status, body, contentType) {
+  res.writeHead(status, {
+    "content-type": contentType,
+    "cache-control": "no-store"
+  });
+  res.end(body);
+}
+function payloadOf(insp) {
+  return {
+    modules: insp.modules,
+    edges: insp.edges,
+    routes: insp.routes,
+    producers: insp.producers
+  };
+}
+function jsonPretty(insp) {
+  return JSON.stringify(payloadOf(insp), null, 2);
+}
+function jsonCompact(insp) {
+  return JSON.stringify(payloadOf(insp));
+}
+async function startServer(options) {
+  let lastResult = null;
+  let lastError = null;
+  const sseClients = /* @__PURE__ */ new Set();
+  let nextSseId = 1;
+  async function refresh() {
+    try {
+      lastResult = await loadInspection({ cwd: options.cwd, modulesFile: options.modulesFile });
+      lastError = null;
+      const payload = jsonCompact(lastResult.inspection);
+      for (const c of sseClients) {
+        c.res.write(`event: graph
+data: ${payload}
+
+`);
+      }
+    } catch (err) {
+      lastResult = null;
+      lastError = err instanceof Error ? err : new Error(String(err));
+      const payload = JSON.stringify({ message: lastError.message });
+      for (const c of sseClients) {
+        c.res.write(`event: error
+data: ${payload}
+
+`);
+      }
+    }
+  }
+  await refresh();
+  const watchPaths = [];
+  if (lastResult) watchPaths.push(lastResult.resolvedAbsolutePath);
+  const srcModulesDir = resolve2(options.cwd, "src/modules");
+  if (existsSync2(srcModulesDir)) watchPaths.push(srcModulesDir);
+  let watcher = null;
+  if (watchPaths.length > 0) {
+    watcher = chokidarWatch(watchPaths, {
+      ignoreInitial: true,
+      ignored: (p) => p.includes("/node_modules/") || p.includes("/dist/")
+    });
+    let pending = null;
+    const debounced = () => {
+      if (pending) clearTimeout(pending);
+      pending = setTimeout(() => {
+        pending = null;
+        void refresh();
+      }, 50);
+    };
+    watcher.on("add", debounced);
+    watcher.on("change", debounced);
+    watcher.on("unlink", debounced);
+  }
+  const handler = async (req, res) => {
+    const url2 = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const pathname = url2.pathname;
+    if (pathname === "/api/graph.json") {
+      if (lastError) {
+        send(res, 500, JSON.stringify({ error: lastError.message }, null, 2), "application/json; charset=utf-8");
+        return;
+      }
+      if (!lastResult) {
+        send(res, 503, JSON.stringify({ error: "graph not loaded yet" }), "application/json; charset=utf-8");
+        return;
+      }
+      send(res, 200, jsonPretty(lastResult.inspection), "application/json; charset=utf-8");
+      return;
+    }
+    if (pathname === "/api/graph.sse") {
+      res.writeHead(200, {
+        "content-type": "text/event-stream; charset=utf-8",
+        "cache-control": "no-store",
+        connection: "keep-alive"
+      });
+      const id = nextSseId++;
+      const client = { res, id };
+      sseClients.add(client);
+      res.write(`: connected
+
+`);
+      if (lastResult) {
+        res.write(`event: graph
+data: ${jsonCompact(lastResult.inspection)}
+
+`);
+      } else if (lastError) {
+        res.write(`event: error
+data: ${JSON.stringify({ message: lastError.message })}
+
+`);
+      }
+      const keepalive = setInterval(() => res.write(`: ping
+
+`), 15e3);
+      req.on("close", () => {
+        clearInterval(keepalive);
+        sseClients.delete(client);
+      });
+      return;
+    }
+    if (pathname === "/" || pathname === "/index.html") {
+      const indexPath = join(uiStaticDir, "index.html");
+      if (existsSync2(indexPath)) {
+        const buf = await readFile(indexPath);
+        send(res, 200, buf, "text/html; charset=utf-8");
+        return;
+      }
+      send(
+        res,
+        404,
+        "UI bundle not found \u2014 did you run `pnpm --filter @katajs/devtools build`?",
+        "text/plain; charset=utf-8"
+      );
+      return;
+    }
+    const safe = normalize(pathname).replace(/^([./\\])+/, "");
+    const filePath = join(uiStaticDir, safe);
+    if (filePath.startsWith(uiStaticDir) && existsSync2(filePath)) {
+      const buf = await readFile(filePath);
+      send(res, 200, buf, mimeFor(filePath));
+      return;
+    }
+    send(res, 404, "not found", "text/plain; charset=utf-8");
+  };
+  const server = createServer((req, res) => {
+    handler(req, res).catch((err) => {
+      const msg = err instanceof Error ? err.stack ?? err.message : String(err);
+      send(res, 500, msg, "text/plain; charset=utf-8");
+    });
+  });
+  await new Promise((resolveStart, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, options.host, () => {
+      server.off("error", reject);
+      resolveStart();
+    });
+  });
+  const url = `http://${options.host === "0.0.0.0" ? "localhost" : options.host}:${options.port}`;
+  return {
+    url,
+    async close() {
+      for (const c of sseClients) c.res.end();
+      sseClients.clear();
+      if (watcher) await watcher.close();
+      await new Promise((r) => server.close(() => r()));
+    }
+  };
+}
+
+// src/cli.ts
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? `open "${url}"` : platform === "win32" ? `start "" "${url}"` : `xdg-open "${url}"`;
+  exec(cmd, (err) => {
+    if (err) {
+      process.stderr.write(dim(`(could not auto-open browser: ${err.message})
+`));
+    }
+  });
+}
+async function findFreePort(start, host) {
+  const { createServer: createServer2 } = await import("net");
+  for (let port = start; port < start + 20; port++) {
+    const free = await new Promise((res) => {
+      const probe = createServer2();
+      probe.once("error", () => {
+        probe.close();
+        res(false);
+      });
+      probe.once("listening", () => {
+        probe.close(() => res(true));
+      });
+      probe.listen(port, host);
+    });
+    if (free) return port;
+  }
+  throw new Error(`No free port found in range ${start}-${start + 19}.`);
+}
+async function run(options) {
+  const cwd = resolve3(options.cwd ?? process.cwd());
+  const host = options.host ?? "127.0.0.1";
+  const requestedPort = options.port ?? 4242;
+  const port = await findFreePort(requestedPort, host);
+  process.stdout.write(`
+  ${bold(cyan("katajs-devtools"))}  ${dim("\u2014 interactive module graph")}
+
+`);
+  process.stdout.write(`  ${dim("cwd:")}    ${cwd}
+`);
+  process.stdout.write(
+    `  ${dim("source:")} ${options.modulesFile ?? dim("(auto-detect: scripts/modules.ts \u2192 scripts/graph.ts)")}
+
+`
+  );
+  let server;
+  try {
+    server = await startServer({
+      cwd,
+      modulesFile: options.modulesFile,
+      port,
+      host
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`  ${red("\u2717")} failed to start: ${msg}
+
+`);
+    process.exit(1);
+  }
+  if (port !== requestedPort) {
+    process.stdout.write(
+      `  ${yellow("!")} port ${requestedPort} was busy, using ${port} instead
+`
+    );
+  }
+  process.stdout.write(`  ${green("\u279C")} ${bold("Local:")}   ${cyan(server.url)}
+`);
+  process.stdout.write(`  ${dim("Press Ctrl+C to stop.")}
+
+`);
+  if (options.open !== false) {
+    openBrowser(server.url);
+  }
+  const shutdown = async (signal) => {
+    process.stdout.write(`
+${dim(`received ${signal}, shutting down...`)}
+`);
+    await server.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}
+var cli = cac("katajs-devtools");
+cli.command("[cwd]", "Start the interactive devtools server").option("--port <port>", "Port to listen on", { default: 4242 }).option("--host <host>", "Host to bind", { default: "127.0.0.1" }).option("--no-open", "Do not auto-open the browser").option("--modules-file <path>", "Override the modules file location").action((cwdArg, opts) => {
+  void run({
+    cwd: cwdArg,
+    port: typeof opts.port === "number" ? opts.port : Number(opts.port),
+    host: typeof opts.host === "string" ? opts.host : void 0,
+    open: opts.open !== false,
+    modulesFile: typeof opts.modulesFile === "string" ? opts.modulesFile : void 0
+  });
+});
+cli.help();
+cli.version("0.1.0");
+cli.parse();