@malyuga/aether-cli 0.1.1

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

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}

package/dist/templates/middleware/middleware.ts.eta

@@ -0,0 +1,6 @@
+import type { Middleware } from "./types";
+
+export const <%= it.exportName %>: Middleware = async (_req, _res, next) => {
+  // TODO: implement <%= it.name %> middleware
+  await next();
+};

package/dist/templates/resource/controller.ts.eta

@@ -0,0 +1,135 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Params } from "../app/router";
+import { JsonBodyError, readJson, sendError, sendJson, HTTP_STATUS } from "../app/http";
+import type { <%= it.entityPascal %>Service } from "./<%= it.resourceKebab %>.service";
+<% if (it.crud) { %>
+import { parseCreateInput, parseUpdateInput } from "./<%= it.resourceKebab %>.validate";
+import { parseListQuery } from "../app/list";
+<% } %>
+
+const REPOSITORY_NOT_CONFIGURED = "Repository not configured";
+
+<% if (it.crud) { %>
+async function parseJson(req: IncomingMessage): Promise<unknown> {
+  try {
+    return await readJson(req);
+  } catch (err) {
+    if (err instanceof JsonBodyError) {
+      throw err;
+    }
+    throw new JsonBodyError("Invalid JSON body");
+  }
+}
+
+export function create<%= it.entityPascal %>Controller(deps: {
+  service: <%= it.entityPascal %>Service | null;
+  repositoryConfigured: boolean;
+}) {
+  return {
+    async list(req: IncomingMessage, res: ServerResponse, _params: Params): Promise<void> {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      const parsed = parseListQuery(url.searchParams);
+      if (!parsed.ok) {
+        sendError(res, HTTP_STATUS.BAD_REQUEST, parsed.message);
+        return;
+      }
+      if (!deps.repositoryConfigured || !deps.service) {
+        sendError(res, HTTP_STATUS.NOT_IMPLEMENTED, REPOSITORY_NOT_CONFIGURED);
+        return;
+      }
+      sendJson(res, HTTP_STATUS.OK, deps.service.list(parsed.value));
+    },
+
+    async getById(_req: IncomingMessage, res: ServerResponse, params: Params): Promise<void> {
+      if (!deps.repositoryConfigured || !deps.service) {
+        sendError(res, HTTP_STATUS.NOT_IMPLEMENTED, REPOSITORY_NOT_CONFIGURED);
+        return;
+      }
+      const item = deps.service.getById(params.id!);
+      if (!item) {
+        sendError(res, HTTP_STATUS.NOT_FOUND, "Not found");
+        return;
+      }
+      sendJson(res, HTTP_STATUS.OK, item);
+    },
+
+    async create(req: IncomingMessage, res: ServerResponse, _params: Params): Promise<void> {
+      if (!deps.repositoryConfigured || !deps.service) {
+        sendError(res, HTTP_STATUS.NOT_IMPLEMENTED, REPOSITORY_NOT_CONFIGURED);
+        return;
+      }
+      let body: unknown;
+      try {
+        body = await parseJson(req);
+      } catch (err) {
+        if (err instanceof JsonBodyError) {
+          sendError(res, err.status, err.message);
+          return;
+        }
+        throw err;
+      }
+      const parsed = parseCreateInput(body);
+      if (!parsed.ok) {
+        sendError(res, HTTP_STATUS.BAD_REQUEST, parsed.message);
+        return;
+      }
+      const created = deps.service.create(parsed.value);
+      sendJson(res, HTTP_STATUS.CREATED, created);
+    },
+
+    async update(req: IncomingMessage, res: ServerResponse, params: Params): Promise<void> {
+      if (!deps.repositoryConfigured || !deps.service) {
+        sendError(res, HTTP_STATUS.NOT_IMPLEMENTED, REPOSITORY_NOT_CONFIGURED);
+        return;
+      }
+      let body: unknown;
+      try {
+        body = await parseJson(req);
+      } catch (err) {
+        if (err instanceof JsonBodyError) {
+          sendError(res, err.status, err.message);
+          return;
+        }
+        throw err;
+      }
+      const parsed = parseUpdateInput(body);
+      if (!parsed.ok) {
+        sendError(res, HTTP_STATUS.BAD_REQUEST, parsed.message);
+        return;
+      }
+      const updated = deps.service.update(params.id!, parsed.value);
+      if (!updated) {
+        sendError(res, HTTP_STATUS.NOT_FOUND, "Not found");
+        return;
+      }
+      sendJson(res, HTTP_STATUS.OK, updated);
+    },
+
+    async remove(_req: IncomingMessage, res: ServerResponse, params: Params): Promise<void> {
+      if (!deps.repositoryConfigured || !deps.service) {
+        sendError(res, HTTP_STATUS.NOT_IMPLEMENTED, REPOSITORY_NOT_CONFIGURED);
+        return;
+      }
+      const ok = deps.service.remove(params.id!);
+      if (!ok) {
+        sendError(res, HTTP_STATUS.NOT_FOUND, "Not found");
+        return;
+      }
+      res.statusCode = HTTP_STATUS.NO_CONTENT;
+      res.end();
+    },
+  };
+}
+
+export type <%= it.entityPascal %>Controller = ReturnType<typeof create<%= it.entityPascal %>Controller>;
+<% } else { %>
+export function create<%= it.entityPascal %>Controller(deps: { service: <%= it.entityPascal %>Service }) {
+  return {
+    async status(_req: IncomingMessage, res: ServerResponse, _params: Params): Promise<void> {
+      sendJson(res, HTTP_STATUS.OK, { resource: deps.service.status() });
+    },
+  };
+}
+
+export type <%= it.entityPascal %>Controller = ReturnType<typeof create<%= it.entityPascal %>Controller>;
+<% } %>

