@malyuga/aether-cli 0.1.1

package/dist/templates/init/chisel.config.json.eta

@@ -0,0 +1,5 @@
+{
+  "version": <%= it.configVersion %>,
+  "srcDir": "<%= it.srcDir %>",
+  "appEntry": "<%= it.appEntry %>"
+}

package/dist/templates/init/env.eta

@@ -0,0 +1,8 @@
+# Local defaults. Add new keys here and in AppConfig in src/app/config.ts.
+PORT=3000
+HOST=0.0.0.0
+NODE_ENV=development
+SHUTDOWN_GRACE_MS=10000
+CORS_ORIGIN=
+BODY_LIMIT_BYTES=1048576
+BEARER_TOKEN=

package/dist/templates/init/env.example.eta

@@ -0,0 +1,8 @@
+# Local defaults. Add new keys here and in AppConfig in src/app/config.ts.
+PORT=3000
+HOST=0.0.0.0
+NODE_ENV=development
+SHUTDOWN_GRACE_MS=10000
+CORS_ORIGIN=
+BODY_LIMIT_BYTES=1048576
+BEARER_TOKEN=

package/dist/templates/init/gitignore.eta

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.log
+.env
+.DS_Store

package/dist/templates/init/package.json.eta

@@ -0,0 +1,14 @@
+{
+  "name": "<%= it.projectName %>",
+  "version": "0.1.0",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/main.js",
+    "dev": "tsx watch src/main.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.5",
+    "tsx": "^4.19.3",
+    "typescript": "^7.0.2"
+  }
+}

package/dist/templates/init/src-app-composition.ts.eta

@@ -0,0 +1,6 @@
+import type { Route } from "./router";
+import { healthRoutes } from "../health/health.routes";
+
+export function buildAppRoutes(): Route[] {
+  return [...healthRoutes];
+}

package/dist/templates/init/src-app-config.ts.eta