package/dist/templates/resource/module.test.ts.eta

@@ -0,0 +1,16 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { create<%= it.entityPascal %>Module } from "../src/<%= it.resourceKebab %>/<%= it.resourceKebab %>.module";
+import { createFake<%= it.entityPascal %>Repository } from "./<%= it.resourceKebab %>.repository.fake";
+
+describe("<%= it.resourceKebab %> module", () => {
+  it("lists a page when repository is wired", () => {
+    const repository = createFake<%= it.entityPascal %>Repository();
+    repository.create({} as never);
+    repository.create({} as never);
+    assert.equal(repository.findAll({ limit: 1, offset: 0 }).length, 1);
+    assert.equal(repository.findAll({ limit: 1, offset: 1 }).length, 1);
+    const mod = create<%= it.entityPascal %>Module({ repository });
+    assert.equal(mod.routes.length, 5);
+  });
+});

package/dist/templates/resource/module.ts.eta

@@ -0,0 +1,25 @@
+<% if (it.crud) { %>
+import type { <%= it.entityPascal %>Repository } from "./<%= it.resourceKebab %>.repository";
+import { create<%= it.entityPascal %>Controller } from "./<%= it.resourceKebab %>.controller";
+import { create<%= it.entityPascal %>Routes } from "./<%= it.resourceKebab %>.routes";
+import { create<%= it.entityPascal %>Service } from "./<%= it.resourceKebab %>.service";
+
+export function create<%= it.entityPascal %>Module(opts: { repository?: <%= it.entityPascal %>Repository }) {
+  const repositoryConfigured = opts.repository !== undefined;
+  const service = repositoryConfigured ? create<%= it.entityPascal %>Service(opts.repository!) : null;
+  const controller = create<%= it.entityPascal %>Controller({ service, repositoryConfigured });
+  const routes = create<%= it.entityPascal %>Routes(controller);
+  return { routes };
+}
+<% } else { %>
+import { create<%= it.entityPascal %>Controller } from "./<%= it.resourceKebab %>.controller";
+import { create<%= it.entityPascal %>Routes } from "./<%= it.resourceKebab %>.routes";
+import { create<%= it.entityPascal %>Service } from "./<%= it.resourceKebab %>.service";
+
+export function create<%= it.entityPascal %>Module() {
+  const service = create<%= it.entityPascal %>Service();
+  const controller = create<%= it.entityPascal %>Controller({ service });
+  const routes = create<%= it.entityPascal %>Routes(controller);
+  return { routes };
+}
+<% } %>