@@ -0,0 +1,105 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type AppConfig = {
+  port: number;
+  host: string;
+  nodeEnv: "development" | "production" | "test";
+  shutdownGraceMs: number;
+  corsOrigin: string;
+  bodyLimitBytes: number;
+  bearerToken: string;
+};
+
+const ALLOWED_NODE_ENV = new Set(["development", "production", "test"]);
+const DEFAULT_PORT = 3000;
+const DEFAULT_HOST = "0.0.0.0";
+const DEFAULT_NODE_ENV = "development";
+const DEFAULT_SHUTDOWN_GRACE_MS = 10000;
+const DEFAULT_BODY_LIMIT_BYTES = 1048576;
+const PORT_MIN = 1;
+const PORT_MAX = 65535;
+
+function stripQuotes(value: string): string {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/** Loads KEY=VALUE lines from `.env` in cwd; does not override existing process.env. */
+export function loadEnvFile(relativePath = ".env"): void {
+  const abs = join(process.cwd(), relativePath);
+  if (!existsSync(abs)) {
+    return;
+  }
+  const raw = readFileSync(abs, "utf8");
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    const value = stripQuotes(trimmed.slice(eq + 1).trim());
+    if (key.length === 0) {
+      continue;
+    }
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}
+
+export function loadConfig(): AppConfig {
+  loadEnvFile();
+
+  const portRaw = process.env.PORT ?? String(DEFAULT_PORT);
+  const port = Number(portRaw);
+  if (!Number.isInteger(port) || port < PORT_MIN || port > PORT_MAX) {
+    throw new Error(`Invalid PORT: ${portRaw}`);
+  }
+
+  const host = process.env.HOST ?? DEFAULT_HOST;
+  if (host.length === 0) {
+    throw new Error("HOST must not be empty");
+  }
+
+  const nodeEnv = process.env.NODE_ENV ?? DEFAULT_NODE_ENV;
+  if (!ALLOWED_NODE_ENV.has(nodeEnv)) {
+    throw new Error(`Invalid NODE_ENV: ${nodeEnv}`);
+  }
+
+  const graceRaw = process.env.SHUTDOWN_GRACE_MS ?? String(DEFAULT_SHUTDOWN_GRACE_MS);
+  const shutdownGraceMs = Number(graceRaw);
+  if (!Number.isFinite(shutdownGraceMs) || shutdownGraceMs < 0) {
+    throw new Error(`Invalid SHUTDOWN_GRACE_MS: ${graceRaw}`);
+  }
+
+  const corsOrigin = (process.env.CORS_ORIGIN ?? "").trim();
+  const bearerToken = process.env.BEARER_TOKEN ?? "";
+
+  const bodyLimitRaw = process.env.BODY_LIMIT_BYTES ?? String(DEFAULT_BODY_LIMIT_BYTES);
+  const bodyLimitBytes = Number(bodyLimitRaw);
+  if (!Number.isInteger(bodyLimitBytes) || bodyLimitBytes < 1) {
+    throw new Error(`Invalid BODY_LIMIT_BYTES: ${bodyLimitRaw}`);
+  }
+
+  return {
+    port,
+    host,
+    nodeEnv: nodeEnv as AppConfig["nodeEnv"],
+    shutdownGraceMs,
+    corsOrigin,
+    bodyLimitBytes,
+    bearerToken,
+  };
+}
+
+export const config = loadConfig();

package/dist/templates/init/src-app-http.ts.eta

@@ -0,0 +1,74 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { config } from "./config";
+
+export const HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  NOT_FOUND: 404,
+  PAYLOAD_TOO_LARGE: 413,
+  INTERNAL_SERVER_ERROR: 500,
+  NOT_IMPLEMENTED: 501,
+} as const;
+
+export const HTTP_METHOD = {
+  GET: "GET",
+  POST: "POST",
+  PUT: "PUT",
+  PATCH: "PATCH",
+  DELETE: "DELETE",
+  OPTIONS: "OPTIONS",
+} as const;
+
+export type HttpMethod = (typeof HTTP_METHOD)[keyof typeof HTTP_METHOD];
+
+export const HTTP_CONTENT_TYPE = {
+  JSON: "application/json",
+} as const;
+
+export async function readJson<T = unknown>(
+  req: IncomingMessage,
+  maxBytes = config.bodyLimitBytes,
+): Promise<T> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    size += buf.length;
+    if (size > maxBytes) {
+      throw new JsonBodyError("Request body too large", HTTP_STATUS.PAYLOAD_TOO_LARGE);
+    }
+    chunks.push(buf);
+  }
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) {
+    throw new JsonBodyError("Request body is empty");
+  }
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    throw new JsonBodyError("Invalid JSON body");
+  }
+}
+
+export class JsonBodyError extends Error {
+  readonly status: number;
+
+  constructor(message: string, status: number = HTTP_STATUS.BAD_REQUEST) {
+    super(message);
+    this.name = "JsonBodyError";
+    this.status = status;
+  }
+}
+
+export function sendJson(res: ServerResponse, status: number, data: unknown): void {
+  res.statusCode = status;
+  res.setHeader("Content-Type", HTTP_CONTENT_TYPE.JSON);
+  res.end(JSON.stringify(data));
+}
+
+export function sendError(res: ServerResponse, status: number, message: string): void {
+  sendJson(res, status, { error: message });
+}

package/dist/templates/init/src-app-list.ts.eta

@@ -0,0 +1,35 @@
+export type ListQuery = {
+  limit: number;
+  offset: number;
+};
+
+export const LIST_DEFAULT_LIMIT = 50;
+export const LIST_MAX_LIMIT = 100;
+
+export type ListQueryResult =
+  | { ok: true; value: ListQuery }
+  | { ok: false; message: string };
+
+const INVALID_LIST_QUERY = "Invalid list query";
+
+function parseCount(raw: string | null, fallback: number): number | null {
+  if (raw === null || raw.length === 0) {
+    return fallback;
+  }
+  if (!/^\d+$/.test(raw)) {
+    return null;
+  }
+  return Number(raw);
+}
+
+export function parseListQuery(search: URLSearchParams): ListQueryResult {
+  const limit = parseCount(search.get("limit"), LIST_DEFAULT_LIMIT);
+  const offset = parseCount(search.get("offset"), 0);
+  if (limit === null || offset === null) {
+    return { ok: false, message: INVALID_LIST_QUERY };
+  }
+  if (limit < 1 || limit > LIST_MAX_LIMIT) {
+    return { ok: false, message: INVALID_LIST_QUERY };
+  }
+  return { ok: true, value: { limit, offset } };
+}