package/dist/templates/resource/repository.fake.ts.eta

@@ -0,0 +1,33 @@
+import type { <%= it.entityPascal %>, Create<%= it.entityPascal %>Input } from "../src/<%= it.resourceKebab %>/<%= it.resourceKebab %>.types";
+import type { <%= it.entityPascal %>Repository } from "../src/<%= it.resourceKebab %>/<%= it.resourceKebab %>.repository";
+import type { ListQuery } from "../src/app/list";
+
+export function createFake<%= it.entityPascal %>Repository(): <%= it.entityPascal %>Repository {
+  const store = new Map<string, <%= it.entityPascal %>>();
+  let seq = 1;
+
+  return {
+    findAll(query: ListQuery) {
+      return [...store.values()].slice(query.offset, query.offset + query.limit);
+    },
+    findById(id: string) {
+      return store.get(id);
+    },
+    create(input: Create<%= it.entityPascal %>Input) {
+      const id = String(seq++);
+      const item = { id, ...input } as <%= it.entityPascal %>;
+      store.set(id, item);
+      return item;
+    },
+    update(id, input) {
+      const existing = store.get(id);
+      if (!existing) return undefined;
+      const next = { ...existing, ...input };
+      store.set(id, next);
+      return next;
+    },
+    delete(id) {
+      return store.delete(id);
+    },
+  };
+}

package/dist/templates/resource/repository.ts.eta

@@ -0,0 +1,14 @@
+import type { <%= it.entityPascal %> } from "./<%= it.resourceKebab %>.types";
+<% if (it.crud) { %>
+import type { ListQuery } from "../app/list";
+<% } %>
+
+export interface <%= it.entityPascal %>Repository {
+<% if (it.crud) { %>
+  findAll(query: ListQuery): <%= it.entityPascal %>[];
+  findById(id: string): <%= it.entityPascal %> | undefined;
+  create(input: Omit<<%= it.entityPascal %>, "id">): <%= it.entityPascal %>;
+  update(id: string, input: Partial<Omit<<%= it.entityPascal %>, "id">>): <%= it.entityPascal %> | undefined;
+  delete(id: string): boolean;
+<% } %>
+}

package/dist/templates/resource/routes.ts.eta

@@ -0,0 +1,18 @@
+<% const basePath = it.routePrefix ? it.routePrefix + "/" + it.resourceKebab : "/" + it.resourceKebab; %>
+import { HTTP_METHOD } from "../app/http";
+import type { Route } from "../app/router";
+import type { <%= it.entityPascal %>Controller } from "./<%= it.resourceKebab %>.controller";
+
+export function create<%= it.entityPascal %>Routes(controller: <%= it.entityPascal %>Controller): Route[] {
+  return [
+<% if (it.crud) { %>
+    { method: HTTP_METHOD.GET, path: "<%= basePath %>", handler: controller.list },
+    { method: HTTP_METHOD.GET, path: "<%= basePath %>/:id", handler: controller.getById },
+    { method: HTTP_METHOD.POST, path: "<%= basePath %>", handler: controller.create },
+    { method: HTTP_METHOD.PATCH, path: "<%= basePath %>/:id", handler: controller.update },
+    { method: HTTP_METHOD.DELETE, path: "<%= basePath %>/:id", handler: controller.remove },
+<% } else { %>
+    { method: HTTP_METHOD.GET, path: "<%= basePath %>", handler: controller.status },
+<% } %>
+  ];
+}

package/dist/templates/resource/service.ts.eta