package/dist/templates/init/src-app-logger.ts.eta

@@ -0,0 +1,35 @@
+import { config } from "./config";
+
+type LogMeta = Record<string, unknown>;
+
+function formatMessage(level: string, message: string, meta?: LogMeta): string {
+  if (!meta || Object.keys(meta).length === 0) {
+    return `[${level}] ${message}`;
+  }
+  return `[${level}] ${message} ${JSON.stringify(meta)}`;
+}
+
+export const logger = {
+  info(message: string, meta?: LogMeta): void {
+    console.log(formatMessage("INFO", message, meta));
+  },
+
+  error(message: string, err?: unknown): void {
+    if (err instanceof Error) {
+      console.error(formatMessage("ERROR", message, { name: err.name, message: err.message }));
+      return;
+    }
+    if (err !== undefined) {
+      console.error(formatMessage("ERROR", message, { err }));
+      return;
+    }
+    console.error(formatMessage("ERROR", message));
+  },
+
+  debug(message: string, meta?: LogMeta): void {
+    if (config.nodeEnv === "production") {
+      return;
+    }
+    console.debug(formatMessage("DEBUG", message, meta));
+  },
+};

package/dist/templates/init/src-app-middleware-bearer-auth.ts.eta

@@ -0,0 +1,60 @@
+import { timingSafeEqual } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { config } from "../config";
+import { HTTP_METHOD, HTTP_STATUS, sendError } from "../http";
+import type { Middleware } from "./types";
+
+function tokensEqual(left: string, right: string): boolean {
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  if (a.length !== b.length) {
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}
+
+function readBearer(header: string | string[] | undefined): string | undefined {
+  const value = Array.isArray(header) ? header[0] : header;
+  if (!value) {
+    return undefined;
+  }
+  const match = /^Bearer\s+(\S+)/i.exec(value);
+  return match?.[1];
+}
+
+function requestPath(req: IncomingMessage): string {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const pathname = url.pathname;
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    return pathname.slice(0, -1);
+  }
+  return pathname || "/";
+}
+
+export const bearerAuth: Middleware = async (
+  req: IncomingMessage,
+  res: ServerResponse,
+  next,
+) => {
+  if (config.bearerToken.length === 0) {
+    await next();
+    return;
+  }
+
+  const method = (req.method ?? HTTP_METHOD.GET).toUpperCase();
+  if (
+    method === HTTP_METHOD.OPTIONS ||
+    (method === HTTP_METHOD.GET && requestPath(req) === "/health")
+  ) {
+    await next();
+    return;
+  }
+
+  const token = readBearer(req.headers.authorization);
+  if (!token || !tokensEqual(token, config.bearerToken)) {
+    sendError(res, HTTP_STATUS.UNAUTHORIZED, "Unauthorized");
+    return;
+  }
+
+  await next();
+};

package/dist/templates/init/src-app-middleware-body-limit.ts.eta

@@ -0,0 +1,37 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { config } from "../config";
+import { HTTP_METHOD, HTTP_STATUS, sendError, type HttpMethod } from "../http";
+import type { Middleware } from "./types";
+
+const BODY_METHODS = new Set<HttpMethod>([
+  HTTP_METHOD.POST,
+  HTTP_METHOD.PUT,
+  HTTP_METHOD.PATCH,
+]);
+
+export const bodyLimit: Middleware = async (
+  req: IncomingMessage,
+  res: ServerResponse,
+  next,
+) => {
+  const method = (req.method ?? HTTP_METHOD.GET).toUpperCase() as HttpMethod;
+  if (!BODY_METHODS.has(method)) {
+    await next();
+    return;
+  }
+
+  const raw = req.headers["content-length"];
+  if (raw !== undefined) {
+    const length = Number(raw);
+    if (!Number.isInteger(length) || length < 0) {
+      sendError(res, HTTP_STATUS.BAD_REQUEST, "Invalid Content-Length");
+      return;
+    }
+    if (length > config.bodyLimitBytes) {
+      sendError(res, HTTP_STATUS.PAYLOAD_TOO_LARGE, "Request body too large");
+      return;
+    }
+  }
+
+  await next();
+};

package/dist/templates/init/src-app-middleware-cors.ts.eta

@@ -0,0 +1,53 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { config } from "../config";
+import { HTTP_METHOD, HTTP_STATUS } from "../http";
+import type { Middleware } from "./types";
+
+const ALLOW_METHODS = [
+  HTTP_METHOD.GET,
+  HTTP_METHOD.POST,
+  HTTP_METHOD.PATCH,
+  HTTP_METHOD.PUT,
+  HTTP_METHOD.DELETE,
+  HTTP_METHOD.OPTIONS,
+].join(", ");
+const ALLOW_HEADERS = "Content-Type, Authorization";
+
+function allowedOrigin(requestOrigin: string | undefined): string | undefined {
+  const configured = config.corsOrigin;
+  if (configured.length === 0) {
+    return undefined;
+  }
+  if (configured === "*") {
+    return "*";
+  }
+  if (!requestOrigin) {
+    return undefined;
+  }
+  const allowed = configured.split(",").map((part) => part.trim()).filter(Boolean);
+  return allowed.includes(requestOrigin) ? requestOrigin : undefined;
+}
+
+export const cors: Middleware = async (req: IncomingMessage, res: ServerResponse, next) => {
+  const allow = allowedOrigin(req.headers.origin);
+  if (allow) {
+    res.setHeader("Access-Control-Allow-Origin", allow);
+    res.setHeader("Access-Control-Allow-Methods", ALLOW_METHODS);
+    res.setHeader("Access-Control-Allow-Headers", ALLOW_HEADERS);
+    if (allow !== "*") {
+      res.setHeader("Vary", "Origin");
+    }
+  }
+
+  if ((req.method ?? HTTP_METHOD.GET).toUpperCase() === HTTP_METHOD.OPTIONS) {
+    if (config.corsOrigin.length === 0) {
+      await next();
+      return;
+    }
+    res.statusCode = HTTP_STATUS.NO_CONTENT;
+    res.end();
+    return;
+  }
+
+  await next();
+};

package/dist/templates/init/src-app-middleware-error-handler.ts.eta

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { logger } from "../logger";
+import { sendError, HTTP_STATUS } from "../http";
+
+export function handleRequestError(
+  _req: IncomingMessage,
+  res: ServerResponse,
+  err: unknown,
+): void {
+  logger.error("Request failed", err);
+  if (res.headersSent) {
+    return;
+  }
+  sendError(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, "Internal Server Error");
+}

package/dist/templates/init/src-app-middleware-request-logger.ts.eta

@@ -0,0 +1,8 @@
+import type { Middleware } from "./types";
+import { HTTP_METHOD } from "../http";
+import { logger } from "../logger";
+
+export const requestLogger: Middleware = async (req, _res, next) => {
+  logger.info(`${req.method ?? HTTP_METHOD.GET} ${req.url ?? "/"}`);
+  await next();
+};

package/dist/templates/init/src-app-middleware-types.ts.eta

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export type Middleware = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  next: () => Promise<void>,
+) => void | Promise<void>;

package/dist/templates/init/src-app-router.ts.eta

@@ -0,0 +1,72 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { sendError, HTTP_METHOD, HTTP_STATUS, type HttpMethod } from "./http";
+
+export type Params = Record<string, string>;
+
+export type Handler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  params: Params,
+) => void | Promise<void>;
+
+export type Route = {
+  method: HttpMethod;
+  path: string;
+  handler: Handler;
+};
+
+type CompiledRoute = {
+  method: HttpMethod;
+  regex: RegExp;
+  keys: string[];
+  handler: Handler;
+};
+
+function normalizePath(pathname: string): string {
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    return pathname.slice(0, -1);
+  }
+  return pathname || "/";
+}
+
+function compilePath(path: string): { regex: RegExp; keys: string[] } {
+  const keys: string[] = [];
+  const segments = path.split("/").filter(Boolean);
+  const parts = segments.map((seg) => {
+    if (seg.startsWith(":")) {
+      keys.push(seg.slice(1));
+      return "([^/]+)";
+    }
+    return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  });
+  const pattern = "^/" + parts.join("/") + "$";
+  return { regex: new RegExp(pattern), keys };
+}
+
+export function createRouter(routes: Route[]): Handler {
+  const compiled: CompiledRoute[] = routes.map((r) => {
+    const { regex, keys } = compilePath(r.path);
+    return { method: r.method, regex, keys, handler: r.handler };
+  });
+
+  return async (req, res, _params) => {
+    const method = (req.method ?? HTTP_METHOD.GET).toUpperCase() as HttpMethod;
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const pathname = normalizePath(url.pathname);
+
+    for (const route of compiled) {
+      if (route.method !== method) continue;
+      const match = pathname.match(route.regex);
+      if (!match) continue;
+
+      const params: Params = {};
+      route.keys.forEach((key, i) => {
+        params[key] = decodeURIComponent(match[i + 1] ?? "");
+      });
+      await route.handler(req, res, params);
+      return;
+    }
+
+    sendError(res, HTTP_STATUS.NOT_FOUND, "Not Found");
+  };
+}