@@ -0,0 +1,45 @@
+<% if (it.crud) { %>
+import type { <%= it.entityPascal %>Repository } from "./<%= it.resourceKebab %>.repository";
+import type {
+  <%= it.entityPascal %>,
+  Create<%= it.entityPascal %>Input,
+  Update<%= it.entityPascal %>Input,
+} from "./<%= it.resourceKebab %>.types";
+import type { ListQuery } from "../app/list";
+
+export function create<%= it.entityPascal %>Service(repository: <%= it.entityPascal %>Repository) {
+  return {
+    list(query: ListQuery): <%= it.entityPascal %>[] {
+      return repository.findAll(query);
+    },
+
+    getById(id: string): <%= it.entityPascal %> | undefined {
+      return repository.findById(id);
+    },
+
+    create(input: Create<%= it.entityPascal %>Input): <%= it.entityPascal %> {
+      return repository.create(input);
+    },
+
+    update(id: string, input: Update<%= it.entityPascal %>Input): <%= it.entityPascal %> | undefined {
+      return repository.update(id, input);
+    },
+
+    remove(id: string): boolean {
+      return repository.delete(id);
+    },
+  };
+}
+
+export type <%= it.entityPascal %>Service = ReturnType<typeof create<%= it.entityPascal %>Service>;
+<% } else { %>
+export function create<%= it.entityPascal %>Service() {
+  return {
+    status(): string {
+      return "<%= it.resourceKebab %>";
+    },
+  };
+}
+
+export type <%= it.entityPascal %>Service = ReturnType<typeof create<%= it.entityPascal %>Service>;
+<% } %>

package/dist/templates/resource/types.ts.eta

@@ -0,0 +1,12 @@
+export type <%= it.entityPascal %> = {
+  id: string;
+<% if (it.crud) { it.fields.forEach(function(field) { %>
+  <%= field.name %>: <%= field.tsType %>;
+<% }); } %>
+};
+
+<% if (it.crud) { %>
+export type Create<%= it.entityPascal %>Input = Omit<<%= it.entityPascal %>, "id">;
+
+export type Update<%= it.entityPascal %>Input = Partial<Omit<<%= it.entityPascal %>, "id">>;
+<% } %>

package/dist/templates/resource/validate.ts.eta

@@ -0,0 +1,64 @@
+import type { Create<%= it.entityPascal %>Input, Update<%= it.entityPascal %>Input } from "./<%= it.resourceKebab %>.types";
+
+/** Replace this module with Zod/Ajv/etc. when you outgrow hand-rolled checks. */
+export type ValidateResult<T> = { ok: true; value: T } | { ok: false; message: string };
+
+export function parseCreateInput(body: unknown): ValidateResult<Create<%= it.entityPascal %>Input> {
+  if (typeof body !== "object" || body === null) {
+    return { ok: false, message: "Invalid request body" };
+  }
+  const b = body as Record<string, unknown>;
+<% if (it.fields.length === 0) { %>
+  for (const key of Object.keys(b)) {
+    return { ok: false, message: "Invalid request body" };
+  }
+  return { ok: true, value: {} as Create<%= it.entityPascal %>Input };
+<% } else { %>
+<% it.fields.filter(function(f) { return f.required; }).forEach(function(field) { %>
+  if (typeof b.<%= field.name %> !== "<%= field.tsType %>") {
+    return { ok: false, message: "Invalid request body" };
+  }
+<% if (field.tsType === "string") { %>
+  if ((b.<%= field.name %> as string).length === 0) {
+    return { ok: false, message: "Invalid request body" };
+  }
+<% } %>
+<% }); %>
+  return {
+    ok: true,
+    value: b as Create<%= it.entityPascal %>Input,
+  };
+<% } %>
+}
+
+export function parseUpdateInput(body: unknown): ValidateResult<Update<%= it.entityPascal %>Input> {
+  if (typeof body !== "object" || body === null) {
+    return { ok: false, message: "Invalid request body" };
+  }
+<% if (it.fields.length === 0) { %>
+  return { ok: false, message: "No update fields configured" };
+<% } else { %>
+  const b = body as Record<string, unknown>;
+  let hasField = false;
+<% it.fields.forEach(function(field) { %>
+  if (b.<%= field.name %> !== undefined) {
+    hasField = true;
+    if (typeof b.<%= field.name %> !== "<%= field.tsType %>") {
+      return { ok: false, message: "Invalid request body" };
+    }
+<% if (field.tsType === "string") { %>
+    if ((b.<%= field.name %> as string).length === 0) {
+      return { ok: false, message: "Invalid request body" };
+    }
+<% } %>
+  }
+<% }); %>
+  if (!hasField) {
+    return { ok: false, message: "Invalid request body" };
+  }
+  return {
+    ok: true,
+    value: b as Update<%= it.entityPascal %>Input,
+  };
+<% } %>
+}

package/llms.txt

@@ -0,0 +1,57 @@
+# Aether CLI
+
+> Source scaffolder for plain TypeScript HTTP backends on Node's built-in `http` module. Generated apps have zero runtime npm dependencies and do not require Aether at runtime.
+
+## When to use
+
+- Starting a new Node.js backend with TypeScript and `node:http`, not a runtime web framework
+- You want generated source you own: router, middleware, composition root, CRUD layers
+- Generating CRUD modules from an OpenAPI 3.0 specification
+- Production deploy should be `tsc` + `node` with no application `dependencies`
+
+## Install
+
+```bash
+npm i -g @malyuga/aether-cli
+```
+
+Requires Node.js 20+.
+
+## Quick start
+
+```bash
+mkdir my-api && cd my-api
+aether init
+npm install
+aether g resource users --crud
+npm run dev
+```
+
+After `init`, `GET /health` works. CRUD routes are registered in `src/app/composition.ts`, but the generated repository is an interface only. Until you pass a real implementation to `createUserModule({ repository: … })`, CRUD returns HTTP 501 with `{ "error": "Repository not configured" }`.
+
+## Commands
+
+- `aether init` — scaffold project in the current directory (`-f`, `--dry-run`, `--diff`, `--json`)
+- `aether g resource <name>` — resource module; `--crud` for full stack; `--tests` for fake repo + tests
+- `aether g middleware <name>` — middleware stub; `--global` registers in `src/app.ts`
+- `aether g openapi <spec>` — CRUD resources from OpenAPI 3.0 JSON/YAML
+- `aether check` — verify composition and config layout
+- `aether doctor` — Node version, project context, packaged templates
+- `aether upgrade` — read-only drift report; does not rewrite code
+- `aether help` — full terminal guide
+
+Alias: `g` for `generate`. Global flags: `--json`, `--diff` (with `--dry-run`).
+
+## Generated app notes
+
+- CommonJS; local imports without file extensions
+- Optional Bearer auth via `BEARER_TOKEN` in `.env` (wired by `init`; health stays public)
+- OpenAPI re-run without `--force` updates `*.types.ts` and `*.validate.ts` only
+
+## Documentation
+
+- [README](https://github.com/MalyugaSensei/aether-cli/blob/main/README.md): user-facing overview and examples
+- [npm package](https://www.npmjs.com/package/@malyuga/aether-cli): install and registry metadata
+- [Repository](https://github.com/MalyugaSensei/aether-cli): source and issues
+
+This file is for external coding agents. Repository `AGENTS.md` is for contributors developing the CLI itself, not for end-user scaffolding.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@malyuga/aether-cli",
+  "version": "0.1.1",
+  "description": "Scaffold plain TypeScript HTTP backends on node:http with zero runtime dependencies; OpenAPI-to-CRUD and explicit composition wiring",
+  "keywords": [
+    "aether",
+    "cli",
+    "scaffold",
+    "generator",
+    "backend-scaffold",
+    "typescript-backend",
+    "node-http",
+    "openapi",
+    "crud-generator",
+    "zero-runtime-dependencies",
+    "composition-root"
+  ],
+  "license": "MIT",
+  "author": "MalyugaSensei",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MalyugaSensei/aether-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MalyugaSensei/aether-cli/issues"
+  },
+  "homepage": "https://github.com/MalyugaSensei/aether-cli#readme",
+  "type": "module",
+  "bin": {
+    "aether": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-templates.mjs",
+    "pretest": "npm run build",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run tests/integration/e2e-install.test.ts",
+    "prepublishOnly": "npm test",
+    "release:patch": "npm version patch",
+    "release:minor": "npm version minor",
+    "release:major": "npm version major"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "eta": "^4.6.0",
+    "prettier": "^3.9.7",
+    "ts-morph": "^28.0.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.3",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
+  }
+}