package/dist/templates/init/src-app-server.ts.eta

@@ -0,0 +1,16 @@
+import { createServer as createHttpServer, type Server } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { handleRequestError } from "./middleware/error-handler";
+
+export type RequestListener = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => void | Promise<void>;
+
+export function createServer(listener: RequestListener): Server {
+  return createHttpServer((req, res) => {
+    void Promise.resolve(listener(req, res)).catch((err: unknown) => {
+      handleRequestError(req, res, err);
+    });
+  });
+}

package/dist/templates/init/src-app.ts.eta

@@ -0,0 +1,36 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { createRouter, type Route } from "./app/router";
+import type { Middleware } from "./app/middleware/types";
+import { buildAppRoutes } from "./app/composition";
+import { handleRequestError } from "./app/middleware/error-handler";
+import { requestLogger } from "./app/middleware/request-logger";
+import { cors } from "./app/middleware/cors";
+import { bodyLimit } from "./app/middleware/body-limit";
+import { bearerAuth } from "./app/middleware/bearer-auth";
+
+const middleware: Middleware[] = [cors, bodyLimit, requestLogger, bearerAuth];
+const routes: Route[] = buildAppRoutes();
+
+export function createApp(): (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => void | Promise<void> {
+  const router = createRouter(routes);
+
+  return async (req, res) => {
+    try {
+      let index = 0;
+      const run = async (): Promise<void> => {
+        if (index >= middleware.length) {
+          await router(req, res, {});
+          return;
+        }
+        const mw = middleware[index++]!;
+        await mw(req, res, run);
+      };
+      await run();
+    } catch (err) {
+      handleRequestError(req, res, err);
+    }
+  };
+}

package/dist/templates/init/src-health-health.routes.ts.eta

@@ -0,0 +1,12 @@
+import type { Route } from "../app/router";
+import { HTTP_METHOD, sendJson, HTTP_STATUS } from "../app/http";
+
+export const healthRoutes: Route[] = [
+  {
+    method: HTTP_METHOD.GET,
+    path: "/health",
+    handler: (_req, res) => {
+      sendJson(res, HTTP_STATUS.OK, { status: "ok" });
+    },
+  },
+];

package/dist/templates/init/src-main.ts.eta

@@ -0,0 +1,37 @@
+import { createServer } from "./app/server";
+import { createApp } from "./app";
+import { config } from "./app/config";
+import { logger } from "./app/logger";
+
+const listener = createApp();
+const server = createServer(listener);
+
+server.listen(config.port, config.host, () => {
+  logger.info(`Server listening on http://${config.host}:${config.port}`);
+});
+
+let shuttingDown = false;
+
+function shutdown(signal: string): void {
+  if (shuttingDown) {
+    return;
+  }
+  shuttingDown = true;
+  logger.info(`Received ${signal}, shutting down...`);
+
+  const forceTimer = setTimeout(() => {
+    server.closeAllConnections();
+  }, config.shutdownGraceMs);
+  forceTimer.unref();
+
+  server.close((err) => {
+    clearTimeout(forceTimer);
+    if (err) {
+      logger.error("Shutdown error", err);
+      process.exitCode = 1;
+    }
+  });
+}
+
+process.once("SIGINT", () => shutdown("SIGINT"));
+process.once("SIGTERM", () => shutdown("SIGTERM"));